Skip to content

Example plugins

Four published plugins, all public, all installable in Kino, and all usable as a template. Start from Internet Archive for the simplest possible template; start from Tu servidor, the complete API demo, when your source is a server the person owns, or when you want to see every feature up to apiVersion 7 working end to end; start from Internet Archive Audio for music and podcasts (apiVersion 8, Kino 0.9.54).

  • Tu servidor · kinotvapp/kino-plugin-own-server


    The complete API demo. A media server at home (Jellyfin, Emby, a NAS…): the person types its address, user and password. Version 1.5.0, apiVersion 7: "hosts": [], every setting type and the full settings form, a session kept with kino.storage, kino.rank, seasons, download, copies, request signing, channels in every shape, a section and Categorías tiles, migrate, meta, subtitles, tracking and segments, plus a reference server (server.mjs) to run it against with nothing of your own.

    Use as template View on GitHub

  • Internet Archive · kinotvapp/kino-plugin-archive


    Public-domain films and classic TV from archive.org. The simplest template to start from: one manifest, one JavaScript file, no build step, all five capabilities plus download, and one list setting for the person's own archive.org addresses (apiVersion 4), with the sdk/ kit, GUIDE.md, contract.json and kino.d.ts.

    Use as template View on GitHub

  • Internet Archive Audio · kinotvapp/kino-plugin-archive-audio


    The reference audio plugin. Free music, live concerts, audiobooks and old-time radio from archive.org, as music and podcast items: apiVersion 8, Kino 0.9.54 or newer. episodes answers for every album, audiobook and show (even a single track), resolve offers each audio format as a labelled lazy copy, plus download, a section of its own and Categorías tiles. See Music and podcasts.

    Use as template View on GitHub

  • Vault demo · kinotvapp/kino-plugin-vault-demo


    The kino.vault.get() example. The plugin's secret (an API base, keys, a token) lives in the Kino vault, not in the code: one call, await kino.vault.get(), and Kino resolves the secret only for THIS plugin and only for a person in the Kino group. apiVersion 28 (Kino 0.9.90), capabilities screen + identity + vault, a hand‑written, heavily commented plugin.js that handles every state (not_member, not_found…).

    Use as template View on GitHub

To try one in Kino, open Ajustes > Plugins and type kinotvapp/kino-plugin-archive, kinotvapp/kino-plugin-own-server or kinotvapp/kino-plugin-archive-audio.

Use the template, don't fork. "Use as template" creates a fresh repository of your own with the same files. A fork would work as a plugin too, but Kino's community search leaves forks out (Get found). Then change id, name, homepage, hosts and capabilities in kino-plugin.json, rewrite plugin.js, and keep sdk/.

Plugins that use each other (apiVersion 20, Kino 0.9.81): TMDB and Cine Trivia

Cine Trivia (kinotvapp/kino-plugin-cine-trivia) is the reference consumer of the plugin protocol: a five-question movie game (a screen plugin, phone and TV) that takes every movie from the movies door of TMDB, the reference provider (TMDB 1.3.0 and later, door in enhancements["20"]). It shows the whole pattern: consumes + recommends, an install screen with go.installPlugin until TMDB is installed, kino.plugins.call with every error code handled, and a live trending stream. Both need Kino 0.9.81 or newer for the door.

A real-world example: a plugin that uses the hidden browser

Maratón (signed, apiVersion 6, "browser": "pages") is a real-world plugin, by someone else, that finds its video with kino.browser.capture and offers each episode's other servers and languages as labelled lazy copies. It is an example of those two features only (Kino just lists community plugins: each author is responsible for theirs); "Tu servidor" stays the complete reference plugin.

Sync providers: Sync-Gram, Sync Servidor and Sync-Gram Cuenta

The references for a sync provider (apiVersion 12, Kino 0.9.74) are three public repositories: Sync-Gram (kinotvapp/kino-plugin-sync-gram, a Telegram bot of the person's own; unofficial, not affiliated with Telegram; recommended in Kino) and Sync Servidor (kinotvapp/kino-plugin-sync-server, a single-file Node server the person runs; not listed in Kino, installed by pasting its repository address) and Sync-Gram Cuenta (kinotvapp/kino-plugin-sync-gram-account, the person's own Telegram account over a WebSocket, apiVersion 13; unofficial; not listed in Kino, installed by pasting kinotvapp/kino-plugin-sync-gram-account). Each has a guide in English and Spanish and offline tests. See The three example providers.

Kino Sync (experimental): sync through your own Google Drive

Kino Sync (kinotvapp/kino-plugin-sync-gdrive) is a sync provider that keeps the encrypted copy in the person's own Google Drive: no server of yours and no tokens to paste. The person taps Connect with Google, types a code at google.com/device (the same step TV apps use) and that is it. It is an experiment: not part of Kino, not recommended, and unofficial (not affiliated with Google). It draws a screen (settingsIn: "screen") with the steps, a banner with «Try again», the state of the copy in Drive and an accordion of questions; the copy lives in a «Kino Sync» folder as a single file, kino-sync.bin, with the drive.file permission (the plugin only sees what it created). The Google client is built in as a sealed secret, and since Drive cannot write «only if the version is X», the plugin checks, writes and checks again to detect a conflict. It ships offline Node tests with an imitation of Google.

Screens (apiVersion 14, with Kino 0.9.74): three examples

apiVersion 13 (Kino 0.9.74): a byte-stream example

No published example plugin uses apiVersion 13 yet. The guide has a complete socket + byteSource plugin, a video library behind a WebSocket, with the Node test that checks every range it serves: A complete example. The catalog, image and QR pages each carry a complete example too.

The reference plugin

