Ações

Uma ação é um pedaço de HTML, CSS e JavaScript que aparece no overlay. Cada uma roda isolada, sem rede e sem acesso a senhas: o que ela precisa de fora, pede à Vovó.

Começar

"Nova ação" cria uma em branco ou a partir de um exemplo: alertas e chat, tocando agora, contagem regressiva, meta, sorteio, contador de mortes e outros. O exemplo vira uma cópia sua, para mudar à vontade.

Em três degraus

Só HTML: um <template> que aparece quando o evento acontece, com os campos do evento entre chaves.

<template data-on="follow" data-seconds="5">
    <div class="alerta">{user} seguiu o canal!</div>
</template>

Um pouco de JavaScript: vovo.on("raid", (e) => { ... }) e vovo.show("nome", e). E a API inteira para o resto.

• Referência da API
• Como uma ação roda

Gatilhos

A ação só recebe os eventos que estão na lista de gatilhos dela, no editor. Um botão do pad é o gatilho button.

Condições

O ícone de ajustes ao lado de um gatilho abre as condições dele: o gatilho só dispara quando todas batem. Uma raid com 50 pessoas ou mais, uma mensagem que começa com !entrar, a recompensa certa.

Timer e atalho

O gatilho Timer dispara de tempos em tempos: a condição every diz de quantos em quantos segundos (sem ela, a cada minuto). O gatilho Atalho dispara com uma combinação de teclas, a condição keys, mesmo com o jogo na frente.

Controles

No cartão Controles do editor, a ação declara o que o pad pode mudar enquanto ela roda: liga e desliga, uma escolha entre opções, um contador (com uma meta, se quiser) ou um texto. Cada um fica em vovo.state, na chave mostrada no diálogo, e cada mudança chega como o evento control, sem precisar de gatilho. Os exemplos Alertas e chat, Meta de seguidores e Contador de mortes mostram como.

vovo.on("control", () =>
{
    document.getElementById("chat").hidden = !vovo.state.chat;
});

Personalizar

Uma ação pode deixar quem a usa mudá-la sem abrir o código: a cor, o tamanho do texto, a fonte, um lado da tela, uma imagem ou um som seu. A paleta ao lado do nome do painel dela, ou na linha dela na lista de ações, abre Personalizar: uma linha para cada configuração, com o que ela tem, o padrão quando difere, e o jeito de voltar a ele. Uma mudança aparece na hora nas cenas que mostram a ação, sem reiniciá-la, e cada uma vira uma versão que a Auditoria desfaz. Ela é escolhida só neste computador: um celular ou outra Vovó nunca a veem. O pacote da ação leva os padrões, nunca as suas escolhas; um que tome o lugar da ação mantém as escolhas que ainda cabem nele.

Quem escreve a ação as declara no cartão Personalizar do editor, ou em settings no action.json: cada uma com um tipo (uma cor, um número de um mínimo a um máximo, liga ou desliga, uma escolha, um texto, uma imagem, um som ou um vídeo, uma fonte), um nome, uma chave e um padrão. A ação as lê em vovo.settings, e ouve o evento settings quando uma muda; o CSS dela as lê como var(--vovo-chave) (um número com a unidade, como 32px), e um liga ou desliga ou uma escolha como um atributo da página, para seletores:

.chat
{
    color: var(--vovo-cor);
    font-size: var(--vovo-tamanho);
    font-family: var(--vovo-fonte), sans-serif;
}
html[data-vovo-lado="Direita"] .chat
{
    right: 40px;
}

Uma configuração também pode ser uma câmera: quem usa a ação escolhe uma das câmeras do próprio computador em Personalizar, e a ação a mostra onde a posiciona (vovo.camera.place, com a permissão camera.show). Uma ação vem sem câmera e nunca fica sabendo qual foi escolhida, nem vê as imagens dela: vovo.settings diz só se alguma foi escolhida, como true ou false. O exemplo "Câmera" é uma câmera numa moldura.

Painéis

