Rooms, the library and player control¶
Available with Kino 0.9.74
Available from Kino 0.9.74. 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).
Three capabilities give your plugin a reach beyond its own source:
library: read what the person watched and saved in Kino (below).playerControl: pause, resume and move the video by itself, not only right after the person presses a button (below).room: open a room that other people reach over the Internet through the person's device (below).
All three are declarative (you export nothing new: you declare them in capabilities) and all three have a red
consent line the person approves. A screen (screen) or a tab of the
player panel is what uses them.
The reference example is Party Chat (https://github.com/kinotvapp/kino-plugin-watch-party): a player-panel tab, on
any title of any plugin, that opens a room, shares it with a code and a QR, keeps everyone at the same point of the video
with playerControl and carries a chat. It shows everything on this page.
Consent¶
None of these capabilities is approved on its own. Kino asks the person in its own words, which you cannot change or hide:
| Capability | What the person reads | Red, waits for approval | The person's switch (your tab in Ajustes) |
|---|---|---|---|
library |
«Podrá leer lo que has visto y guardado en Kino, cuánto lo ves y a qué hora, y enviarlo a sus servicios» ("Can read what you have watched and saved in Kino, how much and at what time of day, and send it to its services") | yes | «Dejar que lea lo que he visto y guardado» ("Let it read what I watched and saved") |
playerControl |
«Podrá pausar, reanudar y mover tu video por sí solo» ("Can pause, resume and move your video by itself") | yes | «Dejar que pause y mueva mi video» ("Let it pause and move my video") |
room |
«Podrá abrir una sala a la que se entra por internet a través de este aparato, y enviar los mensajes de la sala a quienes entren» ("Can open a room that people reach over the Internet through this device, and send the room's messages to whoever joins") | yes | «Dejar que abra salas por internet» ("Let it open rooms over the Internet") |
- A red line is asked at install and again on the update that adds it, and Kino never approves it on its own; the
kit's import starts it unticked. Until the person approves it the API refuses (
permission_denied), so always handle that refusal and work without it. - Each switch is in your plugin's tab in Ajustes, covers the whole device and every profile, and syncs to the person's other devices. Off, the API refuses at once (a room closes).
- Kino lists your declared hosts beside the line: these lines are the safeguard, not a technical wall. A plugin that can
fetchcan send what it reads to its hosts. - Be honest in your own UI too: say what you send and where.
The whole model, with the other capabilities that go with screens, is in Screens.
Reading what the person watched (library)¶
"apiVersion": 14,
"capabilities": ["screen", "library"]
library may stand alone or beside screen (a plugin that declares only library is still valid, but can never read
it: see when).
const watched = await kino.library.watched({ limit: 20, kind: "movie", sinceMs: Date.now() - 30 * 86400000 });
const saved = await kino.library.saved({ limit: 50 });
kino.library.watched({ limit?, kind?, sinceMs? }) and kino.library.saved({ limit?, kind? }) answer what the active
profile watched and saved, newest first, one entry per title:
interface KinoLibraryEntry {
title: string; // as Kino shows it (TMDB's when Kino identified it), at most 200 characters
year?: number; // only when Kino knows it; usually absent on a watched one
kind: "movie" | "series";
ids: { tmdb?: number; imdb?: string }; // each only when Kino knows it; may be empty
progress?: number; // watched only: 0..1 in steps of 0.01 (1 when finished)
watchedAtMs?: number; // watched only: rounded down to the day (UTC midnight)
season?: number; // watched series only (apiVersion 15): the season of the latest chapter played
episode?: number; // watched series only (apiVersion 15): the number of that chapter
}
-
seasonandepisode(from Kino 0.9.77): on a watched series, the latest chapter played, only when its source numbered it. Never on a movie or on a series with no numbered chapter. -
kindismovieorseriesand works as a filter; music and podcasts are left out. limit: default 50, at most 100 (above 100 gives 100).sinceMskeeps titles played on that day (UTC) or later. A number that is not finite isbad_request.
From apiVersion 17, kino.library.stats({ month? }) answers a month's aggregates (seconds watched, by kind and by time of day,
titles, active days and a top) with this same capability and the same switch: see
kino.library.stats.
What never comes¶
- Never: a stream URL, a plugin ref, a Kino id, a position in seconds, a profile name, anything of another profile, or an 18+ title (always left out, even with the 18+ code unlocked; a title whose source this device cannot place is left out too: it fails closed).
- Coarse on purpose:
watchedAtMsandsinceMsare rounded down to the day (UTC),progressto steps of 0.01, so nothing finer can be probed. Titles watched on the same day come in Kino's own order.
When it can be read¶
- Only inside a call the person started:
screen,screenEvent(timer ticks count while the screen is in front),home,section,search, and a background job with this approval. Never in prewarm or sync calls. A plugin with onlylibrarycan therefore never read it. - At most 30 calls a minute per plugin.
- Kino keeps nothing of an answer; a Home answer you build from it is cached like any Home answer.
Errors and detection¶
permission_denied(not approved, or switched off),rate_limited,bad_request.- Feature-detect with
typeof kino.library === "object"and still catchpermission_denied: a plugin whoselibrarycame through anenhancementsblock on a Kino updated after the install is asked only with its next version.
async function recentMovies() {
if (typeof kino.library !== "object") return [];
try {
return await kino.library.watched({ limit: 20, kind: "movie" });
} catch (e) {
if (e && e.code === "permission_denied") return []; // not approved or switched off: work without it
throw e;
}
}
- Kit:
KINO_LIBRARY_FIXTURE=<json>stands in for the person's data andKINO_LIBRARY_REVOKED=1plays the switch off.
Moving the video (playerControl)¶
A declarative capability (no export) that never stands alone: only beside a panel, your own (panel) or a tab you
contribute to other plugins ("panel": { "contributes": true } with playerPanelTab, see
the player panel). Without a panel the manifest is refused with
"The \"playerControl\" capability needs a \"panel\" ...".
"apiVersion": 14,
"capabilities": ["screen", "playerPanelTab", "playerControl", "room"],
"panel": { "contributes": true, "label": "Party Chat" }
With playerControl a player action may also carry pause: true pauses, false resumes (any other value is
dropped). It is a one-shot command: never stored.
Without the capability and with it¶
Every player action has an origin: press, change or submit (what the person does in the panel), refresh (a
panel result's own player: on open, on a tab, on a refreshMs tick, or a playerEvent answer's new panel) and event
(a playerEvent answer).
| Who | Without playerControl |
With playerControl |
|---|---|---|
| The plugin whose title plays | The apiVersion 9 rules: every player field after the person's press, change or submit and in a playerEvent answer; pause only after a press; a panel result's own player never counts. |
Every origin counts: press, change, submit, refresh and event. |
| A tab contributed to another plugin | Only seekToMs, only after a press in your tab. |
seekToMs, pause and speed, from any origin. |
So a refreshMs tick can keep the video in step with the room without anybody touching anything.
What Kino still enforces¶
The same for every plugin (contract.json kinoPlayerControl):
- One seek or pause a second per plugin, always (the panel and its
playerEventcalls together). - An action kept only thanks to the capability is dropped while Kino is not in front (the player covered or in the background), while one of Kino's dialogs is up, or while the person is seeking.
- On a live stream, only
pause. - At most 30 a minute.
- A pause is dropped while the phone's player is held for a cast (Chromecast or DLNA), and when it asks for the state the video is already in (no notice, no budget).
- A panel nested in an answer carries no
playerof its own. - When the action does not come from the person's press (
refreshorevent), Kino shows a short notice naming your plugin, which you cannot word or suppress: «Party Chat: pausado», «Party Chat: reanudado, movido a 1:02:03» (in English "Party Chat: paused", "resumed", "moved to {time}", "speed {speed}"). A name that reads like "Kino" is shown qualified. - A contributed tab's speed is never stored: it ends with the title, and the person's own speed wins.
The player properties (seekToMs, speed, resize…) and who wins against the person are in
Driving the player.
- Kit:
KINO_PLAYER_CONTROL_REVOKED=1plays the switch off.
Rooms over the Internet (room)¶
A declarative capability that never stands alone: a screen or a player-panel tab drives it. kino.room is a
short-lived mailbox hosted on the person's own device and reached from the Internet through the same Cloudflare quick
tunnel Kino opens for «Recibir configuración»: no server of yours or Kino's, and your code never sees an address.
const { code, words, expiresAtMs } = await kino.room.open({ ttlMin: 120, max: 6, name: "Ana" }); // the host, from a press
const { handle, memberId } = await kino.room.join({ words, code, name: "Beto" }); // a guest, from a press
await kino.room.send({ t: "chat", text: "hola" }); // a JSON object
const { events, last, more, reachable } = await kino.room.inbox({ since: state.last }); // poll it from a timer
Feature-detect it with typeof kino.room === "object".
The functions¶
| Function | What it does |
|---|---|
open({ ttlMin?, max?, name?, codeDigits?, code? }) |
Opens the tunnel and the mailbox. ttlMin 10 to 240 (default 120); max members counting you, 2 to 8 (default 6); name, your name as the guests see it, up to 40 characters. Answers { code, words, expiresAtMs }. |
join({ words, code, name? }) |
Joins a room with the words and code the host shared; name up to 24 characters. Answers { handle, memberId, host: { name }, expiresAtMs }. Keep handle: it names this session in the other calls. |
send(payload, { to?, session? }) |
Sends a JSON object of at most 8192 bytes and 4 levels. The host writes to one memberId or everyone (to absent or "all"); a guest to the host (to absent or "host") or to "all" through the host, never to another member directly. |
inbox({ since?, limit?, session? }) |
Answers { events, last, more, reachable }: the events after since (pass the answer's last next time), at most limit (1 to 50, default 50). |
members({ session? }) |
[{ memberId, name, host }]: never an address. |
close({ session? }) |
Closes the session (or the room, if you are the host). |
state() |
{ role: "host" \| "guest" \| "none", joined: [...], hosted: { code, words, expiresAtMs, members } \| null }: your plugin's sessions on this device. |
wordsare public (brave-river-cat-moon): anyone may see them. Thecodeis the room's only secret: 12 digits, or the ones you ask for withcodeDigits(4 to 12). Show it grouped, «1234 5678 9012», and as a QR; spaces and hyphens are ignored onjoin.joinneeds both.- An event is
{ seq, from, kind, payload?, name? }:kindismsg,join,leaveorclosed;fromis amemberIdor"host";payload(msgonly) is the object the sender passed, re-serialised by Kino;name(joinonly) is the member's name.seqonly grows. reachable: falsemeans a guest's last poll of its host got no answer: your failover cue. A guest asks its host at most once a second.sessionis"hosted"(the room this device hosts) or ahandlefromjoin. Absent: the first joined session, else the hosted one.- A member the host has not heard from for 2 minutes is dropped (
leave).
A short code¶
open({ codeDigits: 4 }) makes a code friends can type. It keeps strangers out only because the words cannot be
guessed and the room closes itself after 30 wrong codes (Kino tells the person; your next calls get room_closed).
Whoever captures the traffic and knows the words, the tunnel provider among them, recovers a 4-digit code offline in
milliseconds: such a room is not private from the provider. The default 12 digits makes that expensive, not impossible.
Keep a room's messages low-sensitivity either way.
When it can be called¶
openandjoinonly from the person's own press (screenEvent,panelAction; never a tick or a refresh), so a plugin can never move a person into a room, or open one, behind their back.send,inboxandmembersfrom your screen's or panel's calls (screen,screenEvent,panel,panelAction,playerEvent), ticks included, only while Kino is in front.closeandstatefrom any live call.- Never from a background job (there
kino.roomanswersnot_allowed).
Limits¶
| What | Limit |
|---|---|
| A message | at most 8192 bytes (UTF-8, as your plugin's JSON text) and 4 levels (the object itself is 1) |
| Rate per member | 5 messages a second; 100 messages and 256 KB a minute (checked by the sender's Kino and again by the host) |
| Members | 2 to 8 (default 6) |
| Lifetime | 10 to 240 minutes (default 120) |
| Mailbox | 200 events or 15 minutes per member |
| Sessions per device | 2 joined and 1 hosted; at most 2 of them for one plugin (room_busy) |
| Wrong codes | 5 lock joins for 60 s, doubling up to 30 minutes (rate_limited); 30 in all close the room |
A room closes at its lifetime, with close(), when the plugin is removed, disabled or the person switches it off, when
plugin screens are switched off in Kino, and after 30 minutes of Kino in the background. While the device hosts a room,
Android shows Kino's own notification «Sala abierta · N personas» with «Cerrar sala» and keeps the room alive, so the host
can step out to paste the invitation; the person swiping Kino away closes it.
While the device hosts a room, your tab in Ajustes shows it with a button to close it.
Errors¶
room_denied, room_closed, room_full, room_unreachable, room_busy, rate_limited, permission_denied,
bad_request. room_unreachable (no internet, a network that blocks it, Cloudflare's rate limit) and the room refusals
carry Kino's own userMessage.
Security, said plainly¶
- Every request is sealed (scrypt N=8192 r=8 of the code salted with the words, AES-256-GCM plus HMAC-SHA256, per-member keys) and messages are never stored, logged or executed by Kino.
- The code protects against casual access, not against the tunnel provider. A stranger can only guess online (and gets locked out), but the TLS-terminating provider, targeting a room, could crack a captured join offline (about 400 GPU-days on average on one high-end GPU) and then read it; there is no forward secrecy. Keep a room's messages low-sensitivity (a chat, a position). A password-authenticated exchange (CPace or SPAKE2) is recorded as future hardening.
- Payloads are untrusted: check every message's kind, exact fields, sizes and types; scrub names; cap texts; never execute or render one as markup. Never put the code in a message or a log.
What is yours¶
Who leads, what a message means, history and failover are yours. With open({ code }) a member opens a second door to
the same room with its own words (refused with permission_denied unless your plugin is in that room now or opened it;
its expiry is capped at the room's); publish its words a few seconds later (a fresh name takes a moment to resolve). Send
a goodbye before close(). Party Chat shows all of it.
- Kit: an in-memory room with two simulated members (
createKitRoom()in tests:say,leave) andKINO_ROOM_REVOKED=1for the switch off.
Trying it with the kit¶
node sdk/validate.mjs <folder> # the manifest, the exports, every consent line
node sdk/run.mjs --foreign latino:Latino <folder> panel <ref> # a tab you contribute to another plugin's title
node sdk/run.mjs --state '{}' --screen <folder> panelAction <ref> <name> press
| Variable | What it plays |
|---|---|
KINO_LIBRARY_FIXTURE=<json> |
the person's data for kino.library |
KINO_LIBRARY_REVOKED=1 |
library switched off |
KINO_PLAYER_CONTROL_REVOKED=1 |
playerControl switched off |
KINO_ROOM_REVOKED=1 |
room switched off |
In node --test files, import the kit's helpers (createKino, createKitRoom…) as Party Chat's tests do. More in
Testing screens with the kit.
Limits in one place¶
| What | Limit |
|---|---|
kino.library |
limit default 50, at most 100; at most 30 calls a minute per plugin; times rounded to the day, progress to 0.01 |
playerControl |
one seek or pause a second per plugin; at most 30 actions a minute |
kino.room |
a message at most 8192 bytes and 4 levels; 5 messages a second, 100 and 256 KB a minute per member; 2 to 8 members; 10 to 240 minutes (default 120); mailbox 200 events or 15 minutes; 2 joined and 1 hosted per device, 2 per plugin; 5 wrong codes lock joins for 60 s, doubling up to 30 minutes; closed after 30 minutes in the background (a hosted room shows Kino's notification meanwhile) |