Packaging & publishing plugins

El formato de distribución de un plugin es el archivo .ocpkg: un solo paquete que contiene tu plugin.manifest.json, tu código de plugin, tus directorios public/ y assets/, y opcionalmente un icono y un documento de instrucciones. Ese único archivo es todo lo que un administrador de servidor necesita para instalar tu plugin.

Construyendo el paquete

JavaScript

npm run package

npm run package only rebuilds when the bundle is missing. After changing source, run npm run build first so the package doesn't ship stale code.

Python

owncast-plugin-py package my-plugin

Native WebAssembly

Use your language toolchain to compile the module, then package it as a ZIP with the canonical plugin.wasm filename. The Native WebAssembly guide includes build commands for Rust, TinyGo, and AssemblyScript.

The resulting \<your-slug>.ocpkg contains the manifest and runnable code. It can also include the plugin's public/ and assets/ directories.

The JavaScript and Python packagers run the built plugin through owncast-plugin-test --load-only before writing the archive. This uses the same install-time load path as a real server, covering register(), manifest and runtime agreement, and permission-gated subscriptions. Native WebAssembly authors run owncast-plugin-test directly before packaging. See Native WebAssembly: Test before installing.

El archivo es autónomo. Compártelo como quieras:

• Adjúntalo a un lanzamiento de GitHub
• Aloja en tu propio servidor
• Entregalo a un administrador por chat o email

Icono del plugin

Coloca un icon.png en la raíz de tu proyecto (junto a plugin.manifest.json) y el empaquetador lo agrupa automáticamente en el .ocpkg. La UI del administrador lo obtiene de /api/plugins/\<your-slug>/icon y lo muestra en la lista de plugins y en la entrada de la barra lateral para cualquier plugin que incluya una página de administración.

my-plugin/
├── plugin.manifest.json
├── icon.png              bundled automatically
├── src/
├── public/
└── assets/

Notas:

• No se requieren permisos. El host sirve el icono directamente. No necesitas http.serve.
• El icono es distinto de los iconos de los botones de acción, que se encuentran en public/ (servidos por web) y son referenciados por el campo icon de una entrada actions[]. Consulta UI: Botones de acción.

Instrucciones

Coloca un INSTRUCTIONS.md en la raíz de tu proyecto (junto a plugin.manifest.json) y el empaquetador lo agrupa automáticamente en el .ocpkg. La UI del administrador lo obtiene de /api/admin/plugins/\<your-slug>/instructions y lo presenta como markdown en una pestaña Instrucciones en la página de detalles del plugin.

my-plugin/
├── plugin.manifest.json
├── INSTRUCTIONS.md          bundled automatically
├── src/
├── public/
└── assets/

Utiliza esto para pasos de configuración, notas de configuración, qué permisos se solicitan y por qué, y cualquier otra cosa que un administrador necesita saber después de instalar. Los plugins sin uno no muestran pestaña de Instrucciones. El nombre del archivo es fijo (INSTRUCTIONS.md). No se requiere permiso de http.serve.

El archivo es para administradores, así que escríbelo para el streamer que instaló tu plugin y está abriendo la UI de administración para averiguar cómo usarlo. Notas para desarrolladores en estilo README pertenecen en el README de tu repositorio.

Qué hay dentro de un .ocpkg

• plugin.manifest.json
• One code entry: plugin.js, plugin.py, or plugin.wasm
• icon.png si proporcionaste uno
• INSTRUCTIONS.md si proporcionaste uno
• El contenido de tu directorio public/ si tienes uno (servido por web en /plugins/\<slug>/)
• El contenido de tu directorio assets/ si tienes uno (acceso del host para campos de manifiesto que integran contenido)

The code filename selects the runtime. A native module must be named plugin.wasm inside the archive, regardless of the plugin slug.

Build inputs such as node_modules, package.json, pyproject.toml, Cargo.toml, and uncompiled source do not belong in the package. They produce the code entry that the server runs.

Loose native WebAssembly files

During development, a native module can be installed without creating an .ocpkg. Copy the module and manifest into data/plugins/ with the same basename:

data/plugins/
├── my-plugin.wasm
└── my-plugin.manifest.json

Owncast scans for the .wasm file and reads the matching .manifest.json. The packaged .ocpkg format is still recommended for distribution because it keeps the code, manifest, and optional assets together.

Instalando en un servidor

En el administrador de Owncast, abre Plugins en la barra lateral y haz clic en Subir plugin. Selecciona tu .ocpkg y el servidor lo instala en su lugar. El nuevo plugin aparece en la lista de inmediato.

Si la UI del administrador no es una opción (automatización, sin acceso al navegador, despliegues por script) también puedes colocar el .ocpkg directamente en el directorio data/plugins/ del servidor:

scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/

El servidor escanea este directorio periódicamente. El plugin aparece en la página de Plugins del administrador en un par de segundos.

En ambos casos, termina la instalación en el administrador:

1. Haz clic en tu plugin en la lista para abrir su vista de detalle.
2. Revisa la pestaña Permisos. Estos son exactamente los que tu manifiesto declaró.
3. Activa Habilitado para cargar el plugin. La primera habilitación también captura el conjunto de permisos aprobados.

Actualizando un plugin instalado

To ship an update, replace the package file in data/plugins/ directly, or install the new version from the admin's Browse tab if you publish to the directory. The manifest's slug is the identity key: the new contents replace the existing entry with the same slug, whatever the file was called. Para forzar una recarga inmediata de un plugin habilitado, haz clic en Recargar en su fila.

