El hueco del reproductor (playerSlot, apiVersion 23)¶
Próxima versión de Kino, todavía sin publicar
El apiVersion 23 llega con la próxima versión de Kino (provisionalmente la 0.9.83), que todavía no está publicada. Un Kino
que no lo tiene rechaza un manifiesto con la capacidad playerSlot o el bloque slot ("Este plugin necesita una versión
más nueva de Kino"). Para seguir corriendo en Kinos anteriores, conserva tu apiVersion y agrega los dos como
mejora (enhancements["23"]: "capabilities": ["playerSlot"], "slot": { ... }).
Un plugin puede poner hasta tres cosas pequeñas en la esquina superior derecha del reproductor de la TV: un reloj, un
marcador, un logo, un botón que abre el panel del reproductor del plugin. Kino llama a dos funciones tuyas,
playerSlot(context) para llenar los elementos y playerSlotAction({ id, context }) cuando la persona aprieta un botón, y
dibuja lo que respondes con su propio aspecto. Como en una pantalla, tú describes y Kino dibuja: nada de vistas,
colores ni píxeles.
- Solo en la TV. El reproductor del teléfono no cambia: ningún elemento, ninguna llamada.
- Películas, series y canales de En vivo. Lo que cambia en un canal está más abajo.
- Tres elementos en pantalla en total, entre todos los plugins. Primero los
fixed, después los que salen con los controles; el orden de plugins de la persona (Ajustes, "Paneles del reproductor", la misma lista que las pestañas del panel) desempata y los demás no se dibujan. - Ningún destino de red nuevo. El hueco usa los hosts que el plugin ya declara; una
imagela carga Kino desde cualquier dirección https pública.
Los números de esta página salen de contract.json (playerSlot); las formas están en
kino.d.ts (KinoManifestSlot, KinoSlotContext, KinoSlotAnswer, KinoSlotActionAnswer).
Un primer hueco: un reloj¶
El ejemplo completo es el reloj del reproductor (versión 1.1.0): la hora y la fecha en español o en inglés, en un único
elemento de texto overlay, sin red. La persona lo viste en los ajustes del plugin: zona horaria (la del aparato por defecto),
tamaño, grosor, color, fondo y posición (ver Vestir un texto). Sus módulos están en src/ y scripts/build.mjs los
junta en plugin.js (Kino carga un solo archivo).
Descargas: kino-plugin.json ·
plugin.js · src/clock.js ·
src/index.js · scripts/build.mjs
kino-plugin.json (lo esencial; la descarga trae el formulario de ajustes completo, con sus textos en inglés y todas las opciones)
{
"id": "player-clock",
"version": "1.1.0",
"apiVersion": 23,
"entry": "plugin.js",
"hosts": ["kinotvapp.github.io"],
"capabilities": ["playerSlot"],
"slot": { "elements": [{ "id": "clock", "kind": "text", "mode": "overlay" }] },
"settings": [
{ "key": "timezone", "label": "Zona horaria", "labelEn": "Time zone", "type": "select", "default": "auto",
"options": [{ "value": "auto", "label": "La del aparato (por defecto)", "labelEn": "This device's own (default)" },
{ "value": "-5", "label": "UTC-5 · Colombia, Perú, Nueva York", "labelEn": "UTC-5 · Colombia, Peru, New York" }] },
{ "key": "size", "label": "Tamaño del texto", "labelEn": "Text size", "type": "select", "default": "normal", "options": [] },
{ "key": "weight", "label": "Grosor de la letra", "labelEn": "Letter weight", "type": "select", "default": "auto", "options": [] },
{ "key": "color", "label": "Color de la letra", "labelEn": "Letter colour", "type": "select", "default": "auto", "options": [] },
{ "key": "background", "label": "Fondo de la pastilla", "labelEn": "Pill background", "type": "select", "default": "default", "options": [] },
{ "key": "left", "label": "Horizontal", "labelEn": "Horizontal", "type": "select", "default": "0", "options": [] },
{ "key": "top", "label": "Vertical", "labelEn": "Vertical", "type": "select", "default": "0", "options": [] }
]
}
("options": [] representa la lista de la descarga: un select necesita al menos una opción.)
src/index.js (la entrada; src/clock.js convierte una Date y context.lang en "21:05\nmié 4 nov")
// Player clock: an example of the player slot (apiVersion 23). One overlay text element in the top-right corner of the TV
// player shows the time and the date with the controls; Kino asks again every minute. The person dresses it in the plugin's
// settings: the time zone (the device's own by default), the size of the text, its colour, the pill behind it and where it sits.
// No network, no buttons.
import { clockText, offsetMinutes } from "./clock.js";
/** Letter colours and pill fills the settings offer; "auto" and "default" send nothing, so Kino draws its own. */
const COLORS = { white: "#FFFFFF", yellow: "#FFD54F", cyan: "#4DD0E1", green: "#81C784", orange: "#FFB74D", pink: "#F48FB1", black: "#000000" };
const BACKGROUNDS = { none: "#00000000", dark: "#000000B3", black: "#000000", white: "#FFFFFF" };
const setting = (key) => {
try {
return kino.config.get(key);
} catch (e) {
return undefined;
}
};
/** A whole-dp nudge from a select's value ("-60", "24"); 0 for anything else. */
const nudge = (v) => {
const n = Number(v);
return Number.isFinite(n) ? Math.trunc(n) : 0;
};
/** The slot's answer: the clock element's text and look, and when to ask again (a minute is the longest Kino allows). */
export async function playerSlot(context) {
const item = { id: "clock", text: clockText(new Date(), context && context.lang, offsetMinutes(setting("timezone"))) };
const size = setting("size");
if (size && size !== "normal") item.size = size;
const weight = setting("weight");
if (weight && weight !== "auto") item.weight = weight;
const color = COLORS[setting("color")];
if (color) item.color = color;
const background = BACKGROUNDS[setting("background")];
if (background) item.background = background;
const left = nudge(setting("left"));
const top = nudge(setting("top"));
if (left !== 0) item.left = left;
if (top !== 0) item.top = top;
return { items: [item], refreshMs: 60000 };
}
/** The slot has no button, so Kino never calls this; the capability still requires the export. */
export async function playerSlotAction() {
return null;
}
- Un plugin con solo
playerSloty su bloqueslotestá completo: comoscreen, no reproduce nada, así que no necesita niresolvenisearch. - Las reglas del manifiesto piden al menos una entrada en
hosts, así que nombrakinotvapp.github.io; el plugin nunca lo llama. playerSlotActiones obligatorio con la capacidad aunque el reloj no tenga botón (aquí Kino nunca lo llama).refreshMs: 60000es lo máximo que Kino permite: un reloj que muestra minutos pregunta una vez por minuto.
node sdk/run.mjs player-clock playerSlot # el cuadro que Kino guardaría
node sdk/run.mjs --context '{"lang":"en-US"}' player-clock playerSlot # en inglés
node sdk/validate.mjs player-clock # un hueco solo `overlay` no muestra línea de consentimiento
node sdk/run.mjs --config timezone=-5 player-clock playerSlot # probar un ajuste
El bloque slot del manifiesto¶
{
"apiVersion": 23,
"capabilities": ["playerSlot"],
"slot": { "elements": [
{ "id": "clock", "kind": "text", "mode": "fixed" },
{ "id": "open", "kind": "button", "mode": "overlay" }
] }
}
| Campo | Regla |
|---|---|
elements |
De 1 a 3 objetos (un cuarto se rechaza con The "slot.elements" field must list 1 to 3 elements). La cantidad, los tipos y los modos se fijan aquí: tus respuestas solo cambian el contenido. |
id |
Minúsculas, dígitos, - o _, empieza con una letra, de 1 a 24 caracteres (^[a-z][a-z0-9_-]{0,23}$), único en el bloque. Tus respuestas lo usan como clave. |
kind |
text, icon, image o button. La respuesta de un elemento tiene que ser de su tipo: un elemento text respondido con un icon se descarta. |
mode |
overlay: flota sobre el video y sale con los controles (los de una película o serie; en un canal, la tarjeta del canal). fixed: se queda en su lugar todo el tiempo, también en pausa o cargando, y pide la aprobación de la persona (consentimiento). |
- La capacidad y el bloque se necesitan:
The "slot" field needs the "playerSlot" capability,The "playerSlot" capability needs a "slot" block. La capacidad exportaplayerSlotyplayerSlotAction, los dos obligatorios (si no, la instalación falla con "El plugin no carga: le falta ..."). playerSlotpuede ser la única capacidad del plugin. Un plugin que solo tiene el hueco no puede declararplayerControl: esa necesita unpanel.- Cuándo Kino no dibuja nada: mientras hay un panel de plugin abierto, el selector de audio y subtítulos abierto, un error
de carga a la vista o el reproductor en imagen en imagen (un diálogo normal de Kino solo oscurece la pantalla; los elementos
siguen). Un plugin 18+ solo dibuja mientras el código 18+ de la persona está desbloqueado. Los elementos
overlayademás esperan a los controles: en una película se esconden con ellos, y mientras la pantalla está bloqueada, hay una transmisión a un aparato DLNA o la persona está marcando un tiempo.
playerSlot(context): lo que muestra cada elemento¶
{ "items": [
{ "id": "clock", "text": "21:05\nmié 4 nov" },
{ "id": "mark", "icon": "star" },
{ "id": "logo", "image": "https://example.com/logo.png" },
{ "id": "open", "label": "Marcador", "icon": "tune" }
],
"refreshMs": 30000 }
kind |
Respondes | Lo que Kino guarda y dibuja |
|---|---|---|
text |
text: un texto; los saltos de línea separan líneas |
Máximo 2 líneas (las vacías se descartan, cada una recortada), 2000 caracteres antes de separar, sin caracteres de control ni de dirección. Nunca recibe el foco. |
icon |
icon: uno de los nombres de íconos de Kino |
El ícono a 28 dp. Un nombre desconocido descarta el elemento. Nunca recibe el foco. |
image |
image: una dirección https de un host público (nunca una IP, localhost ni un nombre local) |
Pequeña: unos 40 dp de alto y máximo 120 dp de ancho. Cualquier otra cosa descarta el elemento. Nunca recibe el foco. |
button |
label (máximo 40 caracteres, sin caracteres de control) y/o icon (un nombre conocido) |
Necesita al menos uno de los dos válido. Un botón redondo (solo ícono) o una píldora (con texto), que recibe el foco con el control remoto; el de solo ícono se lee "Botón del plugin" / "Plugin button" en un lector de pantalla. |
refreshMses cuándo Kino vuelve a llamar aplayerSlot, contado desde el final de la última llamada: por debajo de 2000 sube a 2000 y por encima de 60 000 baja a 60 000. Si falta (o no es un número) no se vuelve a llamar, y eso está bien para un botón que no cambia.- Nada se repara. Un id que no declaraste, un elemento del tipo equivocado, un ícono desconocido, una imagen mala y un botón
sin nada que mostrar se descartan; un id repetido conserva el primero válido. Si la respuesta no es un objeto con una lista
items, Kino conserva el último cuadro bueno (ninguno la primera vez). - Los elementos salen en el orden declarado, respondas en el orden que respondas. Un elemento que dejas fuera simplemente no se dibuja.
Vestir un texto y colocar un elemento¶
Un elemento text también puede decir cómo se ve, y cualquier elemento puede decir dónde va. Lo habitual es ofrecerlos como
ajustes normales de tu plugin, como hace el reloj de ejemplo, y leerlos con kino.config.get.
| Campo | En | Valor | Lo que Kino dibuja |
|---|---|---|---|
size |
text |
"small", "normal", "large" o "xlarge" |
12, 14 (el de siempre), 18 o 24 sp, con una línea que crece con él; la píldora crece con las letras |
weight |
text |
"extralight", "light", "normal", "medium", "semibold" o "bold" |
El grosor de Inter (200, 300, 400, 500, 600, 700) en todas las líneas. Ausente: el de Kino, la primera línea Medium y la siguiente Regular |
color |
text |
"#RRGGBB" o "#RRGGBBAA" |
El color de la letra. Nunca menos de la mitad de opaca (un alfa menor se sube a la mitad) |
background |
text |
"#RRGGBB" o "#RRGGBBAA" |
La píldora detrás del texto, en lugar del negro translúcido de Kino. "#00000000" (alfa 0) no dibuja píldora |
left, top |
cualquier elemento | números enteros de dp | Mueve el elemento desde su lugar en la fila: left lo mueve a la derecha (negativo: a la izquierda), top hacia abajo (negativo: hacia arriba). Se acota a -400..200 y -40..300; lo que no sea un número cuenta como 0 |
- Cada campo se lee por separado. Uno inválido (un tamaño o grosor desconocido,
"red","#12345") se ignora: Kino dibuja el suyo para ese campo. - Kino mantiene el texto legible. Un
colorcuyo contraste con una píldora opaca (o con la oscura de Kino, si no dasbackground) es menor de 2:1 se descarta, y la letra blanca de Kino pasa a negra sobre una píldora opaca clara. Una píldora que no es opaca (alfa menor de 240) nunca se revisa, porque Kino no puede saber qué muestra el video detrás. - Un desplazamiento conserva el espacio que tenía el elemento, así que puede solaparse con el vecino: desplaza un elemento que esté solo.
- La zona horaria es del plugin, no de Kino. El reloj de ejemplo ofrece un ajuste «Zona horaria» cuyo valor por defecto es el reloj del aparato; las demás son desfases fijos respecto de UTC (UTC-5, UTC+5:30...) que no siguen el horario de verano, porque un plugin no puede contar con una base de datos de zonas horarias en su sandbox.
Tiempos, reintentos y segundo plano¶
- Cada llamada tiene 5 s. Las llamadas van en fila: nunca dos a la vez para un plugin.
- La primera llamada puede fallar sin perder el hueco: hasta tener una respuesta buena, Kino vuelve a llamar a
playerSlotcada 5 s, hasta 4 veces más, y después se rinde para esa reproducción. Después de la primera respuesta, una llamada fallida o inválida conserva el último cuadro y el reloj derefreshMssigue. - Las llamadas corren solas. Una llamada a
playerSlot(la primera también) nunca cuenta para "No responde" (la racha de tiempos agotados seguidos); un toque sí. Por eso tampoco hay corte para las actualizaciones: un plugin cuyoplayerSlotagota el tiempo una y otra vez después de su primer cuadro se vuelve a llamar cadarefreshMsmás hasta unos 5 s, mientras dure la reproducción, y conserva su último cuadro. - Nada en segundo plano. Kino no llama a
playerSlotmientras está en segundo plano (se apretó Inicio, o hay una página de Kino sobre el reproductor) y vuelve a llamar al regresar.
playerSlotAction({ id, context }): un toque¶
Corre cuando la persona aprieta un botón (OK en el control remoto); id es el id del elemento. Kino solo la llama para un botón
declarado que está en pantalla. Responde null o {} para no hacer nada, o:
{ "openPanel": true, "player": { "pause": true } }
| Clave | Qué hace Kino |
|---|---|
openPanel |
true abre el panel del reproductor de tu plugin (el que dibuja tu export panel: necesita un bloque panel, o una pestaña aportada). Si el panel ya está abierto, no cambia a tu pestaña. Sin un panel tuyo en ese reproductor, se registra y se ignora. |
player |
Una acción player normal del panel (seekToMs, pause, speed, resize...), leída por el lector del propio panel y después con las mismas reglas que un toque en un panel: el plugin del título que suena conserva sus campos, cualquier otro plugin solo un salto (con la capacidad playerControl aprobada: un salto, pause y speed). Se aplica la compuerta de Kino (un salto o una pausa por segundo, nada bajo un diálogo de Kino ni mientras la persona salta, 30 acciones controladas por minuto), y una acción controlada muestra un aviso con el nombre de tu plugin. |
El contexto¶
context es el contexto del panel del reproductor para el título que suena (mira panel(context))
más live: true | false. Cuál recibes depende de qué suena y de quién puede saberlo:
| Qué suena | context |
|---|---|
| Un título de tu propio plugin | El contexto completo del panel: kind, ref, title, ids, posición, tus valores guardados... y live: false. |
| Un título de otro plugin (nunca 18+) | El contexto de una pestaña aportada: un ref opaco, foreign: true, source: { pluginId, name } y live: false. |
| Un título que no llega a ningún otro plugin (18+, un título que no es de ningún plugin, como una de las fuentes propias de Kino, o un título que Kino no puede confirmar que es el que suena) | El contexto mínimo: solo live, foreign: true, device, lang y features. Sin kind, ni siquiera película o serie: el código que lee context.kind tiene que soportar que falte. |
| Un canal de En vivo que su proveedor confirmó | El contexto del panel en vivo (kind: "live", live: true, channel, foreign, source...), mira Tu pestaña en un canal en vivo. |
| Cualquier otro canal de En vivo | El contexto mínimo con live: true. |
Lee live y lang (es-CO, en-US...: un reloj escribe su fecha en ese idioma) y trata todo lo demás como algo que puede
faltar.
En un canal de En vivo¶
- Los elementos
fixedsiempre se ven; losoverlaysalen con la tarjeta del canal (la que aparece al cambiar de canal y se esconde a los 3 segundos más o menos), y se van con ella. - Llegar a un botón: la tecla Menú. Arriba y Abajo siguen cambiando de canal, así que no entran a la fila. Menú saca la tarjeta y pone el foco en el primer botón; Izquierda y Derecha recorren los botones, Abajo o Atrás vuelven al video (Atrás no cierra el reproductor). Mientras un botón tiene el foco, la tarjeta se queda. Un control sin tecla Menú, como el del Chromecast con Google TV, no llega a un botón en vivo: no hagas que una función solo en vivo dependa de uno.
- Un toque en un canal puede hacer muy poco. En un canal un plugin siempre cuenta como otro plugin, así que Kino solo
conserva un salto (o con
playerControltambiénpauseyspeed), y un canal no tiene línea de tiempo:seekToMs,seekStepMs,speed,skip,markersyautoNextse descartan con una línea en el registro, yresizenunca se conserva para otro plugin. Lo que sobrevive espause(true o false), y solo con la capacidadplayerControlaprobada, que un plugin con solo el hueco no puede tener.openPanelsolo tiene efecto cuando el reproductor del canal ofrece pestañas de panel de plugins; en un canal sin ellas (un canal M3U propio, por ejemplo) se ignora y se registra.
En una película o una serie¶
Con los controles a la vista, Arriba desde la barra de progreso llega al primer botón de la fila; Izquierda y Derecha pasan de un botón a otro y Abajo vuelve a la barra. Sin ningún botón en pantalla (solo textos, íconos e imágenes, o ningún plugin con hueco) Arriba hace exactamente lo de antes. Los elementos de texto, ícono e imagen nunca reciben el foco.
Cómo se ve¶
Kino dibuja cada elemento con su propio aspecto, así que no aplica ninguna propiedad de estilo del kit de pantallas (padding,
color, style...), y no hay ring de foco ni key que poner.
- Un texto va sobre una píldora oscura translúcida: el tamaño de etiqueta pequeña del reproductor, blanco con sombra (se lee
sobre el video solo, porque un elemento
fixedse ve sin los controles), la primera línea en Medium y la segunda en Regular, con cifras tabulares para que un reloj que avanza nunca cambie el ancho de la píldora; si no cabe, termina en puntos suspensivos. Tu respuesta puede cambiar el tamaño, el grosor, el color y la píldora, y moverla: ver Vestir un texto y colocar un elemento. - Un botón es un botón redondo (solo ícono) o una píldora (con texto), con el mismo fondo translúcido mientras no tiene el foco.
- Orden: los elementos conservan el orden en que los declaraste, los
overlaya la izquierda de losfixed, así que un elemento fijo nunca se mueve cuando los otros aparecen y desaparecen.
La tipografía propia de Kino cambia en la misma versión (pesos más livianos en sus propias pantallas); el hueco conserva el aspecto que se describe aquí, y las pantallas de los plugins conservan la escala de texto de siempre: los encabezados siguen en negrita.
Consentimiento e interruptor¶
fixedes el que pregunta. Un plugin con un elementofixedmuestra una línea en rojo en su hoja de instalación: "Mostrará algo suyo de forma permanente en el reproductor mientras ves un video". Una actualización que agrega un elementofixedvuelve a preguntar, marcada como nueva, y Kino nunca la aprueba por su cuenta; al importar con el kit empieza sin marcar. Un hueco con solo elementosoverlayno muestra ninguna línea ni pide aprobación.- Por aparato. La aprobación de un hueco
fixednunca pasa desde otro aparato vinculado ni desde una copia de seguridad: la persona la aprueba otra vez en cada aparato. - El interruptor de la persona, en la pestaña de tu plugin en Ajustes: "Dejar que muestre algo en el reproductor". Vale para todo el aparato y se sincroniza con los demás aparatos de la persona; apagado, Kino deja de llamarte en el acto.
- Un toque es una acción de la persona; una llamada a
playerSlotno. El contexto sigue las mismas reglas de privacidad que el de un panel, y el mínimo es todo lo que recibe un título que Kino no puede compartir.
Probarlo con el kit¶
node sdk/run.mjs <carpeta> playerSlot [ref] # el cuadro: elementos en orden declarado, refreshMs ajustado; lo descartado va a stderr
node sdk/run.mjs <carpeta> playerSlotAction <ref> <id del botón> # el pedido: { openPanel, player, controlled }
node sdk/run.mjs --foreign <id del plugin>[:<nombre>] <carpeta> playerSlot <ref> # un título de otro plugin
node sdk/run.mjs --bare <carpeta> playerSlot # el contexto de un título privado (sin kind)
node sdk/run.mjs --live-channel tdt:la1:La 1 <carpeta> playerSlot - # el de un canal de En vivo
node sdk/run.mjs --bare --live-channel tdt:la1:La 1 <carpeta> playerSlot - # un canal que Kino no puede confirmar
node sdk/validate.mjs <carpeta> # también imprime la línea roja de un elemento fixed
--context '<json>'mezcla tu JSON sobre el contexto falso del kit (por ejemplo{"lang":"en-US"}). El ref es-con--live-channelo--bare.validaterevisa el bloqueslotcontra el contrato y que la entrada exporteplayerSlotyplayerSlotAction, y (con--run playerSlot) llama al export y lee su respuesta como lo hace Kino.- El kit no puede decir cómo se ve un cuadro en una TV: para eso, instala el plugin en un aparato con control remoto.
Mira también Probar en local y El panel del reproductor.