Plugin de início rápido

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é-requisitos

• Um servidor Owncast que você pode administrar, versão 0.3.0 ou mais recente.

JavaScript

• Node.js 18 ou mais recente (node --version para verificar) para a toolchain @owncast/plugin-sdk.

Python

• Python 3.8 ou mais recente, e uv ou pip para instalar a toolchain owncast-plugin-py.

1. Crie um novo plugin

O identificador de um plugin é seu slug: letras minúsculas, dígitos e hífens, começando com uma letra. É usado como o nome do diretório, o nome do arquivo de saída e o prefixo da URL.

JavaScript

Crie um projeto com create-owncast-plugin, passando o slug:

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

Você agora tem:

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 também cria node_modules/. Nenhum destes é criado para você, mas você pode adicionar um icon.png (exibido na lista de plugins do admin), um diretório public/ (arquivos estáticos servidos em /plugins/meu-plugin/), e um diretório assets/ (arquivos que o host insere para campos de manifesto).

Python

Crie um projeto com new, passando o slug. uvx executa o criador diretamente do PyPI sem instalar nada:

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

Você agora tem:

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

O manifesto possui tanto um nome de exibição legível por humanos ("name": "Meu Plugin") quanto um slug ("slug": "meu-plugin"). O nome de exibição é o que os administradores veem nas listas. O slug é o identificador canônico. Veja a referência do manifesto para as regras.

2. Escreva algum código

Um manipulador reage a um evento. O SDK deriva a lista de assinaturas do manifesto a partir dos manipuladores que você define, então não há nada mais para manter em sincronia. Aqui está um bot de eco:

JavaScript

Abra src/plugin.js:

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

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

Python

Crie src/plugin.py:

from owncast_plugin import plugin, owncast

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

Veja a referência de manipuladores para tudo que você pode conectar, e a referência de APIs para cada método owncast.*.

3. Construa o plugin

Isto produz meu-plugin.ocpkg na raiz do seu projeto: um único arquivo contendo seu manifesto, o plugin compilado e o conteúdo de public/ e assets/. O .ocpkg é o formato de distribuição: aquele arquivo é tudo que um administrador precisa.

JavaScript

npm run package

Python

owncast-plugin-py package

4. Execute os testes

Cada cenário gera eventos através do tempo de execução real do plugin com efeitos colaterais simulados, então um teste bem-sucedido significa o mesmo comportamento em produção. Veja o guia de testes para o modelo de dados completo.

JavaScript

npm test

Python

owncast-plugin-py test

5. (Opcional) iterar contra um servidor de desenvolvimento local

Serve o plugin em http://localhost:8080/plugins/meu-plugin/ para testar endpoints, abrir páginas estáticas no navegador ou acionar manipuladores de eventos através dos endpoints auxiliares /_dev/ (por exemplo POST /_dev/chat). Reinicie o servidor de desenvolvimento quando você mudar seu código.

JavaScript

npm run serve

Python

owncast-plugin-py serve

6. Instale no seu servidor

No admin do Owncast, abra Plugins na barra lateral e clique em Fazer upload do plugin. Escolha o arquivo meu-plugin.ocpkg que sua construção gerou. O plugin aparece na lista imediatamente. Ative Habilitado para carregá-lo.

Alternativamente, copie meu-plugin.ocpkg para o diretório data/plugins/ do seu servidor e a próxima verificação o pegará:

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

Se o plugin declarar permissões, o administrador as revisa na aba Permissões na página de detalhes do plugin antes de habilitá-lo. A primeira ativação captura o conjunto de permissões aprovadas. 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.

O que ler em seguida

• Escolhendo um SDK e suas páginas JavaScript / Python para a referência completa específica da linguagem.
• Referência do Manifesto para o esquema completo do plugin.manifest.json.
• Referência de Manipuladores para cada evento ao qual você pode se inscrever.
• APIs do Owncast para cada método que você pode chamar do código do plugin.

Quando as coisas dão errado

• O plugin não aparece na lista do admin. Certifique-se de que o .ocpkg está em data/plugins/, não apenas plugins/, e o nome do arquivo termina em .ocpkg. A página Plugins do admin tem um botão Atualizar se você não quiser esperar pela próxima verificação.
• O plugin aparece, mas não pode ser ativado. Verifique a visualização de detalhes do plugin do admin. A coluna Status mostra erro se o manifesto for inválido ou o plugin falhou ao instanciar. Passe o mouse para ver a mensagem ou execute seus testes localmente para capturar o mesmo problema antes de enviar.
• O plugin é ativado, mas não faz nada. Certifique-se de que está usando o nome de manipulador correto (onChatMessage / on_chat_message, não onMessage) e que a permissão correspondente está em seu manifesto. 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.
• O plugin é desativado automaticamente. Um filtro que lança ou congela cinco vezes consecutivas é desativado pelo resto da sessão. Corrija o bug, reconstrua, reimplante e reabilite.