action.json e pad.json

Cada chave dos dois arquivos que a Vovó lê de uma pasta ou de um zip, gerada do próprio código da Vovó, então sempre corresponde a esta versão. A Vovó confere cada arquivo quando ele chega e o recusa com uma frase dizendo o que está errado; uma chave que ela não conhece passa sem uma palavra, e um editor que lê o schema a sublinha.

Uma chave tem letras minúsculas, dígitos e _, e um nome pode ter também -, cada um com no máximo 32 caracteres.

Para um editor que completa as chaves e sublinha os erros, nomeie o schema no começo do arquivo, como fazem os exemplos. O vovo dev grava o action.schema.json ao lado das partes de uma ação; o código-fonte da Vovó tem os dois na pasta api.

action.json

O manifesto de uma ação: como ela se chama, o que ela ouve, o que pede e o que oferece a quem opera a live. Ele fica ao lado de index.html, style.css, script.js e files/, num pacote ou numa pasta.

{
    "$schema": "./action.schema.json",
    "name": "Raffle",
    "id": "example.raffle",
    "version": "1.2.0",
    "api": 1,
    "author": "A maker",
    "site": "https://example.com/raffle",
    "description": "!join in chat joins the wheel; the panel draws the winner.",
    "license": "MIT",
    "triggers": ["chat", "timer"],
    "bindings": [
        { "event": "chat", "filter": [{ "field": "text", "op": "starts", "value": "!join" }] },
        { "event": "timer", "filter": [{ "field": "every", "op": "is", "value": 300 }] }
    ],
    "permissions": ["chat.send"],
    "controls": [
        { "key": "open", "label": "Entries open", "kind": "toggle" },
        { "key": "prize", "label": "Prize", "kind": "text" }
    ],
    "settings": [
        { "key": "color", "label": "Wheel colour", "kind": "color", "default": "#840926" },
        { "key": "size", "label": "Size", "kind": "number", "min": 200, "max": 800, "step": 10, "unit": "px", "default": 420 },
        { "key": "side", "label": "Side", "kind": "choice", "options": ["Left", "Right"], "default": "Right" }
    ],
    "panel": [
        { "kind": "control", "key": "open" },
        { "kind": "control", "key": "prize" },
        { "kind": "form", "name": "add", "label": "Put someone in", "button": "Put", "fields": [{ "key": "who", "label": "Name" }] },
        { "kind": "button", "name": "draw", "label": "Draw", "confirm": true },
        { "kind": "list", "key": "names", "label": "In the wheel", "empty": "Nobody yet", "buttons": [{ "name": "out", "label": "Take out", "confirm": true }] }
    ]
}

• $schema (texto): Onde um editor encontra o schema deste arquivo: ./action.schema.json, que o vovo dev grava ao lado dele. A Vovó não lê nada aqui.
• name (texto; obrigatório): O nome dela, único no perfil: uma ação trazida com o nome de uma que já existe se oferece para tomar o lugar dela, ou entra como "Raffle 2".
• id (texto, uma linha, no máximo 64 caracteres): Um nome que quem a fez dá a ela uma vez e nunca muda: o nome de quem fez e o da ação com um ponto entre os dois, como example.raffle, em letras minúsculas, números e -. Uma versão mais nova trazida encontra por ele a ação que atualiza, seja qual for o nome que essa ação tenha então; sem ele, pelo nome. Uma cópia feita na Vovó não fica com ele.
• version (texto, uma linha, no máximo 32 caracteres): A versão dela, mostrada na lista de ações e, quando um pacote toma o lugar de uma ação, ao lado da que essa ação tinha, avisando quando o pacote é a mesma versão ou uma mais antiga. Números separados por pontos são lidos como números (1.10.0 é mais nova que 1.9.2, e 1.0.0-beta.1 vem antes de 1.0.0); escritas de qualquer outro jeito, duas versões só são iguais ou não. 1.0.0 sem ela.
• api (número inteiro, 1 ou mais; obrigatório): A versão da API para a qual ela foi escrita: 1. Uma mais nova que a desta Vovó é recusada, com o que fazer.
• triggers (lista de eventos): Os eventos que ela ouve: os da API, ou nomes próprios dela, que vovo.emit e vovo emit disparam. Um nome parecido com um da API é recusado, com o que se quis dizer. control, settings e panel chegam a uma ação que declara controles, configurações ou um painel sem estarem na lista.
• bindings (lista): As condições dos gatilhos.
• permissions (lista de permissões): O que ela pode pedir à Vovó, mostrado a quem a traz. Uma que a Vovó não conhece é recusada, com a que se quis dizer.
• persistent (verdadeiro ou falso): Se ela fica na tela (um chat, uma barra de meta) em vez de aparecer quando os eventos dela chegam, que é como o editor e a lista de ações a chamam. Não muda nada em como ela roda.
• operator (verdadeiro ou falso): Só para quem opera a live: ela ouve o pad, os atalhos, os timers, os controles dela e o que o OBS e o computador dizem, nunca espectadores, chat, recompensas, webhooks ou o evento de outra ação. Um gatilho que outra pessoa poderia disparar é recusado.
• controls (lista, no máximo 32): O que o pad muda enquanto ela roda.
• settings (lista, no máximo 32): O que quem a usa pode mudar sem o código dela.
• panel (lista): O que ela mostra a quem opera a live, em Painéis.
• author (texto, uma linha, no máximo 80 caracteres): Quem a fez.
• site (endereço web, no máximo 200 caracteres): Onde ler mais sobre ela, ou sobre quem a fez.
• description (texto, uma linha, no máximo 300 caracteres): O que ela faz, numa linha, mostrado quando ela é trazida.
• license (texto, uma linha, no máximo 100 caracteres): Em que termos ela é entregue, como quem a fez diz: o nome de uma licença (MIT, CC-BY-4.0) ou uma linha própria, mostrada quando ela é trazida e na lista de ações. O texto inteiro da licença vai ao lado deste arquivo como LICENSE (ou LICENSE.md, LICENSE.txt), com no máximo 64 KB de texto, e é lido no diálogo de importar antes de a ação entrar. A Vovó diz o que está escrito e não obriga ninguém a nada: não confere chave, conta nem compra.