O que um botão não comporta (os nomes de um sorteio, as metas com os números, um aperto que deve perguntar duas vezes) vai no painel da ação: panel no manifesto dela, mostrado em Painéis, na barra lateral (o ícone dele na borda direita da janela, presente enquanto alguma ação tem painel). Um painel é uma lista de peças que a Vovó desenha: heading e note, um control pela chave, um button (com confirm, ele pergunta "Certeza?" antes), um form com até quatro campos, e uma list lida do vovo.state (a key dela, e um path dentro dela), cada linha com até três botões.

Uma ação com muito a oferecer divide isso de dois jeitos. { "kind": "panel", "label": "Sorteio", "icon": "gift" } começa outro painel: uma entrada própria em Painéis, com o nome e o ícone dele (um ícone da Vovó pelo nome, ou um emoji; sem ícone, o do primeiro botão da ação no pad). As peças depois dele, até o próximo, são dele, e as que vêm antes do primeiro aparecem no topo de todos. Dentro de um painel, tab começa uma seção (até doze): as peças depois dela, até a próxima aba, aparecem enquanto ela está escolhida, e as que vêm antes da primeira aba aparecem em todas. Assim um sorteio é um painel com uma seção para o sorteio, outra para quem está dentro e outra para quem ganhou, em vez de uma página comprida. Uma ação que não declara nenhum { "kind": "panel" } tem um só, com o nome dela.

O topo de Painéis diz qual está na frente; um clique ali lista todos, cada um dizendo se alguma cena aberta o mostra e de quem ele é, com uma busca quando há mais de oito. As seções aparecem como abas sob o topo: as que cabem, e o resto em "Mais". Um título abre um grupo: as peças depois dele ficam num cartão, botões seguidos dividem uma linha, uma lista é um cartão só dela com a contagem, e uma nota fica entre os cartões. Um formulário de um campo é digitado no próprio painel, e Enter envia; um controle de texto também; um formulário com mais campos abre uma janelinha. Um contador com meta (max) mostra quanto falta.

Uma lista pode ter milhares de linhas. Com mais de oito, ela tem uma busca própria, que continua à vista enquanto a lista rola. Quando é a última peça da seção, aparece inteira; com peças depois dela, mostra as oito primeiras linhas e o caminho para todas: por isso ponha uma lista longa por último, ou numa seção só dela.

O que se faz ali chega como o evento panel, sem precisar de gatilho: o name, os values de um formulário, e o item e o index de uma linha. Os nomes são da ação, seja qual for o painel que os mostra. Uma ação só ouve o painel enquanto alguma cena aberta a mostra, no OBS ou na janela de prévia: sem nenhuma, o painel avisa, os botões esperam apagados e "Abrir a prévia" abre a da cena; os controles e as listas continuam aparecendo, porque a Vovó os guarda. Só quem opera a live usa, aqui ou num dispositivo a que você liberou os painéis, e nada chega à ação durante o pânico.

Escrever no chat

Com a permissão chat.send, vovo.chat.send("...") escreve no chat da live como você. A Vovó segura o ritmo (20 linhas em 30 segundos) e escreve uma vez só o que duas páginas mostrando a ação pedem; dois apertos de um botão são duas linhas. O exemplo Lembrete no chat mostra como. Com { as: "persona" }, a linha vai pela conta própria da persona na Twitch (Integrações, na Twitch): o que a persona diz que não é uma resposta dela, como uma linha que alguém digita para ela dizer. Enquanto essa conta não está conectada, nada é escrito, e nada como você no lugar.

A Vovó distingue a chamada de uma página da de outra pelo evento que a ação tratava quando chamou. Uma chamada feita depois, após um await ou num timer, diz a qual evento responde com { event: e }, sendo e o que o seu ouvinte recebeu: vovo.chat.send("Bem-vindo!", { event: e }). O mesmo vale para vovo.emit, vovo.pad.play, vovo.webhook.send, vovo.draw, vovo.media.play e as chamadas do OBS. Sem isso, duas páginas escreveriam a linha duas vezes, e o link de um moderador esperaria no sino.

O microfone, a tela e como você se move

