Packaging & publishing plugins

Il formato di distribuzione di un plugin è il file .ocpkg: un singolo pacchetto contenente il tuo plugin.manifest.json, il codice del plugin, le directory public/ e assets/, e opzionalmente un'icona e un documento di istruzioni. Quel singolo file è tutto ciò di cui un amministratore del server ha bisogno per installare il tuo plugin.

Creazione del pacchetto

JavaScript

npm run package

npm run package only rebuilds when the bundle is missing. After changing source, run npm run build first so the package doesn't ship stale code.

Python

owncast-plugin-py package my-plugin

Native WebAssembly

Use your language toolchain to compile the module, then package it as a ZIP with the canonical plugin.wasm filename. The Native WebAssembly guide includes build commands for Rust, TinyGo, and AssemblyScript.

The resulting \<your-slug>.ocpkg contains the manifest and runnable code. It can also include the plugin's public/ and assets/ directories.

The JavaScript and Python packagers run the built plugin through owncast-plugin-test --load-only before writing the archive. This uses the same install-time load path as a real server, covering register(), manifest and runtime agreement, and permission-gated subscriptions. Native WebAssembly authors run owncast-plugin-test directly before packaging. See Native WebAssembly: Test before installing.

Il file è autosufficiente. Condividilo come preferisci:

• Allegalo a una release di GitHub
• Ospitalo sul tuo server
• Consegnalo a un amministratore via chat o email

Icona del plugin

Posiziona un icon.png nella radice del progetto (accanto a plugin.manifest.json) e il packager lo include automaticamente nel .ocpkg. L'interfaccia di amministrazione lo recupera da /api/plugins/\<your-slug>/icon e lo visualizza nella lista dei plugin e nella voce della barra laterale per ogni plugin che fornisce una pagina di amministrazione.

my-plugin/
├── plugin.manifest.json
├── icon.png              bundled automatically
├── src/
├── public/
└── assets/

Note:

• Nessun permesso richiesto. L'host serve l'icona direttamente. Non è necessario http.serve.
• L'icona è separata dalle icone dei pulsanti d'azione, che risiedono in public/ (fornite via web) e sono referenziate dal campo icon di una voce actions[]. Vedi UI: Pulsanti d'azione.

Istruzioni

Posiziona un INSTRUCTIONS.md nella radice del progetto (accanto a plugin.manifest.json) e il packager lo include automaticamente nel .ocpkg. L'interfaccia di amministrazione lo recupera da /api/admin/plugins/\<your-slug>/instructions e lo rende come markdown in una scheda Istruzioni nella pagina dei dettagli del plugin.

my-plugin/
├── plugin.manifest.json
├── INSTRUCTIONS.md          bundled automatically
├── src/
├── public/
└── assets/

Usalo per i passaggi di configurazione, le note sulla configurazione, quali permessi vengono richiesti e perché, e qualsiasi altra cosa che un amministratore deve sapere dopo l'installazione. I plugin senza tale file non mostrano la scheda Istruzioni. Il nome del file è fisso (INSTRUCTIONS.md). Non è richiesto il permesso http.serve.

Il file è rivolto all'amministratore, quindi scrivilo per lo streamer che ha installato il tuo plugin e sta aprendo l'interfaccia di amministrazione per capire come usarlo. Note rivolte agli sviluppatori in stile README dovrebbero invece andare nel README del tuo repository.

Cosa c'è dentro un .ocpkg

