action.json e pad.json

Ogni chiave dei due file che Vovó legge da una cartella o da uno zip, generata dal codice stesso di Vovó, quindi sempre allineata a questa versione. Vovó controlla ogni file quando arriva e lo rifiuta con una frase che dice cosa non va; una chiave che non conosce viene ignorata senza dire nulla, e un editor che legge lo schema la sottolinea.

Una chiave è fatta di lettere minuscole, cifre e _, e un nome può avere anche -, ciascuno di 32 caratteri al massimo.

Perché un editor completi le chiavi e sottolinei gli errori, indica lo schema all'inizio del file, come fanno gli esempi. vovo dev scrive action.schema.json accanto alle parti di un'azione; il codice sorgente di Vovó li ha entrambi nella cartella api.

action.json

Il manifesto di un'azione: come si chiama, cosa ascolta, cosa chiede e cosa offre a chi gestisce la diretta. Sta accanto a index.html, style.css, script.js e files/, in un pacchetto o in una cartella.

{
    "$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 (testo): Dove un editor trova lo schema di questo file: ./action.schema.json, che vovo dev scrive accanto. Vovó non vi legge nulla.
• name (testo; obbligatorio): Il suo nome, unico nel profilo: un'azione importata con il nome di una già presente propone di prenderne il posto, o entra come "Raffle 2".
• id (testo, una riga, al massimo 64 caratteri): Un nome che chi l'ha fatta le dà una volta e non cambia mai: il nome di chi l'ha fatta e quello dell'azione con un punto in mezzo, come example.raffle, in lettere minuscole, cifre e -. Una versione più recente importata trova con esso l'azione che aggiorna, comunque si chiami ormai; senza, la trova dal nome. Una copia fatta in Vovó non lo conserva.
• version (testo, una riga, al massimo 32 caratteri): La sua versione, mostrata nell'elenco delle azioni e, quando un pacchetto prende il posto di un'azione, accanto a quella che l'azione aveva, segnalando quando il pacchetto è la stessa versione o una più vecchia. I numeri separati da punti si leggono come numeri (1.10.0 è più recente di 1.9.2, e 1.0.0-beta.1 viene prima di 1.0.0); scritte in qualsiasi altro modo, due versioni sono solo uguali o no. 1.0.0 se manca.
• api (numero intero, 1 o più; obbligatorio): La versione dell'API per cui è stata scritta: 1. Una più recente di quella di questa Vovó viene rifiutata, con cosa fare.
• triggers (elenco di eventi): Gli eventi che ascolta: quelli dell'API, o nomi suoi, che vovo.emit e vovo emit fanno scattare. Un nome simile a uno dell'API viene rifiutato, con quello inteso. control, settings e panel arrivano a un'azione che dichiara controlli, impostazioni o un pannello senza essere elencati.
• bindings (elenco): Le condizioni degli attivatori.
• permissions (elenco di permessi): Ciò che può chiedere a Vovó, mostrato a chi la importa. Uno che Vovó non conosce viene rifiutato, con quello inteso.
• persistent (vero o falso): Se resta sullo schermo (una chat, una barra obiettivo) invece di apparire quando arrivano i suoi eventi, che è come la chiamano l'editor e l'elenco delle azioni. Non cambia nulla di come funziona.
• operator (vero o falso): Solo per chi gestisce la diretta: ascolta il pad, le scorciatoie, i timer, i suoi controlli e ciò che dicono OBS e il computer, mai gli spettatori, la chat, i premi, i webhook o l'evento di un'altra azione. Un attivatore che qualcun altro potrebbe far scattare viene rifiutato.
• controls (elenco, al massimo 32): Ciò che il pad cambia mentre è in funzione.
• settings (elenco, al massimo 32): Ciò che chi la usa può cambiare senza il suo codice.
• panel (elenco): Ciò che mostra a chi gestisce la diretta, in Pannelli.
• author (testo, una riga, al massimo 80 caratteri): Chi l'ha fatta.
• site (indirizzo web, al massimo 200 caratteri): Dove leggere di più su di lei, o su chi l'ha fatta.
• description (testo, una riga, al massimo 300 caratteri): Cosa fa, in una riga, mostrato quando viene importata.
• license (testo, una riga, al massimo 100 caratteri): A quali condizioni viene consegnata, come dice chi l'ha fatta: il nome di una licenza (MIT, CC-BY-4.0) o una riga propria, mostrata all'importazione e nell'elenco delle azioni. Il testo completo della licenza sta accanto a questo file come LICENSE (o LICENSE.md, LICENSE.txt), al massimo 64 KB di testo, e si legge dalla finestra di importazione prima che l'azione entri. Vovó dice ciò che è scritto e non vincola nessuno: non controlla chiavi, account né acquisti.

Condizioni

Ogni attivatore di nuovo, con le condizioni che devono valere tutte perché faccia scattare l'azione, come le salva l'editor. Uno per ogni nome in triggers, in qualsiasi ordine: se non corrispondono uno a uno, tutte le condizioni vengono tralasciate senza dire nulla e ogni attivatore scatta per qualsiasi cosa.

• event (evento; obbligatorio): Uno dei nomi in triggers.
• filter (elenco): Le sue condizioni; senza nessuna, ogni evento di quel tipo la fa scattare.

Una condizione

Uno dei campi dell'evento confrontato con un valore. I testi si confrontano senza distinguere maiuscole e minuscole; un numero scritto come testo viene letto come numero.

• field (testo; obbligatorio): Il campo dell'evento, come lo chiama il riferimento dell'API: viewers, reward, text. L'intervallo di un timer è il campo every (secondi, 5 o più), e la combinazione di un hotkey il campo keys, ciascuno con is.
• op (uno tra is, not, above, atleast, below, atmost, contains, starts; obbligatorio): Come vengono confrontati: is e not così come sono, above, atleast, below e atmost come numeri, contains e starts come testi.
• value (testo, numero, o vero o falso; obbligatorio): Con cosa si confronta il campo.

Controlli

Ciò che il pad cambia mentre l'azione è in funzione: ognuno tenuto in vovo.state sotto la sua chiave e comunicato all'azione come evento control, che ascolta senza elencarlo.

• key (chiave; obbligatorio): Dove vovo.state lo tiene; due controlli non ne condividono una.
• label (testo; obbligatorio): Come lo chiama il pad.
• kind (uno tra toggle, choice, counter, text; obbligatorio): Attivo o disattivo; una delle sue opzioni; un numero intero, uno in più o in meno alla volta; o una riga di testo, di 300 caratteri al massimo.
• options (elenco di testi): Le opzioni di una scelta, due o più.
• max (numero): L'obiettivo di un contatore, mostrato accanto al conteggio.

Impostazioni

Ciò che chi usa l'azione può cambiare senza il suo codice, in Personalizza: letto come vovo.settings.<key>, come --vovo-<key> nel suo CSS e, per attivo o disattivo e una scelta, come data-vovo-<key> sul suo documento. Ciò che si sceglie resta con l'azione, e un pacchetto porta solo i predefiniti. Al massimo otto sono testi.

• kind (uno tra color, number, toggle, choice, text, file, font, camera; obbligatorio): Che cos'è, come dicono le parti qui sotto.
• key (chiave; obbligatorio): Come l'azione la legge; due impostazioni non ne condividono una, e nessuna è accent.
• label (testo, al massimo 60 caratteri; obbligatorio): Come la chiama Personalizza.

Impostazioni: color

Un colore; il vinaccia di Vovó, #840926, se l'azione non ne indica un altro.

• default (colore, #RRGGBB): Come arriva l'azione; senza, quello del tipo.

Impostazioni: number

Un numero da un minimo a un massimo, a passi; il minimo se l'azione non ne indica un altro.

• min (numero; obbligatorio): Il minimo.
• max (numero; obbligatorio): Il massimo, sopra il minimo.
• step (numero): Di quanto avanza ogni passo, sopra 0; 1 se manca.
• unit (uno tra px, %, s, ms, em, deg): L'unità che porta la sua variabile CSS; senza, un numero semplice.
• default (numero): Come arriva l'azione; senza, quello del tipo.

Impostazioni: toggle

Attivo o disattivo; disattivo se l'azione non dice altro.

• default (vero o falso): Come arriva l'azione; senza, quello del tipo.

Impostazioni: choice

Una delle sue opzioni; la prima se l'azione non ne indica un'altra.

• options (elenco di testi, da 2 a 12; obbligatorio): Le opzioni, ciascuna una volta.
• default (testo): Come arriva l'azione; senza, quello del tipo.

Impostazioni: text

Una riga di testo; vuota se l'azione non ne indica un'altra.

• default (testo, una riga, al massimo 200 caratteri): Come arriva l'azione; senza, quello del tipo.

Impostazioni: file

Un'immagine, un suono o un video scelto da chi la usa, di 50 MB al massimo; come arriva l'azione, uno dei suoi file, per percorso, o nessuno.

• accept (uno tra image, sound, video): Cosa può essere: un'immagine se l'azione non dice altro.
• default (percorso di un file, o null): Come arriva l'azione; senza, quello del tipo.

Impostazioni: font

Uno dei caratteri del computer, per famiglia; Segoe UI se l'azione non ne indica un altro.

• default (testo, una riga, al massimo 64 caratteri): Come arriva l'azione; senza, quello del tipo.

Impostazioni: camera

Una delle videocamere del computer, che sceglie in Personalizza chi usa l'azione, mostrata dove l'azione la colloca (vovo.camera.place, con il permesso camera.show); al massimo quattro. Arriva senza, quindi non ha un valore predefinito.

Pannello

Ciò che l'azione mostra a chi gestisce la diretta in Pannelli, nella barra laterale: pezzi in ordine, ciascuno indicato dal suo kind, disegnati da Vovó. Ciò che vi si fa arriva all'azione come evento panel, che ascolta senza elencarlo. Un pezzo panel inizia un altro pannello, con i pezzi successivi fino al prossimo, e i pezzi prima del primo compaiono in tutti; un tab divide un pannello in sezioni allo stesso modo. I nomi di pulsanti, moduli e pulsanti di un elenco sono unici nell'azione. Un'azione dichiara al massimo 24 pannelli, ciascuno con al massimo 40 pezzi e 12 schede.

• kind (uno tra panel, tab, heading, note, control, button, form, list; obbligatorio): Che cos'è, come dicono le parti qui sotto.

Pannello: panel

Qui inizia un altro pannello, con una voce propria in Pannelli.

• label (testo, al massimo 30 caratteri; obbligatorio): Il suo nome in Pannelli.
• icon (testo, al massimo 32 caratteri): Una delle icone di Vovó per nome, o un emoji; senza, l'icona del primo pulsante dell'azione sul pad.

Pannello: tab

Una sezione del pannello: i pezzi successivi, fino alla prossima scheda.

• label (testo, al massimo 30 caratteri; obbligatorio): Il suo nome.

Pannello: heading

Un titolo sopra i pezzi successivi, che condividono una scheda.

• label (testo, al massimo 60 caratteri; obbligatorio): Il suo testo.

Pannello: note

Una riga che dice qualcosa.

• label (testo, al massimo 60 caratteri; obbligatorio): Il suo testo.

Pannello: control

Uno dei controlli dell'azione, usato qui come sul pad.

• key (chiave; obbligatorio): La chiave del controllo.

Pannello: button

Un pulsante.

• name (nome; obbligatorio): Ciò che l'evento panel dice sia stato premuto.
• label (testo, al massimo 60 caratteri; obbligatorio): Il suo testo.
• confirm (vero o falso): La prima pressione chiede, la seconda esegue.

Pannello: form

Alcuni campi e un pulsante: ciò che si scrive parte con la pressione, nei values dell'evento. Un modulo di un solo campo si compila nel pannello stesso.

• name (nome; obbligatorio): Ciò che l'evento panel dice sia stato inviato.
• label (testo, al massimo 60 caratteri; obbligatorio): Il suo testo.
• button (testo): Il testo del pulsante.
• fields (elenco, da 1 a 4; obbligatorio): I suoi campi.

Campi di un modulo

Ciascuno una riga scritta nel pannello, inviata con il modulo con la sua chiave.

• key (nome; obbligatorio): La sua chiave nei values dell'evento, una sola volta nel modulo.
• label (testo, al massimo 60 caratteri; obbligatorio): Come si chiama il campo.

Pannello: list

Un elenco letto dallo stato dell'azione, una riga per elemento, che possono essere migliaia; uno con più di otto righe ha una ricerca propria.

• key (testo; obbligatorio): La chiave di vovo.state che lo contiene.
• path (testo): Al suo interno, le chiavi fino all'elenco, unite da punti: round.names.
• label (testo, al massimo 60 caratteri; obbligatorio): Il suo nome.
• show (testo): Per gli elementi che sono oggetti: il campo che una riga mostra, o una riga con {field} riempiti da ogni elemento.
• empty (testo): Ciò che dice finché è vuoto.
• buttons (elenco, al massimo 3): Pulsanti su ogni riga: una pressione comunica all'azione item e index della riga.

Pulsanti di un elenco

Pulsanti su ogni riga dell'elenco.

• name (nome; obbligatorio): Ciò che l'evento panel dice sia stato premuto.
• label (testo, al massimo 60 caratteri; obbligatorio): Il suo testo.
• confirm (vero o falso): La prima pressione chiede, la seconda esegue.

pad.json

Un pacchetto di pulsanti per il pad: uno zip o una cartella di suoni e video, con pad.json alla radice che indica i gruppi e i loro pulsanti; senza, ogni cartella è un gruppo e ogni suono o video un pulsante con il nome del suo file. Importato di nuovo, aggiorna ciò che nomina e lascia il resto com'è.

{
    "$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 (testo): Dove un editor trova lo schema di questo file, per esempio un ./pad.schema.json accanto. Vovó non vi legge nulla.
• groups (elenco; obbligatorio): I gruppi, in ordine.

Gruppi

Un gruppo del pad e i suoi pulsanti, in ordine.

• name (testo, al massimo 60 caratteri; obbligatorio): Il suo nome: un gruppo del profilo con questo nome, senza distinguere maiuscole, viene aggiornato.
• color (colore, #RRGGBB): Il suo colore; senza, un gruppo già presente tiene il suo e uno nuovo prende il successivo.
• buttons (elenco): I suoi pulsanti.

Pulsanti

Un pulsante e cosa fa: Vovó legge il primo di questi che trova, in quest'ordine: sound; video; action con control; action; source con filter, o scene con source; scene. Un pacchetto porta al massimo 2.000 pulsanti.

• label (testo, al massimo 60 caratteri; obbligatorio): Il suo nome sul pad: un pulsante del suo gruppo con questo nome, senza distinguere maiuscole, viene aggiornato.
• icon (testo): Una delle icone di Vovó per nome, o un emoji.
• sound (percorso di un file): Un suono del pacchetto, per il suo percorso al suo interno: MP3, OGG, WAV, M4A, WEBM o FLAC, di 20 MB al massimo.
• video (percorso di un file): Un video del pacchetto, per il suo percorso al suo interno: MP4 o M4V, di 200 MB al massimo; va sopra tutto il palco.
• key (testo): Cosa viene tolto dal video, come fanno i filtri di OBS: none, luma (nero), chroma (verde) o chroma:#RRGGBB.
• loop (vero o falso): Il video si ripete di continuo, finché il suo pulsante non viene premuto di nuovo.
• action (testo): Una delle azioni del profilo, per nome, fatta scattare come il suo evento button.
• control (chiave): Con action: uno dei suoi controlli, per chiave, usato come lo usa il suo pulsante sul pad.
• value (testo): Con control, per una scelta: l'opzione che sceglie; senza, le scorre una dopo l'altra.
• scene (testo): Una scena di OBS, per nome, mandata in onda.
• source (testo): Con scene: una fonte al suo interno, mostrata o nascosta. Con filter: la fonte su cui sta il filtro.
• filter (testo): Con source: uno dei suoi filtri, attivato o disattivato.
• team (testo, al massimo 300 caratteri): Una riga che scrive nella conversazione della squadra come chi fa la diretta, mai in diretta né in chat; il pad di un dispositivo non ha mai il pulsante.
• favorite (vero o falso): Nei Preferiti o no; senza, un pulsante già presente tiene ciò che ha.
• hotkey (testo): La combinazione che lo preme da qualsiasi programma, come la si scrive: F13, Ctrl+Shift+1. Due pulsanti del profilo non ne condividono una.
• volume (numero intero, da 0 a 150): Il volume a cui suona un suono o un video, in percentuale del suo file; senza, un pulsante già presente tiene il suo.