# Vidmoat Script

> Write a video as a plain .txt file: tags set each scene's voice, footage, graphics, sounds and the steps Otto runs, and the file becomes a storyboard.

A Vidmoat Script is an ordinary text file. Plain lines are what is said; tags in angle brackets say how each scene is made. Open it in the editor, send it to a Vidmoat bot, or pass it to the API, and it becomes a storyboard: one card per scene, with its voice, footage, graphics and the steps Otto will run.

**Nothing runs when a script is read.** You see the scenes, their steps and the price first, then build.

```text launch.txt
<scene title="Hook" seconds="4">
<voiceover emotion="excited">You're paying $225 for an edit you could get for ten.</voiceover>
<onscreen>$10 vs $225</onscreen>
<footage stock>close-up of a hand counting cash</footage>
<sfx>whoosh</sfx>
</scene>

<scene title="The trick">
<voiceover>I post two videos a day, and two things make them look expensive.</voiceover>
<footage media="interview.mp4" />
<insert component="stat-counter" on="two videos">2 videos a day</insert>
<sfx on="two">pop</sfx>
<agent>Cut this to the strongest 8 seconds.</agent>
</scene>

<music>calm lo-fi, ducked under the voice</music>
<captions preset="Bold Yellow" />
```

> **Note: Without any tag.** A text with no tag still works: each paragraph (split by a blank line) becomes one scene, exactly as pasting a script always did.

## Scenes

| Tag | What it does |
|---|---|
| `<scene title="Hook" seconds="4">` ... `</scene>` | One scene. `seconds` is its target length; without it the length is estimated from the words. |
| `---` or a blank line | Starts the next scene, when the file has no `<scene>` tags. |
| plain lines | The scene's script. |

## Voice and words on screen

| Tag | What it does |
|---|---|
| `<voiceover voice="..." language="en" emotion="excited">` | The line, spoken by a generated voice. `emotion` uses the voice's named emotions where it has them. |
| `<record>` | The line you will say yourself (the phone's Direct mode films against it). |
| `<onscreen>` | Text shown on screen in that scene. |
| `<captions preset="Bold Yellow" />` | The scene's captions: a preset, `off` or `auto`. Outside every scene, the default for each scene that sets none. |

## Footage and look

| Tag | What it does |
|---|---|
| `<footage stock>`, `<footage generate>`, `<footage own>` | Where the picture comes from, with a description inside. Add `still` or `video` for a generated still or clip. |
| `<footage media="interview.mp4" />` | Your own uploads, by file name. Only your library is searched. |
| `<look preset="...">` | The scene's grade: a preset, a description, or both. |

## Graphics, sounds and Otto

| Tag | What it does |
|---|---|
| `<insert component="stat-counter" on="two videos">2 videos a day</insert>` | A designed graphic on what is said, the way a paid editor packages a talking head. `component` is one of stat-counter, keyword, checklist, chat-bubbles, search-bar, proof-card, icon-card or quote-card (leave it out and Otto chooses); `on` is the spoken words it lands on. Every figure and word on it is checked against what the speaker actually says, so a script cannot put a claim on screen that is not said. |
| `<sfx>whoosh</sfx>`, `<sfx on="two">pop</sfx>` | A sound effect from the stock library: on each graphic in the scene, or on one spoken word. |
| `<agent>` | An instruction Otto carries out on **that scene only**. It cannot change other scenes. |
| `<cut />`, `<cut fillers />` | Remove silences, or filler words, from the scene's speech. |
| `<review />` | Otto reviews the scene and reports what is wrong with it. |

## The whole video

| Tag | What it does |
|---|---|
| `<music>` | The music bed, with what it should feel like. |
| `<chapters />` | Chapters from the scene titles. |
| `<export />` | Open the export when every scene is built. |

Attributes take `"double"`, `'single'` or bare values, and a bare word is a flag (`<footage stock>`). `<!-- comments -->` are ignored.

## Where you can use it

- **The editor**, on the web and in the phone app: Storyboard, then *Split a script into scenes*. Paste it or press **Open a .txt**. What the tags make, and anything not used, is shown before you press **Make scenes from the tags**.
- **Telegram, WhatsApp and Discord**: send the .txt file to the Vidmoat bot in a private chat. It makes the storyboard in a new project and replies with its scenes, anything it could not use, and the link to open and build it.
- **MCP**: `create_storyboard` with `from: { script: "..." }`.
- **API**: `POST /v1/projects/{id}/storyboard` with the same body. The answer carries `script.problems` (line and reason) and `script.notes`.

> **Warning: Nothing is silently dropped.** A tag Vidmoat does not know, text outside every scene, an `<agent>` outside a scene, an upload name that matches nothing, or a tag that is never closed is listed with its line number. Over a board limit (40 scenes, 2,000 characters of script a scene, 12 steps a scene) the whole file is refused with the limit named; nothing is cut to fit.

## Limits

| | Limit |
|---|---|
| Scenes | 40 |
| Script per scene | 2,000 characters |
| Steps per scene (voice, agent, insert, sfx, cut, look, review) | 12 |
| One `<agent>` instruction | 600 characters |
| File sent to a bot | 256 KB of text |

---

Source: https://developer.vidmoat.com/developer/docs/vidmoat-script
Previous: [Test and live keys](https://developer.vidmoat.com/developer/docs/concepts/test-and-live-keys.md)
Next: [Agent profiles on Vidmoat Social](https://developer.vidmoat.com/developer/docs/social-agents.md)
All documentation: https://developer.vidmoat.com/llms-full.txt