• plugin.manifest.json
• One code entry: plugin.js, plugin.py, or plugin.wasm
• icon.png se ne hai fornito uno
• INSTRUCTIONS.md se ne hai fornito uno
• Il contenuto della tua directory public/ se ne hai una (servito via web su /plugins/\<slug>/)
• Il contenuto della tua directory assets/ se ne hai una (accessibile dall'host per i campi del manifest che incorporano contenuto)

The code filename selects the runtime. A native module must be named plugin.wasm inside the archive, regardless of the plugin slug.

Build inputs such as node_modules, package.json, pyproject.toml, Cargo.toml, and uncompiled source do not belong in the package. They produce the code entry that the server runs.

Loose native WebAssembly files

During development, a native module can be installed without creating an .ocpkg. Copy the module and manifest into data/plugins/ with the same basename:

data/plugins/
├── my-plugin.wasm
└── my-plugin.manifest.json

Owncast scans for the .wasm file and reads the matching .manifest.json. The packaged .ocpkg format is still recommended for distribution because it keeps the code, manifest, and optional assets together.

Installazione su un server

Nell'admin di Owncast, apri Plugin nella barra laterale e clicca Carica plugin. Seleziona il tuo .ocpkg e il server lo installa in loco. Il nuovo plugin appare immediatamente nella lista.

Se l'interfaccia admin non è un'opzione (automazione, nessun accesso a un browser, deploy scriptati), puoi anche posizionare il .ocpkg direttamente nella directory data/plugins/ del server:

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

Il server scansiona periodicamente questa directory. Il plugin appare nella pagina Plugin dell'admin entro un paio di secondi.

In entrambi i casi, completa l'installazione nell'admin:

1. Clicca il tuo plugin nella lista per aprire la vista dei dettagli.
2. Controlla la scheda Permessi. Questi sono esattamente quelli dichiarati dal tuo manifest.
3. Attiva Abilitato per caricare il plugin. La prima attivazione salva anche il set di permessi approvato.

Aggiornamento di un plugin installato

To ship an update, replace the package file in data/plugins/ directly, or install the new version from the admin's Browse tab if you publish to the directory. The manifest's slug is the identity key: the new contents replace the existing entry with the same slug, whatever the file was called. Per forzare un ricaricamento immediato di un plugin abilitato, clicca Ricarica sulla sua riga.

Uploading from the admin's Plugins page only installs a new plugin. An upload whose slug already belongs to an installed plugin is rejected ("uninstall it before uploading another plugin with the same slug"), so uninstall the old one first if the admin upload is your only update path.

Two files in data/plugins/ that declare the same slug are also a conflict. Owncast keeps the first one it finds, ignores the other, and logs which package was skipped.

Cosa succede quando i permessi cambiano

• Hai rimosso dei permessi. Nessun avviso. Il plugin si ricarica con il set ridotto.
• Hai aggiunto dei permessi. The old approved version keeps running (it holds only the approved permissions) and the new package waits as pending, with a "needs re-approval" badge in the plugin list. The admin reviews the new permissions in the Permissions tab (new entries are tagged) and clicks Approve to accept the expanded set and load the update.

Le capacità effettive di un plugin non crescono mai senza il consenso esplicito dell'amministratore, nemmeno attraverso gli aggiornamenti.

Incrementare la versione

Incrementa version in plugin.manifest.json ogni volta che pubblichi una release. It's what admins see in the plugin list and what the registry uses to tell releases apart. The host doesn't gate loading on it: update identity is the slug, and the load-time check compares slug and permissions, not version.

Il versioning è per gli esseri umani. Semver è raccomandato ma non imposto.

Disabilitazione e disinstallazione

• Disabilita mantiene il plugin installato ma ne impedisce il caricamento. La scelta dell'amministratore viene mantenuta tra i riavvii. Riattiva Abilitato per caricarlo di nuovo.
• La disinstallazione rimuove completamente il plugin. Dalla pagina Plugin dell'admin clicca sull'icona del cestino nella riga del plugin e conferma. (Puoi anche rimuovere direttamente il .ocpkg da data/plugins/, e la successiva scansione rileva la cancellazione.)

Lista di controllo per la distribuzione

Prima di pubblicare un plugin:

• Il manifest dichiara solo ciò che usi. Rimuovi i permessi non usati. Più mirata è la tua richiesta, più semplice sarà la decisione di fiducia dell'amministratore.
• description è compilato. Gli amministratori lo vedono nella lista dei plugin e durante l'installazione. Una frase che descriva cosa fa il plugin.
• version riflette ciò che stai distribuendo. Semver è convenzionale.
• Il README nel tuo repo spiega cosa fa, quali permessi richiede e perché, e cosa configurare (variabili d'ambiente, impostazioni della pagina admin, ecc.).
• I test passano. Il comando di test del tuo SDK dovrebbe risultare verde.
• L'icona è inclusa se ne hai una.
• Un INSTRUCTIONS.md include tutto ciò che un amministratore deve sapere dopo l'installazione: passaggi di configurazione, note sulla configurazione, perché viene richiesto ogni permesso. I plugin con comportamenti non ovvi o configurazioni richieste dovrebbero includerne uno. I plugin triviali (un handler chat hello-world) non ne hanno bisogno.

Pubblicazione nella directory

Inserire il tuo plugin nella directory pubblica su owncast.directory è opzionale. Un .ocpkg è autosufficiente, quindi puoi sempre consegnarlo direttamente a un amministratore. La directory rende il tuo plugin scopribile e offre agli amministratori installazione e aggiornamenti con un clic.

Alcuni campi del manifest definiscono la tua scheda, quindi compilali prima: name (il nome visualizzato), version (incrementalo a ogni aggiornamento), slug (il tuo identificatore permanente, vedi Manifest), description (il riassunto in una riga sulla tua scheda), permissions (mantienili minimi, gli amministratori li revisionano), e un opzionale icon.png.

Accedi

La directory usa un accesso senza password tramite magic-link. Vai su owncast.directory/plugins/login, inserisci la tua email e clicca il link nella tua casella di posta. La tua email è la tua identità di autore, legata ai plugin che possiedi. Nella pagina del tuo account puoi impostare un nome visualizzato opzionale che appare come autore nelle tue schede.

Invia

Vai su owncast.directory/plugins/submit e carica il tuo .ocpkg. La directory legge il tuo manifest, valida il pacchetto e pubblica la versione. La sottomissione avviene attraverso il sito web, senza un passaggio di pubblicazione da riga di comando al momento. Il modulo accetta anche alcuni extra opzionali: un'immagine di anteprima (uno screenshot, PNG o JPEG fino a 5 MB), un link alla homepage, tag per la ricerca e un sommario che sovrascrive la descrizione del manifest.

Proprietà e aggiornamenti

• La prima persona che invia possiede lo slug. Quando pubblichi uno slug per la prima volta, questo viene vincolato al tuo account e nessun altro può pubblicare con quello slug. Una sottomissione per uno slug di proprietà di un altro autore viene rifiutata.
• Ogni versione viene pubblicata una sola volta. Per distribuire un aggiornamento, aumenta version nel tuo manifest, ricrea il pacchetto e invia di nuovo.
• Gestisci i tuoi plugin su owncast.directory/plugins/account, dove puoi vedere tutto quello che hai pubblicato e rimuovere una scheda.

Cosa vedono gli operatori

Nella vista Browse della directory il tuo plugin mostra il nome, l'autore, la descrizione, l'icona, l'ultima versione e l'immagine di anteprima se ne hai caricata una. Quando un amministratore lo installa, Owncast mostra i permessi richiesti dal tuo manifest, visualizza il tuo INSTRUCTIONS.md e elenca eventuali comandi chat che registri. Questi metadati sono ciò che un operatore usa per decidere se fidarsi e abilitare il tuo plugin, quindi scrivili pensando a quel lettore.

Dove andare dopo

• Riferimento Manifest per l'elenco completo dei campi del manifest.
• Permessi per il modello di fiducia e l'elenco completo dei permessi.
• Example plugins: JavaScript · Python.