Plugin inicio rápido

The quickest way to build a plugin is with the JavaScript or Python SDK. Pick a tab below and follow it through installation. To use Rust, TinyGo, AssemblyScript, Zig, or another compiled language instead, see Native WebAssembly.

Requisitos previos

• Un servidor Owncast que puedas administrar, versión 0.3.0 o más reciente.

JavaScript

• Node.js 18 o más reciente (node --version para verificar) para la herramienta @owncast/plugin-sdk.

Python

• Python 3.8 o más reciente, y uv o pip para instalar la herramienta owncast-plugin-py.

1. Crea un nuevo plugin

Un identificador de plugin es su slug: letras minúsculas, dígitos y guiones, comenzando con una letra. Se utiliza como el nombre del directorio, el nombre de archivo de salida y el prefijo de URL.

JavaScript

Crea un proyecto con create-owncast-plugin, pasando el slug:

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install

Ahora tienes:

my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test

npm install también crea node_modules/. Ninguno de estos se crea por ti, pero puedes agregar un icon.png (mostrado en la lista de plugins de administración), un directorio public/ (archivos estáticos servidos en /plugins/my-plugin/), y un directorio assets/ (archivos que el host integra en los campos de manifiesto).

Python

Crea un proyecto con new, pasando el slug. uvx ejecuta el generador directamente desde PyPI sin instalar nada:

uvx owncast-plugin-py new my-plugin
cd my-plugin
uv tool install owncast-plugin-py      # or:  pip install owncast-plugin-py — for build/test/serve/package

Ahora tienes:

my-plugin/
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.py            your code, with a sample handler
└── __tests__/
    └── plugin.test.json     a sample scenario test

El manifiesto tiene tanto un nombre para mostrar legible por humanos ("name": "My Plugin") como un slug ("slug": "my-plugin"). El nombre para mostrar es lo que los administradores ven en las listas. El slug es el identificador canónico. Consulta la referencia del manifiesto para las reglas.

2. Escribe algo de código

Un manejador reacciona a un evento. El SDK deriva la lista de suscripción del manifiesto de los manejadores que defines, así que no hay nada más que mantener en sincronización. Aquí hay un bot de eco:

JavaScript

Abre src/plugin.js:

const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

Python

Crea src/plugin.py:

from owncast_plugin import plugin, owncast

@plugin.on_chat_message
def echo(msg):
    owncast.chat.send(f"echo: {msg.body}")

Consulta la referencia de manejadores para todo lo que puedes enganchar y la referencia de APIs para cada método owncast.*.

3. Construye el plugin

Esto produce my-plugin.ocpkg en la raíz de tu proyecto: un solo archivo que contiene tu manifiesto, el plugin compilado, y el contenido de public/ y assets/. El .ocpkg es el formato de distribución: ese único archivo es todo lo que un administrador necesita.

JavaScript

npm run package

Python

owncast-plugin-py package

4. Ejecuta las pruebas

Cada escenario dispara eventos a través del verdadero tiempo de ejecución del plugin con efectos secundarios simulados, así que una prueba aprobada significa el mismo comportamiento en producción. Consulta la guía de pruebas para el modelo de datos completo.

JavaScript

npm test

Python

owncast-plugin-py test

5. (Opcional) iterar contra un servidor de desarrollo local

Sirve el plugin en http://localhost:8080/plugins/my-plugin/ para ejecutar endpoints, abrir páginas estáticas en un navegador, o activar manejadores de eventos a través de los endpoints auxiliares /_dev/ (por ejemplo POST /_dev/chat). Reinicia el servidor de desarrollo cuando cambies tu código.

JavaScript

npm run serve

Python

owncast-plugin-py serve

6. Instala en tu servidor

En la administración de Owncast, abre Plugins en la barra lateral y haz clic en Subir plugin. Elige el archivo my-plugin.ocpkg que tu construcción produjo. El plugin aparece en la lista inmediatamente. Activa Habilitado para cargarlo.

Alternativamente, copia my-plugin.ocpkg al directorio data/plugins/ de tu servidor y la próxima verificación lo recogerá:

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

Si el plugin declara permisos, el administrador los revisa en la pestaña Permisos en la página de detalles del plugin antes de habilitarlo. La primera habilitación captura el conjunto de permisos aprobados. If you later ship an update that asks for more access, the already-approved version keeps running with its existing permissions while the update waits as pending until the admin re-approves.

Qué leer a continuación

• Elegir un SDK y sus páginas de JavaScript / Python para la referencia completa específica del lenguaje.
• Referencia de manifiesto para el esquema completo de plugin.manifest.json.
• Referencia de manejadores para cada evento al que puedes suscribirte.
• APIs de Owncast para cada método que puedes llamar desde el código del plugin.

Cuando algo sale mal

• El plugin no aparece en la lista de administración. Asegúrate de que el .ocpkg esté en data/plugins/, no solo en plugins/, y que el nombre del archivo termine en .ocpkg. La página de Plugins de administración tiene un botón de Actualizar si no quieres esperar a la próxima verificación.
• El plugin aparece pero no se habilita. Revisa la vista detallada del plugin en la administración. La columna de Estado muestra error si el manifiesto es inválido o si el plugin no se pudo instanciar. Pasa el ratón para ver el mensaje, o ejecuta tus pruebas localmente para capturar el mismo problema antes de enviar.
• El plugin se habilita pero no hace nada. Asegúrate de que estás usando el nombre de manejador correcto (onChatMessage / on_chat_message, no onMessage) y que el permiso correspondiente está en tu manifiesto. A call without its permission never reaches Owncast: the denial is logged on the server and the call returns an empty or zero value, so watch the Owncast logs.
• El plugin está deshabilitado automáticamente. Un filtro que lanza o cuelga cinco veces seguidas se desactiva por el resto de la sesión. Corrige el error, reconstruye, vuelve a desplegar y vuelve a habilitar.