Uma ação pode acompanhar o volume do seu microfone (audio.level), a cor da tela (screen.color) e como você se move num jogo (input.move): o quanto a câmera girou, para onde você anda e se pula, pelo mouse, por W, A, S e D ou pelas setas, e por um controle, para uma cena balançar com a câmera. Os exemplos "Brilho da tela" e "Balanço da câmera" mostram como. A Vovó lê cada um só enquanto um overlay aberto mostra uma ação que espera por ele, e a barra de status mostra o ícone dele no meio dela enquanto isso dura, com as ações na dica. Do teclado ela lê só as teclas de movimento, como uma direção, nunca qual tecla, e não enquanto a janela da própria Vovó está na frente, onde o que você digita balançaria a cena; o mouse e um controle ainda a movem nessa hora, a não ser que "Pausar o movimento com a Vovó na frente" esteja ligado (Configurações, Geral). O som nunca sai do computador, só o volume.

Clipes e vídeos

Com a permissão media.play, vovo.media.play(link) mostra um clipe da Twitch, um vídeo da Twitch ou um vídeo do YouTube no player oficial, onde vovo.media.place(elemento) o pôs, com o som. Uma ação que só quem opera dispara toca na hora; qualquer outra, que alguém no chat pode ter disparado, espera no sininho até você (ou um dispositivo com permissão de aprovar) liberar. O player não sabe quando um clipe acaba: passe { seconds: 60 }, ou chame vovo.media.stop(). O exemplo Clipes na TV aceita !clip e um link vindo dos moderadores.

Os seus moderadores são as pessoas a quem você confia o chat: em Integrações, na Twitch, "Links de moderadores tocam na hora" deixa um link que um deles (ou você) cola ir ao ar sem esperar, quando a ação o mostra por causa da mensagem dele. Desligado até você ligar; o link de todos os outros continua esperando.

Chamadas de voz

Com a permissão call, uma ação pode pôr você ao telefone com um modelo de IA, no ar: você fala ao microfone, ele responde em voz alta, e a live ouve os dois. vovo.call.start({ instructions, voice }) abre a chamada com a sua chave da OpenAI (Integrações, IA); instructions é quem o modelo é e como fala. A chamada abre em silêncio, para a ação poder tocar um telefone antes; vovo.call.answer() abre o microfone e faz o modelo falar primeiro, vovo.call.tell() diz algo a ele durante a chamada, e vovo.call.end() desliga. call.started, call.answered, call.text (o que é dito, por escrito) e call.ended contam o que acontece.

O que o modelo diz é ouvido na hora, sem ninguém ler antes, então uma chamada só começa por algo que você fez com a mão: um botão do pad, um atalho, um controle ou o painel da ação. Chat, resgates e webhooks não começam nenhuma. A OpenAI cobra por segundo desde a abertura, então cada chamada tem um teto (cinco minutos no máximo). Enquanto uma está no ar, um telefone vermelho aparece na barra de baixo: aperte-o, ou o pânico, para desligar na hora. Use fone de ouvido, ou o modelo se ouve pelas suas caixas de som.

Webhooks

Com a permissão webhook, vovo.webhook.send("nome", { ... }) pede à Vovó que envie o JSON a um webhook cadastrado em Configurações, Webhooks: o de um canal do Discord, uma automação, uma ferramenta na sua rede. O endereço fica no cofre deste computador, fora de backups e pacotes, e a ação só conhece o nome. O exemplo Avisar no Discord mostra como.

Webhooks de entrada

No outro sentido, um serviço na internet avisa a Vovó: em Configurações, Webhooks, crie um webhook de entrada, copie o endereço dele e cole no serviço (uma página de doações, uma loja, um script). Cada chamada chega às ações como o evento webhook, com hook (o nome) e data (o que foi enviado). Use o gatilho webhook com a condição de hook ser o nome. Cada webhook tem um endereço só dele: dê esse endereço apenas ao serviço que chama. O relay guarda a chamada lacrada para este computador por um dia no máximo, então uma feita com a Vovó fechada chega quando ela abre. O que chega é texto de outra pessoa: as ações mostram só como texto.

De um programa deste computador

