# Shot sequence

> Author a narrated motion-graphics video whose text and shapes appear exactly when the voiceover says them, with a brief, forced alignment and a render.

Source: https://nodaro.ai/docs/mcp/shot-sequence

A **shot sequence** is a narrated motion-graphics video in which every piece of on-screen text, every shape and every image appears the moment the voiceover speaks its matching phrase. You, or an assistant, write a **brief**: the narration, its cues, and the scenes, shots and reveals. Nodaro aligns the recorded voiceover word by word and bakes every cue into an exact frame, so the timing is deterministic. The [Video Director](https://nodaro.ai/docs/mcp/video-director) builds on this pipeline and writes the brief for you.

## The pipeline

Workflow: The narration is voiced, aligned word by word, resolved into a frame-exact plan, and rendered.

- generate_speech → forced_alignment (audio)
- forced_alignment → resolve_shot_sequence (alignment)
- resolve_shot_sequence → render_shot_sequence (plan)

### Voice the narration

Call [`generate_speech`](https://nodaro.ai/docs/mcp/tools/audio#generate_speech) with the narration script. Read the audio URL from the job output. 30 credits with ElevenLabs v3.

### Align the words

Call `forced_alignment` with the audio and the exact same script as `transcript`. Read `output_data.alignment`, a list of `{ word, start, end }` in seconds. 30 credits.

### Resolve the brief

Call `resolve_shot_sequence` with the brief, the audio URL and the alignment. It answers at once with the render-ready `plan` and any `warnings`. Free.

### Render

Call `render_shot_sequence` with the plan. The job renders the MP4, which the card plays and your library keeps. 50 credits at 1920 by 1080.

Call [`start_video_director`](https://nodaro.ai/docs/mcp/tools/shot-sequence-and-video-director#start_video_director) first: it returns the guide for writing the narration as cue phrases and building a good brief.

## Write a brief

A brief has a `narration`, with its `script` and `cues`, and `scenes` that contain `shots`, which contain `reveals`. A **cue** is a phrase of the script. A **reveal** places an element when a cue is spoken.

```json
{
"fps": 30, "width": 1920, "height": 1080, "backgroundColor": "#0b0b0f",
"narration": {
"script": "Ship faster. Nodaro turns your idea into video.",
"cues": [
{ "id": "c_ship", "text": "Ship faster" },
{ "id": "c_idea", "text": "your idea into video" }
]
},
"scenes": [
{
"id": "scene_hook",
"shots": [{
"id": "shot_1",
"reveals": [
{
"id": "rv_title",
"element": { "id": "t1", "type": "text", "text": "Ship faster", "fontFamily": "Inter", "fontSize": 120, "fontWeight": 900, "color": "#ffffff", "x": 200, "y": 450 },
"revealAt": { "kind": "cue", "cueId": "c_ship", "edge": "start" },
"enter": { "motion": "slide-up", "durationFrames": 12, "easing": "easeOut" }
}
]
}]
}
]
}
```

### Anchors

| Anchor | When the element appears |
| --- | --- |
| `{ "kind": "cue", "cueId": "…", "edge": "start" }` | When the cue's phrase starts. Use `"edge": "end"` for when it ends, and `offsetMs` to nudge it. |
| `{ "kind": "frame", "frame": 0 }` | At a fixed frame, for elements without narration, such as an intro logo or an outro |

For an element that must be visible on the thumbnail at frame 0, use `"enter": { "motion": "none", "durationFrames": 0 }`.

### How long an element stays

An element leaves at the end of its scene's content. Set `hold`, the frames it stays after its entrance, and `exit`, a motion after the hold, to control how it leaves.

### Rules that keep the timing exact

- **Cues must match the script exactly**, including spaces. Write the spoken form: "twenty twenty-six", not "2026", and "five dollars", not "$5".
- **Scenes must not overlap in time.** Each scene owns one continuous stretch of the narration. When two scenes' reveals overlap, `resolve_shot_sequence` returns `422 scene_overlap`.
- **Fonts** come from the supported families, such as Inter, Roboto, Montserrat, Poppins, Playfair Display, Bebas Neue, Anton, Caveat, Roboto Mono and Fira Code. Rubik, Heebo, Cairo and Tajawal cover Hebrew and Arabic.
- **Entrance motions** are `fade`, `scale-up`, `wipe-in`, `slide-up`, `slide-down`, `slide-left`, `slide-right` and `none`.
- **Exit motions** are `fade`, `slide-up`, `slide-down`, `slide-left`, `slide-right` and `none`.

A cue that cannot be found in the transcript falls back to proportional timing, and `warnings` says so.

## Blueprints

A blueprint is a ready-made animated beat that you place with a `blueprint` reveal and fill with `params`. `list_shot_shapes` returns the catalog and `get_shot_shape` returns one blueprint's parameters with a worked example. Blueprints cost nothing on their own; the render price covers the whole video.

| Id | Roles | Default frames | What it does |
| --- | --- | --- | --- |
| `comparison-split` | feature showcase | 180 | Two labeled panels slide in from opposite sides and hold with a divider; optional badges pop near the end. |
| `constellation-hub` | hook, social proof | 180 | Labeled nodes spring into a ring around a center hub, then the shot resolves on the core. |
| `cta-morph-press` | call to action | 150 | A button appears in the center, and a cursor slows in and presses it. |
| `cursor-ui-demo` | feature showcase, product intro | 210 | A cursor drives your screenshots through clicks while the view follows each target. |
| `dataviz-countup` | pain point | 240 | A big number counts up to a value with a label. |
| `device-surface-showcase` | product intro, feature showcase | 240 | A device mockup holds while its screens cycle through your screenshots, with headlines in sync. |
| `grid-card-assemble` | feature showcase, benefit, social proof | 180 | Text cards cascade into a grid. |
| `kinetic-type-beats` | hook | 150 | One to four statement lines swap in; the last one pops on an accent. |
| `logo-assemble-lockup` | product intro, branding | 180 | The letters of the brand word assemble into a centered lockup, with an optional tagline. |
| `overwhelm-surround` | pain point | 210 | Tool cards assemble and chips scatter in, then demands close in from every side. |
| `spatial-pan-stations` | hook, pain point | 240 | Labeled stations on one large canvas, visited by smooth camera pans with a callout at each stop. |
| `ticker-takeover` | hook, branding | 180 | A typed lead-in with a cycling accent word, then the hero crashes in. |
| `titlecard-reveal` | benefit, social proof | 120 | One clean title, with an optional subtitle, revealed with one restrained move and held. |
| `typewriter-reveal` | hook, branding | 180 | Text types in letter by letter with a blinking caret; an optional sub-label fades up. |
| `waterfall-reveal` | hook, feature showcase | 150 | The words of a line cut in one by one from left to right; an optional sub-label fades up. |

Default lengths are in frames at 30 fps. `list_shot_shapes` always returns the live catalog.

## Brand tokens

A brief can carry brand tokens, with a palette, fonts and a logo, so every blueprint uses your colors and type. In a brief, the tokens must be the full object, not a preset id: copy a preset's tokens from `list_brand_presets`. The fields are the same as the [Video Director's brand](https://nodaro.ai/docs/mcp/video-director#brand).

## Frequently asked questions

### What is a shot sequence in Nodaro?

A narrated motion-graphics video described as a brief. Each piece of text, shape or image is anchored to a phrase of the voiceover, and Nodaro turns the word timings into exact frames before it renders the MP4.

### How much does a shot sequence video cost?

110 credits for a 1920 by 1080 video. 30 for the voiceover with ElevenLabs v3, 30 for the forced alignment and 50 for the render. Resolving the plan is free.

### Why does resolve_shot_sequence return scene_overlap?

Two scenes have reveals in the same stretch of time. Each scene owns one continuous window of the narration, so keep all of one scene's cues before the next scene's cues.

### How should numbers be written in the narration?

The way they are spoken, such as "twenty twenty-six" or "five dollars". A cue must match the script word for word, and the alignment matches spoken words.