Packaging & publishing plugins

O formato de distribuição de um plugin é o arquivo .ocpkg: um único pacote contendo seu plugin.manifest.json, o código do plugin, os diretórios public/ e assets/, e opcionalmente um ícone e um documento de instruções. Esse único arquivo é tudo o que um administrador de servidor precisa para instalar seu plugin.

Construindo o pacote

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.

O arquivo é autocontido. Compartilhe como preferir:

• Anexe-o a um release no GitHub
• Hospede-o em seu próprio servidor
• Envie-o a um administrador por chat ou e-mail

Ícone do plugin

Coloque um icon.png na raiz do seu projeto (ao lado de plugin.manifest.json) e o empacotador o inclui automaticamente no .ocpkg. A UI de administração busca-o em /api/plugins/\<your-slug>/icon e o renderiza na lista de plugins e na entrada da barra lateral para qualquer plugin que forneça uma página de administração.

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

Observações:

• Nenhuma permissão necessária. O host serve o ícone diretamente. Você não precisa de http.serve.
• O ícone é separado dos ícones dos botões de ação, que ficam em public/ (servidos via web) e são referenciados pelo campo icon de uma entrada actions[]. Veja UI: Botões de ação.

Instruções

Coloque um INSTRUCTIONS.md na raiz do seu projeto (ao lado de plugin.manifest.json) e o empacotador o inclui automaticamente no .ocpkg. A UI de administração busca-o em /api/admin/plugins/\<your-slug>/instructions e o renderiza como Markdown em uma aba Instruções na página de detalhes do plugin.

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

Use isto para passos de configuração, notas de configuração, quais permissões são solicitadas e por quê, e qualquer outra coisa que um administrador precise saber após a instalação. Plugins sem ele não exibem a aba Instruções. O nome do arquivo é fixo (INSTRUCTIONS.md). Permissão http.serve não é necessária.

O arquivo é voltado para administradores, então escreva-o para o streamer que instalou seu plugin e está abrindo a UI de administração para descobrir como usá-lo. Notas voltadas para desenvolvedores no estilo README devem ficar no README do seu repositório.

O que há dentro de um .ocpkg

• plugin.manifest.json
• One code entry: plugin.js, plugin.py, or plugin.wasm
• icon.png se você forneceu um
• INSTRUCTIONS.md se você forneceu um
• O conteúdo do seu diretório public/, se houver (servido pela web em /plugins/\<slug>/)
• O conteúdo do seu diretório assets/, se houver (lido pelo host para campos do manifest que embutem conteúdo)

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.

Instalando em um servidor

Na interface de administração do Owncast, abra Plugins na barra lateral e clique em Enviar plugin. Escolha seu .ocpkg e o servidor o instala no local. O novo plugin aparece na lista imediatamente.

Se a UI de administração não for uma opção (automação, sem acesso ao navegador, deploys scriptados), você também pode colocar o .ocpkg diretamente no diretório data/plugins/ do servidor:

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

O servidor faz a varredura desse diretório periodicamente. O plugin aparece na página Plugins da administração dentro de alguns segundos.

Em qualquer caso, finalize a instalação na administração:

1. Clique no seu plugin na lista para abrir a vista de detalhes.
2. Revise a aba Permissões. São exatamente o que seu manifest declarou.
3. Ative Habilitado para carregar o plugin. A primeira habilitação também captura o conjunto de permissões aprovado.

Atualizando um plugin instalado

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. Para forçar um recarregamento imediato de um plugin habilitado, clique em Recarregar na sua linha.

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.

O que acontece quando as permissões mudam

• Você removeu permissões. Silencioso. O plugin recarrega com o conjunto menor.
• Você adicionou permissões. 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.

As capacidades efetivas de um plugin nunca crescem sem consentimento explícito do administrador, mesmo entre atualizações.

Atualizando a versão

Atualize version em plugin.manifest.json sempre que você lançar uma versão. 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.

Versionamento é para humanos. Semver é recomendado, mas não obrigatório.

Desabilitar e desinstalar

