Skip to content

The player panel (apiVersion 9)

From Kino 0.9.55 your plugin can open its own panel from the player: a surface you describe in JavaScript for what is playing right now (movie, episode, copy, position), with text, images, buttons and inputs, whose values are kept per video or for your whole plugin and synced across the person's devices. The same panel can drive the player (seek, speed, picture size, markers, an end-of-episode countdown) and, with playerEvent, you can learn what happens during playback. All of it needs "apiVersion": 9; below that, or on Kino 0.9.54 and older (which refuse a manifest with "apiVersion": 9), none of it exists. Your plugin must not depend on it to play.

A complete example with every element, both tabs and every action is sdk/test/panel-demo in the kit's repository; there is a small one below.

From "apiVersion": 14 (Kino 0.9.74) the panel can also be built with the screen kit, a tab can live in another plugin's panel or on a live channel, and the person can pin it next to the video: see The panel built with the screen kit.

From "apiVersion": 23 (the next Kino release) a plugin can also keep up to three small elements in the top-right corner of the TV player, and a button there can open this panel (openPanel): see The player slot.

What is not in this version

ai (Kino's AI) and chat do not ship in Kino 0.9.55; they come in a later version. If your panel includes an ai or chat element, Kino drops it and writes "needs a newer Kino" to the log. There is no kino.socket either.

Where it appears

  • A button with the name and icon from your manifest, next to the subtitles one ("Audio y subtítulos"), only while a title from that plugin plays. On the phone it sits in the icon row at the bottom, beside the subtitles one (if the row does not fit it scrolls, and the panel button is among the first); on the TV, right after the subtitles button, reachable with the remote's D-pad.
  • It does not appear if the plugin is off or damaged, if its apiVersion is below 9, if the manifest does not declare panel, or if the plugin does not export panel. On the TV, a plugin's live channel has no on-screen buttons, so it has no panel; channels in the En vivo tab do not either (on the phone, a plugin's live channel does have it).
  • The video never pauses while the panel is open. Back, or the X, closes it; it also closes when the app goes to the background and when the app's language changes.
  • While the panel loads the person sees "Cargando el panel…". If the first call fails they see the message and "Reintentar" / "Cerrar"; if a panel was already showing, the error appears as a red line and the panel stays.

The manifest: panel

"apiVersion": 9,
"panel": { "label": "Opciones", "labelEn": "Options", "icon": "tune" }
Field What it is
label 1 to 24 characters: the button's name.
labelEn Optional, 1 to 24: the name when the app is in English (label is used when it is missing).
icon Optional: one of Kino's 16 icons: info, tune (the default), settings, star, bolt, language, subtitles, list, magic, heart, movie, tv, sports, music, bookmark, help. An unknown name draws tune (and validate.mjs warns you).
iconFile Optional: your own icon, a file in your plugin's repository next to the manifest (relative path, .png). A PNG of exactly 96×96 px, with an alpha channel, at most 24 KB. Kino draws only its alpha and tints it with the button's colour (focused or not), so a full-colour image shows as its silhouette. Kino downloads it on install and on update; if it does not qualify the install fails with "The panel icon must be a 96×96 px PNG with a transparent background, at most 24 KB". If it later fails to load, the button draws tune.

