Plugin-Quickstart

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.

Voraussetzungen

• Ein Owncast-Server, den Sie verwalten können, Version 0.3.0 oder neuer.

JavaScript

• Node.js 18 oder neuer (node --version, um zu überprüfen) für die @owncast/plugin-sdk-Toolchain.

Python

• Python 3.8 oder neuer, und uv oder pip, um die owncast-plugin-py-Toolchain zu installieren.

1. Ein neues Plugin erstellen

Die Kennung eines Plugins ist sein Slug: Kleinbuchstaben, Ziffern und Bindestriche, die mit einem Buchstaben beginnen. Es wird als Verzeichnisname, Ausgabedateiname und URL-Präfix verwendet.

JavaScript

Erstellen Sie ein Projekt mit create-owncast-plugin, geben Sie das Slug an:

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

Sie haben nun:

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 erstellt auch node_modules/. Keine dieser Dateien wird für Sie erstellt, aber Sie können eine icon.png (im Admin-Pluginliste angezeigt), ein Verzeichnis public/ (statische Dateien, die unter /plugins/my-plugin/ bereitgestellt werden) und ein Verzeichnis assets/ (Dateien, die der Host inline für Manifestfelder einfügt) hinzufügen.

Python

Erstellen Sie ein Projekt mit new, geben Sie das Slug an. uvx führt den Gerüstbau direkt von PyPI aus, ohne etwas zu installieren:

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

Sie haben nun:

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

Das Manifest hat sowohl einen menschenlesbaren Anzeigenamen ("name": "My Plugin") als auch einen Slug ("slug": "my-plugin"). Der Anzeigename ist das, was Administratoren in Listen sehen. Der Slug ist der kanonische Bezeichner. Siehe die Manifestreferenz für die Regeln.

2. Schreiben Sie etwas Code

Ein Handler reagiert auf ein Ereignis. Das SDK leitet die Abonnentenliste des Manifests von den Handlern ab, die Sie definieren, sodass nichts anderes synchronisiert werden muss. Hier ist ein Echo-Bot:

JavaScript

Öffnen Sie src/plugin.js:

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

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

Python

Erstellen Sie src/plugin.py:

from owncast_plugin import plugin, owncast

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

Siehe die Handlerreferenz für alles, in das Sie sich einhaken können, und die APIs-Referenz für jede owncast.*-Methode.

3. Bauen Sie das Plugin

Dies erzeugt my-plugin.ocpkg in Ihrem Projektstamm: eine einzelne Datei, die Ihr Manifest, das kompilierte Plugin und den Inhalt von public/ und assets/ enthält. Die .ocpkg ist das Distributionsformat: Diese eine Datei ist alles, was ein Administrator braucht.

JavaScript

npm run package

Python

owncast-plugin-py package

4. Führen Sie die Tests durch

Jedes Szenario löst Ereignisse durch die echte Plugin-Laufzeit mit simulierten Nebeneffekten aus, sodass ein erfolgreicher Test dasselbe Verhalten in der Produktion bedeutet. Siehe die Testanleitung für das vollständige Datenmodell.

JavaScript

npm test

Python

owncast-plugin-py test

5. (Optional) gegen einen lokalen Entwicklungsserver iterieren

Dient das Plugin unter http://localhost:8080/plugins/my-plugin/ zum Curlen von Endpunkten, Öffnen statischer Seiten in einem Browser oder Auslösen von Ereignis-Handlern über die /_dev/-Hilfseindpunkte (zum Beispiel POST /_dev/chat). Starten Sie den Entwicklungsserver neu, wenn Sie Ihren Code ändern.

JavaScript

npm run serve

Python

owncast-plugin-py serve

6. Installieren Sie es auf Ihrem Server

Im Owncast-Admin öffnen Sie Plugins in der Seitenleiste und klicken auf Plugin hochladen. Wählen Sie die Datei my-plugin.ocpkg, die Ihr Build erstellt hat. Das Plugin erscheint sofort in der Liste. Aktivieren Sie Aktiviert, um es zu laden.

Alternativ können Sie my-plugin.ocpkg in das Verzeichnis data/plugins/ Ihres Servers kopieren, und der nächste Scan-Tick wird es erfassen:

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

Wenn das Plugin Berechtigungen deklariert, überprüft der Administrator sie im Tab Berechtigungen auf der Detailseite des Plugins, bevor er sie aktiviert. Die erste Aktivierung erfasst das genehmigte Berechtigungsset. 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.

Was als Nächstes gelesen werden soll

• Wählen Sie ein SDK und seine Seiten JavaScript / Python für die vollständige sprachspezifische Referenz.
• Manifestreferenz für das vollständige Schema von plugin.manifest.json.
• Handlerreferenz für jedes Ereignis, auf das Sie sich abonnieren können.
• Owncast-APIs für jede Methode, die Sie aus dem Plugin-Code aufrufen können.

Wenn etwas schiefgeht

• Das Plugin erscheint nicht in der Admin-Liste. Stellen Sie sicher, dass die .ocpkg im data/plugins/ und nicht nur in plugins/ ist, und dass der Dateiname mit .ocpkg endet. Die Admin-Plugins-Seite verfügt über einen Aktualisieren-Button, wenn Sie nicht auf den nächsten Scan-Tick warten möchten.
• Das Plugin erscheint, kann aber nicht aktiviert werden. Überprüfen Sie die Detailansicht des Plugins des Administrators. Die Status-Spalte zeigt Fehler an, wenn das Manifest ungültig ist oder das Plugin nicht instanziiert werden konnte. Fahren Sie mit dem Mauszeiger über die Nachricht oder führen Sie Ihre Tests lokal aus, um dasselbe Problem vor dem Versand zu erkennen.
• Das Plugin wird aktiviert, macht jedoch nichts. Stellen Sie sicher, dass Sie den richtigen Handler-Namen verwenden (onChatMessage / on_chat_message, nicht onMessage) und dass die entsprechende Berechtigung in Ihrem Manifest vorhanden ist. 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.
• Das Plugin wird automatisch deaktiviert. Ein Filter, der fünf Mal in Folge einen Fehler auslöst oder hängen bleibt, wird für den Rest der Sitzung deaktiviert. Beheben Sie den Fehler, bauen Sie neu, stellen Sie bereit und aktivieren Sie erneut.