Passer au contenu principal

Étendre Owncast avec des plugins

Owncast peut être étendu avec des plugins : de petits programmes que le serveur charge à l'exécution pour réagir aux messages de chat, aux événements de diffusion, aux activités du fediverse et aux requêtes HTTP. Ils s'exécutent dans un environnement isolé, de sorte qu'un plugin peut planter sans faire tomber le serveur, et l'hôte applique un modèle de permissions clair afin qu'un administrateur sache toujours ce qu'un plugin peut toucher.

Plugins require Owncast v0.3.0

Les plugins sont une toute nouvelle fonctionnalité, introduite dans Owncast 0.3.0, et l'API est encore en évolution. Si vous rencontrez un bug ou avez une suggestion, veuillez ouvrir un problème ou discuter en direct avec la communauté.

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.

Ce que vous pouvez construire​

  • Des chatbots qui répondent à des mots-clés ou des commandes, publient des rappels, organisent des sondages ou modèrent le spam.
  • Des filtres qui réécrivent ou suppriment les messages de chat avant qu'ils n'atteignent les spectateurs.
  • Des superpositions rendues au-dessus de votre flux, parlant aux points de terminaison HTTP de votre plugin.
  • Des intégrations qui relient Owncast à Discord, au fediverse, aux notifications push du navigateur ou à tout service HTTPS.
  • Des outils d'administration qui ajoutent un onglet à l'interface d'administration d'Owncast pour les paramètres spécifiques aux plugins.
  • Des boutons d'action qui apparaissent sous votre stream, lançant des widgets, des pages de dons ou autre chose que vous servez.

Chaque exemple de plugin dans le SDK est un point de départ complet que vous pouvez copier.

Choose an authoring path​

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

  • JavaScript avec @owncast/plugin-sdk. Créez une structure avec npx create-owncast-plugin, écrivez definePlugin({ ... }), and build with npm run package.
  • Python avec 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}")

Comment cela s'assemble​

Un plugin est un seul fichier .ocpkg contenant le manifeste de votre plugin, le code compilé et tous les actifs statiques. Un administrateur place le fichier dans le répertoire data/plugins/ d'Owncast et l'active depuis la page Plugins dans l'administration.

Une fois activé, le plugin s'exécute à l'intérieur du processus Owncast. Les gestionnaires que vous avez définis sont déclenchés lorsque des événements correspondants se produisent. Les API que vous appelez (envoi de chat, lecture de config, récupération d'URL) passent par l'hôte, qui vérifie les permissions que vous avez déclarées dans votre manifeste.

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.

Ce qu'un plugin peut faire​

  1. S'abonner aux événements. Messages de chat, début et fin de diffusion, suivis du fediverse, nouveaux utilisateurs de chat rejoignent. Définissez une méthode gestionnaire et le SDK dérive l'abonnement.
  2. Filtrer le chat. Voir chaque message de chat avant qu'il ne soit diffusé, le modifier ou le supprimer.
  3. Appeler les API d'Owncast. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url) et des dizaines d'autres, la plupart soumis à une permission déclarée.
  4. Servir HTTP. Chaque plugin peut posséder l'espace d'URL à /plugins/<votre-slug>/... pour les actifs statiques et les gestionnaires dynamiques.
  5. Ajouter une interface utilisateur. Déclarez des pages d'administration, des boutons d'action, des feuilles de style de plugins, des scripts de plugins ou un bloc HTML supplémentaire dans votre manifeste et Owncast les intègre dans son propre chrome.
  6. Gérer l'accès. Un plugin peut être le fournisseur d'authentification du site. Faire en sorte que les spectateurs se connectent (OAuth, un mot de passe, quoi que ce soit par HTTP) avant de pouvoir accéder à la page, à la vidéo, au chat ou à l'API.

Ce qu'un plugin ne peut pas faire​

De par sa conception :

  • Pas d'accès direct au système de fichiers, au réseau ou aux processus de l'hôte. Le bac à sable impose cela. Les plugins font ce que les API de l'hôte exposent, et uniquement avec les permissions déclarées.
  • Pas d'usurpation d'identité. Chaque plugin obtient une identité de chat (le bot qu'Owncast fournit à l'installation), et les publications sortantes sur le fediverse proviennent du compte de celui qui diffuse.
  • Pas de lectures inter-plugins. Le stockage de clé-valeur de chaque plugin est dans un espace de noms.
  • Pas de blocage de chat indéfini. Les appels de filtrage sont limités dans le temps à 50 ms, et un plugin qui échoue de manière répétée est désactivé automatiquement.

C'est pourquoi un administrateur peut installer un plugin tiers sans auditer chaque ligne de code. La frontière de confiance est la liste de permissions du manifeste.

Où aller ensuite​

Source​

Improve this page

See something missing or incorrect? Edit the English version of this page or help improve translations.

Contributors to this documentation
Gabe KangasGabe Kangas
G
Gabe Kangas