A six-minute technical explainer video, built as a codebase instead of a slide deck.
Archived. This was a one-off university assignment, finished in Semester 1 2026 and kept public as a portfolio piece. It is not maintained, has no roadmap, and issues and pull requests are not being monitored. It is here to read, not to depend on.
Every frame of this presentation is authored HTML and CSS. Narration, captions, scene timings and citations live in a single JSON manifest, and the video is compiled from that source by Hyperframes, HeyGen's agent-native video framework. There is no video editor in the loop and no timeline to drag — changing the presentation means editing text and re-rendering.
The subject matter is eXtreme Programming, and the build is an argument for its central claim. If a video is a compiled artefact, it can have tests, guard rails and a deterministic build. So it does.
The novelty is not that a video was generated. It is that the parts of a video that normally rot silently — a citation that no longer matches its source tag, a caption that drifts out of sync after a re-record, a scene that overruns the time limit — were turned into failing tests.
That mattered because most of the content was authored by coding agents against
AGENTS.md. Agents are fast and confident, and confident is the
dangerous half. Prose review does not reliably catch a reference number that
quietly shifted from [7] to [8] across three files. A test does.
| Failure mode | Guard |
|---|---|
| On-screen citation disagrees with the reference list | test/reference-consistency.test.mjs cross-checks source-tags.json, every scene's citationRefs, the rendered source tags and docs/references.md |
| Re-recording one scene desyncs everything after it | cascadeSceneTimings shifts all downstream scenes by the duration delta and rewrites the HTML timing attributes |
| Captions drift from the spoken audio | Word-level Whisper timestamps are anchored to manifest cues, not hand-typed |
| An anchor points at words nobody actually said | buildCueAnchorMap resolves animation anchors against real transcript cues and reports unresolved ones rather than inventing a timing |
| A deliberate timing decision gets quietly reverted | test/cue-anchors.test.mjs pins the loop tracer to the diagram's own animation rather than the spoken cue — a choice that looks like a bug until you watch it |
| Layout breaks the visual contract | static-layout-check.mjs rejects visible scene numbers and stray meta commentary |
| Renders start before the media is ready | private-media:check verifies all 23 required media files exist first |
The whole suite is dependency-free and runs on the Node built-in test runner:
node --test
# tests 23 pass 23 fail 0scene-manifest.json ──┬──► compositions/*.html (timing attributes)
single source of ├──► assets/private/captions.vtt
truth for content └──► docs/references.md ◄──► source-tags.json
│
assets/private/*.mov │ ffmpeg: speech cleanup
│ │ + two-pass EBU R128
└──► *.mp4 ──► Whisper ─────┘
word timings
│
hyperframes render ──► 1920×1080 @ 30fps
One source of truth. scene-manifest.json holds narration, cue text,
word-level timings, durations and citation references for all 11 scenes. Nothing
is duplicated into a separate transcript or subtitle file — those are generated.
Content changes cascade. Re-record scene 3 and every later scene's start time,
the HTML data-start and data-duration attributes, and the WebVTT file all
update from the measured media duration. --dry-run reports the new runtime
before anything is written, which matters when the hard limit is 6:00.
Audio is processed, not just recorded. A nine-stage ffmpeg chain — high-pass,
low-pass, FFT denoise, mud cut, presence boost, de-esser, compressor, two-pass
loudnorm to about −16 LUFS, true-peak limiter — turns inconsistent laptop-mic
takes into something uniform. It is honest about its limits: it cannot repair a
clipped or reverberant recording, and AGENTS.md says so rather
than pretending otherwise.
The design system is enforced, not documented. DESIGN.md
defines a semantic palette where each colour carries narrative meaning — blue for
the active feedback loop, green for passing CI, red for failures. Values trace
back to tokens in src/base/tokens.css; ad-hoc colours are a review failure.
scene-manifest.json Canonical content: narration, cues, timings, citations
compositions/ One HTML file per scene (11 scenes)
src/base/tokens.css Design tokens — the only place raw values live
src/styles/, src/ Shared layout, components, icon library
scripts/ Caption generation, audio processing, manifest validation
test/ 23 tests: citations, timing cascade, cue anchors
docs/references.md IEEE-style reference list
source-tags.json Citation key → reference number → URL
AGENTS.md The contract coding agents work against
DESIGN.md Visual system and its rationale
npm install
npm run validate:manifest # structural check on scene-manifest.json
npm run pacing # per-scene and total runtime report
npm test # 23 tests, no dependencies needed
npm run layout:check # static layout contract
npm run preview # live preview in the browserThe rendered video and its media are not in this repository, and npm run render
will not work without them. The presenter footage is a face on camera next to a
student card, so assets/private/ is gitignored and stays that way. What is here
is the machinery: the compositions, the pipeline, the guard rails and the tests,
all of which run standalone.
- Presenter video and audio. Face and identity footage. Never committed.
- The student number. It was in the original history and has been removed from every commit in this published copy; scene 01 shows a masked placeholder.
- The course task sheet and marking rubric. UQ's material, not mine to republish, and of no use to anyone but a future student who should not have it.
Hyperframes 0.4.31 ·
GSAP 3.14.2 · Node ≥22 · ffmpeg ·
Whisper (mlx-whisper on Apple Silicon)
Code and build tooling are MIT — see LICENSE. The presentation
narrative, reference list and design documents are academic work by the author;
the cited sources belong to their respective authors and are credited in
docs/references.md.
Michael Blauberg · CSSE3012, University of Queensland · Semester 1, 2026