For the basics -- search, home, browse, episodes and resolve over a public site, with no settings or session -- the reference is kino-plugin.json and plugin.js in kinotvapp/kino-plugin-archive, the Internet Archive plugin, with all five capabilities. It reads about like this:

  1. It declares archive.org and *.archive.org: a download URL on archive.org redirects to a storage node such as dn720705.ca.archive.org, and the wildcard does not cover the bare domain.
  2. getJson does the await first and throws afterwards (the rule of the rejection trap).
  3. search cleans what the person typed: archive.org answers 200 with an error body when the query has a stray /, -, & or ' or a dangling AND/OR/NOT, so it keeps letters, digits and apostrophes inside words, drops the operator words, and asks both collections (films and classic TV) whatever type says, using it only to decide which group comes first; an item that is in both is listed once.
  4. home builds three rows (films, classic TV, classic animation) and wraps each row in its own try/catch, so one failing row does not lose the others; it reports it with kino.log. Each row carries its own id as ref, and browse(ref, cursor) pages through the same query 50 at a time with the page number as the cursor ("2", "3", …), throwing kino.error("not_found") for a row it does not know.
  5. episodes reads the item's file list, keeps the video originals in natural order (a small natural() comparator, because localeCompare cannot be trusted), numbers them from S01E02 in the file name or 1, 2, 3, and uses "<item>|<file name>" as each episode's ref.
  6. resolve picks the best playable file (an mp4 derived from the original, or the mp4/webm itself), turns sibling .vtt/.srt files into subtitles, and sets durationMs.
  7. Every URL it builds is https on a declared host; posters use https://archive.org/services/img/<id> and are not host-checked.

README.md in that repository says what it does not do (a collection is exposed as a single movie, episodes numbered 0 are dropped), so do not copy those as intended behavior.

For everything else, up to apiVersion 7 (Kino 0.9.51) -- settings, a session, downloads, live items, channels, the apiVersion 6 set, tracking and segments -- the reference is kinotvapp/kino-plugin-own-server ("Tu servidor" 1.5.0): its kino-plugin.json and its plugin.js use nearly everything that exists, and its README.md maps every feature to the title of its test server that exercises it:

What it shows Where in the code Guide
"hosts": [], the server the person types and its other addresses (a list of url fields) kino-plugin.json; base(), addresses(), reach() The person's own servers
Every setting type: url, text, password, toggle, select, list, section (a 300-character hint), status, action kino-plugin.json: settings The settings form
Status lines, buttons (confirm, clearSettings) and a check before saving settingsStatus(), action(), validateSettings() The settings form
A login and a token kept in kino.storage, retried once on a 401; kino.sleep on a short Retry-After token(), api() kino.storage
Typed errors (kino.error) and your own sentence (userMessage) api(), resolveCopy() Errors people understand
A cache with ttlMs the person picks, and the last copy when the server is down; telemetry + kino.log.report home(), reach() kino.storage, Telemetry
Title search over a backend that matches any word; a Page with next; scopedSearch search(), kino.rank.* kino.rank, Searching inside "Ver más"
Cursor paging, rows with genre browse(), refFilter(), ROWS Paging
Seasons as separate titles episodes() Seasons
ids.tmdb + ids.imdb, item fields, adult: true entries item(), categories() ids.tmdb, 18+ content
A section with tabs and a hero, Categorías tiles, theme section(), categories(); kino-plugin.json Section, categories and colors
Downloads (download) kino-plugin.json; resolve() returns a progressive mp4 Downloads
audioTracks, subtitles, durationMs and skip on the Stream resolve() The Stream rules
Labelled and lazy copies, the same file at the other addresses withCopies(), resolveCopy(), withAddresses() Labelled and lazy copies
Signing every request (signing, signContext, sign, alternateHosts, resolve(ref, { retry })) signedStream(), sign(), resolve() Signing every request
live items (apiVersion 2) item(), resolve() Live channels (apiVersion 2)
channels: a ref, an inline stream, an M3U list with an XMLTV guide, a resolve: true list, liveSearch, paging liveCategories(), channel(), liveChannels(), liveSearch(), resolveListEntry() Channels in the En vivo tab, Three recipes
A User-Agent the channels insist on: headers on a Stream, streamHeaders on a playlist agentHeaders() Channels in the En vivo tab
A guide for its own channels guide() The channel functions
Moving saved titles from the server's older ids migrate(), movedTable() Moving saved titles
meta with logo, ratings and cast (Kino 0.9.51) meta() Describing other titles
subtitles with the file hint (Kino 0.9.51) subtitles() Subtitles for any title
tracking (apiVersion 7): idempotency by event.id, { skipped: true } track() Telling a tracker
segments (apiVersion 7) segments() Where the intro and credits are

Its core, line by line, is in the cookbook: The person's own server.

Install it and see it work

kinotvapp/kino-plugin-own-server bundles a reference server with no dependencies (node server.mjs [--port 8096] [--user ana] [--password s3cr3t] [--live-agent VLC]) whose catalog exercises one feature per title, so you can install the plugin in Kino and watch every row of the table above work, with no real server of your own.

A few powers are deliberately not in it, because a server at home never needs them: Widevine DRM (recipe), a declared host over plain http (recipe), streams on any server (recipe), sealed secrets (kino.secret), the author's signature (Signed plugins), the hidden browser and kino.html.select (Hidden browser), and key pairs (Key pairs).

Example plugin stores

To publish your own store (apiVersion 15, with Kino 0.9.77) there are two complete, copyable plugins: a local store whose list is a static JSON file and a live store with its own API. Both pass the kit and ship tests that run without a network: Example stores. The store that ships in the app, Kino Plugins, is another real example (Plugin stores).