Erweitere Owncast mit Plugins

Owncast kann mit Plugins erweitert werden: kleine Programme, die vom Server zur Laufzeit geladen werden, um auf Chatnachrichten, Streamereignisse, Fediverse-Aktivitäten und HTTP-Anfragen zu reagieren. Sie laufen in einer Sandbox, sodass ein Plugin abstürzen kann, ohne den Server herunterzufahren, und der Host ein klares Genehmigungsmodell durchsetzt, sodass ein Administrator immer weiß, was ein Plugin ansprechen kann.

Plugins require Owncast v0.3.0

Plugins sind brandneue Funktionen, die in Owncast 0.3.0 eingeführt wurden, und die API entwickelt sich weiterhin. Wenn du einen Fehler entdeckst oder einen Vorschlag hast, bitte öffne ein Problem oder chatte live mit der Community.

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.

Was du bauen kannst

• Chatbots, die auf Schlüsselwörter oder Kommandos reagieren, Erinnerungen posten, Umfragen durchführen oder Spam moderieren.
• Filter, die Chatnachrichten umschreiben oder löschen, bevor sie die Zuschauer erreichen.
• Überlagerungen, die über deinem Stream gerendert werden und mit den HTTP-Endpunkten deines Plugins kommunizieren.
• Integrationen, die Owncast mit Discord, dem Fediverse, Browser-Push oder einem beliebigen HTTPS-Dienst verbinden.
• Admin-Tools, die einen Tab in der Owncast-Admin-Benutzeroberfläche für pluginspezifische Einstellungen hinzufügen.
• Aktionsschaltflächen, die unter deinem Stream erscheinen und Widgets, Spenden-Seiten oder alles andere, was du anbietest, starten.

Jedes Beispiel-Plugin im SDK ist ein vollständiger Ausgangspunkt, den du kopieren kannst.

Choose an authoring path

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

• JavaScript mit @owncast/plugin-sdk. Erstelle mit npx create-owncast-plugin, schreibe definePlugin({ ... }), and build with npm run package.
• Python mit 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}")

Wie es zusammenpasst

Ein Plugin ist eine einzelne .ocpkg-Datei, die das Manifest deines Plugins, den kompilierten Code und alle statischen Assets enthält. Ein Administrator legt die Datei in das Verzeichnis data/plugins/ von Owncast ab und aktiviert sie auf der Plugins-Seite im Adminbereich.

Sobald aktiviert, läuft das Plugin innerhalb des Owncast-Prozesses. Handler, die du definiert hast, werden ausgelöst, wenn passende Ereignisse eintreten. APIs, die du aufrufst (Chat senden, Konfiguration lesen, URLs abrufen), laufen über den Host, der die Berechtigungen überprüft, die du in deinem Manifest deklariert hast.

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.

Was ein Plugin tun kann

1. Ereignisse abonnieren. Chatnachrichten, Stream-Start und -Stopp, Fediverse-Followers, neuer Chatbenutzer tritt ein. Definiere eine Handler-Methode und das SDK leitet das Abonnement ab.
2. Chat filtern. Jede Chatnachricht sehen, bevor sie gesendet wird, sie ändern oder wegwerfen.
3. Owncast-APIs aufrufen. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url) und Dutzende mehr, die meisten gesperrt durch eine deklarierte Berechtigung.
4. HTTP bedienen. Jedes Plugin kann den URL-Bereich bei /plugins/<dein-slug>/... für sowohl statische Assets als auch dynamische Handler besitzen.
5. UI hinzufügen. Deklariere Adminseiten, Aktionsschaltflächen, Stylesheets für Plugins, Skripte für Plugins oder einen HTML-Block für zusätzlichen Inhalt in deinem Manifest, und Owncast fügt sie in seinen eigenen Chrome ein.
6. Zugang beschränken. Ein Plugin kann der Authentifizierungsanbieter der Seite sein. Lass Zuschauer sich anmelden (OAuth, ein Passwort, alles über HTTP), bevor sie zur Seite, zum Video, zum Chat oder zur API gelangen.

Was ein Plugin nicht tun kann

Von Design:

• Kein direkter Zugriff auf das Host-Dateisystem, Netzwerk oder Prozesse. Die Sandbox erzwingt dies. Plugins tun, was die Host-APIs bereitstellen und nur mit deklarierten Berechtigungen.
• Keine Identitätsvertretung. Jedes Plugin erhält eine Chatidentität (den Bot, den Owncast bei der Installation bereitstellt), und ausgehende Fediverse-Posts stammen vom eigenen Konto des Streamers.
• Keine inter-plugin-Lesungen. Der Speicher des Schlüssel-Wert-Speichers jedes Plugins ist benannt.
• Keine unbefristete Chatblockierung. Filteraufrufe sind zeitlich auf 50 ms begrenzt, und ein Plugin, das wiederholt Fehler auslöst, wird automatisch deaktiviert.

Deshalb kann ein Administrator ein Drittanbieter-Plugin installieren, ohne jede Codezeile zu prüfen. Die Vertrauensgrenze ist die Genehmigungsliste des Manifests.

Was als Nächstes zu tun ist

• Schnellstart. Erstelle ein neues Plugin, baue es, installiere es.
• JavaScript, Python, and Native WebAssembly. Choose a language and build path.
• Manifestreferenz. Jedes Feld, das deine plugin.manifest.json enthalten kann.
• Chat-Plugins. Bots, Moderationstools und Chatfilter bauen.
• Ereignisse. Jedes Ereignis, auf das dein Plugin abonnieren kann, mit Payload-Formen.
• Owncast-APIs. Jede owncast.* Methode, was sie tut und welche Berechtigung sie benötigt.
• Berechtigungen. Die vollständige Liste und wie das Sicherheitsmodell funktioniert.
• HTTP bedienen. Bediene URLs von deinem Plugin und schicke Echtzeit-Ereignisse an Browser.
• UI beitragen. Registriere Adminseiten und trage Aktionsschaltflächen unter dem Stream bei.
• Testen. Szenarientests, die dein Plugin durch die echte Laufzeit treiben.
• Verpacken & veröffentlichen. Bündle das .ocpkg, installiere es und liste es im Verzeichnis auf.

Quelle

• SDK-Quelle: github.com/owncast/plugin-sdk
• Example plugins: JavaScript · Python