The manifest¶
kino-plugin.json, at most 16 KB:
{
"id": "archive-org",
"name": "Internet Archive",
"version": "1.0.0",
"apiVersion": 1,
"entry": "plugin.js",
"description": "Películas de dominio público y televisión clásica de archive.org",
"author": "kinotvapp",
"homepage": "https://github.com/kinotvapp/kino-plugin-archive",
"hosts": ["archive.org", "*.archive.org"],
"capabilities": ["search", "home", "browse", "episodes", "resolve"],
"color": "#E0A030",
"icon": "icon.png"
}
If a rule below is broken, Kino refuses to install the plugin and shows a message in Spanish that names the field.
| Field | Rule |
|---|---|
id |
Required. ^[a-z0-9][a-z0-9-]{1,39}$ (2 to 40 lowercase letters, digits or hyphens, not starting with a hyphen). Not one of live, local, unknown, plugin, own, subtitle-keys, subtitle-prefs (Kino's own names; older versions reserve a few more: if one says "El id … está reservado por Kino", pick another). It is the plugin's identity: never change it once people have installed it. |
name |
Required. 1 to 40 characters. |
version |
Required. MAJOR.MINOR.PATCH and nothing else (no -beta, no +build), each number up to 6 digits and without leading zeros. |
apiVersion |
Required. 1 to 27 (27 adds the clockLive field of a live stream, Kino 0.9.88: Kino builds the live window from a CDN's media clock, and a plugin that keeps a lower apiVersion turns it on with an empty enhancements["27"]; 26 adds to appThemes the painted surfaces, gloss, layouts, assets, background picture and font, Kino 0.9.87; 25 lets a stream subtitle carry its own decrypted text instead of a url, Kino 0.9.86; 24 lets a stream's drm be a list and adds the clearkey type, Kino 0.9.85; 23 adds the playerSlot capability and the slot block, Kino 0.9.83; 22 adds the progress capability, Kino 0.9.83; 21 adds the files capability, Kino 0.9.82): 12, 13 and 14 arrive together in Kino 0.9.74. A higher number than Kino supports is refused with "Este plugin necesita una versión más nueva de Kino". Declare the lowest number that has what you use, so your plugin also runs on older Kino builds: 2 for download, drm, insecureHttp, "hosts": [] or live items; 3 for channels/liveStreamHosts; 4 for a list setting, streamHosts or secrets; 5 only for a signed plugin (Kino 0.9.45+); 6 (Kino 0.9.50+) for anything on the apiVersion 6 list: typed or larger sealed secrets, migrate, scopedSearch, request-signed streams, the settings form's section/status/action, debug, telemetry, section, categories, theme, userMessage, adult entries, channels in Home rows, kino.crypto's key-pair calls, the meta capability, "browser": true with kino.browser.capture (and "browser": "pages" with kino.browser.page too), and labelled and lazy copies; 7 (Kino 0.9.51+) for the tracking and segments capabilities; 8 (Kino 0.9.54+) for music and podcast items and the details export; 9 (Kino 0.9.55+) for section.labelEn, the player panel, settingsLayout and a hand-written plugin's fetchHosts: "any"; 10 (Kino 0.9.65+) for the playlists capability (still just a contract -- no plugin uses it today); 11 (Kino 0.9.66+) for the externalResolve capability and the manifest's externalResolver; 12 (Kino 0.9.74+) for the syncProvider capability, the manifest's sync block and the settings form's link and help types; 13 (Kino 0.9.74+) for the socket and byteSource capabilities (Sockets and plugin-served bytes), storageLarge and catalog (Catalog and large storage), qrScan and the settings form's qr type (QR codes), imageSource (Images from the plugin); 14 (Kino 0.9.74+) for the screen capability with its screen block, the library, room and playerControl capabilities (Rooms, the library and player control), playerPanelTab (The player panel), schedule with jobs, ai and shared (Background jobs, shared results and AI), a setting's unlockWith and kino.fetch's maxBytes and stopAt options; 15 (Kino 0.9.77) for the identity, notifications and pluginStore capabilities with their pluginStore block, and for season and episode in kino.library.watched(); 16 (Kino 0.9.78) for the coins capability (kino.coins: the person's Kino coins balance, and giving one coin for a post) and for kino.sync.setActive, which is not an apiVersion; 17 for kino.library.stats (a month's aggregates of what the person watched, for the library capability; Kino 0.9.81), a job's "perProfile" (Background jobs), kino.tmdb inside a job and 60 s and 20 requests for a job with ai; 18 (Kino 0.9.81) for appThemes (whole-app themes), go.useTheme, go.setExperience and activeTheme (App themes); 19 (Kino 0.9.81) for the lyrics capability and go.installPlugin; 20 (Kino 0.9.81) for the plugin protocol: provides, consumes and kino.plugins.call (both blocks also work inside enhancements["20"] without raising yours), and for visualBrowser and kino.visualBrowser.open (a browser window the person drives); the enhancements block is read by Kino 0.9.74 at any apiVersion (kino.crypto's byte operations come with the same Kino version at any apiVersion; a stream's advisory media and its portable copy are read at any apiVersion). |
entry |
Required. Relative path of the JavaScript file: letters, digits, ., _, - and / only, no .., at most 200 characters, ends in .js. The file is at most 1 MB. Write "plugin.js", never "./plugin.js": Kino 0.9.45 and older refuse a leading ./ (see the warning below). |
signature |
Optional, from apiVersion 5: { "authorKey": "<64 hex>", "value": "<128 hex>" }, written by node sdk/seal.mjs --sign: your signature over the entry file. Needs Kino 0.9.45+. See Signed plugins. Below apiVersion 5 it is ignored. |
hosts |
Required. at least 1 entry, with no upper limit from Kino 0.9.45 (only the manifest's 16 KB bounds it). Kino 0.9.44 and older refuse more than 20, so with more than 20 hosts the kit warns "Más de 20 hosts: Kino 0.9.44 o anterior rechaza este plugin; necesita Kino 0.9.45 o superior". From apiVersion 2 it may be empty, [], when the plugin has a url setting: see The person's own servers). From apiVersion 18 it may also be empty in a plugin that only ships appThemes: it reaches nothing, and its card says it doesn't connect to the internet. From apiVersion 20 it may also be empty in a plugin that only opens doors with provides, and in a screen-only consumer: a non-empty consumes and capabilities exactly ["screen"] (its own kino.fetch is then refused unless it declares fetchHosts: "any" or a url setting; pictures from public addresses (https, and http where kino.screen.httpImages) need no host; with no setting at all its card says it doesn't connect to the internet). Never a placeholder such as example.com: sdk/validate.mjs warns on one. Each a lowercase DNS name (archive.org), *. plus a DNS name (*.archive.org), or (apiVersion 2 only) an object { "host": "…", "insecureHttp": true } (below). Host names only: no scheme, port or path. No bare *, no IP addresses, no localhost, nothing ending in .local, .lan, .internal, .localhost or .home.arpa, and at least one dot. *.x covers subdomains only, not x itself: if you need both, list both. The hosts a person approves later, one by one, while your plugin runs (A host you forgot) are not counted against the manifest. |
capabilities |
Required. A subset of search, home, browse, episodes, resolve, download, drm, channels, migrate, scopedSearch, meta, subtitles, tracking, segments, lyrics, playlists, externalResolve, nuvio (apiVersion 11, with nuvioRepos), syncProvider, from apiVersion 13 socket, byteSource, storageLarge, catalog, qrScan, imageSource, and from apiVersion 14 screen, library, playerPanelTab, playerControl, room, schedule, ai and shared, and from apiVersion 15 identity, notifications and pluginStore, and from apiVersion 16 coins, and from apiVersion 21 files, and from apiVersion 22 progress (declarative, no consent line; it may stand alone or sit beside any other capability and the plugin stays that kind of plugin), and from apiVersion 23 playerSlot (the exports playerSlot and playerSlotAction and the slot block; it may be the plugin's only capability; red consent line only with a fixed element). Must include resolve and at least one of search or home, except in a catalog-only plugin ("catalogOnly": true, Kino 0.9.54) and a plugin that declares only subtitles, tracking, segments and/or syncProvider (below); from apiVersion 13 such a plugin may also declare socket, storageLarge, catalog and qrScan and stay that kind of plugin (a sync provider that talks over kino.ws, ["syncProvider", "socket"]), while those four alone, with none of the four above, still need resolve and search or home. search, home, browse, episodes and resolve must each be an exported function of the entry file, or the install fails with "El plugin no carga: le falta ...". download and drm need apiVersion: 2 and are declarative flags instead — the app acts on them, not your code, so nothing extra to export; declaring one shows its consent line ("Puede descargar videos para verlos sin conexión" / "Reproduce video protegido (DRM)") and needs approval again on an update that adds it. download gives your titles offline downloads (see Downloads); drm lets a Stream carry a Widevine license (see A Widevine-protected stream). channels needs apiVersion: 3 and the exports liveCategories and liveChannels (see Channels in the En vivo tab). migrate needs apiVersion: 6 and the export migrate; declaring it shows "Revisar lo que tienes guardado (biblioteca, historial, favoritos) para pasarlo a este plugin" and needs approval again on an update that adds it (see Moving saved titles). scopedSearch needs apiVersion: 6 and search (refused otherwise with "La capacidad \"scopedSearch\" necesita también \"search\""); it exports nothing of its own: your search gets within when the person searches inside a "Ver más" page (see Searching inside a "Ver más" page). meta needs apiVersion: 6 and the export meta, no consent line (see Describing other titles). subtitles needs the export subtitles; ["subtitles"] alone is a subtitle provider; a plugin that declares only subtitles, tracking and/or segments (a subtitle provider, a tracker, a segment source or a mix of them) is also an exception to "resolve and search or home" (see Subtitles for any title). tracking needs apiVersion: 7 and the export track; declaring it shows a red line naming your hosts ("Le contará a seenr.app qué ves y cuándo lo terminas") and needs approval again on an update that adds it, even when Kino approves other updates on its own (see Telling a tracker what the person watches). segments needs apiVersion: 7 and the export segments; declaring it shows "Agrega el botón para saltar la intro y los créditos", not in red and with no approval of its own (see Where the intro and credits are). playlists needs apiVersion: 10; unlike the others, none of its six exports (playlists, playlistItems, playlistCreate, playlistAddItem, playlistRemoveItem, playlistReorder) is required -- declare only the ones your service supports; no consent line of its own; still no installed or announced plugin uses it, and Kino doesn't wire it into any screen yet (see Playlists). externalResolve needs apiVersion: 11, a declarative flag like download and drm (nothing to export): it lets a resolve() answer (or one of a Stream's alternatives) be { external: { protocol, ref } } instead of a playable url, so Kino hands ref to an independently-installed resolver app; it adds no consent line to your install sheet (the only consent is per app, asked the first time one is needed; see External resolver apps and the contract). syncProvider needs apiVersion: 12 (Kino 0.9.74) and the exports syncPull and syncPush (syncStatus optional); it may be the plugin's only capability. The plugin becomes the transport of the person's cross-device sync: Kino encrypts the snapshot and hands the plugin an opaque base64 blob to store and give back byte for byte. It requires the manifest's sync block with keySecret. Declaring it shows one consent line, always in red, "Sincronizará tus datos a través de su servicio: el plugin y su servicio podrán leerlos", and needs approval again on an update that adds it (never approved on its own). See Sync providers. The six of apiVersion 13 (Kino 0.9.74) show no consent line and need no approval of their own: socket is declarative and unlocks kino.ws, WebSockets to your declared hosts only; byteSource needs the export read and lets a stream be { source: "plugin", handle, size, mime } (Sockets and plugin-served bytes); storageLarge is declarative and makes kino.storage 16 MB, device-only; catalog is declarative and unlocks kino.catalog (Catalog and large storage); qrScan is declarative and unlocks kino.qr.scan (QR codes); imageSource needs the export image and lets a poster, backdrop, still or section hero image be { source: "plugin", handle } (Images from the plugin). Each one below "apiVersion": 13 is refused ("The \"catalog\" capability needs apiVersion 13"). The eight of apiVersion 14 (Kino 0.9.74): screen needs the exports screen and screenEvent and the screen block, may be the plugin's only capability and shows no consent line (Screens); library (declarative, may stand alone) reads what the person watched and saved (kino.library); playerPanelTab needs the export panel and "panel": { "contributes": true }, may stand alone and adds a tab to the player panel of any plugin's title (The player panel); playerControl (declarative, never alone, needs a panel) lets your player actions pause and move the video on their own (Player control); room (declarative, never alone) unlocks kino.room, rooms over the Internet hosted on the person's device; schedule needs the export job and the jobs block, never alone (Background jobs); ai (declarative, never alone) unlocks kino.ai.ask; shared (declarative, never alone) unlocks kino.shared. library, playerPanelTab, playerControl, room, schedule and ai each show a red consent line and need approval at install and on the update that adds them (never approved by Kino on its own), and the person can switch them off in your tab in Ajustes; shared shows a plain line, not red, and waits for no approval. A plugin that stays on a lower apiVersion can offer them through enhancements. The three of apiVersion 15 (Kino 0.9.77) are not offered through enhancements: identity (declarative, never alone) unlocks kino.identity.telegram, with a red consent line, and gives the signed token only to the author keys Kino trusts (kinoIdentity.tokenAuthors; any other author gets the pseudonym and the attestation from Kino 0.9.88); notifications (declarative, never alone) unlocks kino.notifications, with a plain line; pluginStore needs the export storeSync (and storeList and storeSearch for a live store), may stand alone and makes your plugin a source of plugins for Kino's store, with a plain line and, for a live store, a red one (Plugin stores). All three need approval at install and on the update that adds them, and the person can switch identity and notifications off in your tab in Ajustes. coins (apiVersion 16, Kino 0.9.78; declarative, never alone and not offered through enhancements either) unlocks kino.coins, the person's Kino coins balance and giving one coin, with a red consent line («Podrá ver tu saldo de kinos y regalar tus kinos»); it needs approval the same way and has no switch of its own: the person revokes it by disabling or removing your plugin. From apiVersion 20 a plugin whose only purpose is a non-empty provides may declare no capability at all (the field may be left out): see A plugin that only provides. provides and consumes are not capabilities: a provider or a consumer keeps the capabilities of the kind of plugin it is. |
settings |
Optional. What the person fills in on your plugin's "Configurar" screen: see below. |
permissions |
Optional. A list of names from the closed list in contract.json. The list is empty in this version: any name is refused with "permiso desconocido: …". It exists so a later version can add permissions (each one shown on the consent screen) without a new apiVersion. |
color |
Optional #RRGGBB: the accent of your plugin's tab and chips. A neutral color by default. |
icon |
Optional relative path to a square .png, at most 128 KB. An icon that is missing or too big is skipped without failing the install. |
discoverable |
Optional true or false (default true), at every apiVersion. false keeps the plugin out of Kino's community search (see Get found); people can still install it by typing its address. Any other value is refused with "El campo \"discoverable\" debe ser true o false". |
categories |
Optional, at every apiVersion: what your plugin offers, for the category chips of Kino's plugin marketplace (Recomendados, "De la comunidad", "Elige tus plugins"). A list without repeats of movies, series, anime, live, radio, subtitles, utilities, themes, adult (themes: a plugin that offers app themes, listed under Temas), or of a new type of your own (manga, audio-books): 2 to 24 lowercase letters, digits and hyphens, starting with a letter. A new type needs no change in Kino: its chip (the id with hyphens as spaces and a capital first letter: "Manga", "Audio books") shows up by itself while some listed plugin carries it. Declare a new type in the catalog entry whenever you can: a Kino that predates new types refuses a manifest that names one, while it silently drops the id from a catalog entry. When present it replaces Kino's guess from your capabilities (channels is live, episodes is series, anything that lists and plays is movies); an adult plugin's chip only shows while the person's 18+ code is unlocked. Any other value is refused with "El campo \"categories\" debe ser una lista sin repetidos de: movies, series, anime, live, radio, subtitles, utilities, themes, adult, o un tipo nuevo (de 2 a 24 letras minúsculas, dígitos y guiones, empezando por una letra)". Not the same as the categories() export (tiles inside Kino's Categorías, see Section, categories and colors). |
catalogOnly |
Optional true or false (default false), at every apiVersion, from Kino 0.9.54 (older Kino ignores it). true says the plugin lists and describes titles but plays none: resolve is no longer required, and Kino never calls it; its titles go to "Buscar dónde verlo". It needs one of home, browse, search or meta, and refuses download, drm, channels, streamHosts and "browser": true. To stay installable on Kino 0.9.53 and older, keep declaring and exporting resolve (failing with not_found) and search or home. See Catalog-only plugins. Any other value is refused with "El campo \"catalogOnly\" debe ser true o false". |
resolveAhead |
Optional true or false (default false), at every apiVersion (no apiVersion of its own; first read by Kino 0.9.88, ignored by an older Kino). true lets Kino call your resolve for a movie or an episode before the person presses play, so the video starts sooner. Kino does it only when your resolve can ask the person nothing: an approved "fetchHosts": "any", video from any server (an approved "streamHosts": "any" or the broad video permission), no externalResolve and no browser. Declare it only if a resolve nobody plays has no effect the person would notice; otherwise leave it out and export prepare instead. It never refuses the plugin: any other value is ignored (logged, and sdk/validate.mjs warns), and so is true beside catalogOnly or browser. See Getting a title ready ahead. |
recommends |
Optional (Kino 0.9.81), at every apiVersion (an older Kino ignores it; it has no apiVersion of its own): a list of at most 8 plain GitHub owner/name strings, the plugins yours works better with (no URL, no sub-path, no @ref, at most 100 characters each; the case you write is kept, repeats ignoring case collapse). Anything else is refused: The "recommends" field must be a list of at most 8 plain GitHub owner/name repositories. Your screen and screenEvent get installed, { "<repo as written>": true \| false } for these entries only, to offer a go.installPlugin button for each missing one: see Recommended plugins and installed. A protocol consumer names its provider here too (the install gate). |
creator |
Optional, at every apiVersion (Kino never reads it; no apiVersion of its own). Your Kino Social handle (3 to 20 characters: letters, digits and _), e.g. "lordmacu". It only rides along in the published kino-plugin.json so Kino Social's community-plugin index can attach the plugin to your profile there. Leave it out and the plugin simply appears on no Kino Social profile. A value that does not match that shape is ignored. |
provides |
Optional, apiVersion 20 (Kino 0.9.81; also inside enhancements["20"], which keeps your apiVersion): the doors this plugin opens to other plugins, { "<door>": { "summary", "calls", "streams", "types" } }: at most 4 doors, each with a summary of at most 120 characters, at most 16 calls and 8 streams, answered by your exports proto_<door>_<call>(arg) and proto_<door>_<stream>(cursor). Kino checks every request and answer against the declared types. A malformed block refuses the manifest with a message naming the door and the field; a top-level block below apiVersion 20 is refused with The "provides" block needs apiVersion 20. A plugin with only provides needs no capability and may have "hosts": []. See The plugin protocol. |
consumes |
Optional, apiVersion 20 (Kino 0.9.81; also inside enhancements["20"]): the doors of other plugins this one uses, { "<alias>": { "repo", "door", "calls", "streams" } }: at most 8 entries; repo the provider's plain GitHub owner/name (a fork does not stand in), door its door, calls (at most 16) and streams (at most 8) the names you use. Your code calls await kino.plugins.call("<alias>", "<call>", arg); the consent sheet shows «Usa datos de <provider> (<door summary>)». Pair it with recommends and go.installPlugin to invite the person to install the provider. See The plugin protocol. |
openFrom |
Optional, apiVersion 20 (Kino 0.9.84; also inside enhancements["20"]): { "routes": ["detail", …] }, the names of your own screen routes that other plugins' cards may open with go.plugin. It needs the screen capability. 1 to 16 different names, each 1 to 64 letters, digits or . _ ~ - (the same names a go.screen route takes). It says what may be opened, not how: you decide later, in your screen, how each route reaches its content. A card whose route you do not list falls back to a search. A bad list refuses the manifest with a message naming openFrom.routes. See Sharing. |
visualBrowser |
Optional true or false (default false), apiVersion 20 (Kino 0.9.81; also inside enhancements["20"], which keeps your apiVersion); below it the key is ignored and any other value is refused (The "visualBrowser" field must be true or false). true lets the plugin open kino.visualBrowser.open, a web window the person drives on the plugin's own hosts. Not a capability: nothing is approved at install except a plain consent line, and Kino asks in its own sheet at every open. See A browser window the person drives. |
browser |
Optional true, false or "pages", from apiVersion 6; ignored below. true lets the plugin open pages in a hidden web view on the device with kino.browser.capture (in resolve), shown in red as "Puede abrir páginas web ocultas para encontrar el video"; "pages" adds kino.browser.page, shown as "Puede abrir páginas web ocultas para mostrar contenido y encontrar el video". An update that adds it, or moves true to "pages", waits for approval again; an approved plugin's resolve gets 75 s. See Hidden browser. Any other value is refused with "El campo \"browser\" debe ser true, false o \"pages\"". |
externalResolver |
Optional, from apiVersion 11, and only with the externalResolve capability (otherwise the manifest is refused: The "externalResolver" field needs the "externalResolve" capability): { "package": "com.example.resolver", "apk"?: { "url": "https://github.com/<owner>/<repo>/releases/download/<tag>/<file>.apk", "sha256": "<64 hex characters>", "label"?: "..." }, "fdroid"?: true, "downloader"?: { "code": "<3 to 10 digits>" } }. package is the one resolver app this plugin wants its external answers handed to; with it set, no other app is ever asked, whatever else declares the protocol (a stream's own external.resolver overrides it). apk, fdroid and downloader are optional and independent ways to get that app when it is not installed: apk is where Kino may offer to download it. Only a GitHub release asset (https://github.com/<owner>/<repo>/releases/download/<tag>/<file>) or an archive.org file (https://archive.org/download/<item>/<file>) is accepted (https, no query), at most 300 MB, and the downloaded file must have exactly that sha256 or nothing is offered; label is the app's name for the person (at most 40 characters). fdroid: true says the same package is listed in F-Droid (Kino opens F-Droid for exactly that package; only true is accepted). downloader.code is a Downloader (TV sideloading app) code of 3 to 10 digits that Kino only shows. Anything malformed refuses the manifest (The "externalResolver" field must be an object with a "package" (an Android package name) and, optionally, an "apk" with a GitHub release "url" ... and a 64-character hex "sha256"; "fdroid" may only be true and "downloader" an object with a "code" of 3 to 10 digits). Older Kino ignores the field. See External resolver apps. |
sync |
From apiVersion 12 (Kino 0.9.74), required with the syncProvider capability and only with it (otherwise the manifest is refused: The "sync" field needs the "syncProvider" capability; a provider without it or without keySecret: The "syncProvider" capability needs a "sync" field whose "keySecret" is the key of one of the plugin's own "password" settings): { "mode"?: "poll" \| "realtime", "pullEveryMs"?: 600000, "pushDebounceMs"?: 300000, "maxBlobBytes"?: 4194304, "keySecret": "<setting key>", "provision": ["<setting key>", ...] }. mode defaults to poll (Kino pulls when it comes to the front and every pullEveryMs, and pushes pushDebounceMs after a change); realtime lets the provider call kino.sync.remoteChanged() when it learns the remote moved. The times are positive whole milliseconds that Kino clamps to its own floors. maxBlobBytes is the largest blob the provider accepts (default and maximum 4194304, 4 MiB); it also sets how big syncPull/syncPush's kino.fetch requests, responses and answers may be (ceil(maxBlobBytes × 4/3) + 64 KB). keySecret names one of your own password settings (with no default): Kino derives the sync key from its value on each device, so the key never travels, and the plugin and its service can read the synced data (red consent line). provision lists at most 8 of your own valued settings (secret or not) that "Enviar configuración" ("Send settings") hands to a second device; it must include keySecret, and from apiVersion 13 it may name a "sync": false password as a one-shot secret (never as keySecret), never a "sync": false text. From apiVersion 13, "generateKey": true makes Kino create the keySecret value itself (32 random bytes as hex) while it is empty (A key Kino makes); anything but a boolean is refused. Every rule, message and trade-off: Sync providers. Older Kino ignores the field. |
screen |
From apiVersion 14 (Kino 0.9.74), required with the screen capability: the menu entry and the options of the plugin's full-screen canvas, { "label": "Noticias", "labelEn": "News", "icon": "list", "menuOpens": "screen" }. Every field and rule: The manifest's screen block. |
jobs |
From apiVersion 14 (Kino 0.9.74), required with the schedule capability and refused without it: 1 to 3 background jobs, each { "id": "refresh", "label": { "es": "Actualizar noticias", "en": "Refresh news" }, "everyMin": 60, "everyOptions": [15, 30, 60, 180, 720, 1440] }, with an optional runOn ("any" or "preferPhone") and perProfile (apiVersion 17, true or false, always with runOn: "any"): one run per profile of the device with your plugin on. Every field and rule: Background jobs. |
slot |
From apiVersion 23 (Kino 0.9.83), with the playerSlot capability (each needs the other): { "elements": [ { "id", "kind", "mode" } ] }, 1 to 3 elements; id matches ^[a-z][a-z0-9_-]{0,23}$ and is unique; kind is text, icon, image or button; mode is overlay (shows with the controls) or fixed (always there; a red consent line). Up to three small elements in the top-right corner of the TV player: see The player slot. |
pluginStore |
From apiVersion 15 (Kino 0.9.77), optional and only with the pluginStore capability (refused without it): { "mode"?: "local" \| "live", "name"?: 1 to 60 characters }. mode is "local" by default; name is how the store shows in the filter and on its cards (default: the plugin's name). See Plugin stores. |
enhancements |
Optional, read by Kino 0.9.74 (apiVersion 14) at any apiVersion; an older Kino ignores it like any key it does not know. Features of a newer apiVersion without raising yours: "apiVersion": 8, "enhancements": { "14": { "capabilities": ["screen", "library"], "screen": { "label": "Inicio" } } }. A block that fails the rules is dropped and logged, never refusing your plugin. From Kino 0.9.81 a block may also carry provides and consumes ("enhancements": { "20": { "provides": { … } } }): the plugin protocol on a plugin that keeps a lower apiVersion. From Kino 0.9.88 an empty "27": {} block raises your feature apiVersion to 27, which turns on clockLive for your live streams; your code reads that number in kino.pluginApiVersion. Everything: Screens without raising your apiVersion. |
debug |
Optional true or false (default false), from apiVersion 6; ignored below. From Kino 0.9.50 every installed plugin has a "Modo debug" switch in its Ajustes tab (errors on screen and a "Registro" the person can copy or share with you); this field only turns it on by default. Without it the switch starts off and each person turns it on when they want to send you a report. The person's own choice wins once they touch it (validate.mjs notes what true means). See Logs and telemetry. Any other value is refused with "El campo \"debug\" debe ser true o false". |
telemetry |
Optional true, false or "verbose" (default false), from apiVersion 6; ignored below. Asks to share your plugin's diagnostic lines with Kino's error tracker when a call fails, whatever repository the plugin comes from, and turns on kino.log.report. It shows on the consent sheet and an update that newly declares it waits for their approval. Up to Kino 0.9.53 the lines of every plugin that declares it are always sent, with no switch; from Kino 0.9.54 your plugin's tab in Ajustes has an "Enviar registros de errores y de reproducción" switch, on by default, and the consent line says "Comparte con Kino registros de errores y datos técnicos de algunas reproducciones para corregir fallas" (true also sends a small sample of good playbacks). See Logs and telemetry. Any other value is refused with "El campo \"telemetry\" debe ser true, false o \"verbose\"". |
section |
Optional { "label": "…" } (1 to 20 characters), from apiVersion 6; ignored below. Gives your plugin its own section and requires the section export: see Section, categories and colors. From apiVersion 9 (Kino 0.9.55) it may also carry "labelEn" (1 to 20 characters): the section's name when the app is in English; label stays the Spanish text and the fallback. Below 9 it is ignored without being checked. An empty one, one over 20 or one that is not a text is refused with "El campo \"section.labelEn\" debe tener entre 1 y 20 caracteres". See English texts. |
theme |
Optional object, from apiVersion 6; ignored below. Up to five #RRGGBB colors: accent, onAccent, background, surface, highlight; any other key is refused with "El campo \"theme\" tiene un color desconocido". The manifest only checks the format; the readability guardrails run when Kino uses the colors (Your colors). |
appThemes |
Optional list, from apiVersion 18 (Kino 0.9.81); ignored below and not offered through enhancements. 1 to 8 whole-app themes declared as data (no code, no network, no capability), each { "id", "name": { "es", "en" }, "colors", "background", "shape", "typography", "elevation", "motion", "player", "tv", "phone", "adjustable", "pluginColors", "price", "experience", "logo" }. A format error (an unknown field or token, a wrong type, a bad or repeated id) refuses the manifest; a value outside its range is dropped with a warning and Kino's stays. A plugin with only appThemes needs no capabilities and may have "hosts": []; give it "categories": ["themes"]. Every token, range and guardrail, the price in kinos, the suggested experience, the vector logo and go.useTheme: App themes. Not the same as theme above, which only colours your own pages. From apiVersion 26 a theme can also paint (surfaces, style.gloss, layout, assets, background.image, typography.fontFamily, shape.heroRadius, shape.railItemRadius): see Painted surfaces, layouts and files. |
panel |
Optional, { "label", "labelEn?", "icon?" \| "iconFile?" }, from apiVersion 9 (Kino 0.9.55); ignored below. A button in the player, next to the subtitles one, while a title from your plugin plays, that opens your own panel. label 1 to 24 characters; icon one of 16 names (tune by default) or iconFile, a 96×96 PNG with alpha of at most 24 KB, never both. Requires the panel export; panelAction and playerEvent are optional. See The player panel. |
settingsLayout |
Optional, a list of rows, columns and cards holding { "setting": "<key>" }, from apiVersion 9; ignored below. Arranges the settings you already declared without removing any (those you do not name go at the end). See settingsLayout. |
fetchHosts |
Optional, only "any". Lets your kino.fetch reach any public host, over https on port 443 only, for scrapers whose sites or extractor redirects rotate domains. On a plugin written by hand Kino honours it from apiVersion 9 (Kino 0.9.55), after the person approves it in red ("Puede conectarse a cualquier servidor público de internet (solo https, nunca tu red local)"); kino.fetchAnyHost is true when it is active. With a request budget, and without touching your declared hosts. Below apiVersion 9 Kino honours it only on the manifests it makes when it converts a Nuvio scraper; on your plugin it is ignored (your kino.fetch stays on your hosts) and sdk/validate.mjs warns "fetchHosts only takes effect on plugins converted from Nuvio or, on one written by hand, from apiVersion 9 (Kino 0.9.55); in your plugin it is ignored". See Reaching any server. From apiVersion: 4 its only value is "any"; any other is refused with The "fetchHosts" field only takes "any". Below apiVersion 4 it is ignored. |
nuvioRepos |
Optional, from apiVersion 11 (Kino 0.9.71); ignored below it. 1 to 4 Nuvio repositories, each a GitHub owner/repo or the https address of its manifest.json. It goes with the nuvio capability (each requires the other) and fixes the repositories kino.nuvio may use: any other is refused with not_allowed. The capability is declarative and the person approves it when installing. See Plugins that use Nuvio scrapers. |
description, author, homepage |
Optional strings. Trimmed and cut to 300, 60 and 200 characters. Kino shows the name, author, version and description when it asks the person to install. |
support |
Optional. The author's email, one single address (name@example.com). With it, the plugin's actions sheet offers Report a problem: it opens the person's own mail app with a message to that address, the plugin's cleaned log and the device facts in the body. The person reads and edits it before sending; Kino sends nothing and has no server. Phone only (a TV has no mail). An invalid address is ignored: the manifest stays valid and the plugin offers no Report a problem. Kino 0.9.58 or newer; older versions ignore the field. |
Other keys are ignored. hosts does three jobs: it is what the person approves, it is the only set
of sites kino.fetch can reach, and it is the set a Stream's URLs must be on: the video, its
subtitles, its audioTracks and a drm block's licenseUrl (besides the person's own server).
One more field, liveStreamHosts, is read only with "apiVersion": 3 and only for plugins with the
channels capability: see Channels from any server. Live
items (apiVersion 2) and the En vivo tab (apiVersion 3) have their own page,
Live channels.
Paths in entry and icon: no leading ./¶
Write plugin.js, never ./plugin.js
entry and icon are paths relative to the manifest. Kino 0.9.45 and older refuse a leading
./: the install fails with El campo "entry" debe ser una ruta relativa a un archivo .js
(or the same for "icon"), and in the app it just looks like the plugin "does not install". An
AI-generated plugin wrote "./plugin.js" and failed for about 35 installs. Kino 0.9.46 and later
accept a leading ./ and drop it, but people on older versions still exist, so
always write "plugin.js" and "icon.png", with no ./ (a folder is fine: "src/plugin.js").
The kit's validate.mjs refuses it with: Quita el "./" del campo "entry" (por ejemplo
"plugin.js"): Kino 0.9.45 y anteriores no instalan el plugin con "./".
Playing from any server (streamHosts, apiVersion 4)¶
Some sources serve their video from CDNs whose domains you cannot list (they change, or sit on bare
TLDs, which a *.xyz entry can never cover). With "apiVersion": 4 a plugin may add:
"apiVersion": 4,
"streamHosts": "any"
"any" is the only value and no capability is needed; an older manifest ignores the field. It lets
what the plugin plays be on any public host, over http or https:
- a movie or an episode: exactly the rule of the
broad video permission -- the same rule, asked for by you up front
instead of granted by the person. In the player, the
urlresolvereturns, everything its manifest names, every redirect hop, and thesubtitlesandaudioTracksyou return may be on any public host, and no video host is ever asked about. A download of that movie or episode follows the same rule; - a live channel: the rule of
liveStreamHosts: "any"(the stream, its manifest and redirects; yoursubtitlesandaudioTracksstay on yourhosts).
It changes nothing else: kino.fetch (and so every sealed secret), images and DRM
license servers stay on your declared hosts, and local or private addresses (and public names that
resolve into the home network) are still refused. The consent screen shows it in red ("Puede
reproducir video desde cualquier servidor que indique"), and an update that adds it waits for the
person to approve again. Prefer listing the real domains when you can: people trust a narrow list
more.
Reaching any server (fetchHosts, apiVersion 9)¶
Some scrapers cannot list their hosts: the site moves to a new domain every so often, or an extractor redirects to a different CDN for each video. From Kino 0.9.55 a plugin written by hand may ask for:
"apiVersion": 9,
"fetchHosts": "any"
Then your kino.fetch (every redirect hop included, and its cookie jar) may reach hosts you did not
declare, without a question per host, under these rules (the Nuvio scrapers Kino converts have had it
for longer):
- The person approves it. The consent screen shows it in red ("Puede conectarse a cualquier servidor
público de internet (solo https, nunca tu red local)"), and an update that adds it waits for the person to
approve again. Without that approval,
kino.fetchstays on yourhosts. - Only
https, on port 443, and only to a dotted name or a public IPv4 address. This applies to a host reached only through this grant (not in yourhosts, not a server the person typed), on every redirect hop. Anhttp://URL, another port or a single-label name (router,nas) fails withhost_not_allowed(ande.hostsays which). From the Kino version after 0.9.72, a redirect that nameshttp://on the default port is followed overhttps://instead: nothing is ever sent in the clear; any other port is refused. - A request budget. Those requests (every hop that goes out) spend a budget Kino keeps per plugin for the
whole app: at most 60 a minute to one site (a domain and its subdomains count together) and 600 every 10
minutes in all (250 and 2,500 for a plugin converted from Nuvio), refilled continuously. Over it, the request
fails at once with
rate_limited. The 60 requests per call ofkino.fetchstill apply. - Your declared
hostsand the servers the person typed keep their own rules (aninsecureHttphost still takeshttp, a declared one any port) and spend no budget. Declare your primary sites: it is faster, it does not depend on the budget, and people trust a short list more. - Never the home network. Local or private addresses (
localhost,192.168.x.x,10.x.x.x,.local…) and public names that resolve into the home network stay refused withhost_not_allowed, on a redirect hop too. An IPv6 address written as such ([2001:db8::1]) is always refused, local or public: use a name. - Sealed secrets do not change: a request carrying a sealed value only goes to the
hostsyou declared, overhttps, on every hop. - Hidden pages. If you also declared
"browser", the start address of whatkino.browser.captureandkino.browser.pageopen, and every later top-level navigation of the page (a redirect, alocation), follow one rule: a host you declared or the person typed keeps its own, and one reached only through this grant must behttps, port 443 and a dotted name or a public IPv4 address. The navigation may leave your hosts (embeds hop between hosts), and the first one that breaks the rule ends the capture or read withblocked. That is detection, not always prevention: when the device's WebView routes the page through Kino's proxy, a server redirect of the top page may contact its target once before the capture ends. What the page loads afterwards (frames, scripts, the video's CDN) stays free (any public host, never the home network) and spends no budget. What you play follows its own rules (streamHosts); images, DRM licenses and downloads do not change. kino.fetchAnyHostistruewhen the permission is active for this install (declared, at apiVersion 9, and approved),falseotherwise, andundefinedon an older Kino: use it to choose between going straight to the new host and keeping your own fallback. ThekinoAPI.
Below apiVersion 9 a plugin written by hand may declare the field (the manifest stays valid), but Kino
ignores it: the consent screen does not show it and kino.fetch stays on your hosts. And since Kino
0.9.54 and older refuse "apiVersion": 9, such a plugin needs Kino 0.9.55. If you can, list the real
domains: people trust a short list more.
Sealed secrets (apiVersion 4)¶
A plugin that ships a fixed key (an API token baked into a site's own client, a per-tenant secret its author owns) can seal it instead of writing it into the manifest as plain text:
node sdk/seal.mjs --repo owner/repo --name apiKey
(owner/repo/path for a plugin that lives in a subfolder.) --repo follows the same rules as the
address people install from: a trailing / and a .git are dropped, but a URL
(https://github.com/...) and an @ref are refused rather than guessed at. The value is read from a
hidden prompt or piped on stdin -- never as a command-line argument, which would land in shell
history. It must be 1 to 4,096 bytes (UTF-8) -- up to 8,192 with "apiVersion": 6; the tool prints one line, kino-sealed:v1:..., to paste
into the manifest:
"apiVersion": 4,
"secrets": { "apiKey": "kino-sealed:v1:AbC123..." }
- Up to 16 secrets; each name matches
^[A-Za-z][A-Za-z0-9_]{0,31}$.secretsneeds"apiVersion": 4; below that the field is ignored (the plugin installs with no secrets, andkino.secretthrows for every name), and a Kino too old for apiVersion 4 refuses the whole install with "Este plugin necesita una versión más nueva de Kino". - A seal is bound to the repository (and subfolder) you passed
seal.mjs, lowercased, never to a ref. At install and at every update Kino opens each seal once against the address the person is installing from, only to check it belongs there; each run of the plugin opens them again, in memory, for that run alone. A seal made for a different repository, path or name, or one that was corrupted, is refused with "Los datos sellados de este plugin no son para este repositorio o están dañados"; a build that cannot open seals at all refuses with "Este Kino no puede abrir datos sellados". - Only from the default branch, never an explicit
@ref. GitHub serves any commit reachable in a repository's fork network -- a fork's or a pull request's -- through the parent repository's own address, and not only for an obvious SHA: a short hex prefix or a git-describe ref resolves the same way. Soowner/repo@<anything>can be someone else's manifest, with their ownhosts, while the seal still readsowner/repo. A plugin with secrets installed or updated with any explicit@ref-- branch, tag, commit -- is refused with "Los datos sellados solo funcionan si instalas el plugin desde su rama principal, sin @rama", and a run at such an address gets no secrets. - A seal trusts the repository's name: if its owner is renamed or deleted and someone else registers that name, their repository opens your seals. Seal again for the new name, and rotate the value if the old one was worth protecting.
- Declaring any secret adds "Usa datos sellados por su autor" to the consent sheet; an update that brings secrets to a plugin that had none asks again, exactly like a new host. Adding, changing or removing a secret in a plugin that already declared some does not.
Typed cipher keys (apiVersion 6)¶
A sealed value used as the key of kino.crypto.encrypt/decrypt can be declared as a key, so Kino
reads its bytes with an encoding fixed in the manifest instead of whatever keyEncoding the code
passes. That is what lets a sealed key work for des-ede3-* too (an untyped sealed key stays AES-only):
node sdk/seal.mjs --repo owner/repo --name portalKey --use cipher-key --encoding hex
prints one JSON line to paste as the secret's value:
"apiVersion": 6,
"secrets": { "portalKey": { "seal": "kino-sealed:v1:...", "use": "cipher-key", "encoding": "hex" } }
usemust be"cipher-key";encodingis"hex"or"base64"; no other field is allowed.- The value must decode, under that encoding, to a 16, 24 or 32-byte key:
seal.mjsrefuses anything else, and Kino refuses the install with "El secreto "portalKey" debe ser una clave de 16, 24 o 32 bytes". kino.secret("portalKey")works as the wholekeyof anyencrypt/decrypt; thekeyEncodingyou pass is ignored. It is refused, with "a sealed value can't be used here", as an HMAC key, apbkdf2input, anywhere indata/iv/aad, and anywhere in akino.fetchrequest (the URL, header names or values, a text, JSON or form body): a typed key is forkino.cryptoonly and never goes on the wire.- Below apiVersion 6 an object here is not a seal: the manifest is refused.
- The SDK kit simulates all of this from the plain value in
.kino-secrets.json; the key's bytes, in hex (either case) or base64, are also redacted from anything a server sends back.
What this protects, and what it does not. This is obfuscation, not secrecy: the private key that
opens a seal ships inside every copy of Kino. Sealing a value keeps it out of your manifest and your
repository's history; it does not stop someone from pulling Kino apart and opening the seal
themselves, any more than it stops the site you call from seeing the plain value on its own end.
Don't bother sealing a value that is already public (a key already sitting in that site's own player
JavaScript gains nothing from being sealed in yours), and never seal the person's credentials:
those belong in a password setting.
Using it. kino.secret(name) answers a marker, not the value; Kino swaps
the marker for the real value only inside kino.fetch, toward your manifest's own hosts over
https, and redacts the value from everything that comes back to your code. The full rules
(where the marker is swapped, kino.crypto, redaction) are on The kino API;
testing with the Node kit is on Test it locally.
Settings¶
settings is a list of at most 12 entries that hold a value (plus, from apiVersion 6, at most 16 that
only show or do something: see The settings form). Each one becomes a field on the plugin's "Configurar"
screen (Ajustes ▸ Plugins), and your code reads its value with kino.config.get(key):
"settings": [
{ "key": "server", "label": "Servidor", "type": "url", "required": true, "hint": "http://192.168.1.10:8096" },
{ "key": "user", "label": "Usuario", "type": "text", "required": true },
{ "key": "password", "label": "Contraseña", "type": "password", "required": true },
{ "key": "quality", "label": "Calidad", "type": "select", "default": "hd",
"options": [{ "value": "hd", "label": "Alta" }, { "value": "sd", "label": "Normal" }] },
{ "key": "subs", "label": "Subtítulos", "type": "toggle", "default": true }
]
| type | value | can be required |
can have a default |
longest value |
|---|---|---|---|---|
text |
text | yes | yes | 500 characters |
url |
text | yes | no (use hint for an example) |
2,048 characters |
password |
text | yes | yes | 500 characters |
toggle |
true / false |
no (always has a value) | yes | — |
select |
one of the options values |
no (always has a value) | yes | — |
list |
a list of entries, each an object of the list's fields |
yes | no | — |
section |
none (apiVersion 6) | no (holds no value) | no | — |
status |
none (apiVersion 6) | no (holds no value) | no | — |
action |
none (apiVersion 6) | no (holds no value) | no | — |
qr |
none (apiVersion 13) | no (holds no value) | no | 512 characters |
link |
none (apiVersion 12) | no (holds no value) | no | — |
help |
none (apiVersion 12) | no (holds no value) | no | — |
A value that stays on one device ("sync": false, apiVersion 13, Kino 0.9.74). A password may say
"sync": false to stay on the device where the person typed it: for a value that only makes sense once, on one device,
such as a two-step verification password your plugin sends right away and then clears (clearSettings). It is never
sent to a paired device, a value another device sends never sets or clears it, and it is in no backup and no kit. A sync
provider's sync.provision may still name it as a one-shot secret, never as its
keySecret. A text may say "sync": false too (a phone number shown as typed, kept on the device), but never appears
in sync.provision. sync on any other type, or not a boolean, refuses the manifest; below apiVersion 13, and in a Kino without it, the key is ignored (the password
syncs as usual). The settings form.
linkandhelp(apiVersion 12, Kino 0.9.74) are configuration aids: a button that opens anhttpsaddress through the system and a button that opens your instructions in a modal. See Configuration aids.keymatches^[a-z][a-zA-Z0-9_]{0,31}$and is unique;labelis 1 to 40 characters;hint(the example under the field) at most 80.selectneedsoptions(1 to 20, each avalueand alabelof at most 40 characters); itsdefaultmust be one of the values. Atoggledefault istrueorfalse.list(apiVersion 4) is a list the person builds with an "Agregar" button: each entry is a text line with an "Editar" button, and the dialog to add or edit one shows the list'sfields(1 to 4, each with akey,label, atypeoftextorurl, and optionallyhintandrequired; nodefault).max(1 to 50, default 20) caps the entries.kino.config.get(key)returns an array of objects{ [field.key]: string }, trimmed, without all-blank entries; an empty list isundefined. Arequiredlist needs at least one entry. Theurlfields of the entries become hosts your plugin may reach, exactly like aurlsetting (sohostsmay be[]).{ "key": "sources", "label": "Direcciones", "type": "list", "max": 30, "fields": [ { "key": "url", "label": "Dirección", "type": "url", "required": true }, { "key": "category", "label": "Categoría", "type": "text" } ] }- A
urlsetting has nodefault: a server the person types becomes a host your plugin may reach, so only the person can choose it. A manifest with adefaulton aurlsetting is refused; put an example address inhintinstead. - A
requiredsetting with no value stops every call to your plugin before it runs: the plugin shows "Falta configurar", its Home rows are not asked for, and anything the person opens from it says "Configura <name> en Ajustes ▸ Plugins" with a button to that screen. - Passwords are stored encrypted on the device. Your code can read them (it has to send them), which is why the consent screen says "Este plugin usa tu usuario y contraseña". Kino never writes any setting to its log; do not do it yourself.
- Changing any setting closes your plugin's sandbox, deletes its cookies and its cached Home
rows, so the next call starts a new session with the new values.
kino.storageis not cleared: if you keep a token there, key it by the user and server it belongs to (the cookbook does). - Uninstalling deletes the settings, passwords included.
- From apiVersion 6 the form can also show a status, run action buttons and check values before saving, and settings travel between the person's devices: see The settings form.
The person's own servers¶
A url setting is how a plugin talks to a server that is not on the internet: a media server at
home, for instance. The server the person types becomes one more host your plugin may reach,
exactly as typed: its scheme (http is allowed here, because home servers rarely have a
certificate), host and port. Nothing else on that machine or network is allowed, redirects from it
may only go to the same server or to your declared hosts, and your stream and image URLs may point
at it. The consent screen warns "Se conectará a los servidores que escribas en su configuración", and
Ajustes lists what each plugin reaches ("Se conectará a: …").
A plugin whose only reach is that server (it never calls a site of its own) declares
"hosts": [] from "apiVersion": 2, as long as it has at least one url setting: the consent
screen then lists no host at all, only the line about the servers the person types, and Ajustes says
"Se conectará solo a los servidores que escribas en su configuración" until one is typed. An empty
hosts with no url setting is refused (El campo "hosts" solo puede estar vacío si el plugin
tiene un ajuste de tipo "url"), and on "apiVersion": 1 it is refused as always. (Kino never lists
a host under the reserved .invalid domain either, the placeholder older manifests used.)
Only the scheme, host and port count: any path on that server is reachable, and
kino.config.get returns the value as typed. Kino refuses, with a message under the field, a value
that is not an http/https URL, or whose host is localhost, a loopback address (127.0.0.1,
::1), a link-local one (169.254.x.x, fe80::) or 0.0.0.0. Addresses in the person's own network (192.168.x.x,
10.x.x.x, a .local name) are allowed: that is the point.
Declaring an insecure host (apiVersion 2)¶
A hosts entry can also be an object, for a site of yours that has no certificate:
"hosts": ["archive.org", { "host": "cdn.example.org", "insecureHttp": true }]
This needs "apiVersion": 2. insecureHttp: true is the only thing it can carry beyond host, and
it marks the only declared hosts (not the person's own server, above) allowed over plain http:
kino.fetch, a Stream's url, its subtitles, its audioTracks and a drm block's licenseUrl
all accept http://cdn.example.org/… once it is declared this way, and every redirect hop is judged
by the same rule. Every other declared host stays https-only, https keeps working on the insecure
one, and the host is matched exactly: sub.cdn.example.org is not covered. The same rules as a plain
string still apply (public DNS name, no *, no IP, nothing private/LAN; a name that resolves into
the person's own network is still refused) plus one more: no *. wildcard — an insecure host is
named exactly. The consent screen shows it in red, "Conexión sin cifrar con cdn.example.org", and an
update that newly marks a host this way waits for approval like a brand new host would. See
A site of yours without a certificate.
Downloads (apiVersion 2)¶
Declare "download" in capabilities (with "apiVersion": 2) and Kino offers your titles for
offline viewing: "Descargar" on the info page and "Guardar en el dispositivo" in the library, on
phones (Kino never downloads on a TV). Nothing extra to export. When the person saves a title, Kino
calls your resolve(ref) when the download actually runs, exactly as playing would, and saves the
Stream as one file, with your headers on every request, through the same host gate as the player
for that stream: https on your hosts or the person's own server -- or any public host when your
manifest has streamHosts: "any" or the person gave your plugin the
broad video permission -- every redirect hop checked, never the home
network. A download never asks about a host. A server the gate refuses ends the download for good
(no "Reintentar": it is not network trouble), with a sentence that names the server; when it is one
that playing would have asked about, the sentence says to play the title once to approve it, and
after that a new download works.
Your subtitles are saved next to it. audioTracks are not saved: the offline copy has
only the audio inside the video file, so a source that dubs through separate tracks is heard in its
main audio when offline.
What downloads, and what does not:
- A progressive file (
mp4,mkv,webm,ts, …) downloads. The saved file takes its extension from yourmimewhen you give one, else from the URL, elsemp4; the player sniffs the bytes anyway. - An HLS VOD stream (
.m3u8, anmpegurlmime, or a response that turns out to be a playlist) downloads too, saved as one file: MPEG-TS segments become a.ts, fMP4 ones (EXT-X-MAP) an.mp4. From a master playlist Kino takes the highest variant up to 1080p whose audio is inside the video; AES-128 keys and byte ranges are handled, and yourheadersgo on the playlists, the key and every segment. At anEXT-X-DISCONTINUITYthe segments are kept as they are (the timestamps restart there and the player follows; seeking right at the splice may land a little off), unless the video or audio format changes at it (e.g. H.264 → HEVC, a track added or gone): that is refused like below. Metadata streams (ID3, SCTE-35, private data) don't count as a change, and the same formats arriving under other stream numbers (PIDs) after the splice are written back under the first segment's ones, so the saved.tsplays to the end. A retry resumes at the first missing segment when it gets the same content (same variant, same first bytes), even from another CDN; different content starts over. - Audio (Kino 0.9.54, apiVersion 8
musicandpodcastitems): progressive audio files and audio-only HLS download too, and a downloaded album plays offline in the audio player. - What cannot be saved ends as "Este contenido no se puede descargar" ("Este video no se puede
descargar" up to Kino 0.9.53), a final state with no
"Reintentar" (it would refuse the same way) that the person can only remove, and the partial file
is deleted: a DASH or Smooth manifest (
.mpd,application/dash+xml, …), a live HLS playlist (noEXT-X-ENDLIST), SAMPLE-AES or any DRM key, a key that is not 16 bytes or does not decrypt, an empty segment (asked for 3 times first), a master whose every video variant needs a separate audio rendition (Kino does not save a silent video), a DRM-protected stream and a live channel (a live channel never even shows a download button, also in a plugin that declares bothchannelsanddownload). Subtitle renditions inside the playlist are not saved (yoursubtitlesare). There is no separate "resolve for download" call: if your source offers DASH and also a file or HLS, prefer those, or accept that those titles play but do not download. - The queue downloads one title at a time, so a
refmay wait a while beforeresolveis called: keep something stable in it and look the fresh link up insideresolve(as recommended in The contract). A retry resumes the partial file even when your URL changed. Aresolvethe queue makes that times out fails that download only: it does not count toward the three timeouts in a row that switch your plugin off ("No responde"), which only calls made for the person on screen do. - A plugin that is disabled, waiting for its settings, or uninstalled downloads nothing: its titles show no download button, and a title already queued fails with "Este plugin ya no puede descargar videos". Files already downloaded keep playing offline and stay removable in Descargas, whatever happens to the plugin afterwards.
Declaring download shows "Puede descargar videos para verlos sin conexión" on the consent sheet,
and an update that newly declares it waits for the person's approval (Publishing).