Dicklesworthstone/jeffs_math_explainer_videos

<###>jeffs_math_explainer_videos

<div align="center">

<img src="docs/media/hero.webp" alt="Four shipped 4K60 math explainer videos: Hoeffding's D, How to Count Fish You've Never Seen, The Arithmetic Where 3 × 7 = 9, and The Algorithm Lamport Is Proudest Of" width="100%">

<br/>

A monorepo of narrated, 3Blue1Brown-style 4K math explainer videos, each one written in Rust against franken_manim (native TeX, no LaTeX, no Python) and voiced by FrankenTTS. Every number on screen or in the narration is computed by the scene and pinned against an independent oracle, every narration line is checked by speech recognition and never time-stretched, publication requires continuous audiovisual review, including listening to the finished narration, and a warm, procedurally synthesized score sits under the voice without competing with it.

</div>

> A note on tense. Like franken_manim's README, this one describes the > method in the present tense, because the method is fixed and every video > follows it. What exists today is stated separately and plainly: see > The canonical video catalog. Eleven selected > Michael cuts were public at the 2026-10-15 audit. The catalog preserves their > publication records, earlier cuts and all known future proposals; Beads owns > the work graph. Older build-status prose below is historical and does not > supersede those dated records. Proposed narration improvements are research, > not claims that the current audio has passed new listening tests. > > 2026-10-19 narration incident. The owner rejected the newly published > packing, medical p-value and Golay videos for voice drift, pronunciation, > clipping and cadence. All three were set to Private. Their publication > lacked a demonstrated continuous listening review; technical checks did not > establish acceptable narration. Repairs and new silent chapter previews > remain separate from audio acceptance. They must not be republished without > a new explicit owner instruction.

<###>TL;DR

The goal. Explain genuinely deep mathematics so clearly that a curious 14-year-old follows it, a working programmer could implement it afterwards, and a professional mathematician finds nothing incorrect or misleading and marvels at the clarity. Never by dumbing down: by finding the right picture, the right tiny example, the right order, and by earning every formula.

The problem with the usual way. Explainer videos are usually assembled from tools that cannot check themselves. Numbers are typed into slides, so they drift from the math. Narration is recorded once and stretched to fit the picture, so it sounds smeared. Background music is chosen by taste and mixed by ear, so it masks the consonants that carry the meaning. And the rendering stack (manim + LaTeX + Python + system fonts) is a multi-gigabyte install that renders differently on every machine.

The approach here. Each video is a Rust program:

<###>The corpus

<###>How a video is made

 brief ─► facts + oracle ─► storyboard ─► review R1 ─► script ─► review R2 + audit
   │                                                              │
   │   (every number computed, then pinned)    (one beat per line; prediction pauses;
   │                                             one word per idea; listen windows)
   ▼                                                              ▼
 build: scenes in Rust ─► 540p drafts + layout lint + contact/cue sheets (read every one)
                                                                  │
 narration: FrankenTTS per sentence ─► FrankenWhisper scores ─► best take ─► ASR gate
                                                                  │
 narrated draft ─► score: timeline pass ─► music stems ─► score QA ─► review R3
                                                                  │
 4K60 chapters in parallel ─► PCM master (one fixed gain) ─► strict verify ─► release

Each arrow is a gate that fails closed; the ./x driver runs each step (recording the gates for ./x status, so an agent can resume by asking what is next, is still to come). The full pipeline, with every gate, is §4 of the plan.

<###>Design commitments<###>The sound

The first video's score was a static sine-wave pad per chapter plus bell chimes. Measured against the real narration, the pad's chord tones sat inside the narrator's pitch range, its detuned sines pumped with a 12 dB beating tremolo, and, as actually mixed, it sat only about 5.6 LU under the voice; the chimes put their energy at 2.4–4.8 kHz, exactly where consonants live, and cost up to 0.165 of speech intelligibility at each onset. The new engine (crates/explainer_score, std-only Rust, built to §7 of the plan and docs/research/sound_design/) fixes that by construction:

• warm, analog-style voices (PolyBLEP oscillators with slow random pitch drift,

zero-delay-feedback ladder filters, Juno- and Solina-style chorus, tape wow and flutter, modal marimba/vibraphone/kalimba, FM electric piano, Karplus–Strong plucks, an 8-line FDN reverb);

