Extender Owncast con plugins

Owncast se puede extender con plugins: pequeños programas que el servidor carga en tiempo de ejecución para reaccionar a mensajes de chat, eventos de transmisión, actividad en el fediverso y solicitudes HTTP. Se ejecutan dentro de un entorno aislado, por lo que un plugin puede fallar sin afectar al servidor, y el host impone un modelo de permisos claro, por lo que un administrador siempre sabe qué puede tocar un plugin.

Plugins require Owncast v0.3.0

Los plugins son una funcionalidad completamente nueva, introducida en Owncast 0.3.0, y la API aún está evolucionando. Si encuentras un error o tienes una sugerencia, por favor informa un problema o chatea en vivo con la comunidad.

You can write a plugin with the JavaScript SDK, the Python SDK, or as a native WebAssembly module. The two SDKs are the recommended paths for most plugins. Native WebAssembly is an advanced option for compiled languages and direct access to the plugin wire protocol.

Lo que puedes construir

• Bots de chat que responden a palabras clave o comandos, publican recordatorios, realizan encuestas o moderan spam.
• Filtros que reescriben o eliminan mensajes de chat antes de que lleguen a los espectadores.
• Superposiciones renderizadas sobre tu transmisión, comunicándose con los puntos finales HTTP de tu plugin.
• Integraciones que conectan Owncast con Discord, el fediverso, notificaciones del navegador o cualquier servicio HTTPS.
• Herramientas de administración que añaden una pestaña al UI de administración de Owncast para configuraciones específicas del plugin.
• Botones de acción que aparecen debajo de tu transmisión, lanzando widgets, páginas de donaciones o cualquier cosa que sirvas.

Cada plugin de ejemplo en el SDK es un punto de partida completo que puedes copiar.

Choose an authoring path

All three paths produce the same .ocpkg format and use the same manifest, permissions, events, and Owncast APIs.

• JavaScript con @owncast/plugin-sdk. Estructura con npx create-owncast-plugin, escribe definePlugin({ ... }), and build with npm run package.
• Python con owncast-plugin-py. Scaffold with uvx owncast-plugin-py new, write decorated functions, and build with owncast-plugin-py package.
• Native WebAssembly with Rust, TinyGo, AssemblyScript, Zig, or another compiled language. Implement the wire protocol directly and package the compiled module as plugin.wasm.

The same echo bot in each SDK:

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

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

# Python
from owncast_plugin import plugin, owncast

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

Cómo se integra todo

Un plugin es un único archivo .ocpkg que contiene el manifiesto de tu plugin, el código compilado y cualquier activo estático. Un administrador coloca el archivo en el directorio data/plugins/ de Owncast y lo activa desde la página de Plugins en la administración.

Una vez activado, el plugin se ejecuta dentro del proceso Owncast. Los controladores que defines se activan cuando ocurren eventos coincidentes. Las APIs que llamas (enviando chat, leyendo configuración, obteniendo URLs) pasan a través del host, que verifica los permisos que declaraste en tu manifiesto.

Each enabled plugin uses more server memory. JavaScript and Python share one runtime per language, so the first plugin in either language has a larger one-time cost. A native WebAssembly plugin loads its own compiled module instead of a shared language runtime.

Lo que un plugin puede hacer

1. Suscribirse a eventos. Mensajes de chat, inicio y parada de transmisión, seguimientos del fediverso, nuevos usuarios de chat que se unen. Define un método de controlador y el SDK deriva la suscripción.
2. Filtrar chat. Ve cada mensaje de chat antes de que se difunda, modifícalo o elimínalo.
3. Llamar a las APIs de Owncast. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url), y docenas más, la mayoría controladas por un permiso declarado.
4. Servir HTTP. Cada plugin puede poseer el espacio de URL en /plugins/<tu-slug>/... tanto para activos estáticos como para controladores dinámicos.
5. Agregar UI. Declara páginas de administración, botones de acción, hojas de estilo de plugins, scripts de plugins o un bloque HTML de contenido extra en tu manifiesto y Owncast los inserta en su propia interfaz.
6. Controlar el acceso. Un plugin puede ser el proveedor de autenticación del sitio. Haz que los espectadores inicien sesión (OAuth, una contraseña, cualquier cosa por HTTP) antes de que puedan acceder a la página, el video, el chat o la API.

Lo que un plugin no puede hacer

Por diseño:

• Sin acceso directo al sistema de archivos del host, red o procesos. El entorno aislado hace cumplir esto. Los plugins hacen lo que las APIs del host exponen, y solo con permisos declarados.
• Sin suplantación de identidad. Cada plugin recibe una identidad de chat (el bot que Owncast proporciona en la instalación), y las publicaciones salientes del fediverso provienen de la cuenta del streamer.
• Sin lecturas entre plugins. El almacenamiento clave-valor de cada plugin tiene un espacio de nombres.
• Sin bloqueo indefinido de chat. Las llamadas a los filtros tienen un límite de tiempo de 50 ms, y un plugin que lanza errores repetidamente se desactiva automáticamente.

Por eso un administrador puede instalar un plugin de terceros sin auditar cada línea de código. El límite de confianza es la lista de permisos del manifiesto.

Dónde ir a continuación

• Guía rápida. Estructura un nuevo plugin, compílalo, instálalo.
• JavaScript, Python, and Native WebAssembly. Choose a language and build path.
• Referencia de manifiesto. Cada campo que tu plugin.manifest.json puede contener.
• Plugins de chat. Crea bots, herramientas de moderación y filtros de chat.
• Eventos. Cada evento al que tu plugin puede suscribirse, con formas de carga útil.
• APIs de Owncast. Cada método owncast.*, lo que hace y el permiso que necesita.
• Permisos. La lista completa y cómo funciona el modelo de seguridad.
• Servir HTTP. Sirve URLs desde tu plugin y envía eventos en tiempo real a los navegadores.
• Contribuyendo a la UI. Registra páginas de administración y contribuye con botones de acción debajo de la transmisión.
• Pruebas. Pruebas de escenario que llevan tu plugin a través del tiempo de ejecución real.
• Empaquetado y publicación. Agrupa el .ocpkg, instálalo y anúncialo en el directorio.

Origen

• Código fuente del SDK: github.com/owncast/plugin-sdk
• Example plugins: JavaScript · Python