A short documentary-style video, the kind a history or nature page posts as a vertical clip, has the same job as a long film: make someone care about a true thing. It has far less room to do it. The usual failure isn't a lack of material. It is a script that tries to say everything and runs well over its time, so the edit becomes a series of cuts to the narration.
This post sets out the structure I'd use for a script of about a minute, a few habits for writing words meant to be heard, and a small tool that tells you how long a script will take and where it goes wrong. I'll be upfront about what is opinion and what is arithmetic. The structure and the writing advice are opinion. The timing is arithmetic.
Start from the clock, not the topic
Most scripts begin with a subject ("the Battle of Trafalgar") and then discover the time. I'd begin with the time and work backwards. If the video is about 60 seconds, the narration is some number of words, and that number depends entirely on how fast the narrator speaks. That is why I won't give you a universal figure here. Reading speed varies between people, between languages, and between a calm voice-over and an excited one. Measure your own: read a passage of your usual style aloud at the pace you'd actually narrate, time it with a stopwatch, count the words, and divide. Do it three times and use the middle result.
Once you have your number, a 60-second video has a word budget. If you read at 150 words per minute, you have 150 words for the whole minute, which is far fewer than most people expect. If you read at 120, you have 120. Silence and music count against the budget too, which is why I'd keep at least a couple of beats of the video wordless.
Hook, beats, close
For a one-minute piece I use three parts.
The hook (the first few seconds)
One concrete sentence that puts a specific person, place or question on screen. Not "Have you ever wondered about history?" but a thing: "In the autumn of 1805, a fleet of thirty-three ships sailed toward a coast nobody aboard had seen." A hook promises that the next fifty seconds will be about something particular.
Two to five beats
A beat is one idea with one image or piece of evidence. "The decision." "What the map shows." If a beat needs the word "and" to describe it, it is probably two beats. Each beat should leave the viewer knowing one more thing than before.
The close
Either a loose end honestly left open ("We still don't know why the signal was misread") or a question for the comments. I'd avoid a tidy moral. A short video that says what the evidence can't tell us is more convincing than one that wraps up a complicated event in a line.
The tool below enforces exactly this shape, because a rule is easier to keep when something checks it.
Write for the ear
Words that read well on a page can be hard to say and hard to follow when heard. These are habits I'd apply; try them and keep what helps.
- One idea per sentence. A listener can't re-read. If a sentence has a clause in the middle that you have to hold in your head while waiting for the verb, split it.
- Put the new thing last. "The line broke at the centre" lands harder than "At the centre, the line broke", because the sentence ends on the information.
- Say numbers the way you'd say them. "Thirty-three ships" beats "33 vessels" on the page and in the mouth. Round figures you can't cite exactly. If you give a number, you should have a source for it, a point I come back to below.
- Read it aloud before you time it. Anything you trip over, the audience will trip over too. Fix the sentence, not your delivery.
- Cut the throat-clearing. "It's important to note that" and "As we all know" are word budget spent on nothing.
A before and after
Here is the kind of paragraph that goes over budget, made up for this example:
There were a great many factors that contributed to the decision that was made by the admiral, and it is
important to note that the weather conditions at the time were, as historians have often pointed out,
quite unfavourable for any kind of prolonged waiting.
That's 45 words and says almost nothing. The rewrite:
The admiral had two options. Wait for better weather, or close the distance before the enemy formed a line.
That's 19 words, names the choice, and gives the viewer something to hold. It also makes a claim ("two options") that you would need to be able to support from a source, which is the real work of a documentary script and the thing no tool can do for you.
A script-timing tool
The script below reads a script written with [HOOK], [BEAT: label] and [CLOSE] markers on their own lines, counts the words in each part, converts them to seconds at the words-per-minute figure you give it, and reports problems: a script that doesn't open with a hook or end with a close, a hook longer than your limit, a beat that runs too long, too few or too many beats, and a total over your target (with the number of words you need to cut).
script_timing.py
"""Time a short-video narration script from its word count, beat by beat, and flag the usual problems.
Script format: markers on their own line, then the narration.
[HOOK]
In October 1805 ...
[BEAT: The decision]
...
[CLOSE]
...
python script_timing.py script.txt --wpm 150 --target 60
Measure YOUR wpm by reading a paragraph aloud with a stopwatch; 150 below is only a default to adjust.
"""
import re
import sys
MARKER = re.compile(r"^\[(HOOK|BEAT(?::\s*(.*?))?|CLOSE)\]\s*$", re.M | re.I)
def words(text):
return len(re.findall(r"[A-Za-z0-9][A-Za-z0-9'’\-]*", text))
def parse(script):
"""Return [(kind, label, text)]. Raises ValueError if text appears before the first marker."""
marks = list(MARKER.finditer(script))
if not marks:
raise ValueError("no [HOOK]/[BEAT]/[CLOSE] markers found")
if script[:marks[0].start()].strip():
raise ValueError("text before the first marker")
out = []
for i, m in enumerate(marks):
end = marks[i + 1].start() if i + 1 < len(marks) else len(script)
kind = m.group(1).split(":")[0].upper()
out.append((kind, (m.group(2) or "").strip(), script[m.end():end].strip()))
return out
def timing(script, wpm=150, target=60, max_hook=8, max_beat=20):
parts = parse(script)
rows = [{"kind": k, "label": lab, "words": words(t), "seconds": words(t) / wpm * 60} for k, lab, t in parts]
total = sum(r["seconds"] for r in rows)
problems = []
kinds = [r["kind"] for r in rows]
if kinds[0] != "HOOK":
problems.append("the script should open with [HOOK]")
if kinds[-1] != "CLOSE":
problems.append("the script should end with [CLOSE]")
if kinds.count("HOOK") > 1 or kinds.count("CLOSE") > 1:
problems.append("only one [HOOK] and one [CLOSE]")
beats = kinds.count("BEAT")
if not 2 <= beats <= 5:
problems.append(f"{beats} beat(s): aim for two to five in a short video")
for r in rows:
if r["kind"] == "HOOK" and r["seconds"] > max_hook:
problems.append(f"hook runs {r['seconds']:.1f}s; aim for {max_hook}s or less")
if r["kind"] == "BEAT" and r["seconds"] > max_beat:
problems.append(f"beat '{r['label']}' runs {r['seconds']:.1f}s; split it or cut it ({max_beat}s max)")
if total > target:
problems.append(f"total {total:.1f}s is over the {target}s target by {total - target:.1f}s "
f"(about {round((total - target) / 60 * wpm)} words)")
return rows, total, problems
def report(script, **kw):
rows, total, problems = timing(script, **kw)
lines = [f"{'part':<26}{'words':>6}{'seconds':>9}"]
for r in rows:
name = r["kind"] + (f": {r['label']}" if r["label"] else "")
lines.append(f"{name:<26}{r['words']:>6}{r['seconds']:>9.1f}")
lines.append(f"{'TOTAL':<26}{sum(r['words'] for r in rows):>6}{total:>9.1f}")
lines += [f"PROBLEM: {p}" for p in problems]
return "\n".join(lines)
if __name__ == "__main__":
import argparse
ap = argparse.ArgumentParser()
ap.add_argument("script")
ap.add_argument("--wpm", type=int, default=150)
ap.add_argument("--target", type=int, default=60)
a = ap.parse_args()
print(report(open(a.script).read(), wpm=a.wpm, target=a.target))
Here is the made-up sample script it runs against:
sample_script.txt
[HOOK]
In the autumn of 1805, a fleet of thirty-three ships sailed toward a coast nobody aboard had seen.
[BEAT: The decision]
The admiral had two options. He could wait for better weather, or he could close the distance before the enemy formed a line. He chose to close the distance, and that choice shaped everything that followed.
[BEAT: What the map shows]
This chart, drawn from the surviving logs, marks where each ship stood at noon. Notice the gap in the centre. It is the reason the line broke.
[CLOSE]
We still do not know why the signal was misread. What would you have done in that hour?
At 150 words per minute the sample comes to 99 words and 39.6 seconds, with no problems. The same script at 90 words per minute takes 66 seconds, and the tool flags three things: the hook runs 12 seconds against an 8-second limit, "The decision" runs 24 seconds against a 20-second limit, and the total is 6 seconds, or about 9 words, over a 60-second target. That's the useful behaviour: the same text is fine for a fast reader and too long for a slow one, so the number that matters is your own.
The tests check the word counter on hyphens, apostrophes and numbers, the parser, the arithmetic, the over-target message, the structure checks, the hook and beat limits, and that malformed input raises an error. All 8 pass.
test_script_timing.py
import unittest
from pathlib import Path
from script_timing import words, parse, timing, report
HERE = Path(__file__).parent
SAMPLE = (HERE / "sample_script.txt").read_text()
class Tests(unittest.TestCase):
def test_word_count_handles_hyphens_apostrophes_and_numbers(self):
self.assertEqual(words("thirty-three ships in 1805, don't wait."), 6)
def test_parse_kinds_and_labels(self):
parts = parse(SAMPLE)
self.assertEqual([p[0] for p in parts], ["HOOK", "BEAT", "BEAT", "CLOSE"])
self.assertEqual(parts[1][1], "The decision")
def test_timing_is_words_over_wpm(self):
rows, total, _ = timing("[HOOK]\n" + "word " * 25 + "\n[BEAT]\n" + "word " * 50 + "\n[BEAT]\n" + "word " * 25 + "\n[CLOSE]\n" + "word " * 25, wpm=150)
self.assertEqual([r["words"] for r in rows], [25, 50, 25, 25])
self.assertAlmostEqual(total, 125 / 150 * 60) # 50 seconds
self.assertAlmostEqual(rows[0]["seconds"], 10.0)
def test_sample_script_numbers(self):
rows, total, problems = timing(SAMPLE, wpm=150, target=60, max_hook=8)
print(report(SAMPLE, wpm=150, target=60))
self.assertEqual([r["words"] for r in rows], [18, 36, 27, 18])
self.assertEqual(sum(r["words"] for r in rows), 99)
self.assertAlmostEqual(total, 99 / 150 * 60) # 39.6 seconds
self.assertEqual(problems, []) # no problems at 150 wpm
def test_slower_reader_goes_over_target_and_is_told_by_how_many_words(self):
_, total, problems = timing(SAMPLE, wpm=90, target=60)
self.assertAlmostEqual(total, 66.0)
self.assertTrue(any("over the 60s target by 6.0s" in p and "9 words" in p for p in problems))
def test_structure_problems(self):
_, _, problems = timing("[BEAT: a]\nsome words here\n[BEAT: b]\nmore words here\n", wpm=150)
text = " | ".join(problems)
self.assertIn("should open with [HOOK]", text)
self.assertIn("should end with [CLOSE]", text)
def test_long_hook_and_long_beat_are_flagged(self):
s = "[HOOK]\n" + "word " * 40 + "\n[BEAT: slow]\n" + "word " * 60 + "\n[BEAT: ok]\nshort one\n[CLOSE]\nbye now\n"
_, _, problems = timing(s, wpm=150)
self.assertTrue(any(p.startswith("hook runs 16.0s") for p in problems))
self.assertTrue(any("beat 'slow' runs 24.0s" in p for p in problems))
def test_bad_input(self):
with self.assertRaises(ValueError):
parse("no markers at all")
with self.assertRaises(ValueError):
parse("stray text\n[HOOK]\nhello")
if __name__ == "__main__":
unittest.main()
Where this runs out
The tool counts words; it doesn't hear them. It can't tell that a sentence is hard to say, that a pause is needed after a dramatic line, or that a beat is boring. It also treats every word as the same length. A script full of long place names will take longer than the word count suggests, so after the arithmetic, read the script aloud against a stopwatch and trust that over the tool.
The limits I set (8 seconds for a hook, 20 for a beat, two to five beats) are my defaults, set to enforce the shape I described. They are not rules from any platform. Change them with the command-line options or by editing the function arguments if your style differs.
Every number needs a source
In a minute of narration, one wrong date or figure is a large share of what the viewer takes away. I'd keep a short list beside the script: each factual claim, where it came from, and whether I saw the source myself. The post on source-checking describes a routine for this. And any footage or images you cut to need a rights check of their own, which the archival footage post covers.
What I haven't verified
- That this structure suits your audience. I haven't tested it on viewers, and I have no retention or engagement data to share.
- Any platform's length limits or what it recommends for pacing. I haven't read or relied on them here.
- A "right" words-per-minute figure. There isn't one; measure yours.
What I ran this against
- The script-timing tool was run with Python 3.13.5 (standard library only) on 17 November 2026. 8 tests pass. The sample script in the post is made up for the example.
- Every timing in this post is simple arithmetic: words divided by words per minute. I did not record narration for this post, and the 150 words-per-minute default in the tool is a placeholder for you to replace with your own measured pace, not a claim about how anyone speaks.
- The advice on structure and writing for the ear is my own opinion from how I'd approach a script; it is not drawn from outside research, and none of it has been tested on an audience.