• the bed 18 LU under the voice during speech and 10 LU under it in authored

gaps, ducked offline with perfect look-ahead from the known narration timeline, with a 1–4 kHz pocket carved while the voice speaks;

• no sustained music inside the narrator's pitch band during speech (measured

per voice from the real takes), no melody starting under a sentence, chords moving every 4–16 seconds, and a musical identity per video (key, palette, a leitmotif in scale degrees);

• sonification only where it teaches, in authored listen windows: in the bakery

video only one process's melody can ever sound at a time, so mutual exclusion is audible and a violation sounds like a bug.

Measured on the Hoeffding narration by the plan's §7.6 QA, the v5 score and the new one, chapter by chapter (8 chapters, the same voice placement and QA code for both):

The A/B itself (the v5 4K video with each soundtrack, loudness-matched) is for the owner's ears; metrics can rule a score out, not in.

<###>Repository layout

crates/
  explainer_score/       the sound engine: DSP, instruments, theory, arrangement,
                         offline duck and pocket, listen-window sonifications,
                         §7.6 QA (std-only Rust)
  explainer_kit/         the shared scene kit: palette, text and math helpers, live
                         readouts, playback, plots, narration and the exact cue
                         log, layout lint, NumPy-parity stats, facts harness,
                         delivery encoder, the shared CLI with the two-pass score,
                         the PCM master, captions and thumbnails
explainer_corpus/        one directory per video (each a Rust crate)
  hoeffding_d/           corpus entry 1 (finished; imported, now on the shared kit)
  capture_recapture/     How to Count Fish You've Never Seen (binary `fish`)
  raptorq_gf256/         The Arithmetic Where 3 × 7 = 9 (binary `gf256`)
  bakery_algorithm/      The Algorithm Lamport Is Proudest Of (binary `bakery`)
  fair_coin/             How to Make a Fair Coin Out of an Unfair One (binary `coin`)
  mental_math/           Mental Math Tricks That Actually Work (and Why) (binary `mental`)
  lie_robotics/          Why Robot Arms Think in Lie Groups (binary `lie`)
  bayesian_search/       How to Find a Lost Submarine (binary `search`)
  visual_proofs/         Proofs You Can See (binary `proofs`)
  matrix_exponential/    What Does It Mean to Raise e to a Matrix? (binary `expm`)
  eigen_engineering/     The One Idea Behind Bridges, Concert Halls and Economies (binary `eigen`)
tools/                   storyboard → script.tsv, facts-check against the oracle,
                         persona review packets, the private-details scan
x                        the driver: build, test, draft, narrated, score, final,
                         master, captions, verify, watch, thumbnail
.github/workflows/       CI: the private-details scan, the storyboard check, and
                         the score engine's tests on every push
docs/
  planning/              the comprehensive plan (architecture, doctrine, all storyboards)
  research/              one memo per topic plus scripts that recompute every number
  reviews/plan_r1/       review round 1 of the plan: three viewers, an audit,
                         engine feasibility, creative direction, and their scripts
.beads/                  the work graph (br): what to build next, and in what order
AGENTS.md                rules for coding agents working here
LICENSE                  MIT with an OpenAI/Anthropic rider

Still to come, per the plan's §3: templates/explainer/ (./x new) and the driver's gate tracking (./x status).

<###>Building

Every video builds the same way. The workspace pins franken_manim by git revision, so nothing else needs to be checked out:

git clone https://github.com/Dicklesworthstone/jeffs_math_explainer_videos
cd jeffs_math_explainer_videos
cargo test --release -p hoeffding_explainer   # rustup fetches the pinned nightly; first build fetches the FrankenSuite (~6.5 GB cargo home)
cargo build --release -p hoeffding_explainer
target/release/hoeffding stats  # every number the video shows
target/release/hoeffding render 01_hook --res 960x540 --fps 30 --silent --out draft

The newer videos run through the driver, which wraps the same binaries (fish, gf256, bakery; each also has facts, script, chapters):

./x raptorq_gf256 test          # tests, clippy -D warnings, fmt --check
./x raptorq_gf256 facts-check   # every number against oracle.py
./x raptorq_gf256 draft         # 960x540 scratch-voice drafts + layout lint; ./x … sheets
./x raptorq_gf256 narrated      # with the real narration + the cue check and cue sheets
./x raptorq_gf256 score         # the music: timeline pass, then stems with QA
./x raptorq_gf256 final         # 3840x2160@60 chapters; then master, captions, verify
./x raptorq_gf256 watch scored  # one file of the scored draft, to watch

