Skip to content

About

A six-minute technical explainer on eXtreme Programming, built as a codebase: HTML/CSS scenes compiled to video by Hyperframes, with tests guarding citations, caption sync and scene timing. Archived university project.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

XP Hyperframes

A six-minute technical explainer video, built as a codebase instead of a slide deck.

status maintenance node tests licence

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.


Why this is interesting

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 0

How it works

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

Layout

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

Running it

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 browser

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

Deliberately not published

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

Built with

Hyperframes 0.4.31 · GSAP 3.14.2 · Node ≥22 · ffmpeg · Whisper (mlx-whisper on Apple Silicon)

Licence

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

About

A six-minute technical explainer on eXtreme Programming, built as a codebase: HTML/CSS scenes compiled to video by Hyperframes, with tests guarding citations, caption sync and scene timing. Archived university project.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages