The contract (apiVersion 1 to 27)¶
Your entry file is one ES module that exports one async function for each capability you
declared, and nothing is called that you did not declare:
export async function search(query) { /* -> Item[] or Page */ }
export async function home() { /* -> Row[] */ }
export async function browse(ref, cursor) { /* -> Page */ }
export async function episodes(ref) { /* -> { series?: SeriesInfo, episodes: Episode[], seasons?: Season[] } */ }
export async function resolve(ref) { /* -> Stream */ }
export async function prepare(ref) { /* answer ignored: warm what resolve(ref) will need (optional, any apiVersion, Kino 0.9.88) */ }
export async function details(ref) { /* -> SeriesInfo or null (apiVersion 8, Kino 0.9.54) */ }
export async function liveCategories() { /* -> Array<LiveCategory | Playlist> or Playlist */ }
export async function liveChannels({ categoryId, cursor }) { /* -> { items: LiveChannel[], next? } */ }
export async function guide({ channelIds, from, to }) { /* -> GuideEntry[] */ }
export async function liveSearch({ query }) { /* -> { items: LiveChannel[] } */ }
export async function subtitles({ imdbId, tmdbId, kind, season, episode, title, year, languages, file }) { /* -> { lang, url, format?, label?, translated? }[] */ }
export async function track(event) { /* -> { ok: true } or { skipped: true }, or throw kino.error(code) (apiVersion 7) */ }
export async function segments(query) { /* -> { type, startMs, endMs }[] (apiVersion 7) */ }
export async function lyrics(query) { /* -> { synced?, plain?, label?, instrumental?, matchDurationMs? } or null (apiVersion 19) */ }
From "apiVersion": 6 (Kino 0.9.50) there are more optional exports, each with its own page:
sign (Signing every request), migrate (Moving saved titles),
section and categories (Section, categories and colors), and settingsStatus,
action and validateSettings (The settings form), and meta
(Describing other titles). subtitles (Subtitles for any title) needs no new
apiVersion. From "apiVersion": 7 (Kino 0.9.51): track (Telling a tracker what the person
watches) and segments (Where the intro and credits are). From
"apiVersion": 8 (Kino 0.9.54): the audio item kinds music and podcast
(Music and podcasts) and the optional details export (A title's own
details). And at every apiVersion, from Kino 0.9.54, a plugin that lists titles but plays
none can say so with "catalogOnly": true (Catalog-only plugins). From
"apiVersion": 12 (Kino 0.9.74) a plugin can be the transport of the person's cross-device sync with
syncPull, syncPush and the optional syncStatus (Being the person's sync transport).
At every apiVersion, from Kino 0.9.74, an action may also answer setSettings and link
(The settings form). From "apiVersion": 13 (Kino 0.9.74):
read for a stream your plugin serves and image for a picture it serves (Bytes and images your plugin
serves). From "apiVersion": 14 (Kino 0.9.74): screen and screenEvent for a
screen and job for a background job; a plugin with
playerPanelTab uses the panel export (The player panel). And at every
apiVersion, from Kino 0.9.88, a plugin with resolve may export prepare (Warming up before the play) or
declare "resolveAhead": true (Getting a title ready ahead).
export async function read({ handle, offset, length }) { /* -> { bytes: base64 } (apiVersion 13, byteSource) */ }
export async function image({ handle }) { /* -> { bytes: base64, mime } (apiVersion 13, imageSource) */ }
export async function screen(ctx) { /* -> a tree of nodes (apiVersion 14, screen) */ }
export async function screenEvent(ev) { /* -> { state, toast, go, ui, config... } or null (apiVersion 14, screen) */ }
export async function job(ctx) { /* answer ignored (apiVersion 14, schedule) */ }
export async function storeSync({ reason, since, state }) { /* -> { full, entries, removed?, state? } (apiVersion 15, pluginStore) */ }
export async function storeList({ category, sort, cursor }) { /* -> { entries, next? } (apiVersion 15, a live store) */ }
export async function storeSearch({ q, category, cursor }) { /* -> { entries, next? } (apiVersion 15, a live store) */ }
From "apiVersion": 15 (Kino 0.9.77): storeSync, and storeList and storeSearch in a live
store, for a plugin that is a source of plugins (Plugin stores). identity and notifications are
declarative and export nothing (Identity, Notices in the bell); from "apiVersion": 16,
coins exports nothing either (kino.coins).
(kino.d.ts has the same shapes as TypeScript declarations.)
Use named exports (export async function ...). Data crosses into and out of your code as JSON, so
return plain data: strings, numbers, booleans, arrays and objects.
The live-channel functions (liveCategories, liveChannels, and the optional guide and
liveSearch, apiVersion 3) have their arguments and rules on Live channels.
Arguments¶
search(query)gets{ q, type, season, episode, tmdbId, year, originalTitle, altTitles, cursor }:qis the text the person typed (it can be empty; return[]).typeis"movie"or"series"(or, apiVersion 8,"music"or"podcast") when Kino leans towards that kind, and"any"otherwise. It is a hint, not a filter: Kino derives it from TMDB's movie/tv split, which rarely lines up with a source's own catalogue, and a title can exist as both. Return every plausible match; usetypeat most to put the kind it names first.seasonandepisodeare0unless Kino is looking for a specific episode;tmdbIdandyearare0when unknown.originalTitleis TMDB's original title when it differs fromq(else""), andaltTitlesup to 5 other titles Kino knows for the work (each at most 200 characters): try them whenqfinds nothing on a source that names things in another language.cursorisnull, except when the person asked for more results and your previous page said where to continue (seePagebelow).within(apiVersion 6, only for a plugin that declaresscopedSearch) is present when the person searches inside one of your "Ver más" pages: see Searching inside a "Ver más" page.
home()getsnull.browse(ref, cursor)gets therefof one of your Home rows (or arefa previous page gave), andcursornullfor the first page or thenextof the page before.episodes(ref)gets therefof aseriesitem, as you returned it, or (apiVersion 8) therefof amusicorpodcastitem, for its tracks or episodes.details(ref)(apiVersion 8, Kino 0.9.54) gets therefof amovieitem when its page opens: see A title's own details.resolve(ref, options)gets therefof amovieitem, therefof an episode, (apiVersion 2) therefof aliveitem, or (apiVersion 8) therefof amusicorpodcastitem from a plugin withoutepisodes.optionsisundefinedon a normal call; only an apiVersion 6 plugin with a request-signed stream ever gets it, as{ retry }. From apiVersion 6 it also gets therefof one of your lazy copies, when that copy is needed.subtitles(arg)gets{ imdbId?, tmdbId?, kind, season?, episode?, title?, year?, languages, file? }(see Subtitles for any title) and returns an array shaped like aStream'ssubtitles, each entry with an optionallabelandtranslated.
What you return¶
Item = { id: string, ref: string, title: string, kind: "movie" | "series" | "live" | "music" | "podcast",
year?: string, poster?: string, backdrop?: string, overview?: string,
lang?: string, quality?: string, originalTitle?: string,
genres?: string[], rating?: number, runtimeMinutes?: number,
ids?: { tmdb?: number, imdb?: string }, badges?: string[], adult?: boolean,
artist?: string } // music, podcast, artist: apiVersion 8 (Kino 0.9.54)
Row = { id: string, title: string, items: Item[], ref?: string, genre?: Genre }
Genre = "peliculas" | "series" | "anime" | "infantil" | "documentales" | "deportes" | "noticias" | "musica" | "entretenimiento" | "otros"
Page = { items: Item[], next?: string }
SeriesInfo = { title?: string, poster?: string, backdrop?: string, overview?: string,
ids?: { tmdb?: number, imdb?: string, mal?: number, anilist?: number, kitsu?: number },
genres?: string[], year?: string,
rating?: number, runtimeMinutes?: number } // rating, runtimeMinutes, ids.mal/anilist/kitsu: Kino 0.9.54
Episode = { season: number, number: number, ref: string, title?: string,
still?: string, overview?: string, airDate?: string, runtimeMinutes?: number }
Season = { id: string, ref: string, title: string, number?: number, current?: boolean }
Stream = { url: string, mime?: string, headers?: Record<string, string>,
subtitles?: { lang: string, url: string, format?: "vtt" | "srt" }[],
audioTracks?: { lang: string, url: string, label?: string }[],
durationMs?: number, expiresInSeconds?: number,
drm?: { type: "widevine", licenseUrl: string, licenseHeaders?: Record<string, string> },
label?: string, // apiVersion 6
alternatives?: ({ url: string, mime?: string, headers?: Record<string, string>, label?: string }
| { ref: string, label?: string }
| { external: External, label?: string })[], // label and { ref }: apiVersion 6; { external }: 11
skip?: { openingStartMs?: number, openingEndMs?: number, endingStartMs?: number },
signing?: "request", signContext?: string, alternateHosts?: string[], // the last three: apiVersion 6
external?: External, // apiVersion 11: instead of url
media?: Media, // Kino 0.9.66: what you know about the file
portable?: { url: string, mime?: "application/x-mpegURL" } } // Kino 0.9.66: a universal HLS copy
External = { protocol: string, ref: string, resolver?: string }
Media = { title?: string, sizeBytes?: number, container?: string,
video?: { codec?: string, profile?: string, width?: number, height?: number, fps?: number, bitDepth?: number, hdr?: boolean },
audio?: { codec?: string, channels?: number, language?: string, title?: string, default?: boolean }[],
subtitles?: { codec?: string, language?: string, title?: string, text?: boolean }[],
converted?: boolean, notes?: string[] }
Genre (Categorías and the En vivo filter). A Home Row, a live LiveCategory and a playlist may carry an optional genre. On a LiveCategory and a playlist it is a closed list of ten ids: peliculas, series, anime, infantil, documentales, deportes, noticias, musica, entretenimiento, otros (Kino shows their Spanish names). On a Home Row it accepts any category: a known id or alias (Spanish or English) maps to the base id, and anything else is kept as a slug (lowercase ASCII [a-z0-9-], at most 40 characters) and appended after the known ones; see Home categories. It lets Kino line up categories from different plugins: the Categorías tab groups the browsable Home rows (those with a ref, when you declare browse) of every plugin by genre, and En vivo can narrow its categories by genre. On a live category or a playlist, a value outside the list is ignored, never an error, and without a genre Kino guesses from the title of the row or group ("Deportes", "Noticias Colombia", "Kids"…), so set it when your titles do not say it. On a playlist the genre is the default for the groups of the list (each group's own title is guessed first). The older Categorías tab still uses only the ten ids: a row with genre: "accion" or a new slug gets its tile guessed from its title. Kino versions before this field ignore it.
How the pieces connect¶
A movie item's ref goes to resolve. A series item's ref goes to
episodes, and each episode's ref goes to resolve. A live item's ref (apiVersion 2, see
Live channels) goes to resolve too, and its Stream plays as live. A
music or podcast item's ref (apiVersion 8) goes to episodes when you declare it (its tracks
or episodes, each ref to resolve), else straight to resolve (see
Music and podcasts). A row's ref goes to browse, and so does each page's
next. A movie's ref also goes to details when you export it (apiVersion 8, below).
Seasons¶
Two shapes, and your episodes answer says which. When every season of a show is in
one list, give each episode its season and leave seasons out: Kino reads the seasons from the
episodes and shows a selector that only filters the list. When your source keeps each season as its
own series item (its own id and ref, as a search would list it), return only that season's
episodes and list every season of the show in seasons, the one you are answering for included:
{ id, ref, title, number?, current? }, with title what the selector shows ("Temporada 2") and
current: true on the season being listed (Kino also recognizes it by id). Kino shows the seasons
as chips; choosing another one calls episodes with that season's ref and opens it as that title,
with its own progress in the library. seasons is optional and new in this revision of apiVersion 1:
a plugin that never returns it keeps working exactly as before.
Paging ("Ver más")¶
If you declare browse, a Home row with a ref gets a "Ver más" card that
opens a grid: Kino calls browse(ref, null), then browse(ref, next) while the person scrolls and
you keep returning a next. search may also return a Page; its next puts "Ver más resultados
de <name>" under your results, and Kino calls search again with the same query and cursor: next.
A next (and a row's ref) is only kept when you declare browse; without it Kino drops them with a
line in the log. Cursors are opaque to Kino: a page number, an offset, a URL, at most 2048
characters.
A title's own details (details, apiVersion 8, Kino 0.9.54)¶
A search or Home item often carries only a name and a poster. The title page shows whatever the item
carries (overview, backdrop, genres, year, rating, runtimeMinutes) and, for a series, what
episodes(ref).series adds. For a movie there is no episodes call, so you may export
details(ref): it gets the movie item's ref and answers one SeriesInfo object (or null: nothing to
add).
export async function details(ref) {
const page = await loadPage(ref); // your own helper, ideally cached per ref
return { overview: page.plot, backdrop: page.fanart, genres: page.tags, year: String(page.year),
rating: page.score, runtimeMinutes: page.minutes };
}
- From
apiVersion8,detailsis a reserved export name: export a function by that name only with this meaning (a helper of yours calleddetailsmust be renamed or left unexported). There is no capability to declare: Kino calls it only if your plugin exports it and declaresapiVersion8 or more, so an older Kino never calls it, and an older plugin's own helper nameddetailsis never called either. - Kino calls it when the page opens, alongside its TMDB lookup (never in front of it), with a 20 s
limit (
timeoutsMs.details). It may usekino.browser.pagelikeepisodes. - When the item carried no
ids, theidsof your answer pin the movie on TMDB. Besidestmdbandimdb,ids(indetailsand inepisodes().series) may carry an anime'smal,anilistandkitsu(Kino 0.9.54): AniList and the person'smetaplugins are then asked by them. ratingis 0 to 10 (like an item's);runtimeMinutesis the movie's length (a series'runtimeMinutesis ignored: it is per episode).episodes(ref).seriestakesratingandruntimeMinutestoo from Kino 0.9.54; older versions ignore them.- If your
resolveneeds the same pagedetailsread, keep it in a small cache in your module: the person usually presses play right after the page opens.
The page is built from every answer with one fixed order per field, whatever order the answers arrive in:
| Field | First → last |
|---|---|
| synopsis, year, genres | TMDB → your item → details → AniList → meta plugins |
| poster, backdrop | your item → details → AniList → meta plugins |
| score | TMDB → your item → details (a series page too: TMDB → your item → episodes().series) |
| runtime | TMDB → meta plugins → your item → details |
| cast; tagline, directors, certification | TMDB (cast then meta plugins) |
| logo, other sites' ratings | your item → meta plugins |
While details has not answered (up to its limit), AniList's and the meta plugins' synopsis, year,
genres and art wait for it, since it outranks them; everything else shows at once.
Searching inside a "Ver más" page (scopedSearch, apiVersion 6)¶
Every "Ver más" page (a Home row, a row of your section, one of your Categorías) has
a search field at the top ("Buscar en esta categoría"). For every plugin, Kino filters the titles already
loaded on that page by name (accents and case aside, every word anywhere in the title); with fewer than
24 matches it keeps loading the next pages of the same ref ("Buscando en más páginas…"), at most 10
pages or 300 titles per round, and the person may ask for another round. A new query cancels the
running one.
Declare "scopedSearch" in capabilities (apiVersion 6, together with search; nothing more to
export, no consent line) to answer that search yourself, e.g. with your backend's search restricted to
that category. Without search the manifest is refused with "La capacidad \"scopedSearch\" necesita
también \"search\"". Kino then calls your search with the usual query plus within, the page's browse
ref exactly as you gave it:
export async function search(query) {
if (query.within) {
const category = categoryOf(query.within); // your own ref
if (!category) return null; // "can't search there": Kino filters the page itself
return searchCategory(category, query.q, query.cursor); // Item[] or Page, paged by your `next`
}
/* the plain search */
}
type is always "any" there, and season, episode, tmdbId and year are 0. The answer is
checked like any search answer (the same caps, adult titles only while the 18+ code is unlocked), and
a Page's next pages it as the person scrolls. Kino falls back to its own filter when you answer
null, throw, or have not answered after 6 s (the page then searches its own titles and drops your late
answer; your call keeps the search limit of 15 s); a failure reaches the error board like any failed
call, never with the query or the ref. Answering null is not a failure. sdk/validate.mjs warns when
you declare scopedSearch and your entry never reads within; try it with
node sdk/run.mjs --within '<ref>' ./plugin.js search "texto".
id is stable, ref may change¶
id is the identity of a title: the person's library,
progress and "Continuar viendo" hang off it, so it must be the same every time the same title comes
back, in every search and on every Home refresh. ref is opaque to Kino: it is just what your
episodes/resolve need to find the title again. It may differ from one call to the next (sources
re-issue links), and Kino can hand you a ref you returned earlier, for example the one saved with a
title in the person's library. So make refs that keep working; if your source's links expire, put
something stable in the ref (an id) and look the fresh link up inside resolve.
Kino is strict, and forgiving with lists¶
Every list is checked entry by entry: a bad entry is
dropped (with a line in the log) and the rest survive; anything over a cap is cut. A Stream is
all or nothing.
| Thing | Rules |
|---|---|
search result |
At most 100 items (an Item[], or a Page). A live item whose name has nothing to do with the query is dropped: it stays only when its name carries at least 60% of the words of 3 or more letters of some form of the query (what was typed, originalTitle or one of altTitles), accents and case ignored -- the rule of kino.rank.filterRelevant. Movies and series are never judged this way (they may rightly carry another title), and a query with no such word drops nothing. So don't answer a search with your whole channel list when nothing matches. |
browse result |
A Page of at most 100 items. |
home result |
At most 20 rows of at most 60 items each. A row needs a unique id (same pattern as an item id) and a non-blank title; rows with no valid items are dropped. Kino shows them after its own rows, labelled with your plugin's name, and caches them for 6 hours (stale rows show while it refreshes; an answer with no valid rows, or over 2 MB, is not cached and is asked again next time). If home() fails you contribute no rows and Home is not blocked. |
episodes result |
At most 5000 episodes. number is required and from 1 to 99999 (an episode numbered 0, such as a special, is dropped). season should be from 1 to 999; a missing or out-of-range season becomes 1. ref is required. A repeated season and number is dropped. Without a title, Kino shows "Capítulo N". |
seasons (in the episodes result) |
Optional; at most 50. Each needs an id (same pattern as an item id; a repeated one is dropped), a non-empty ref of at most 4096 characters and a non-blank title (up to 200 characters), or it is dropped. number from 1 to 999 and current a boolean; a wrong one is ignored, not the season. Anything that is not a list is ignored. |
id |
^[A-Za-z0-9._~-]{1,128}$. Anything else drops the item, so if your source's own ids have other characters (spaces, /, :, %), derive a stable id yourself, such as a slug. Repeated ids in one list are dropped. |
ref |
A non-empty string of at most 4096 characters. |
kind |
"movie", "series", (apiVersion 2) "live" or (apiVersion 8) "music" or "podcast"; a live item stays in a home row only from apiVersion 6 (below it, it is dropped from Home: see Channels in your Home rows). A series item from a plugin that does not declare episodes is dropped: it could never be opened; a live item from an apiVersion 1 plugin is dropped too (see Live channels), and a music or podcast item from a plugin below apiVersion 8 (see Music and podcasts), which needs no episodes. |
| Text fields | title is required and non-blank, up to 200 characters. overview up to 2000; lang and quality up to 20 (for example "es", "1080p"); year up to 10 (a number is accepted and converted). Longer text is cut; the text of SeriesInfo and Episode is cut the same way (200 characters for titles, 2000 for overviews). |
| Extra item fields | All optional; a wrong one is ignored, not the item. genres at most 5, each at most 30 characters; badges (shown as chips, e.g. "HD", "Latino") at most 3 of at most 20; rating from 0 to 10; runtimeMinutes from 1 to 1000; ids.tmdb a positive integer (Kino uses it to match your title with TMDB, to find it again from search, and to enrich its info page -- see below); ids.imdb matches ^tt\d{5,10}$ (also enriches a movie's info page when you have no ids.tmdb). An episode's airDate is YYYY-MM-DD. |
adult |
From apiVersion 6, adult: true marks an 18+ entry: Kino shows it only while the person's 18+ code is unlocked on that device (Ajustes ▸ Control parental), and hides it again when they lock it; below apiVersion 6 it is dropped. It applies on Home, in search, "Ver más", your section and Categorías. See 18+ content. |
| Images | poster, backdrop and still must be http or https URLs of at most 2048 characters, or they are ignored (Kino versions before the one that accepted http for images ignore the http ones). Images are loaded by Kino directly and are not checked against hosts (they are display only), and Kino does not send your headers or cookies with them. This is the one exception to the host rule, with one limit: an image on the home network, a private or reserved IP address, or a local name (localhost, .local, .lan, …) is ignored too, and so is a name without a dot over http (router, nas), unless it is on a server the person typed in your settings. A public IPv4 address is fine. From apiVersion 13 (Kino 0.9.74) a plugin that declares imageSource may answer, instead of a URL, an image reference { "source": "plugin", "handle": "…" } in poster, backdrop, still and a section hero's image: Kino then asks its image export for the bytes (Images from the plugin); from any other plugin, or anywhere else, a reference is ignored. No data URIs: a string is always a URL. |
ids.tmdb enriches the info page, not only matching¶
When TMDB has this exact title (matched by
ids.tmdb, or by ids.imdb on a movie when you gave no ids.tmdb), opening it adds three kinds of
field, each filled in differently:
- Only TMDB has these, so they always come from it: a tagline, the director or (for a series) creator, the cast and the age rating.
- TMDB wins whenever it has an answer; yours is only the fallback for what TMDB left blank: the year and the genres. A title with its own year or genres still shows TMDB's once matched, not its own.
- Yours wins when you gave one; TMDB only fills the gap: the synopsis (only replaced if yours was empty), the rating (only if you left it out), and a movie's runtime (only if you left it unset -- a series' runtime is never touched either way, TMDB's included; it prints per episode, not for the whole show).
It does not add a poster, a backdrop or seasons from TMDB -- those stay exactly what your
Item/SeriesInfo/episodes answer gave, or blank if you left them out.
Kino 0.9.54 changes the third group. From 0.9.54 TMDB comes first for the synopsis, the year, the
genres, the score and a movie's runtime too, on movie and series pages alike: your own values are the
fallback for what TMDB left blank. The full order per field, with the new details export, AniList and
meta plugins, is in A title's own details. Music and podcast titles are never matched with
TMDB.
The Stream rules¶
From apiVersion 13 (Kino 0.9.74), a plugin that declares byteSource may answer instead a stream with no URL,
{ source: "plugin", handle, size, mime }, whose bytes Kino asks your read export for; the rules below about url
do not apply to it, and its own rules are in Sockets and plugin-served bytes.
urlmust behttpsand its host must be one of yourhosts, and so must the host of every subtitle URL, or it must be on a server the person typed in your settings (exactly that scheme, host and port). The one other way to plainhttpis a host you declared{ "host": "…", "insecureHttp": true }(apiVersion 2, see the manifest): that host, exactly, acceptshttpfor the stream, its subtitles, its audio tracks and its license. A stream that breaks this is refused as a whole; a bad subtitle is dropped and the stream still plays. Two things relax this for a movie or an episode: a manifest withstreamHosts: "any"and the person's broad video permission; and a host you forgot may be asked about instead of refused.mimeis optional, of the formvideo/mp4(anything else refuses the stream). When it is missing Kino's player detects HLS, DASH or a plain file from the URL and the content.- Everything the player fetches for the stream follows the
kino.fetchhost rules. That covers theurlitself, the variants, segments and#EXT-X-KEYkeys an HLS manifest names, theBaseURLs of a DASH manifest, the subtitles, and every redirect hop of any of them: each must behttpson one of yourhosts(orhttpon one you declaredinsecureHttp), never an IP address or a local name, and a declared name that resolves inside the person's own network is refused. A request that breaks this fails before it leaves the device and playback stops with an error, so a manifest that points at another CDN needs that CDN inhosts. headersare sent with every one of those player requests (the stream, its manifest's segments and keys, its subtitles, and redirect hops, all on yourhosts) and, if you declaredownload, with every request that saves the stream to the device (for HLS: the playlists, the key and every segment) — and nowhere else. At most 20; names are letters, digits and hyphens; values are at most 4096 characters with no line breaks;Host,Content-Length,Transfer-EncodingandConnectionare ignored.subtitles: at most 30, each{ lang, url, format? }.langis a short language code such as"es"(up to 20 characters; blank becomes"und"),formatis"vtt"or"srt".-
audioTracks: at most 8, each{ lang, url, label? }-- a dub or an alternate mix your source serves as its own file, separate from the video. Checked exactly like a subtitle:urlmust behttpson a declared host, or the person's own server exactly as typed; a bad entry is dropped and the rest of the stream still plays, and so is aurlalready listed (the first entry wins).langup to 16 characters (blank becomes"und");label, up to 40 characters, is shown in the audio menu verbatim when given, instead of a name guessed fromlang. Kino merges each one into the video and offers it, auto-picked by the person's audio preference, in the same menu as the container's own embedded tracks. A stream with noaudioTracksplays exactly as it always has. Example, a source that dubs into two languages:return { url: videoUrl, audioTracks: [ { lang: "es-419", url: dubUrl("es"), label: "Español (Latinoamérica)" }, { lang: "en", url: dubUrl("en") }, ], }; -
alternatives(at most 8, each{ url, mime?, headers? }): other copies of the same video, best first. Whenurlcannot play on the device (a codec it has no decoder for, a broken or unsupported file) or is gone (404, 403), Kino moves on to the next alternative by itself, at the same spot, and only shows an error once none is left. A lost network is not a reason to move on: that is retried as usual. Each entry is checked exactly likeurl,mimeandheaders; a bad one is dropped and the rest still count. They share the stream'ssubtitlesandaudioTracks. Ignored next todrm, withsigning(alternateHostsis a signed stream's failover) and for a live channel. Return them when your source offers several files of one title (other servers, resolutions, encodes): a device that cannot decode the first one still gets to watch. Every alternative must be the same video in the same language (same dub, same subtitles burned in or not): Kino switches between them by itself, so a dubbed copy listed next to the original would change the language under the person. Offer another language as another stream (another search result or episode source), never as an alternative. From Kino 0.9.54, after repeated stalls Kino also moves once, by itself, to a clearly lighter copy (at most three quarters of the height on screen) when the labels say so: name the resolution in the label ("Streamwish · 720p","4K","Full HD"); a bareHDorSDis never enough for that. From apiVersion 6 an alternative may carry alabel, or be a lazy{ label, ref }resolved only when needed: see Labelled and lazy copies. label(apiVersion 6): the Stream's own short name, and each alternative may carry one too -- e.g."Latino · Servidor 1". Trimmed; at most 48 characters, no control characters, or it is dropped (the copy still plays). When a Stream has two or more copies the player shows them all, by label, in a Servidor section at the top of its "Audio y subtítulos" menu (phone and TV, reachable with the D-pad), where the person can switch at any moment and keep watching from the same spot; a copy without a label shows as "Opción 2", "Opción 3"… Labels also go to the plugin's log, with the host only (never a URL or a token).signing,signContextandalternateHosts(apiVersion 6): an HLS stream that needs a fresh signature on every request. They have their own page: Signing every request.durationMsis optional, in milliseconds.-
skipis optional: where THIS file's opening and ending are, in milliseconds from its start --{ openingStartMs?, openingEndMs?, endingStartMs? }. Kino shows its "Saltar intro" button fromopeningStartMs(0 when left out ornull) toopeningEndMs, and "Saltar outro" (to the next episode) fromendingStartMs. Every value must be a finite number between 0 anddurationMs(or 24 h when you give nodurationMs); the opening needs itsopeningEndMs, after its start;endingStartMsmust not be before the opening's end. A bad part is dropped and the rest still count; a badskipnever stops the stream. Send times for the exact file you return: a different cut of the same episode has its opening somewhere else. Kino keeps them as the episode's markers, also for a downloaded copy, and they sync to the person's other device. A correction the person makes by hand always wins over yours; yours win over the community times Kino looks up on its own for anime (AniSkip), which is not asked at all when you sendskip. Ignored for a live channel. Older Kino versions ignore the field.return { url: videoUrl, durationMs: 1_420_000, skip: { openingStartMs: 62_000, openingEndMs: 152_000, endingStartMs: 1_290_000 } }; -
expiresInSeconds(30 to 86400) says when your URL may stop working. If playback fails after that long, Kino callsresolveonce more and continues where the person was. media(optional, Kino 0.9.66; older Kino ignores it) says what you know about the file itself: itstitle,sizeBytesandcontainer, itsvideo(codec,profile,width,height,fps,bitDepth,hdr), itsaudioandsubtitlestracks (codec,language,title, anddefault/text), whether youconvertedit for playback and shortnotes. It is advisory: Kino shows and logs it and may use it as a hint (for a cast), but never trusts it for anything that could harm the person. Every field is optional and cleaned: text is one line (control characters dropped, whitespace collapsed) cut at 120 characters (codec/container40,language20), numbers are clamped (width/heightto 16384,fpsto 480,bitDepthto 16,channelsto 32,sizeBytesto 2^50), at most 16 tracks and 4notes; an object with nothing usable left is dropped. A badmedianever refuses the stream. Details.portable(optional, Kino 0.9.66; older Kino ignores it) is a universal copy of this same video next tourl:{ url, mime? }, an HLS (application/x-mpegURL) any TV receiver plays (H.264 8-bit up to 1080p with stereo AAC). Only a source that can make one on demand has any use for it; the phone's own player never uses it, and Kino casts it to a TV only when the title's own route would need a conversion or the stream is likely not playable as it is. It is checked exactly likeurl(same host rules); anything else, a non-HLSmimeincluded, is dropped and the rest of the answer still counts. It is ignored next todrm, requestsigningorexternal. Details.clockLive(apiVersion 27, Kino 0.9.88; live streams only): instead of a playlist address, the media clock of a CDN that names its segments by it, from which Kino builds the live window itself. Beside iturlis ignored (send"", or the address an older Kino plays), and so arealternativesand what a live channel never uses; adrm, a requestsigningor anexternalbeside it refuses the stream. Kino reads it only from a plugin whose feature apiVersion is 27 (enhancements["27"]turns it on without raising yours). Live by clock.- DRM only when declared. A stream carrying any of
drm,license,licenseUrl,drmLicenseUrl,keySystemorwidevineis refused ("El video tiene DRM y los plugins no lo soportan") -- unless your manifest declares thedrmcapability (apiVersion 2) and the only such key is adrmblock{ type: "widevine", licenseUrl, licenseHeaders? }: then Kino plays it as Widevine.licenseUrlis checked exactly likeurl(https on one of yourhosts, or the person's own server), andlicenseHeadersare filtered likeheaders(at most 20) and sent with the license request only. The other five keys are refused even next to a validdrmblock. See A Widevine-protected stream.
Labelled and lazy copies (apiVersion 6)¶
A source often has the same episode in several languages and on several servers, and finding each
server's video costs time (a page to open, sometimes a hidden browser capture of 5-25 s).
Resolving all of them before the first frame would make every play slow. From "apiVersion": 6, a
Stream's alternatives may name a copy without resolving it: { label, ref } instead of { url }.
Kino passes that ref to your resolve(ref) only when the copy is actually needed:
- the person picks it in the player's Servidor menu (the copy on screen keeps playing while it opens, then the new one starts at the same spot; if it fails, they read "No se pudo abrir …" and keep watching the copy they had);
- the automatic fallback reaches it (the copy on screen cannot play on this device, or is gone);
- a download's copy choice gets to it (inside the same 30 s budget it spends probing copies; a lazy copy that has not answered by then is skipped, never waited for).
That call is a normal resolve: the same time limit (75 s for an approved browser
plugin) when the person picked the copy -- they chose to wait for it -- but at most 20 s when the
automatic fallback asked, after which Kino cancels it (ending a capture still running) and moves on
to the next copy; the same checks on what it returns, kino.browser.capture allowed (for a download's copy
choice: only when no other page is open, else busy and the copy is skipped), host questions asked as
for the title. From its answer Kino uses url, headers, mime, subtitles (when it brings some;
otherwise the title's are kept), expiresInSeconds (a lazy copy past its expiry is resolved again, not
the whole title) and skip (it shows "Saltar intro" while that copy plays, never saved: the Stream's
own skip stays the episode's, and a hand correction still wins). Its own alternatives are ignored --
a copy never expands into more copies. A resolve that fails moves on to the next copy.
export async function resolve(ref) {
// A copy's own ref: "<episode>|<server>". Resolve just that server.
if (ref.includes("|")) return resolveServer(ref);
const servers = await listServers(ref); // [{ id, lang, name }], fast: no page opened yet
const first = await resolveServer(`${ref}|${servers[0].id}`);
return {
...first,
label: `${servers[0].lang} · ${servers[0].name}`, // "Latino · Servidor 1"
alternatives: servers.slice(1, 9).map((s) => ({
label: `${s.lang} · ${s.name}`, // "Subtitulado · Servidor 2"
ref: `${ref}|${s.id}`,
})),
};
}
Rules: ref is a non-blank string of at most 512 characters with no control characters (a bad or
repeated one is dropped); an entry with a url is a normal copy whatever else it carries; lazy and
concrete copies mix freely and share the limit of 8; each label is trimmed, at most 48 characters, no
control characters, or it is dropped while the copy still counts. Keep the ref enough to find that one
server again: it may be resolved minutes after the title (a person switching servers mid-episode).
Below apiVersion 6 the keys are unknown: a label is ignored and a { ref } entry, having no url, is
dropped exactly as before. Try it with node sdk/run.mjs ./plugin.js resolve '<ref>', which prints
each copy with its label, then resolve '<a copy's ref>' to resolve that copy.
A complete plugin that captures its first server and offers the rest this way is on Hidden browser.
Letting another app resolve what you found (externalResolve, apiVersion 11, Kino 0.9.66)¶
Sometimes your plugin can tell exactly what it found but cannot turn it into a playable URL itself: that needs a
separate, independently-installed Android app. From "apiVersion": 11, declare the externalResolve capability
(declarative: nothing to export) and have resolve() -- or one entry of a Stream's alternatives -- answer
{ external: { protocol, ref } } instead of { url, ... }:
export async function resolve(ref) {
return { external: { protocol: "my-protocol", ref: "some-opaque-reference" } };
}
protocol is a string you choose (1 to 64 characters from a-z 0-9 . _ -; Kino never interprets it), ref is
opaque (1 to 2048 characters, no control characters, never logged in full) and the optional resolver is the
Android package of the one app you want: it overrides the manifest's
externalResolver, and with it set no other app is ever asked. Kino finds an
app that declares protocol, asks the person's permission the first time, hands it ref and waits for an answer
shaped like a normal resolve() answer. From your plugin's side, assume one of two things: it plays, or it fails
like any other resolve() failure. Use it only when you genuinely cannot produce a url yourself, and give it a
fallback when you can. Everything else -- the whole flow, what the person sees, media and portable,
casting to a TV, building the other side -- is on External resolver apps.
A host you forgot may be asked about, once¶
When the person opens a title in the player and the only thing wrong with your Stream is that a URL
(the video, its license, a subtitle or an audio track) is on an https host you did not declare,
Kino asks them in the moment ("El video está en <host>, un servidor nuevo para este plugin.
¿Permitir?"), the same dialog a kino.fetch to an undeclared host gets. The
player also asks when it meets a new host mid-playback (a manifest, a segment, a redirect).
"Permitir" adds that host to your plugin's approved hosts (there is no cap on how many a person
approves this way; an update keeps them) and the video plays; "Rechazar" (or Back) is remembered for
your plugin -- the video fails as described above, a subtitle or audio track is dropped -- and that
host is never asked about again until the person chooses "Olvidar rechazos de host". An IP address, a
local name, plain http or a stream broken in any other way is never asked about, and nothing is
asked when nobody is watching: a download fails on that host instead. Don't rely on it: declare the
hosts your streams use.
The broad video permission¶
For a movie or an episode, those video, subtitle and audio dialogs have a third choice, "Permitir
video de cualquier servidor". It is the person's own grant, shown and revocable in Ajustes ▸ Plugins
("Puede reproducir video desde cualquier servidor", "Quitar permiso de video amplio"); the one way for
you to ask for the same rule up front is streamHosts: "any"
(apiVersion 4), approved on the consent sheet. An update or a reinstall keeps it; uninstalling drops
it.
While it is on, your movie or episode Stream is checked the way a live channel's is under
liveStreamHosts: "any": its url, everything its manifest
names, every redirect hop, and its subtitles and audioTracks may be on any public host, over
http or https, a public IPv4 address included, and no video host is ever asked about again for
your plugin. A download of a movie or an episode follows the same rule. It
never covers:
- the home network: private, loopback, link-local and CGNAT addresses, IPv6 literals, local names, and a public name that resolves into the LAN;
- a
drmblock'slicenseUrl(still your hosts only, asked about as above); kino.fetch: your own code still reaches only your hosts and the ones approved one by one;- live channels, which have their own rule.
It exists for sources whose hosters change domain per video or mid-playback; a plugin with a fixed CDN should still declare it.
Music and podcasts (apiVersion 8, Kino 0.9.54)¶
With "apiVersion": 8 an item may be audio: kind: "music" (an album, a playlist or a single
track) or kind: "podcast" (a show or an audiobook), in search, browse, home rows and your
section, next to your movies and series. Nothing to declare beyond the version: an audio item does
not need the episodes capability. An older Kino refuses an
apiVersion 8 plugin with "Este plugin necesita una versión más nueva de Kino", so declare 8 only when
you return audio items or export details.
export async function search(q) {
return [
{ id: "album-42", ref: "album:42", title: "Un álbum", kind: "music", artist: "Los Artistas", poster: "https://cdn.example.org/a42.jpg" },
{ id: "show-7", ref: "show:7", title: "Un podcast", kind: "podcast", overview: "Una charla por semana" },
];
}
export async function episodes(ref) { // only with the "episodes" capability
if (ref.startsWith("album:")) return { episodes: [
{ season: 1, number: 1, ref: "track:1", title: "Primera canción", runtimeMinutes: 4 },
{ season: 1, number: 2, ref: "track:2", title: "Segunda canción", runtimeMinutes: 5 },
] };
// ...a podcast's episodes, a series' chapters
}
How the pieces connect:
- With
episodesdeclared, Kino callsepisodes(ref)with the item'sref, for everymusicandpodcastitem: an album's or playlist's tracks, a podcast's episodes, an audiobook's chapters, in your order (a single track answers one entry).numberis the track or episode number,title,still(the cover) andruntimeMinuteswork as for any episode, and each entry'srefgoes toresolve. If you declareepisodes(for your series, say), yourepisodesmust also answer for everymusicandpodcastref, even a lone track: there is no per-item way to skip it. - Without
episodes, the item's ownrefgoes straight toresolveand plays as one track, exactly like a movie's. artist(optional,musicandpodcastonly) is the artist (music) or the host/author (podcast): trimmed, at most 200 characters, ignored on any other kind. The album or podcast page shows it as the line under the title (and Kino names it as the artist where it plays the audio). Without it there is no such line: Kino never takes one fromovervieworgenres.ids(optional) also names, on amusicorpodcastitem (apiVersion 19), the ids a lyrics plugin may match the song by:youtube(a video id, the most exact for YouTube Music),isrc,musicbrainz; each a text of 1 to 64 characters, others skipped. Kino keeps them with the item's artist on the device (a cache, relearned the next time the item is listed) and sends them in theidsof thelyricsquery while it plays.runtimeMinutesis kept on an audio item (unlike aliveone).searchmay gettype: "music"ortype: "podcast"when Kino leans that way;"any"includes them, and it stays a hint.- The
Streamis a normal one: progressive audio (MP3, M4A, AAC, OGG) or an HLS/DASH manifest. The kind is a hint: a stream that turns out to carry video still plays as video. migratemay answer a saved title as{ kind: "music" | "podcast", id, ref }(below apiVersion 8 that answer is no claim).
What the person gets with them in Kino 0.9.54:
- Audio titles on square covers, in Home rows of their own, after the video in search, and in their own section of the library. They are kept away from TMDB and from recommendations.
- An album or podcast page on phone and TV, with "Reproducir", "Aleatorio" and the track list, instead of the video title page.
- An audio player for on-demand music and podcasts: the track's name and cover, seek and previous/next (also from the notification and headphones), and the next track after 2 s. A podcast resumes exactly where it was left and counts as finished only in its last 30 s.
- "Seguir escuchando", a Home row for podcasts (audio leaves "Continuar viendo").
- Downloads, when you declare
download(apiVersion 2): progressive audio files and audio-only HLS are saved like a video, and a downloaded album plays offline in the audio player. - Cast: a track goes to a Chromecast as music, with its title, artist, album and cover, and to a DLNA TV as an audio item; an 18+ track sends only the app's name.
Limits: a music or podcast item from a plugin below "apiVersion": 8 is dropped (with a line in
the log), and the rest of the answer stays. Audio items count against the same row and page sizes as
any item, and adult: true follows the same 18+ lock.
The person's playlists on your plugin (apiVersion 10, Kino 0.9.65)¶
With "apiVersion": 10 a plugin may declare the "playlists" capability: the contract for the day
Kino's UI connects to it, so the playlists the person already has in their account on that service
show up inside Kino's "Mis listas", next to their own. For now it is just that -- a complete, honest
contract, with no UI connection yet: no installed or announced plugin uses this capability, and Kino
itself doesn't call any of these six exports anywhere on screen. It's infrastructure for a future
plugin that might need it, not something anyone uses today. Unlike music and podcasts (above), this
really is a capability -- the same as channels or tracking -- but the other way around from
channels: its six exports are all independently optional, including playlists() itself.
Declare the capability and export only the ones your service actually supports; not one of them is
required. No red approval. An older Kino refuses an apiVersion 10 plugin with "Este plugin necesita
una versión más nueva de Kino", so declare 10 only when you declare this capability.
"playlist" means three distinct, unrelated things in this SDK: the ones in this section, on your
plugin's own service (KinoHostedPlaylist); the M3U/IPTV list you build for
Live channels (KinoPlaylist, and contract.json's
live.maxPlaylists limits); and the kind: "playlist" you sign in
Signing every request (an HLS manifest request, nothing to do with a list of
titles). None of the three shares a capability or an export with the others: each lives only in its
own section.
export async function playlists() {
return [{ id: "42", title: "My usual playlist", itemCount: 12 }];
}
export async function playlistItems({ playlistId, cursor }) { // same shape as browse
return { items: [ /* ...KinoItem[]... */ ], next: null };
}
export async function playlistCreate({ title }) {
return { id: await createRemotePlaylist(title) };
}
export async function playlistAddItem({ playlistId, ref }) { /* ... */ }
export async function playlistRemoveItem({ playlistId, ref }) { /* ... */ }
export async function playlistReorder({ playlistId, refs }) { /* ... */ }
What each export answers:
playlists()answers the playlists the person already has on the service: an array of{ id, title, itemCount }(KinoHostedPlaylist).playlistItems({ playlistId, cursor })answers a playlist's contents, in the same shape asbrowse: an array ofKinoItemor aPagewithnext.playlistCreate({ title })answers{ id }when your service can create a new playlist. Without this export, Kino's UI will not offer "Crear lista nueva" for your plugin.playlistAddItem({ playlistId, ref })andplaylistRemoveItem({ playlistId, ref })add or remove an item; they are independent of each other -- you may have one without the other.playlistReorder({ playlistId, refs })gets the playlist's whole new order, as the array of every item'sref, in the final order.
What "Mis listas" will do the day Kino's UI connects to this capability (not built in any version
yet): a playlist from your plugin will be labelled "‹name› · ‹plugin›", mixed in with their own. Only
the button for an operation you actually exported will show up -- "Agregar" with playlistAddItem,
"Quitar" with playlistRemoveItem, "Reordenar" with playlistReorder -- never a disabled button,
never a "not implemented" error; a plugin that exports only playlists and playlistItems will look
read-only, with none of the three. Renaming the playlist or deleting it outright will not be part
of this capability: there is no export for either one, so those two options in the "Mis listas"
menu will exist only for one of the person's own native playlists, never for a plugin's.
Limits: declaring the playlists capability with an apiVersion below 10 is refused when the plugin
is installed (The "playlists" capability needs apiVersion 10). In the "Agregar a lista" sheet, a
playlist from your plugin will only show up for a title that comes from the same plugin that hosts
it -- adding a video to "your YouTube playlist" will only make sense for a video from that YouTube
plugin.
Subtitles for any title¶
Export subtitles({ imdbId, tmdbId, kind, season, episode, title, year, languages, file }) and Kino lists
what you answer in the player's "Buscar subtítulos en línea" (phone and TV), under your plugin's name,
next to OpenSubtitles and SubDL: for any movie or episode the person plays -- your titles, another
plugin's, a Stremio addon's -- as long as Kino knows its IMDb or TMDB id (a title known only by name is
never sent to you). The person picks a track, Kino downloads it, turns it into SRT and adds it like any
online subtitle (sync offset, style, remembered for the title).
Two ways to offer it:
- A subtitle provider:
"capabilities": ["subtitles"]and nothing else. Noresolve,searchorhomeneeded; the plugin appears nowhere but the subtitle search and Ajustes ▸ Plugins (it is not a source in "Elige tus plugins"). The consent screen says "Agrega subtítulos a tus películas y series". Older Kino versions refuse a capability they do not know: they do not install it. - Alongside your videos: keep your capabilities and just export
subtitles(declaringsubtitlestoo adds the consent line, but older Kino versions would then refuse the plugin). Kino asks every plugin whose install found the export; older versions never call it.
The argument: imdbId (tt…) and/or tmdbId (a number), at least one of them; kind "movie" or
"series" -- for an episode the ids are the series' and season/episode are set; title and
year are hints; languages are the person's subtitle languages, ISO 639-1, best first (["es",
"en"]). file (Kino 0.9.51) is what Kino knows of the file playing, when the person searches from the
player: { hash?, size?, name? }, each only when known, and absent when nothing is. hash is the
16-hex OpenSubtitles hash and size the bytes it was computed with (only for a plain, stable file);
name is the file's name with its extension ("The.Matrix.1999.1080p.mkv", at most 200 characters),
taken only from a URL that ends in a video file name, otherwise a release-style name Kino builds from
the title ("Oppenheimer.2023.mkv", "Breaking.Bad.S01E05.mkv"). Never the video's URL. Use it to rank the
release that matches the exact file first; older Kino versions never send it, so treat it as a hint.
Return an array of { lang, url, format?, label?, translated? }: a Stream's subtitles
entries plus an optional label and translated: true for a machine translation (the menu then says
"Español (traducido)" and lists it after the person-made tracks of that language). Kino keeps 30, then
lists only those in the person's languages, in that order, 15 per plugin: put the asked languages first.
label (60 characters) is shown next to the language, a release name for example. Each url follows a
Stream's subtitle rule: your hosts, the person's server, or any public host with
streamHosts: "any". The call is a background one (10 s, it never marks
your plugin "No responde"); return [] when you have nothing. Try it with
node sdk/run.mjs ./plugin.js subtitles tt0944947 1 1 (KINO_LANGS=es,en for the languages).
Describing other titles (meta, apiVersion 6)¶
Declare "meta" and export meta(query) to fill in what Kino could not find about a title on its info
page, whatever plugin listed it: a synopsis, a poster or background, genres, a year, a runtime, an
episode list. Kino asks TMDB first and, for an anime, AniList; your answer only fills what they left
empty, never replaces a value they gave (and never the title's own plugin's). It is the way to describe
titles TMDB does not know, like kitsu: anime. No consent line.
export async function meta(query) {
// query: { type: "movie" | "series", ids: { imdb?, tmdb?, kitsu?, mal?, anilist? }, id?, lang? }
// id: the title's own Stremio-style id in its source ("kitsu:1376", "tt0944947"), when it has one
// lang: the person's language ("es")
const found = await lookUp(query.ids);
if (!found) return null; // not a title you know: no failure
return {
title, overview, poster, backdrop, year: "2011", genres: ["Drama"], runtimeMinutes: 57,
episodes: [{ season: 1, number: 1, title, overview, still, airDate: "2011-04-17", id: "tt0944947:1:1" }],
logo: "https://img.example.org/got-logo.png", // Kino 0.9.51+
ratings: [{ source: "imdb", value: "9.2" }, { source: "rottentomatoes", value: "89%" }],
cast: [{ name: "Emilia Clarke", character: "Daenerys Targaryen", photo: "https://img.example.org/ec.jpg" }],
};
}
Every field is optional. Images follow the same rules as an item's. From Kino 0.9.51 three more (older
versions ignore them; no new apiVersion):
logo: a clear-logo of the title (its name drawn as art, transparent background). The info page shows it instead of the title's name at the top (phone and TV; the name stays for TalkBack and comes back if the image fails to load). Same image rules as aposter.ratings: at most 6{ source, value }, one per source.sourceis one ofimdb,tmdb,rottentomatoes,metacritic,letterboxd,mal,anilist,trakt;valuea number as the site writes it, up to 3 digits with up to 2 decimals, optionally followed by%or a scale ("8.8","94%","4.1/5"; a JSON number works too). Shown next to the page's ★ score ("IMDb 8.8 · Rotten Tomatoes 94%"). Unlike the other fields they add up: TMDB's own score stays, and atmdbrating is dropped when the page already has a score. A bad entry is dropped, the rest kept.cast: at most 20{ name, character?, photo? }(nameandcharacter60 characters;photoan image like aposter). Like every other field it only fills a gap: Kino shows TMDB's cast when TMDB has one. Kino shows the names;characterandphotoare kept for later.
episodes[].id is the episode's
Stremio-style video id: a Stremio addon's title whose own listing failed can then play those episodes
by it. Kino asks every meta plugin of the person at once, at most 6 s each, uses the first answer in
install order, and remembers it for 30 minutes; a failure or a timeout is just no answer, and the page
never waits for you.
What Kino reads, field by field (the rest of an answer is ignored, and each part is dropped on its own):
- Text fields (
title,overview, an episode'stitle/overview/id, a cast member'sname/character) may be strings or numbers, are trimmed and cut at their limit.titleis read but never shown: the page keeps the source's own. year: only its first 9 characters are read, and their first four digits are the year (1999,"1999-2003"; not"estrenada 1999").runtimeMinutes: 1 to 1000 (a numeric string or a decimal is read as Android's JSON does), shown only for a movie.genres: strings only, the first 5 non-empty ones, each cut at 30 characters.episodes: the first 5000 entries are read, invalid ones included;season0 to 999 (0 is kept but the page never lists it),number1 to 99999, one per season and number (the first wins), sorted.- Images (
poster,backdrop,logo, an episode'sstill, a castphoto): an item's image rule. A URL is read as text first, and one longer than 2048 characters is dropped (never cut into a broken address). Ametaanswer takes URLs only: an image reference (imageSource, apiVersion 13) is ignored here. - An answer whose only usable parts are
yearand/orruntimeMinutescounts as no answer, likenull.
Try it with node sdk/run.mjs <plugin dir> meta tt0133093 (or tmdb:603, kitsu:1376 series, several
ids, or the whole query as JSON): it prints your answer, Kino's verdict for every field (kept, cut,
dropped and why), what Kino keeps, and how the info page would use it (see
Test it locally). node sdk/validate.mjs . --run search <text> (or home, browse)
also asks your meta about the first title of the answer that carries ids.imdb or ids.tmdb, the way
Kino builds the query. The other way round, any plugin can ask Kino what it knows about a title:
kino.meta (Kino 0.9.53).
Catalog-only plugins (catalogOnly, Kino 0.9.54)¶
A plugin that lists and describes titles but has no video of its own -- a TMDB catalog, a list of
what's new, ratings -- says so with "catalogOnly": true in its manifest (Kino 0.9.54):
{
"id": "tmdb", "name": "TMDB", "version": "1.2.0", "apiVersion": 7, "entry": "plugin.js",
"hosts": ["image.tmdb.org"],
"capabilities": ["search", "home", "browse", "episodes", "resolve", "meta"],
"catalogOnly": true
}
What Kino 0.9.54 and later do with it:
- Its titles take the "Buscar dónde verlo" route. The info page's main button reads "Buscar dónde verlo" instead of "Reproducir", and every other way into the player (Home and its quick play, "Continuar viendo", the hero, a deep link, the TV's quick play) looks the title up in the person's other plugins first: one source that has it plays, several open the sources list, none says "Ninguno de tus plugins tiene este título…". The same detour Stremio addons without streams get.
- It is never a source of a title. Its
searchis not asked when Kino lists the sources of a title (the search screen, the player's "Ver en otros plugins", "Buscar dónde verlo"), it is not offered in "Buscar por fuente", and it never shows up in the player's "Servidor" list. Inside its own pages (its section, "Ver más", searching inside a "Ver más" page) its catalog is browsed and searched as always. - Its
resolveis never called. If a title of it reaches the player anyway, the player says "<name> solo muestra el catálogo: no reproduce videos. Busca este título en tus otros plugins." (or its English version), with "Ver en otros plugins" under it. - It is not a source in "Elige tus plugins", and Kino files it under Utilidades when the manifest
has no
categories. - The consent sheet says "Solo catálogo: no reproduce videos" ("Catalog only: doesn't play videos"). It is no grant: an update that adds or drops the field applies without asking.
The rules (the install is refused otherwise, with the message in quotes):
| Rule | Refusal |
|---|---|
true or false only |
"El campo \"catalogOnly\" debe ser true o false" |
At least one of home, browse, search, meta (instead of resolve plus search or home) |
"Un plugin \"catalogOnly\" debe declarar \"home\", \"browse\", \"search\" o \"meta\"" |
No download, drm or channels: they only serve playback |
"Un plugin \"catalogOnly\" no puede declarar \"download\": no reproduce videos" (the first one found) |
No streamHosts (from apiVersion 4) and no "browser": true (from apiVersion 6); "browser": "pages" is fine, it reads pages for the catalog |
"Un plugin \"catalogOnly\" no puede declarar \"streamHosts\": no reproduce videos" |
resolve may still be declared and exported: every capability you declare must be exported, as
always, and Kino 0.9.54+ simply never calls it. subtitles, tracking, segments, meta, episodes,
scopedSearch, migrate, section, categories() and settings all work as for any plugin.
No new apiVersion. The field is additive, like discoverable and kino.meta: valid at every
apiVersion, and an older Kino ignores it as it ignores any key it does not know. That is what lets one
manifest serve both:
-
Kino 0.9.53 and older ignore
catalogOnlyand apply their own rules, which requireresolveandsearchorhome. So, to stay installable there, keep declaring and exportingresolve-- one that always fails with a sentence for the person -- and declaresearchorhome:export async function resolve() { // Only Kino 0.9.53 and older call this: 0.9.54+ sends the person to their other sources first. throw kino.error("not_found", "catalog only", { userMessage: "Este catálogo no reproduce: busca el título en tus otros plugins." }); }Without them, Kino 0.9.53 and older refuse the plugin ("El plugin debe declarar \"resolve\""), and an installed older version simply stops updating there.
sdk/validate.mjstells you which case you are in. -
Kino 0.9.54 and later read the field and never call that
resolve.
sdk/validate.mjs prints the consent line and a note about older Kino; sdk/run.mjs . resolve <ref>
still runs your resolve (for the older Kino it serves) and reminds you that 0.9.54+ never calls it. A
complete catalog that uses it: A TMDB catalog.
Getting a title ready ahead (resolveAhead, Kino 0.9.88)¶
Available from Kino 0.9.88
No new apiVersion: the manifest field is valid at every one, Kino 0.9.88 is the first to read it, and an older Kino
ignores it like any key it does not know.
Pressing play on one of your titles waits for your resolve before the player can even start: on a 1.5 GB TV box, a
resolve that makes three requests took 0.7 to 0.8 s. The person has usually spent longer than that on the title's page
before pressing play (a "Continuar viendo" card opens that page too, on the episode to go on with), and
"resolveAhead": true lets Kino use that time:
{
"id": "my-movies", "name": "My movies", "version": "1.4.0", "apiVersion": 9, "entry": "plugin.js",
"hosts": ["api.example.com"],
"capabilities": ["search", "home", "episodes", "resolve"],
"fetchHosts": "any",
"streamHosts": "any",
"resolveAhead": true
}
- When. Once the person has stayed about 0.3 s on the page of one of your titles, Kino may call your
resolvefor what its play button would start (the movie, or the episode they would go on with), as a background call. If they leave the page before then, nothing is called; a call already running is never cancelled. - Only a
resolvethat can ask nothing. Nobody waits for that call, so it may not ask the person anything: Kino resolves ahead only for a plugin whose"fetchHosts": "any"the person approved, whose video may come from any server (an approved"streamHosts": "any", or the broad video permission), and which declares neitherexternalResolvenorbrowser. For any other plugin the field does nothing, and Kino does not callpreparein its place: leave the field out and exportprepareinstead. - Hosts. Kino checks the answer exactly as it checks the player's own
resolve. An answer the player would have had to ask the person about (a DRM license on a host you never declared, say) is not kept: pressing play then callsresolveagain, and the person is asked as always. - What Kino keeps. The answer, for that title only, for at most 20 minutes after it came, or until 60 s before its
expiresInSecondsruns out when that comes first. If the person presses play by then, the player starts from that answer without callingresolveagain. After that, after a failed answer, and on a retry or a reopen, Kino callsresolveas it always does. - Never for a live channel, an 18+ plugin while the person's 18+ code is locked, a title with a finished download, or a plugin that is off or waiting for its settings; at most 6 calls ahead a minute per plugin.
- What it asks of you. Your
resolvemay run for titles nobody plays. Declare the field only if such a call has no effect the person would notice: no play counted on your service, no quota or trial spent, no hidden page. - Ignored beside
catalogOnly(Kino never calls thatresolve) andbrowser,trueor"pages"(aresolvecalled ahead is a background call, wherekino.browser.captureandkino.browser.pageare refused).
The next episode of a series is a different case: Kino already gets it ready near the end of the episode playing, for any plugin that opens no hidden pages, with or without this field.
The field is a hint and never refuses the plugin: any value but true, false or null (read as left out) is ignored,
and Kino logs "The \"resolveAhead\" field must be true or false; Kino ignores any other value". sdk/validate.mjs warns
about that value and about catalogOnly or browser beside the field, and notes what true means.
Warming up before the play (prepare, Kino 0.9.88)¶
Available from Kino 0.9.88
No new apiVersion: any apiVersion may export it, Kino 0.9.88 is the first to call it and an older Kino never does.
Some services must never be asked for a stream nobody plays: a backend that allows a set number of resolve calls an
hour per account, or a portal whose free plays each resolve spends. Such a plugin leaves resolveAhead out and may
export prepare instead, to get ready while the person reads the title page. It works for any plugin with resolve,
whatever its hosts:
// Kino ignores what prepare returns: warm only what resolve(ref) will need, and never count a play or spend a quota.
export async function prepare(ref) {
await sessionToken();
}
export async function resolve(ref) {
const token = await sessionToken(); // already there when prepare ran
const r = await kino.fetch("https://api.example.com/play/" + encodeURIComponent(ref), {
headers: { Authorization: "Bearer " + token },
});
if (!r.ok) throw kino.error("unavailable", "play " + r.status);
return { url: r.json().url };
}
async function sessionToken() {
const kept = kino.storage.get("session");
if (kept) return kept;
const r = await kino.fetch("https://api.example.com/session", { method: "POST" });
if (!r.ok) throw kino.error("unavailable", "session " + r.status);
const token = r.json().token;
kino.storage.set("session", token, { ttlMs: 20 * 60 * 1000 });
return token;
}
- When. Once the person has stayed about 0.3 s on the page of one of your titles, Kino calls
prepare(ref)with the veryrefyourresolvegets for what the page's play button would start (the movie, the episode they would go on with, or a lone track; never a series and never a live channel). If they leave the page before then, nothing is called; a call already running is never cancelled. - What Kino does with it. Nothing: the answer is ignored, whatever it is, and so is a failure. Pressing play calls
resolveas always, so warm what thatresolvewill need: sign in, refresh a token, open a session, fetch an authorization and keep it (in memory,kino.storageorkino.cookies). - Limits. A background call of 15 s: nobody is asked anything (a
kino.fetchthat would need the person to approve a host fails instead of asking), a timeout or a failure never counts toward "No responde", and the person's own calls go first in your plugin's queue. At most once every 5 minutes for the sameref(a failed call counts), and at most 6 a minute for your plugin. - What it asks of you.
preparemust not start or count a play, and must not spend anything of the person's: no quota, no trial, no free play. It may run for titles nobody plays. - When Kino never calls it. Beside
"resolveAhead": true(Kino resolves ahead instead, or calls neither when it cannot), in a plugin without theresolvecapability, in acatalogOnlyplugin (Kino never calls itsresolve) and in one that declaresbrowser(trueor"pages": its hidden pages need a play the person started); nor for an 18+ plugin while the person's 18+ code is locked, a title with a finished download, or a plugin that is off or waiting for its settings.
sdk/validate.mjs notes what Kino does with it and warns when Kino would never call it; node sdk/run.mjs . prepare <ref>
runs it (Test it locally).
Telling a tracker what the person watches (tracking, apiVersion 7)¶
A plugin for a tracking service -- Seenr, Trakt, Simkl, a Plex-style webhook, the person's own server --
declares "capabilities": ["tracking"] (alone, with subtitles/segments, or next to a source's
capabilities) and "apiVersion": 7, and exports track(event). Kino calls it for every movie or
episode the person plays on that device, from any source. Kino 0.9.50 and older refuse such a
manifest with "Este plugin necesita una versión más nueva de Kino".
- Consent. The install sheet says, in red, "Le contará a
<your hosts>qué ves y cuándo lo terminas" (the first 3 hosts, then "y N más"; with no host, "al servidor que escribas en su configuración"). An update that addstrackingalways waits for the person, even when Kino approves other updates on its own. - The switch. Your Ajustes tab gets "Enviar lo que veo" (on by default, synced to the person's other
devices). Off, Kino stops calling
trackand deletes what was waiting; disabling or uninstalling the plugin does the same. - What is never sent. Live channels and radio, 18+ titles, anything a Chromecast or DLNA TV plays (the phone is only a remote then), a title that is not in the person's library, and an episode whose number Kino does not know.
When. start once the video really plays (and again when it resumes after a pause); progress at
most every 5 minutes of playback and on every pause (with paused: true); stop with the position
when the person leaves the title (or plays another one); watched once, when the position crosses
Kino's own "visto" rule: 3 minutes or less left and at least 90% played. A title opened already past
that point (resumed at the credits on another device) does not send watched again, and each device
sends a title's watched to your plugin at most once.
{
id: "6f1c…", // stable: the same on every retry of this event, use it to ignore a repeat
type: "start" | "progress" | "stop" | "watched",
at: 1759670000000, // when it happened on the device (epoch ms), not when it reached you
kind: "movie" | "episode",
ids: { imdb?, tmdb?, tvdb?, anilist?, mal? }, // a movie's; an episode's OWN (see below)
title?: "…", // the movie's name; an episode's own name when TMDB has one
year?: 1999, // a movie's year
show?: { title: "…", year?: 2008, ids: { imdb?, tmdb?, tvdb?, anilist?, mal? } }, // episodes only
season?: 1, episode?: 2, // episodes only (season 1 when the source gave none)
positionMs?: 1234000, durationMs?: 8160000, progress?: 0.151, // where the person was, 0..1
paused?: true // a progress sent because the person paused
}
Which ids. For an episode, ids are the episode's own (TMDB's episode id, and its IMDb and
TVDB ids when TMDB knows them) and the show's are in show.ids: never use show.ids where a service
expects an episode id, or the check-in lands on the wrong item. Kino fills the ids it lacks from TMDB
when it delivers (at most 8 s); when TMDB doesn't answer the event still goes, and an episode's ids
may be {}: fall back to show.ids + season + episode. anilist/mal appear only when the title's
own source named them. Every key is absent when unknown; imdb is a tt… string, the rest numbers.
What to return. Anything ({ ok: true } by convention) means delivered. Return { skipped: true }
for an event your service has no use for (a tracker that keeps no progress, a title it does not have):
Kino drops it the same way, but only a real delivery clears the red "No pudo avisar…" line, so a wrong
link stays visible until it is fixed. To fail, throw kino.error(code):
timeout,network,unavailable,rate_limited(and a timeout of the call itself, or an error thrown without a code): Kino tries the same event again later -- 30 s, doubling up to 6 h, 12 tries at most -- and your later events wait behind it, in order;auth_required,invalid_request,not_found,geo_blocked,host_not_allowed,too_large: the event is dropped at once.
A dropped event, or three failures in a row, shows "No pudo avisar a <your plugin>: …" in red in your
Ajustes tab and in Gestionar, until a delivery succeeds. The call is a background one (10 s, never "No
responde"), never on the player's thread. Kino keeps at most 200 events waiting per plugin (the oldest
progress goes first, a watched never) and drops one still undelivered after 7 days; a newer
progress replaces a waiting one of the same title, and a stop or watched replaces its waiting
progress. Nothing is lost offline or when the app is closed: Kino delivers once there is network.
Kino's own logs never carry what the person watched; with "Modo debug" on, your Registro shows each
event sent. A converted Stremio addon never gets tracking (Stremio has no scrobble protocol). Try it
with node sdk/run.mjs <plugin dir> track start (or progress, stop, watched, plus a JSON object to
change the sample).
Where the intro and credits are (segments, apiVersion 7)¶
A plugin that knows where a title's intro and credits are -- an IntroDB-like database, an AniSkip-like
one, the person's own server -- declares "capabilities": ["segments"] (alone, with
subtitles/tracking, or next to a source's capabilities) and "apiVersion": 7, and exports
segments(query). Kino then shows its "Saltar intro" and "Saltar outro" buttons, and "Saltar
automáticamente" jumps the intro, for any movie or episode the person plays, from any source, on
phone and TV. Kino 0.9.50 and older refuse such a manifest.
- Consent. "Agrega el botón para saltar la intro y los créditos", not in red (like
subtitles, your plugin only learns which title plays). An update that addssegmentsneeds no approval of its own. - When. Once a movie or episode really plays (Kino knows the file's length), in the background:
playback never waits for you. Never for live channels or radio, 18+ titles, or a title Kino knows by
no id. Every installed
segmentsplugin is asked at once; Kino keeps an answer (an empty one too) for the session per title, episode and length (rounded to 10 s), and asks again after 2 minutes only when every plugin failed.
{
kind: "movie" | "episode",
ids: { imdb?, tmdb?, tvdb?, anilist?, mal? }, // a movie's; an episode's OWN, as track() gets them
show?: { ids: { imdb?, tmdb?, tvdb?, anilist?, mal? } }, // episodes only: the show's
season?: 1, episode?: 2, // episodes only
durationMs?: 1440000 // the playing file's length: answer for THAT cut
}
No title, year or URL is sent; an episode's ids may be {}, so fall back to show.ids + season +
episode. Return an array of { type, startMs, endMs } ([] or null when you know nothing):
type one of intro, outro, recap, credits, preview, times in whole ms of the file. Kino checks
each entry on its own and drops a bad one without losing the rest: an unknown type, a time that is not
a whole number, a start below 0, an end not at least 1 s after the start, and -- with durationMs
known -- a start at or past the end or an end more than 5 s past it (within that it is cut). Of
overlapping entries of the same type the earlier one stays. Kino reads the first 100 entries and keeps
10. The earliest intro is the intro, the earliest outro or credits after it is where the ending
starts; recap and preview are accepted and have no button yet.
Who wins. The person's own correction (the marker editor) always does, and so does the
skip of the plugin serving the file. For anime, AniSkip (when "Saltar intro en anime" is on)
wins part by part: your answer fills only the intro or ending it lacks. Between two segments plugins,
the first in Ajustes ▸ Plugins' order with a usable answer wins. Nothing you answer is stored or synced.
The call is a background one (8 s, never "No responde"); Kino waits for it at most 12 s. Try it with
node sdk/run.mjs <plugin dir> segments tt0133093 8160000 (a movie and its length) or
segments tmdb:1396 1 2 2880000 (an episode, by the show's id): it prints what Kino keeps, what it
dropped and why, and the button it makes of it.
Lyrics for the music player (lyrics, apiVersion 19)¶
Available from Kino 0.9.81
apiVersion 19 ships with Kino 0.9.81. Older Kinos refuse a manifest with
"apiVersion": 19 with «Este plugin necesita una versión más nueva de Kino».
A plugin that finds a song's lyrics -- LRCLIB, a lyrics site, the person's own library -- declares
"capabilities": ["lyrics"] (alone, with subtitles/tracking/segments, or next to a source's capabilities) and
"apiVersion": 19, and exports lyrics(query). Kino then shows a "Letra" button next to the playback controls of the music
player, over the cover, on phone and TV, for music items and, from Kino 0.9.84, podcast items too: an episode's
transcript, an audiobook's or a reading's text.
- Consent. The install sheet says what your plugin learns: the title and artist of what the person listens to (not in
red). An update that adds
lyricsneeds no approval of its own. - When. Only when the person turned the lyrics on for a song, in the background: playback never waits for you. Several
lyricsplugins are asked at once and the person picks the source; Kino keeps an answer for 7 days and "nothing found" for 10 minutes (a failure is never kept).
{
title: "Song",
artist: "Artist", // may be ""
album?: "Album",
durationMs?: 215000, // the song's length: answer for THAT cut
ids?: { isrc?, musicbrainz?, youtube? } // only what Kino knows; the most exact way to find a song
}
The audio's address is never sent. Search by ids when you can, then by artist and title, and use durationMs to pick
between versions of the same song.
Return an object with any of synced ([{ ms, text }], time-synchronized), plain (the text only), label (60
characters, names the source), instrumental: true (the song has no lyrics) and matchDurationMs (the length of the entry you
matched); null, [] or {} means "nothing for this song". Kino checks each synced line on its own and drops a bad one
without losing the rest: ms not a whole number of at least 0, below the previous line's, or no text. It reads the first 800
lines, cuts a line at 300 characters and a plain text at 20,000, removes control and right-to-left override characters, and
drops an answer over 102,400 characters whole.
What is shown. The synchronized lines only when they plausibly fit the song: matchDurationMs within 3 s of the song's
length, or, without it, a last line no more than 5 s past the end. Otherwise plain, and if you gave none, nothing. With the
song's length unknown, plain is preferred and the synchronized lines show only when they are all there is. Lyrics that exist
win over instrumental.
The call is a background one (10 s, never "No responde"). Kino's logs carry only plugin ids and counts, never the title or the
artist. Lyrics are copyrighted: your plugin and its source are yours to answer for. Try it with
node sdk/run.mjs <plugin dir> lyrics "Song" "Artist" "Album" 215000 or a JSON query: it prints what Kino keeps, what it
dropped and why, and what it would draw.
Being the person's sync transport (syncProvider, apiVersion 12, Kino 0.9.74)¶
A plugin that declares "capabilities": ["syncProvider"] (alone or next to others) and
"apiVersion": 12 carries the person's sync between their devices through a service it talks to: a
bot, a storage API, a server the person runs. Kino keeps all the logic (what syncs, merging, when to
run) and encrypts the snapshot before your code sees it; your plugin only stores an opaque blob and
gives it back byte for byte:
export async function syncPull({ maxBlobBytes }) { /* -> { blob, version } or null when nothing is stored */ }
export async function syncPush({ maxBlobBytes, blob, expectedVersion }) { /* -> { version } */ }
export async function syncStatus(_null) { /* optional -> { ready, message? } */ }
- One object argument each (
nullforsyncStatus).blobis standard base64 (RFC 4648,+and/, padded) without line breaks, in both directions.versionis an opaque string of yours. - Conflicts:
syncPushgets the version Kino last pulled (expectedVersion,nullif none). A provider that can tell the remote changed since throwskino.error("conflict", "…"); Kino then pulls, merges and pushes again. One that cannot tell ignores it. - Limits: the blob is at most the manifest's
sync.maxBlobBytes(default and maximum 4 MiB), and only insidesyncPull/syncPushmaykino.fetchand the call's answer be that big. - Key and consent: the manifest must declare
sync.keySecret(one of yourpasswordsettings); Kino derives the sync key from it on each device, so the plugin and its service can read the data. One red consent line says so, and an update that adds the capability waits for the person's approval.
The manifest's sync block, who can read what, the cadence, the realtime signal, the provisioning flow,
the consent lines and the two example providers are on Sync providers.
Bytes and images your plugin serves (apiVersion 13, Kino 0.9.74)¶
apiVersion 13 arrives in Kino 0.9.74 together with apiVersion 12. It adds six capabilities, none with a consent line of its own:
| Capability | Export | What it gives | Page |
|---|---|---|---|
socket |
none | kino.ws, outbound WebSockets (wss://, port 443) to your declared hosts |
Sockets and plugin-served bytes |
byteSource |
read({ handle, offset, length }) → { bytes } |
resolve() may answer { source: "plugin", handle, size, mime }; Kino plays it (and casts it) from your read |
Sockets and plugin-served bytes |
storageLarge |
none | kino.storage holds 16 MB (2 MB per value), device-only |
Catalog and large storage |
catalog |
none | kino.catalog, a SQLite catalog of up to 100,000 of your items, searched by Kino |
Catalog and large storage |
qrScan |
none | kino.qr.scan(), the phone's camera scanner, from a settings action or a panel action |
QR codes |
imageSource |
image({ handle }) → { bytes, mime } |
poster, backdrop, still and a section hero's image may be { source: "plugin", handle } |
Images from the plugin |
It also adds the settings form's qr type (A QR code), and the same Kino version brings
kino.crypto's byte operations aesIge, aesIgeVerify, modPow, gunzip and convert to every plugin, whatever its
apiVersion (Byte operations). A plugin that
declares one of the capabilities below "apiVersion": 13 is refused ("The \"catalog\" capability needs apiVersion
13"); an exported read or image without its capability is never called.
Errors people understand¶
A plain throw new Error("…") reaches the person as a generic failure of your plugin. When the
failure is one of the usual ones, throw a typed error instead and Kino says it properly, in Spanish, with your plugin's
name:
if (r.status === 401) throw kino.error("auth_required", "la sesión venció");
kino.error code |
What the person sees |
|---|---|
auth_required |
"Configura {plugin} en Ajustes ▸ {plugin}" when your plugin declares settings (its own tab in Ajustes), else "Configura {plugin} en Ajustes ▸ Plugins" ("Menú ▸ Plugins" on the phone), with a button to its Configurar screen |
not_found |
"No se encontró en {plugin}" |
geo_blocked |
"Este contenido no está disponible en tu región" |
rate_limited |
"{plugin} está limitando las peticiones; intenta en unos minutos" |
unavailable |
"{plugin} no está disponible ahora" |
Your message is a detail for the log (cut at 200 characters); the person reads Kino's sentence. An unknown code becomes a plain error.
From Kino 0.9.50, auth_required reads "Configura {plugin} en Ajustes ▸ {plugin}" when your plugin
declares settings (it has its own tab in Ajustes), else "Configura {plugin} en Ajustes ▸ Plugins"
("Menú ▸ Plugins" on the phone), with the same button.
Your own sentence for the person (userMessage, apiVersion 6)¶
When Kino's sentence says too little (a chapter that was taken down, an account to link again), pass your own sentence for the person as a third argument:
throw kino.error("not_found", "E100006", { userMessage: "Este capítulo ya no está disponible." });
throw kino.error("auth_required", "E100083", {
userMessage: "Tu cuenta se abrió en otro dispositivo. Vuelve a intentarlo, o vincúlala de nuevo.",
});
Kino shows it instead of its own line, always as "Mensaje de <your plugin's name>: <your sentence>" ("Mensaje de Demo: Este capítulo ya no está disponible."), only when all of this holds; otherwise the person reads Kino's line and your sentence goes nowhere (it is not logged either; the detail is):
- your plugin's name can introduce it: only the characters below, no
:, no digit glued to a letter, nothing that spells Kino (so a plugin namedM3UorCuevana3always shows Kino's line;Cuevana 3is fine); - the code is one of the five in the table (Kino always words
timeout,network,host_not_allowed,crypto_errorand the rest itself); - it is 1 to 160 characters once trimmed, made only of the letters of Basic Latin and Latin-1 (what
Spanish, Portuguese and English write: á é í ó ú ü ñ ç ã õ â ê ô à è…, but not ø æ ð þ ß), the digits
0-9, the plain space and
. , : ; ¿ ? ¡ ! ' ’ ‘ “ ” « » ( ) % - – — ▸(a;only before a space): so no other script, look-alike letter, small capital, line break, tab, other kind of space, invisible character, emoji or@; - it reads as plain words: at least two words, no URL, no error prefix (
TypeError:,[Tag]), noundefined/null/NaN, and it doesn't end in:,;or-; - fewer than 6 digits in all, whatever separates them (no phone or account number, and so no full date
with its year), and no digit glued to a letter (
en 5 minutosis fine,5minutosis not); - no domain: a dot glued to a letter (
site.app), a dot after a space (site .app), a dot followed by a lowercase word of 2 to 6 letters (site. app),www, orpunto/dotglued to or followed by a domain ending (punto com,puntodev; "a punto de volver" and "en este punto es mejor" are fine:es,la,meandtoare not read as endings); - it never spells Kino: read with
1,l,!,¡asi,0asoand every non-letter dropped, it holds nokinoanywhere (so avoid a word like "Kinoshita"); - it asks for no credentials, money or contact outside Kino, read word by word (a word split on purpose
is read whole:
N e q u i,Ne qui,con tra seña,What s app,pun to com): nopag…(pago, pagues, págalo; "página" is fine),abon…,recarg…,transfer…,consign…,deposit…,contraseñ…,passw…,clave…,credencial…,token…,tarjeta,PIN, Nequi, Daviplata, WhatsApp, Telegram, acódigothat came by SMS or is a verification code (verification…; "Verifica tu conexión" is fine): your own settings are the only place for those (recarg…also refuses "Recarga la lista": say "Vuelve a cargar"); - it holds none of the passwords the person typed in your settings (checked against your plugin's stored values; while they can't be read, the sentence is not shown), nor any sealed secret's value. Never echo what the person typed, in any form.
Never use userMessage to ask for money, passwords or contact data
Each author is responsible for their own plugin. Kino only lists community plugins (its
community search); it does not recommend or promote them. If a plugin breaks the rules for
plugins -- for example, it uses userMessage to ask for money, passwords or contact data, it is
malware, or it infringes someone's rights -- Kino removes it from the community index through
community-blocklist.json (at the root of this repository), and anyone can report it
with the "Reclamo / retiro de plugin" issue template. An installed copy stays installed,
its card says "Retirado del índice de la comunidad." and it gets no more updates; a fork needs its
own report. See Claims and plugin takedowns.
Write it for the person, in their language; Kino doesn't translate it. It takes the very place Kino's
own line takes, so it never changes what the screen does: auth_required keeps the button to your
Configurar screen; geo_blocked shows the player's "No se puede reproducir" dialog; the other codes
show Kino's error line (on a live channel the person keeps zapping). It is also the reason under your
plugin's Home row and in the search notices. Your settings form and your section pages show it for
not_found, unavailable and rate_limited, and keep their own generic text for auth_required and
geo_blocked. One thing still wins over it, whatever the code: a host the person refused for this call
(they can act on that). The sentence counts only for the call that built the error: build it where you
throw it, not once at the top of your module. The Node kit (run.mjs) prints what the person would
read, or why the sentence is not shown. Kino builds older than 0.9.50 ignore the third argument and
show their own line, so it is always safe to pass.
A pending update wins over the error¶
When a newer version of your plugin waits for the person's approval (it asks for a new host,
permission or capability), a failed call does not show the usual sentence but "Hay una versión nueva de
<name>: actualízala en Ajustes ▸ Plugins", so the person knows what to do. A refused host, your
valid userMessage and auth_required (which keeps its button) still win over it. See
Updates.
18+ content (adult, apiVersion 6)¶
From "apiVersion": 6, adult: true on an item, on one of your Categorías
tiles, or on a live category or channel marks an 18+ entry. Kino shows it only while the person's 18+
code is unlocked on that device (Ajustes ▸ Control parental) and hides it again when they lock it. Nothing to
declare in the manifest. Below apiVersion 6 an adult: true entry is dropped, as before.
- It applies on Home, in search, "Ver más", your section, Categorías and En vivo. A row or a group left with only 18+ entries is not shown while the code is locked.
- Every channel of an 18+ category counts as 18+, and an 18+ channel never enters "Recientes".
liveSearchhits need a mark: see Mark everyliveSearchhit.- Sending an 18+ title to the paired TV needs the TV's 18+ content unlocked too ("Desbloquea el contenido 18+ en el TV para verlo allí").
- Your plugin cannot tell whether the code is unlocked, nor get around the lock: always return the mark and Kino decides what shows.