• render needs ffmpeg on PATH; stats, script and cargo test don't.
• A narrated render needs the voice-over WAVs, which are generated, not

committed (see the explainer's README).

• Producing narration uses the owner's FrankenTTS narration skills, referenced

by path rather than vendored here.

• x narrate now requires FTTS generation receipts: the effective seed, voice and

model hashes must match, and the model must have reached EOS. Cache schema 2 retains older takes but does not reuse their weaker receipts. Use the verified build selected by local project.env; an older same-version binary without receipts is refused. This checks termination and provenance, not Michael's accent or perceptual acceptance. See the N10 native checks.

The sound engine and its A/B on the Hoeffding narration (the demo reads the explainer's timeline pass, run with the v5 narration WAVs; see the example's header):

cargo test --release -p explainer_score
HOEFFDING_V5_SOUND=1 target/release/hoeffding render --timeline-only --narration NARRATION_DIR --out RENDER_DIR
cargo run --release -p explainer_score --example score_demo -- RENDER_DIR OUT_DIR

The research scripts run with a plain Python 3 (python3 -I <script>.py); a few need numpy or the raptorq package, as each folder's scripts/README.md says.

<###>Status<###>Limitations

• Narration needs the FrankenTTS skills. The narration pipeline (takes,

scoring, pronunciation probes, the release gate) lives in the owner's published skills and is referenced by path. Without them you can build and render the pictures, but not regenerate the voice.

• Heavy work wants a big machine. TTS, speech recognition and 4K finals run

best on a many-core host (video B's 4K final, 75,359 frames with x264 at CRF 16, took 40 minutes on 36 cores); a laptop can draft at 540p.

• The engine has honest gaps (from the plan's engine review): no 2D camera

pan or zoom on the fast route, no bloom, a few Greek letters drawn in variant forms, 3D only on a slower CPU route. The videos work around each one, and §14 of the plan lists them for upstream.

• Renders are not in git. At 200–300 MB, a 4K master is over GitHub's

100 MB file limit; finished cuts are published as release assets.

<###>FAQ

Why Rust and franken_manim instead of manim? One binary, native TeX with no LaTeX install, deterministic output, and live readouts recomputed from the picture every frame. A real-world measurement: the Hoeffding explainer's binary is 9.2 MB; making the same kind of video with legacy manim means installing a LaTeX distribution and a Python stack of 0.9–11 GB.

Why so much process for a video? Because the failure modes are real and were all hit: a number on screen that drifted from the math, a narration stretched until it smeared, an "always" that was false with ties, a chime that buried a consonant at the moment of a reveal. Each gate exists because of one of those.

Are the videos AI-generated? The narration voice is synthetic (FrankenTTS), and AI agents write much of the code and the first drafts under the owner's direction. The mathematics is checked by code, not by trust: every number against an oracle, every claim in a fact sheet with its source, every quote verbatim.

Can I use the research? The memos and scripts in docs/research/ are part of this repository and carry its license.

<###>About Contributions

Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

<###>License

The source code, research memos and scripts in this repository are licensed under the MIT License with an OpenAI/Anthropic Rider, Copyright (c) 2026 Jeffrey Emanuel (see LICENSE). The rider withholds all rights from OpenAI, Anthropic, their affiliates, and anyone acting on their behalf, including any use of the software or derivative works in a machine-learning dataset, training corpus, evaluation harness, or pipeline. In any conflict between the rider and the rest of the license, the rider controls. Short quotations from published works in the research memos are attributed to their sources.

<###>See also

• COMPREHENSIVE_PLAN_FOR_JEFFS_MATH_EXPLAINER_VIDEOS.md: the plan (revision 2): mission and the three viewers, the engine's verified capabilities, the repository architecture, the production pipeline and its gates, the pedagogy, visual and sound doctrines, beat-by-beat storyboards for every new video, testing, workstreams, risks and decisions.
• AGENTS.md: rules for agents working in this repository.
• franken_manim: the animation engine.
• FrankenTTS and FrankenWhisper: the voice and the ears.