Scene reference

92 kinds of scene. Each entry shows what it looks like, how its narration reveals it, a complete example you can play, and every field.

A scene is an object in the scenes array. Its kind says which scene it is, and the rest of its fields depend on the kind.

Fields every scene has

Field	Type	What it does
kindrequired	enum	Which scene this is. `introsectionstatementcardstableexamplestatchartrankingversusfeaturetimelinecyclefunnelquotecalloutmediaclipgallerywalkthroughmotionworldmapjourneyberlinmaptimetravelcodequiztermagendamatrixpyramidvennmindmapscalegaugecounterformulabeforeafterpricingtestimonialchatteamfaqbulletsstepsschedulecalendartimercolumnscomparetagsflashcardswaffleprofilesocialheadlinestoryboardtreereceiptchecklistshortcutsemailsearchticketpodiumscoreboardbracketratingforecastplaylistdecisionherohotspotsdeviceofferkineticmontagetrustbrandrevealshowcasespecsmenueventreviewsorbitappuicascadenotifyconstellationendcardctaoutro`
delivery	string	Premium voice only: how this scene is spoken, added to the delivery of the whole video, e.g. "building excitement" or "quiet and sincere". Leave out to keep the video's delivery. Limits: 1–120 characters
hold	number	Extra seconds the scene stays on screen after its narration ends, so a chart, a picture or a clip can be looked at. Leave out for none. Limits: 0–60
transition	enum	Overrides `style.transition` for the way this scene comes in. `risefadeslide-leftslide-rightslide-upslide-downzoom-inzoom-outblurblur-zoomwhipflipcubewipewipe-upirisdiamondsplit-hswirldropbounceelasticthroughburndipflashglitchtvnone`
enter	enum	Overrides `style.enter` for the items of this scene. `popfadeslide-upslide-leftslide-rightslide-blurdriftzoomfocus-pullblurfliptiltrotateswingbouncedropelasticgrowlaunchrevealreveal-upcurtainiriswarp-inflashglitchnone`
image	object	A picture behind or beside this scene.
└ srcrequired	string	Address of the picture: one made or uploaded in the editor (`/api/assets/<id>`), or an http(s) link.
└ alt	string	What the picture shows. Limits: 1–150 characters
└ mode	enum	`backdrop` (default) fills the whole frame behind the scene, softened so the text stays readable. `cutout` is a picture with a transparent background that floats beside the content. `card` is a framed photo, slightly tilted, beside the content. `backdropcutoutcard`
└ side	enum	Which side a `cutout` or `card` sits on. Default `right`. Ignored for a backdrop. `leftright`
└ motion	enum	How the picture moves. Backdrop: `zoom-in` or `zoom-out` (default, they alternate), `pan`, `still`. Cut-out and card: `float` (default), `sway`, `spin` (turns round), `turn` (swings like a 3D display), `pulse`, `bounce`, `still`. `zoom-inzoom-outpanfloatswayspinturnpulsebouncestill`
└ prompt	string	What the AI was asked to paint. Kept so the picture can be made again; it is not shown. Limits: 1–600 characters
header	boolean	`false` hides the top bar (host, title, kicker, brand) during this scene; `true` shows it where it would not be, such as on the title card. See `style.header` for the video as a whole.
progress	boolean	`false` hides the progress indicator during this scene; `true` shows it (as a bar when the video has no `style.progress`).

Scene transitions: rise, fade, slide-left, slide-right, slide-up, slide-down, zoom-in, zoom-out, blur, blur-zoom, whip, flip, cube, wipe, wipe-up, iris, diamond, split-h, swirl, drop, bounce, elastic, through, burn, dip, flash, glitch, tv, none. Item animations: pop, fade, slide-up, slide-left, slide-right, slide-blur, drift, zoom, focus-pull, blur, flip, tilt, rotate, swing, bounce, drop, elastic, grow, launch, reveal, reveal-up, curtain, iris, warp-in, flash, glitch, none. Both are described on the Looks & styles page.

Title card intro

Opening card: the host waves, the emoji floats beside it, then the title, chips and summary from the top of the spec. Use once, first.

Narration. Each say line is one passage. The summary fades in with the first.

Example

{
  "kind": "intro",
  "say": [
    "Welcome! Today we will learn how the water cycle works.",
    "It takes just two minutes."
  ]
}

Field	Type	What it does
sayrequired	string[]	One to three lines that introduce the video. Limits: 1–3 items, each 1–500 characters

Field

Type

What it does

sayrequired

string[]

One to three lines that introduce the video.

Limits: 1–3 items, each 1–500 characters

Chapter break section

A big chapter marker with a number, a title and a subtitle. Use to divide a long video into parts.

Narration. One say line, spoken as the chapter appears.

Example

{
  "kind": "section",
  "number": 2,
  "title": "Putting it into practice",
  "subtitle": "Three steps you can try today",
  "icon": "🛠️",
  "say": "Part two: putting it into practice."
}

Field	Type	What it does
number	string \| integer	Chapter number or a short label such as `Part A`. Limits: 1–4 characters
titlerequired	string	Limits: 1–80 characters
subtitle	string	Limits: 1–150 characters
icon	string	An emoji or a short symbol. Limits: 1–8 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Big statement statement

One short sentence in very large type, optionally with an emoji. Use for a punchline, a definition or a turning point.

Narration. One say line, spoken as the statement appears.

Example

{
  "kind": "statement",
  "eyebrow": "Remember",
  "text": "Small habits, repeated daily, beat **big plans** that never start.",
  "icon": "🌱",
  "say": "Small habits repeated daily beat big plans that never start."
}

Field	Type	What it does
eyebrow	string	Small label above the statement. Limits: 1–48 characters
textrequired	string	The statement. Wrap words in double asterisks to highlight them. Limits: 1–120 characters
icon	string	An emoji or a short symbol. Limits: 1–8 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Cards cards

Concept cards that appear one by one. grid = tiles (best for 3-6 parallel ideas), flow = numbered steps joined by arrows (a process), list = rows with a tick (a checklist; give an item tone: "rose" for a cross).

Narration. Optional lead, then one passage per item (items[].say), then optional outro.

Example

