Saltar a contenido

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 image la 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 playerSlot y su bloque slot está completo: como screen, no reproduce nada, así que no necesita ni resolve ni search.
  • Las reglas del manifiesto piden al menos una entrada en hosts, así que nombra kinotvapp.github.io; el plugin nunca lo llama.
  • playerSlotAction es obligatorio con la capacidad aunque el reloj no tenga botón (aquí Kino nunca lo llama).
  • refreshMs: 60000 es 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 exporta playerSlot y playerSlotAction, los dos obligatorios (si no, la instalación falla con "El plugin no carga: le falta ...").
  • playerSlot puede ser la única capacidad del plugin. Un plugin que solo tiene el hueco no puede declarar playerControl: esa necesita un panel.
  • 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 overlay ademá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.
  • refreshMs es cuándo Kino vuelve a llamar a playerSlot, 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 color cuyo contraste con una píldora opaca (o con la oscura de Kino, si no das background) 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 playerSlot cada 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 de refreshMs sigue.
  • 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 cuyo playerSlot agota el tiempo una y otra vez después de su primer cuadro se vuelve a llamar cada refreshMs más hasta unos 5 s, mientras dure la reproducción, y conserva su último cuadro.
  • Nada en segundo plano. Kino no llama a playerSlot mientras 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 fixed siempre se ven; los overlay salen 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 playerControl también pause y speed), y un canal no tiene línea de tiempo: seekToMs, seekStepMs, speed, skip, markers y autoNext se descartan con una línea en el registro, y resize nunca se conserva para otro plugin. Lo que sobrevive es pause (true o false), y solo con la capacidad playerControl aprobada, que un plugin con solo el hueco no puede tener. openPanel solo 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 fixed se 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 overlay a la izquierda de los fixed, 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.

  • fixed es el que pregunta. Un plugin con un elemento fixed muestra 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 elemento fixed vuelve 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 elementos overlay no muestra ninguna línea ni pide aprobación.
  • Por aparato. La aprobación de un hueco fixed nunca 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 playerSlot no. 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-channel o --bare.
  • validate revisa el bloque slot contra el contrato y que la entrada exporte playerSlot y playerSlotAction, 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.