El manifiesto¶
kino-plugin.json, máximo 16 KB:
{
"id": "archive-org",
"name": "Internet Archive",
"version": "1.0.0",
"apiVersion": 1,
"entry": "plugin.js",
"description": "Películas de dominio público y televisión clásica de archive.org",
"author": "kinotvapp",
"homepage": "https://github.com/kinotvapp/kino-plugin-archive",
"hosts": ["archive.org", "*.archive.org"],
"capabilities": ["search", "home", "browse", "episodes", "resolve"],
"color": "#E0A030",
"icon": "icon.png"
}
Si se rompe una regla de las de abajo, Kino se niega a instalar el plugin y muestra un mensaje en español que nombra el campo.
| Campo | Regla |
|---|---|
id |
Obligatorio. ^[a-z0-9][a-z0-9-]{1,39}$ (de 2 a 40 letras minúsculas, dígitos o guiones, sin empezar por guion). No puede ser live, local, unknown, plugin, own, subtitle-keys ni subtitle-prefs (nombres propios de Kino; las versiones anteriores reservan además otros ids: si una dice "El id … está reservado por Kino", escoge otro). Es la identidad del plugin: nunca lo cambies cuando ya haya gente que lo instaló. |
name |
Obligatorio. De 1 a 40 caracteres. |
version |
Obligatorio. MAJOR.MINOR.PATCH y nada más (sin -beta, sin +build), cada número de hasta 6 dígitos y sin ceros a la izquierda. |
apiVersion |
Obligatorio. De 1 a 27 (27 agrega el campo clockLive de un stream en vivo, Kino 0.9.88: Kino arma la ventana en vivo desde el reloj de medios de un CDN, y un plugin que se queda en un apiVersion más bajo lo enciende con un enhancements["27"] vacío; 26 agrega a appThemes las superficies pintadas, el brillo, las capas, los assets, la imagen de fondo y la fuente, Kino 0.9.87; 25 deja que el subtítulo de un stream lleve su propio text descifrado en lugar de una url, Kino 0.9.86; 24 deja que el drm de un stream sea una lista y agrega el tipo clearkey, Kino 0.9.85; 23 agrega la capacidad playerSlot y el bloque slot, Kino 0.9.83; 22 agrega la capacidad progress, Kino 0.9.83; 21 agrega la capacidad files, Kino 0.9.82): 12, 13 y 14 llegan juntos en Kino 0.9.74. Un número más alto del que Kino soporta se rechaza con "Este plugin necesita una versión más nueva de Kino". Declara el número más bajo que tenga lo que usas, para que tu plugin también corra en versiones viejas de Kino: 2 para download, drm, insecureHttp, "hosts": [] o ítems live; 3 para channels/liveStreamHosts; 4 para un ajuste list, streamHosts o secrets; 5 solo para un plugin firmado (Kino 0.9.45+); 6 (Kino 0.9.50+) para cualquier cosa de la lista de apiVersion 6: secretos con tipo o más grandes, migrate, scopedSearch, streams firmados por petición, section/status/action en los ajustes, debug, telemetry, section, categories, theme, userMessage, entradas adult, canales en filas de Inicio, las llamadas de pares de llaves de kino.crypto, la capacidad meta, "browser": true con kino.browser.capture (y "browser": "pages" con kino.browser.page también), y las copias con etiqueta y perezosas; 7 (Kino 0.9.51+) para las capacidades tracking y segments; 8 (Kino 0.9.54+) para los ítems music y podcast y el export details; 9 (Kino 0.9.55+) para section.labelEn, el panel del reproductor, settingsLayout y fetchHosts: "any" en un plugin escrito a mano; 10 (Kino 0.9.65+) para la capacidad playlists (todavía solo un contrato: ningún plugin la usa hoy); 11 (Kino 0.9.66+) para la capacidad externalResolve y el externalResolver del manifiesto; 12 (Kino 0.9.74+) para la capacidad syncProvider, el bloque sync del manifiesto y los tipos de ajuste link y help; 13 (Kino 0.9.74+) para las capacidades socket y byteSource (Sockets y bytes del plugin), storageLarge y catalog (Catálogo y almacenamiento grande), qrScan y el tipo de ajuste qr (Códigos QR), imageSource (Imágenes del plugin); 14 (Kino 0.9.74+) para la capacidad screen con su bloque screen, las capacidades library, room y playerControl (Salas, biblioteca y control del reproductor), playerPanelTab (Panel del reproductor), schedule con jobs, ai y shared (Trabajos en segundo plano, resultados compartidos e IA), unlockWith en un ajuste y las opciones maxBytes y stopAt de kino.fetch; 15 (Kino 0.9.77) para las capacidades identity, notifications y pluginStore con su bloque pluginStore, y para season y episode en kino.library.watched(); 16 (Kino 0.9.78) para la capacidad coins (kino.coins: el saldo de kinos de la persona y regalar un kino por una publicación) y para kino.sync.setActive, que no es un apiVersion; 17 para kino.library.stats (los agregados de un mes de lo que la persona vio, para la capacidad library; Kino 0.9.81), "perProfile" en un trabajo (Trabajos en segundo plano), kino.tmdb dentro de un trabajo y 60 s y 20 peticiones para un trabajo con ai; 18 (Kino 0.9.81) para appThemes (temas para toda la app), go.useTheme, go.setExperience y activeTheme (Temas de la app); 19 (Kino 0.9.81) para la capacidad lyrics y go.installPlugin; 20 (Kino 0.9.81) para el protocolo entre plugins: provides, consumes y kino.plugins.call (los dos bloques también funcionan dentro de enhancements["20"] sin subir el tuyo), y para visualBrowser y kino.visualBrowser.open (una ventana de navegador que la persona maneja); el bloque enhancements lo lee Kino 0.9.74 con cualquier apiVersion (las operaciones de bytes de kino.crypto llegan con esa misma versión de Kino en cualquier apiVersion; la media informativa de un stream y su copia portable se leen en cualquier apiVersion). |
entry |
Obligatorio. Ruta relativa del archivo JavaScript: solo letras, dígitos, ., _, - y /, sin .., máximo 200 caracteres, termina en .js. El archivo pesa máximo 1 MB. Escribe "plugin.js", nunca "./plugin.js": Kino 0.9.45 y anteriores rechazan un ./ al principio (mira la advertencia más abajo). |
signature |
Opcional, desde apiVersion 5: { "authorKey": "<64 hex>", "value": "<128 hex>" }, la escribe node sdk/seal.mjs --sign: tu firma sobre el archivo de entrada. Necesita Kino 0.9.45+. Mira Plugins firmados. Por debajo de apiVersion 5 se ignora. |
hosts |
Obligatorio. Al menos 1 entrada, sin tope máximo desde Kino 0.9.45 (solo la acota el manifiesto de 16 KB). Kino 0.9.44 y anteriores rechazan más de 20, así que con más de 20 hosts el kit avisa "Más de 20 hosts: Kino 0.9.44 o anterior rechaza este plugin; necesita Kino 0.9.45 o superior". Desde apiVersion 2 puede estar vacío, [], cuando el plugin tiene un ajuste de tipo url: mira Los servidores propios de la persona). Desde apiVersion 18 también puede estar vacío en un plugin que solo trae appThemes: no llega a ningún lado, y su tarjeta dice que no se conecta a internet. Desde apiVersion 20 también puede estar vacío en un plugin que solo abre puertas con provides, y en un consumidor solo de pantalla: un consumes no vacío y capabilities exactamente ["screen"] (su propio kino.fetch se rechaza entonces salvo que declare fetchHosts: "any" o un ajuste url; las imágenes de direcciones públicas (https, y http donde kino.screen.httpImages) no necesitan host; sin ningún ajuste, su tarjeta dice que no se conecta a internet). Nunca un relleno como example.com: sdk/validate.mjs avisa si lo hay. Cada una es un nombre DNS en minúsculas (archive.org), *. más un nombre DNS (*.archive.org) o (solo apiVersion 2) un objeto { "host": "…", "insecureHttp": true } (abajo). Solo nombres de host: sin esquema, puerto ni ruta. Nada de * solo, nada de direcciones IP, nada de localhost, nada que termine en .local, .lan, .internal, .localhost o .home.arpa, y por lo menos un punto. *.x cubre solo los subdominios, no x mismo: si necesitas los dos, pon los dos. Los hosts que la persona aprueba después, uno por uno, mientras tu plugin corre (Un host que se te olvidó) no cuentan contra el manifiesto. |
capabilities |
Obligatorio. Un subconjunto de search, home, browse, episodes, resolve, download, drm, channels, migrate, scopedSearch, meta, subtitles, tracking, segments, lyrics, playlists, externalResolve, nuvio (apiVersion 11, con nuvioRepos), syncProvider, desde apiVersion 13 socket, byteSource, storageLarge, catalog, qrScan, imageSource, y desde apiVersion 14 screen, library, playerPanelTab, playerControl, room, schedule, ai y shared, y desde apiVersion 15 identity, notifications y pluginStore, y desde apiVersion 16 coins, y desde apiVersion 21 files, y desde apiVersion 22 progress (declarativa, sin línea de consentimiento; puede ir sola o junto a cualquier otra capacidad y el plugin sigue siendo de ese tipo), y desde apiVersion 23 playerSlot (los exports playerSlot y playerSlotAction y el bloque slot; puede ser la única capacidad del plugin; línea de consentimiento en rojo solo con un elemento fixed). Debe incluir resolve y al menos uno de search o home, salvo en un plugin de solo catálogo ("catalogOnly": true, Kino 0.9.54) y en un plugin que declara solo subtitles, tracking, segments y/o syncProvider (abajo); desde apiVersion 13 un plugin así también puede declarar socket, storageLarge, catalog y qrScan y seguir siendo de ese tipo (un proveedor de sincronización que habla por kino.ws, ["syncProvider", "socket"]), mientras que esas cuatro solas, sin ninguna de las cuatro de arriba, siguen necesitando resolve y search o home. search, home, browse, episodes y resolve tienen que ser, cada una, una función exportada del archivo de entrada, o la instalación falla con "El plugin no carga: le falta ...". download y drm necesitan apiVersion: 2 y son banderas declarativas — la app actúa sobre ellas, no tu código, así que no hay nada más que exportar; declarar una muestra su línea de consentimiento ("Puede descargar videos para verlos sin conexión" / "Reproduce video protegido (DRM)") y pide aprobación otra vez en una actualización que la agregue. download les da descargas sin conexión a tus títulos (mira Descargas); drm le permite a un Stream llevar una licencia Widevine (mira Un stream protegido con Widevine). channels necesita apiVersion: 3 y los exports liveCategories y liveChannels (mira Canales en la pestaña En vivo). migrate necesita apiVersion: 6 y el export migrate; declararla muestra "Revisar lo que tienes guardado (biblioteca, historial, favoritos) para pasarlo a este plugin" y pide aprobación otra vez en una actualización que la agregue (mira Pasar lo guardado). scopedSearch necesita apiVersion: 6 y search (si no, se rechaza con "La capacidad \"scopedSearch\" necesita también \"search\""); no exporta nada propio: tu search recibe within cuando la persona busca dentro de un "Ver más" (mira Buscar dentro de un "Ver más"). meta necesita apiVersion: 6 y el export meta, sin línea de consentimiento (mira Describir otros títulos). subtitles necesita el export subtitles; ["subtitles"] sola es un proveedor de subtítulos; un plugin que declara solo subtitles, tracking y/o segments (un proveedor de subtítulos, de seguimiento, de segmentos o una mezcla) también es una excepción a "resolve y search o home" (mira Subtítulos para cualquier título). tracking necesita apiVersion: 7 y el export track; declararla muestra una línea en rojo con tus hosts ("Le contará a seenr.app qué ves y cuándo lo terminas") y pide aprobación otra vez en una actualización que la agregue, aunque Kino apruebe otras actualizaciones por su cuenta (mira Contarle a un servicio de seguimiento qué ve la persona). segments necesita apiVersion: 7 y el export segments; declararla muestra "Agrega el botón para saltar la intro y los créditos", no en rojo y sin aprobación propia (mira Dónde están la intro y los créditos). playlists necesita apiVersion: 10; a diferencia de las demás, ninguno de sus seis exports (playlists, playlistItems, playlistCreate, playlistAddItem, playlistRemoveItem, playlistReorder) es obligatorio — declara solo los que tu servicio soporta; sin línea de consentimiento propia; todavía ningún plugin instalado ni anunciado la usa, y Kino no la conecta a ninguna pantalla por ahora (mira Playlists). externalResolve necesita apiVersion: 11, una bandera declarativa como download y drm (no hay nada que exportar): permite que una respuesta de resolve() (o una de las alternatives de un Stream) sea { external: { protocol, ref } } en vez de una url reproducible, para que Kino le pase ref a una app resolutora instalada por separado; no agrega ninguna línea de consentimiento a tu hoja de instalación (el único consentimiento es por app, y se pide la primera vez que se necesita una; mira Aplicaciones resolutoras externas y el contrato). syncProvider necesita apiVersion: 12 (Kino 0.9.74) y los exports syncPull y syncPush (syncStatus es opcional); puede ser la única capacidad del plugin. El plugin pasa a ser el transporte de la sincronización entre los aparatos de la persona: Kino cifra la copia y le entrega al plugin un blob opaco en base64 para guardarlo y devolverlo byte por byte. Exige el bloque sync del manifiesto con keySecret. Declararla muestra una sola línea de consentimiento, siempre en rojo, "Sincronizará tus datos a través de su servicio: el plugin y su servicio podrán leerlos", y pide aprobación otra vez en una actualización que la agregue (nunca se aprueba sola). Mira Proveedores de sincronización. Las seis de apiVersion 13 (Kino 0.9.74) no muestran línea de consentimiento ni piden aprobación propia: socket es declarativa y abre kino.ws, WebSockets solo a tus hosts declarados; byteSource necesita el export read y permite que un stream sea { source: "plugin", handle, size, mime } (Sockets y bytes del plugin); storageLarge es declarativa y deja kino.storage en 16 MB, solo en el aparato; catalog es declarativa y abre kino.catalog (Catálogo y almacenamiento grande); qrScan es declarativa y abre kino.qr.scan (Códigos QR); imageSource necesita el export image y permite que un poster, un backdrop, un still o la image del encabezado de una sección sea { source: "plugin", handle } (Imágenes del plugin). Cada una por debajo de "apiVersion": 13 se rechaza ("The \"catalog\" capability needs apiVersion 13"). Las ocho de apiVersion 14 (Kino 0.9.74): screen necesita los exports screen y screenEvent y el bloque screen, puede ser la única capacidad del plugin y no muestra línea de consentimiento (Pantallas); library (declarativa, puede ir sola) deja leer lo que la persona vio y guardó (kino.library); playerPanelTab necesita el export panel y "panel": { "contributes": true }, puede ir sola y agrega una pestaña al panel del reproductor del título de cualquier plugin (Panel del reproductor); playerControl (declarativa, nunca sola, necesita un panel) deja que tus acciones del reproductor pausen y muevan el video por su cuenta (Control del reproductor); room (declarativa, nunca sola) abre kino.room, salas por internet alojadas en el aparato de la persona; schedule necesita el export job y el bloque jobs, nunca sola (Trabajos en segundo plano); ai (declarativa, nunca sola) abre kino.ai.ask; shared (declarativa, nunca sola) abre kino.shared. library, playerPanelTab, playerControl, room, schedule y ai muestran cada una una línea de consentimiento en rojo y piden aprobación en la instalación y en la actualización que la agrega (nunca la aprueba Kino solo), y la persona puede apagarlas en tu pestaña de Ajustes; shared muestra una línea normal, no en rojo, y no espera aprobación. Un plugin que se queda en un apiVersion más bajo puede ofrecerlas con enhancements. Las tres de apiVersion 15 (Kino 0.9.77) no se ofrecen con enhancements: identity (declarativa, nunca sola) abre kino.identity.telegram, con una línea de consentimiento en rojo, y da el token firmado solo a las llaves de autor en las que Kino confía (kinoIdentity.tokenAuthors; cualquier otro autor recibe el seudónimo y la atestación desde Kino 0.9.88); notifications (declarativa, nunca sola) abre kino.notifications, con una línea normal; pluginStore necesita el export storeSync (y storeList y storeSearch si la tienda es en vivo), puede ir sola y hace de tu plugin una fuente de plugins para la tienda de Kino, con una línea normal y, en una tienda en vivo, otra en rojo (Tiendas de plugins). Las tres piden aprobación en la instalación y en la actualización que las agrega, y la persona puede apagar identity y notifications en tu pestaña de Ajustes. coins (apiVersion 16, Kino 0.9.78; declarativa, nunca sola y tampoco se ofrece con enhancements) abre kino.coins, el saldo de kinos de la persona y regalar un kino, con una línea de consentimiento en rojo («Podrá ver tu saldo de kinos y regalar tus kinos»); pide aprobación igual y no tiene interruptor propio: la persona la revoca al desactivar o quitar tu plugin. Desde apiVersion 20, un plugin cuyo único propósito es un provides no vacío puede no declarar ninguna capacidad (el campo puede faltar): mira Un plugin que solo provee. provides y consumes no son capacidades: un proveedor o un consumidor conserva las capacidades del tipo de plugin que es. |
settings |
Opcional. Lo que la persona llena en la pantalla "Configurar" de tu plugin: mira abajo. |
permissions |
Opcional. Una lista de nombres de la lista cerrada de contract.json. La lista está vacía en esta versión: cualquier nombre se rechaza con "permiso desconocido: …". Existe para que una versión futura pueda agregar permisos (cada uno visible en la pantalla de consentimiento) sin un apiVersion nuevo. |
color |
Opcional, #RRGGBB: el acento de la pestaña y los chips de tu plugin. Por defecto, un color neutro. |
icon |
Opcional, ruta relativa a un .png cuadrado de máximo 128 KB. Un ícono que falta o que pesa demasiado se omite sin que falle la instalación. |
discoverable |
Opcional, true o false (por defecto true), en cualquier apiVersion. false deja el plugin por fuera de la búsqueda de la comunidad de Kino (mira Hazte encontrar); la gente igual puede instalarlo escribiendo su dirección. Cualquier otro valor se rechaza con "El campo \"discoverable\" debe ser true o false". |
categories |
Opcional, en cualquier apiVersion: lo que ofrece tu plugin, para los chips de categoría de la tienda de plugins de Kino (Recomendados, "De la comunidad", "Elige tus plugins"). Una lista sin repetidos de movies, series, anime, live, radio, subtitles, utilities, themes, adult (themes: un plugin que ofrece temas de la app, listado en Temas), o de un tipo nuevo tuyo (manga, audio-books): de 2 a 24 letras minúsculas, dígitos y guiones, empezando por una letra. Un tipo nuevo no pide cambiar Kino: su chip (el id con los guiones como espacios y la primera letra en mayúscula: "Manga", "Audio books") aparece solo mientras algún plugin listado lo lleve. Declara el tipo nuevo en la entrada del catálogo siempre que puedas: un Kino anterior a los tipos nuevos rechaza un manifiesto que lo nombra, mientras que en una entrada del catálogo simplemente descarta el id. Si está, reemplaza lo que Kino adivina por tus capacidades (channels es live, episodes es series, todo lo que lista y reproduce es movies); el chip de un plugin adult solo se ve mientras el código +18 de la persona está desbloqueado. Cualquier otro valor se rechaza con "El campo \"categories\" debe ser una lista sin repetidos de: movies, series, anime, live, radio, subtitles, utilities, themes, adult, o un tipo nuevo (de 2 a 24 letras minúsculas, dígitos y guiones, empezando por una letra)". No es lo mismo que el export categories() (mosaicos dentro de Categorías de Kino, mira Sección, categorías y colores). |
catalogOnly |
Opcional, true o false (por defecto false), en cualquier apiVersion, desde Kino 0.9.54 (un Kino anterior lo ignora). true dice que el plugin lista y describe títulos pero no reproduce ninguno: resolve deja de ser obligatorio y Kino nunca lo llama; sus títulos van a "Buscar dónde verlo". Necesita una de home, browse, search o meta, y rechaza download, drm, channels, streamHosts y "browser": true. Para seguir instalándose en Kino 0.9.53 y anteriores, sigue declarando y exportando resolve (que falle con not_found) y search o home. Mira Plugins de solo catálogo. Cualquier otro valor se rechaza con "El campo \"catalogOnly\" debe ser true o false". |
resolveAhead |
Opcional, true o false (por defecto false), en cualquier apiVersion (sin apiVersion propio; lo lee por primera vez Kino 0.9.88 y un Kino anterior lo ignora). true deja que Kino llame tu resolve para una película o un episodio antes de que la persona apriete reproducir, para que el video arranque antes. Kino lo hace solo cuando tu resolve no puede preguntarle nada a la persona: un "fetchHosts": "any" aprobado, video desde cualquier servidor (un "streamHosts": "any" aprobado o el permiso de video amplio), sin externalResolve y sin browser. Decláralo solo si un resolve que nadie reproduce no tiene ningún efecto que la persona note; si no, déjalo afuera y exporta prepare. Nunca rechaza el plugin: cualquier otro valor se ignora (con registro, y sdk/validate.mjs avisa), y también un true al lado de catalogOnly o browser. Mira Dejar listo un título. |
recommends |
Opcional (Kino 0.9.81), con cualquier apiVersion (un Kino anterior lo ignora; no tiene apiVersion propio): una lista de máximo 8 textos owner/name de GitHub sin más, los plugins con los que el tuyo funciona mejor (sin URL, sin subcarpeta, sin @ref, de máximo 100 caracteres cada uno; se conservan las mayúsculas que escribiste y un repetido, sin importar mayúsculas, se junta). Cualquier otra cosa se rechaza: The "recommends" field must be a list of at most 8 plain GitHub owner/name repositories. Tus screen y screenEvent reciben installed, { "<repo tal como lo escribiste>": true \| false } solo para estas entradas, para ofrecer un botón go.installPlugin por cada uno que falte: mira Plugins recomendados e installed. Un consumidor del protocolo también nombra aquí a su proveedor (la puerta de instalación). |
creator |
Opcional, en cualquier apiVersion (Kino no lo lee; no tiene apiVersion propio). Tu usuario de Kino Social (de 3 a 20 caracteres: letras, dígitos y _), p. ej. "lordmacu". Solo viaja en el kino-plugin.json publicado para que el índice de plugins de la comunidad de Kino Social asocie el plugin a tu perfil allí. Si lo omites, el plugin simplemente no aparece en ningún perfil de Kino Social. Un valor que no tenga esa forma se ignora. |
provides |
Opcional, apiVersion 20 (Kino 0.9.81; también dentro de enhancements["20"], que conserva tu apiVersion): las puertas que este plugin abre a otros plugins, { "<puerta>": { "summary", "calls", "streams", "types" } }: máximo 4 puertas, cada una con un summary de máximo 120 caracteres, máximo 16 llamadas y 8 flujos, que responden tus exportaciones proto_<puerta>_<llamada>(arg) y proto_<puerta>_<flujo>(cursor). Kino revisa cada petición y cada respuesta contra los tipos declarados. Un bloque mal formado rechaza el manifiesto con un mensaje que nombra la puerta y el campo; un bloque en el nivel principal por debajo de apiVersion 20 se rechaza con The "provides" block needs apiVersion 20. Un plugin que solo tiene provides no necesita capacidades y puede tener "hosts": []. Mira Protocolo entre plugins. |
consumes |
Opcional, apiVersion 20 (Kino 0.9.81; también dentro de enhancements["20"]): las puertas de otros plugins que este usa, { "<alias>": { "repo", "door", "calls", "streams" } }: máximo 8 entradas; repo el owner/name de GitHub del proveedor, sin más (un fork no lo reemplaza), door su puerta, calls (máximo 16) y streams (máximo 8) los nombres que usas. Tu código llama await kino.plugins.call("<alias>", "<llamada>", arg); la hoja de consentimiento muestra «Usa datos de <proveedor> (<resumen de la puerta>)». Acompáñalo de recommends y go.installPlugin para invitar a la persona a instalar al proveedor. Mira Protocolo entre plugins. |
openFrom |
Opcional, apiVersion 20 (Kino 0.9.84; también dentro de enhancements["20"]): { "routes": ["detail", …] }, los nombres de las rutas de tu propia pantalla que las tarjetas de otros plugins pueden abrir con go.plugin. Necesita la capacidad screen. De 1 a 16 nombres distintos, cada uno de 1 a 64 letras, dígitos o . _ ~ - (los mismos que acepta la route de go.screen). Dice qué se puede abrir, no cómo: tú decides después, en tu pantalla, cómo llega cada ruta a su contenido. Una tarjeta cuya ruta no listas cae en una búsqueda. Una lista mala rechaza el manifiesto con un mensaje que nombra openFrom.routes. Mira Compartir. |
visualBrowser |
Opcional, true o false (por defecto false), apiVersion 20 (Kino 0.9.81; también dentro de enhancements["20"], que conserva tu apiVersion); por debajo la clave se ignora y cualquier otro valor se rechaza (The "visualBrowser" field must be true or false). true deja que el plugin abra kino.visualBrowser.open, una ventana web que la persona maneja sobre los hosts del propio plugin. No es una capability: en la instalación solo se aprueba una línea de consentimiento sencilla, y Kino pregunta en su propia hoja en cada apertura. Mira Una ventana de navegador que la persona maneja. |
browser |
Opcional, true, false o "pages", desde apiVersion 6; por debajo se ignora. true deja que el plugin abra páginas en una vista web oculta en el aparato con kino.browser.capture (en resolve), en rojo como "Puede abrir páginas web ocultas para encontrar el video"; "pages" agrega kino.browser.page, como "Puede abrir páginas web ocultas para mostrar contenido y encontrar el video". Una actualización que lo agrega, o que pasa de true a "pages", espera aprobación de nuevo; el resolve de un plugin aprobado tiene 75 s. Mira Navegador oculto. Cualquier otro valor se rechaza con "El campo \"browser\" debe ser true, false o \"pages\"". |
externalResolver |
Opcional, desde apiVersion 11, y solo con la capacidad externalResolve (si no, se rechaza el manifiesto: The "externalResolver" field needs the "externalResolve" capability): { "package": "com.example.resolver", "apk"?: { "url": "https://github.com/<owner>/<repo>/releases/download/<tag>/<file>.apk", "sha256": "<64 caracteres hex>", "label"?: "..." }, "fdroid"?: true, "downloader"?: { "code": "<3 a 10 dígitos>" } }. package es la única app resolutora a la que este plugin quiere que se le pasen sus respuestas external; con él puesto no se le pregunta a ninguna otra app, aunque otra declare el protocolo (el external.resolver de un stream lo pasa por encima). apk, fdroid y downloader son opcionales e independientes: formas de conseguir esa app cuando no está instalada; apk es dónde puede Kino ofrecer descargarla. Solo se acepta un archivo de un release de GitHub (https://github.com/<owner>/<repo>/releases/download/<tag>/<file>) o un archivo de archive.org (https://archive.org/download/<item>/<file>) (https, sin query), de 300 MB como máximo, y el archivo descargado debe tener exactamente ese sha256 o no se ofrece nada; label es el nombre de la app para la persona (40 caracteres como máximo). fdroid: true dice que el mismo package está en F-Droid (Kino abre F-Droid para exactamente ese paquete; solo se acepta true). downloader.code es un código de Downloader (la app para instalar en la TV) de 3 a 10 dígitos que Kino solo muestra. Cualquier cosa mal formada rechaza el manifiesto (The "externalResolver" field must be an object with a "package" (an Android package name) and, optionally, an "apk" with a GitHub release "url" ... and a 64-character hex "sha256"; "fdroid" may only be true and "downloader" an object with a "code" of 3 to 10 digits). Un Kino más viejo ignora el campo. Mira Aplicaciones resolutoras externas. |
sync |
Desde apiVersion 12 (Kino 0.9.74), obligatorio con la capacidad syncProvider y solo con ella (si no, se rechaza el manifiesto: The "sync" field needs the "syncProvider" capability; un proveedor sin él o sin keySecret: The "syncProvider" capability needs a "sync" field whose "keySecret" is the key of one of the plugin's own "password" settings): { "mode"?: "poll" \| "realtime", "pullEveryMs"?: 600000, "pushDebounceMs"?: 300000, "maxBlobBytes"?: 4194304, "keySecret": "<clave de un ajuste>", "provision": ["<clave de un ajuste>", ...] }. mode es poll por defecto (Kino trae la copia cuando pasa al frente y cada pullEveryMs, y la envía pushDebounceMs después de un cambio); realtime le permite al proveedor llamar a kino.sync.remoteChanged() cuando se entera de que la copia remota cambió. Los tiempos son milisegundos enteros positivos que Kino sube a sus propios mínimos. maxBlobBytes es el blob más grande que acepta el proveedor (por defecto y como máximo 4194304, 4 MiB); también fija cuánto pueden medir las peticiones, respuestas y resultados de kino.fetch dentro de syncPull/syncPush (ceil(maxBlobBytes × 4/3) + 64 KB). keySecret nombra uno de tus ajustes password (sin default): Kino deriva la llave de sincronización de su valor en cada aparato, así que la llave nunca viaja, y el plugin y su servicio sí pueden leer los datos sincronizados (línea de consentimiento en rojo). provision lista hasta 8 de tus ajustes con valor (secretos o no) que "Enviar configuración" le pasa a un segundo aparato; tiene que incluir keySecret, y desde apiVersion 13 puede nombrar una contraseña con "sync": false como secreto de un solo uso (nunca como keySecret), nunca un texto con "sync": false. Desde apiVersion 13, "generateKey": true hace que Kino cree él mismo el valor de keySecret (32 bytes aleatorios en hexadecimal) mientras está vacío (Una llave que crea Kino); cualquier cosa que no sea un booleano se rechaza. Todas las reglas, mensajes y compromisos: Proveedores de sincronización. Un Kino más viejo ignora el campo. |
screen |
Desde apiVersion 14 (Kino 0.9.74), obligatorio con la capacidad screen: la entrada del menú y las opciones de la pantalla completa del plugin, { "label": "Noticias", "labelEn": "News", "icon": "list", "menuOpens": "screen" }. Cada campo y cada regla: El bloque screen del manifiesto. |
jobs |
Desde apiVersion 14 (Kino 0.9.74), obligatorio con la capacidad schedule y rechazado sin ella: de 1 a 3 trabajos en segundo plano, cada uno { "id": "refresh", "label": { "es": "Actualizar noticias", "en": "Refresh news" }, "everyMin": 60, "everyOptions": [15, 30, 60, 180, 720, 1440] }, con runOn opcional ("any" o "preferPhone") y perProfile (apiVersion 17, true o false, siempre con runOn: "any"): una ejecución por perfil del aparato que tiene tu plugin activado. Cada campo y cada regla: Trabajos en segundo plano. |
slot |
Desde apiVersion 23 (Kino 0.9.83), con la capacidad playerSlot (cada una necesita a la otra): { "elements": [ { "id", "kind", "mode" } ] }, de 1 a 3 elementos; id cumple ^[a-z][a-z0-9_-]{0,23}$ y es único; kind es text, icon, image o button; mode es overlay (sale con los controles) o fixed (siempre a la vista; una línea de consentimiento en rojo). Hasta tres elementos pequeños en la esquina superior derecha del reproductor de la TV: mira El hueco del reproductor. |
pluginStore |
Desde apiVersion 15 (Kino 0.9.77), opcional y solo con la capacidad pluginStore (sin ella se rechaza): { "mode"?: "local" \| "live", "name"?: 1 a 60 caracteres }. mode es "local" por defecto; name es cómo sale la tienda en el filtro y en las tarjetas (por defecto, el name del plugin). Ver Tiendas de plugins. |
enhancements |
Opcional, lo lee Kino 0.9.74 (apiVersion 14) con cualquier apiVersion; un Kino anterior lo ignora como cualquier clave que no conoce. Funciones de un apiVersion más nuevo sin subir el tuyo: "apiVersion": 8, "enhancements": { "14": { "capabilities": ["screen", "library"], "screen": { "label": "Inicio" } } }. Un bloque que no cumple las reglas se descarta y se registra, nunca rechaza tu plugin. Desde Kino 0.9.81 un bloque también puede llevar provides y consumes ("enhancements": { "20": { "provides": { … } } }): el protocolo entre plugins en un plugin que se queda en un apiVersion más bajo. Desde Kino 0.9.88 un bloque vacío "27": {} sube tu apiVersion efectivo a 27, lo que enciende clockLive en tus streams en vivo; tu código lee ese número en kino.pluginApiVersion. Todo: Pantallas sin subir tu apiVersion. |
debug |
Opcional, true o false (por defecto false), desde apiVersion 6; por debajo se ignora. Desde Kino 0.9.50 todo plugin instalado tiene un interruptor "Modo debug" en su pestaña de Ajustes (errores en pantalla y un "Registro" que la persona puede copiar o compartirte); este campo solo lo deja encendido de entrada. Sin él arranca apagado y cada persona lo enciende cuando quiere mandarte un reporte. Cuando la persona lo toca, manda su decisión (validate.mjs te dice qué significa true). Mira Registro y telemetría. Cualquier otro valor se rechaza con "El campo \"debug\" debe ser true o false". |
telemetry |
Opcional, true, false o "verbose" (por defecto false), desde apiVersion 6; por debajo se ignora. Pide compartir las líneas de diagnóstico de tu plugin con el registro de errores de Kino cuando una llamada falla, venga de donde venga el plugin, y enciende kino.log.report. Se muestra en la hoja de consentimiento y una actualización que lo declara por primera vez espera su aprobación. Hasta Kino 0.9.53 las líneas de todo plugin que lo declara se envían siempre, sin interruptor; desde Kino 0.9.54 la pestaña de tu plugin en Ajustes tiene un interruptor "Enviar registros de errores y de reproducción", encendido por defecto, y la línea de consentimiento dice "Comparte con Kino registros de errores y datos técnicos de algunas reproducciones para corregir fallas" (true también envía una pequeña muestra de reproducciones que salieron bien). Mira Registro y telemetría. Cualquier otro valor se rechaza con "El campo \"telemetry\" debe ser true, false o \"verbose\"". |
section |
Opcional, { "label": "…" } (de 1 a 20 caracteres), desde apiVersion 6; por debajo se ignora. Le da a tu plugin su propia sección y exige el export section: mira Sección, categorías y colores. Desde apiVersion 9 (Kino 0.9.55) puede llevar también "labelEn" (de 1 a 20 caracteres): el nombre de la sección cuando la app está en inglés; label sigue siendo el texto en español y el de respaldo. Por debajo de 9 se ignora sin revisarlo. Uno vacío, de más de 20 o que no sea texto se rechaza con "El campo \"section.labelEn\" debe tener entre 1 y 20 caracteres". Mira Textos en inglés. |
theme |
Opcional, un objeto, desde apiVersion 6; por debajo se ignora. Hasta cinco colores #RRGGBB: accent, onAccent, background, surface, highlight; cualquier otra clave se rechaza con "El campo \"theme\" tiene un color desconocido". El manifiesto solo revisa el formato; las protecciones de lectura corren cuando Kino usa los colores (Tus colores). |
appThemes |
Opcional, una lista, desde apiVersion 18 (Kino 0.9.81); por debajo se ignora y no se ofrece por enhancements. De 1 a 8 temas para toda la app, declarados como datos (sin código, sin red, sin capacidades), cada uno { "id", "name": { "es", "en" }, "colors", "background", "shape", "typography", "elevation", "motion", "player", "tv", "phone", "adjustable", "pluginColors", "price", "experience", "logo" }. Un error de formato (un campo o token desconocido, un tipo equivocado, un id inválido o repetido) rechaza el manifiesto; un valor fuera de su rango se descarta con una advertencia y queda el de Kino. Un plugin que solo trae appThemes no necesita capacidades y puede tener "hosts": []; ponle "categories": ["themes"]. Cada token, rango y protección, el precio en kinos, la experiencia sugerida, el logo vectorial y go.useTheme: Temas de la app. No es lo mismo que theme de arriba, que solo colorea tus propias páginas. Desde apiVersion 26 un tema también puede pintar (surfaces, style.gloss, layout, assets, background.image, typography.fontFamily, shape.heroRadius, shape.railItemRadius): ver Superficies pintadas, capas y archivos. |
panel |
Opcional, { "label", "labelEn?", "icon?" \| "iconFile?" }, desde apiVersion 9 (Kino 0.9.55); por debajo se ignora. Un botón en el reproductor, junto al de subtítulos, mientras suena un título de tu plugin, que abre tu propio panel. label de 1 a 24 caracteres; icon uno de 16 nombres (tune por defecto) o iconFile, un PNG de 96×96 con alfa de máximo 24 KB, nunca los dos. Exige el export panel; panelAction y playerEvent son opcionales. Mira El panel del reproductor. |
settingsLayout |
Opcional, una lista de filas, columnas y tarjetas con { "setting": "<clave>" }, desde apiVersion 9; por debajo se ignora. Acomoda los ajustes que ya declaraste sin quitar ninguno (los que no nombres van al final). Mira settingsLayout. |
fetchHosts |
Opcional, solo "any". Deja que tu kino.fetch llegue a cualquier host público, solo por https en el puerto 443, para scrapers cuyos sitios o redirecciones de extractores cambian de dominio. En un plugin escrito a mano Kino lo respeta desde apiVersion 9 (Kino 0.9.55), después de que la persona lo aprueba en rojo ("Puede conectarse a cualquier servidor público de internet (solo https, nunca tu red local)"); kino.fetchAnyHost es true cuando está activo. Con un cupo de peticiones y sin tocar tus hosts declarados. Por debajo de apiVersion 9 solo lo respeta en los manifiestos que arma al convertir un scraper de Nuvio; en tu plugin se ignora (tu kino.fetch sigue limitado a tus hosts) y sdk/validate.mjs avisa "fetchHosts only takes effect on plugins converted from Nuvio or, on one written by hand, from apiVersion 9 (Kino 0.9.55); in your plugin it is ignored". Mira Conectarse a cualquier servidor. Desde apiVersion: 4 su único valor es "any"; cualquier otro se rechaza con The "fetchHosts" field only takes "any". Por debajo de apiVersion 4 se ignora. |
nuvioRepos |
Opcional, desde apiVersion 11 (Kino 0.9.71); por debajo se ignora. De 1 a 4 repositorios de Nuvio, cada uno owner/repo de GitHub o la dirección https de su manifest.json. Va junto con la capacidad nuvio (cada una exige a la otra) y fija los repositorios que kino.nuvio puede usar: cualquier otro se rechaza con not_allowed. La capacidad es declarativa y la persona la aprueba al instalar. Mira Plugins que usan scrapers de Nuvio. |
description, author, homepage |
Textos opcionales. Se les quitan los espacios de los extremos y se cortan a 300, 60 y 200 caracteres. Kino muestra el nombre, el autor, la versión y la descripción cuando le pregunta a la persona si quiere instalar. |
support |
Opcional. El correo del autor, una sola dirección (nombre@ejemplo.com). Con él, la hoja de acciones del plugin ofrece Reportar un problema: abre la app de correo de la persona con un mensaje para esa dirección, con el registro limpio del plugin y los datos del aparato en el cuerpo. La persona lo lee y lo edita antes de enviarlo; Kino no envía nada y no tiene servidor. Solo en el teléfono (la TV no tiene correo). Una dirección inválida se ignora: el manifiesto sigue siendo válido y el plugin no ofrece Reportar un problema. Para Kino 0.9.58 o más nueva; las anteriores ignoran el campo. |
Las demás claves se ignoran. hosts cumple tres funciones: es lo que la persona aprueba, es el
único conjunto de sitios a los que llega kino.fetch, y es el conjunto en el que deben estar las
URL de un Stream: el video, sus subtítulos, sus audioTracks y la licenseUrl de un bloque
drm (además del servidor propio de la persona).
Hay un campo más, liveStreamHosts, que solo se lee con "apiVersion": 3 y solo en plugins con la
capacidad channels: mira Canales desde cualquier servidor.
Los ítems en vivo (apiVersion 2) y la pestaña En vivo (apiVersion 3) tienen su propia página,
Canales en vivo.
Rutas en entry e icon: sin ./ al principio¶
Escribe plugin.js, nunca ./plugin.js
entry e icon son rutas relativas al manifiesto. Kino 0.9.45 y anteriores rechazan un ./
al principio: la instalación falla con El campo "entry" debe ser una ruta relativa a un
archivo .js (o lo mismo para "icon"), y en la app solo parece que el plugin "no se instala".
Un plugin generado con IA escribió "./plugin.js" y falló en unas 35 instalaciones. Kino 0.9.46
y posteriores aceptan un ./ al principio y lo quitan, pero todavía hay gente con versiones
más viejas, así que escribe siempre "plugin.js" e "icon.png", sin ./ (una carpeta sí vale:
"src/plugin.js"). El validate.mjs del kit lo rechaza con: Quita el "./" del campo "entry"
(por ejemplo "plugin.js"): Kino 0.9.45 y anteriores no instalan el plugin con "./".
Reproducir desde cualquier servidor (streamHosts, apiVersion 4)¶
Algunas fuentes sirven el video desde CDNs cuyos dominios no puedes listar (cambian, o están en TLDs
sueltos, que una entrada *.xyz nunca cubre). Con "apiVersion": 4 un plugin puede agregar:
"apiVersion": 4,
"streamHosts": "any"
"any" es el único valor y no hace falta ninguna capacidad; un manifiesto más viejo ignora el campo.
Deja que lo que el plugin reproduce esté en cualquier host público, por http o https:
- una película o un episodio: exactamente la regla del
permiso amplio de video -- la misma regla, pedida por ti de entrada en
vez de concedida por la persona. En el reproductor, la
urlque devuelveresolve, todo lo que nombra su manifiesto, cada salto de redirección y lossubtitlesyaudioTracksque devuelves pueden estar en cualquier host público, y nunca se pregunta por un host de video. Una descarga de esa película o episodio sigue la misma regla; - un canal en vivo: la regla de
liveStreamHosts: "any"(el stream, su manifiesto y sus redirecciones; tussubtitlesyaudioTrackssiguen en tushosts).
No cambia nada más: kino.fetch (y por tanto todo secreto sellado), las imágenes y los
servidores de licencia DRM siguen en los hosts que declaraste, y las direcciones locales o privadas
(y los nombres públicos que resuelven dentro de la red de la casa) siguen rechazadas. La pantalla de
consentimiento lo muestra en rojo ("Puede reproducir video desde cualquier servidor que indique"), y
una actualización que lo agrega espera a que la persona apruebe de nuevo. Si puedes, lista los
dominios reales: la gente confía más en una lista corta.
Conectarse a cualquier servidor (fetchHosts, apiVersion 9)¶
Hay scrapers que no pueden listar sus hosts: el sitio cambia de dominio cada tanto, o un extractor redirige a un CDN distinto en cada video. Desde Kino 0.9.55 un plugin escrito a mano puede pedir:
"apiVersion": 9,
"fetchHosts": "any"
Con eso, tu kino.fetch (cada salto de redirección incluido, y su tarro de cookies) puede llegar a
hosts que no declaraste, sin una pregunta por host, con estas reglas (la tienen los
scrapers de Nuvio que Kino convierte, desde antes):
- La persona lo aprueba. La pantalla de consentimiento lo muestra en rojo ("Puede conectarse a
cualquier servidor público de internet (solo https, nunca tu red local)"), y una actualización que lo
agrega espera a que la persona apruebe de nuevo. Sin esa aprobación,
kino.fetchsigue en tushosts. - Solo
https, por el puerto 443, y solo a un nombre con punto o a una IPv4 pública. Esto vale para un host que llega únicamente por este permiso (no está en tushostsni es un servidor que escribió la persona), en cada salto de redirección. Unhttp://, otro puerto o un nombre de una sola etiqueta (router,nas) falla conhost_not_allowed(ye.hostdice cuál). Desde la versión de Kino posterior a la 0.9.72, una redirección que nombrahttp://en el puerto por defecto se sigue porhttps://: nunca se envía nada en claro; cualquier otro puerto se rechaza. - Un cupo de peticiones. Esas peticiones (cada salto que sale) gastan un cupo que Kino lleva por plugin
para toda la app: como mucho 60 por minuto a un mismo sitio (un dominio y sus subdominios cuentan
juntos) y 600 cada 10 minutos en total (250 y 2500 en un plugin convertido de Nuvio); se rellena de forma
continua. Pasado el cupo, la petición falla al instante con
rate_limited. Los 60 pedidos por llamada dekino.fetchsiguen aplicando. - Tus
hostsdeclarados y los servidores que escribió la persona conservan sus propias reglas (un hostinsecureHttpsigue aceptandohttp, uno declarado cualquier puerto) y no gastan cupo. Declara tus sitios principales: es más rápido, no depende del cupo y la gente confía más en una lista corta. - Nunca la red de la casa. Las direcciones locales o privadas (
localhost,192.168.x.x,10.x.x.x,.local…) y los nombres públicos que resuelven dentro de la red de la casa siguen rechazados conhost_not_allowed, también en un salto de redirección. Una dirección IPv6 escrita tal cual ([2001:db8::1]) se rechaza siempre, sea local o pública: usa un nombre. - Los secretos sellados no cambian: un pedido que lleva un valor sellado solo va a los
hostsque declaraste, porhttps, en cada salto. - Las páginas ocultas. Si además declaraste
"browser", la dirección inicial de lo que abrenkino.browser.captureykino.browser.page, y cada navegación de la página principal que sigue (una redirección, unlocation), siguen una sola regla: un host que declaraste o que escribió la persona conserva la suya, y uno que llega solo por este permiso tiene que serhttps, puerto 443 y un nombre con punto o una IPv4 pública. La navegación puede salir de tushosts(los embeds saltan de host), y la primera que rompe la regla termina la captura o la lectura conblocked. Es detección, no siempre prevención: cuando el WebView del aparato pasa la página por el proxy de Kino, una redirección de servidor de la página principal puede contactar su destino una vez antes de que la captura termine. Lo que la página carga después (frames, scripts, el CDN del video) sigue siendo libre (cualquier host público, nunca la red de la casa) y no gasta cupo. Lo que reproduces sigue sus propias reglas (streamHosts); las imágenes, las licencias DRM y las descargas no cambian. kino.fetchAnyHostestruecuando el permiso está activo en esta instalación (declarado, con apiVersion 9 y aprobado),falsesi no, yundefineden un Kino anterior: úsalo para elegir entre ir directo al host nuevo o quedarte con tu propio respaldo. La APIkino.
Por debajo de apiVersion 9 un plugin escrito a mano puede declarar el campo (el manifiesto sigue
siendo válido), pero Kino lo ignora: la pantalla de consentimiento no lo muestra y kino.fetch sigue
en tus hosts. Y como Kino 0.9.54 y anteriores rechazan "apiVersion": 9, ese plugin necesita Kino
0.9.55. Si puedes, lista los dominios reales: la gente confía más en una lista corta.
Secretos sellados (apiVersion 4)¶
Un plugin que trae una clave fija (un token de API metido en el cliente del propio sitio, un secreto por cliente que es del autor) puede sellarla en vez de escribirla en texto plano en el manifiesto:
node sdk/seal.mjs --repo owner/repo --name apiKey
(owner/repo/ruta para un plugin que vive en una subcarpeta.) --repo sigue las mismas reglas que
la dirección desde la que la gente instala: se quitan un / final y un .git, pero una URL
(https://github.com/...) y un @ref se rechazan en vez de adivinar. El valor se lee de un prompt
oculto o por stdin -- nunca como argumento de la línea de comandos, que quedaría en el historial de la
terminal. Debe tener de 1 a 4.096 bytes (UTF-8) -- hasta 8.192 con "apiVersion": 6; la herramienta imprime una línea,
kino-sealed:v1:..., para pegar en el manifiesto:
"apiVersion": 4,
"secrets": { "apiKey": "kino-sealed:v1:AbC123..." }
- Hasta 16 secretos; cada nombre cumple
^[A-Za-z][A-Za-z0-9_]{0,31}$.secretsnecesita"apiVersion": 4; por debajo el campo se ignora (el plugin se instala sin secretos ykino.secretlanza error con cualquier nombre), y un Kino demasiado viejo para apiVersion 4 rechaza toda la instalación con "Este plugin necesita una versión más nueva de Kino". - Un sello queda atado al repositorio (y subcarpeta) que le pasaste a
seal.mjs, en minúsculas, nunca a un ref. Al instalar y en cada actualización, Kino abre cada sello una vez contra la dirección desde la que la persona instala, solo para comprobar que es de ahí; cada ejecución del plugin los vuelve a abrir, en memoria, solo para esa ejecución. Un sello hecho para otro repositorio, ruta o nombre, o uno dañado, se rechaza con "Los datos sellados de este plugin no son para este repositorio o están dañados"; una versión que no puede abrir sellos los rechaza con "Este Kino no puede abrir datos sellados". - Solo desde la rama principal, nunca con un
@refexplícito. GitHub sirve cualquier commit alcanzable en la red de forks de un repositorio -- el de un fork o el de un pull request -- por la dirección del repositorio padre, y no solo con un SHA evidente: un prefijo hexadecimal corto o un ref de git-describe resuelven igual. Así,owner/repo@<lo-que-sea>puede ser el manifiesto de otra persona, con sus propioshosts, mientras el sello sigue diciendoowner/repo. Un plugin con secretos que se instala o actualiza con cualquier@refexplícito -- rama, etiqueta o commit -- se rechaza con "Los datos sellados solo funcionan si instalas el plugin desde su rama principal, sin @rama", y una ejecución desde una dirección así no recibe secretos. - Un sello confía en el nombre del repositorio: si su dueño cambia de nombre o se borra y otra persona registra ese nombre, su repositorio abre tus sellos. Vuelve a sellar para el nombre nuevo, y cambia el valor si el viejo valía la pena protegerlo.
- Declarar cualquier secreto agrega "Usa datos sellados por su autor" a la hoja de consentimiento; una actualización que trae secretos a un plugin que no tenía pide aprobación otra vez, igual que un host nuevo. Agregar, cambiar o quitar un secreto en un plugin que ya declaraba alguno no la pide.
Llaves de cifrado con tipo (apiVersion 6)¶
Un valor sellado que se usa como llave de kino.crypto.encrypt/decrypt se puede declarar como llave,
para que Kino lea sus bytes con una codificación fijada en el manifiesto en vez del keyEncoding que
pase el código. Eso es lo que deja que una llave sellada sirva también para des-ede3-* (una llave
sellada sin tipo sigue siendo solo para AES):
node sdk/seal.mjs --repo owner/repo --name portalKey --use cipher-key --encoding hex
imprime una línea JSON para pegar como valor del secreto:
"apiVersion": 6,
"secrets": { "portalKey": { "seal": "kino-sealed:v1:...", "use": "cipher-key", "encoding": "hex" } }
usetiene que ser"cipher-key";encodinges"hex"o"base64"; no se permite ningún otro campo.- El valor, leído con esa codificación, tiene que dar una llave de 16, 24 o 32 bytes:
seal.mjsrechaza cualquier otra cosa, y Kino rechaza la instalación con "El secreto "portalKey" debe ser una clave de 16, 24 o 32 bytes". kino.secret("portalKey")sirve como lakeycompleta de cualquierencrypt/decrypt; elkeyEncodingque pases se ignora. Se rechaza, con "a sealed value can't be used here", como llave de HMAC, como entrada depbkdf2, en cualquier parte dedata/iv/aad, y en cualquier parte de una petición dekino.fetch(la URL, los nombres o valores de los headers, un cuerpo de texto, JSON o formulario): una llave con tipo es solo parakino.cryptoy nunca sale por la red.- Por debajo de apiVersion 6 un objeto aquí no es un sello: el manifiesto se rechaza.
- El kit de Node simula todo esto a partir del valor en claro de
.kino-secrets.json; los bytes de la llave, en hex (mayúsculas o minúsculas) o base64, también se tapan en todo lo que devuelve un servidor.
Qué protege y qué no. Esto es ofuscación, no secreto: la clave privada que abre un sello va dentro
de cada copia de Kino. Sellar un valor lo saca de tu manifiesto y del historial de tu repositorio; no
impide que alguien desarme Kino y abra el sello por su cuenta, igual que no impide que el sitio al que
llamas vea el valor en claro de su lado. No selles un valor que ya es público (una clave que ya está
en el JavaScript del reproductor de ese sitio no gana nada sellada en el tuyo), y nunca selles las
credenciales de la persona: esas van en un ajuste de tipo password.
Cómo se usa. kino.secret(name) devuelve un marcador, no el valor; Kino
cambia el marcador por el valor real solo dentro de kino.fetch, hacia los hosts de tu manifiesto
por https, y tapa el valor en todo lo que vuelve a tu código. Las reglas completas (dónde se cambia
el marcador, kino.crypto, el tapado) están en La API kino; cómo probarlo con
el kit de Node, en Probar en local.
Ajustes¶
settings es una lista de máximo 12 entradas que guardan un valor (más, desde apiVersion 6, máximo 16
que solo muestran o hacen algo: mira Formulario de ajustes). Cada una se vuelve un
campo en la pantalla "Configurar" del plugin (Ajustes ▸ Plugins, y desde Kino 0.9.50 también la propia
pestaña de tu plugin en Ajustes), y tu código lee su valor con kino.config.get(key):
"settings": [
{ "key": "server", "label": "Servidor", "type": "url", "required": true, "hint": "http://192.168.1.10:8096" },
{ "key": "user", "label": "Usuario", "type": "text", "required": true },
{ "key": "password", "label": "Contraseña", "type": "password", "required": true },
{ "key": "quality", "label": "Calidad", "type": "select", "default": "hd",
"options": [{ "value": "hd", "label": "Alta" }, { "value": "sd", "label": "Normal" }] },
{ "key": "subs", "label": "Subtítulos", "type": "toggle", "default": true }
]
| type | valor | puede ser required |
puede tener default |
valor más largo |
|---|---|---|---|---|
text |
texto | sí | sí | 500 caracteres |
url |
texto | sí | no (usa hint para un ejemplo) |
2.048 caracteres |
password |
texto | sí | sí | 500 caracteres |
toggle |
true / false |
no (siempre tiene valor) | sí | — |
select |
uno de los valores de options |
no (siempre tiene valor) | sí | — |
list |
una lista de entradas, cada una un objeto con los fields de la lista |
sí | no | — |
section |
ninguno (apiVersion 6) | no (no guarda valor) | no | — |
status |
ninguno (apiVersion 6) | no (no guarda valor) | no | — |
action |
ninguno (apiVersion 6) | no (no guarda valor) | no | — |
qr |
ninguno (apiVersion 13) | no (no guarda valor) | no | 512 caracteres |
link |
ninguno (apiVersion 12) | no (no guarda valor) | no | — |
help |
ninguno (apiVersion 12) | no (no guarda valor) | no | — |
Un valor que se queda en un aparato ("sync": false, apiVersion 13, Kino 0.9.74). Un password puede decir
"sync": false para quedarse en el aparato donde la persona lo escribió: para un valor que solo tiene sentido una vez, en
un aparato, como una contraseña de verificación en dos pasos que tu plugin manda enseguida y después borra
(clearSettings). Nunca se envía a un aparato emparejado, un valor que manda otro aparato nunca lo pone ni lo borra, y no
va en ninguna copia de seguridad ni en ningún kit. El sync.provision de un proveedor de sincronización sí puede
nombrarlo como secreto de un solo uso, nunca como su keySecret. Un text también puede
decir "sync": false (un número de teléfono que se ve tal cual y se queda en el aparato), pero nunca va en
sync.provision. sync en cualquier otro tipo, o que no es un booleano, rechaza el manifiesto; por debajo de apiVersion 13, y en un Kino que no lo tiene, la clave se ignora (la contraseña se sincroniza
como siempre). Formulario de ajustes.
linkyhelp(apiVersion 12, Kino 0.9.74) son ayudas para configurar: un botón que abre una direcciónhttpspor el sistema y un botón que abre tus instrucciones en una ventana. Mira Ayudas para configurar.keycumple^[a-z][a-zA-Z0-9_]{0,31}$y no se repite;labeltiene de 1 a 40 caracteres;hint(el ejemplo que sale debajo del campo), máximo 80.selectnecesitaoptions(de 1 a 20, cada una con unvaluey unlabelde máximo 40 caracteres); sudefaulttiene que ser uno de los valores. Eldefaultde untoggleestrueofalse.list(apiVersion 4) es una lista que la persona arma con un botón "Agregar": cada entrada es una línea de texto con un botón "Editar", y el diálogo para agregar o editar muestra losfieldsde la lista (de 1 a 4, cada uno conkey,label, untypetextourl, y opcionalmentehintyrequired; sindefault).max(de 1 a 50, 20 por defecto) limita las entradas.kino.config.get(key)devuelve un arreglo de objetos{ [field.key]: string }, sin espacios sobrantes y sin las entradas totalmente vacías; una lista vacía esundefined. Una listarequirednecesita al menos una entrada. Los camposurlde las entradas se vuelven hosts a los que tu plugin puede llegar, igual que un ajusteurl(así quehostspuede ser[]).{ "key": "sources", "label": "Direcciones", "type": "list", "max": 30, "fields": [ { "key": "url", "label": "Dirección", "type": "url", "required": true }, { "key": "category", "label": "Categoría", "type": "text" } ] }- Un ajuste
urlno tienedefault: un servidor que escribe la persona se vuelve un host al que tu plugin puede llegar, así que solo la persona puede escogerlo. Un manifiesto condefaulten un ajusteurlse rechaza; pon una dirección de ejemplo enhint. - Un ajuste
requiredsin valor frena cualquier llamada a tu plugin antes de que corra: el plugin muestra "Falta configurar", no se le piden sus filas de Inicio, y todo lo que la persona abra de él dice "Configura <name> en Ajustes ▸ Plugins" con un botón a esa pantalla. - Las contraseñas se guardan cifradas en el dispositivo. Tu código puede leerlas (tiene que enviarlas), y por eso la pantalla de consentimiento dice "Este plugin usa tu usuario y contraseña". Kino nunca escribe un ajuste en su log; no lo hagas tú tampoco.
- Cambiar cualquier ajuste cierra el sandbox de tu plugin y borra sus cookies y sus filas de
Inicio guardadas, así que la siguiente llamada arranca una sesión nueva con los valores nuevos.
kino.storageno se borra: si guardas un token ahí, ponle como clave el usuario y el servidor a los que pertenece (el recetario lo hace). - Desinstalar borra los ajustes, contraseñas incluidas.
- Desde apiVersion 6 el formulario también puede mostrar estados, botones de acción y validar antes de guardar, y los ajustes viajan entre los aparatos de la persona: mira Formulario de ajustes.
Los servidores propios de la persona¶
Un ajuste url es la forma en que un plugin habla con un servidor que no está en internet: un
servidor multimedia en la casa, por ejemplo. El servidor que escribe la persona se vuelve un host
más al que tu plugin puede llegar, exactamente como se escribió: su esquema (aquí se permite
http, porque los servidores caseros casi nunca tienen certificado), su host y su puerto. Nada más de
esa máquina o de esa red se permite, sus redirecciones solo pueden ir al mismo servidor o a tus
hosts declarados, y las URL de tus streams y de tus imágenes pueden apuntar a él. La pantalla de
consentimiento avisa "Se conectará a los servidores que escribas en su configuración", y Ajustes
lista a qué llega cada plugin ("Se conectará a: …").
Un plugin que solo llega a ese servidor (nunca llama a un sitio propio) declara "hosts": []
desde "apiVersion": 2, siempre que tenga al menos un ajuste url: la pantalla de consentimiento
entonces no lista ningún host, solo la línea sobre los servidores que escribe la persona, y Ajustes
dice "Se conectará solo a los servidores que escribas en su configuración" hasta que se escriba uno.
Un hosts vacío sin ajuste url se rechaza (El campo "hosts" solo puede estar vacío si el plugin
tiene un ajuste de tipo "url"), y con "apiVersion": 1 se rechaza como siempre. (Kino tampoco
lista nunca un host bajo el dominio reservado .invalid, el comodín que usaban manifiestos viejos.)
Solo cuentan el esquema, el host y el puerto: cualquier ruta de ese servidor es alcanzable, y
kino.config.get devuelve el valor tal como se escribió. Kino rechaza, con un mensaje debajo del
campo, un valor que no sea una URL http/https, o cuyo host sea localhost, una dirección de
loopback (127.0.0.1, ::1), una link-local (169.254.x.x, fe80::) o 0.0.0.0. Las direcciones
de la red de la persona (192.168.x.x, 10.x.x.x, un nombre .local) sí se permiten: ese es el
punto.
Declarar un host inseguro (apiVersion 2)¶
Una entrada de hosts también puede ser un objeto, para un sitio tuyo que no tiene certificado:
"hosts": ["archive.org", { "host": "cdn.example.org", "insecureHttp": true }]
Esto necesita "apiVersion": 2. insecureHttp: true es lo único que puede llevar además de host,
y marca los únicos hosts declarados (no el servidor propio de la persona, de arriba) que se
permiten por http plano: kino.fetch, la url de un Stream, sus subtitles, sus audioTracks
y la licenseUrl de un bloque drm aceptan http://cdn.example.org/… cuando se declara así, y cada
salto de redirección se juzga con la misma regla. Todos los demás hosts declarados siguen siendo solo
https, https sigue funcionando en el inseguro, y el host se compara exacto: sub.cdn.example.org
no queda cubierto. Siguen aplicando las mismas reglas que para un texto simple (nombre DNS público,
sin *, sin IP, nada privado ni de LAN; un nombre que resuelve dentro de la red de la persona igual
se rechaza) más una: sin comodín *. — un host inseguro se nombra exacto. La pantalla de
consentimiento lo muestra en rojo, "Conexión sin cifrar con cdn.example.org", y una actualización que
marque un host así por primera vez espera aprobación, igual que un host nuevo. Mira
Un sitio tuyo sin certificado.
Descargas (apiVersion 2)¶
Declara "download" en capabilities (con "apiVersion": 2) y Kino ofrece tus títulos para verlos
sin conexión: "Descargar" en la página de información y "Guardar en el dispositivo" en la biblioteca,
en celulares (Kino nunca descarga en un televisor). No hay nada más que exportar. Cuando la persona
guarda un título, Kino llama a tu resolve(ref) en el momento en que la descarga de verdad arranca,
igual que al reproducir, y guarda el Stream como un solo archivo, con tus headers en cada
petición, por el mismo filtro de hosts que el reproductor usa con ese stream: https en tus hosts o
el servidor propio de la persona -- o cualquier host público cuando tu manifiesto tiene
streamHosts: "any" o la persona le dio a tu plugin el
permiso amplio de video --, cada salto de redirección revisado, nunca la
red de la casa. Una descarga nunca pregunta por un host. Un servidor que el filtro rechaza termina la
descarga para siempre (sin "Reintentar": no es un problema de red), con una frase que nombra el
servidor; cuando es uno por el que reproducir habría preguntado, la frase dice que reproduzcas el
título una vez para aprobarlo, y después una descarga nueva funciona. Tus subtitles se
guardan al lado. Los audioTracks no se guardan: la copia sin conexión solo tiene el audio que va
dentro del archivo de video, así que una fuente que dobla con pistas aparte se oye con su audio
principal cuando está sin conexión.
Qué se descarga y qué no:
- Un archivo progresivo (
mp4,mkv,webm,ts, …) se descarga. El archivo guardado toma su extensión de tumimecuando lo das, si no de la URL, y si nomp4; el reproductor igual mira los bytes. - Un stream HLS bajo demanda (
.m3u8, unmimempegurl, o una respuesta que resulta ser una playlist) también se descarga, guardado como un solo archivo: los segmentos MPEG-TS quedan en un.tsy los fMP4 (EXT-X-MAP) en un.mp4. De una playlist maestra Kino toma la variante más alta hasta 1080p cuyo audio va dentro del video; se manejan las llaves AES-128 y los rangos de bytes, y tusheadersvan en las playlists, la llave y cada segmento. En unEXT-X-DISCONTINUITYlos segmentos se guardan tal cual (los tiempos arrancan de nuevo ahí y el reproductor los sigue; adelantar justo en el empalme puede caer un poco corrido), salvo que ahí cambie el formato del video o del audio (por ejemplo H.264 → HEVC, o una pista que aparece o desaparece): eso se rechaza como abajo. Las pistas de metadatos (ID3, SCTE-35, datos privados) no cuentan como cambio, y los mismos formatos que llegan con otros números de pista (PID) después del empalme se reescriben con los del primer segmento, así que el.tsguardado se reproduce hasta el final. Un reintento retoma en el primer segmento que falta cuando recibe el mismo contenido (la misma variante, los mismos primeros bytes), aunque venga de otro CDN; un contenido distinto arranca de cero. - El audio (Kino 0.9.54, ítems
musicypodcastde apiVersion 8): los archivos de audio progresivos y el HLS solo de audio también se descargan, y un álbum descargado se reproduce sin conexión en el reproductor de audio. - Lo que no se puede guardar termina como "Este contenido no se puede descargar" ("Este video no se
puede descargar" hasta Kino 0.9.53), un estado final sin
"Reintentar" (se negaría igual) que la persona solo puede quitar, y el archivo parcial se borra: un
manifiesto DASH o Smooth (
.mpd,application/dash+xml, …), una playlist HLS en vivo (sinEXT-X-ENDLIST), SAMPLE-AES o cualquier llave DRM, una llave que no tiene 16 bytes o que no descifra, un segmento vacío (pedido 3 veces antes), una maestra en la que toda variante de video necesita una pista de audio aparte (Kino no guarda un video mudo), un stream con DRM y un canal en vivo (un canal en vivo ni siquiera muestra el botón de descarga, tampoco en un plugin que declarachannelsydownloada la vez). Los subtítulos que vienen dentro de la playlist no se guardan (tussubtitlessí). No hay una llamada aparte de "resolve para descargar": si tu fuente ofrece DASH y también un archivo o HLS, prefiere esos, o acepta que esos títulos se reproducen pero no se descargan. - La cola descarga un título a la vez, así que un
refpuede esperar un rato antes de que se llame aresolve: guarda en él algo estable y busca el enlace fresco dentro deresolve(como se recomienda en Contrato). Un reintento retoma el archivo parcial aunque tu URL haya cambiado. Unresolvede la cola que se pasa del tiempo hace fallar solo esa descarga: no cuenta para los tres tiempos agotados seguidos que apagan tu plugin ("No responde"); eso solo lo cuentan las llamadas hechas para la persona que está en pantalla. - Un plugin desactivado, esperando sus ajustes o desinstalado no descarga nada: sus títulos no muestran el botón de descarga, y un título que ya estaba en cola falla con "Este plugin ya no puede descargar videos". Los archivos ya descargados se siguen reproduciendo sin conexión y se pueden quitar en Descargas, pase lo que pase después con el plugin.
Declarar download muestra "Puede descargar videos para verlos sin conexión" en la hoja de
consentimiento, y una actualización que lo declare por primera vez espera la aprobación de la
persona (Publicar).