Changes to the snippet API

Each line says what changed for people writing actions. Adding an event, a field or a member keeps the version; changing or removing one starts a new version, and actions written for the old one keep working.

The rest of this folder is generated from src/core/api/schema.rs: change the schema, run VOVO_BLESS=1 cargo test, and add a line here, in one commit.

API 1

• First version. Simple events follow, sub, raid, chat and tip, the same on every platform; the Twitch events they are made from, plus twitch.redemption and twitch.hypetrain; button, hotkey, timer, webhook and obs.scene.
• vovo.on, vovo.show, vovo.emit and vovo.state.
• Templates with data-on, data-name and data-seconds; {field} filled as plain text.
• The --vovo-accent CSS variable.
• Permissions chat.send and webhook.
• media.track: what plays on the computer, with its cover. obs.scene and media.track are current values: an action that loads later gets the latest one at once.
• vovo.draw(entries): the app draws one, fairly, and the audit records it.
• vovo.say(text, { voice }): speech on the stream, made by the app.
• persona.answer: the persona's approved answers.
• twitch.viewers: how many watch the stream, about once a minute while it is live; a current value too.
• audio.level and screen.color: the microphone's loudness and the screen's colour, many times a second, read only while an action listens.
• vovo.screen.place(element) and screen.shared: what the streamer shares from the share page (a screen, a window or a tab) shown where an action says, with the screen.show permission.
• vovo.chat.send(text): a line in the live's chat, with the chat.send permission, at the pace the app keeps. timer goes off at the interval its trigger's every condition sets, and hotkey at the combination its keys condition names.
• Controls: an action declares in its manifest what the pad can change while it runs (controls: on or off, a choice, a counter, a text), each kept in vovo.state under its key. A change arrives as control, with the key and the new value, trigger or not.
• vovo.webhook.send(name, data): the app posts JSON to one of the profile's outbound webhooks, by name, with the webhook permission.
• twitch.redemption.resolved: a redemption in a reward's queue approved or rejected, with status; twitch.redemption and it carry the redemption's id as redemption.
• parts on chat and twitch.chat: the message in parts, its emotes as pictures Vovó serves; vovo.chat.parts(e) makes them into nodes, words as text and emotes as images.
• sound.played and video.played: a pad's sound or video button played, with the file it played, which of several when the button draws one. overlay.connected: OBS loaded or reloaded one of the active profile's scenes.
• An action's manifest may say "operator": true: it is then set off only by the pad, hotkeys, timers, its controls and what OBS and the computer say, never by viewers, chat, rewards, webhooks or another action's event.
• vovo.media.play(link), vovo.media.place(element) and vovo.media.stop(): a Twitch clip, a Twitch video or a YouTube video on the stage, in its official player, with the media.play permission; asked by an action anyone may set off, it waits for approval.
• vovo.say's voice names a voice in Piper's folder as piper:<voice>.
• screen.shared also tells a guest's screen the streamer put on air, with guest, the name the streamer gave them; empty for the streamer's own.
• twitch.redemption and twitch.redemption.resolved carry reward_id, Twitch's id for the reward, which survives renaming it: a condition on it keeps working when the reward's title changes.
• vovo.pad.play(label), with the pad.play permission: one of the pad's sound or video buttons pressed by the action, so a reward or a chat command plays a sound the streamer put on the pad.
• persona.answer carries mood: a word in brackets at the answer's start or end ([dancing] we won!), taken off the answer that goes to chat and to speech, so a persona drawn by an action can act as it speaks.
• vovo.say's options pitch, ring and small: a character's voice (higher or lower at the same length, a metallic edge, smaller) from any voice.
• An action's manifest may declare a panel, drawn by the app in the drawer's Extensions: headings, notes, its controls, buttons (asking twice with confirm), forms and lists read from its state with buttons on each line. What is done there arrives as panel, with the name, a form's values, and a line's item and index.
• vovo.media.play tells the app which event it was handled for, like the other calls: a moderator's chat message may then let its link through at once, when the profile says so.
• vovo.obs.source(scene, source, on?) and vovo.obs.filter(source, filter, on?), with the obs.toggle permission: a source shown or hidden in an OBS scene, a filter turned on or off; without on, switched.
• event in the options of vovo.chat.send, vovo.pad.play, vovo.webhook.send, vovo.draw, vovo.media.play, vovo.obs.source and vovo.obs.filter: the event a call answers, for a call made after its listener returned (after an await, in a timer), so two pages still ask once and a moderator's link still plays at once.
• input.move: how the streamer moves in a game, for a scene that sways with the camera: the mouse's movement (dx, dy), where W, A, S and D point (walk, strafe) and jump; a signal, read only while an action listens. The "Camera sway" example uses it.
• input.move also comes from the arrows and from a controller (the left stick as the direction, the right one as the camera's turn, A as the jump); walk and strafe go from -1 to 1, a stick as far as it is pushed.
• remote.talk: someone talked on air from their phone, holding its button as with a walkie-talkie (name, the phone's; seconds, how long the voice lasts), for a scene that shows who is talking while they talk.
• input.move goes on from the mouse and a controller while Vovó's window is in front, unless the computer pauses it; the keys still stop there.
• speech.text: what the streamer said into the microphone, a phrase at a time, for captions (text); a signal, read only while an action listens, written down by Whisper on the computer or by OpenAI when chosen.
• Voice calls with an AI model, on air, with the call permission: vovo.call.start opens one (only from something done by hand by whoever runs the live), vovo.call.answer opens the microphone and has the model speak first, vovo.call.tell tells it something, vovo.call.end hangs up; call.started, call.answered, call.text and call.ended say what happens, with no trigger needed.
• The tts.spoken event: the app read a chat message or a reward's text aloud on air, with persona true for the persona's own line.
• vovo.pad.busy(label, seconds, { lock }): one of the action's own buttons shown at work on the pad, its foot draining as the time goes; locked, a press of it waits for the end.
• sound.played and video.played say how long the file plays (seconds), as the pad shows their buttons at work for that long.
• vovo.pad.lock(label, locked): one of the action's own buttons held, faded and not to be pressed, as a state of the action, with nothing draining.
• A panel may hold several extensions: { "kind": "extension", "label", "icon" } starts another, an entry of its own in Extensions with its name and its icon (one of Vovó's icons by name, or an emoji), and the pieces before the first show at the top of every one. tab then splits an extension into sections, up to twelve in each. A panel that declares none is one extension, as before, and names stay the action's.
• Settings an action declares (settings in action.json: a colour, a number, on or off, a choice, a text, a file, a font), chosen in Customize at the computer: vovo.settings, the settings event, the --vovo-<key> CSS variables and the data-vovo-<key> attributes.
• What an action shows whoever runs the live is called a panel, in Vovó and in the manifest: { "kind": "panel", "label", "icon" } starts another, an entry of its own in Panels, and Vovó writes panel from now on. "kind": "extension", its first name, is read as the same for good, in packages already handed over and in actions already kept. An action that declares several panels this way is refused by a Vovó older than this, as any addition to the manifest is.
• vovo.screen.place(element, { background }): a colour (#000000) for the room contain leaves in the place when the shared screen is another shape. Without it that room stays see-through, as before, and shows what is behind the scene. screen.shared also says window or screen for what Vovó captures itself, with no sound, and comes again with on still true when something else takes the place of what was shared.
• action.json and pad.json described key by key, generated from Vovó's own code like this reference: a page of the help (api/json.*.md), and JSON Schemas for editors, api/action.schema.json, which vovo dev writes beside an action's parts, and api/pad.schema.json. Nothing in either file changed.
• vovo.emit(name, data, { event }): an action's own event is set off once however many pages show the action, as its other calls of the app are, by the event it answers (the one being handled, or event for a call made later) or, with none behind it, by its name and data within 5 seconds. Until now each page's call was an event of its own, so a scene open in OBS and in the preview window had what listened do its part twice.
• vovo.say(text, { event }): speech an action asks for is made once however many pages show the action, and each page plays the one file, by the event it answers (the one being handled, or event for a call made later) or, with none behind it, by its text, voice and pitch within 5 seconds. Until now it was made once for each page, so a scene open in OBS and in the preview window had two voices made for one sentence, which with OpenAI's are two requests that may not sound the same.
• action.json has id: a name of its maker's choosing, the maker's and the action's with a dot between them (example.raffle), the same in every version. A package brought in finds the action it is a version of by it, whatever that action was renamed to, and no longer takes the place of another maker's action of the same name; without one, an action is found by its name, as before. A Vovó older than this passes the key over. version is one line of 32 characters at most, and when a package takes an action's place the two versions are said, read as numbers when they are written as numbers (1.10.0 after 1.9.2, 1.0.0-beta.1 before 1.0.0), with the package being the same or older said and never refused.
• action.json has license: on what terms the action is handed over, as its maker says them, a licence's name (MIT, CC-BY-4.0) or a line of one's own, 100 characters at most, shown as the action is brought in and in the list of actions. A package may carry the licence's whole text beside the manifest as LICENSE (read too as LICENSE.md and LICENSE.txt, and as each with LICENCE), 64 KB of text at most: it is kept with the action, read from the import's dialog before the action comes in, and written back as LICENSE. Vovó says what is written and holds nobody to it. A Vovó older than this passes both over.
• A setting of the kind camera: one of the computer's cameras, chosen in Customize by whoever uses the action, four at most. An action comes with none, and vovo.settings, --vovo-<key> and data-vovo-<key> say only whether one is chosen.
• vovo.camera.place(element, { camera, fit, radius, background, mirror }): shows that camera where the element is, under the action's own drawing, as vovo.screen.place shows the shared screen; with the camera.show permission. The action never sees its pictures.
• camera: a camera the action placed began to show, or stopped; heard without a trigger by an action that may show one.
• A chat message's parts may carry more pictures: with a service switched on in Integrations (7TV, BetterTTV, FrankerFaceZ), a word of the message that is one of its emotes is a part with an image, as Twitch's own emotes are. Nothing changes for an action: vovo.chat.parts(e) shows them, and with every switch off the parts are what they were.
• vovo.chat.send(text, { as: "persona" }): the line goes through the persona's own Twitch account, as the persona's own and not the streamer's; while that account is not connected it is refused and nothing is written as the streamer in its place. Without as, nothing changes.
• twitch.chat's persona: true when the persona's own account wrote the line, so an action leaves the persona's lines out of what it draws and never answers them.
• music.request: a viewer asked for a song of Vovó's music player, by its reward or its chat command, and what became of it (waiting, queued, playing, discarded, or refused and why), so an action answers in chat or shows who asked for what plays.

• Vovó API 1