Ir para o conteúdo principal

Estenda o Owncast com plugins

O Owncast pode ser estendido com plugins: programas pequenos que o servidor carrega em tempo de execução para reagir a mensagens de chat, eventos de stream, atividades do fediverse e solicitações HTTP. Eles funcionam dentro de um ambiente seguro, então um plugin pode falhar sem derrubar o servidor, e o host aplica um modelo claro de permissão para que um administrador sempre saiba o que um plugin pode acessar.

Plugins require Owncast v0.3.0

Plugins são funcionalidades novas, introduzidas no Owncast 0.3.0, e a API ainda está evoluindo. Se você encontrar um bug ou tiver uma sugestão, por favor, abra uma issue ou converse ao vivo com a comunidade.

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.

O que você pode construir​

  • Bots de chat que respondem a palavras-chave ou comandos, publicam lembretes, realizam enquetes ou moderam spam.
  • Filtros que reescrevem ou descartam mensagens de chat antes que cheguem aos espectadores.
  • Sobreposições renderizadas sobre seu stream, falando com os endpoints HTTP do seu plugin.
  • Integrações que conectam o Owncast ao Discord, ao fediverse, push no navegador ou qualquer serviço HTTPS.
  • Ferramentas administrativas que adicionam uma guia à UI de administração do Owncast para configurações específicas do plugin.
  • Botões de ação que aparecem sob seu stream, lançando widgets, páginas de doação ou qualquer outra coisa que você sirva.

Cada exemplo de plugin no SDK é um ponto de partida completo que você pode copiar.

Choose an authoring path​

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

  • JavaScript com @owncast/plugin-sdk. Scaffold with npx create-owncast-plugin, write definePlugin({ ... }), and build with npm run package.
  • Python com 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}")

Como se encaixa​

Um plugin é um único arquivo .ocpkg contendo o manifesto do seu plugin, o código compilado e quaisquer ativos estáticos. Um administrador coloca o arquivo no diretório data/plugins/ do Owncast e habilita-a a partir da página de Plugins no admin.

Uma vez habilitado, o plugin roda dentro do processo do Owncast. Os manipuladores que você definiu são acionados quando eventos correspondentes acontecem. As APIs que você chama (enviando chat, lendo configuração, buscando URLs) passam pelo host, que verifica as permissões que você declarou no seu manifesto.

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.

O que um plugin pode fazer​

  1. Inscrever-se em eventos. Mensagens de chat, início e parada de stream, seguimentos pelo fediverse, novos usuários de chat que se juntam. Defina um método manipulador e o SDK derivará a inscrição.
  2. Filtrar chat. Veja cada mensagem de chat antes que ela seja transmitida, modifique-a, ou descarte-a.
  3. Chamar APIs do Owncast. owncast.chat.send(text), owncast.kv.get(key), owncast.http.fetch(url), e dezenas mais, a maioria condicionada por uma permissão declarada.
  4. Servir HTTP. Cada plugin pode possuir o espaço de URL em /plugins/<seu-slug>/... para ativos estáticos e manipuladores dinâmicos.
  5. Adicionar UI. Declare páginas administrativas, botões de ação, folhas de estilo do plugin, scripts do plugin, ou um bloco HTML de conteúdo extra no seu manifesto e o Owncast os incorpora em seu próprio chrome.
  6. Controlar acesso. Um plugin pode ser o provedor de autenticação do site. Faça com que os espectadores façam login (OAuth, uma senha, qualquer coisa sobre HTTP) antes que possam acessar a página, o vídeo, o chat, ou a API.

O que um plugin não pode fazer​

Por design:

  • Sem acesso direto ao sistema de arquivos do host, rede ou processos. O ambiente seguro aplica isso. Os plugins fazem o que as APIs do host expõem, e apenas com permissões declaradas.
  • Sem falsificação de identidade. Cada plugin recebe uma identidade de chat (o bot que o Owncast provisiona na instalação), e as postagens de saída no fediverse vêm da conta própria do streamer.
  • Sem leituras entre plugins. Cada armazenamento de chave-valor de um plugin é nomeado.
  • Sem bloqueio indefinido de chat. Chamadas de filtro são limitadas a 50 ms, e um plugin que falha repetidamente é desativado automaticamente.

É por isso que um administrador pode instalar um plugin de terceiros sem auditar cada linha de código. A fronteira de confiança é a lista de permissões do manifesto.

Para onde ir a seguir​

Fonte​

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation
Gabe KangasGabe Kangas
G
Gabe Kangas