Um programa deste computador pode contar a uma ação o que ele sabe: um script que lê o log de um jogo, uma ferramenta que guarda o placar de um campeonato, uma macro. A ação ouve um evento com nome próprio, entre os gatilhos do action.json dela (como numa pasta que o vovo dev acompanha):

"triggers": ["placar"]

e o recebe como qualquer outro:

vovo.on("placar", (e) =>
{
    document.getElementById("casa").textContent = e.casa;
    document.getElementById("fora").textContent = e.fora;
});

O programa conta com vovo emit, o nome e os campos:

vovo emit placar casa=2 fora=1

Um número, true e false chegam como são, o resto como texto. Listas e objetos vão inteiros em JSON, que é como um programa chama:

import json, subprocess
subprocess.run(["vovo", "emit", "placar", "--fields", json.dumps({"casa": 2, "fora": 1})])

Ele diz quais ações ouviram, e falha (código de saída 1, com o motivo) quando nenhuma ouviria: nenhuma ação tem esse nome entre os gatilhos, as condições delas não valem, ou nenhuma página aberta as mostra. Vai aonde o vovo.emit de uma ação iria, nunca durante o pânico, no máximo 30 em 10 segundos, e a auditoria diz que foi a linha de comando. Uma ação só para quem opera não o ouve. O que um programa manda é texto desse programa: a ação mostra só como texto. Para fingir que um evento da API aconteceu, como um follow, use vovo simulate.

Prévia e Simular

O editor mostra a ação ao vivo enquanto você digita, e os botões de Simular disparam os gatilhos sem esperar acontecer de verdade e mexem nos controles como o botão do pad mexeria. Nada da prévia vai para a live. O ícone no canto do código ou da prévia dá a ele a janela toda; o mesmo ícone, ou Esc, o devolve ao lado do outro.

Leitores de tela

O editor de código não é lido por leitores de tela. O botão Texto simples, acima do código, troca por uma caixa de texto que o Narrador, o NVDA e o JAWS leem inteira, por linha, palavra e caractere. Ele já começa ligado quando o Windows avisa que há um leitor de tela; Tab segue adiante, então indente com espaços.

Arquivos

Na aba Arquivos do editor, adicione imagens, sons, vídeos e fontes. A ação os usa pelo nome: <img src="logo.png">. Para passar um som ou vídeo dela pelo Web Audio (um compressor, um medidor), peça com crossOrigin = "anonymous" antes de dar o nome: uma ação roda isolada de tudo, e para ela até os próprios arquivos vêm de fora, o que o Web Audio, sem isso, ouve como silêncio.

Permissões

O que a ação pode pedir à Vovó fica em Comportamento: escrever no chat, chamar um webhook, mostrar a tela compartilhada, mostrar uma câmera, mostrar fontes e ligar filtros no OBS. Desligada, a ação não consegue.

O OBS a partir de uma ação

Com a permissão obs.toggle, vovo.obs.source("Cena", "Fonte", true) mostra uma fonte numa cena do OBS (false esconde; sem ele, inverte), e vovo.obs.filter("Fonte", "Filtro", true) faz o mesmo com um filtro. Os nomes são os do OBS, sem diferenciar maiúsculas nem acentos; um que o OBS não tem é dito no Console, com o que você quis dizer. É tudo o que uma ação alcança no OBS: ela não para a transmissão nem lê a chave.

Só para quem opera

Em Comportamento, "Só para quem opera a live" faz a ação ser disparada só pelo pad, atalhos, timers e os controles dela: nunca por espectadores, chat, recompensas, webhooks ou o evento de outra ação. Use para o que ninguém assistindo deveria conseguir fazer, como limpar o chat ou trocar de cena.

Versões

Cada vez que você salva, fica uma versão. "Histórico" traz qualquer uma de volta.

Pacotes

