Interactive video
Choices that branch, quizzes, polls, things to tap, a score and endings, and characters a viewer can talk to, all over one ordinary video file.
How it works#
An interactive video is one timeline and one video file. Every branch is a storyboard scene laid on that timeline. A viewer of the interactive version jumps between scenes; a viewer of the plain MP4 sees them in timeline order.
The interactive parts (choices, quizzes, hotspots, rules) are data that sits beside the picture. So:
- Changing a question, an answer or where it leads never re-renders the video.
- The same export plays as an ordinary video everywhere, and as the interactive one on its Vidmoat watch link.
- Everything a creator writes is drawn as text. There is no markup and no web address in a label; over a limit is refused, never trimmed.
Make scenes
Nothing interactive can name a scene that does not exist.
GET /v1/projects/{id}(or MCPget_project) lists the storyboard scenes;setStoryboardwith layout"cover", oraddSceneandassignToScene, makes them over footage already on the timeline.Read what is there
The project carries
interactive { start, flow, items, problems, routes }: where viewers start, what follows each scene, every item with its ids, anything that would leave a viewer stuck, and every route through the video. Change one thing at a time, by id.Add the parts
Send the commands below through Apply commands or MCP
edit_project. Every result carriesproblemsfor what you just wrote: an error means a viewer would get stuck, so fix it before you publish.Render, publish, share
Render once. Put the choices on that export, then make its watch link. See Publishing.
A choice that branches#
The first option of each choice is the default route: what the plain MP4 follows, and what a timed choice takes when nobody picks. A branch that should rejoin the main line needs setSceneFlow with then: "goto" to the scene where it rejoins, or then: "end". Without one it runs on into whatever is next on the timeline, which is usually the other branch.
Commands#
| Command | What it does |
|---|---|
addInteractiveItem | Adds one item to a scene and returns its itemId and optionIds. |
updateInteractiveItem | { itemId, ...only the fields that change }. When replacing options, keep each kept option's id. |
removeInteractiveItem | { itemId }. |
setSceneFlow | { sceneId, then, goto? }: what follows a scene. then is "next", "end" or "goto". Also carries branches, onEnter, angles, explore and variants (below). |
setInteractiveSettings | { start?, chapters?, transition?, hud? } and the design tokens: where viewers start, the chapter menu, "fade" or "cut" between scenes, which variables show on screen, and how everything over the picture looks. See Designing for interaction. |
Kinds of item#
kind | Fields |
|---|---|
choice | options [{ label, goto }], optional prompt, wait: "hold" (the picture holds on the scene's last frame), "loop", "play" (the film plays on under the choice and takes the first option at the scene's end), or { seconds, default } (a held choice that picks an option id after real seconds). |
quiz | question, options [{ label, correct?: true }], optional right { say } and wrong { say, recap }. recap is a scene id: it plays, then the question is asked again. |
poll | question, options [{ label }], showResults. |
hotspot | at { t }, until, box { x, y, w, h } as shares of the frame, label (its name: said by screen readers, never drawn over the picture), action: { goto }, { goto, back: true } (a close-up that returns the viewer to where they tapped) or { card: { title, body } }, and optional mark and position. |
at is "end" (the default) or { t }, seconds from the scene's start. At most 4 options an item, 80 characters a label, 60 items a project.
A hotspot can follow a thing in the picture: make an object mask of it on the clip, then send trackHotspot { itemId, clipId, objectMatte }. The hotspot moves with the thing and cannot be tapped where it leaves the frame. The mask is not applied to the clip.
Designing for interaction#
What is drawn over the picture is a set of typed design tokens. There is no CSS, markup or style string: each token takes one value from a closed list, a value outside the list is refused with the list, and a token you do not send draws its default. One look per video.
Token (on setInteractiveSettings) | Values | Default |
|---|---|---|
tone | "brand", "light", "dark" | "dark". "brand" is dark surfaces with the answers filled in the accent. |
position | "bottom", "centre", "top" | "bottom" |
panel | "card", "glass", "bar", "bare" | "card". glass is frosted, bar a band the width of the picture with the answers side by side, bare no panel at all. |
corners | "round", "soft", "square" | "soft" |
accent | "#RRGGBB", exactly | None. Replaces the orange on answers, lines, the timer and the hotspot mark. |
layout | "row", "stack", "grid" | Automatic: two answers side by side, three or more stacked on a tall picture. |
scrim | "auto", "none", "strong" | "auto": the picture dims a little behind a question. |
font | "inherit", "serif", "mono", "rounded" | "inherit". System font stacks only. |
motion | "rise", "fade", "none" | "rise". A viewer who asked for reduced motion gets none. |
mark | "outline", "ring", "dot", "glow", "none" | What hotspots draw: an outline, or a ring for one that follows a thing. |
null puts a token back to its default. Two fields go on a single item: position ("bottom", "centre", "top") moves one question, or a hotspot's card, away from the subject of its shot; mark on a hotspot overrides the video's.
Three things are refused, with the reason: an accent that is not exactly #RRGGBB, or that neither dark nor white words can be read on at 4.5:1; panel: "bare" together with scrim: "none", which would leave words on a bright frame unreadable; and a mark on anything but a hotspot. mark: "none" is accepted with a warning: nothing is drawn, so the footage itself has to invite the tap.
Every panel in every tone is measured at 4.5:1 or better over a white frame and over a black one, so no combination of tokens can make the words unreadable.
Principles#
- The picture is the content. Nothing over it sits on a face, on-screen text, captions or the thing being discussed. Use the third the shot leaves empty, and move the panel (
position) rather than shrink the subject. - Invite, do not label. A hotspot's label is its accessible name and is never drawn. Build the invitation into the footage (someone looks at or points to the thing, it is lit or framed alone, the narration asks) and let the mark confirm it.
dotcovers least. - Give the shot a beat, then ask. Not during fast cuts, not over speech that matters, and with time to read: about a second for every three words.
- One thing to decide at once, on targets made for a thumb: big, apart, and away from the bottom edge and a feed's right rail.
- Few words, and verbs. A question is one line; an answer is two to four words and starts with a verb when it is an action. Never "Click here".
- Every tap answers at once. The player says what was picked and marks right from wrong with a sign and a word. Do not add a second confirmation.
- Name things for someone who cannot see them: "The red door", not "Tap here".
- The first option is the plain video's route, and nothing should depend on sound.
Games: a score, rules and endings#
Variables turn a branching video into a game. An effect changes a variable; a rule reads one.
setInteractiveVariable { id, kind: "number" | "flag", label, start, min?, max? }.removeInteractiveVariableis refused while anything uses the variable.- Effects
{ var, add }or{ var, set }go on an option'sset, a quiz'sright.setandwrong.set, a hotspot'sset, and a scene'sonEnter(throughsetSceneFlow). - Rules
{ var, op, value }(withall,any,notandvisited) go on an option's or a hotspot'sshowIf(offered only when true) and onsetSceneFlowbranches, read when the scene ends, first match wins. An early game over is{ when: { var: "lives", op: "lte", value: 0 }, goto: "sc_game_over" }. setEnding { sceneId, title, kind: "good" | "bad" | "neutral" }marks an ending.{score}in any text shows the variable's value.
The project then lists the shortest way to each ending. A choice that could offer nothing, or a loop no state escapes, is reported as an error.
Film moves#
| To get | Send |
|---|---|
| Another camera angle of the same moment | setSceneFlow { sceneId, angles: [scene ids] }. Scenes of the same length; the viewer switches and keeps their place. |
| Looking around inside a scene | setSceneFlow { sceneId, explore: { zoom } }. The viewer drags the picture on the watch page. |
| Another take of a scene, by state | setSceneFlow { sceneId, variants: [{ when, scene }] }: the table without the key, once it was taken. |
| Words or a picture that react | setLayer { kind, scene, box, at?, until?, showIf? }, with kind "text" or "image". Text fills in {score}. removeLayer { layerId } takes it off. |
| Music that plays through jumps | Export with the music left out of the file; the watch page plays it across every jump. |
A character to talk to#
setCharacter { name, scene, brief, avoid?, voice?, intents?: [{ when, goto }], turns?, cap? } lets a viewer of the shared video type to a character during that scene. The scene loops while they talk, and an intent opens a scene when the viewer clearly means it. removeCharacter { characterId } takes one off.
Publishing#
Choices are published onto an export that already exists. The server checks that the export still shows the project's picture, compiles the interactive parts into a manifest and stores it with the export.
| Tool | What it does |
|---|---|
publish_interactive { projectId, exportId?, publish?, share? } | Without exportId: lists the project's exports with samePicture and published. With it: publishes, updates, or (publish: false) takes the choices off. share: true also makes the watch link. |
share_export { jobId, share?, title? } | Makes an export's watch link, or takes it away. The link is unlisted: only people who have it can watch. |
It is refused, with the reason, when the picture changed since the export (render again), when the choices would leave a viewer stuck, or on a plan that cannot publish. Publishing never makes a private video public: the link is always a separate, explicit step. Do not make a link the person did not ask for.
Over REST the same three steps are:
| Call | What it does |
|---|---|
GET /v1/projects/{id}/interactive | Lists the project's exports with samePicture and published. |
POST /v1/projects/{id}/interactive | { exportId, publish?, share? }: publishes, updates, or takes the choices off. |
POST /v1/renders/{id}/share | { share?, title? }: makes an export's watch link, or takes it away. |
They are the same functions as the MCP tools and the app's Publish panel, so a refusal carries the same reason on every door.
The plain video#
For TikTok, YouTube and anywhere else that plays a file, render one route as an ordinary video. On POST /v1/renders (and MCP render_project):
| Field | Meaning |
|---|---|
linear: true | The default route: the first option of each choice. |
path: [option ids] | The route you name, one option id per choice. Implies linear. |
A route that would never end is refused before anything is charged.
What a viewer gets#
The watch link (vidmoat.com/watch/…) plays the export with its choices drawn over the picture:
- A question arrives as a beat of the film: the picture dims, the answers rise in, and a timed choice shows how long is left.
- Keys 1 to 4 pick an answer. Escape closes a card. Choices are announced to screen readers, and nothing animates for a viewer who asked for reduced motion.
- The player's bar is about the scene the viewer is in. Full screen keeps the choices on the picture.
- An answer taken before is marked, and an ending offers "Back to the last choice" as well as starting over. A game remembers where a viewer was. All of that is kept in the viewer's own browser.
- Short sounds mark a question, a pick and a change in the score. They play only while the video is not muted.
- At an ending the viewer sees the way they came: each scene, the answer they took and the ones they did not, how many scenes they have seen and how many endings they have found. They can go back to any scene on their path, or share where they ended.
- After a pick the viewer is told what share of viewers chose the same (once ten have picked), and a poll shows every answer's share. Picks are counted as totals only: no account, cookie or address is stored with one.
In your own page#
The embeddable player plays an interactive document as a viewer will see it, before anything is rendered or published: send it the document, then { type: 'viewer', on: true }. It posts every scene, pick and ending to your page, so you can build your own progress, scoring or analytics around it.
Limits and refusals#
- A scene named by a choice, a hotspot, a rule or an angle must exist and have footage.
- Text is plain: no markup, no web addresses.
- Every refusal says what was refused and why, and changes nothing. A refusal that says interactive videos are not switched on is final for that request.