Plugin de démarrage rapide

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.

Prérequis

• Un serveur Owncast que vous pouvez administrer, version 0.3.0 ou plus récent.

JavaScript

• Node.js 18 ou plus récent (node --version pour vérifier) pour l'outil @owncast/plugin-sdk.

Python

• Python 3.8 ou plus récent, et uv ou pip pour installer l'outil owncast-plugin-py.

1. Créer un nouveau plugin

L'identifiant d'un plugin est son slug : lettres minuscules, chiffres et tirets, commençant par une lettre. Il est utilisé comme nom de répertoire, nom de fichier de sortie, et préfixe d'URL.

JavaScript

Échafaudez un projet avec create-owncast-plugin, en passant le slug :

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

Vous avez maintenant :

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 crée également node_modules/. Aucun de ces éléments n'est créé pour vous, mais vous pouvez ajouter un icon.png (affiché dans la liste des plugins de l'admin), un répertoire public/ (fichiers statiques servis à /plugins/my-plugin/), et un répertoire assets/ (fichiers que l'hôte intègre pour les champs de manifeste).

Python

Échafaudez un projet avec new, en passant le slug. uvx exécute le générateur directement depuis PyPI sans installer quoi que ce soit :

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

Vous avez maintenant :

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

Le manifeste a à la fois un nom affiché lisible par l'humain ("name": "My Plugin") et un slug ("slug": "my-plugin"). Le nom affiché est ce que voient les administrateurs dans les listes. Le slug est l'identifiant canonique. Consultez la référence du manifeste pour les règles.

2. Écrivez du code

Un gestionnaire réagit à un événement. Le SDK dérive la liste d'abonnement du manifeste des gestionnaires que vous définissez, donc il n'y a rien d'autre à garder synchronisé. Voici un bot écho :

JavaScript

Ouvrez src/plugin.js :

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

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

Python

Créez src/plugin.py :

from owncast_plugin import plugin, owncast

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

Consultez la référence des gestionnaires pour tout ce que vous pouvez raccorder, et la référence des API pour chaque méthode owncast.*.

3. Construisez le plugin

Cela produit my-plugin.ocpkg à la racine de votre projet : un seul fichier contenant votre manifeste, le plugin compilé, et le contenu de public/ et assets/. Le .ocpkg est le format de distribution : ce fichier unique est tout ce dont un administrateur a besoin.

JavaScript

npm run package

Python

owncast-plugin-py package

4. Exécutez les tests

Chaque scénario déclenche des événements à travers l'exécution réelle du plugin avec des effets secondaires simulés, donc un test réussi signifie le même comportement en production. Consultez le guide de test pour le modèle de données complet.

JavaScript

npm test

Python

owncast-plugin-py test

5. (Optionnel) itérez contre un serveur de développement local

Serve le plugin à http://localhost:8080/plugins/my-plugin/ pour interroger les points de terminaison, ouvrir des pages statiques dans un navigateur, ou déclencher des gestionnaires d'événements via les points de terminaison d'aide /_dev/ (par exemple POST /_dev/chat). Redémarrez le serveur de développement lorsque vous modifiez votre code.

JavaScript

npm run serve

Python

owncast-plugin-py serve

6. Installez sur votre serveur

Dans l'administration Owncast, ouvrez Plugins dans la barre latérale et cliquez sur Télécharger le plugin. Choisissez le fichier my-plugin.ocpkg que votre compilation a produit. Le plugin apparaît immédiatement dans la liste. Activez Activé pour le charger.

Sinon, copiez my-plugin.ocpkg dans le répertoire data/plugins/ de votre serveur et le prochain scan le prendra :

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

Si le plugin déclare des permissions, l'administrateur les examine dans l'onglet Permissions sur la page de détail du plugin avant de l'activer. Le premier activation capture l'ensemble de permissions approuvé. 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.

Que lire ensuite

• Choisir un SDK et ses pages JavaScript / Python pour la référence complète spécifique à la langue.
• Référence du manifeste pour le schéma complet pour plugin.manifest.json.
• Référence des gestionnaires pour chaque événement auquel vous pouvez vous abonner.
• APIs Owncast pour chaque méthode que vous pouvez appeler à partir du code du plugin.

Quand les choses vont mal

• Le plugin n'apparaît pas dans la liste de l'administration. Assurez-vous que le .ocpkg est dans data/plugins/, pas seulement plugins/, et que le nom de fichier se termine par .ocpkg. La page Plugins de l'administrateur a un bouton Rafraîchir si vous ne voulez pas attendre le prochain scan.
• Le plugin apparaît mais ne s'active pas. Vérifiez la vue de détail du plugin de l'administrateur. La colonne Statut affiche erreur si le manifeste est invalide ou si le plugin a échoué à s'instancier. Survolez pour le message, ou exécutez vos tests localement pour capturer le même problème avant de déployer.
• Le plugin s'active mais ne fait rien. Assurez-vous d'utiliser le bon nom de gestionnaire (onChatMessage / on_chat_message, pas onMessage) et que la permission correspondante figure dans votre manifeste. 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.
• Le plugin est désactivé automatiquement. Un filtre qui génère une erreur ou reste bloqué cinq fois de suite est désactivé pour le reste de la session. Corrigez le bug, reconstruisez, déployez à nouveau et réactivez.