O ícone de exportar, na lista de ações, grava a ação num .zip com o código e os arquivos dela, para passar a outra pessoa. Em Comportamento, o autor, o site e uma linha sobre o que ela faz vão junto, para quem a trouxer saber o que ela é e de onde veio. "Importar ação" mostra o que o pacote traz e o que ele pede antes de guardar, e abre a ação no editor: leia antes de usar. Um pacote com o nome de uma ação que você já tem é, quase sempre, essa ação numa versão mais nova, então ele se oferece para tomar o lugar dela: a ação continua com cenas, botões e estado, e a versão que ela tinha fica no histórico. No terminal, vovo export e vovo import fazem o mesmo, e vovo import --replace toma o lugar da ação de mesmo nome. Um pacote feito para outras pessoas pode dizer um id em Comportamento, o nome de quem fez e o da ação com um ponto entre os dois (example.raffle). A próxima versão dele então encontra a ação que atualiza mesmo depois de você renomeá-la, e duas ações de mesmo nome, de autores diferentes, nunca tomam o lugar uma da outra; vovo import --replace também se guia por ele. Com id ou sem, a importação diz qual versão toma o lugar de qual, e avisa quando o arquivo é a mesma versão ou uma mais antiga, e o que você escolheu em Personalizar continua onde a versão nova ainda tiver aquela configuração. Um pacote pode dizer sob qual licença ele é entregue: o nome de uma licença ou uma linha sua em Comportamento, e o texto inteiro da licença, escolhido ali de um arquivo ou guardado como LICENSE ao lado de action.json numa pasta. Quem traz a ação vê a linha, e lê o texto no diálogo de importar antes de ela entrar. A Vovó diz o que você escreveu e não obriga ninguém a nada: não confere chave, conta nem compra, e vender uma ação acontece fora da Vovó. O ícone de copiar, ao lado, duplica a ação e abre a cópia no editor, para começar uma variação a partir de uma que funciona: o código, os arquivos e os gatilhos vêm junto; o estado, as cenas e os botões não, e um gatilho de atalho vem sem a combinação, para uma tecla não disparar as duas.

No seu próprio editor

Uma ação pode ser escrita no editor que você preferir, ou por um build seu: guarde as partes dela numa pasta como um pacote as guarda (action.json, index.html, style.css, script.js e files/) e, num terminal, rode vovo dev com a pasta. A Vovó abre o editor dela na ação com esse nome, criando-a a partir da pasta quando o perfil não tem uma, e mostra na prévia, na hora, cada mudança gravada na pasta; o Simular funciona como sempre. Como uma mudança digitada aqui, ela só chega à live quando você Salva. vovo dev stop, ou Parar de acompanhar no topo do editor, solta a pasta.

O vovo new <pasta> começa essa pasta para você, em branco ou a partir de um dos exemplos (vovo new --list diz quais, e --from goal usa um), e o vovo check <pasta> diz de uma vez tudo o que está errado numa pasta ou num pacote, sem criar nem abrir nada: cada problema com o arquivo dele, e o que a Vovó aceitaria e deixaria passar, como uma chave que ela não usa. Os dois respondem também com a Vovó fechada. O vovo export <ação> <pasta> grava como uma pasta dessas uma ação que você já tem.

O vovo dev também grava na pasta o vovo.d.ts, a API como esta Vovó a tem, e um jsconfig.json quando não houver um, para um editor como o VS Code completar vovo., os nomes dos eventos em vovo.on(" e os campos de cada evento. Nenhum dos dois faz parte da ação, e um pacote nunca os leva; num controle de versão, guarde ou ignore, como preferir. Para ver um campo errado sublinhado, acrescente "checkJs": true em compilerOptions no jsconfig.

Ele grava ali também o action.schema.json, que também não é parte da ação: com "$schema": "./action.schema.json" no começo do action.json, o editor completa as chaves, oferece os eventos e as permissões pelo nome e sublinha o que a Vovó recusaria.

A prévia abre também no seu navegador, no endereço que o vovo dev mostra ou pela seta no canto da prévia: o mesmo rascunho, rodado pelo mesmo vovo do ar, recarregado a cada mudança, com o Simular chegando nele, e com as ferramentas de desenvolvedor do próprio navegador (o console, os breakpoints, os elementos).

• action.json e pad.json

Para aparecer na live

A ação precisa estar numa cena, e a cena no OBS.

• Cenas e o OBS