Configuration via Plugins

Owncast oferece aos plugins duas maneiras de permitir que um administrador mude configurações. Declare um bloco config no manifesto e o Owncast renderiza um formulário tipado para você, sem HTML de administrador e sem código para salvar ou carregar. Ou registre uma página admin e sirva seu próprio HTML.

Use o bloco config do manifesto para controles planos e tipados: strings, números e switches. Acesse uma página de administração personalizada somente quando você precisar de uma interface que o formulário automático não consiga expressar, como um layout agrupado, uma pré-visualização ao vivo ou um botão de ação que chama sua própria API. Os dois podem coexistir. Um plugin pode ter tanto a aba de Configurações do formulário automático quanto uma ou mais páginas de administração personalizadas.

Declare configurações no manifesto

Cada entrada sob config possui um type, um default e uma description:

{
  "config": {
    "greeting": { "type": "string", "default": "welcome!", "description": "First-join message" },
    "cooldownMs": { "type": "number", "default": 2000, "description": "Per-user command cooldown" },
    "modOnly": { "type": "boolean", "default": false, "description": "Restrict to moderators" }
  }
}

Campo	Notas
type	Um dos string, number ou boolean. Qualquer outro valor é aceito, mas resulta em uma entrada de texto simples e sem verificação de tipo ao salvar.
default	O valor retornado por config.get até que um administrador salve uma substituição. Seu tipo JSON deve corresponder ao type.
description	O rótulo mostrado ao lado do campo no formulário de administração. Cai de volta para o nome da chave quando está vazio.

Nomes de chaves não podem começar com __. Esse prefixo é reservado para o estado por instância que o host injeta, e um plugin que declara uma chave como __internal não consegue carregar.

O que o administrador vê

Um plugin que declara um bloco config ganha uma aba Configurações em sua página de detalhes sob Admin → Plugins. Owncast constrói o formulário a partir do esquema:

• string renderiza uma entrada de texto, number uma entrada numérica, e boolean um switch.
• A description é o rótulo do campo.
• O default é exibido até que um administrador salve uma substituição.
• Uma chave cujo nome se parece com uma credencial é renderizada como uma entrada de senha mascarada. A correspondência é insensível a maiúsculas e é acionada quando o nome contém secret, password, token, apikey ou api_key, ou é a palavra isolada key. Portanto, apiKey, clientSecret, accessToken, e webhook_secret são mascarados. Nomes como accessKey ou keyValue não são, porque key apenas corresponde como uma palavra inteira. Nomeie um campo secreto como apiKey, api_key, ou qualquer coisa que termine em Secret ou Token se você quiser que seja mascarado.

Um plugin sem bloco config não mostra aba de Configurações.

Leia valores em tempo de execução

owncast.config.get(key, fallback?) retorna a substituição do administrador quando uma é definida, caso contrário, o padrão declarado, já analisado para o tipo declarado.

JavaScript

const cooldownMs = owncast.config.get('cooldownMs', 2000);
const modOnly = owncast.config.get('modOnly', false);

Python

cooldown_ms = owncast.config.get("cooldownMs", 2000)
mod_only = owncast.config.get("modOnly", False)

config.get é ambiental, então não precisa de permissão. Um campo number retorna como um número e um boolean como um bool, então você não analisa strings você mesmo. Para uma chave desconhecida, ou uma chave declarada que não tem nem um padrão nem uma substituição salva, retorna fallback (undefined no JavaScript e None no Python quando você passa nenhum). Passe um fallback que você possa executar.

A assinatura completa está no referência das APIs.

Validação e armazenamento

Quando um administrador salva o formulário, o Owncast verifica cada valor contra o esquema antes de armazená-lo:

• Uma chave não declarada no manifesto é rejeitada com 400 chave de configuração desconhecida.
• Um campo string deve receber uma string, um number um número, e um boolean um bool. Uma incompatibilidade de tipo é rejeitada. Qualquer outro type declarado é armazenado como está.
• O corpo da solicitação é limitado a 1 MB.

Substituições persistem na própria loja de chave/valor do plugin sob a chave reservada owncast.config, nomeada pelo slug do plugin. Outros plugins não podem lê-las, e elas sobrevivem a reinicializações e reinstalações. Mudar o slug após o lançamento inicia uma nova loja, então substituições salvas revertam para seus padrões, a mesma regra que se aplica ao restante de seus dados KV.