# 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.

> **Note: Who has it.** Interactive video is part of the Creator and Studio plans (a team plan and a day pass count too). On a Hobby account every command on this page is refused with a sentence that says so, and nothing is changed. It runs in the app, over MCP and over the API; the chat bots do not have it.

## 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.

### Step 1: Make scenes

Nothing interactive can name a scene that does not exist. `GET /v1/projects/{id}` (or MCP `get_project`) lists the storyboard scenes; `setStoryboard` with layout `"cover"`, or `addScene` and `assignToScene`, makes them over footage already on the timeline.

### Step 2: 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.

### Step 3: Add the parts

Send the commands below through [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands) or MCP `edit_project`. Every result carries `problems` for what you just wrote: an error means a viewer would get stuck, so fix it before you publish.

### Step 4: Render, publish, share

Render once. Put the choices on that export, then make its watch link. See [Publishing](#publishing).

## A choice that branches

```json
{
  "commands": [
    { "op": "addInteractiveItem", "kind": "choice", "scene": "sc_opening",
      "prompt": "Which way?",
      "options": [
        { "label": "Into the forest", "goto": "sc_forest" },
        { "label": "Down to the river", "goto": "sc_river" }
      ] },
    { "op": "setSceneFlow", "sceneId": "sc_forest", "then": "end" },
    { "op": "setSceneFlow", "sceneId": "sc_river", "then": "end" }
  ]
}
```

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](#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.

```json
{
  "commands": [
    { "op": "setInteractiveSettings", "panel": "glass", "tone": "brand",
      "accent": "#2E7BFF", "corners": "round", "position": "bottom" },
    { "op": "updateInteractiveItem", "itemId": "it_choice01", "position": "top" },
    { "op": "updateInteractiveItem", "itemId": "it_door0001", "mark": "dot" }
  ]
}
```

| 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. `dot` covers 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.

```json
{
  "commands": [
    { "op": "setInteractiveVariable", "id": "score", "kind": "number", "label": "Score", "start": 0 },
    { "op": "setInteractiveSettings", "hud": ["score"] },
    { "op": "updateInteractiveItem", "itemId": "it_choice01",
      "options": [
        { "id": "op_forest", "label": "Into the forest", "goto": "sc_forest" },
        { "id": "op_river", "label": "Down to the river", "goto": "sc_river",
          "set": [{ "var": "score", "add": 10 }] }
      ] },
    { "op": "setEnding", "sceneId": "sc_river", "title": "Home with {score} points", "kind": "good" },
    { "op": "setEnding", "sceneId": "sc_forest", "title": "Lost in the trees", "kind": "bad" }
  ]
}
```

- `setInteractiveVariable { id, kind: "number" | "flag", label, start, min?, max? }`. `removeInteractiveVariable` is refused while anything uses the variable.
- **Effects** `{ var, add }` or `{ var, set }` go on an option's `set`, a quiz's `right.set` and `wrong.set`, a hotspot's `set`, and a scene's `onEnter` (through `setSceneFlow`).
- **Rules** `{ var, op, value }` (with `all`, `any`, `not` and `visited`) go on an option's or a hotspot's `showIf` (offered only when true) and on `setSceneFlow` `branches`, 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.

> **Warning: Replies cost the creator, and viewer text leaves Vidmoat.** Every reply costs the video's creator 2 credits, or 6 with a voice, up to `cap` credits a month for that video; a reply that would cross the cap is not given. What a viewer types is sent to DeepSeek (China) to write the reply, and is not kept. The creator's `brief`, `avoid` and `cap` never reach the viewer. Never set a voice or a cap the person did not ask for, and never make a character of a real person without their permission.

## 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.

```js MCP
// 1. Render the project (render_project), wait for it (get_render_status).
// 2. Put the choices on that export. No second render.
{ "name": "publish_interactive",
  "arguments": { "projectId": "…", "exportId": "…", "share": true } }
// -> { published: true, shareUrl: "https://www.vidmoat.com/watch/…" }

// Changed a choice and not the picture? Publish again on the same export.
// Changed the picture? The call is refused with the reason: render again.
```

| 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](https://developer.vidmoat.com/developer/docs/preview) 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.

- [MCP](https://developer.vidmoat.com/developer/docs/mcp): Connect an agent and let it build, publish and share an interactive video.
- [Apply commands](https://developer.vidmoat.com/developer/docs/api/projects/apply-commands): The endpoint every command on this page goes through.

---

Source: https://developer.vidmoat.com/developer/docs/interactive
Previous: [Video preview](https://developer.vidmoat.com/developer/docs/preview.md)
Next: [Interactive sites](https://developer.vidmoat.com/developer/docs/interactive-sites.md)
All documentation: https://developer.vidmoat.com/llms-full.txt
