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.

After voice, this lists the spoken words of a scene with their start times and the markers between them, so you can pick a word as a cue:

npx --yes explainroo words videos/dns hook

A word spoken more than once shows its cue for each time, like fills#2 for the second time.

How do I add a pause?

[pause] adds half a second of silence, and [pause 1.2] adds 1.2 seconds. Your own recording keeps its recorded pauses. These marks do not add silence to it.

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”.

How do I color a word in bold captions?

Put it in stars, like *stale*. Nobody hears the stars. With "captions": "bold", the word shows in the keyword color, and numbers and amounts of money get that color by themselves. Use stars for one or two words a sentence, or the color stops meaning anything. See captions.

explainroo voice lists the words the speech check could not confirm. Under each scene it quotes the sentence the voice was given, after {shown|spoken}, and what it heard there, with four words on each side. Then it says what to do. Then you know what to fix. If the word already has {shown|spoken}, try another spoken spelling or reword the sentence. With your own recording, change the script to match what you said.

The check counts the word when it hears either form, so “example.com” confirms {example.com|example dot com}. It also counts a word heard as another word with the same sound, like “peace” for “piece”, and two words heard as one. check lists them with the words that only nearly matched, like “Soundroo” heard as “Soundru”, each with its time in the video. They need no fix unless one sounds wrong when you listen at that time. See checking a video.

What if the check hears a word another way?

Sometimes the voice says a name right, and the speech model writes it another way, like “Reg X 101” for regex101. {shown|spoken} doesn’t help there, because the voice is not the problem. Accept that form in video.json instead:

"heard": { "regex101": ["reg x 101", "regex 101"] }

When the speech model hears one of these forms where the script has the word, the word counts as confirmed in every check. The voice isn’t made again. Two words heard as one take both words with a space, like "heard": { "ape lo": ["apelo"] }.

A form matches one word or a few words next to each other, written the way the check writes them. Case and punctuation don’t count. A form is read like the transcript, so “$” is “dollars”. It can’t change the order of words or stand for part of a word.

You rarely write the line yourself. When voice hears a word the same way twice in a row, it prints the line to add. When a word comes up several times and is heard as the same other spelling each time, voice and check print it too. When a form matches nothing while its word is still unconfirmed, check names the form and what it heard there instead.

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, push, wipe, zoom, brush or cut
chapter	a chapter title in quotes, from 1 to 60 characters

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

How do I add chapters?

A chapter helps viewers find a part of a longer video. Add its title to the scene where it starts:

## resolver {chapter="How the resolver finds it"}

Your browser asks a resolver for the address.

It lasts until the next chapter. If the first scene has no chapter title, explainroo uses the video’s title for the first chapter. render adds chapters to the MP4 and writes out/video.chapters.txt. Paste that file into your YouTube description. YouTube needs at least three chapters, each at least ten seconds long. check gives hints when they are too few or too short.

The publishing page covers the other files that come with a render.

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 language 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. At the default speed the voice says about 13 letters a second. In English that is 165 to 200 words a minute, depending on how long the words are. A number takes longer than its digits suggest, because “1972” is said as “nineteen seventy-two”. Some voices are slower, like am_michael, and some are faster, like af_jessica. Other languages have their own figures.

On top of the speech, each scene adds its lead and its hold, 0.35 and 0.7 seconds by default. Each new sentence in a scene adds a pause of 0.3 seconds, and a new paragraph adds 0.55. The end of the video adds 1.4 seconds. So 105 words in 6 scenes make a video of about 45 seconds, and a finished video has about 130 to 155 words a minute.

To see the length before you make the voice, run this:

npx --yes explainroo voice videos/dns --estimate

It prints the estimate with each of its parts, worked out from your video’s settings, and it makes nothing. The estimate comes with a range, like 43 to 47 seconds, and the voice nearly always lands in it. So aim the middle a little under a target. When the estimate is too long, cut words before you make the voice.

For an exact length, set it in video.json, or run explainroo set videos/dns targetSeconds 40:

"targetSeconds": 40

voice --estimate also says what the estimate means for the target.

When the video comes out shorter, the missing time goes evenly into the holds of its scenes, so it ends at 40 seconds. When that adds more than 3 seconds to each scene, or when the video runs more than half a second longer, voice and check say so and name the longest scenes. Without targetSeconds, a video is as long as its narration. The target counts for every size. A block under "sizes" can set its own, or null for none.

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.

How do I write in another language?

The rules above count in every language, but the filler words they name are English. Leave out the same kind of word in the language of your video, and write the way someone would say it in that language. The length estimate counts about 13 letters a second for every language with an alphabet. So how many words fit in a minute depends on how long the words of the language are. For ordinary narration at the default speed, that is about:

Language	Words a minute	Filler words to leave out
English	165 to 200	just, simply, really, actually
Spanish	175	realmente, simplemente, básicamente
French	160	vraiment, simplement, juste
Italian	180	davvero, semplicemente, praticamente
Brazilian Portuguese	185	realmente, simplesmente, basicamente
German	135	eigentlich, einfach, wirklich

For Hindi the estimate counts 150 words a minute. Japanese counts 300 characters a minute, and Chinese 230. voice --estimate gives the figure for your own script. The voices and languages page says how to set the language.