• Desabilitar mantém o plugin instalado, mas deixa de carregá-lo. A escolha do administrador é persistida entre reinicializações. Ative Habilitado novamente para carregá-lo.
• Desinstalar remove o plugin completamente. Na página Plugins da administração, clique no ícone de lixeira na linha do plugin e confirme. (Você também pode remover o .ocpkg de data/plugins/ diretamente, e a próxima varredura detectará a exclusão.)

Lista de verificação de distribuição

Antes de publicar um plugin:

• O manifest declara apenas o que você usa. Remova permissões não usadas. Quanto menor sua solicitação, mais fácil a decisão de confiança do administrador.
• description está preenchido. Administradores o veem na lista de plugins e durante a instalação. Uma frase cobrindo o que o plugin faz.
• version reflete o que você está entregando. Semver é convencional.
• O README no seu repositório explica o que ele faz, quais permissões solicita e por quê, e o que configurar (variáveis de ambiente, configurações da página de administração, etc.).
• Os testes passam. O comando de teste do seu SDK deve estar verde.
• O ícone é incluído se você tiver um.
• Um INSTRUCTIONS.md deve conter tudo o que um administrador precisa saber após a instalação: passos de configuração, notas de configuração, por que cada permissão é solicitada. Plugins com comportamento não óbvio ou configuração obrigatória devem incluir um. Plugins triviais (um manipulador de chat 'hello-world') não precisam dele.

Publicar no diretório

Listar seu plugin no diretório público em owncast.directory é opcional. Um .ocpkg é autocontido, então você sempre pode entregá-lo diretamente a um administrador. O diretório apenas torna seu plugin descobrível e oferece aos administradores instalação e atualizações com um clique.

Alguns campos do manifest moldam sua listagem, então preencha-os primeiro: name (o nome exibido), version (aumente-o a cada atualização), slug (seu identificador permanente, veja Manifest), description (o resumo em uma linha no seu cartão), permissions (mantenha-os mínimos, administradores os revisam), e um icon.png opcional.

Entrar

O diretório usa login sem senha, por link mágico. Vá para owncast.directory/plugins/login, insira seu e-mail e clique no link na sua caixa de entrada. Seu e-mail é sua identidade de autor, vinculada aos plugins que você possui. Na página da sua conta você pode definir um nome de exibição opcional que aparece como autor nas suas listagens.

Enviar

Vá para owncast.directory/plugins/submit e faça upload do seu .ocpkg. O diretório lê seu manifest, valida o pacote e publica a versão. A submissão é feita através do site, sem uma etapa de publicação via linha de comando atualmente. O formulário também aceita alguns extras opcionais: uma imagem de pré-visualização (uma captura de tela, PNG ou JPEG de até 5 MB), um link para homepage, tags de navegação e um resumo que substitui a descrição do manifest.

Propriedade e atualizações

• O primeiro a submeter torna-se proprietário do slug. Quando você publica um slug pela primeira vez, ele fica vinculado à sua conta e mais ninguém pode publicar sob ele. Uma submissão para um slug pertencente a outro autor é rejeitada.
• Cada versão é publicada uma única vez. Para enviar uma atualização, aumente version no seu manifest, reempacote e submeta novamente.
• Gerencie seus plugins em owncast.directory/plugins/account, onde você pode ver tudo o que publicou e remover uma listagem.

O que os operadores veem

Na visualização Browse do diretório, seu plugin mostra seu nome, autor, descrição, ícone, versão mais recente e imagem de pré-visualização se você fez upload de uma. Quando um administrador o instala, o Owncast mostra as permissões solicitadas pelo seu manifest, renderiza seu INSTRUCTIONS.md e lista quaisquer comandos de chat que você registre. Esses metadados são o que um operador usa para decidir se confia e habilita seu plugin, então escreva-os tendo esse leitor em mente.

Para onde ir a seguir

• Referência do manifest para a lista completa dos campos do manifest.
• Permissões para o modelo de confiança e a lista completa de permissões.
• Example plugins: JavaScript · Python.