Condições

Cada gatilho de novo, com as condições que precisam valer todas para ele disparar a ação, como o editor as salva. Um para cada nome em triggers, em qualquer ordem: quando não batem um a um, todas as condições ficam de fora sem uma palavra e cada gatilho dispara com tudo.

• event (evento; obrigatório): Um dos nomes em triggers.
• filter (lista): As condições dele; sem nenhuma, todo evento desses a dispara.

Uma condição

Um dos campos do evento comparado com um valor. Textos são comparados sem diferenciar maiúsculas; um número escrito como texto é lido como número.

• field (texto; obrigatório): O campo do evento, como a referência da API o chama: viewers, reward, text. O intervalo de um timer é o campo every (segundos, 5 ou mais), e a combinação de um hotkey o campo keys, cada um com is.
• op (um de is, not, above, atleast, below, atmost, contains, starts; obrigatório): Como são comparados: is e not como estão, above, atleast, below e atmost como números, contains e starts como textos.
• value (texto, número, ou verdadeiro ou falso; obrigatório): Com o que o campo é comparado.

Controles

O que o pad muda enquanto a ação roda: cada um guardado em vovo.state sob sua chave e contado à ação como o evento control, que ela ouve sem tê-lo na lista.

• key (chave; obrigatório): Onde o vovo.state o guarda; dois controles não usam a mesma.
• label (texto; obrigatório): Como o pad o chama.
• kind (um de toggle, choice, counter, text; obrigatório): Liga ou desliga; uma das opções dele; um número inteiro, um a mais ou a menos de cada vez; ou uma linha de texto, com no máximo 300 caracteres.
• options (lista de textos): As opções de uma escolha, duas ou mais.
• max (número): A meta de um contador, mostrada ao lado da contagem.

Configurações

O que quem usa a ação pode mudar sem o código dela, em Personalizar: lido como vovo.settings.<key>, como --vovo-<key> no CSS dela e, para liga ou desliga e uma escolha, como data-vovo-<key> no documento dela. O que é escolhido fica com a ação, e um pacote leva só os padrões. No máximo oito delas são textos.

• kind (um de color, number, toggle, choice, text, file, font, camera; obrigatório): O que ela é, como dizem as partes abaixo.
• key (chave; obrigatório): Como a ação a lê; duas configurações não usam a mesma, e nenhuma é accent.
• label (texto, no máximo 60 caracteres; obrigatório): Como Personalizar a chama.

Configurações: color

Uma cor; o vinho da Vovó, #840926, se a ação não disser outra.

