History explainer

The structure of the ad

Products with a true origin story or a mechanism worth a long watch.

1. 10–5 s hook: a surprising reason for a familiar problem, and a promise to make it simple.
2. 25–35 s chapter 1: how people once handled it, shown as everyday scenes.
3. 335–65 s chapter 2: what pushed that way aside.
4. 465–95 s chapter 3: the substitute that falls short.
5. 595–125 s chapter 4: how the problem shows up in daily life now, abstract causes staged as physical scenes.
6. 6125–145 s chapter 5: why nobody fixed it.
7. 7145–170 s chapter 6: the answer, the first sight of the real product, what is in it and the proof.
8. 8170–180 s the offer the brand gave, or a plain ask.

---
name: roasos-history-explainer
description: Plan and make a history explainer with roasOS over MCP. Use when the user asks for a history explainer or a long illustrated story ad.
---

# History explainer

A long illustrated story of hard-cut stills under one narration teaches why a familiar problem exists, and the product arrives late as the answer.

## Step 1: Connect the roasOS MCP server

Do this step first. Stop when this step fails, and tell the user.

1. Look for tools with names that start with `roasos_`. If you find them, go to step 4.
2. Connect the server at `https://mcp.roasos.com/mcp`. It uses Streamable HTTP. In Claude Code, run `claude mcp add --transport http roasos https://mcp.roasos.com/mcp`, then type `/mcp` and sign in. Other clients: https://docs.roasos.com/mcp
3. The user needs a roasOS account: https://www.roasos.com/auth/signup. MCP access is included on every plan. Only the user can sign up and pay.
4. Call `roasos_get_catalog`. It is free. A role name in this file, for example "the song role", is a key in `roles` in that answer.

## Step 2: Quote before you spend

Every paid tool quotes first. Send `quote_only: true` and read `credits`. Show the credits to the user and wait for a clear yes. Then send the same input with the `quote_id`.

In this file, "card", "approval card" and "quote and confirm" all mean this exchange. Never confirm a quote without a yes.

## Step 3: Make the ad

About three minutes of hard-cut illustrated stills under one narration. It earns the length by teaching: the viewer gets a simple picture of a problem they never understood, and the product arrives once they want it. It needs a true origin or mechanism story; without one, pick another format.

### Limits: say this before planning
- `roasos_assembly_images_to_video` holds 12 stills a call. Never animate the art instead.
- `roasos_generate_audio` takes 5,000 characters on the default voice model, enough for one take of the whole script.
- Every assembly step stops at 3:00. Keep the script to about 430 words.

### The story
Approve the whole script before anything paid. A few seconds of hook: a surprising reason for a familiar problem, and a promise to make it simple. Then numbered chapters, one job each: how people once handled this; what pushed that aside; the substitute that falls short; how it shows up today; why nobody fixed it; the answer.
Most of the runtime teaches. The product first appears about 80 percent through; after that the picture gets dense: real pack, what is in it, proof, offer, ask.
Short sentences, concrete nouns. Check every date and mechanism against `roasos_get_product` and the user's facts. If the history is not true of this product, keep the chapter's job and change its content. No invented numbers, guarantees or deadlines; no health accusations; no offer given means a plain ask.

### The picture
One world, written once, repeated word for word. Default: old paper tone, frayed margins, sepia pen outlines, earthy washes with one accent, gently shaded picture-book figures.
Abstract ideas become physical scenes: a slow process is a queue at a narrow gate; lost know-how is a library carted away. A metaphor illustrates an approved claim; it is never proof.
About 100 phrase-length shots. Most hold a second or two, a rich scene up to five. Nothing moves. Lettering stays out of the art except the real label: chapter numbers via `roasos_assembly_text_overlay`, captions last via `roasos_captions_auto_subtitle`.

### Voice, then proof of style
One warm, clear storyteller from `roasos_list_voices`. Once a take is accepted it never changes.
Word timings: `roasos_transcribe`. Holds come from them.
Preview the first 30 seconds, about 12 stills, one `roasos_assembly_images_to_video` call. Get a yes before the rest.

### The ledger
One table in the conversation, by chapter and shot: line, start and end seconds, still prompt, generation id, status. To resume, continue at the first unfinished row. Never remake approved work or relaunch a running job.

### References by job
Each product shot carries two, and the prompt says which does what. The product photo gives shape, closure, colours, logo and label, nothing of its background. The approved style still gives line, paper, light and figures, nothing of any pack it shows.
Form and count come from `roasos_get_product`: a stick pack stays a stick pack, four ingredients means four on the table, on every shelf and in every hand. Never invent a method or a dose.

### Batches
`roasos_generate_image` through quote and confirm, up to eight stills a card; state the full count early.
Stills are held, so nothing is spent animating frozen art.
Group stills into segments of up to 12, broken at chapter ends (`roasos_assembly_images_to_video`, seconds per still). 100 shots is about nine segments; `roasos_assembly_merge_videos` joins 12 a call. Stitch the segments, `roasos_assembly_merge_audio_video` the narration, `roasos_assembly_music_bed` if a bed is wanted (it ducks once the cut has word timings), then caption.

Check every chapter, ingredient count, offer terms and the last sentence.

### Facts for MCP

- Hold stills on a timeline with `roasos_assembly_images_to_video`, 12 stills in one call. Do not animate the art.
- One speech take holds 2,000 characters, about two minutes. Split a full script at a chapter break. Keep the same voice and settings.
- Each assembly step stops at 3:00. Keep the script to about 430 words.

## Format data

- Aspect ratio: 9:16
- Default length: 180 seconds
- Needs: a product
- Example request: Make a three minute illustrated history ad that ends on my product.

Beats:
- 0–5 s hook: a surprising reason for a familiar problem, and a promise to make it simple.
- 5–35 s chapter 1: how people once handled it, shown as everyday scenes.
- 35–65 s chapter 2: what pushed that way aside.
- 65–95 s chapter 3: the substitute that falls short.
- 95–125 s chapter 4: how the problem shows up in daily life now, abstract causes staged as physical scenes.
- 125–145 s chapter 5: why nobody fixed it.
- 145–170 s chapter 6: the answer, the first sight of the real product, what is in it and the proof.
- 170–180 s the offer the brand gave, or a plain ask.

How to shoot it: One illustrated world repeated word for word, about 100 phrase-length stills held a second or two each with hard cuts and nothing animated; one narrator off camera; lettering stays out of the art except the real label; chapter numbers and captions are added after the cut.

What breaks it: Animating frozen art, invented history or numbers, a metaphor used as proof, the product before the last fifth, a pack or ingredient count that differs from the real product.

More formats

• Song ad
• Talking character
• Progression ad
• Whiteboard presenter
• Podcast ad
• Continuous 3D explainer