Vai al contenuto principale

Estendi Owncast con i plugin

Owncast può essere esteso con plugin: piccoli programmi che il server carica a runtime per reagire ai messaggi della chat, agli eventi di streaming, alle attività del fediverse e alle richieste HTTP. Essi girano all'interno di un ambiente isolato, quindi un plugin può bloccarsi senza abbattere il server e l'host applica un chiaro modello di autorizzazione affinché un amministratore sappia sempre cosa può toccare un plugin.

Plugins require Owncast v0.3.0

I plugin sono una funzionalità completamente nuova, introdotta in Owncast 0.3.0, e l'API è ancora in evoluzione. Se trovi un bug o hai un suggerimento, ti prego di aprire un problema o chiacchierare dal vivo con la comunità.

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.

Cosa puoi costruire​

  • Bot della chat che rispondono a parole chiave o comandi, postano promemoria, conducono sondaggi o moderano lo spam.
  • Filtri che riscrivono o rimuovono i messaggi della chat prima che raggiungano gli spettatori.
  • Sovrapposizioni rese sopra al tuo stream, comunicando con gli endpoint HTTP del tuo plugin.
  • Integrazioni che collegano Owncast a Discord, al fediverse, a notifiche del browser, o a qualsiasi servizio HTTPS.
  • Strumenti per amministratori che aggiungono una scheda all'interfaccia amministrativa di Owncast per le impostazioni specifiche del plugin.
  • Pulsanti d'azione che appaiono sotto il tuo stream, avviando widget, pagine di donazione o qualsiasi altra cosa tu offra.

Ogni plugin di esempio nell'SDK è un punto di partenza completo che puoi copiare.

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. Scaffold with npx create-owncast-plugin, write 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}")

Come si incastra tutto​

Un plugin è un singolo file .ocpkg contenente il manifesto del tuo plugin, il codice compilato, e qualsiasi asset statico. Un amministratore inserisce il file nella directory data/plugins/ di Owncast e lo abilita dalla pagina Plugin nell'amministrazione.

Una volta abilitato, il plugin gira all'interno del processo di Owncast. I gestori che hai definito si attivano quando accadono eventi corrispondenti. Le API che chiami (inviando chat, leggendo la configurazione, recuperando URL) passano attraverso l'host, che controlla le autorizzazioni dichiarate nel tuo manifesto.

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.

Cosa può fare un plugin​

  1. Iscriviti agli eventi. Messaggi di chat, avvio e arresto dello streaming, seguito del fediverse, nuovo utente della chat che si unisce. Definisci un metodo gestore e l'SDK deriverà l'iscrizione.
  2. Filtra la chat. Vedi ogni messaggio della chat prima che venga trasmesso, modificalo o rimuovilo.
  3. Chiama le API di Owncast. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url), e decine di altri, la maggior parte gateati da un'autorizzazione dichiarata.
  4. Servi HTTP. Ogni plugin può possedere lo spazio URL a /plugins/<your-slug>/... per asset statici e gestori dinamici.
  5. Aggiungi interfaccia utente. Dichiara pagine amministrative, pulsanti d'azione, fogli di stile dei plugin, script dei plugin, o un blocco di contenuto HTML extra nel tuo manifesto e Owncast li in linea nel suo stesso chrome.
  6. Controlla l'accesso. Un plugin può essere il fornitore di autenticazione del sito. Costringe gli spettatori a effettuare il login (OAuth, una password, qualsiasi cosa in HTTP) prima che possano raggiungere la pagina, il video, la chat o l'API.

Cosa un plugin non può fare​

Per design:

  • Nessun accesso diretto al filesystem, rete o processi dell'host. Il sandbox applica questo. I plugin fanno ciò che le API dell'host espongono, e solo con autorizzazioni dichiarate.
  • Nessuna impersonificazione dell'identità. Ogni plugin ottiene un'identità di chat (il bot fornito da Owncast durante l'installazione), e i post outbound del fediverse provengono dall'account stesso dello streamer.
  • Nessuna lettura cross-plugin. Il negozio chiave-valore di ogni plugin è namespaced.
  • Nessun blocco di chat indefinito. Le chiamate al filtro sono limitate nel tempo a 50 ms, e un plugin che solleva ripetutamente viene disabilitato automaticamente.

Questo è il motivo per cui un amministratore può installare un plugin di terze parti senza controllare ogni riga di codice. Il confine di fiducia è l'elenco delle autorizzazioni del manifesto.

Dove andare dopo​

Fonte​

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation
Gabe KangasGabe Kangas
G
Gabe Kangas