Uploading from the admin's Plugins page only installs a new plugin. An upload whose slug already belongs to an installed plugin is rejected ("uninstall it before uploading another plugin with the same slug"), so uninstall the old one first if the admin upload is your only update path.

Two files in data/plugins/ that declare the same slug are also a conflict. Owncast keeps the first one it finds, ignores the other, and logs which package was skipped.

Qué sucede cuando cambian los permisos

• Has eliminado permisos. Silencioso. El plugin se recarga con el conjunto más pequeño.
• Has añadido permisos. The old approved version keeps running (it holds only the approved permissions) and the new package waits as pending, with a "needs re-approval" badge in the plugin list. The admin reviews the new permissions in the Permissions tab (new entries are tagged) and clicks Approve to accept the expanded set and load the update.

Las capacidades efectivas de un plugin nunca crecen sin el consentimiento explícito del administrador, incluso a través de actualizaciones.

Aumentando la versión

Aumenta version en plugin.manifest.json cada vez que realices un lanzamiento. It's what admins see in the plugin list and what the registry uses to tell releases apart. The host doesn't gate loading on it: update identity is the slug, and the load-time check compares slug and permissions, not version.

La versionización es para humanos. Se recomienda Semver pero no se aplica obligatoriamente.

Desactivando y desinstalando

• Desactivar mantiene el plugin instalado pero detiene su carga. La elección del administrador se persiste a través de reinicios. Activa Habilitado nuevamente para cargarlo de nuevo.
• Desinstalar elimina el plugin por completo. Desde la página de Plugins del administrador haz clic en el icono de papelera en la fila del plugin y confirma. (También puedes eliminar el .ocpkg de data/plugins/ directamente, y el próximo escaneo recoge la eliminación.)

Lista de verificación de distribución

Antes de publicar un plugin:

• El manifiesto declara solo lo que usas. Elimina permisos no usados. Cuanto más estrecho sea tu pedido, más fácil será la decisión de confianza del administrador.
• description está completado. Los administradores lo ven en la lista de plugins y durante la instalación. Una oración que cubre lo que hace el plugin.
• version refleja lo que estás enviando. Se acepta semver como convencional.
• El README en tu repositorio explica lo que hace, qué permisos solicita y por qué, y qué configurar (variables de entorno, configuración de página de administración, etc.).
• Las pruebas pasan. El comando de prueba de tu SDK debería estar en verde.
• El icono está incluido si tienes uno.
• Un INSTRUCTIONS.md se envía con cualquier cosa que el administrador necesita saber después de la instalación: pasos de configuración, notas de configuración, por qué se solicita cada permiso. Los plugins con comportamiento no obvio o configuración requerida deberían incluir uno. Plugins triviales (un manejador de chat hello-world) no lo necesitan.

Publicando en el directorio

Listar tu plugin en el directorio público en owncast.directory es opcional. Un .ocpkg es autónomo, así que siempre puedes entregárselo directamente a un administrador. El directorio solo hace que tu plugin sea descubrible y le da a los administradores instalación y actualizaciones con un solo clic.

Algunos campos del manifiesto dan forma a tu listado, así que complétalos primero: name (el nombre para mostrar), version (aumenta por cada actualización), slug (tu identificador permanente, consulta Manifest), description (el resumen en una línea en tu tarjeta), permissions (mantenlos mínimos, los administradores los revisan), y un opcional icon.png.

Iniciar sesión

El directorio utiliza inicio de sesión sin contraseña, con enlace mágico. Ve a owncast.directory/plugins/login, ingresa tu email y haz clic en el enlace en tu bandeja de entrada. Tu email es tu identidad de autor, vinculada a los plugins que posees. En tu página de cuenta puedes establecer un nombre para mostrar opcional que aparecerá como autor en tus listados.

Enviar

Ve a owncast.directory/plugins/submit y sube tu .ocpkg. El directorio lee tu manifiesto, valida el paquete y publica la versión. La presentación se realiza a través del sitio web, sin un paso de publicación por línea de comandos hoy en día. El formulario también acepta algunos extras opcionales: una imagen de vista previa (una captura de pantalla, PNG o JPEG de hasta 5 MB), un enlace a la página principal, etiquetas de navegación y un resumen que reemplaza la descripción del manifiesto.

Propiedad y actualizaciones

• El primer presentador es el propietario del slug. Cuando publicas un slug por primera vez, está vinculado a tu cuenta y nadie más puede publicarlo. Una presentación para un slug de otro autor es rechazada.
• Cada versión se publica una vez. Para enviar una actualización, aumenta version en tu manifiesto, vuelve a empaquetar y presenta nuevamente.
• Gestiona tus plugins en owncast.directory/plugins/account, donde puedes ver todo lo que has publicado y eliminar un listado.

Qué ven los operadores

En la vista de Navegar del directorio, tu plugin muestra su nombre, autor, descripción, icono, última versión e imagen de vista previa si has subido una. Cuando un administrador lo instala, Owncast muestra los permisos que tu manifiesto solicita, presenta tu INSTRUCTIONS.md y lista cualquier comando de chat que registres. Esa metadata es lo que un operador utiliza para decidir si confiar y habilitar tu plugin, así que escríbelo teniendo en cuenta a ese lector.

Dónde ir a continuación

• Referencia del manifiesto para la lista completa de campos del manifiesto.
• Permisos para el modelo de confianza y la lista completa de permisos.
• Example plugins: JavaScript · Python.