{
  "kind": "cards",
  "heading": "Three states of water",
  "layout": "grid",
  "items": [
    {
      "icon": "🧊",
      "title": "Ice",
      "text": "Solid below zero degrees.",
      "tone": "sky",
      "say": "Below zero degrees water freezes into ice."
    },
    {
      "icon": "💧",
      "title": "Liquid",
      "text": "What we drink and swim in.",
      "tone": "teal",
      "say": "In between it is a liquid, the form we know best."
    },
    {
      "icon": "☁️",
      "title": "Vapour",
      "text": "Invisible gas in the air.",
      "tone": "violet",
      "say": "And when heated it becomes vapour, an invisible gas."
    }
  ],
  "lead": "Water exists in three forms."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
layout	enum	Default `grid`. `gridflowlist`
itemsrequired	object[]	Limits: 1–8 items
└ iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Table table

A comparison table; two columns get a head-to-head look. Rows appear one at a time. Cells are short phrases.

Narration. Optional lead, then one passage per row (rows[].say), then optional outro.

Example

{
  "kind": "table",
  "heading": "Electric vs petrol",
  "columns": [
    "",
    "Electric",
    "Petrol"
  ],
  "rows": [
    {
      "cells": [
        "Running cost",
        "Low",
        "High"
      ],
      "tone": "emerald",
      "say": "Electric cars cost far less to run."
    },
    {
      "cells": [
        "Refuelling",
        "30 minutes",
        "3 minutes"
      ],
      "tone": "amber",
      "say": "But refuelling takes longer, about thirty minutes against three."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
columnsrequired	string[]	Limits: 2–4 items, each up to 48 characters
rowsrequired	object[]	Limits: 1–8 items
└ cellsrequired	string[]	Limits: 2–4 items, each up to 48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Worked example example

A calculation or walk-through: numbered lines, each with an optional highlighted result on the right.

Narration. Optional lead, then one passage per line (lines[].say), then optional outro.

Example

{
  "kind": "example",
  "heading": "Splitting a bill",
  "lines": [
    {
      "text": "Total bill",
      "result": "$120",
      "say": "The dinner costs one hundred and twenty dollars."
    },
    {
      "text": "Add a 15% tip",
      "result": "$138",
      "tone": "amber",
      "say": "Add a fifteen percent tip and it becomes one thirty-eight."
    },
    {
      "text": "Split between 4 friends",
      "result": "$34.50 each",
      "tone": "emerald",
      "say": "Split between four friends, that is thirty-four fifty each."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
linesrequired	object[]	Limits: 1–6 items
└ textrequired	string	Limits: 1–150 characters
└ result	string	Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Big numbers stat

Large number tiles with a label underneath. Use for facts and figures. value is short: 87%, $4.2B, 3x, 24/7.

Narration. Optional lead, then one passage per tile (items[].say), then optional outro.

Example

{
  "kind": "stat",
  "heading": "The ocean in numbers",
  "items": [
    {
      "value": "71%",
      "label": "of Earth is ocean",
      "tone": "sky",
      "say": "Oceans cover seventy-one percent of our planet."
    },
    {
      "value": "3,700 m",
      "label": "average depth",
      "tone": "violet",
      "say": "The average depth is about three thousand seven hundred metres."
    },
    {
      "value": "80%",
      "label": "still unexplored",
      "tone": "fuchsia",
      "say": "And eighty percent of it is still unexplored."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 1–6 items
└ valuerequired	string	Limits: 1–14 characters
└ labelrequired	string	Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Chart chart

An animated chart that fills in as the narrator goes through the data. bars = horizontal bars, columns = vertical columns, donut = shares of a whole, line = a trend (needs 2+ points, one per step), area = a trend with the space under it filled (2+ points), radar = a spider chart comparing 3 to 8 qualities against the highest value, rings = progress rings (values are percentages 0 to 100, at most 5).

Narration. Optional lead, then one passage per data item (items[].say), then optional outro. Each step reveals that item.

Example

{
  "kind": "chart",
  "heading": "Where our energy comes from",
  "chart": "donut",
  "center": "2024",
  "items": [
    {
      "label": "Fossil fuels",
      "value": 60,
      "display": "60%",
      "tone": "orange",
      "say": "Sixty percent still comes from fossil fuels."
    },
    {
      "label": "Renewables",
      "value": 30,
      "display": "30%",
      "tone": "emerald",
      "say": "Thirty percent is renewable."
    },
    {
      "label": "Nuclear",
      "value": 10,
      "display": "10%",
      "tone": "violet",
      "say": "And ten percent is nuclear."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
chartrequired	enum	`barscolumnsdonutlinearearadarrings`
itemsrequired	object[]	Limits: 1–8 items
└ labelrequired	string	Limits: 1–48 characters
└ valuerequired	number	The number to plot. Not negative.
└ display	string	How the value is written next to the element. Default: the number itself. Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
center	string	Text in the hole of a `donut`. Limits: 1–14 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Ranking ranking

A numbered top list. By default it counts down: the last place appears first and number one is the finale.

Narration. Optional lead, then one passage per item in REVEAL order (items[].say), then optional outro. List items in rank order (number one first); with countdown they are narrated bottom-up.

Example

{
  "kind": "ranking",
  "heading": "Top 3 productivity habits",
  "items": [
    {
      "title": "Plan the day",
      "text": "Ten minutes each morning.",
      "value": "#1",
      "tone": "amber",
      "say": "And the number one habit: plan your day every morning."
    },
    {
      "title": "Single-task",
      "text": "One thing at a time.",
      "tone": "violet",
      "say": "Number two: focus on one task at a time."
    },
    {
      "title": "Take breaks",
      "text": "Short and regular.",
      "tone": "teal",
      "say": "Number three: take short, regular breaks."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
order	enum	`countdown` (default) reveals the last place first. `ascending` reveals number one first. `countdownascending`
itemsrequired	object[]	Limits: 2–7 items
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ value	string	Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Two sides versus

Two columns with a title each (pros and cons, before and after, myth and fact). Every point belongs to the left or right side.

Narration. Optional lead, then one passage per point in the order listed (points[].say), then optional outro.

Example

{
  "kind": "versus",
  "heading": "Working from home",
  "left": {
    "title": "Pros",
    "icon": "👍",
    "tone": "emerald"
  },
  "right": {
    "title": "Cons",
    "icon": "👎",
    "tone": "rose"
  },
  "points": [
    {
      "side": "left",
      "text": "No commute",
      "say": "You save the daily commute."
    },
    {
      "side": "right",
      "text": "Harder to switch off",
      "say": "But it is harder to switch off at the end of the day."
    },
    {
      "side": "left",
      "text": "Flexible hours",
      "say": "Your hours can be flexible."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
leftrequired	object
└ titlerequired	string	Limits: 1–48 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
rightrequired	object
└ titlerequired	string	Limits: 1–48 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
pointsrequired	object[]	Limits: 2–8 items
└ siderequired	enum	`leftright`
└ textrequired	string	Limits: 1–150 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Feature feature

A large emoji card on one side and bullet points on the other. Use to introduce one concept with its key traits.

Narration. Optional lead, then one passage per bullet (bullets[].say), then optional outro.

Example

{
  "kind": "feature",
  "heading": "Meet the octopus",
  "icon": "🐙",
  "text": "The master of disguise",
  "bullets": [
    {
      "text": "Three hearts",
      "tone": "rose",
      "say": "An octopus has three hearts."
    },
    {
      "text": "Blue blood",
      "tone": "sky",
      "say": "Its blood is blue."
    },
    {
      "text": "Changes colour in a blink",
      "tone": "fuchsia",
      "say": "And it can change colour in a blink."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
text	string	A line under the big icon. Limits: 1–150 characters
bulletsrequired	object[]	Limits: 1–5 items
└ textrequired	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Timeline timeline

Events along a line, each with a date or label. Use for history, roadmaps and processes over time.

Narration. Optional lead, then one passage per event (events[].say), then optional outro.

Example

{
  "kind": "timeline",
  "heading": "Road to the Moon",
  "events": [
    {
      "label": "1957",
      "title": "Sputnik",
      "text": "First satellite in orbit.",
      "icon": "🛰️",
      "tone": "sky",
      "say": "In nineteen fifty-seven, Sputnik became the first satellite in orbit."
    },
    {
      "label": "1961",
      "title": "First human in space",
      "icon": "👨‍🚀",
      "tone": "violet",
      "say": "In nineteen sixty-one, Yuri Gagarin became the first human in space."
    },
    {
      "label": "1969",
      "title": "Moon landing",
      "text": "Apollo 11.",
      "icon": "🌕",
      "tone": "amber",
      "say": "And in nineteen sixty-nine, Apollo eleven landed on the Moon."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
eventsrequired	object[]	Limits: 2–7 items
└ labelrequired	string	Date or step label, e.g. `1969`, `Day 1`. Limits: 1–16 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Cycle cycle

Steps arranged in a circle with arrows between them, and an optional centre label. Use for loops: the water cycle, a feedback loop, a sprint.

Narration. Optional lead, then one passage per step (items[].say), then optional outro.

Example

{
  "kind": "cycle",
  "heading": "The water cycle",
  "center": "Water",
  "items": [
    {
      "icon": "☀️",
      "label": "Evaporation",
      "tone": "amber",
      "say": "The sun heats the ocean and water evaporates."
    },
    {
      "icon": "☁️",
      "label": "Condensation",
      "tone": "sky",
      "say": "The vapour cools and forms clouds."
    },
    {
      "icon": "🌧️",
      "label": "Rain",
      "tone": "violet",
      "say": "Clouds release the water as rain."
    },
    {
      "icon": "🏞️",
      "label": "Collection",
      "tone": "teal",
      "say": "Rivers carry the water back to the ocean."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
center	string	Short label in the middle of the circle. Limits: 1–24 characters
itemsrequired	object[]	Limits: 3–6 items
└ iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
└ labelrequired	string	Limits: 1–24 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Funnel funnel

Stages that get narrower from top to bottom, each with an optional number. Use for conversion funnels, filters and hierarchies.

Narration. Optional lead, then one passage per stage (stages[].say), then optional outro.

Example

{
  "kind": "funnel",
  "heading": "From visitor to customer",
  "stages": [
    {
      "label": "Visitors",
      "value": "10,000",
      "tone": "sky",
      "say": "Ten thousand people visit the site."
    },
    {
      "label": "Sign-ups",
      "value": "1,200",
      "tone": "violet",
      "say": "Twelve hundred of them sign up."
    },
    {
      "label": "Customers",
      "value": "240",
      "tone": "emerald",
      "say": "And two hundred and forty become paying customers."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
stagesrequired	object[]	Limits: 2–6 items
└ labelrequired	string	Limits: 1–48 characters
└ value	string	Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Quote quote

A large pull quote with the author below. Use for testimonials, famous sayings and expert opinions.

Narration. One say line (usually the quote itself, optionally followed by the author), spoken as the quote appears.

Example

{
  "kind": "quote",
  "quote": "The best way to predict the future is to invent it.",
  "author": "Alan Kay",
  "role": "Computer scientist",
  "say": "As Alan Kay put it: the best way to predict the future is to invent it."
}

Field	Type	What it does
quoterequired	string	Limits: 1–220 characters
authorrequired	string	Limits: 1–48 characters
role	string	The author's title or where the quote is from. Limits: 1–48 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Callout callout

A single tip, warning or fact on a coloured card. warning switches the whole stage to the alert backdrop.

Narration. One say line, spoken as the card appears.

Example

{
  "kind": "callout",
  "tone": "tip",
  "title": "Pro tip",
  "text": "Set one small goal per day. It is easier to keep than a big one.",
  "say": "Here is a tip: set one small goal per day, because it is easier to keep than a big one."
}

Field	Type	What it does
tonerequired	enum	`tipwarningfact`
titlerequired	string	Limits: 1–48 characters
textrequired	string	Limits: 1–220 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Picture media

A full-frame picture with a slow camera move and captions that change as the narrator speaks. Needs a public image address.

Narration. One passage per caption entry (items[].say). The picture is visible from the start; caption shows while that line is spoken.

Example

{
  "kind": "media",
  "heading": "The Great Barrier Reef",
  "src": "https://images.unsplash.com/photo-1544551763-46a013bb70d5?w=1600",
  "alt": "Colourful coral reef with fish",
  "motion": "zoom-in",
  "items": [
    {
      "caption": "2,300 km long",
      "say": "The Great Barrier Reef stretches over two thousand three hundred kilometres."
    },
    {
      "caption": "Visible from space",
      "say": "It is the only living structure visible from space."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
srcrequired	string	Image address.
altrequired	string	What the picture shows. Limits: 1–150 characters
motion	enum	Slow camera move. Default `zoom-in`. `zoom-inzoom-outpanstill`
itemsrequired	object[]	Limits: 1–4 items
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
└ caption	string	Limits: 1–150 characters

Video clip clip

Your own silent footage (b-roll) filling the frame while the narrator speaks, or on its own with no words. Pick a clip from your library; trim with start and length. The scene stays on screen at least as long as the clip plays.

Narration. Optional say: one line spoken while the clip plays. With no narration, the clip alone sets how long the scene lasts.

Example

{
  "kind": "clip",
  "heading": "Morning commute",
  "src": "/api/assets/0123456789abcdef",
  "say": "Every day starts the same way: coffee, keys, and out the door.",
  "fit": "cover",
  "start": 0,
  "length": 8,
  "duration": 24
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
srcrequired	string	Your uploaded clip.
say	string	What the narrator says over the clip. Leave out for footage only. Limits: 1–500 characters
fit	enum	How the clip fills the frame. Default `cover`. `covercontain`
start	number	Seconds into the source where playback begins. Default 0. Limits: 0–60
lengthrequired	number	Seconds of the source to play in this scene. Limits: 0.1–60
durationrequired	number	Full length of the source clip in seconds (copied when you pick the clip). Limits: 0.1–60

Picture gallery gallery

Several pictures that move, for travel, products, people, places or moods. mosaic is a grid of tiles that fill up one picture at a time, each tile drifting slowly, stack deals the pictures like photos tossed on a table, carousel slides them past one after the other with a slow zoom, flipbook swaps them in one frame like the frames of a short film. Each picture comes in when its line is spoken. Needs 2 to 9 pictures, such as ones painted in the editor.

Narration. Optional lead, then one passage per picture (items[].say): each step brings in the next picture, then optional outro.

Example

{
  "kind": "gallery",
  "heading": "Kyoto in pictures",
  "layout": "stack",
  "items": [
    {
      "src": "/examples/travel-kyoto-cherry-blossom/torii.webp",
      "alt": "A red torii gate",
      "caption": "Fushimi Inari",
      "say": "Start with the red gates of Fushimi Inari."
    },
    {
      "src": "/examples/travel-kyoto-cherry-blossom/lane.webp",
      "alt": "A quiet old lane",
      "caption": "Old lanes",
      "say": "Wander the quiet lanes of the old town."
    },
    {
      "src": "/examples/travel-kyoto-cherry-blossom/lantern.webp",
      "alt": "A paper lantern",
      "caption": "Lantern light",
      "say": "Stay for the lanterns after dark."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
layout	enum	How the pictures move. Default `mosaic`. `mosaicstackcarouselflipbook`
itemsrequired	object[]	Limits: 2–9 items
└ srcrequired	string	Picture address.
└ alt	string	What the picture shows. Limits: 1–150 characters
└ caption	string	A few words shown under the picture while its line is spoken. Limits: 1–48 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Walkthrough walkthrough

A screenshot of an app, website, chart or document turned into a guided tour: the picture sits in a window frame while the camera glides to each area you name, the rest dims, and a numbered pin with a short callout appears. For product demos, software tutorials and UI explainers. One scene per screenshot; attach the picture first, then set screenshot to its address.

Narration. Optional lead (overview of the whole screen), then one passage per step (steps[].say): each step zooms to its focus and shows its callout, then optional outro.

Example

{
  "kind": "walkthrough",
  "heading": "Your first project",
  "screenshot": "/examples/tech-dashboard-walkthrough/dashboard.webp",
  "lead": "This is the dashboard you see after signing in.",
  "steps": [
    {
      "focus": {
        "x": 2,
        "y": 4,
        "width": 22,
        "height": 12
      },
      "title": "Sidebar",
      "text": "Jump between sections here.",
      "say": "On the left, the sidebar lists every main section.",
      "marker": "box"
    },
    {
      "focus": {
        "x": 28,
        "y": 14,
        "width": 44,
        "height": 28
      },
      "title": "Project list",
      "say": "The middle shows your projects, ready to open.",
      "marker": "spotlight"
    },
    {
      "focus": {
        "x": 76,
        "y": 8,
        "width": 20,
        "height": 10
      },
      "title": "New project",
      "say": "Tap here when you want to start something new.",
      "marker": "pin"
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
screenshotrequired	string	Screenshot to guide the viewer through.
stepsrequired	object[]	Limits: 1–8 items
└ focusrequired	object	The part of the screenshot to zoom into.
└ xrequired	number	Distance from the left edge of the picture, as a percentage of its width. Limits: 0–100
└ yrequired	number	Distance from the top edge of the picture, as a percentage of its height. Limits: 0–100
└ widthrequired	number	Width of the area, as a percentage of the picture width. Limits: 0–100
└ heightrequired	number	Height of the area, as a percentage of the picture height. Limits: 0–100
└ titlerequired	string	Short label on the callout. Limits: 1–48 characters
└ text	string	Extra detail under the title. Limits: 1–150 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
└ marker	enum	How the focus is highlighted. Default `box`. `ellipse` and `underline` are drawn by hand, stroke by stroke, like a presenter circling or underlining the spot. `boxspotlightarrowpinellipseunderline`
└ pointer	boolean	A hand pointer glides to the area and taps it, as if someone were clicking there. For buttons, toggles and fields.
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Motion graphic motion

A drawing made of shapes (rectangles, circles, stars, hearts, arrows, lines, text, paths ...) that move like in a motion-graphics video: they pop in, draw themselves, bounce, orbit, follow a route. Each shape is plain JSON with a position, a size and colours, and says how it comes in (enter), keeps moving (loop) and leaves (exit). repeat makes rows, grids and rings of copies. For choreography beyond that, script is a GSAP timeline written as text (tl.to("ball", { x: 40, duration: 1 }, "line2")), placed on the narration with the labels line1, line2 ... Use it for ideas that words and cards cannot show: growth, flow, balance, orbit, a countdown, a diagram that builds itself.

Narration. Optional lead, then one passage per entry of lines. The shapes and the script can be timed to each passage: the moment line 2 is spoken is at: "line2" on a shape and "line2" as the position in the script.

Example

{
  "kind": "motion",
  "heading": "Launch day",
  "shapes": [
    {
      "id": "star",
      "type": "star",
      "size": 3,
      "x": 80,
      "y": 7,
      "fill": "amber",
      "repeat": {
        "count": 9,
        "gap": 16
      },
      "enter": "pop",
      "loop": "blink",
      "at": 0.3
    },
    {
      "id": "trail",
      "type": "path",
      "d": "M 14 50 C 50 54, 80 6, 146 12",
      "stroke": "sky",
      "strokeWidth": 0.8,
      "enter": "draw",
      "at": "line1",
      "duration": 1.6
    },
    {
      "id": "rocket",
      "type": "triangle",
      "width": 7,
      "height": 10,
      "x": 14,
      "y": 50,
      "fill": "rose",
      "glow": true,
      "enter": "pop",
      "at": "line2"
    },
    {
      "id": "label",
      "type": "text",
      "text": "Lift-off!",
      "size": 7,
      "x": 118,
      "y": 42,
      "fill": "text",
      "enter": "type",
      "at": "line3"
    }
  ],
  "script": "tl.to(\"rocket\", { motionPath: { path: \"trail\", autoRotate: 90 }, duration: 2.6, ease: \"power1.inOut\" }, \"line2+=0.4\");",
  "lines": [
    {
      "say": "Every launch starts with a plan, drawn out on the board."
    },
    {
      "say": "Then the rocket takes its place at the start of the route."
    },
    {
      "say": "And off it goes, all the way to lift-off."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
canvas	enum	The drawing board, in canvas units: `wide` is 160 wide and 60 tall, `square` is 100 wide and 100 tall, `tall` is 60 wide and 100 tall. Default `wide`. Shapes are placed with x from 0 to the width and y from 0 (top) to the height. `widesquaretall`
shapesrequired	object[]	What to draw, from the back to the front. Limits: 1–40 items
└ idrequired	string	Name of the shape. The script refers to it by this name.
└ typerequired	enum	What to draw. `rectsquarecircleellipsetrianglediamondpolygonstarheartarrowlineringcrosstextpath`
└ group	string	A name shared by several shapes, so the script can move them together.
└ x	number	Centre of the shape across the canvas. Default: the middle. A `line` or `arrow` starts here; a `path` is drawn from here (default 0). Limits: -400–400
└ y	number	Centre of the shape down the canvas. Default: the middle. Limits: -400–400
└ size	number	Width and height of the shape (font size for `text`). Default 16 (6 for `text`). Limits: 0–400
└ width	number	Overrides the width of `rect`, `ellipse`, `triangle`, `diamond`, `polygon`, `star`, `heart`, `cross`, `ring`. Limits: 0–400
└ height	number	Overrides the height, like `width`. Limits: 0–400
└ x2	number	Where a `line` or `arrow` ends, across. Default: `size` to the right of the start. Limits: -400–400
└ y2	number	Where a `line` or `arrow` ends, down. Default: level with the start. Limits: -400–400
└ fill	string	Colour inside the shape. Default `accent` (or `none` if only `stroke` is given). A `line`, `arrow` or `ring` takes it as its stroke colour.
└ fill2	string	A second colour: the fill becomes a gradient from `fill` (top left) to `fill2` (bottom right).
└ stroke	string	Colour of the outline.
└ strokeWidth	number	Thickness of the outline or line. Default 1 for lines, 2 for a `ring`. Limits: 0–40
└ opacity	number	0 is invisible, 1 solid (default). Limits: 0–1
└ rotation	number	Degrees, clockwise. Limits: -3600–3600
└ radius	number	Rounded corners of a `rect` or `square`. Limits: 0–400
└ sides	integer	Corners of a `polygon`. Default 6. Limits: 3–12
└ points	integer	Points of a `star`. Default 5. Limits: 3–16
└ inner	number	How deep a `star` is cut, or how thin the arms of a `cross` are, from 0.1 to 0.9. Default 0.5 (0.34 for a cross). Limits: 0.1–0.9
└ text	string	The words of a `text` shape. Limits: 1–60 characters
└ weight	integer	Boldness of `text`. Default 800. Limits: 100–900
└ d	string	SVG path data in canvas units, for a `path`, e.g. `M 10 40 C 40 5, 80 5, 110 40`. Limits: up to 600 characters
└ glow	boolean	A soft glow in the colour of the shape.
└ repeat	object	Draw many copies of this shape in a row, grid or circle.
└ countrequired	integer	How many copies. They are named `<id>1`, `<id>2` ... and all belong to the group `<id>`. Limits: 2–60
└ layout	enum	Where the copies go, around the shape's own position. Default `row`. `rowcolumngridcirclediagonal`
└ gap	number	Distance between the centres of neighbouring copies. Default: 1.5 times the size. Limits: 0–400
└ columns	integer	Copies per row in a `grid`. Default: the square root of the count, rounded up. Limits: 1–20
└ radius	number	Radius of a `circle`. Default: wide enough for the copies not to touch. Limits: 0–400
└ startAngle	number	Where a `circle` starts, in degrees. Default -90 (the top). Limits: -360–360
└ palette	string[]	Colours the copies take in turn, instead of `fill`. Limits: 1–8 items
└ rotate	boolean	Turn each copy of a `circle` to face outwards.
└ enter	enum	How the shape comes in. Without it the shape is simply there from the start. `fadepoprisedropslide-leftslide-rightzoomspingrowdrawtype`
└ loop	enum	A movement that repeats while the shape is on screen. `floatpulsespinswaybounceblinkwiggle`
└ exit	enum	How the shape leaves, at `exitAt`. `fadeshrinkslide-leftslide-rightslide-upslide-down`
└ at	number \| string	When the shape comes in: seconds, or `line2` for when the second line is spoken. Default: one after another, a quarter of a second apart. Limits: 0–600
└ delay	number	Extra seconds before `enter`. Limits: 0–600
└ duration	number	Seconds `enter` and `exit` take. Default depends on the animation. Limits: 0.05–30
└ stagger	number	Seconds between the copies of a `repeat`. Default 0.08. Limits: 0–5
└ exitAt	number \| string	When the shape leaves, in the same terms as `at`. Limits: 0–600
script	string	A GSAP timeline as text, for movements `enter`, `loop` and `exit` cannot make: `tl.to("ball", { x: 40, rotation: 90, duration: 1, ease: "power2.out" }, "line2")`. Calls: `tl.to`, `tl.from`, `tl.fromTo`, `tl.set`, `tl.addLabel`. Names are shape ids, group names or "all". Limits: up to 4000 characters
linesrequired	object[]	The narration, one passage at a time. Their moments are the labels `line1`, `line2` ... Limits: 1–8 items
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

World map worldmap

A map of the world that visits places one by one: the camera swoops in on a country, which lights up with a glow and its name, or on a city, which gets a pulsing marker. Places already visited stay tinted, so the map fills up as the narration goes. For geography, travel, history, news, where something happens or where a company operates. Countries and about 150 major cities are known by name; any other place can be given with latitude and longitude.

Narration. Optional lead (the whole world is shown), then one passage per place (places[].say): each step flies to the next place, then optional outro.

Example

{
  "kind": "worldmap",
  "heading": "Where the coffee comes from",
  "places": [
    {
      "place": "Brazil",
      "note": "Largest producer",
      "tone": "emerald",
      "say": "Brazil grows more coffee than any other country."
    },
    {
      "place": "Ethiopia",
      "note": "Where coffee began",
      "tone": "amber",
      "say": "Ethiopia is where coffee was first discovered."
    },
    {
      "place": "Vietnam",
      "note": "Home of robusta",
      "tone": "rose",
      "say": "Vietnam is the world's leader in robusta beans."
    },
    {
      "place": "Seattle",
      "note": "A coffee-shop capital",
      "tone": "sky",
      "say": "And Seattle turned it into a coffee-shop culture."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
placesrequired	object[]	Limits: 1–8 items
└ placerequired	string	A country (`Japan`, `United States`, `UK`) or a city (`Tokyo`, `New York`, `Sao Paulo`) the map knows by name. Limits: 1–48 characters
└ latitude	number	Only for a place the map does not know by name: its latitude (north is positive). Give `longitude` too. Limits: -90–90
└ longitude	number	Only for a place the map does not know by name: its longitude (east is positive). Give `latitude` too. Limits: -180–180
└ label	string	The text shown on the map. Default: the name of the place. Limits: 1–48 characters
└ note	string	A few words under the label, such as a number or a date. Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Journey journey

A trip across the map: stops are marked one by one and a vehicle travels the route between them, a plane on a high arc, a train, a bus, a car, a boat, a bike or a person on foot, leaving a drawn line behind it. Each stop says how to get there from the one before. For travel plans, itineraries, shipping and supply chains, migrations, explorers, a product's path, a customer's trip. Needs 2 to 8 stops, known by name or given with latitude and longitude.

Narration. Optional lead, then one passage per stop (stops[].say): each step announces the next stop and sets the vehicle off to it, then optional outro. The first stop is simply where the trip starts.

Example

{
  "kind": "journey",
  "heading": "Two weeks across Asia",
  "stops": [
    {
      "place": "London",
      "say": "The trip begins in London."
    },
    {
      "place": "Dubai",
      "mode": "plane",
      "say": "A night flight takes us to Dubai for a first stop."
    },
    {
      "place": "Mumbai",
      "mode": "plane",
      "say": "Then on to Mumbai, where the real adventure starts."
    },
    {
      "place": "Delhi",
      "mode": "train",
      "say": "A long train ride north brings us to Delhi."
    },
    {
      "place": "Kathmandu",
      "mode": "bus",
      "say": "And a bumpy bus ride to the mountains of Kathmandu."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
stopsrequired	object[]	Limits: 2–8 items
└ placerequired	string	A country (`Japan`, `United States`, `UK`) or a city (`Tokyo`, `New York`, `Sao Paulo`) the map knows by name. Limits: 1–48 characters
└ latitude	number	Only for a place the map does not know by name: its latitude (north is positive). Give `longitude` too. Limits: -90–90
└ longitude	number	Only for a place the map does not know by name: its longitude (east is positive). Give `latitude` too. Limits: -180–180
└ label	string	The text shown at the stop. Default: the name of the place. Limits: 1–48 characters
└ mode	enum	How the trip gets here from the previous stop. Default `plane`. Ignored for the first stop. `planetrainbuscarboatbikewalk`
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Berlin map berlinmap

A detailed map of Berlin with its districts, parks, lakes and rivers that visits places one by one: the camera flies to a district (Bezirk), which lights up with a glow and its name, or to a landmark or neighbourhood, which gets a pulsing marker. Places already visited stay tinted or marked, so the map fills up as the narration goes. With connect, a line is drawn from each stop to the next, for a walking tour or a day plan. For anything about Berlin: its districts, what to see, where to eat or stay, a weekend itinerary, the history of the city. Only Berlin is mapped. The 12 districts and about 100 landmarks and neighbourhoods are known by name (Mitte, Neukölln, Brandenburg Gate, East Side Gallery, Kreuzberg, Tempelhofer Feld); any other spot in Berlin can be given with latitude and longitude.

Narration. Optional lead (the whole city is shown), then one passage per place (stops[].say): each step flies to the next place, then optional outro.

Example

{
  "kind": "berlinmap",
  "heading": "A day in the middle of Berlin",
  "connect": true,
  "lead": "Berlin is big, but the best of it fits into one day.",
  "stops": [
    {
      "place": "Brandenburg Gate",
      "note": "Start here",
      "tone": "amber",
      "say": "Start at the Brandenburg Gate, the symbol of a city that was once divided."
    },
    {
      "place": "Museum Island",
      "note": "Five museums",
      "tone": "violet",
      "say": "Walk along Unter den Linden to Museum Island, five museums on one tiny island."
    },
    {
      "place": "TV Tower",
      "note": "368 metres",
      "tone": "rose",
      "say": "Then ride up the TV Tower for the best view over the city."
    },
    {
      "place": "East Side Gallery",
      "note": "1.3 km of art",
      "tone": "emerald",
      "say": "End the day at the East Side Gallery, the longest open-air gallery in the world."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
stopsrequired	object[]	Limits: 1–12 items
└ placerequired	string	A district (`Mitte`, `Friedrichshain-Kreuzberg`, `Neukölln`), or a landmark or neighbourhood the map knows by name (`Brandenburg Gate`, `Museum Island`, `Prenzlauer Berg`). Limits: 1–48 characters
└ latitude	number	Only for a spot the map does not know by name: its latitude, such as `52.5163`. Give `longitude` too.
└ longitude	number	Only for a spot the map does not know by name: its longitude, such as `13.3777`. Give `latitude` too.
└ label	string	The text shown on the map. Default: the name of the place. Limits: 1–48 characters
└ note	string	A few words under the label, such as a number or a nickname. Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
connect	boolean	Draw a line from each stop to the next. For a route that is followed in order; leave it out for places that are only listed.
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Time travel timetravel

A journey through years: a big counter spins from one year to the next while a ruler of years slides past, and each stop pops up with what happened then. Works forwards (1900 to 2026) and backwards, over decades or millennia (negative years are BC). For history, the story of a company or a technology, a person's life, how something changed, before and after. Needs 2 to 8 events; from lets the trip start before the first one.

Narration. Optional lead (the counter waits at from), then one passage per event (events[].say): each step travels to the year of the next event, then optional outro.

Example

{
  "kind": "timetravel",
  "heading": "A century of flight",
  "from": 1900,
  "events": [
    {
      "year": 1903,
      "title": "The first flight",
      "text": "The Wright brothers fly for twelve seconds.",
      "say": "In 1903 the Wright brothers got off the ground for twelve seconds."
    },
    {
      "year": 1927,
      "title": "Across the Atlantic",
      "text": "Lindbergh flies solo from New York to Paris.",
      "say": "In 1927 Charles Lindbergh flew alone across the Atlantic."
    },
    {
      "year": 1969,
      "title": "The jumbo jet",
      "text": "The 747 makes long-haul travel affordable.",
      "say": "In 1969 the jumbo jet made long flights something everyone could afford."
    },
    {
      "year": 2026,
      "title": "Electric planes",
      "text": "Short routes begin to go electric.",
      "say": "And today, the first electric planes are starting to carry passengers."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
from	integer	The year the trip starts at. Default: the year of the first event (so the first step does not travel). Limits: -9999–9999
eventsrequired	object[]	Limits: 2–8 items
└ yearrequired	integer	The year of the event; negative years are BC. Events can go forwards or backwards in time. Limits: -9999–9999
└ titlerequired	string	What happened. Limits: 1–48 characters
└ text	string	A line of detail. Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Code code

A code editor window whose lines appear one by one, the current line highlighted. Use for programming, commands and config.

Narration. One passage per line (lines[].say), spoken as that line appears. Every line needs one, even a closing brace or a blank line, so keep snippets short and skip blank lines.

Example

{
  "kind": "code",
  "heading": "A tiny function",
  "filename": "greet.ts",
  "lines": [
    {
      "code": "function greet(name: string) {",
      "say": "We start by declaring a function called greet that takes a name."
    },
    {
      "code": "  return `Hello, ${name}!`;",
      "say": "It returns a friendly greeting built from that name."
    },
    {
      "code": "}",
      "say": "And that closes the function."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
filename	string	Shown in the editor title bar. Limits: 1–32 characters
linesrequired	object[]	Limits: 1–12 items
└ coderequired	string	One line of code. Leading spaces are kept. Limits: 1–64 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Quiz quiz

A multiple-choice question. The question and options appear first, then the correct answer is revealed with an optional explanation.

Narration. Exactly two lines in say: the first reads the question (and options), the second reveals the answer.

Example

{
  "kind": "quiz",
  "question": "Which planet is closest to the Sun?",
  "options": [
    "Venus",
    "Mercury",
    "Mars"
  ],
  "answer": 1,
  "explanation": "Mercury orbits the Sun in just 88 days.",
  "say": [
    "Quick quiz: which planet is closest to the Sun? Venus, Mercury or Mars?",
    "The answer is Mercury, which orbits the Sun in just eighty-eight days."
  ]
}

Field	Type	What it does
heading	string	Default: `Quick quiz`. Limits: 1–60 characters
questionrequired	string	Limits: 1–150 characters
optionsrequired	string[]	Limits: 2–4 items, each 1–48 characters
answerrequired	integer	Index of the correct option, counting from 0. Limits: 0–3
explanation	string	Limits: 1–150 characters
sayrequired	[string, string]	[question line, answer line] Limits: exactly 2 items, each 1–500 characters

Definition term

A dictionary-style card: the term, its pronunciation and type, the definition, and an example sentence, revealed in that order.

Narration. say has one line per reveal: 1 = the term, 2 = the definition, 3 = the example (only when example is set).

Example

{
  "kind": "term",
  "term": "Photosynthesis",
  "pronunciation": "/ˌfoʊtoʊˈsɪnθəsɪs/",
  "partOfSpeech": "noun",
  "definition": "The process plants use to turn sunlight, water and carbon dioxide into food and oxygen.",
  "example": "Thanks to photosynthesis, a single tree can release enough oxygen for two people.",
  "say": [
    "Our word for today is photosynthesis.",
    "It is the process plants use to turn sunlight, water and carbon dioxide into food and oxygen.",
    "For example, one tree can release enough oxygen for two people."
  ]
}

Field	Type	What it does
termrequired	string	Limits: 1–48 characters
pronunciation	string	For example `/ˈɛnərdʒi/`. Limits: 1–48 characters
partOfSpeech	string	For example `noun`. Limits: 1–20 characters
definitionrequired	string	Limits: 1–220 characters
example	string	An example sentence. Limits: 1–150 characters
sayrequired	string[]	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–3 items, each 1–500 characters

Agenda agenda

A numbered "what we will cover" list with big numerals and thin dividers. Use it near the start to preview the video, or to list chapters. Cleaner and more editorial than cards.

Narration. Optional lead, then one passage per item (items[].say), then optional outro.

Example

{
  "kind": "agenda",
  "heading": "What we will cover",
  "items": [
    {
      "title": "Why sleep matters",
      "text": "What happens in the brain overnight.",
      "tone": "violet",
      "say": "First, why sleep matters and what happens in your brain overnight."
    },
    {
      "title": "How much you need",
      "text": "It depends on your age.",
      "tone": "sky",
      "say": "Then, how much sleep you really need at each age."
    },
    {
      "title": "Better habits",
      "text": "Five small changes.",
      "tone": "emerald",
      "say": "And finally, five small habits that help you sleep better."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–7 items
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

2×2 matrix matrix

A four-quadrant grid with a labelled horizontal and vertical axis (priority matrix, SWOT, effort versus impact). The x axis grows to the right, the y axis grows upwards. Give exactly four quadrants in reading order: top-left, top-right, bottom-left, bottom-right.

Narration. Optional lead, then one passage per quadrant in reading order (quadrants[].say), then optional outro.

Example

{
  "kind": "matrix",
  "heading": "The priority matrix",
  "xAxis": {
    "label": "Urgency",
    "low": "Can wait",
    "high": "Now"
  },
  "yAxis": {
    "label": "Importance",
    "low": "Minor",
    "high": "Major"
  },
  "quadrants": [
    {
      "title": "Schedule",
      "text": "Important, not urgent.",
      "tone": "sky",
      "say": "Important but not urgent tasks go in your calendar."
    },
    {
      "title": "Do first",
      "text": "Important and urgent.",
      "tone": "rose",
      "say": "Important and urgent tasks come first."
    },
    {
      "title": "Drop",
      "text": "Neither.",
      "tone": "violet",
      "say": "Tasks that are neither can often be dropped."
    },
    {
      "title": "Delegate",
      "text": "Urgent, not important.",
      "tone": "amber",
      "say": "Urgent but unimportant tasks are best handed to someone else."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
xAxisrequired	object	Horizontal axis. `low` is written at the left end, `high` at the right end.
└ labelrequired	string	Limits: 1–24 characters
└ low	string	Limits: 1–20 characters
└ high	string	Limits: 1–20 characters
yAxisrequired	object	Vertical axis. `low` is written at the bottom, `high` at the top.
└ labelrequired	string	Limits: 1–24 characters
└ low	string	Limits: 1–20 characters
└ high	string	Limits: 1–20 characters
quadrantsrequired	object[]	Exactly four: top-left, top-right, bottom-left, bottom-right. Limits: exactly 4 items
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Pyramid pyramid

A stacked pyramid of levels with a title and text beside each (a hierarchy of needs, a food pyramid, layers of a model). List the levels from the TOP (the narrow tip) to the BASE. By default the base is revealed first, building the pyramid upwards.

Narration. Optional lead, then one passage per level in REVEAL order (items[].say), then optional outro. With the default base-first, narrate the base first.

Example

{
  "kind": "pyramid",
  "heading": "Maslow's hierarchy of needs",
  "items": [
    {
      "icon": "🌟",
      "title": "Self-fulfilment",
      "text": "Reaching your potential.",
      "tone": "fuchsia",
      "say": "At the top sits self-fulfilment, becoming the best version of yourself."
    },
    {
      "icon": "🏆",
      "title": "Esteem",
      "text": "Respect and recognition.",
      "tone": "amber",
      "say": "Below it is esteem: respect, recognition and confidence."
    },
    {
      "icon": "🤝",
      "title": "Belonging",
      "text": "Friends, family, love.",
      "tone": "rose",
      "say": "Next comes belonging, the need for friends, family and love."
    },
    {
      "icon": "🛡️",
      "title": "Safety",
      "text": "Security and stability.",
      "tone": "sky",
      "say": "Then safety, which means security and stability."
    },
    {
      "icon": "🍞",
      "title": "Basic needs",
      "text": "Food, water, sleep.",
      "tone": "emerald",
      "say": "At the base are the basics: food, water and sleep."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
order	enum	`base-first` (default) reveals the bottom level first. `top-first` starts at the tip. `base-firsttop-first`
itemsrequired	object[]	Limits: 3–6 items
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Venn diagram venn

Two or three overlapping circles with a label each, and an optional label for where they all overlap. Use for what two ideas share, or for the sweet spot between three.

Narration. Optional lead, then one passage per circle (sets[].say), then the passage of the overlap (overlap.say) if there is one, then optional outro.

Example

{
  "kind": "venn",
  "heading": "Finding your career sweet spot",
  "sets": [
    {
      "label": "What you love",
      "text": "Work that energises you.",
      "tone": "rose",
      "say": "Start with what you love doing."
    },
    {
      "label": "What you are good at",
      "text": "Your strengths.",
      "tone": "sky",
      "say": "Add what you are genuinely good at."
    },
    {
      "label": "What pays",
      "text": "What the world needs.",
      "tone": "emerald",
      "say": "And what people will pay for."
    }
  ],
  "overlap": {
    "label": "Your sweet spot",
    "say": "Where all three meet is your sweet spot."
  }
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
setsrequired	object[]	Limits: 2–3 items
└ labelrequired	string	Limits: 1–28 characters
└ text	string	Limits: 1–60 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
overlap	object	Written where all circles overlap.
└ labelrequired	string	Limits: 1–32 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Mind map mindmap

A central topic with branches radiating out, each joined to the centre by a line. Use to break one big idea into 3 to 6 parts.

Narration. Optional lead, then one passage per branch (branches[].say), then optional outro. The centre is visible from the start.

Example

{
  "kind": "mindmap",
  "heading": "Ingredients of a great talk",
  "center": "A great talk",
  "centerIcon": "🎤",
  "branches": [
    {
      "icon": "🎯",
      "title": "Clear message",
      "text": "One idea to remember.",
      "tone": "violet",
      "say": "It has one clear message the audience can remember."
    },
    {
      "icon": "📖",
      "title": "Story",
      "text": "People remember stories.",
      "tone": "amber",
      "say": "It tells a story, because people remember stories, not slides."
    },
    {
      "icon": "🖼️",
      "title": "Simple slides",
      "text": "Few words, big visuals.",
      "tone": "sky",
      "say": "Its slides are simple, with few words and big visuals."
    },
    {
      "icon": "🗣️",
      "title": "Practice",
      "text": "Rehearse out loud.",
      "tone": "emerald",
      "say": "And it is rehearsed out loud, more than once."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
centerrequired	string	The central topic. Limits: 1–48 characters
centerIcon	string	An emoji or a short symbol. Limits: 1–8 characters
branchesrequired	object[]	Limits: 3–6 items
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–60 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Scale scale

A coloured spectrum bar with labelled markers placed along it (the pH scale, a temperature range, a risk level). Each marker has a position from 0 (start) to 100 (end).

Narration. Optional lead, then one passage per marker in the order listed (markers[].say), then optional outro.

Example

{
  "kind": "scale",
  "heading": "The pH scale",
  "from": "Acidic",
  "to": "Alkaline",
  "markers": [
    {
      "position": 5,
      "label": "Lemon juice",
      "text": "pH 2",
      "tone": "rose",
      "say": "Lemon juice is strongly acidic, around pH two."
    },
    {
      "position": 50,
      "label": "Pure water",
      "text": "pH 7",
      "tone": "emerald",
      "say": "Pure water sits in the middle at seven, which is neutral."
    },
    {
      "position": 93,
      "label": "Bleach",
      "text": "pH 13",
      "tone": "violet",
      "say": "Bleach is strongly alkaline, around pH thirteen."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
from	string	Label of the start of the bar. Limits: 1–20 characters
to	string	Label of the end of the bar. Limits: 1–20 characters
markersrequired	object[]	Limits: 2–6 items
└ positionrequired	number	Where on the bar: 0 is the start, 100 the end. Limits: 0–100
└ labelrequired	string	Limits: 1–28 characters
└ text	string	Limits: 1–60 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Gauges gauge

One to three speedometer-style dials whose needle swings to a value from 0 to 100. Use for scores, levels, progress and ratings.

Narration. Optional lead, then one passage per gauge (items[].say), then optional outro.

Example

{
  "kind": "gauge",
  "heading": "Your daily energy",
  "items": [
    {
      "label": "Morning",
      "value": 85,
      "display": "High",
      "tone": "emerald",
      "say": "Most people feel their sharpest in the morning."
    },
    {
      "label": "Afternoon",
      "value": 35,
      "display": "Low",
      "tone": "amber",
      "say": "Energy dips after lunch."
    },
    {
      "label": "Evening",
      "value": 62,
      "display": "Medium",
      "tone": "sky",
      "say": "And recovers a little in the evening."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 1–3 items
└ labelrequired	string	Limits: 1–48 characters
└ valuerequired	number	Where the needle points: 0 (far left) to 100 (far right). Limits: 0–100
└ display	string	The text under the dial. Default: the value followed by %. Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Rolling counters counter

One to three big numbers that roll up like an odometer to their value. Use for one headline figure or a few key totals (users, revenue, distance).

Narration. Optional lead, then one passage per counter (items[].say), then optional outro.

Example

{
  "kind": "counter",
  "heading": "A year of learning",
  "items": [
    {
      "value": 2450000,
      "label": "learners joined",
      "tone": "violet",
      "say": "Over two million four hundred thousand learners joined us."
    },
    {
      "value": 98.6,
      "decimals": 1,
      "suffix": "%",
      "label": "would recommend",
      "tone": "emerald",
      "say": "Nearly ninety-nine percent would recommend us to a friend."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 1–3 items
└ valuerequired	number	The number to roll up to. Not negative. Limits: 0–1000000000000
└ decimals	integer	Digits after the decimal point. Default 0. Limits: 0–3
└ prefix	string	Before the number, e.g. `$`. Limits: 1–4 characters
└ suffix	string	After the number, e.g. `%`, `k`, `km`. Limits: 1–8 characters
└ labelrequired	string	Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Formula formula

An equation built from labelled blocks: result = term + term × term. Use for formulas in science, finance and maths (speed = distance ÷ time, profit = revenue − costs).

Narration. Optional lead, then the passage of the result (result.say), then one passage per term (terms[].say), then optional outro.

Example

{
  "kind": "formula",
  "heading": "How fast are you going?",
  "result": {
    "symbol": "Speed",
    "label": "km/h",
    "tone": "emerald",
    "say": "To find your speed,"
  },
  "terms": [
    {
      "symbol": "Distance",
      "label": "km",
      "tone": "sky",
      "say": "take the distance you travelled,"
    },
    {
      "symbol": "Time",
      "label": "hours",
      "op": "÷",
      "tone": "amber",
      "say": "and divide it by the time it took."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
resultrequired	object	The left-hand side, e.g. `Speed`.
└ symbolrequired	string	Limits: 1–16 characters
└ label	string	Limits: 1–28 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
termsrequired	object[]	Limits: 2–6 items
└ symbolrequired	string	The block's text, e.g. `Distance` or `m`. Limits: 1–16 characters
└ label	string	Small caption under the block, e.g. `metres`. Limits: 1–28 characters
└ op	string	The sign written before this block, e.g. `+`, `−`, `×`, `÷`. Default `+`. Not used on the first term. Limits: 1–3 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Before and after beforeafter

Two panels side by side: the first shows how things were, then the second wipes in to show how they are now. Use for transformations, results and improvements.

Narration. Optional lead, then before.say, then after.say, then optional outro.

Example

{
  "kind": "beforeafter",
  "heading": "Switching to a morning routine",
  "before": {
    "title": "Snooze, rush, skip breakfast",
    "text": "Stressed and late most days.",
    "icon": "😵",
    "tone": "rose",
    "say": "Before, mornings were a rush of snoozing and skipped breakfasts."
  },
  "after": {
    "title": "Calm start, clear head",
    "text": "Time to think, eat and plan.",
    "icon": "😊",
    "tone": "emerald",
    "say": "After, a calm routine gives you time to eat, think and plan your day."
  }
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
beforerequired	object
└ label	string	Small tag above the title. Default `Before` / `After`. Limits: 1–16 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
afterrequired	object
└ label	string	Small tag above the title. Default `Before` / `After`. Limits: 1–16 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Pricing plans pricing

Two to four plan cards side by side with a name, a price and a few features. Give one plan a badge (for example Most popular) to highlight it.

Narration. Optional lead, then one passage per plan (plans[].say), then optional outro.

Example

{
  "kind": "pricing",
  "heading": "Choose your plan",
  "plans": [
    {
      "name": "Starter",
      "price": "Free",
      "features": [
        "3 videos a month",
        "720p export"
      ],
      "tone": "sky",
      "say": "Starter is free and includes three videos a month."
    },
    {
      "name": "Pro",
      "price": "$19",
      "period": "/month",
      "features": [
        "Unlimited videos",
        "1080p export",
        "Custom branding"
      ],
      "badge": "Most popular",
      "tone": "violet",
      "say": "Pro costs nineteen dollars a month with unlimited videos and your own branding."
    },
    {
      "name": "Team",
      "price": "$49",
      "period": "/month",
      "features": [
        "Everything in Pro",
        "5 seats",
        "Priority support"
      ],
      "tone": "emerald",
      "say": "Team adds five seats and priority support for forty-nine dollars."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
plansrequired	object[]	Limits: 2–4 items
└ namerequired	string	Limits: 1–24 characters
└ pricerequired	string	The price as written, e.g. `$29` or `Free`. Limits: 1–10 characters
└ period	string	Written small after the price, e.g. `/month`. Limits: 1–12 characters
└ featuresrequired	string[]	Limits: 1–4 items, each 1–40 characters
└ badge	string	A ribbon that highlights this plan, e.g. `Most popular`. Limits: 1–16 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Testimonials testimonial

One to three review cards with a star rating, a quote and the person who said it. Use for social proof, reviews and feedback.

Narration. Optional lead, then one passage per testimonial (items[].say), then optional outro.

Example

{
  "kind": "testimonial",
  "heading": "What learners say",
  "items": [
    {
      "quote": "I finally understood compound interest in five minutes.",
      "name": "Maya Patel",
      "role": "Student",
      "rating": 5,
      "tone": "amber",
      "say": "Maya, a student, says she finally understood compound interest in five minutes."
    },
    {
      "quote": "Short, clear and surprisingly fun to watch.",
      "name": "Daniel Okafor",
      "role": "Product manager",
      "rating": 5,
      "tone": "violet",
      "say": "Daniel finds the lessons short, clear and surprisingly fun."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 1–3 items
└ quoterequired	string	Limits: 1–150 characters
└ namerequired	string	Limits: 1–32 characters
└ role	string	Limits: 1–40 characters
└ rating	integer	Stars out of 5. Leave out for no stars. Limits: 1–5
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Chat chat

A messaging conversation: bubbles appear one by one, from the left or the right. Use for dialogues, customer questions, interviews and role play.

Narration. Optional lead, then one passage per message (messages[].say), then optional outro. The narrator can read the message or comment on it.

Example

{
  "kind": "chat",
  "heading": "Asking for a refund",
  "messages": [
    {
      "from": "left",
      "name": "Customer",
      "text": "Hi, my order arrived damaged. Can I get a refund?",
      "say": "A customer writes that their order arrived damaged and asks for a refund."
    },
    {
      "from": "right",
      "name": "Support",
      "text": "I am sorry to hear that! Could you send me a photo?",
      "say": "Support apologises and asks for a photo."
    },
    {
      "from": "left",
      "name": "Customer",
      "text": "Sure, sending it now.",
      "say": "The customer sends it straight away."
    },
    {
      "from": "right",
      "name": "Support",
      "text": "Thanks. Your refund is on its way.",
      "say": "And support confirms that the refund is on its way."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
messagesrequired	object[]	Limits: 2–6 items
└ fromrequired	enum	Which side the bubble is on. `leftright`
└ name	string	Shown above the bubble. Limits: 1–20 characters
└ textrequired	string	Limits: 1–120 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

People team

Two to six people as avatar cards with a name, a role and an optional line. Use to introduce a team, hosts, characters or historical figures.

Narration. Optional lead, then one passage per person (members[].say), then optional outro.

Example

{
  "kind": "team",
  "heading": "Meet the crew",
  "members": [
    {
      "name": "Ada Lovelace",
      "role": "Mathematician",
      "icon": "🧮",
      "text": "Wrote the first program.",
      "tone": "violet",
      "say": "Ada Lovelace wrote what is considered the first computer program."
    },
    {
      "name": "Grace Hopper",
      "role": "Computer scientist",
      "icon": "⚓",
      "text": "Invented the compiler.",
      "tone": "sky",
      "say": "Grace Hopper built the first compiler."
    },
    {
      "name": "Alan Turing",
      "role": "Codebreaker",
      "icon": "🔐",
      "text": "Father of computer science.",
      "tone": "emerald",
      "say": "And Alan Turing laid the foundations of computer science."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
membersrequired	object[]	Limits: 2–6 items
└ namerequired	string	Limits: 1–32 characters
└ rolerequired	string	Limits: 1–40 characters
└ icon	string	The avatar. Default: the first letter of the name. Limits: 1–8 characters
└ text	string	Limits: 1–80 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Questions and answers faq

Two to five questions, each with its answer written beneath it. Use to bust myths, handle objections or end with common questions.

Narration. Optional lead, then one passage per question and answer together (items[].say), then optional outro.

Example

{
  "kind": "faq",
  "heading": "Common questions",
  "items": [
    {
      "question": "Do I need to drink eight glasses of water a day?",
      "answer": "Not exactly. Needs vary, and food and tea count too.",
      "tone": "sky",
      "say": "Do you need eight glasses of water a day? Not exactly: needs vary, and food and tea count too."
    },
    {
      "question": "Is cracking your knuckles harmful?",
      "answer": "Studies have not linked it to arthritis.",
      "tone": "amber",
      "say": "Is cracking your knuckles harmful? Studies have not linked it to arthritis."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–5 items
└ questionrequired	string	Limits: 1–90 characters
└ answerrequired	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Bullet points bullets

A plain list of key points that appear one at a time, each with an optional emoji. Use for takeaways, requirements, tips and anything that is just a list. marker chooses dots (default), numbers, ticks or arrows.

Narration. Optional lead, then one passage per point (items[].say), then optional outro.

Example

{
  "kind": "bullets",
  "heading": "Before you travel",
  "marker": "tick",
  "items": [
    {
      "text": "Check that your **passport** is valid for six months.",
      "tone": "emerald",
      "say": "First, check that your passport is valid for at least six months."
    },
    {
      "text": "Book the first and last night in advance.",
      "tone": "sky",
      "say": "Book your first and last night in advance, and stay flexible in between."
    },
    {
      "text": "Save the **emergency numbers** offline.",
      "tone": "amber",
      "say": "And save the local emergency numbers on your phone, offline."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
marker	enum	What stands before each point. Default `dot`. `dotnumbertickarrow`
itemsrequired	object[]	Limits: 1–8 items
└ textrequired	string	Limits: 1–150 characters
└ icon	string	An emoji shown instead of the marker. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Step by step steps

Two to six numbered steps down a vertical rail that fills as the narrator moves on. Each step has a title, an optional explanation and an optional duration chip. Use for how-tos, recipes, set-up guides and processes.

Narration. Optional lead, then one passage per step (items[].say), then optional outro.

Example

{
  "kind": "steps",
  "heading": "Make a pot of tea",
  "items": [
    {
      "title": "Boil the water",
      "text": "Fresh water, just below a rolling boil.",
      "time": "3 min",
      "tone": "sky",
      "say": "Start by boiling fresh water, then let it settle just below a rolling boil."
    },
    {
      "title": "Add the leaves",
      "text": "One teaspoon per cup.",
      "time": "1 min",
      "tone": "emerald",
      "say": "Add about one teaspoon of leaves per cup to the pot."
    },
    {
      "title": "Steep and serve",
      "text": "Cover, wait, pour.",
      "time": "4 min",
      "tone": "amber",
      "say": "Cover it, wait four minutes, and pour."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–6 items
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ time	string	A short chip such as `5 min` or `Day 1`. Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Schedule schedule

A timetable: two to seven rows, each with a time on the left and a title, a short line and an emoji. Use for itineraries, daily routines, class timetables, event programmes and plans.

Narration. Optional lead, then one passage per row (items[].say), then optional outro.

Example

{
  "kind": "schedule",
  "heading": "A day in Lisbon",
  "items": [
    {
      "time": "09:00",
      "title": "Pastel de nata",
      "text": "Breakfast at a corner café.",
      "icon": "🥐",
      "tone": "amber",
      "say": "Start with a custard tart and coffee at a corner café."
    },
    {
      "time": "11:00",
      "title": "Tram 28",
      "text": "Up and down the old hills.",
      "icon": "🚋",
      "tone": "rose",
      "say": "Ride tram twenty-eight through the old hills."
    },
    {
      "time": "14:00",
      "title": "Seafood lunch",
      "text": "Fresh from the Atlantic.",
      "icon": "🦐",
      "tone": "sky",
      "say": "Have a seafood lunch by the river."
    },
    {
      "time": "19:00",
      "title": "Sunset view",
      "text": "A miradouro with music.",
      "icon": "🌇",
      "tone": "violet",
      "say": "And watch the sunset from a viewpoint with live music."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–7 items
└ timerequired	string	`08:30`, `Mon`, `Week 2`, ... Limits: 1–14 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–90 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Calendar calendar

One month as a calendar grid with up to six marked days and their labels. Use for deadlines, launches, holidays, challenges and plans over time. Needs month (1 to 12) and year; every day must exist in that month.

Narration. Optional lead, then one passage per marked day (events[].say), then optional outro.

Example

{
  "kind": "calendar",
  "heading": "Your first month",
  "month": 3,
  "year": 2027,
  "events": [
    {
      "day": 1,
      "label": "Kick-off",
      "tone": "violet",
      "say": "You kick things off on the first."
    },
    {
      "day": 15,
      "label": "Halfway check",
      "tone": "amber",
      "say": "Halfway through, on the fifteenth, you check your progress."
    },
    {
      "day": 31,
      "label": "Demo day",
      "tone": "emerald",
      "say": "And on the thirty-first you show what you built."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
monthrequired	integer	1 is January. Limits: 1–12
yearrequired	integer	Limits: 1900–2200
weekStart	enum	The first column. Default `monday`. `mondaysunday`
eventsrequired	object[]	Limits: 1–6 items
└ dayrequired	integer	Limits: 1–31
└ labelrequired	string	Limits: 1–36 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Timer timer

A countdown or interval plan: a ring divided into two to six phases (work, rest, bloom, pour...), each an arc as long as its time, with the time of the phase being spoken in the middle and a legend of every phase underneath or beside it. Give the length of each phase in seconds; the clock times are written for you. An optional rounds says how many times the whole cycle repeats, and the total time is worked out. The ring starts empty and its arcs are drawn one by one as the phases are spoken. Use for workouts and intervals, focus and study sessions, breathing exercises, recipes and brewing, and any "do this for this long, then that" plan.

Narration. Optional lead (spoken while the ring is still empty), then one passage per phase in order (phases[].say), then optional outro (spoken with the total on screen).

Example

{
  "kind": "timer",
  "heading": "A four-minute interval workout",
  "phases": [
    {
      "label": "Work",
      "seconds": 20,
      "icon": "🔥",
      "tone": "rose",
      "say": "Work as hard as you can for twenty seconds."
    },
    {
      "label": "Rest",
      "seconds": 10,
      "icon": "😮‍💨",
      "tone": "sky",
      "say": "Then rest for ten seconds and catch your breath."
    }
  ],
  "rounds": 8,
  "lead": "Here is a workout that fits into a coffee break.",
  "outro": "Eight rounds, and you are done in four minutes."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
phasesrequired	object[]	Limits: 2–6 items
└ labelrequired	string	Limits: 1–20 characters
└ secondsrequired	integer	How long the phase lasts, in seconds (up to an hour). Limits: 1–3600
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
rounds	integer	How many times the whole cycle of phases repeats. Default 1: shown only when more than 1. Limits: 1–60
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Columns columns

Two or three titled columns, each with a short list. Use to sort things into groups: do and don't, pros and cons, ingredients and method, before the trip and after. A column appears with all of its lines.

Narration. Optional lead, then one passage per column (columns[].say), then optional outro.

Example

{
  "kind": "columns",
  "heading": "Recycling at home",
  "columns": [
    {
      "title": "Yes please",
      "icon": "✅",
      "tone": "emerald",
      "items": [
        "Clean paper",
        "Rinsed cans",
        "Glass jars"
      ],
      "say": "Clean paper, rinsed cans and glass jars all belong in the recycling bin."
    },
    {
      "title": "Never",
      "icon": "🚫",
      "tone": "rose",
      "items": [
        "Greasy pizza box",
        "Plastic bags",
        "Broken mirrors"
      ],
      "say": "Greasy boxes, plastic bags and broken mirrors do not."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
columnsrequired	object[]	Limits: 2–3 items
└ titlerequired	string	Limits: 1–32 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour of the column. `emerald` suits a good list, `rose` a bad one. `violetemeraldamberroseskyfuchsiatealorange`
└ itemsrequired	string[]	Limits: 1–5 items, each 1–60 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Comparison grid compare

Two to four options side by side, compared feature by feature. A cell says yes, no or partial (drawn as a tick, a cross or a half circle) or holds a few words. highlight marks the recommended option. Every row needs one value per column.

Narration. Optional lead, then one passage per row (rows[].say), then optional outro.

Example

{
  "kind": "compare",
  "heading": "Which plan fits you?",
  "columns": [
    "Free",
    "Plus",
    "Team"
  ],
  "highlight": 1,
  "rows": [
    {
      "feature": "Projects",
      "values": [
        "3",
        "Unlimited",
        "Unlimited"
      ],
      "say": "The free plan has three projects, the others have no limit."
    },
    {
      "feature": "Offline mode",
      "values": [
        "no",
        "yes",
        "yes"
      ],
      "say": "Offline mode starts with Plus."
    },
    {
      "feature": "Shared folders",
      "values": [
        "no",
        "partial",
        "yes"
      ],
      "say": "Shared folders are limited on Plus and complete on Team."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
columnsrequired	string[]	The names of the options. Limits: 2–4 items, each 1–24 characters
highlight	integer	Index (from 0) of the option to emphasise. Limits: 0–3
rowsrequired	object[]	Limits: 2–6 items
└ featurerequired	string	Limits: 1–40 characters
└ valuesrequired	string[]	One per column: `yes`, `no`, `partial` or a few words. Limits: 2–4 items, each 1–28 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Flashcards flashcards

Two to six cards that show a question and then flip over to reveal the answer. Use for revision, vocabulary, riddles and quick checks. Each card is narrated twice: the question (say), then the answer (sayAnswer).

Narration. Optional lead, then for every card the question (cards[].say) followed by the answer (cards[].sayAnswer), then optional outro.

Example

{
  "kind": "flashcards",
  "heading": "Spanish basics",
  "cards": [
    {
      "question": "How do you say “thank you”?",
      "answer": "Gracias",
      "icon": "🙏",
      "tone": "amber",
      "say": "How do you say thank you in Spanish?",
      "sayAnswer": "Gracias."
    },
    {
      "question": "What does “buenos días” mean?",
      "answer": "Good morning",
      "icon": "🌅",
      "tone": "sky",
      "say": "And what does buenos días mean?",
      "sayAnswer": "It means good morning."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
cardsrequired	object[]	Limits: 2–6 items
└ questionrequired	string	Limits: 1–90 characters
└ answerrequired	string	Limits: 1–90 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	Narration while the question is showing. Limits: 1–500 characters
└ sayAnswerrequired	string	Narration while the answer is showing. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Waffle chart waffle

A 10 by 10 grid of dots where a share of them lights up, so "27%" can be seen as 27 out of 100. One to three grids side by side. Use for proportions, surveys and "1 in 4" statements.

Narration. Optional lead, then one passage per grid (items[].say), then optional outro.

Example

{
  "kind": "waffle",
  "heading": "Where the water goes",
  "items": [
    {
      "value": 70,
      "label": "of the Earth is covered by water",
      "tone": "sky",
      "say": "About seventy percent of the Earth is covered by water."
    },
    {
      "value": 3,
      "label": "of that water is fresh",
      "tone": "emerald",
      "say": "But only three percent of it is fresh."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
shape	enum	The marks of the grid. Default `circle`. `circlesquare`
itemsrequired	object[]	Limits: 1–3 items
└ valuerequired	integer	How many of the 100 marks light up. Limits: 0–100
└ labelrequired	string	Limits: 1–60 characters
└ display	string	The big number. Default: the value with a percent sign. Limits: 1–10 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Profile profile

The spotlight on one person, product, place or organisation: a big avatar card with a name, a role and an optional quote, and two to five key facts that appear beside it. Use lead to introduce the subject before the facts.

Narration. Optional lead (the introduction, spoken while only the card shows), then one passage per fact (facts[].say), then optional outro.

Example

{
  "kind": "profile",
  "heading": "Meet Marie Curie",
  "name": "Marie Curie",
  "role": "Physicist and chemist",
  "icon": "🔬",
  "quote": "Nothing in life is to be feared, it is only to be understood.",
  "facts": [
    {
      "label": "Born",
      "value": "Warsaw, 1867",
      "tone": "sky",
      "say": "She was born in Warsaw in eighteen sixty-seven."
    },
    {
      "label": "Discovered",
      "value": "Polonium and radium",
      "tone": "amber",
      "say": "She discovered two elements, polonium and radium."
    },
    {
      "label": "Awards",
      "value": "Two Nobel Prizes",
      "tone": "emerald",
      "say": "And she won two Nobel Prizes, in physics and in chemistry."
    }
  ],
  "lead": "Few scientists changed the world as much as Marie Curie."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
namerequired	string	Limits: 1–40 characters
role	string	Limits: 1–48 characters
icon	string	The avatar: an emoji. Default: the first letter of the name. Limits: 1–8 characters
quote	string	A line shown under the name. Limits: 1–120 characters
factsrequired	object[]	Limits: 2–5 items
└ labelrequired	string	Limits: 1–24 characters
└ valuerequired	string	Limits: 1–40 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

One to three social media style posts with an avatar, a name and handle, the text and the counts of likes, comments and shares. Use for news, reactions, campaigns and to show what people are saying. Generic look, no brand logos.

Narration. Optional lead, then one passage per post (posts[].say), then optional outro.

Example

{
  "kind": "social",
  "heading": "What people are saying",
  "posts": [
    {
      "name": "Lena Ortiz",
      "handle": "lena.makes",
      "avatar": "🧵",
      "text": "Three weeks of daily sketching and my lines are already steadier. Highly recommend the habit.",
      "time": "2h",
      "verified": true,
      "likes": "1.2k",
      "comments": "84",
      "shares": "210",
      "tone": "fuchsia",
      "say": "Lena shares that after three weeks of daily sketching her lines are already steadier."
    },
    {
      "name": "Sam Baker",
      "handle": "sambakes",
      "avatar": "🥖",
      "text": "Day 12: the sourdough finally rose. Tiny wins count.",
      "time": "5h",
      "likes": "860",
      "comments": "41",
      "shares": "95",
      "tone": "amber",
      "say": "Sam celebrates a sourdough that finally rose, and says tiny wins count."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
postsrequired	object[]	Limits: 1–3 items
└ namerequired	string	Limits: 1–32 characters
└ handlerequired	string	Without the @, it is added. Limits: 1–24 characters
└ avatar	string	An emoji. Default: the first letter of the name. Limits: 1–8 characters
└ textrequired	string	Limits: 1–180 characters
└ time	string	`2h`, `Mar 4`, ... Limits: 1–16 characters
└ verified	boolean	Adds a small tick to the name.
└ likes	string	Limits: 1–10 characters
└ comments	string	Limits: 1–10 characters
└ shares	string	Limits: 1–10 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

News headline headline

A news-bulletin look: a label ("Breaking", "Live", "Update"), a big headline, a standfirst and up to four ticker lines that slide in along the bottom. Use for news, announcements and updates. say is spoken while the headline shows.

Narration. say is the headline and standfirst. Then one passage per ticker line (ticker[].say).

Example

{
  "kind": "headline",
  "label": "Breaking",
  "title": "City opens 40 kilometres of new bike lanes",
  "deck": "The network links every district to the centre and is ready to use from Monday.",
  "source": "City Desk · 18:30",
  "ticker": [
    {
      "text": "Cyclists can use the lanes free of charge",
      "say": "The lanes are free to use for everyone."
    },
    {
      "text": "A second phase is planned for next spring",
      "say": "A second phase is planned for next spring."
    }
  ],
  "say": "Breaking news: the city has opened forty kilometres of new bike lanes, linking every district to the centre."
}

Field	Type	What it does
label	string	The red tag. Default `Breaking`. Limits: 1–24 characters
titlerequired	string	Limits: 1–100 characters
deck	string	The standfirst under the headline. Limits: 1–160 characters
source	string	Shown small, for example `City Desk · 18:30`. Limits: 1–40 characters
ticker	object[]	Limits: up to 4 items
└ textrequired	string	Limits: 1–80 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Storyboard storyboard

Two to four comic-strip panels: a big emoji scene, a caption and an optional speech bubble. Use for stories, fables, examples with characters and step-by-step situations. Kid friendly.

Narration. Optional lead, then one passage per panel (panels[].say), then optional outro.

Example

{
  "kind": "storyboard",
  "heading": "The tortoise and the hare",
  "panels": [
    {
      "icon": "🐇🐢",
      "caption": "A hare boasts about his speed.",
      "bubble": "Nobody can beat me!",
      "tone": "amber",
      "say": "A hare boasted that nobody could beat him in a race."
    },
    {
      "icon": "🏁",
      "caption": "The tortoise accepts the challenge.",
      "bubble": "Let's see.",
      "tone": "emerald",
      "say": "A quiet tortoise accepted the challenge."
    },
    {
      "icon": "😴",
      "caption": "The hare naps by the road.",
      "tone": "sky",
      "say": "Far ahead, the hare took a nap by the road."
    },
    {
      "icon": "🏆",
      "caption": "Slow and steady wins.",
      "tone": "violet",
      "say": "And the tortoise crossed the line first. Slow and steady wins the race."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
panelsrequired	object[]	Limits: 2–4 items
└ iconrequired	string	The picture of the panel: one to three emoji. Limits: 1–12 characters
└ captionrequired	string	Limits: 1–90 characters
└ bubble	string	Words a character says. Limits: 1–60 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Tree diagram tree

A hierarchy: one root on top, two to four branches below it, and up to three short items under each branch. Use for organisation charts, categories, taxonomies, decision breakdowns and family trees. The root is always visible.

Narration. Optional lead (about the root), then one passage per branch (branches[].say), then optional outro.

Example

{
  "kind": "tree",
  "heading": "How a company is organised",
  "root": {
    "title": "CEO",
    "icon": "👩‍💼",
    "text": "Sets the direction"
  },
  "branches": [
    {
      "title": "Product",
      "icon": "🛠️",
      "tone": "violet",
      "children": [
        "Design",
        "Engineering"
      ],
      "say": "Product builds what customers use, from design to engineering."
    },
    {
      "title": "Sales",
      "icon": "🤝",
      "tone": "amber",
      "children": [
        "Accounts",
        "Partners"
      ],
      "say": "Sales finds customers and keeps partners close."
    },
    {
      "title": "Operations",
      "icon": "📦",
      "tone": "emerald",
      "children": [
        "Finance",
        "People"
      ],
      "say": "Operations keeps the company running, with finance and people."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
rootrequired	object
└ titlerequired	string	Limits: 1–40 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ text	string	Limits: 1–60 characters
branchesrequired	object[]	Limits: 2–4 items
└ titlerequired	string	Limits: 1–32 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ children	string[]	Short labels under the branch. Limits: up to 3 items, each 1–32 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Receipt receipt

An itemised receipt or invoice printed on paper: two to seven lines with a name, an optional quantity and an amount, and a total at the bottom. Use for budgets, bills, shopping, costs and "where does the money go". Amounts are written as text, so any currency works.

Narration. Optional lead, then one passage per line (lines[].say), then one for the total (total.say), then optional outro.

Example

{
  "kind": "receipt",
  "heading": "Where a coffee's price goes",
  "paper": "Corner Café · Order 1042",
  "lines": [
    {
      "label": "Espresso beans",
      "qty": "18 g",
      "amount": "$0.45",
      "tone": "amber",
      "say": "Eighteen grams of beans cost forty-five cents."
    },
    {
      "label": "Milk",
      "qty": "150 ml",
      "amount": "$0.30",
      "tone": "sky",
      "say": "The milk adds thirty cents."
    },
    {
      "label": "Rent and staff",
      "amount": "$2.60",
      "tone": "rose",
      "say": "But rent and staff are the biggest slice, two dollars sixty."
    },
    {
      "label": "Profit",
      "amount": "$0.65",
      "tone": "emerald",
      "say": "What is left for the café is sixty-five cents."
    }
  ],
  "total": {
    "amount": "$4.00",
    "say": "Together, that is the four dollars you pay."
  },
  "note": "Thank you, see you tomorrow!"
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
paper	string	The title printed at the top of the paper, for example the shop. Default: none. Limits: 1–40 characters
linesrequired	object[]	Limits: 2–7 items
└ labelrequired	string	Limits: 1–36 characters
└ qty	string	`2x`, `1 kg`, ... Limits: 1–8 characters
└ amountrequired	string	Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
totalrequired	object
└ label	string	Default `Total`. Limits: 1–16 characters
└ amountrequired	string	Limits: 1–14 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
note	string	A line printed under the total, for example `Thank you!`. Limits: 1–60 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Checklist checklist

A checklist on a card: two to eight rows with a tick box that gets ticked as each one is spoken, an optional emoji and an optional small detail. Use for packing lists, ingredients, requirements, safety checks and to-dos.

Narration. Optional lead, then one passage per row (items[].say), then optional outro. A row is ticked while it is spoken.

Example

{
  "kind": "checklist",
  "heading": "Packing for a weekend hike",
  "items": [
    {
      "label": "Water",
      "detail": "2 litres",
      "icon": "💧",
      "tone": "sky",
      "say": "Start with two litres of water."
    },
    {
      "label": "Snacks",
      "detail": "Nuts, fruit",
      "icon": "🥜",
      "tone": "amber",
      "say": "Pack snacks like nuts and fruit."
    },
    {
      "label": "First aid kit",
      "icon": "🩹",
      "tone": "rose",
      "say": "Always bring a small first aid kit."
    },
    {
      "label": "Rain jacket",
      "icon": "🧥",
      "tone": "teal",
      "say": "A light rain jacket weighs almost nothing."
    },
    {
      "label": "Phone and map",
      "icon": "🗺️",
      "tone": "violet",
      "say": "And a charged phone with an offline map."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–8 items
└ labelrequired	string	Limits: 1–40 characters
└ detail	string	A small note on the right, such as an amount. Limits: 1–28 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Keyboard shortcuts shortcuts

Two to six keyboard shortcuts: each shows its keys as key caps (one to four, such as Ctrl and C) and what the shortcut does. Use for software tutorials, productivity tips, games and controls.

Narration. Optional lead, then one passage per shortcut (items[].say), then optional outro.

Example

{
  "kind": "shortcuts",
  "heading": "Four shortcuts that save hours",
  "items": [
    {
      "keys": [
        "Ctrl",
        "C"
      ],
      "action": "Copy",
      "tone": "sky",
      "say": "Control and C copies what you selected."
    },
    {
      "keys": [
        "Ctrl",
        "V"
      ],
      "action": "Paste",
      "tone": "emerald",
      "say": "Control and V pastes it somewhere else."
    },
    {
      "keys": [
        "Ctrl",
        "Z"
      ],
      "action": "Undo",
      "tone": "amber",
      "say": "Control and Z undoes your last mistake."
    },
    {
      "keys": [
        "Ctrl",
        "Shift",
        "T"
      ],
      "action": "Reopen a closed tab",
      "tone": "violet",
      "say": "And control, shift and T brings back the tab you just closed."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
itemsrequired	object[]	Limits: 2–6 items
└ keysrequired	string[]	The keys to press together, in order: `["Ctrl", "C"]`. Limits: 1–4 items, each 1–10 characters
└ actionrequired	string	Limits: 1–40 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Email email

An email message on screen: the sender, the recipient, a subject and one to four paragraphs, with optional attachment chips. The header is always visible; the paragraphs appear one by one and bold words are highlighted. Use for business updates, customer messages, newsletters and spotting scams.

Narration. Optional lead (spoken while only the header shows), then one passage per paragraph (body[].say), then optional outro.

Example

{
  "kind": "email",
  "heading": "Spot the scam email",
  "from": "Support <help@secure-bank-login.example>",
  "to": "you@example.com",
  "subject": "Urgent: your account will be closed",
  "time": "09:41",
  "body": [
    {
      "text": "Dear customer, we noticed **unusual activity** on your account.",
      "say": "A scam email often opens with a vague greeting and talks about unusual activity."
    },
    {
      "text": "Click the link below within **24 hours** or your account will be closed.",
      "say": "Then it creates pressure with a short deadline."
    },
    {
      "text": "https://secure-bank-login.example/verify",
      "say": "And the link leads to a website that is not your bank."
    }
  ],
  "attachments": [
    "verify-now.zip"
  ],
  "lead": "Read this message carefully before you click anything.",
  "outro": "When in doubt, open your bank's own app instead."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
fromrequired	string	The sender, a name or an address. Limits: 1–48 characters
torequired	string	The recipient. Limits: 1–48 characters
subjectrequired	string	Limits: 1–90 characters
time	string	`09:41`, `Mon`, ... Limits: 1–16 characters
bodyrequired	object[]	Limits: 1–4 items
└ textrequired	string	Limits: 1–220 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
attachments	string[]	File names shown as chips under the message. Limits: up to 3 items, each 1–32 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Search results search

A web search page: a query in the search bar and one to four results, each with a title, a site address and a snippet. The search bar is always visible; the results appear one by one. Use to show how to look something up, compare sources, explain search ranking or research.

Narration. Optional lead (spoken while only the search bar shows), then one passage per result (results[].say), then optional outro.

Example

{
  "kind": "search",
  "heading": "Which result can you trust?",
  "query": "is it safe to drink tap water",
  "count": "About 18 million results",
  "results": [
    {
      "title": "Drinking water quality: official guidance",
      "site": "health.gov.example",
      "snippet": "How public water is tested, what the limits are and when to boil water before drinking.",
      "tone": "emerald",
      "say": "The first result is an official health site, which explains how tap water is tested."
    },
    {
      "title": "Top 10 water filters you must buy now",
      "site": "best-filters.example",
      "snippet": "Our readers love these filters. Click to see the lowest prices today.",
      "tone": "amber",
      "say": "The second one is selling filters, so it may not be neutral."
    },
    {
      "title": "Is your tap water poisoning you?",
      "site": "scary-news.example",
      "snippet": "Shocking secrets they do not want you to know about what comes out of your tap.",
      "tone": "rose",
      "say": "And the third uses a scary headline to get clicks."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
queryrequired	string	Limits: 1–60 characters
count	string	The line under the bar, for example `About 2.4 million results`. Limits: 1–32 characters
resultsrequired	object[]	Limits: 1–4 items
└ titlerequired	string	Limits: 1–60 characters
└ siterequired	string	Limits: 1–40 characters
└ snippetrequired	string	Limits: 1–140 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Ticket ticket

A boarding pass or event ticket: where it starts and where it goes (a short code and a city each), an optional carrier, and two to six details such as date, gate and seat that appear one by one. Use for travel, events, bookings and journeys.

Narration. Optional lead (spoken while only the route shows), then one passage per detail (fields[].say), then optional outro.

Example

{
  "kind": "ticket",
  "heading": "Reading your boarding pass",
  "carrier": "SkyWays · SW 214",
  "from": {
    "code": "LIS",
    "city": "Lisbon"
  },
  "to": {
    "code": "AMS",
    "city": "Amsterdam"
  },
  "fields": [
    {
      "label": "Date",
      "value": "14 Mar",
      "tone": "sky",
      "say": "First, check the date of your flight."
    },
    {
      "label": "Gate",
      "value": "B12",
      "tone": "amber",
      "say": "The gate tells you where to wait."
    },
    {
      "label": "Boarding",
      "value": "09:25",
      "tone": "rose",
      "say": "Boarding closes at nine twenty-five, so be there early."
    },
    {
      "label": "Seat",
      "value": "17A",
      "tone": "emerald",
      "say": "And the seat is by the window."
    }
  ],
  "lead": "A boarding pass holds everything you need on one small card."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
carrier	string	The airline, the event or the company, shown on the top of the ticket. Limits: 1–32 characters
fromrequired	object
└ coderequired	string	Limits: 1–5 characters
└ cityrequired	string	Limits: 1–24 characters
torequired	object
└ coderequired	string	Limits: 1–5 characters
└ cityrequired	string	Limits: 1–24 characters
fieldsrequired	object[]	Limits: 2–6 items
└ labelrequired	string	Limits: 1–16 characters
└ valuerequired	string	Limits: 1–24 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Podium podium

A winners' podium with exactly three places: blocks of different heights (gold in the middle, silver on the left, bronze on the right), each with a name, an optional emoji and an optional score. List the places from first to third; they appear from third place up to the winner. Use for top three, awards, contests and results.

Narration. Optional lead, then one passage per place in the order they appear: third place first, the winner last (places[].say), then optional outro.

Example

{
  "kind": "podium",
  "heading": "The fastest animals on land",
  "places": [
    {
      "name": "Cheetah",
      "icon": "🐆",
      "score": "110 km/h",
      "say": "The winner is the cheetah, which sprints at one hundred and ten kilometres an hour."
    },
    {
      "name": "Pronghorn",
      "icon": "🦌",
      "score": "88 km/h",
      "say": "Second comes the pronghorn, which keeps its speed for much longer."
    },
    {
      "name": "Springbok",
      "icon": "🐐",
      "score": "88 km/h",
      "say": "Third is the springbok, famous for its high jumps."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
placesrequired	object[]	First, second and third place, in that order. Limits: exactly 3 items
└ namerequired	string	Limits: 1–28 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ score	string	Limits: 1–14 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Scoreboard scoreboard

A match scoreboard: two sides with a name, an optional emoji and a big score, an optional status line (Full time, Round 2), and one to five key moments listed underneath. The scores are visible from the start; the moments appear one by one. Use for sports, games, contests and any head-to-head result.

Narration. Optional lead (spoken while only the scores show), then one passage per moment (moments[].say), then optional outro.

Example

{
  "kind": "scoreboard",
  "heading": "The school cup final",
  "home": {
    "name": "Green Hawks",
    "icon": "🦅",
    "score": "3"
  },
  "away": {
    "name": "Blue Sharks",
    "icon": "🦈",
    "score": "2"
  },
  "status": "Full time",
  "moments": [
    {
      "time": "12'",
      "text": "Hawks score first",
      "side": "home",
      "say": "The Hawks scored first, after twelve minutes."
    },
    {
      "time": "40'",
      "text": "Sharks equalise",
      "side": "away",
      "say": "The Sharks hit back just before the break."
    },
    {
      "time": "88'",
      "text": "Winner for the Hawks",
      "side": "home",
      "say": "And in the eighty-eighth minute the Hawks scored the winner."
    }
  ],
  "lead": "What a final. Let's see how it ended."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
homerequired	object
└ namerequired	string	Limits: 1–24 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ scorerequired	string	Limits: 1–6 characters
awayrequired	object
└ namerequired	string	Limits: 1–24 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ scorerequired	string	Limits: 1–6 characters
status	string	Limits: 1–24 characters
momentsrequired	object[]	Limits: 1–5 items
└ timerequired	string	Limits: 1–8 characters
└ textrequired	string	Limits: 1–60 characters
└ side	enum	Which side the moment belongs to. Default: neither. `homeaway`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Bracket bracket

A knockout tournament bracket: two or three rounds drawn as columns of matches, each match with two sides (a name and an optional score) and its winner highlighted, flowing from the first round to the final and the champion. Each round has half the matches of the one before: two rounds are 2 matches then the final; three rounds are 4, 2 and the final. Leave out winner for matches that have not been played. The rounds appear one by one, the empty bracket first. Use for tournaments, cups and playoffs, esports, elimination contests and any "who beats whom" story; for a bigger tournament show only its last rounds.

Narration. Optional lead (spoken while the empty bracket shows), then one passage per round from the first round to the final (rounds[].say), then optional outro.

Example

{
  "kind": "bracket",
  "heading": "The school cup, round by round",
  "rounds": [
    {
      "name": "Quarter-finals",
      "matches": [
        {
          "a": {
            "name": "Hawks",
            "score": "3"
          },
          "b": {
            "name": "Wolves",
            "score": "1"
          },
          "winner": "a"
        },
        {
          "a": {
            "name": "Sharks",
            "score": "2"
          },
          "b": {
            "name": "Lions",
            "score": "0"
          },
          "winner": "a"
        },
        {
          "a": {
            "name": "Eagles",
            "score": "1"
          },
          "b": {
            "name": "Bears",
            "score": "2"
          },
          "winner": "b"
        },
        {
          "a": {
            "name": "Tigers",
            "score": "0"
          },
          "b": {
            "name": "Foxes",
            "score": "1"
          },
          "winner": "b"
        }
      ],
      "say": "Eight teams started the cup, and four of them went home after the quarter-finals."
    },
    {
      "name": "Semi-finals",
      "matches": [
        {
          "a": {
            "name": "Hawks",
            "score": "2"
          },
          "b": {
            "name": "Sharks",
            "score": "1"
          },
          "winner": "a"
        },
        {
          "a": {
            "name": "Bears",
            "score": "0"
          },
          "b": {
            "name": "Foxes",
            "score": "1"
          },
          "winner": "b"
        }
      ],
      "say": "In the semi-finals the Hawks beat the Sharks, and the Foxes surprised the Bears."
    },
    {
      "name": "Final",
      "matches": [
        {
          "a": {
            "name": "Hawks",
            "score": "3"
          },
          "b": {
            "name": "Foxes",
            "score": "2"
          },
          "winner": "a"
        }
      ],
      "say": "And in the final the Hawks beat the Foxes by three goals to two."
    }
  ],
  "lead": "Here is how the school cup was won."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
roundsrequired	object[]	The rounds from the first to the final. The winner of a match plays on in the next round: matches 1 and 2 feed match 1 there, matches 3 and 4 feed match 2. Limits: 2–3 items
└ namerequired	string	Limits: 1–20 characters
└ matchesrequired	object[]	Limits: 1–4 items
└ arequired	object
└ namerequired	string	Limits: 1–14 characters
└ score	string	Limits: 1–4 characters
└ brequired	object
└ namerequired	string	Limits: 1–14 characters
└ score	string	Limits: 1–4 characters
└ winner	enum	Which side won, `a` or `b`. Leave out for a match that has not been played yet. `ab`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Rating rating

A review summary: a big score out of five with stars and the number of reviews, and two to five aspects, each with its own score drawn as a bar. The overall score is visible from the start; the aspects appear one by one. Use for product reviews, satisfaction, reputation and "how good is it".

Narration. Optional lead (spoken while only the overall score shows), then one passage per aspect (aspects[].say), then optional outro.

Example

{
  "kind": "rating",
  "heading": "Trailmate backpack reviews",
  "score": 4.6,
  "reviews": "2,314 reviews",
  "aspects": [
    {
      "label": "Comfort",
      "value": 4.8,
      "tone": "emerald",
      "say": "Comfort gets the best score, four point eight."
    },
    {
      "label": "Durability",
      "value": 4.5,
      "tone": "sky",
      "say": "Durability follows with four and a half."
    },
    {
      "label": "Value for money",
      "value": 3.9,
      "tone": "amber",
      "say": "Value for money scores lowest, because it is not cheap."
    }
  ],
  "lead": "Thousands of hikers rated this backpack."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
scorerequired	number	The overall score from 0 to 5; halves are drawn as half stars. Limits: 0–5
reviews	string	`2,314 reviews`. Limits: 1–24 characters
aspectsrequired	object[]	Limits: 2–5 items
└ labelrequired	string	Limits: 1–28 characters
└ valuerequired	number	From 0 to 5. Limits: 0–5
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Forecast forecast

A multi-day weather forecast: two to five columns, each with a day name, a weather emoji, a high and an optional low temperature and an optional short note. Use for weather, trips, outdoor events, seasons and any "what is coming" row.

Narration. Optional lead, then one passage per day (days[].say), then optional outro.

Example

{
  "kind": "forecast",
  "heading": "Your long weekend in Lisbon",
  "place": "Lisbon, Portugal",
  "days": [
    {
      "day": "Friday",
      "icon": "☀️",
      "high": "24°",
      "low": "15°",
      "note": "Clear skies",
      "tone": "amber",
      "say": "Friday is sunny and warm, a perfect day to explore the old town."
    },
    {
      "day": "Saturday",
      "icon": "⛅",
      "high": "22°",
      "low": "14°",
      "note": "Some clouds",
      "tone": "sky",
      "say": "Saturday brings a few clouds but stays dry."
    },
    {
      "day": "Sunday",
      "icon": "🌧️",
      "high": "18°",
      "low": "13°",
      "note": "Rain at noon",
      "tone": "violet",
      "say": "On Sunday rain arrives around noon, so plan a museum visit."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
place	string	The place, shown above the days. Limits: 1–32 characters
daysrequired	object[]	Limits: 2–5 items
└ dayrequired	string	Limits: 1–12 characters
└ iconrequired	string	A weather emoji such as ☀️ or 🌧️. Limits: 1–8 characters
└ highrequired	string	Limits: 1–8 characters
└ low	string	Limits: 1–8 characters
└ note	string	Limits: 1–32 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Playlist playlist

A playlist or course outline: two to six rows with a play button, a title and a length. The row being spoken is highlighted as "now playing" and the ones before it are marked as done. Use for courses and lessons, podcast episodes, albums, chapters and watch lists.

Narration. Optional lead, then one passage per row (items[].say), then optional outro.

Example

{
  "kind": "playlist",
  "heading": "Learn photography in four lessons",
  "label": "Course · 4 lessons",
  "items": [
    {
      "title": "1. How a camera sees",
      "length": "8:20",
      "say": "Lesson one explains how a camera turns light into a picture."
    },
    {
      "title": "2. Light and shadow",
      "length": "11:05",
      "say": "Lesson two is about using light and shadow."
    },
    {
      "title": "3. Composition",
      "length": "9:40",
      "say": "Lesson three teaches composition, so every photo has a clear subject."
    },
    {
      "title": "4. Editing basics",
      "length": "14:15",
      "say": "And lesson four shows how to edit your best shots."
    }
  ]
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
label	string	A small title above the rows, for example `Course · 4 lessons`. Limits: 1–32 characters
itemsrequired	object[]	Limits: 2–6 items
└ titlerequired	string	Limits: 1–48 characters
└ lengthrequired	string	`12:30`, `45 min`, ... Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Decision decision

A decision path: a question at the top that stays visible, and two or three answers below it, each with an arrow to an outcome. Use for "should I...", troubleshooting, eligibility, rules of thumb and choosing between options.

Narration. Optional lead (the question, spoken while only it shows), then one passage per answer (options[].say), then optional outro.

Example

{
  "kind": "decision",
  "heading": "Should you buy it now?",
  "question": "Is it something you will use every week?",
  "options": [
    {
      "answer": "Yes",
      "outcome": "Buy it: the cost per use will be tiny.",
      "icon": "✅",
      "tone": "emerald",
      "say": "If you will use it every week, buy it, because the cost per use will be tiny."
    },
    {
      "answer": "Not sure",
      "outcome": "Wait thirty days, then decide.",
      "icon": "⏳",
      "tone": "amber",
      "say": "If you are not sure, wait thirty days and decide again."
    },
    {
      "answer": "No",
      "outcome": "Skip it and keep the money.",
      "icon": "🚫",
      "tone": "rose",
      "say": "And if the answer is no, skip it and keep the money."
    }
  ],
  "lead": "Before a big purchase, ask yourself one question."
}

Field	Type	What it does
headingrequired	string	Scene heading shown at the top. Limits: 1–60 characters
questionrequired	string	Limits: 1–90 characters
optionsrequired	object[]	Limits: 2–3 items
└ answerrequired	string	Limits: 1–24 characters
└ outcomerequired	string	Limits: 1–70 characters
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Product hero hero

The product on a stage: its picture (ideally with a transparent background) floats in a pool of light or on a pedestal, with the name, a one-line promise, an optional badge such as New or -30%, and a price. The opening reveal of a product ad. Use image with mode backdrop for a lifestyle photo behind it.

Narration. One to three say lines. The first shows the picture and the name, the second the tagline, the third the badge and price. With fewer lines, the rest follows a moment later.

Example

{
  "kind": "hero",
  "picture": "/examples/ads-aurora-headphones/product.webp",
  "name": "Aurora One",
  "tagline": "Wireless headphones that disappear.",
  "badge": "New",
  "price": {
    "now": "$249",
    "was": "$299"
  },
  "stage": "spotlight",
  "say": [
    "Meet Aurora One.",
    "Wireless headphones that disappear the moment you put them on.",
    "Launching today at two hundred forty nine dollars."
  ]
}

Field	Type	What it does
picturerequired	string	The product picture. A cut-out with a transparent background looks best.
namerequired	string	The product name. Limits: 1–32 characters
tagline	string	One line that says what it does or why it matters. Limits: 1–80 characters
badge	string	A small label: `New`, `Best seller`, `-30%`. Limits: 1–16 characters
price	object
└ nowrequired	string	The price to pay, as written: `$49`, `€9.90`, `From $9`. Limits: 1–14 characters
└ was	string	The old price, shown struck through. Limits: 1–14 characters
└ period	string	What the price covers: `/month`, `per box`. Limits: 1–12 characters
stage	enum	The setting. `spotlight` (default) a pool of light, `pedestal` a round plinth, `orbit` rings circling the product, `burst` rays, for a sale, `reveal` the product comes out of the dark as a band of light sweeps across it and it stands on a glowing, reflective floor (the drop of a launch ad), `depth` the name in giant letters behind the product, which stands in front of it. `spotlightpedestalorbitburstrevealdepth`
motion	enum	How the product moves. Default `float`; `reveal` and `depth` keep the product still unless you ask. `floatswayturnpulsestill`
side	enum	Which side the product is on in a wide frame. Default `right`. `leftright`
sayrequired	string[]	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–3 items, each 1–500 characters

Feature hotspots hotspots

A product picture with pulsing pins on the parts that matter. Each pin opens a label with a title and a line of detail while it is narrated. Use for physical products, packaging and interfaces: the viewer sees where each feature is. Set each at area on the picture in the editor.

Narration. Optional lead, then one passage per point (points[].say), then optional outro.

Example

{
  "kind": "hotspots",
  "heading": "Made to be worn all day",
  "picture": "/examples/ads-aurora-headphones/product.webp",
  "points": [
    {
      "at": {
        "x": 52,
        "y": 52,
        "width": 40,
        "height": 38
      },
      "title": "Memory-foam cushions",
      "text": "Soft enough to forget.",
      "say": "Memory foam cushions stay comfortable for hours."
    },
    {
      "at": {
        "x": 30,
        "y": 3,
        "width": 32,
        "height": 14
      },
      "title": "Featherweight band",
      "text": "Only 220 grams.",
      "say": "A featherweight band keeps the whole thing at two hundred twenty grams."
    },
    {
      "at": {
        "x": 8,
        "y": 70,
        "width": 28,
        "height": 24
      },
      "title": "Touch controls",
      "say": "And touch controls sit right under your thumb."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
picturerequired	string	The product picture the pins sit on.
pointsrequired	object[]	Limits: 2–5 items
└ atrequired	object	The part of the picture the pin marks. The pin sits in the middle of this area.
└ xrequired	number	Distance from the left edge of the picture, as a percentage of its width. Limits: 0–100
└ yrequired	number	Distance from the top edge of the picture, as a percentage of its height. Limits: 0–100
└ widthrequired	number	Width of the area, as a percentage of the picture width. Limits: 0–100
└ heightrequired	number	Height of the area, as a percentage of the picture height. Limits: 0–100
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–150 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Device mockup device

A screenshot shown on a phone, tablet, laptop or browser window that tilts into place, with feature chips that pop up beside it. A tall screenshot can scroll inside the screen. The standard way to show an app, a website or a dashboard in an ad.

Narration. The first say line shows the device, then one passage per chip (chips[].say).

Example

{
  "kind": "device",
  "heading": "Everything in one place",
  "device": "laptop",
  "screen": "/examples/ads-flowdesk-app/dashboard.webp",
  "motion": "zoom",
  "chips": [
    {
      "icon": "⚡",
      "text": "Live updates",
      "say": "Every change shows up live, for the whole team."
    },
    {
      "icon": "📊",
      "text": "Reports in one click",
      "say": "And reports are one click away."
    }
  ],
  "say": "This is Flowdesk, the home for your team's work."
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
device	enum	The frame around the screenshot. Default `phone`. `phonelaptoptabletbrowser`
screenrequired	string	A screenshot of the app, site or dashboard.
motion	enum	`zoom` (default) pushes slowly in, `scroll` moves a tall screenshot up through the screen, `still` holds it. `scrollzoomstill`
chips	object[]	Short feature labels that pop up next to the device, one per narrated passage. Limits: 0–4 items
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ textrequired	string	Limits: 1–28 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Offer offer

The deal, drawn like a price tag: a label above (Weekend sale), a big badge such as -30%, the old and new price, a coupon code and when it ends. Use once, before the end, when there is a price or a promotion to announce.

Narration. One to three say lines. The first shows the title and badge, the second the price, the third the code and the deadline. With fewer lines, the rest follows a moment later.

Example

{
  "kind": "offer",
  "eyebrow": "Launch week",
  "title": "Get Aurora One for less",
  "badge": "-17%",
  "price": {
    "now": "$249",
    "was": "$299"
  },
  "code": "AURORA20",
  "ends": "Ends Sunday",
  "perks": [
    "Free shipping",
    "30-day returns"
  ],
  "say": [
    "For launch week only, Aurora One is seventeen percent off.",
    "That is two hundred forty nine dollars, down from two ninety nine.",
    "Use code AURORA20 before Sunday. Shipping is free."
  ]
}

Field	Type	What it does
eyebrow	string	A small label above the title: `Limited time`, `Launch offer`. Limits: 1–32 characters
titlerequired	string	What the offer is, in a few words. Limits: 1–60 characters
badge	string	The headline number: `-30%`, `2 for 1`, `FREE`. Limits: 1–12 characters
price	object
└ nowrequired	string	The price to pay, as written: `$49`, `€9.90`, `From $9`. Limits: 1–14 characters
└ was	string	The old price, shown struck through. Limits: 1–14 characters
└ period	string	What the price covers: `/month`, `per box`. Limits: 1–12 characters
code	string	A coupon code, shown as a ticket. Limits: 1–16 characters
ends	string	The deadline: `Ends Sunday`. Limits: 1–32 characters
perks	string[]	Extras that come with it: `Free shipping`. Limits: 0–3 items, each 1–40 characters
sayrequired	string[]	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–3 items, each 1–500 characters

Kinetic text kinetic

Big words that pop in one by one, then give way to the next line. The hook of a short ad: a question, a pain point or a bold claim in a few words. Wrap words in double asterisks to colour them. Works with no pictures at all.

Narration. One passage per line (lines[].say): each line appears while it is spoken.

Example

{
  "kind": "kinetic",
  "lines": [
    {
      "text": "Tired of **tangled** cables?",
      "say": "Tired of tangled cables?"
    },
    {
      "text": "Wear **nothing** but sound.",
      "tone": "fuchsia",
      "say": "What if you could wear nothing but sound?"
    }
  ],
  "layout": "swap"
}

Field	Type	What it does
linesrequired	object[]	Limits: 1–5 items
└ textrequired	string	The words on screen. A short sentence reads best. Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
layout	enum	`swap` (default) shows one line at a time, `stack` keeps the earlier lines above the current one. `swapstack`

Beat montage montage

Fast cuts, one for each short line of narration: a giant word slams onto the screen over a picture or a block of colour, with a flash and a punch-in on every cut, like the feature montage of a product film. Keep every line to a word or a few words (Light. Fast. Yours.). Use it for the middle of a short ad, where the pace picks up.

Narration. One passage per cut (cuts[].say). The picture changes the moment its line starts; keep each line very short so the cuts come quickly.

Example

{
  "kind": "montage",
  "fit": "contain",
  "cuts": [
    {
      "word": "Light.",
      "picture": "/examples/ads-aurora-headphones/product.webp",
      "say": "Light."
    },
    {
      "word": "Quiet.",
      "tone": "violet",
      "say": "Quiet."
    },
    {
      "word": "Yours.",
      "picture": "/examples/ads-aurora-headphones/product.webp",
      "tone": "fuchsia",
      "say": "Yours."
    }
  ]
}

Field	Type	What it does
cutsrequired	object[]	Limits: 3–8 items
└ wordrequired	string	The giant word of this cut. Limits: 1–22 characters
└ picture	string	The picture of this cut. Without one, the cut is a block of colour.
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
fit	enum	`cover` (default) fills the frame with each picture, `contain` shows all of it on a block of colour: for cut-outs of the product. `covercontain`

Social proof trust

Why people believe it: a star rating with the number of reviews, then up to four trust badges (Free returns, Award winner, Secure payment). Use only real figures the owner gave you.

Narration. Optional lead, then the rating (rating.say), then one passage per badge (badges[].say), then optional outro.

Example

{
  "kind": "trust",
  "heading": "Loved by listeners",
  "rating": {
    "value": 4.8,
    "count": "12,400 reviews",
    "source": "Verified buyers",
    "say": "Rated four point eight out of five by more than twelve thousand listeners."
  },
  "badges": [
    {
      "icon": "🚚",
      "title": "Free shipping",
      "text": "On every order",
      "tone": "sky",
      "say": "Shipping is always free."
    },
    {
      "icon": "↩️",
      "title": "30-day returns",
      "text": "No questions asked",
      "tone": "emerald",
      "say": "And you have thirty days to change your mind."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
rating	object
└ valuerequired	number	The average rating out of 5, such as 4.8. Limits: 0–5
└ countrequired	string	How many ratings it is based on: `12,400 reviews`. Limits: 1–24 characters
└ source	string	Where the rating comes from: `Trustpilot`. Limits: 1–24 characters
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
badgesrequired	object[]	Trust badges. Needed when there is no `rating`. Limits: 0–4 items
└ iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–28 characters
└ text	string	Limits: 1–60 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Brand reveal brandreveal

A short sting: the logo (from brand.logo, or the brand name as a wordmark) arrives with a flourish and the tagline settles under it. Use after the hook and the problem, to put a name to the solution.

Narration. One say line, spoken as the logo arrives.

Example

{
  "kind": "brandreveal",
  "tagline": "Wear nothing but sound.",
  "reveal": "burst",
  "say": "Introducing Aurora. Wear nothing but sound."
}

Field Type What it does

tagline

string

Shown under the logo. Default: brand.tagline.

Limits: 1–60 characters

reveal

enum

How the logo arrives. burst (default) a flash of light, sweep a glint across it, rise from below, zoom from far away.

burstsweeprisezoom

sayrequired

string

The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as <sigh>, <laugh> or <short pause> is performed at that spot and is not shown.

Limits: 1–500 characters

Showcase showcase

Several pictures shown as a gallery, one in focus at a time while it is narrated: a 3D coverflow (default), a filmstrip that slides, or a mosaic that fills in. Each has a title, a line of detail and an optional price or tag. For a collection, a catalogue, a menu of dishes, the rooms of a property or a list of destinations.

Narration. Optional lead, then one passage per item (items[].say), then optional outro.

Example

{
  "kind": "showcase",
  "heading": "The collection",
  "layout": "coverflow",
  "items": [
    {
      "picture": "/examples/ads-aurora-headphones/product.webp",
      "title": "Aurora One",
      "text": "Wireless headphones.",
      "price": "$249",
      "tag": "New",
      "say": "Aurora One, our wireless headphones."
    },
    {
      "picture": "/examples/ads-lume-serum/product.webp",
      "title": "Glow Serum",
      "text": "Vitamin C, in one drop.",
      "price": "$38",
      "say": "Glow Serum, vitamin C in one drop."
    },
    {
      "picture": "/examples/ads-copper-bean-coffee/product.webp",
      "title": "Monday Blend",
      "text": "Small-batch roasted.",
      "price": "$14",
      "tag": "Fresh",
      "say": "And Monday Blend, roasted in small batches."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
layout	enum	`coverflow` (default) a row of pictures tilted in 3D, `filmstrip` a strip that slides, `mosaic` a grid that fills in. `coverflowfilmstripmosaic`
fit	enum	`cover` (default) fills each frame with the picture, `contain` shows all of it: for cut-outs and products on plain backgrounds. `covercontain`
itemsrequired	object[]	Limits: 2–6 items
└ picturerequired	string	A picture of this one.
└ titlerequired	string	Limits: 1–32 characters
└ text	string	One line of detail. Limits: 1–60 characters
└ price	string	Its price, as written. Limits: 1–14 characters
└ tag	string	A small label: `New`, `Best seller`. Limits: 1–16 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Spec sheet specs

The key facts as a spec sheet: big values with their labels (40 h battery life, 3 bedrooms, 0-100 in 3.2 s), as tiles or as rows beside the product picture. Use for hardware, vehicles, property, courses: whatever is bought by its numbers. Values are shown exactly as written.

Narration. Optional lead, then one passage per fact (items[].say), then optional outro.

Example

{
  "kind": "specs",
  "heading": "Aurora One in numbers",
  "picture": "/examples/ads-aurora-headphones/product.webp",
  "layout": "rows",
  "items": [
    {
      "icon": "🔋",
      "label": "Battery life",
      "value": "40 h",
      "note": "On a single charge.",
      "say": "Forty hours of battery life on a single charge."
    },
    {
      "icon": "⚖️",
      "label": "Weight",
      "value": "220 g",
      "say": "At only two hundred twenty grams."
    },
    {
      "icon": "🔌",
      "label": "Full charge",
      "value": "90 min",
      "say": "And a full charge takes ninety minutes."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
picture	string	The product picture beside the facts. A cut-out looks best.
layout	enum	`tiles` (default) a grid of big values, `rows` a list with the value at the end of each row. `tilesrows`
itemsrequired	object[]	Limits: 3–6 items
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ labelrequired	string	What it measures: `Battery life`. Limits: 1–24 characters
└ valuerequired	string	The figure, as written: `40 h`, `3 beds`. Limits: 1–16 characters
└ note	string	A few words of detail. Limits: 1–40 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

A price list in the style of a menu: each row has a name, a line of detail, a dotted line and the price, with an optional tag (Vegan, Best seller). A picture can sit beside it. Use for a restaurant or cafe menu, a salon or spa price list, service packages or class passes. Prices are shown exactly as written.

Narration. Optional lead, then one passage per row (items[].say), then optional outro.

Example

{
  "kind": "menu",
  "eyebrow": "This week",
  "heading": "The menu",
  "picture": "/examples/ads-copper-bean-coffee/product.webp",
  "items": [
    {
      "name": "Monday Blend",
      "text": "Chocolate and toasted hazelnut.",
      "price": "$14",
      "tag": "Bestseller",
      "say": "Monday Blend, chocolate and toasted hazelnut, fourteen dollars."
    },
    {
      "name": "Sunday Single Origin",
      "text": "Bright, with notes of berries.",
      "price": "$18",
      "say": "Sunday Single Origin, bright and fruity, eighteen dollars."
    },
    {
      "name": "Decaf Dusk",
      "text": "Smooth and sweet.",
      "price": "$15",
      "tag": "Decaf",
      "say": "And Decaf Dusk, smooth and sweet, for fifteen."
    }
  ]
}

Field	Type	What it does
eyebrow	string	A small label above the heading: `Today's specials`. Limits: 1–32 characters
heading	string	Scene heading shown at the top. Limits: 1–60 characters
picture	string	A picture beside the list: a dish, a treatment, a room.
itemsrequired	object[]	Limits: 2–6 items
└ namerequired	string	Limits: 1–32 characters
└ text	string	What is in it, or what it includes. Limits: 1–60 characters
└ pricerequired	string	The price, as written: `$12`, `from €30`. Limits: 1–14 characters
└ tag	string	Limits: 1–16 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Event event

An invitation card: a big calendar date, the title, the time and the place, the host and up to three perks (Free entry). Use for an opening, a launch party, a webinar, a class, a sale day or any date people should save.

Narration. One to three say lines. The first shows the date and the title, the second the time and the place, the third the host and the perks. With fewer lines, the rest follows a moment later.

Example

{
  "kind": "event",
  "eyebrow": "You are invited",
  "title": "Grand opening party",
  "date": {
    "day": "14",
    "month": "NOV",
    "weekday": "Friday"
  },
  "time": "7 pm",
  "place": "Copper Bean, Market Street",
  "host": "Hosted by Mia and Leo",
  "perks": [
    "Free entry",
    "Live music",
    "First coffee on us"
  ],
  "say": [
    "Join us for the grand opening party on Friday, November fourteenth.",
    "We open the doors at seven at the Copper Bean on Market Street.",
    "Entry is free, there is live music, and your first coffee is on us."
  ]
}

Field	Type	What it does
eyebrow	string	A small label above the title: `You are invited`. Limits: 1–32 characters
titlerequired	string	What the event is. Limits: 1–60 characters
daterequired	object
└ dayrequired	string	The day of the month, as written: `14`. Limits: 1–4 characters
└ monthrequired	string	The month, as written: `NOV`, `November`. Limits: 1–10 characters
└ weekday	string	`Friday`. Limits: 1–12 characters
└ year	string	Limits: 1–6 characters
time	string	`7 pm`, `10:00 - 16:00`. Limits: 1–24 characters
place	string	Where it is: `Café Aurora, Berlin`, `Online`. Limits: 1–40 characters
host	string	Who is hosting. Limits: 1–40 characters
perks	string[]	Why to come: `Free entry`, `Live music`. Limits: 0–3 items, each 1–28 characters
picture	string	A picture of the place or the host.
sayrequired	string[]	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–3 items, each 1–500 characters

Review wall reviews

A wall of customer reviews in drifting columns, each card with the quote, the name and its stars, the one being read lit up. An overall rating can head it. Use for social proof when there are three or more real reviews. Only real quotes.

Narration. Optional lead, then one passage per review (items[].say), then optional outro.

Example

{
  "kind": "reviews",
  "heading": "Loved by listeners",
  "rating": {
    "value": 4.8,
    "count": "12,400 reviews"
  },
  "items": [
    {
      "quote": "The most comfortable headphones I have ever worn.",
      "name": "Sara K.",
      "role": "Verified buyer",
      "stars": 5,
      "say": "Sara says they are the most comfortable headphones she has ever worn."
    },
    {
      "quote": "Battery lasts all week. Sound is unreal.",
      "name": "Daniel M.",
      "role": "Verified buyer",
      "stars": 5,
      "say": "Daniel says the battery lasts all week and the sound is unreal."
    },
    {
      "quote": "Light enough to forget I am wearing them.",
      "name": "Priya R.",
      "stars": 5,
      "say": "And Priya says they are light enough to forget she is wearing them."
    },
    {
      "quote": "Noise cancelling that actually works on the train.",
      "name": "Tom B.",
      "role": "Commuter",
      "stars": 4,
      "say": "Tom says the noise cancelling actually works on the train."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
rating	object
└ valuerequired	number	The average rating out of 5. Limits: 0–5
└ countrequired	string	`12,400 reviews`. Limits: 1–24 characters
itemsrequired	object[]	Limits: 3–6 items
└ quoterequired	string	Limits: 1–150 characters
└ namerequired	string	Limits: 1–32 characters
└ role	string	Who they are: `Verified buyer`, `Head of design`. Limits: 1–40 characters
└ stars	integer	Its stars, 1 to 5. Leave out to show none. Limits: 1–5
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Orbit orbit

Your name or logo in the middle and three to eight things around it on a ring, joined to it by lines that draw in one by one: integrations, pillars of a service, ingredients, the parts of a platform. The one being narrated lights up. The hub is the logo from brand.logo, or the brand name.

Narration. Optional lead, then one passage per item (items[].say), then optional outro.

Example

{
  "kind": "orbit",
  "heading": "Works with your tools",
  "hub": {
    "label": "Flowdesk"
  },
  "items": [
    {
      "icon": "💬",
      "title": "Slack",
      "text": "Updates where you chat.",
      "say": "Updates land in Slack."
    },
    {
      "icon": "📅",
      "title": "Calendar",
      "text": "Deadlines in sync.",
      "say": "Deadlines sync with your calendar."
    },
    {
      "icon": "🗂️",
      "title": "Drive",
      "say": "Files stay in your Drive."
    },
    {
      "icon": "🧾",
      "title": "Invoices",
      "text": "Billing built in.",
      "say": "And invoices are built in."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
hub	object
└ label	string	Text in the middle. Default: the brand name, or nothing when there is a logo. Limits: 1–24 characters
└ picture	string	A picture in the middle. Default: `brand.logo`.
itemsrequired	object[]	Limits: 3–8 items
└ iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–24 characters
└ text	string	Limits: 1–48 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

App window appui

An app window drawn live, the way a software ad shows its product: a card with a title and up to five rows that come to life as they are narrated. A field is typed letter by letter with a caret, a toggle flips, a chips row selects a choice, a button is tapped by a pointer, an item slides in as an entry of a list, a progress bar fills and a note shows an insight. The row being narrated sits on a soft patch of the accent. Use it to show what using the product feels like, with real labels and figures. Light by default, dark for an app that is dark.

Narration. Optional lead as the window appears, then one passage per row (rows[].say), each as the row comes to life, then optional outro.

Example

{
  "kind": "appui",
  "heading": "Tell it. **Done.**",
  "title": "Listening",
  "status": "Live",
  "rows": [
    {
      "type": "field",
      "label": "What did you spend today?",
      "value": "15,000 for fuel, 5,000 for groceries",
      "icon": "🎙️",
      "say": "Just say what you spent, in your own words."
    },
    {
      "type": "toggle",
      "label": "Split by category",
      "on": true,
      "say": "Switch on categories, and it sorts every entry."
    },
    {
      "type": "chips",
      "label": "Category",
      "options": [
        "Fuel",
        "Groceries",
        "Medicine"
      ],
      "pick": 1,
      "say": "It picks the right one."
    },
    {
      "type": "button",
      "label": "Confirm entry",
      "tone": "emerald",
      "say": "One tap to confirm."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
titlerequired	string	The title of the window: `Listening`, `New alert`, `Settings`. Limits: 1–32 characters
status	string	A small live badge next to the title with a pulsing dot: `Live`, `Recording`. Limits: 1–16 characters
surface	enum	The window itself: `light` (default) or `dark`, whatever the video looks like. `lightdark`
rowsrequired	object[]	Limits: 1–5 items
└ typerequired	enum	What the row is. `field` a labelled input whose `value` is typed in with a caret, `toggle` a switch that flips (`on`, default true), `chips` a row of `options` with `pick` selected, `button` a pill button that is tapped, `item` a list entry with an `icon`, a title (`label`), a detail (`text`) and an amount (`value`), `note` a message such as an insight (`label` is its small title, `text` its body), `progress` a bar that fills to `percent`. `fieldtogglechipsbuttonitemnoteprogress`
└ labelrequired	string	The label of the field, toggle or bar, the text of the button, the title of the item or the small title of the note. Limits: 1–40 characters
└ value	string	A `field`: the text that is typed. An `item`: the amount at its end. A `progress`: the figure shown, such as `72%`. Limits: 1–80 characters
└ text	string	An `item`: the line under its title. A `note`: the message. Not used by the others. Limits: 1–120 characters
└ options	string[]	A `chips` row: the choices. Limits: 2–5 items, each 1–20 characters
└ pick	integer	A `chips` row: which choice (counting from 0) is selected. Default 0. Limits: 0–4
└ on	boolean	A `toggle`: whether it ends switched on. Default true.
└ percent	number	A `progress`: how full the bar gets, 0 to 100. Limits: 0–100
└ icon	string	An `item`: the symbol at its start. A `field` or `note`: a symbol beside its label. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Cascade of cards cascade

Cards that arrive one after another, the way a software ad shows a flow of items: stack (default) cards cascade down and to the right, each new one in front while the earlier ones fall back; wall a tilted grid in 3D that fills in; feed a list of pills that scrolls so the one narrated is in the middle. For job postings, leads, tickets, orders, transactions, alerts or any stream the product handles. Use real titles, not placeholders.

Narration. Optional lead, then one passage per card (items[].say), then optional outro.

Example

{
  "kind": "cascade",
  "heading": "Still refreshing job boards?",
  "layout": "stack",
  "items": [
    {
      "meta": "Posted 2 minutes ago",
      "title": "Senior React Developer for SaaS Dashboard",
      "text": "Hourly: $40-$60",
      "foot": "Payment verified",
      "badge": "Proposals: 5 to 10",
      "say": "A new React job lands."
    },
    {
      "meta": "Posted 5 minutes ago",
      "title": "Next.js + TypeScript Frontend Engineer",
      "text": "Hourly: $50-$80",
      "foot": "Payment verified",
      "badge": "Proposals: 10 to 15",
      "say": "Then a Next.js one."
    },
    {
      "meta": "Posted 12 minutes ago",
      "title": "Build an n8n Automation for Lead Routing",
      "text": "Route inbound leads from Typeform to HubSpot and Slack.",
      "foot": "Payment verified",
      "badge": "Proposals: 50+",
      "say": "And by the time you see it, fifty people have applied."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
layout	enum	`stack` (default), `wall` or `feed`. `stackwallfeed`
itemsrequired	object[]	Limits: 2–8 items
└ meta	string	A small line above the title: `Posted 2 minutes ago`. Limits: 1–40 characters
└ titlerequired	string	Limits: 1–56 characters
└ text	string	A line of detail under the title. Limits: 1–110 characters
└ foot	string	A small line at the bottom: `Payment verified`. Limits: 1–40 characters
└ badge	string	A pill at the bottom right: `Proposals: 50+`, `New`. Limits: 1–20 characters
└ icon	string	A symbol at the start of the card. Always shown in the `feed` layout. Limits: 1–8 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Notifications notify

Notifications that land one after another: lockscreen (default) a phone lock screen with the time and each notification dropping in on a stack, toasts floating cards that slide in from the top, each pushing the earlier ones down. For alerts, reminders, messages and anything the product tells people about, so the ad shows it working while they are away.

Narration. Optional lead, then one passage per notification (items[].say), then optional outro.

Example

{
  "kind": "notify",
  "layout": "lockscreen",
  "time": "9:41",
  "date": "Tuesday, 20 October",
  "items": [
    {
      "app": "Slack",
      "icon": "💬",
      "title": "New job in #alerts",
      "text": "Build an n8n automation for lead routing. Fixed price: $1,200.",
      "when": "now",
      "say": "A new job lands in Slack, the moment it is posted."
    },
    {
      "app": "Calendar",
      "icon": "📅",
      "title": "Call with Maya in 10 minutes",
      "when": "5m ago",
      "tone": "sky",
      "say": "Your calendar keeps the rest in order."
    }
  ]
}

Field	Type	What it does
heading	string	Scene heading shown at the top. Limits: 1–60 characters
layout	enum	`lockscreen` (default) or `toasts`. `lockscreentoasts`
time	string	The clock of the lock screen, as written. Default `9:41`. Limits: 1–8 characters
date	string	The date under the clock, as written: `Tuesday, 20 October`. Limits: 1–24 characters
itemsrequired	object[]	Limits: 1–6 items
└ apprequired	string	The app it comes from: `Slack`, `Calendar`. Limits: 1–24 characters
└ iconrequired	string	An emoji or a short symbol. Limits: 1–8 characters
└ titlerequired	string	Limits: 1–48 characters
└ text	string	Limits: 1–100 characters
└ when	string	When it arrived: `now`, `2m ago`. Limits: 1–12 characters
└ tone	enum	Accent colour. `rose` marks a negative item (cross), `emerald` a positive one. `violetemeraldamberroseskyfuchsiatealorange`
└ sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters
lead	string	Narration before the first item appears. Limits: 1–500 characters
outro	string	Narration after the last item. Limits: 1–500 characters

Constellation constellation

A promise in the middle and the tools around it: four to fourteen symbols or logos circle it on rings, popping in one by one. The middle text may highlight words with double equals (drawn under them by hand) or colour them with double asterisks. For integrations, the platforms a product works with or the things it replaces. Use real names and logos, never invented ones.

Narration. One say line, spoken as the rings fill.

Example

{
  "kind": "constellation",
  "text": "Plugs into ==every tool== you use",
  "items": [
    {
      "icon": "💬",
      "label": "Slack"
    },
    {
      "icon": "📅",
      "label": "Calendar"
    },
    {
      "icon": "🗂️",
      "label": "Drive"
    },
    {
      "icon": "🧾",
      "label": "Invoices"
    },
    {
      "icon": "📧",
      "label": "Email"
    },
    {
      "icon": "📊",
      "label": "Sheets"
    }
  ],
  "say": "It plugs into every tool you already use."
}

Field	Type	What it does
textrequired	string	The promise in the middle: `Connects to ==everything== you use`. Limits: 1–60 characters
itemsrequired	object[]	Limits: 4–14 items
└ icon	string	An emoji or a short symbol. Limits: 1–8 characters
└ picture	string	A logo or picture instead of the symbol.
└ label	string	Its name, under it. Limits: 1–16 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

End card endcard

The closing frame of an ad: the logo, one headline, a button that says what to do, the address to visit and, if there is one, the offer and store badges. One call to action only. Use last.

Narration. One say line, spoken as the card appears.

Example

{
  "kind": "endcard",
  "headline": "Get **Aurora One** today",
  "text": "Thirty days to love them or send them back.",
  "picture": "/examples/ads-aurora-headphones/product.webp",
  "button": "Shop now",
  "link": "aurora.audio/one",
  "offer": "Free shipping this week",
  "say": "Get Aurora One today at aurora dot audio slash one. Free shipping this week."
}

Field	Type	What it does
headlinerequired	string	The one thing to do, as a headline: `Get Aurora One today`. Limits: 1–80 characters
text	string	Limits: 1–150 characters
picture	string	A small picture of the product next to the headline.
buttonrequired	string	The label of the button: `Shop now`, `Start free`. Limits: 1–24 characters
link	string	The address to visit, as it should be read: `aurora.audio/one`. Limits: 1–48 characters
offer	string	A line about the offer, in a ribbon: `Free shipping this week`. Limits: 1–40 characters
badges	string[]	Where to get it: `App Store`, `Google Play`. Limits: 0–3 items, each 1–20 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Call to action cta

A closing card with a headline, a button and a handle or link. Only for a video that asks the viewer to do something (subscribe, sign up, buy); not a way to end every video.

Narration. One say line, spoken as the card appears.

Example

{
  "kind": "cta",
  "title": "Enjoyed this?",
  "text": "New explainers every week.",
  "button": "Subscribe",
  "handle": "@learnwithus",
  "icon": "🔔",
  "say": "If you enjoyed this, subscribe for a new explainer every week."
}

Field	Type	What it does
titlerequired	string	Limits: 1–80 characters
text	string	Limits: 1–150 characters
button	string	Label of the (decorative) button, for example `Subscribe`. Limits: 1–24 characters
handle	string	A handle or address, for example `@learnwithus` or `example.com`. Limits: 1–40 characters
icon	string	An emoji or a short symbol. Limits: 1–8 characters
sayrequired	string	The narration for this item. It is spoken, and shown as the caption. With the premium voice, a tag such as `<sigh>`, `<laugh>` or `<short pause>` is performed at that spot and is not shown. Limits: 1–500 characters

Recap outro

The takeaways as a card the host reads out one by one, plus an optional teaser of what comes next. Optional and rare: a long lesson with several separate ideas can end with one; most videos should end on their last real scene instead.

Narration. lead first, then one passage per recap line (in order), then next.

Example

{
  "kind": "outro",
  "lead": "Let us recap what we learned.",
  "recap": [
    "Water evaporates, condenses and falls again.",
    "The sun powers the whole cycle.",
    "Every drop has travelled for millions of years."
  ],
  "next": "Next time we will look at how clouds are formed."
}

Field Type What it does

leadrequired

string

Spoken as the card appears, e.g. Let us recap.

Limits: 1–500 characters

recaprequired

string[]

The takeaways. Each is shown on the card and spoken.

Limits: 1–6 items, each 1–150 characters

string

Teaser for what comes next.

Limits: 1–500 characters