Skip to content

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 }:
    • q is the text the person typed (it can be empty; return []).
    • type is "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; use type at most to put the kind it names first.
    • season and episode are 0 unless Kino is looking for a specific episode; tmdbId and year are 0 when unknown.
    • originalTitle is TMDB's original title when it differs from q (else ""), and altTitles up to 5 other titles Kino knows for the work (each at most 200 characters): try them when q finds nothing on a source that names things in another language.
    • cursor is null, except when the person asked for more results and your previous page said where to continue (see Page below).
    • within (apiVersion 6, only for a plugin that declares scopedSearch) is present when the person searches inside one of your "Ver más" pages: see Searching inside a "Ver más" page.
  • home() gets null.
  • browse(ref, cursor) gets the ref of one of your Home rows (or a ref a previous page gave), and cursor null for the first page or the next of the page before.
  • episodes(ref) gets the ref of a series item, as you returned it, or (apiVersion 8) the ref of a music or podcast item, for its tracks or episodes.
  • details(ref) (apiVersion 8, Kino 0.9.54) gets the ref of a movie item when its page opens: see A title's own details.
  • resolve(ref, options) gets the ref of a movie item, the ref of an episode, (apiVersion 2) the ref of a live item, or (apiVersion 8) the ref of a music or podcast item from a plugin without episodes. options is undefined on a normal call; only an apiVersion 6 plugin with a request-signed stream ever gets it, as { retry }. From apiVersion 6 it also gets the ref of 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 a Stream's subtitles, each entry with an optional label and translated.

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 apiVersion 8, details is a reserved export name: export a function by that name only with this meaning (a helper of yours called details must be renamed or left unexported). There is no capability to declare: Kino calls it only if your plugin exports it and declares apiVersion 8 or more, so an older Kino never calls it, and an older plugin's own helper named details is 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 use kino.browser.page like episodes.
  • When the item carried no ids, the ids of your answer pin the movie on TMDB. Besides tmdb and imdb, ids (in details and in episodes().series) may carry an anime's mal, anilist and kitsu (Kino 0.9.54): AniList and the person's meta plugins are then asked by them.
  • rating is 0 to 10 (like an item's); runtimeMinutes is the movie's length (a series' runtimeMinutes is ignored: it is per episode). episodes(ref).series takes rating and runtimeMinutes too from Kino 0.9.54; older versions ignore them.
  • If your resolve needs the same page details read, 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.

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.

  • url must be https and its host must be one of your hosts, 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 plain http is a host you declared { "host": "…", "insecureHttp": true } (apiVersion 2, see the manifest): that host, exactly, accepts http for 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 with streamHosts: "any" and the person's broad video permission; and a host you forgot may be asked about instead of refused.
  • mime is optional, of the form video/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.fetch host rules. That covers the url itself, the variants, segments and #EXT-X-KEY keys an HLS manifest names, the BaseURLs of a DASH manifest, the subtitles, and every redirect hop of any of them: each must be https on one of your hosts (or http on one you declared insecureHttp), 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 in hosts.
  • headers are sent with every one of those player requests (the stream, its manifest's segments and keys, its subtitles, and redirect hops, all on your hosts) and, if you declare download, 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-Encoding and Connection are ignored.
  • subtitles: at most 30, each { lang, url, format? }. lang is a short language code such as "es" (up to 20 characters; blank becomes "und"), format is "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: url must be https on 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 a url already listed (the first entry wins). lang up 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 from lang. 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 no audioTracks plays 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. When url cannot 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 like url, mime and headers; a bad one is dropped and the rest still count. They share the stream's subtitles and audioTracks. Ignored next to drm, with signing (alternateHosts is 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 bare HD or SD is never enough for that. From apiVersion 6 an alternative may carry a label, 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, signContext and alternateHosts (apiVersion 6): an HLS stream that needs a fresh signature on every request. They have their own page: Signing every request.
  • durationMs is optional, in milliseconds.
  • skip is optional: where THIS file's opening and ending are, in milliseconds from its start -- { openingStartMs?, openingEndMs?, endingStartMs? }. Kino shows its "Saltar intro" button from openingStartMs (0 when left out or null) to openingEndMs, and "Saltar outro" (to the next episode) from endingStartMs. Every value must be a finite number between 0 and durationMs (or 24 h when you give no durationMs); the opening needs its openingEndMs, after its start; endingStartMs must not be before the opening's end. A bad part is dropped and the rest still count; a bad skip never 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 send skip. 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 calls resolve once 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: its title, sizeBytes and container, its video (codec, profile, width, height, fps, bitDepth, hdr), its audio and subtitles tracks (codec, language, title, and default / text), whether you converted it for playback and short notes. 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/container 40, language 20), numbers are clamped (width/height to 16384, fps to 480, bitDepth to 16, channels to 32, sizeBytes to 2^50), at most 16 tracks and 4 notes; an object with nothing usable left is dropped. A bad media never refuses the stream. Details.
  • portable (optional, Kino 0.9.66; older Kino ignores it) is a universal copy of this same video next to url: { 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 like url (same host rules); anything else, a non-HLS mime included, is dropped and the rest of the answer still counts. It is ignored next to drm, request signing or external. 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 it url is ignored (send "", or the address an older Kino plays), and so are alternatives and what a live channel never uses; a drm, a request signing or an external beside 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, keySystem or widevine is refused ("El video tiene DRM y los plugins no lo soportan") -- unless your manifest declares the drm capability (apiVersion 2) and the only such key is a drm block { type: "widevine", licenseUrl, licenseHeaders? }: then Kino plays it as Widevine. licenseUrl is checked exactly like url (https on one of your hosts, or the person's own server), and licenseHeaders are filtered like headers (at most 20) and sent with the license request only. The other five keys are refused even next to a valid drm block. 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 drm block's licenseUrl (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 episodes declared, Kino calls episodes(ref) with the item's ref, for every music and podcast item: an album's or playlist's tracks, a podcast's episodes, an audiobook's chapters, in your order (a single track answers one entry). number is the track or episode number, title, still (the cover) and runtimeMinutes work as for any episode, and each entry's ref goes to resolve. If you declare episodes (for your series, say), your episodes must also answer for every music and podcast ref, even a lone track: there is no per-item way to skip it.
  • Without episodes, the item's own ref goes straight to resolve and plays as one track, exactly like a movie's.
  • artist (optional, music and podcast only) 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 from overview or genres.
  • ids (optional) also names, on a music or podcast item (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 the ids of the lyrics query while it plays.
  • runtimeMinutes is kept on an audio item (unlike a live one). search may get type: "music" or type: "podcast" when Kino leans that way; "any" includes them, and it stays a hint.
  • The Stream is 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.
  • migrate may 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 as browse: an array of KinoItem or a Page with next.
  • 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 }) and playlistRemoveItem({ 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's ref, 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. No resolve, search or home needed; 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 (declaring subtitles too 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 a poster.
  • ratings: at most 6 { source, value }, one per source. source is one of imdb, tmdb, rottentomatoes, metacritic, letterboxd, mal, anilist, trakt; value a 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 a tmdb rating is dropped when the page already has a score. A bad entry is dropped, the rest kept.
  • cast: at most 20 { name, character?, photo? } (name and character 60 characters; photo an image like a poster). Like every other field it only fills a gap: Kino shows TMDB's cast when TMDB has one. Kino shows the names; character and photo are 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's title/overview/id, a cast member's name/character) may be strings or numbers, are trimmed and cut at their limit. title is 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; season 0 to 999 (0 is kept but the page never lists it), number 1 to 99999, one per season and number (the first wins), sorted.
  • Images (poster, backdrop, logo, an episode's still, a cast photo): 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). A meta answer takes URLs only: an image reference (imageSource, apiVersion 13) is ignored here.
  • An answer whose only usable parts are year and/or runtimeMinutes counts as no answer, like null.

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 search is 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 resolve is 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 catalogOnly and apply their own rules, which require resolve and search or home. So, to stay installable there, keep declaring and exporting resolve -- one that always fails with a sentence for the person -- and declare search or home:

    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.mjs tells 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 resolve for 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 resolve that 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 neither externalResolve nor browser. For any other plugin the field does nothing, and Kino does not call prepare in its place: leave the field out and export prepare instead.
  • 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 calls resolve again, 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 expiresInSeconds runs out when that comes first. If the person presses play by then, the player starts from that answer without calling resolve again. After that, after a failed answer, and on a retry or a reopen, Kino calls resolve as 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 resolve may 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 that resolve) and browser, true or "pages" (a resolve called ahead is a background call, where kino.browser.capture and kino.browser.page are 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 very ref your resolve gets 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 resolve as always, so warm what that resolve will need: sign in, refresh a token, open a session, fetch an authorization and keep it (in memory, kino.storage or kino.cookies).
  • Limits. A background call of 15 s: nobody is asked anything (a kino.fetch that 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 same ref (a failed call counts), and at most 6 a minute for your plugin.
  • What it asks of you. prepare must 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 the resolve capability, in a catalogOnly plugin (Kino never calls its resolve) and in one that declares browser (true or "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 adds tracking always 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 track and 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 adds segments needs 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 segments plugin 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 lyrics needs 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 lyrics plugins 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 (null for syncStatus). blob is standard base64 (RFC 4648, + and /, padded) without line breaks, in both directions. version is an opaque string of yours.
  • Conflicts: syncPush gets the version Kino last pulled (expectedVersion, null if none). A provider that can tell the remote changed since throws kino.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 inside syncPull/syncPush may kino.fetch and the call's answer be that big.
  • Key and consent: the manifest must declare sync.keySecret (one of your password settings); 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 named M3U or Cuevana3 always shows Kino's line; Cuevana 3 is fine);
  • the code is one of the five in the table (Kino always words timeout, network, host_not_allowed, crypto_error and 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]), no undefined/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 minutos is fine, 5minutos is 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, or punto/dot glued to or followed by a domain ending (punto com, puntodev; "a punto de volver" and "en este punto es mejor" are fine: es, la, me and to are not read as endings);
  • it never spells Kino: read with 1, l, !, ¡ as i, 0 as o and every non-letter dropped, it holds no kino anywhere (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): no pag… (pago, pagues, págalo; "página" is fine), abon…, recarg…, transfer…, consign…, deposit…, contraseñ…, passw…, clave…, credencial…, token…, tarjeta, PIN, Nequi, Daviplata, WhatsApp, Telegram, a código that 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".
  • liveSearch hits need a mark: see Mark every liveSearch hit.
  • 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.