Saltar a contenido

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

  1. 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.
  2. Declara lo que necesitas en kino-plugin.json: un id, los hosts a los que vas a llamar y las capabilities que exportas (Manifiesto).
  3. Escribe las funciones en plugin.js: search o home (o las dos), y como mínimo resolve (Contrato, API kino).
  4. Revísalo como lo hace Kino: node sdk/validate.mjs . y luego node sdk/run.mjs . search "algo" (Probar en local).
  5. 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 escribiendo owner/repo o pegando la URL de su kino-plugin.json (Publicar).
  6. 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.

  • entry e icon se leen relativos a la URL del manifiesto: "entry": "plugin.js" al lado de https://example.com/kino/kino-plugin.json es https://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 exactamente kino-plugin.json. También se rechazan un nombre que resuelve a una dirección privada y una redirección que sale de https o va a un host así.
  • Sin secretos sellados: los sellos van amarrados a un repositorio de GitHub, así que un manifiesto con secrets instalado 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 signature va amarrada a owner/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 hosts y cada regla de aprobación, y las actualizaciones: Kino vuelve a leer la misma URL y aplica una version má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 topic kino-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