• default (cor, #RRGGBB): Como a ação vem; sem ele, o do tipo.

Configurações: number

Um número de um mínimo a um máximo, em passos; o mínimo se a ação não disser outro.

• min (número; obrigatório): O mínimo.
• max (número; obrigatório): O máximo, acima do mínimo.
• step (número): O tamanho de cada passo, acima de 0; 1 sem ele.
• unit (um de px, %, s, ms, em, deg): A unidade que a variável CSS dela leva; sem ela, um número simples.
• default (número): Como a ação vem; sem ele, o do tipo.

Configurações: toggle

Liga ou desliga; desligado se a ação não disser outra coisa.

• default (verdadeiro ou falso): Como a ação vem; sem ele, o do tipo.

Configurações: choice

Uma das opções dela; a primeira se a ação não disser outra.

• options (lista de textos, de 2 a 12; obrigatório): As opções, cada uma uma vez.
• default (texto): Como a ação vem; sem ele, o do tipo.

Configurações: text

Uma linha de texto; vazia se a ação não disser outra.

• default (texto, uma linha, no máximo 200 caracteres): Como a ação vem; sem ele, o do tipo.

Configurações: file

Uma imagem, um som ou um vídeo que quem a usa escolhe, com no máximo 50 MB; como a ação vem, um dos arquivos dela, pelo caminho, ou nenhum.

• accept (um de image, sound, video): O que pode ser: uma imagem se a ação não disser outra coisa.
• default (caminho de um arquivo, ou null): Como a ação vem; sem ele, o do tipo.

Configurações: font

Uma das fontes do computador, pela família; Segoe UI se a ação não disser outra.

• default (texto, uma linha, no máximo 64 caracteres): Como a ação vem; sem ele, o do tipo.

Configurações: camera

Uma das câmeras do computador, que quem usa a ação escolhe em Personalizar, mostrada onde a ação a posiciona (vovo.camera.place, com a permissão camera.show); no máximo quatro. Vem sem nenhuma, então não tem padrão.

Painel

O que a ação mostra a quem opera a live em Painéis, na barra lateral: peças em ordem, cada uma dita pelo seu kind, desenhadas pela Vovó. O que é feito ali chega à ação como o evento panel, que ela ouve sem tê-lo na lista. Uma peça panel começa outro painel, com as peças depois dela até a próxima, e as peças antes da primeira aparecem em todos; um tab divide um painel em seções do mesmo jeito. Os nomes de botões, formulários e botões de uma lista são únicos na ação. Uma ação declara no máximo 24 painéis, cada um com no máximo 40 peças e 12 abas.

• kind (um de panel, tab, heading, note, control, button, form, list; obrigatório): O que ela é, como dizem as partes abaixo.

Painel: panel

Outro painel começa aqui, com uma entrada própria em Painéis.

• label (texto, no máximo 30 caracteres; obrigatório): O nome dele em Painéis.
• icon (texto, no máximo 32 caracteres): Um dos ícones da Vovó pelo nome, ou um emoji; sem ele, o ícone do primeiro botão da ação no pad.

Painel: tab

Uma seção do painel: as peças depois dela, até a próxima aba.

• label (texto, no máximo 30 caracteres; obrigatório): O nome dela.

Painel: heading

Um título sobre as peças depois dele, que dividem um cartão.

• label (texto, no máximo 60 caracteres; obrigatório): O texto dele.

Painel: note

Uma linha dizendo algo.

• label (texto, no máximo 60 caracteres; obrigatório): O texto dele.

Painel: control

Um dos controles da ação, mexido aqui como no pad.

• key (chave; obrigatório): A chave do controle.

Painel: button

Um botão.

• name (nome; obrigatório): O que o evento panel diz que foi apertado.
• label (texto, no máximo 60 caracteres; obrigatório): O texto dele.
• confirm (verdadeiro ou falso): O primeiro aperto pergunta, e o segundo faz.

Painel: form

Alguns campos e um botão: o que é digitado vai com o aperto, nos values do evento. Um formulário de um campo é digitado no próprio painel.

• name (nome; obrigatório): O que o evento panel diz que foi enviado.
• label (texto, no máximo 60 caracteres; obrigatório): O texto dele.
• button (texto): O texto do botão.
• fields (lista, de 1 a 4; obrigatório): Os campos dele.

Campos de um formulário

Cada um uma linha digitada no painel, enviada com o formulário pela sua chave.

• key (nome; obrigatório): A chave dele nos values do evento, uma vez no formulário.
• label (texto, no máximo 60 caracteres; obrigatório): Como o campo se chama.

Painel: list

Uma lista lida do estado da ação, uma linha para cada item, que podem ser milhares; uma com mais de oito linhas tem busca própria.

• key (texto; obrigatório): A chave do vovo.state que a guarda.
• path (texto): Dentro dela, as chaves até a lista, unidas por pontos: round.names.
• label (texto, no máximo 60 caracteres; obrigatório): O nome dela.
• show (texto): Para itens que são objetos: o campo que uma linha mostra, ou uma linha com {field}s preenchidos com cada item.
• empty (texto): O que ela diz enquanto está vazia.
• buttons (lista, no máximo 3): Botões em cada linha: um aperto conta à ação o item e o index da linha.

Botões de uma lista

Botões em cada linha da lista.

• name (nome; obrigatório): O que o evento panel diz que foi apertado.
• label (texto, no máximo 60 caracteres; obrigatório): O texto dele.
• confirm (verdadeiro ou falso): O primeiro aperto pergunta, e o segundo faz.

pad.json

Um pacote de botões do pad: um zip ou uma pasta de sons e vídeos, com um pad.json na raiz dizendo os grupos e os botões deles; sem ele, cada pasta é um grupo e cada som ou vídeo um botão com o nome do arquivo. Trazido de novo, ele atualiza o que nomeia e deixa o resto como está.

{
    "$schema": "./pad.schema.json",
    "groups": [
        {
            "name": "Sounds",
            "color": "#2F6FDB",
            "buttons": [
                { "label": "Applause", "icon": "👏", "sound": "sounds/applause.mp3", "favorite": true, "hotkey": "F13" },
                { "label": "Drum roll", "sound": "sounds/drums.ogg", "volume": 130 },
                { "label": "Rain", "video": "videos/rain.mp4", "key": "luma", "loop": true }
            ]
        },
        {
            "name": "Live",
            "buttons": [
                { "label": "Raffle", "action": "Raffle" },
                { "label": "Entries", "action": "Raffle", "control": "open" },
                { "label": "Starting", "scene": "Starting soon" },
                { "label": "Camera", "scene": "Game", "source": "Camera" },
                { "label": "Blur", "source": "Camera", "filter": "Blur" },
                { "label": "One minute", "team": "One minute, then I'm back." }
            ]
        }
    ]
}

• $schema (texto): Onde um editor encontra o schema deste arquivo, como um ./pad.schema.json ao lado dele. A Vovó não lê nada aqui.
• groups (lista; obrigatório): Os grupos, em ordem.

Grupos

Um grupo do pad e os botões dele, em ordem.

• name (texto, no máximo 60 caracteres; obrigatório): O nome dele: um grupo do perfil com esse nome, sem diferenciar maiúsculas, é atualizado.
• color (cor, #RRGGBB): A cor dele; sem ela, um grupo que já existe mantém a sua e um novo pega a próxima.
• buttons (lista): Os botões dele.

Botões

Um botão e o que ele faz: a Vovó lê o primeiro destes que encontrar, nesta ordem: sound; video; action com control; action; source com filter, ou scene com source; scene. Um pacote traz no máximo 2.000 botões.

• label (texto, no máximo 60 caracteres; obrigatório): O nome dele no pad: um botão do grupo dele com esse nome, sem diferenciar maiúsculas, é atualizado.
• icon (texto): Um dos ícones da Vovó pelo nome, ou um emoji.
• sound (caminho de um arquivo): Um som do pacote, pelo caminho dentro dele: MP3, OGG, WAV, M4A, WEBM ou FLAC, com no máximo 20 MB.
• video (caminho de um arquivo): Um vídeo do pacote, pelo caminho dentro dele: MP4 ou M4V, com no máximo 200 MB; ele toca sobre o palco inteiro.
• key (texto): O que do vídeo é tirado, como fazem os filtros do OBS: none, luma (preto), chroma (verde) ou chroma:#RRGGBB.
• loop (verdadeiro ou falso): O vídeo toca sem parar, até o botão dele ser apertado de novo.
• action (texto): Uma das ações do perfil, pelo nome, disparada como o evento button dela.
• control (chave): Com action: um dos controles dela, pela chave, mexido como o botão dele no pad o mexe.
• value (texto): Com control, para uma escolha: a opção que ele escolhe; sem ele, vai passando por elas.
• scene (texto): Uma cena do OBS, pelo nome, colocada no ar.
• source (texto): Com scene: uma fonte nela, mostrada ou escondida. Com filter: a fonte em que o filtro está.
• filter (texto): Com source: um dos filtros dela, ligado ou desligado.
• team (texto, no máximo 300 caracteres): Uma linha que ele escreve na conversa da equipe como quem faz a live, nunca na live nem no chat; o pad de um dispositivo nunca tem o botão.
• favorite (verdadeiro ou falso): Em Favoritos ou não; sem isso, um botão que já existe mantém o que tem.
• hotkey (texto): A combinação que o aperta de qualquer programa, como as pessoas escrevem: F13, Ctrl+Shift+1. Dois botões do perfil não usam a mesma.
• volume (número inteiro, de 0 a 150): O volume com que um som ou um vídeo toca, em porcentagem do arquivo; sem ele, um botão que já existe mantém o seu.