Escribir un plugin de Kino¶
Un plugin de Kino es una fuente de video que cualquiera puede publicar como un repositorio pequeño
de GitHub: un manifiesto JSON y un archivo JavaScript. Una persona escribe owner/repo en Kino, ve
con qué sitios va a hablar el plugin, acepta, y desde ese momento el plugin es una fuente más: sus
resultados salen en la búsqueda y en Inicio, y sus títulos se abren, listan capítulos, se reproducen
en el reproductor de Kino, guardan el progreso y aparecen en "Continuar viendo" y en la biblioteca
como cualquier otro título.
Puedes escribir, ejecutar y probar un plugin en tu computador con Node antes de tocar la app. Esta guía tiene todo lo que necesitas: la estructura de archivos, el manifiesto, el contrato que tu código debe cumplir, la API que Kino te da, cada límite, las particularidades del motor de JavaScript y cómo publicar.
La demo completa de la API es kinotvapp/kino-plugin-own-server
("Tu servidor" 1.5.0: cada función hasta apiVersion 7 funcionando de punta a punta); kinotvapp/kino-plugin-archive
(Internet Archive) es la plantilla de arranque más simple, y
kinotvapp/kino-plugin-archive-audio
(Internet Archive Audio) es la referencia para música y podcasts (apiVersion 8, Kino
0.9.54). Los dos primeros traen la carpeta sdk/, el kit de Node; el kit solo está en kinotvapp/kino-plugin-sdk. Otros dos archivos describen el contrato para máquinas (los dos están en la página
Referencia): contract.json guarda cada número y cada regla que la app hace
cumplir (las tablas de esta guía salen de él, y las pruebas de la app amarran sus propias constantes
a él), y kino.d.ts declara toda la API kino para tu editor
(/// <reference path="./kino.d.ts" /> al comienzo de plugin.js).
El camino de 5 minutos¶
- Parte de la plantilla. Crea tu repositorio desde
kinotvapp/kino-plugin-archive -- la más
simple -- o desde kinotvapp/kino-plugin-own-server
si necesitas ajustes, sesión, descargas o canales en vivo, o desde
kinotvapp/kino-plugin-archive-audio para
música y podcasts ("Use this template" en cualquiera, o clónalo y copia
sdk/). No le hagas fork: la búsqueda de la comunidad de Kino deja los forks por fuera (Hazte encontrar). O deja que el kit te escriba un esqueleto:node sdk/init.mjs mi-plugin --host example.com. - Declara lo que necesitas en
kino-plugin.json: unid, loshostsa los que vas a llamar y lascapabilitiesque exportas (Manifiesto). - Escribe las funciones en
plugin.js:searchohome(o las dos), y como mínimoresolve(Contrato, APIkino). - Revísalo como lo hace Kino:
node sdk/validate.mjs .y luegonode sdk/run.mjs . search "algo"(Probar en local). - Publícalo como repositorio público con el topic
kino-plugin(obligatorio: sin él Kino no lo encuentra), e instálalo en Kino desde Ajustes > Plugins escribiendoowner/repoo pegando la URL de sukino-plugin.json(Publicar). - Haz que Kino lo muestre solo en "De la comunidad": topic, nombre y descripción, y cómo comprobarlo, en Aparecer en Kino.
¿Usas un asistente de IA? Dale el prompt listo: lee toda esta guía desde llms-full.txt y
sigue AGENTS.md.
Qué es un plugin¶
Un repositorio público de GitHub, o una carpeta dentro de uno, con:
kino-plugin.json el manifiesto (obligatorio)
plugin.js el código: un solo módulo ES (obligatorio; su nombre lo fija "entry")
icon.png opcional, cuadrado, máximo 128 KB
README.md para humanos
Kino ejecuta tu código en un sandbox: sin sistema de archivos, sin temporizadores, sin otros plugins,
sin acceso a los datos de la persona. La única salida es kino.fetch, que solo llega a los hosts que
declara tu manifiesto y que la persona aprobó en pantalla, más los servidores que la persona escribió
en los ajustes de tu plugin (mira Manifiesto). Los plugins nunca se llaman directamente: desde Kino 0.9.81
uno puede usar las puertas que abre otro, siempre a través de Kino, que revisa cada petición y cada respuesta
(Protocolo entre plugins).
Kino carga exactamente un archivo JavaScript, así que no hay nada a lo que un import pueda
resolverse. Si usas un paso de compilación o una librería, empaqueta todo en ese único archivo --
mira Dividir tu código en varios archivos para un ejemplo completo.
Cómo lo instala la gente. En Kino, Ajustes > Plugins, escriben la dirección de tu repositorio:
| Escriben | Kino lee |
|---|---|
owner/repo |
la raíz del repositorio, rama por defecto |
owner/repo/sub/dir |
una carpeta dentro del repositorio |
owner/repo@v1.2.0 |
una rama, tag o commit (el nombre no puede tener /); también sirve con una carpeta |
https://github.com/owner/repo o .../tree/<ref>/<path> |
lo mismo, pegado desde el navegador |
https://raw.githubusercontent.com/owner/repo/<ref>/<path>/kino-plugin.json (o un github.com/.../blob/<ref>/.../kino-plugin.json, también /raw/) |
la carpeta donde está ese .json, en esa ref; cualquier otro tipo de archivo se rechaza |
https://cdn.jsdelivr.net/gh/owner/repo[@<ref>]/<path>/kino-plugin.json (también fastly, gcore, testingcf y quantil.jsdelivr.net) |
la misma carpeta del repositorio, leída desde GitHub: sin @ref o con @latest es la rama por defecto; la ref tiene que ser una rama, tag o commit exactos (@main, @v1.2.0), así que un rango de versiones (@1, @^1.2, @1.x) se rechaza |
https://<cualquier servidor público>/<path>/kino-plugin.json |
un plugin alojado fuera de GitHub: mira Instalar desde la URL del manifiesto |
El campo de Kino dice "Escribe usuario/repositorio de GitHub o pega la URL del manifest
(kino-plugin.json)". Un ?query o un #fragmento en una URL pegada se ignora. Una ref que solo viene
de una URL pegada (tree, blob, raw, raw.githubusercontent.com o el @ref de jsDelivr) no es un
pin: un plugin con secretos sellados pegado así se instala desde la rama
principal.
Con una dirección de repositorio, Kino descarga kino-plugin.json, tu archivo de entrada y el ícono
desde raw.githubusercontent.com; por eso el repositorio tiene que ser público. Una URL del
kino-plugin.json de un repositorio (en GitHub, raw.githubusercontent.com o jsDelivr) siempre se
convierte en la dirección de ese repositorio, así que los secretos sellados, la firma y la búsqueda de
la comunidad le siguen funcionando.
Instalar desde la URL del manifiesto¶
Tu plugin no tiene que vivir en GitHub (nuevo en la versión de Kino que sigue a la 0.9.49). La gente
puede pegar la URL https de su kino-plugin.json en cualquier servidor público: tu propio sitio,
GitHub Pages, un CDN como el npm/ de jsDelivr. Kino la guarda como la dirección
url:https://…/kino-plugin.json (esquema y host en minúsculas, puerto por defecto, sin query ni
fragmento): esa URL es la identidad del plugin, y viaja tal cual a los otros aparatos de la persona con
la sincronización de plugins.
entryeiconse leen relativos a la URL del manifiesto:"entry": "plugin.js"al lado dehttps://example.com/kino/kino-plugin.jsoneshttps://example.com/kino/plugin.js.- Solo
https(http://se rechaza con "Kino solo instala plugins desde direcciones https…"), en un nombre público: nada de direcciones IP,localhost, nombres de una sola etiqueta o.local/.lan, ni usuario:contraseña en la URL, y el archivo tiene que llamarse exactamentekino-plugin.json. También se rechazan un nombre que resuelve a una dirección privada y una redirección que sale dehttpso va a un host así. - Sin secretos sellados: los sellos van amarrados a un repositorio de GitHub, así que un
manifiesto con
secretsinstalado desde una URL se rechaza ("Este plugin trae datos sellados, y esos solo funcionan si lo instalas desde su repositorio de GitHub…"). Publica ese plugin en GitHub. - Sin firma: una
signatureva amarrada aowner/repo, así que no se revisa y el plugin se instala (y se muestra) como no firmado. - Todo lo demás es igual que con un repositorio: la hoja de consentimiento, los
hostsy cada regla de aprobación, y las actualizaciones: Kino vuelve a leer la misma URL y aplica unaversionmás alta, y pregunta otra vez cuando necesita más de lo aprobado. La búsqueda de la comunidad nunca lo lista (solo encuentra repositorios de GitHub con el topickino-plugin).
Los addons de Stremio son una función de Kino para la gente, no algo que tú escribes: en el mismo
campo una persona puede pegar la dirección del manifest.json de un addon de Stremio (o un enlace
stremio://) y Kino genera un plugin para él. Nada de esta guía cambia para tu plugin.
Nuevo en Kino 0.9.88: títulos listos por adelantado, en vivo por reloj, imágenes http
Un plugin puede dejar listo un título mientras la persona lee su página (resolveAhead y prepare),
un stream en vivo puede darle a Kino el reloj de medios de un CDN en lugar de una lista (clockLive,
apiVersion 27, también con un enhancements["27"] vacío), y las pantallas dibujan imágenes http en un host público
(imágenes http). Lo que cambió: Novedades.
Nuevo: pantallas propias para tu plugin (apiVersion 14, con Kino 0.9.74)
Un plugin puede dibujar su propia pantalla completa dentro de Kino: columnas, tarjetas, listas, pestañas, formularios, ventanas emergentes y las filas de pósteres de Kino, con el aspecto de Kino, en el celular y en el TV desde el mismo árbol JSON. Empieza por Pantallas y el catálogo de componentes; también llegan salas por internet, trabajos en segundo plano, resultados compartidos entre aparatos y la IA de texto de Kino. Lo que cambió: Novedades.
Nuevo: identidad, avisos y tiendas de plugins (apiVersion 15, con Kino 0.9.77)
Un plugin puede saber quién es la persona sin un registro (Identidad), dejar avisos en la campanita de Inicio (Avisos) y ser una tienda: una fuente de plugins para la tienda de Kino, respaldada por GitHub, por un servidor propio o por un archivo JSON (Tiendas de plugins, con dos tiendas de ejemplo). Lo que cambió: Novedades.
Nuevo: monedas de Kino (apiVersion 16, con Kino 0.9.78) y apiVersion 17
La capacidad coins deja mostrar el saldo de monedas de Kino de la persona y regalarlas (kino.coins), y
kino.sync.setActive deja que un proveedor de sincronización se encienda o se apague. apiVersion 17 (con Kino
0.9.81) trae kino.library.stats, trabajos por perfil, el widget pages y más. Lo que cambió:
Novedades.
La guía, página por página¶
| Página | Qué tiene |
|---|---|
| Primer plugin | Dos archivos que buscan y reproducen, y cómo ejecutarlos |
| Plugins firmados | Firma tu plugin con tu propia clave para que la gente sepa que cada actualización es tuya (apiVersion 5, Kino 0.9.45+) |
| Novedades | Qué cambió para quienes escriben plugins, por versión de Kino |
| Manifiesto | Cada campo y regla de kino-plugin.json, ajustes, streamHosts, secretos sellados, los servidores propios de la persona, insecureHttp, descargas |
| Contrato | Las funciones que exportas, sus argumentos, lo que devuelves, las preguntas de host y el permiso amplio de video, dejar listo un título por adelantado (resolveAhead, prepare), y los errores que la gente entiende |
| API kino | fetch, cookies, secret, crypto, sleep, config, HTML, storage, log, rank |
| Protocolo entre plugins | apiVersion 20, Kino 0.9.81: plugins que se usan entre sí a través de Kino. Un proveedor abre puertas (provides, proto_<puerta>_<llamada>), un consumidor las usa (consumes, kino.plugins.call); tipos, errores, límites, flujos, la puerta de instalación con recommends y go.installPlugin, lo que ve la persona y el ejemplo de TMDB + Cine Trivia |
| Compartir | Un botón Compartir que manda un texto (y el título) a la puerta wall de Kino Social como borrador (Kino 0.9.81, Kino Social 0.9.7), y las tarjetas para compartir de Kino 0.9.84: go.plugin, openFrom.routes, ctx.caller y kino.image.thumbnail |
| Aplicaciones resolutoras externas | externalResolve (apiVersion 11): pasarle un título a una app instalada por separado que lo convierte en una URL reproducible; el flujo, media, portable, errores, enviar a la TV, construir el otro lado |
| Proveedores de sincronización | syncProvider (apiVersion 12, Kino 0.9.74): llevar la sincronización entre los aparatos de la persona por un servicio con el que habla tu plugin; quién puede leer qué, el bloque sync, cada cuánto, conflictos, el límite de 4 MiB, pasar los ajustes a otro aparato, Sync-Gram y Sync Servidor |
| Sockets y bytes del plugin | apiVersion 13, Kino 0.9.74: WebSockets con kino.ws, streams que sirve tu plugin con read (Kino los reproduce y los envía al televisor), las operaciones de bytes de kino.crypto, un ejemplo completo sobre WebSocket con su prueba |
| Catálogo y almacenamiento grande | apiVersion 13, Kino 0.9.74: kino.catalog, un catálogo SQLite de hasta 100.000 ítems en el que busca Kino, y storageLarge |
| Imágenes del plugin | apiVersion 13, Kino 0.9.74: pósteres e imágenes de episodio que sirve tu plugin con image |
| Archivos del aparato | apiVersion 21, Kino 0.9.82: kino.files, archivos y carpetas que elige la persona, leídos por rangos o reproducidos con kino-file: |
| Guardar dónde va la persona | apiVersion 22 (Kino 0.9.83): kino.progress, hasta dónde va la persona en un capítulo o un libro; tu plugin arma su propia fila "Seguir leyendo" |
| Códigos QR | apiVersion 13, Kino 0.9.74: el tipo de ajuste qr y kino.qr.scan, con una receta de inicio de sesión entre dos aparatos |
| Pantallas | apiVersion 14, Kino 0.9.74: la pantalla completa de tu plugin, el bloque screen, screen() y screenEvent(), el estado, las respuestas, go, temporizadores, el foco en el TV, límites, probar con el kit |
| Componentes: diseño, contenido y acciones | Cada componente de una pantalla con sus propiedades: Column, Row, Card, Scaffold, AppBar, NavigationBar, PageView, ListTile, texto, imágenes, tablas, botones, toasts |
| Componentes: formularios, ventanas y navegación | Campos, validación, el nodo settings, diálogos, hojas, menús, ventanas ancladas, cada forma de go |
| Componentes: estado, estilo y recetas | Estado, eventos, valores por tamaño, nombres al estilo Flutter, propiedades comunes, tokens, límites y recetas |
| Salas, biblioteca y control del reproductor | apiVersion 14: kino.room, kino.library y playerControl |
| Trabajos, resultados compartidos e IA | apiVersion 14: schedule con jobs y job(ctx), kino.shared y kino.ai |
| Pantallas sin subir tu apiVersion | enhancements: ofrecer una pantalla y las funciones de apiVersion 14 sin dejar de instalarse en un Kino anterior; un bloque "27" vacío enciende clockLive; el apiVersion efectivo |
| Estructurar un plugin grande | src/ por responsabilidades, un plugin.js generado con esbuild y revisado con check:built |
| Exportar e importar un plugin | El archivo .kinoplugin: qué lleva, la firma, los secretos sellados |
| Canales en vivo | Ítems live, la pestaña En vivo, listas M3U/XMLTV, guías, liveStreamHosts, en vivo por reloj (clockLive, apiVersion 27, Kino 0.9.88), tres recetas |
| Personaliza tu plugin | Todo lo que tu plugin puede cambiar de cómo lo muestra Kino, en una tabla: ícono, color, ajustes, sección, categorías, colores, filas de Inicio, menú Servidor, tus propias frases |
| Formulario de ajustes | Todos los tipos de campo y sus atributos, section, status y action, clearSettings, setSettings y "¿Eres tú?", las ayudas link y help, validateSettings, un ejemplo completo, la pestaña propia y la sincronización |
| Firma por petición | Streams HLS firmados en cada petición: signing, sign, reintentos y alternateHosts (apiVersion 6) |
| Una ventana de navegador que la persona maneja | "visualBrowser": true y kino.visualBrowser.open (apiVersion 20, Kino 0.9.81): una ventana web que la persona ve y usa para iniciar sesión o terminar un paso, sobre tus propios hosts; cookies, storeAs, la receta "Vincular cuenta", Android TV (experimental). También el localStorage de la página: collect.localStorage y doneWhen.localStorage (Kino 0.9.87). |
| Navegador oculto | "browser": true / "pages", kino.browser.capture y kino.browser.page: cuándo usarlos, el modelo de seguridad, nunca un captcha, tiempos y fallas (apiVersion 6) |
| Pasar lo guardado | migrate: pasar a tu plugin lo que la persona tenía guardado (apiVersion 6) |
| Sección, categorías y colores | section, categories y theme (apiVersion 6) |
| Temas de la app | appThemes (apiVersion 18; superficies pintadas, una imagen de fondo, una fuente y capas de la TV desde apiVersion 26): tokens y rangos, price en kinos, experience, un logo vectorial, go.useTheme y go.setExperience |
| Panel del reproductor | panel, panelAction y playerEvent, acciones sobre el reproductor y settingsLayout (apiVersion 9); el panel en modo pantalla, las pestañas en el panel de otro plugin y en un canal en vivo, el panel fijo (apiVersion 14) |
| El hueco del reproductor | playerSlot y el bloque slot (apiVersion 23, Kino 0.9.83): hasta tres elementos pequeños en la esquina superior derecha del reproductor de la TV, el ejemplo del reloj, el consentimiento y el kit |
| Registro y telemetría | debug, la página Registro, telemetry, kino.log.report, logcat y las métricas de reproducción (apiVersion 6) |
| Límites y trampas del motor | Todos los números en un solo lugar, cómo vive tu código, lo que le falta a QuickJS, la trampa del rechazo |
| Probar en local | El kit de Node: run.mjs, validate.mjs, grabar y reproducir, canales en vivo |
| Identidad | apiVersion 15: kino.identity.telegram, un seudónimo de la persona para tu plugin y, para las llaves de autor en las que Kino confía, el token firmado |
| Avisos en la campanita | apiVersion 15: kino.notifications.post y clear, límites, go.screen |
| Tiendas de plugins | apiVersion 15: pluginStore, storeSync completo o en cambios, tiendas locales y en vivo, cómo las mezcla Kino, lista de bloqueo, +18 y límites |
| Tiendas de ejemplo | Dos tiendas completas para copiar: una con un JSON estático y una con su propia API |
| Aparecer en Kino | Los cinco pasos para salir en "De la comunidad", cuánto tarda y cómo comprobarlo |
| Publicar | Versiones, actualizaciones y aprobaciones, y cómo aparecer en "De la comunidad" |
| Lo que ve la persona | La hoja de consentimiento, los diálogos de host, los mensajes del reproductor, Configurar, estados, desactivar y desinstalar |
| Recetario | Un sitio HTML con login, una API JSON con token, el servidor propio de la persona, dos proveedores de sincronización, Widevine, http plano |
| Scrapers de Nuvio | Cómo instala la gente los scrapers de Nuvio, qué arma la conversión y sus límites |
| Plugins con scrapers de Nuvio | kino.nuvio (apiVersion 11): tu plugin nombra un repositorio de Nuvio y Kino instala y usa sus scrapers para buscar enlaces |
| Addons de Stremio | Cómo instala la gente un addon de Stremio, cómo se traduce cada recurso, qué se rechaza y sus límites |
| Plugins de CloudStream | Kino 0.9.54: cómo instala la gente los plugins de un repositorio de CloudStream, el complemento, cómo se traduce cada parte y sus límites |
| Plugins de ejemplo | Los ejemplos publicados (también los de pantallas: la galería de componentes, Solo noticias y Party Chat), y cómo está hecho el plugin de referencia |
| Reclamos y retiro de plugins | Cómo pedir que un plugin de la comunidad salga del índice, qué hace Kino y cómo apelar |
| Referencia | contract.json y kino.d.ts, para leer o descargar |