Skip to content

Writing a Kino plugin

A Kino plugin is a video source that anyone can publish as a small GitHub repository: one JSON manifest and one JavaScript file. A person types owner/repo in Kino, sees which sites the plugin will talk to, accepts, and from then on the plugin is one more source: its results show up in search and on Home, and its titles open, list episodes, play in Kino's player, keep progress and appear in "Continuar viendo" and the library like any other title.

You can write, run and test a plugin on your computer with Node before you ever touch the app. This guide has everything you need: the file layout, the manifest, the contract your code must meet, the API Kino gives you, every limit, the quirks of the JavaScript engine, and how to publish.

The complete API demo is kinotvapp/kino-plugin-own-server ("Tu servidor" 1.5.0: every feature up to apiVersion 7 working end to end); kinotvapp/kino-plugin-archive (Internet Archive) is the simplest starting template, and kinotvapp/kino-plugin-archive-audio (Internet Archive Audio) is the reference for music and podcasts (apiVersion 8, Kino 0.9.54). The first two carry the sdk/ folder, the Node kit; the kit alone is in kinotvapp/kino-plugin-sdk. Two more files describe the contract for machines (both on the Reference page): contract.json holds every number and rule the app enforces (the tables in this guide are generated from it, and the app's tests pin its own constants to it), and kino.d.ts declares the whole kino API for your editor (/// <reference path="./kino.d.ts" /> at the top of plugin.js).

The 5-minute path

  1. Start from the template. Create your repository from kinotvapp/kino-plugin-archive -- the simplest one -- or from kinotvapp/kino-plugin-own-server if you need settings, a session, downloads or live channels, or from kinotvapp/kino-plugin-archive-audio for music and podcasts ("Use this template" on any of them, or clone it and copy sdk/). Do not fork it: Kino's community search leaves forks out (Get found). Or let the kit write a skeleton: node sdk/init.mjs my-plugin --host example.com.
  2. Declare what you need in kino-plugin.json: an id, the hosts you will call and the capabilities you export (The manifest).
  3. Write the functions in plugin.js: search and/or home, and resolve at least (The contract, The kino API).
  4. Check it the way Kino does: node sdk/validate.mjs ., then node sdk/run.mjs . search "algo" (Test it locally).
  5. Publish it as a public repository with the topic kino-plugin (mandatory: without it Kino cannot find it), and install it in Kino from Ajustes > Plugins by typing owner/repo or pasting the URL of its kino-plugin.json (Publishing).
  6. Get Kino to show it by itself in "De la comunidad": the topic, name and description, and how to check it, in Get listed in Kino.

Using an AI assistant? Give it the ready-made prompt: it reads this whole guide from llms-full.txt and follows AGENTS.md.

What a plugin is

A public GitHub repository, or a folder inside one, with:

kino-plugin.json   the manifest (required)
plugin.js          the code: a single ES module (required; its name is set by "entry")
icon.png           optional, square, at most 128 KB
README.md          for humans

Kino runs your code in a sandbox: no filesystem, no timers, no other plugins, no access to the person's data. The only way out is kino.fetch, which can reach only the hosts your manifest declares and the person approved on screen, plus the servers the person typed in your plugin's settings (see The manifest). Plugins never reach each other directly: from Kino 0.9.81 one can use the doors another one opens, always through Kino, which checks every request and answer (The plugin protocol).

Kino loads exactly one JavaScript file, so there is nothing for an import to resolve to. If you use a build step or a library, bundle everything into that single file -- see Splitting your code across files for a worked example.

How people install it. In Kino, Ajustes > Plugins, they type the address of your repository:

They type Kino reads
owner/repo the repository root, default branch
owner/repo/sub/dir a folder inside the repository
owner/repo@v1.2.0 a branch, tag or commit (the name cannot contain /); also works with a folder
https://github.com/owner/repo or .../tree/<ref>/<path> the same, pasted from the browser
https://raw.githubusercontent.com/owner/repo/<ref>/<path>/kino-plugin.json (or a github.com/.../blob/<ref>/.../kino-plugin.json, also /raw/) the folder that .json file is in, at that ref; any other kind of file is refused
https://cdn.jsdelivr.net/gh/owner/repo[@<ref>]/<path>/kino-plugin.json (also fastly, gcore, testingcf and quantil.jsdelivr.net) the same repository folder, read from GitHub: no @ref or @latest is the default branch; the ref must be an exact branch, tag or commit (@main, @v1.2.0), so a version range (@1, @^1.2, @1.x) is refused
https://<any public server>/<path>/kino-plugin.json a plugin hosted outside GitHub: see Installing from a manifest URL

The field in Kino says "Escribe usuario/repositorio de GitHub o pega la URL del manifest (kino-plugin.json)". A ?query or #fragment in a pasted URL is ignored. A ref that only comes from a pasted URL (tree, blob, raw, raw.githubusercontent.com or jsDelivr's @ref) is not a pin: a plugin with sealed secrets pasted that way installs from the default branch.

For a repository address, Kino downloads kino-plugin.json, your entry file and the icon from raw.githubusercontent.com, which is why the repository has to be public. A URL of a repository's kino-plugin.json (on GitHub, raw.githubusercontent.com or jsDelivr) always becomes that repository's address, so sealed secrets, signatures and community search keep working for it.

Installing from a manifest URL

Your plugin does not have to live on GitHub (new in the Kino version after 0.9.49). People can paste the https URL of its kino-plugin.json on any public server: your own site, GitHub Pages, a CDN such as jsDelivr's npm/. Kino stores it as the address url:https://…/kino-plugin.json (scheme and host lowercased, default port, query and fragment dropped): that URL is the plugin's identity, and it travels as is to the person's other devices with plugin sync.

  • entry and icon are read relative to the manifest URL: "entry": "plugin.js" next to https://example.com/kino/kino-plugin.json is https://example.com/kino/plugin.js.
  • https only (http:// is refused with "Kino solo instala plugins desde direcciones https…"), on a public name: no IP addresses, no localhost, no single-label or .local/.lan names, no user:password in the URL, and the file has to be named exactly kino-plugin.json. A name that resolves to a private address, and a redirect off https or to such a host, are refused too.
  • No sealed secrets: seals are bound to a GitHub repository, so a manifest with secrets installed from a URL is refused ("Este plugin trae datos sellados, y esos solo funcionan si lo instalas desde su repositorio de GitHub…"). Publish such a plugin on GitHub.
  • Unsigned: a signature is bound to owner/repo, so it is not checked and the plugin installs (and shows) as unsigned.
  • Everything else is the same as a repository install: the consent sheet, hosts and every approval rule, and updates: Kino re-reads the same URL and applies a higher version, asking again when it needs more than was approved. The plugin is never listed by community search (that only finds GitHub repositories with the kino-plugin topic).

Stremio addons are a Kino feature for people, not something you write: in the same field a person can paste the address of a Stremio addon's manifest.json (or a stremio:// link) and Kino generates a plugin for it. Nothing in this guide changes for your plugin.

New in Kino 0.9.88: titles ready ahead, live by clock, http pictures

A plugin can get a title ready while the person reads its page (resolveAhead and prepare), a live stream can hand Kino a CDN's media clock instead of a playlist (clockLive, apiVersion 27, also through an empty enhancements["27"]), and screens draw http pictures on a public host (http pictures). What changed: What's new.

New: identity, notices and plugin stores (apiVersion 15, with Kino 0.9.77)

A plugin can know who the person is without a sign-up (Identity), leave notices in the Home bell (Notices) and be a store: a source of plugins for Kino's store, backed by GitHub, by its own server or by a JSON file (Plugin stores, with two example stores). What changed: What's new.

New: Kino coins (apiVersion 16, with Kino 0.9.78) and apiVersion 17

The coins capability lets a plugin show the person's Kino coin balance and give coins away (kino.coins), and kino.sync.setActive lets a sync provider switch itself on or off. apiVersion 17 (with Kino 0.9.81) brings kino.library.stats, per-profile jobs, the pages widget and more. What changed: What's new.

New: your plugin's own screens (apiVersion 14, with Kino 0.9.74)

A plugin can draw its own full screen inside Kino: columns, cards, lists, tabs, forms, pop-ups and Kino's own poster rows, with Kino's look, on the phone and on the TV from the same JSON tree. Start with Screens and the component catalogue; rooms over the Internet, background jobs, results shared between devices and Kino's text AI arrive too. What changed: What's new.

The guide, page by page

Page What is in it
A first plugin Two files that search and play, and how to run them
Signed plugins Sign your plugin with your own key so people know every update is yours (apiVersion 5, Kino 0.9.45+)
What's new What changed for plugin authors, by Kino version
The manifest Every field and rule of kino-plugin.json, settings, streamHosts, sealed secrets, the person's own servers, insecureHttp, downloads
The contract The functions you export, their arguments, what you return, host questions and the broad video permission, getting a title ready ahead (resolveAhead, prepare), and the errors people understand
The kino API fetch, cookies, secret, crypto, sleep, config, HTML, storage, log, rank
The plugin protocol apiVersion 20, Kino 0.9.81: plugins that use each other through Kino. A provider opens doors (provides, proto_<door>_<call>), a consumer uses them (consumes, kino.plugins.call); types, errors, limits, streams, the install gate with recommends and go.installPlugin, what the person sees, and the TMDB + Cine Trivia example
Sharing A Share button that sends a text (and the title) to Kino Social's wall door as a draft (Kino 0.9.81, Kino Social 0.9.7), and Kino 0.9.84's share cards: go.plugin, openFrom.routes, ctx.caller and kino.image.thumbnail
External resolver apps externalResolve (apiVersion 11): hand a title to an independently-installed app that turns it into a playable URL; the flow, media, portable, errors, casting, building the other side
Sync providers syncProvider (apiVersion 12, Kino 0.9.74): carry the person's cross-device sync through a service your plugin talks to; who can read what, the sync block, cadence, conflicts, the 4 MiB limit, sending the settings to another device, Sync-Gram and Sync Servidor
Sockets and plugin-served bytes apiVersion 13, Kino 0.9.74: kino.ws WebSockets, streams your plugin serves through read (played and cast by Kino), kino.crypto's byte operations, a complete WebSocket example with its test
Catalog and large storage apiVersion 13, Kino 0.9.74: kino.catalog, a SQLite catalog of up to 100,000 items searched by Kino, and storageLarge
Images from the plugin apiVersion 13, Kino 0.9.74: posters and stills your plugin serves through image
Files on the device apiVersion 21, Kino 0.9.82: kino.files, files and folders the person picks, read by ranges or played with kino-file:
Saving where the person is apiVersion 22 (Kino 0.9.83): kino.progress, where the person is in a chapter or a book; your plugin builds its own "keep reading" row
QR codes apiVersion 13, Kino 0.9.74: the settings form's qr type and kino.qr.scan, with a two-device login recipe
Screens apiVersion 14, Kino 0.9.74: your plugin's full screen, the screen block, screen() and screenEvent(), state, answers, go, timers, TV focus, limits, testing with the kit
Components: layout, content and actions Every screen component with its properties: Column, Row, Card, Scaffold, AppBar, NavigationBar, PageView, ListTile, text, images, tables, buttons, toasts
Components: forms, overlays and navigation Fields, validation, the settings node, dialogs, sheets, menus, anchored pop-ups, every go shape
Components: state, style and recipes State, events, per-size values, Flutter-style names, common properties, tokens, limits and recipes
Rooms, the library and player control apiVersion 14: kino.room, kino.library and playerControl
Background jobs, shared results and AI apiVersion 14: schedule with jobs and job(ctx), kino.shared and kino.ai
Screens without raising your apiVersion enhancements: offer a screen and the apiVersion 14 features and still install on an older Kino; an empty "27" block turns on clockLive; the feature apiVersion
Structure a bigger plugin src/ by responsibility, a plugin.js generated with esbuild and checked with check:built
Exporting and importing a plugin The .kinoplugin file: what it holds, the signature, sealed secrets
Live channels live items, the En vivo tab, M3U/XMLTV playlists, guides, liveStreamHosts, live by clock (clockLive, apiVersion 27, Kino 0.9.88), three recipes
Customize your plugin Everything your plugin can change in how Kino shows it, in one table: icon, color, settings, section, categories, colors, Home rows, the Servidor menu, your own sentences
The settings form Every field type and its attributes, section, status and action, clearSettings, setSettings and "Is this you?", the link and help aids, validateSettings, a complete example, the own tab and syncing
Signing every request HLS streams signed on every request: signing, sign, retries and alternateHosts (apiVersion 6)
A browser window the person drives "visualBrowser": true and kino.visualBrowser.open (apiVersion 20, Kino 0.9.81): a web window the person sees and uses to sign in or finish a step, on your own hosts; cookies, storeAs, the "Vincular cuenta" recipe, Android TV (experimental). Also the page's localStorage: collect.localStorage and doneWhen.localStorage (Kino 0.9.87).
Hidden browser "browser": true / "pages", kino.browser.capture and kino.browser.page: when to use them, the safety model, never a captcha, timeouts and failures (apiVersion 6)
Moving saved titles migrate: move what the person had saved to your plugin (apiVersion 6)
Section, categories and colors section, categories and theme (apiVersion 6)
App themes appThemes (apiVersion 18; painted surfaces, a background picture, a font and TV layouts from apiVersion 26): tokens and ranges, price in kinos, experience, a vector logo, go.useTheme and go.setExperience
The player panel panel, panelAction and playerEvent, player actions and settingsLayout (apiVersion 9); the panel in screen mode, tabs in another plugin's panel and on a live channel, the pinned panel (apiVersion 14)
The player slot playerSlot and the slot block (apiVersion 23, Kino 0.9.83): up to three small elements in the top-right corner of the TV player, the clock example, consent and the kit
Logs and telemetry debug, the Registro page, telemetry, kino.log.report, logcat and playback metrics (apiVersion 6)
Limits and engine quirks Every number in one place, how your code lives, what QuickJS lacks, the rejection trap
Test it locally The Node kit: run.mjs, validate.mjs, record and replay, live channels
Identity apiVersion 15: kino.identity.telegram, a pseudonym of the person for your plugin and, for the author keys Kino trusts, the signed token
Notices in the bell apiVersion 15: kino.notifications.post and clear, limits, go.screen
Plugin stores apiVersion 15: pluginStore, storeSync full or as changes, local and live stores, how Kino mixes them, the blocklist, 18+ and limits
Example stores Two complete stores to copy: one with a static JSON, one with its own API
Get listed in Kino The five steps to show in "De la comunidad", how long it takes and how to check it
Publishing Releases, updates and approvals, and appearing in "De la comunidad"
What people see The consent sheet, host dialogs, player messages, Configurar, statuses, disabling and uninstalling
Cookbook An HTML site with a login, a JSON API with a token, the person's own server, two sync providers, Widevine, plain http
Nuvio scrapers How people install Nuvio scrapers, what the conversion builds, and its limits
Plugins that use Nuvio scrapers kino.nuvio (apiVersion 11): your plugin names a Nuvio repository and Kino installs and uses its scrapers to look for links
Stremio addons How people install a Stremio addon, how each resource maps, what is refused, and its limits
CloudStream plugins Kino 0.9.54: how people install the plugins of a CloudStream repository, the complement, how each part maps, and its limits
Example plugins The two published examples, and how the reference plugin is built
Claims and plugin takedowns How to ask for a community plugin to leave the index, what Kino does and how to appeal
Reference contract.json and kino.d.ts, to read or download