Writing the script

What does a script look like?

# How DNS finds a website

## hook

You type {example.com|example dot com}, and a page appears. [#but] Computers don't
find each other by name, though. [#numbers] They use numbers called IP addresses.

## question {hold=1.5}

So before the page can load, [#ask] your browser needs the IP address of the site.

• # Title is the title of the video. It is not spoken.
• ## hook starts a scene called hook. scenes.js needs a function with the same name.
• The text below the heading is what the voice says. Blank lines inside a scene make a slightly longer pause.

What are markers?

[#numbers] is a marker. It names a moment in the narration. The marker takes the time of the next word. A picture in scenes.js can appear at that moment with at: '#numbers'. Put a marker wherever the picture should change.

You don’t always need one. A picture can also appear on any spoken word, like at: 'resolver'. Markers help when a word comes up more than once, or when you want a moment between two words.

How do I add a pause?

[pause] adds half a second of silence, and [pause 1.2] adds 1.2 seconds.

What if the voice says a word wrong?

Write the word the way it should look, then the way it should sound:

{SQL|sequel} {CLI|C L I} {example.com|example dot com} {v2.1|version two point one}

The captions use the first part, and so does a picture that appears on that word. The voice says the second part. Web addresses need this most. Without it, the voice reads “example.com” as “example comm”.

explainroo voice lists the words the speech check could not confirm. explainroo check also shows what it heard instead. Then you know what to fix.

What can I set per scene?

Attributes are extra settings for one scene. They go in braces after the scene name, like ## outro {hold=2 transition=cut}.

Attribute	What it does
hold	seconds after the voice before the next scene starts (default 0.7)
lead	seconds before the voice starts (default 0.35)
min	the shortest the scene may be (a scene without narration lasts 3 seconds unless you set it)
transition	how this scene comes in: fade, slide, wipe, zoom, brush or cut

A scene without any narration is allowed. It lasts min seconds.

How should the narration sound?

explainroo tells agents to write the way a person explains something to a friend at a table. That style also works best when you edit a script yourself:

• Regular, down-to-earth English and everyday words. When a technical word is needed, say what it means the first time.
• Short sentences, about 8 to 18 words, one idea each.
• Say who does what: “The browser asks a resolver.”
• Every sentence adds a fact. Cut half sentences that repeat what was already said.
• No dashes between phrases, no slogans or punchlines, no “not X, but Y” twists, and no filler words like “just”, “simply” or “really”.
• End with a plain sentence that sums up the main point.

How long should a video be?

Most explainer videos work well between 45 and 120 seconds. A finished video has about 150 words a minute, pauses included. So 150 words make a video of about one minute.

Start with the question or the problem, then explain it in small steps. Give one example and end with a short summary. Keep one idea per scene, usually one to three sentences.