icon and iconFile do not go together (the manifest is refused). Declaring panel requires exporting panel; panelAction and playerEvent are optional (an action without panelAction shows the plugin's error in the panel). An empty label, one over 24, a panel that is not an object, or an iconFile that is not a relative path to a .png are refused at install. Below apiVersion 9 the field is ignored. See also the manifest.

panel(context): what you receive

export async function panel(context) { /* returns a Panel */ }

Kino calls it when the panel opens, when a tab is pressed (with context.tab) and every refreshMs. The context carries exactly these keys (an optional field Kino does not know is left out):

Field What it is
kind "movie", "episode" or "live".
ref the ref of the title playing, exactly as you gave it.
title, year? the title and the year.
season?, episode?, episodeTitle? only for an episode.
ids the ids Kino knows for the title: tmdb, imdb, mal, anilist (tvdb and kitsu exist in the type, but Kino does not send them today).
playing the copy playing: today Kino fills only label (the name the person sees in "Servidor"); lang, quality and server exist in the type and are not sent.
positionMs, durationMs?, paused the position; the duration (absent for live or while the player does not know it); whether it is paused.
seekStepMs the back/forward step in effect (10,000 by default).
stats read-only stats, only what the player knows: width, height, videoCodec, audioCodec, bitrateKbps, bufferedMs, droppedFrames, network (wifi, ethernet, cellular or other), stallsThisSession.
device "tv" or "phone".
lang the app's language, "es-CO" or "en-US". Use it for your own texts.
tab? the tab the person asked for (absent the first time).
values what the person (or you) saved: { video: {…}, plugin: {…} }.
player the player's properties in effect: seekStepMs, speed?, resize? ("fit" if nobody changed it) and your autoNext? if you set one.
features? Kino 0.9.64, additive: what this Kino draws beyond apiVersion 9's panel; "loading" means it understands the loading element. Absent on an older Kino, which drops it as an unknown type: check it before you answer with one.

The context carries nothing about other plugins or the person's account.

Panel: what you return

return {
  presentation: "panel",       // "modal" (default) or "panel"
  title: context.title,        // up to 60 characters (also titleEn)
  accent: "#2E7D32",           // optional, #RRGGBB
  refreshMs: 10000,            // optional, 2000 to 60000
  tabs: [{ id: "info", label: "Info" }],   // optional
  tab: "info",
  elements: [ /* elements */ ],             // at most 40 at the top level
};
  • presentation: accepted for compatibility and no longer read: every panel draws the same way, as a drawer over the whole player (from the right on the TV and on a phone held sideways, from the bottom on a phone held upright), with the video visible and still playing behind it. Any value ("modal", "panel" or none) looks the same.
  • accent: a #RRGGBB that paints the top bar, the states and the focus. It follows the same contrast rules as theme's accent; if it fails, Kino's own is used and the panel stays.
  • refreshMs: asks Kino to call panel(context) again every so often while the panel is open (2000 to 60,000, clamped). Calls never overlap (the next waits for the previous one and for any action); one that fails or times out is skipped without showing an error; refreshing stops when the panel closes or the app goes to the background.
  • title and the other texts have an ...En twin (titleEn, labelEn, textEn…) shown when the app is in English, like the settings form's texts.
  • Everything is validated. An invalid element is dropped with a line in the plugin's log; a panel that is not an object shows nothing.

Elements

Every element may also carry enabled: false (shown dimmed, focus skips it) and hidden: true (not drawn). A key is 1 to 128 characters of A-Z a-z 0-9 . _ ~ - and is unique across the whole panel (a second element with the same key is dropped). Anything that can be pressed or holds a value carries a key.

type Fields Notes and limits
section title, text? a heading with optional text; title up to 60, text up to 1000.
text text multi-line text, up to 1000 characters; not selectable and does nothing.
status text a highlighted status line, up to 200 characters.
image url, aspect?, alt? https only, on a public address: Kino never reaches the device's or the home network's addresses (the one exception is a server the person typed in your plugin's settings); aspect is 16:9, 2:3, 1:1 or banner; alt up to 200. If it fails to load it takes no room and never breaks the panel.
button key, label, confirm? pressing it calls panelAction with trigger: "press". label 1 to 40 (longer, and the button is dropped). With confirm (up to 160) Kino asks first.
toggle key, label, scope, hint?, autoSave? a switch. Calls panelAction with trigger: "change".
select key, label, scope, options, hint?, autoSave? a list of 1 to 20 options { value, label } (each 1 to 40, values distinct; one bad option drops the select).
text-input key, label, scope, hint?, placeholder? a text field. Calls panelAction with trigger: "submit" only on confirm (the TV keyboard's "Listo", the phone keyboard's action), never per keystroke. placeholder up to 40.
qr url, label? a QR code plus the link's text; https only, up to 512 characters, on a public host with a dot (or a public IPv4 address): never the device or the home network (no local or single-name host, private address or IPv6 literal). On the TV it is read with the phone's camera; on the phone, tapping it opens the link. Kino never opens it by itself. label up to 40.
loading text? Kino 0.9.64, additive (any apiVersion): a spinner with text beside it (if missing, Kino's "Cargando…"). Answer at once with the tab's shell and this element, and set refreshMs so Kino asks again once you are done. Send it only when context.features includes "loading": an older Kino drops it as an unknown element (answer with a status there instead).
episodes ref the list of the playing series' episodes with the current one highlighted; choosing one plays it, through the same path as "next episode". It may be empty (a movie, for example) and then takes no focus.
row, col, card see layout containers.
ai, chat not in this version: dropped ("needs a newer Kino").

Rules for the elements that hold a value (toggle, select, text-input):

  • scope is "video" (one value per title; for a series, per episode) or "plugin" (one for all your titles; the default when you leave it out). Any other value drops the element.
  • The value on screen comes from context.values[scope][key].
  • hint up to 80 characters; the label 1 to 40; with autoSave: true (only when it is exactly true) each change saves itself (see Persistence).
  • toggle and select report 300 ms after the last change (several in a row merge into one).

Layout: rows, columns and cards

You build the panel with containers, never with pixels: only weights, gaps and an image's aspect, so nothing overflows on a TV or a phone.

{ type: "row", gap: "small", children: [
  { type: "col", weight: 4, children: [{ type: "image", url: "https://…/poster.jpg", aspect: "2:3" }] },
  { type: "col", weight: 8, children: [{ type: "text", text: "…" }] },
] }
Container Fields
row children, gap? (none, small, medium, large; 0, 8, 16 or 24 dp), align? (start, center, end, stretch), stackOnNarrow? (default true). Puts its children side by side.
col children, weight? (1 to 12; any other value is 1), gap?, align?. A column inside a row takes weight shares of its width. Any loose element in a row weighs 1.
card children, title? (up to 60), style? (plain with no border or padding, outlined with a border, filled with a background). A framed group.
  • Limits: nesting at most 4 levels deep (containers count), at most 6 children per row, at most 120 nodes in the whole panel (containers count; a dropped one does not spend any). Anything over is trimmed with a log line (at most 10 lines per panel, then "N more problems not logged"), and never breaks the panel.
  • Narrow screens. A row with stackOnNarrow (the default) stacks its children vertically, in order, when the panel's space is under 480 dp (a phone held upright, or a narrow strip). stackOnNarrow: false keeps them side by side. align: "stretch" in a row aligns to the top (it does not equalise heights); in a column it makes the children fill the width.
  • Dimmed and hidden. A container with enabled: false dims everything inside it and takes it out of focus; one with hidden: true is not drawn (a row whose children are all hidden leaves no gap).

Scroll and focus

  • The panel scrolls when the content does not fit: by touch on the phone; on the TV the focused element is always brought into view, with a margin (D-pad up/down moves focus and scrolls).
  • Text, sections, images and status lines take no focus (they are scrolled past). Buttons, inputs, episodes and qr do.
  • TV: focus starts on the first element that can take it (the close X if there is none); inside a row, left/right; between rows, up/down, in reading order. Focus does not leave the panel and Back closes it: to reach the player's controls, close it first. While the panel is open the player does not steal focus. The whole panel body is reachable with the D-pad (the QR and long text blocks are focus stops so they scroll into view) and, if the focused control disappears when your answer replaces the panel, focus returns to the first control.
  • Phone: the panel does not take focus on its own, so a text field does not raise the keyboard. The strip fits between the top bar and the bottom controls while they are shown.
  • An action's answer may ask for focus: "<key>" to move focus; it only applies on the TV, once per answer (a refresh does not repeat it).
  • A busy button (waiting for your panelAction) shows a spinner and ignores another press without dropping focus.

Tabs

tabs: [{ id, label }] (at most 6; id like a key, label up to 24, duplicates are dropped) and tab (the current one; the first if it does not exist). They draw as a strip at the top (left/right on the TV). Pressing one calls panel(context) again with context.tab: you build each tab's content. There is no tab trigger: the tab arrives in the context.

panelAction(event, context): your JavaScript is in charge

export async function panelAction(event, context) { /* returns an answer, or null */ }

It is called with two arguments. Kino only draws what you return and tells you what the person does; you can read any field, compute, call kino.fetch, kino.tmdb, kino.meta, kino.storage, and answer with a new panel, values and player actions.

event = {
  key: string,                                  // the element that fired
  trigger: "press" | "change" | "submit",       // "tab" and "open" are reserved: this version never sends them
  values: Record<string, Value>,                // the CURRENT value of every input on screen, saved or not
  value?: Value                                 // the new value of `key` on "change" and "submit"
}

press is a button; change a toggle or select; submit a confirmed text-input.

What the answer may carry

Every field is optional; null (or nothing) means "nothing to do".

Field What it does
panel replaces the whole panel (same rules as panel(context)).
patch { "<key>": element }: replaces just those elements in place (only elements that have a key: button, toggle, select and text-input; to change a text, a status or an image, return a whole panel). At most 40 keys; each entry is a single node, validated like any element and with its own 120-node budget. Kino drops it (with a log line) if the key names no element on screen, if it repeats another element's key in the panel, or if the resulting panel passes 120 nodes or 4 levels.
values { "<key>": value }: changes what the inputs show (clear one, fill one from another). At most 120 keys; each value is a string of up to 500 characters, a boolean, a finite number or null. It does not save. A key that is not an input on screen is ignored.
save ["<key>", …]: saves those inputs, each with the scope it declared (at most 50). Only keys of inputs that are on screen are saved. Also, the toggle or select with autoSave: true that fired the action saves itself, without you listing it.
focus the key to move focus to (TV).
message a short notice for the person, up to 160 characters, that Kino shows as a brief message. It goes through the same rules as a userMessage (Kino shows it as "Message from <your plugin>: …" ("Mensaje de <your plugin>: …" in Spanish), and if your plugin's name cannot introduce it, for example Cuevana3, it is dropped); if it does not pass, it is dropped with a log line.
player actions on the player: the table below.

Kino applies, in this order, panel or patch, values, save, focus, player and, last, message.

While your panelAction runs, the control that fired it shows it is busy; there is one action in flight and the others wait their turn (in order). An error or a timeout shows as the plugin's error line inside the panel, without closing it, and never leaves anything half-saved: values are written only after your action returns without error. A save that spans both scopes is saved whole or not at all.

Driving the player: player

A panelAction or playerEvent answer may carry player: { … }. Any other key inside player is ignored with a log line (the rest of player still applies). A value outside its range is clamped or dropped, also with a log line.

Property Values What it does
seekToMs a number; clamped to 0 up to the duration seeks to that position, through the same seek the other controls use (also when casting). Ignored for live. Never pauses or restarts playback. At most one seek per second per plugin, counting the panel and the events together; the rest are dropped.
seekStepMs 5000 to 120,000, in whole seconds the back/forward step (remote, keyboard, double tap and buttons); the on-screen labels follow the value ("−30", "+30"; at 10 s the usual icons stay).
speed 0.5, 0.75, 1, 1.25, 1.5, 1.75 or 2 the playback speed.
resize "fit", "fill", "zoom", "4:3", "16:9" or "21:9" the picture size.
skip { openingStartMs, openingEndMs, endingStartMs } the skip intro/outro button for this video, with the same rules as Stream.skip.
markers up to 30: { atMs, label } (label up to 24) dots on the progress bar ("Goal 63'"), also in the markers menu; choosing one seeks there. Replaces the video's list; an empty list clears it.
autoNext { enabled, countdownS, nextRef? } the end of an episode: see below.

autoNext controls what happens when a chapter of your plugin ends:

  • No autoNext, or countdownS: 0 with no nextRef: it moves to the next one at once, as always.
  • { enabled: false } (needs no countdownS): the player stays at the end, without advancing.
  • { enabled: true, countdownS: 1..30 } (with enabled: true, countdownS is required; 0 to 30): a card at the bottom right says "Siguiente en N s" with "Ver ahora" (TV focus starts there) and "Cancelar" (Back also cancels and leaves the player at the end). At zero, or on "Ver ahora", the next one plays. If the person seeks back or resumes, the countdown is cancelled.
  • nextRef suggests which one is next: it is used only if it is the ref of an episode in the series' list; otherwise Kino's own next one plays and a log line is written. With countdownS: 0 and a valid nextRef, it plays at once with no card. The countdown starts only where Kino would have advanced anyway (where a next chapter exists).

Who wins

Everything applies only while your plugin's content plays, and what the person does by hand always wins:

  • Speed and size: if the person taps the speed button or the player's zoom, your speed or resize is ignored for as long as that playback screen lasts. The person's own speed cycle does not change (0.75, 1, 1.25, 1.5 and 2); your 0.5 and 1.75 are applied and shown, and the next tap moves to the next step of the person's cycle. The TV has no speed button, so there the person cannot override yours.
  • Skip intro/outro: a manual correction by the person (the "No tiene intro/outro" button, or adjusting the times) wins over your skip. It is not saved for live channels or 18+ titles.
  • The rest (step, autoNext) you save and the person sees as part of the plugin; "Restablecer" undoes it.
  • The context (context.player) tells you what is really in effect: the person's speed if they changed it, else yours, else 1; and for resize, "zoom"/"fit" if the person touched the zoom.

Persistence and sync

  • Values with scope: "video" are stored per plugin and per title (the title's key is the playing item's: for a series, the episode); those with scope: "plugin", per plugin.
  • The player properties are stored the same way, without you writing anything: seekStepMs, speed, resize and autoNext per plugin, and markers per video. skip goes to that episode's skip button.
  • Limits: at most 50 keys per scope and values of at most 500 characters; over that, the whole write is refused with "Couldn't save: …" (in Spanish "No se pudo guardar: …"). Kino also keeps at most 1500 live values in total on the device (all scopes and all plugins); past that, the oldest per-video values go.
  • It syncs both ways across the person's devices, like everything of theirs (last write wins per key). A value that arrives from another device updates the open panel.
  • It is removed when the plugin is uninstalled.
  • Every panel has the "Restablecer" button at the bottom, which Kino provides (not you): it asks "¿Qué quieres dejar como estaba?" with "Solo este video" (clears that title's values, its markers and the skip that came from your plugin) and "Todo lo de este plugin, en todos los videos" (clears every value of the plugin and the step, speed, size and autoNext return to their defaults; skip-intro times already saved stay).

playerEvent(event, context): learning what playback does

Export playerEvent (it needs no panel) to know what happens while one of your titles plays. It is fire-and-forget: Kino expects nothing back and never blocks on it.

export async function playerEvent(event, context) {
  if (event.type === "ended") return { player: { autoNext: { enabled: true, countdownS: 8 } } };
  return null;
}

The event is flat, { type, ...detail }, and the context is the panel's own (with values):

type When Detail
started the first time the title is ready. Another copy of the same title does not repeat it.
paused, resumed when the person pauses or resumes (the intent to play changes). Buffering or a seek sends nothing.
ended once per title, only at the real end (a stream cut midway does not count), never for live.
failed an error happened (it does not mean playback is over: a copy switch or a reopen may follow). kind: for video, the player's error code name (such as "ERROR_CODE_IO_BAD_HTTP_STATUS") or "UNREACHABLE_SERVER"; for live, the error class. For live it is sent per error, within the reopen budget.
copyChanged the copy playing changed. automatic (true if Kino switched, false if the person chose), label? (the new copy) and, when automatic, kind (why the previous one failed).
  • Only started, paused, resumed and ended from the regular player are sent: a download that plays from the service and casting to another screen (Chromecast, DLNA) do not send them. failed and copyChanged still go. Channels in the En vivo tab send no events.
  • They do not overlap. There is at most one call in flight per plugin; while it runs, only the latest event that arrived is kept and sent when it ends (a waiting failed or ended is not replaced by a paused or resumed). A waiting failed can be replaced by a later copyChanged.
  • 5 s limit per call; past it the event is dropped with a log line and the next one goes.
  • Of your answer only player and message count (through the same rules as above, and the same limit of one seek per second per plugin, panel included); anything else is ignored. An error, a timeout or an invalid answer is logged and dropped: it never stops the video.
  • An answer that arrives after the person changed title is dropped.

settingsLayout: arranging your settings

Your plugin's form (Ajustes ▸ your plugin) can use the same containers. It is backward compatible: settings stays as always (keys, types, defaults, required, validateSettings…) and the layout only places settings that already exist, by key.

"settings": [ …as always… ],
"settingsLayout": [
  { "type": "card", "title": "Idioma y calidad", "titleEn": "Language and quality", "children": [
    { "type": "row", "children": [ { "setting": "preferred" }, { "setting": "maxQuality" } ] } ] },
  { "type": "text", "text": "Todo lo demás va debajo.", "textEn": "Everything else goes below." },
  { "type": "image", "url": "https://example.com/banner.png", "aspect": "banner" }
]
  • The leaves are { "setting": "<key>" }, { "type": "text", "text" } (with textEn) and { "type": "image", "url" } (https, with the panel's image rules). The containers are row, col and card (with title and titleEn) with the same limits and look as in the panel; in the form enabled and hidden are ignored.
  • A layout never hides anything: a setting you do not name is appended at the end, in manifest order. A key that is repeated or does not exist is ignored at run time (with a line in the plugin's log) and validate.mjs flags it as a problem.
  • Without settingsLayout the form is exactly as always, and an older Kino ignores the field and shows the usual list. A settingsLayout that only lists the settings in manifest order, with no containers, looks the same as the list. Below apiVersion 9 it is ignored.
  • The section setting type keeps working; a card with a title is its richer version.

The panel built with the screen kit (apiVersion 14)

Available with Kino 0.9.74

Available from Kino 0.9.74. This section needs "apiVersion": 14; an older Kino refuses these plugins with «Este plugin necesita una versión más nueva de Kino»; to keep reaching people on an older version use enhancements (see Screens without raising your apiVersion). Everything above stays valid as it is for apiVersion 9 to 13.

From apiVersion 14 the player panel can be built from the same nodes as a screen, a tab can live in another plugin's panel or on a live channel, and the person can pin the panel next to the video. The reference example is Party Chat (https://github.com/kinotvapp/kino-plugin-watch-party): a tab it contributes to any title's panel, with a room and a chat.

The panel in screen mode, on a phone The panel in screen mode, on a TV

Legacy panel and screen mode

panel(context) may return { format: "screen", root, title?, titleEn?, tabs?, tab?, refreshMs?, accent?, player?, layout? }: the same drawer (its title, tabs, refreshMs and accent follow the rules above; a tabs entry may also carry the shared badge, "dot" or { text, textEn?, color? }, drawn beside its label) with a body that is a screen tree. A result without format is the legacy panel, read and drawn exactly as before; the format may change from one call to the next, and below apiVersion 14 a screen result is read as a legacy panel (logged).

export async function panel(context) {
  if (!(context.features || []).includes("screen")) return { title: "Party Chat", elements: [{ type: "status", text: "Actualiza Kino" }] };
  return { format: "screen", title: "Party Chat", root: { type: "Column", children: [{ type: "ElevatedButton", labelText: "Sincronizar", onPressed: "sync" }] } };
}
What In a panel in screen mode
Result { format: "screen", root, title, titleEn, accent, refreshMs, tabs, tab, player, layout }
Tree depth 6, 200 nodes; AlertDialog, BottomSheet and PopupMenuButton not drawn, unless it has an anchor (a popover inside the drawer, see anchor); no every
Context adds state, size, and features holds "screen" while screens are on
panelAction triggers press, change, submit
Answer fields kept state, toast, toastEn, ui, config, go, close, focus, player, message, pause, panel
Answer fields dropped dialog, sheet, menu, route, share, enableJob; legacy-only patch, values, save

Differences from a full screen:

  • Limits: depth 6 and 200 nodes. A popup node is dropped (pop-ups belong to the screen, not to the drawer) unless it has an anchor, and every is dropped: refreshMs (2,000 to 60,000 ms, only while the panel is open) is THE periodic call.
  • Calls: renders call panel(context); the person's events call panelAction({ event, context }) with event = { key?, trigger, name, arg?, value?, values } (trigger is press, change or submit; tab and open stay reserved); there is no reserved open event. An apiVersion 14 plugin's context carries state (Kino's, kept for this title's playback) and size (the drawer's classes; Kino's estimate until it measured itself) in every call, the first one included, because Kino cannot know the format before your answer. See state and per-size values.
  • Answers: state, toast, ui, config, focus, go (every shape; all but screen and close close the panel first), close, and the legacy player, message, pause and panel are kept; dialog, sheet, menu and route are not honoured, and patch, values and save are legacy-only (dropped, logged). A playerEvent answer's panel (either format) shows in that title's open panel, but its state is never applied: keep that in your own variables or kino.storage. See answers.
  • Detect the format: answer a screen result only when context.features includes "screen". Kino puts it there only while plugin screens are switched on; when they are off a screen result shows no panel, so answer a legacy one then.
  • Errors: a failed event shows the drawer's error line at once; three in a row show the panel's error state.
  • TV: a toast's action runs from the remote's Menu or Play/Pause key (the drawer has no Down-to-toast). The panel's text is a step smaller than a full screen's (the drawer and the dock are 360 to 480 dp wide): h1 draws at a screen's h3 size, h2 at h4's, h3 at h5's, h4 and h5 at the large body size, p at 15 sp; the phone's sizes do not change.
  • TV focus: in any panel, legacy or screen mode, only what does something takes focus and Kino's ring: buttons, toggles, selects, fields, the episode list, the tabs, pin and close. A text, a section, a status, an image or a QR is never a focus stop and never boxed: Up and Down page through them. When an answer's new tree no longer has the focused node (a QR view replacing the pressed button), focus goes to the focusable now at or after its place; with none, the body itself takes it (no ring) so Up and Down still scroll it. An answer's focus wins.
  • Kino's own tab about the title shows, top to bottom, the poster with the title and its facts, the synopsis, the details, the images and last the cast (three cards a row, two on a panel under 360 dp), each part only when TMDB has it.
  • Kit: node sdk/run.mjs --state '<json>' --screen <folder> panelAction <ref> <name> <press|change|submit>.

Layout fill: a chat tab

A panel's body scrolls by default (layout: "scroll"): the tree has no height limit, so a ListView draws flat and flex does nothing, and a row after a list sits right under its last item. A chat wants the opposite: the messages take the room and the input row stays at the bottom of the panel, like any chat app. Answer layout: "fill" (chosen per result: beside root in a panel() result, on the root object of a screen() answer): the root is drawn at the body's size with no body scroll, flex shares the height left, and a ListView with flex is lazy and scrolls itself.

export async function panel(context) {
  const messages = ((context.state || {}).messages || []).map((m, i) => ({ type: "Text", key: "m" + i, text: m }));
  return { format: "screen", title: "Party Chat", layout: "fill", root: { type: "Column", gap: 8, children: [
    { type: "Text", text: "Sala 1234", style: "h4" },
    { type: "ListView", key: "chat", flex: 1, stickToBottom: true, items: messages,
      empty: { type: "Text", text: "Sin mensajes", textEn: "No messages", color: "muted" } },
    { type: "Row", gap: 8, children: [
      { type: "TextField", key: "msg", flex: 1, hintText: "Escribe…", hintTextEn: "Type…" },
      { type: "IconButton", icon: "send", labelText: "Enviar", labelTextEn: "Send", onPressed: "send" },
    ] },
  ] } };
}
  • Where the bottom row goes: at the bottom of the panel, docked (pinned) or in the drawer, upright or sideways, however many messages the list holds; when the panel opens again (a return to Kino, a rotation) it is there too. The phone's keyboard lifts it: the dock and the drawer end above the keyboard, and the list gets the height left.
  • stickToBottom: the list opens at the last message and follows new ones while the person reads the end; scrolled up to read older ones, it stays put until they come back down.
  • TV: Up and Down page through a list with nothing to focus (messages), and leave it at its ends toward the controls.
  • Too tall: when the parts without flex alone are taller than the panel (a short window, a big keyboard), Kino draws that render in the scroll layout and logs screen: layout fill does not fit, using scroll once; it tries fill again when the size or the root's children change. A panel root's own layout is ignored (logged): put it beside root.
  • Full screens already draw the root at the screen's size with no scroll of their own (what fill does), whatever layout says. Any other value is logged and read as scroll.

A tab in another plugin's panel (playerPanelTab)

"apiVersion": 14,
"capabilities": ["playerPanelTab"],
"panel": { "contributes": true, "label": "Party Chat", "icon": "mood" }

"panel": { "contributes": true, "label"?, "labelEn"?, "icon"? | "iconFile"? } with the capability playerPanelTab (each needs the other; it exports panel and may stand alone) adds your tab to the player panel of any plugin's title. A missing label is your plugin's name (cut to 24 characters).

  • The drawer becomes a tab host: Kino's own information tab first (fixed), then the playing plugin's panel (with its own tabs), then the contributed tabs in the person's order (Ajustes, «Paneles del reproductor»; install order by default), at most 6. Each tab shows its plugin's name and icon, never Kino's info icon; a name that reads like "Kino" is shown as «Plugin «name»». The id kino is reserved. Without a contribution the drawer is exactly as before.
  • When you are called: only while your tab is the selected one and the drawer is open (refreshMs only then), and playerEvent only while your tab is open (copyChanged without its label). Nothing runs in the background: when the person switches tabs or closes the drawer, you stop (pin the panel to keep running).
  • What you see (an allow-list): kind, title, year, season, episode, episodeTitle, ids, positionMs, durationMs, paused, seekStepMs, stats, device, lang, your tab, values, features, state and size; of player, only seekStepMs, speed and resize; plus foreign: true, source: { pluginId, name } (the plugin that provides the stream) and ref, an opaque id: "foreign:" and 32 hex characters, the same for the same title on this install for your plugin, different for another plugin or install. It is opaque, not secret. Never the owner's playing copy or its autoNext.
  • Where not: never on an 18+ title, any title of an 18+ plugin (an 18+ contributor only while the code is unlocked), your own titles (there you are the owner), M3U lists, own channels or other non-plugin content.
  • What you may do: your go.title and go.play are dropped (you cannot open the playing plugin's content); search, browse, section, categories, screen, titleByIds, url and close work (see go). Your player actions count only in the answer to a panelAction after a press in your tab, and only seekToMs; with playerControl also pause and speed, from any origin. Your episode list draws nothing.
  • Kit: node sdk/run.mjs --foreign <source plugin id>[:<name>] <folder> panel <ref> gives your calls the foreign context.

The texts a manifest is refused with:

Problem Text
contributes is not a boolean The "panel.contributes" field must be true or false
contributes without the capability The "panel.contributes" field needs the "playerPanelTab" capability
the capability without contributes The "playerPanelTab" capability needs "panel": { "contributes": true }

playerPanelTab needs the person's approval with a red line, at install and on the update that adds it (Kino never approves it on its own; a kit import starts it unticked):

«Su pestaña en el reproductor verá lo que estás viendo (título, año, identificadores y posición, o el canal en vivo) mientras la tengas abierta, y podrá enviarlo a sus servicios» ("Its tab in the player will see what you are watching (title, year, ids and position, or the live channel) while you have it open, and can send it to its services")

The person can hide it with «Mostrar en el reproductor» ("Show in the player", in your tab in Ajustes; it covers the whole device and syncs to their other devices) or reorder it (Ajustes, «Paneles del reproductor»). See the consent model.

Your tab on a live channel ("kinds": ["live"])

Every En vivo channel has the same player panel (Right on the TV remote; the panel button in the live band on a phone), with Kino's own General tab first (the favourite and the channel's brightness). Add "kinds": ["title", "live"] (or ["live"]) to your "panel": { "contributes": true } and your tab joins it after General (default ["title"]: titles only, as before). The consent is the same capability (playerPanelTab).

"panel": { "contributes": true, "label": "Party Chat", "kinds": ["title", "live"] }
  • What you see: kind: "live", live: true, channel: { provider, code, name } (the plugin that lists the channel, its id there, its name), foreign: true, source, device, lang, your tab, values (video is one set for every live channel: the session stays open across zaps), features, state and size. No ref, title, ids, position, duration, pause, stats or player: live has no seek and no pause that matters.
  • When: as on a title, only while your tab is selected and the panel open. On a zap Kino calls panel again with the new channel (the panel stays open); there is no playerEvent on live.
  • Where not: a channel its provider's own listing has not confirmed as not 18+, a channel of an 18+ provider, «Mis canales» (the person's own M3U lists and channels) and saved legacy channels: your tab is not there.
  • What you may do: every player action is dropped (panel: player actions do nothing on a live channel, dropped (live_channel)). go.liveChannel { provider, code } tunes the player to a channel after the person's press (in the panel on live it changes in place): how a room's guest watches the host's channel.
  • Kit: node sdk/run.mjs --live-channel <provider>:<code>[:<name>] <folder> panel -.
Problem Text
kinds empty, unknown or not a list The "panel.kinds" field must be a non-empty list of "title" and "live"
kinds without contributes The "panel.kinds" field needs "panel": { "contributes": true }

The pinned panel

Kino's own, for every panel: «Fijar» / «Pin» in the panel's header (a pin icon alone on a TV) docks it next to the video:

  • the right third on a TV or a landscape window of 600 dp or more; below the video on an upright phone, whose video then gets at least 300 dp or 38 % of the height for its controls;
  • not offered in picture-in-picture, while casting, or in a narrow landscape window.

Docked, the video keeps playing and the panel's sessions, refreshMs and playerEvent keep running while Kino is in front. The pin lasts for the playback: it survives a rotation and the next episodes played in the player, and a new playback starts unpinned (it is not remembered, stored nor synced). The panel only opens when the person opens it.

On a TV: Right from the last control of the player's row (of either row) goes into the panel, on «Desfijar» first, and with the controls hidden Right on the video does too; Left past its edge goes back to the controls; the first Back hides the panel (it stays pinned: opened again, it docks again) and the next Back is the player's. A pop-up or dialog over the panel takes that first Back. While the panel is docked on a TV or a phone held sideways, the player's two groups of buttons sit one row under the other.

Nothing in the plugin contract changes; a plugin that must keep running (Party Chat) tells its people to pin it for the playback.

Robustness

  • A failure never stops the video. The panel runs in the plugin's sandbox; an exception, a timeout or an invalid shape show a contained error state (with your userMessage if there is one) and the video keeps playing.
  • Time limits: panel and panelAction, 20 s each; playerEvent, 5 s.
  • One panelAction in flight (the others wait in order, refreshes too); quick changes to the same input merge into one (300 ms).
  • Validation: everything you return is checked against the contract; what is invalid is dropped with a line in the plugin's log, and a wholly invalid panel shows the error state. Messages are cleaned like a userMessage.
  • A late answer to an action that no longer applies (the panel closed, the title changed, or it was reset) writes nothing.

Trying it with the kit

The Node kit (sdk/run.mjs) runs the three functions with a fake context (a title "Demo", tmdb: 550, position 10:00 of 1:30:00, TV, es-CO) and validates the answer with the same rules and the same log texts as Kino:

node sdk/run.mjs . panel <ref> [tab]
node sdk/run.mjs . panelAction <ref> <key> <press|change|submit> ['<value json>'] ['<values json>']
node sdk/run.mjs . playerEvent <ref> <type> ['<detail json>']
node sdk/run.mjs --context '{"lang":"en-US","kind":"episode","device":"phone"}' . panel <ref>
  • --context merges your JSON over the fake context (for example lang, kind, paused, values, tab).
  • The validated answer goes to stdout; each dropped element goes to stderr as · dropped: <reason>. The exit code is 1 if the whole panel is invalid and 2 if an argument is wrong. playerEvent without that export says Kino will never call your plugin for events.
  • sdk/validate.mjs checks the manifest: panel, the iconFile (96×96, alpha, 24 KB, from disk), an unknown icon (a warning), a panel or layout below apiVersion 9 (ignored) and settingsLayout (a repeated or unknown key is a problem).

See also Test it locally.

A complete small example

kino-plugin.json:

{
  "id": "mi-plugin", "name": "Mi plugin", "version": "1.0.0", "apiVersion": 9,
  "entry": "plugin.js", "hosts": ["example.com"], "capabilities": ["search", "resolve"],
  "panel": { "label": "Opciones", "labelEn": "Options", "icon": "tune" }
}

plugin.js:

export async function search() { return []; }
export async function resolve() { throw kino.error("not_found", "example"); }

export async function panel(context) {
  const en = context.lang.startsWith("en");
  const left = Math.max(0, Math.round(((context.durationMs ?? 0) - context.positionMs) / 60000));
  return {
    presentation: "panel",
    title: context.title,
    accent: "#2E7D32",
    refreshMs: 10000,
    elements: [
      { type: "status", text: en ? `${left} min left` : `Faltan ${left} min` },
      { type: "row", gap: "small", children: [
        { type: "button", key: "back30", label: "−30 s" },
        { type: "button", key: "faster", label: en ? "Speed 1.25x" : "Velocidad 1,25x" },
      ] },
      { type: "toggle", key: "remember", label: en ? "Remember this copy" : "Recordar esta copia", scope: "video", autoSave: true },
      { type: "text-input", key: "note", label: en ? "Note" : "Nota", scope: "video", placeholder: "…" },
    ],
  };
}

export async function panelAction(event, context) {
  if (event.key === "back30") return { player: { seekToMs: Math.max(0, context.positionMs - 30000) } };
  if (event.key === "faster") return { player: { speed: 1.25 }, message: "Velocidad subida" };
  if (event.key === "note" && event.trigger === "submit") return { save: ["note"], message: "Nota guardada" };
  return null; // "remember" (autoSave) needs nothing else
}

export async function playerEvent(event) {
  if (event.type === "ended") return { player: { autoNext: { enabled: true, countdownS: 8 } } };
  return null;
}

And what the kit prints:

$ node sdk/run.mjs . panel m1
{ "presentation": "panel", "title": "Demo", "accent": "#2E7D32", "refreshMs": 10000, "tabs": [], "tab": null,
  "elements": [ { "type": "status", "text": "Faltan 80 min" }, { "type": "row", … }, … ] }
$ node sdk/run.mjs . panelAction m1 back30 press
{ "player": { "seekToMs": 570000 } }
$ node sdk/run.mjs . panelAction m1 note submit '"hola"' '{"remember":true,"note":"hola"}'
{ "save": [ "note" ], "message": "Nota guardada" }
$ node sdk/run.mjs . playerEvent m1 ended
{ "player": { "autoNext": { "enabled": true, "countdownS": 8 } } }

Note: remember saves itself (autoSave), the note only when the person confirms it (save), and the message has no digit glued to a letter ("Velocidad 1,25x" would have been dropped by the userMessage rule).

What the kit cannot check

The kit runs each call on its own, without a player session's state. Only Kino applies these rules:

  • The patch rules that need the panel on screen: that the key names an element, that it does not repeat another element's key, and that the resulting panel stays within 120 nodes and 4 levels. The kit validates each patch entry on its own (and notes it).
  • The cap of one seek per second per plugin, counting panelAction and playerEvent together.
  • values and save keys that name no input on screen (they are ignored), and whatever depends on what is stored: the scopes, the 50-key and 500-character limits, "Restablecer".
  • That a message containing one of the person's own passwords is refused (the kit applies the other userMessage rules).
  • Everything that depends on the device: the real context (the stats, the copy, the ids that are known), the layout and focus on the TV and the phone, how the icon looks, and who wins (the person's speed or zoom).
  • The tab and open triggers: the kit accepts them because they are reserved, but Kino 0.9.55 never sends them.
  • The real player events: with playerEvent you call them by hand.