Project Status

English · 中文

As of 2026-10-29, with everything merged through PR #167. The latest version is v0.2.1 (2026-09-30); everything since is on main and listed under Unreleased in CHANGELOG.md. The tools themselves are in the README's What's in the box; plans are on the Roadmap.

Works and has been tested

Area	State
Workflow	The CLAUDE.md router, 9 type docs (09 experimental), playbook 00–12, 11 templates, concept cards at gate ①, the 20-item checklist with its floor items, the 8-dimension scored review with caps on rounds (at most 10 whole-film reviews a film, 5 tries at one problem), three effort levels and director mode, the spec set up front with text-size floors by where the film is watched. Taste rules are defaults a concept may override; the floors are a short list. All five showcase films were made by agents reading only these docs.
Stops	bin/vh gate builds a stop's decision-first review page in one command; at studio the stop is the review desk (bin/vh desk), where the reviewer ticks, comments and submits while the agent waits in the background. bin/vh status and activity say where a project stands and what ran. A whole standard or studio film doesn't render before gate ① is on record.
CLI	All 65 commands come from one table, tools/commands.json: bin/vh -h, every bin/vh <command> -h, bin/vh commands (by pipeline stage) and the command line in CLAUDE.md are printed from it, and CI checks they match what bin/vh dispatches. Usage errors exit 2. bin/vh doctor reads tools/modules.json, the 39 outside programs, packages, models and services, and --probe calls each service once at an endpoint that costs nothing.
Rendering	Any web-page engine that meets the page contract (window.film) gets bin/vh frames, render, determinism and patch. render draws one-GOP chunks in parallel browsers, resumes a stopped or failed render, estimates a long one before it starts, keeps each render as a version (bin/vh versions), and takes --motion-blur N (sub-frames averaged, a cut still a cut) and --alpha (ProRes 4444 to lay over footage). patch redraws a few seconds of a finished film.
Edit lists	edit.json (bin/vh edit) lays a film out as a row of pages, images, colours, slates, footage clips, other projects' films and sound tracks. edit init turns the shot table into slates timed as planned, which is gate ②'s full-length animatic. A chunk cache means a render after a change draws only the entries that changed; check, patch and deliver read the same list, and a film with a slate left can't be delivered.
Engines	HyperFrames 0.8.202, with its block registry (bin/vh hf catalog, add); canvas-film, the narration-driven canvas engine, with a Three.js layer for GLB models and their clips; ClaudeAnimationBase; Manim CE, with ManimGX as an optional backend (on showcase 03: about 5× faster, the same film to the eye, not the same pixels; research note 08); Blender for path-traced shots or for preparing a 3D asset. bin/vh model3d check reads a model before it goes in (with --blender, checks run in Blender: faces fighting, parts inside out), and bin/vh hdri takes a CC0 environment map from Poly Haven.
Material	bin/vh footage (Internet Archive, Wikimedia Commons, NASA: only the seconds you need), image (generated pictures; checked live on 2026-10-26), sfx and bgm search and pick (your own sound library and Openverse), music --provider lyria (checked once live on 2026-10-26), and cast (a project's characters, costumes, props and sets as settled reference pictures). Every file goes on one asset ledger (bin/vh assets) with its source, licence and cost, assets check compares it with what each page actually loaded, and a paid call is held against the project's budget before it is made. CI tests the networked commands offline, against recorded answers.
Library	32 styles, 71 shot recipes (each with a code sketch has its rendered sample sheet), 10 whole-film skeletons, 24 shot-grammar cards (a shot's camera line on the storyboard page), 5 motion components (a spring scene, a page turn, paper transitions, a chapter bar, a build-up of pieces). bin/vh know says what the repo knows about a few words before anyone reads the docs.
Voice	Tested end to end: qwen (Chinese and English), say, edge (English), gemini (Chinese and English, live on 2026-09-30, including dialogue, joined takes and designed voices), minimax (tested against the API on 2026-10-07, one request a take, timed by its own subtitles), and --align gemini. --align local times words with Whisper on the machine, with no key or quota. bin/vh pace evens out the pace of the lines in one take without synthesizing again. gemini-lite uses the same API as gemini but has no separate live test on record.
Captions, music, SFX, mix, mux, QA	Tested end to end. The four showcase films 00–03 and the swatches are mixed with profiles and pass the QA gates on the WAV and on the mp4: no digital silence, every cue within one frame, −14 LUFS and under −1.5 dBTP after the AAC encode, the same bytes on every rebuild. qa reads the score (a note's attack isn't a click, a rest isn't a dropout) and says why for each finding; qa --listen N cuts out the places a person should hear. mux refuses a failed or stale mix. The intro film is mixed with the promo profile; its checks are in its README.
Sound effects	21 built-ins. Each event gets its own variant along a walk for that sound through the film, can be shaped to its move, and bin/vh sfx audition plays a family; bin/vh qa warns when a sound repeats three or more times in a row.
Music engine	Instrument parts, motifs, dynamics, the plucked-string models and the note map are deterministic, and each engine change was checked to leave existing scores rendering the same bytes. Film declarations and project scripts read one rendered music map.
Checks	bin/vh check compares the film with its BRIEF (length, frame, frame rate, a 4K render against the approved 1080p cut) and finds black, frozen or silent stretches, one-frame glitches, flashes, still stretches, cuts that flash, subtitles too short to read, colour tags and loudness, and names a way out of each finding. textcheck and fonts measure text in the Chrome that renders the film (covered, too faint, out of frame, a character missing from its font); readcheck and cues check reading time and where cues landed.
Styles	32 presets, each with a rendered swatch and a soundtrack of its own, audio QA and a determinism check; tabletop-miniature is a Blender scene.
Determinism	Every frame is a function of t, checked by bin/vh determinism on lossless frames. ClaudeAnimationBase frames are pixel-identical across launches and render orders, checked with --soft-gl and on a Mac GPU. Swatches render on the CPU with a single-threaded encode and come out byte-identical across runs and worker counts (checked on nine of them). A Blender frame rendered twice with Cycles on the CPU is pixel-identical, so Blender swatches render on the CPU.
Colour	Delivered mp4s are limited-range BT.709 with all four colour tags, the hand-drawn engine included; bin/vh check reports the colour format.
CI	tools/ci.sh runs on every pull request: all checks on Linux, and on macOS in two shards side by side (it also runs bin/vh under the system /bin/bash 3.2). Both must pass before anything merges into main.

Experimental or not yet tested live

• Type 09, editing your own footage (video-types/09): written from a survey of similar projects; its thresholds were calibrated on synthetic material only. No real footage has been cut with it yet.
• Generative video + code (playbook/05): organised by task, with dated market and ledger pages and three helper tools checked on synthetic clips. No video model has been called yet, so every threshold about real generated footage is a guess until a first real project.
• Blender (engines/blender.md): partly verified. Blender 5.2 rendered the tabletop-miniature swatch and the intro film's opening; the results of the smoke tests that were run are written back and marked, and a few haven't been run. The sandbox is macOS-only (sandbox-exec); on Linux, render only Blender scenes you have read.
• dashscope and elevenlabs voices: written from the official docs, not yet run against the live APIs, ElevenLabs' word timing included.
• Songs with vocals: not generated here. ElevenLabs Music and local song models are reserved interfaces; songs come from a service such as Suno and are imported.
• 3D and shader films: no type doc of their own yet. A narrated film can carry 3D in canvas-film's Three.js layer; showcase 04, with its Blender opening, is the one finished example.
• Linux: covered by CI, with fixes from an Ubuntu 24.04 setup that are on main but not in a tagged release yet. No local voice on Linux.

Known limitations

• Swatch scores. No swatch has every review score ≥ 8 yet; the median lowest score is about 6 (styles/README.md).
• Concept first is barely measured. Research note 06 compared two films per arm on two one-line requests: the reviewer found the workflow's films more original both times but chose the floors-only film to post both times, and the score means differ by 0.3 and 0.7, likely within run-to-run noise.
• Nobody has judged the final mixes end to end by ear. Agents can't hear, so the swatch scores and the film mixes were measured, and the seven-feature distance between soundtracks can't hear a melody or a harmony. qa --listen now picks the spots for a person, but no listening verdicts are on record.
• Qwen3-TTS 0.6B on short English lines. It can keep mumbling for seconds after the words. Aiden is the default English voice (Ryan went wrong on 9 of 40 lines across 8 runs, Aiden on none of 25), silence at line edges is trimmed, and --align flags run-on lines. Re-run a flagged line, use a larger model, or switch to gemini or minimax.
• Audio QA blind spots, measured and not yet fixed (tools/audio/README.md, 已知局限): the pumping check misses long, shallow dips; the cue check normalizes to the film's loudest onset and can't tell whose onset it found; sounds with no attack (a scrape, a swell) can't be cue-checked; clicks are warnings for a human ear; bin/vh beats can report half the real BPM on syncopated music and counts plucked bass in the kick range as kicks.
• Mix profiles level toward the middle. Each effect moves half way to its class's range, so a badly designed gain_db still shows; a low-frequency hit needs a 1–4 kHz layer, not gain; the music's own room isn't wired into bin/vh music yet.
• Gemini quotas. Tier 1 allows about 10 transcriptions a minute and 100 a day; a spent daily quota fails at once, and --resume continues later (or use --align local).
• Docs language. The workflow docs are Chinese-first. The READMEs, the CHANGELOG, the showcase notes, the research notes and this wiki are in English too.
• Windows isn't covered: the requirements list macOS or Linux, and CI runs only those two.

Versions

Version	Date	Highlights
v0.1.0	2026-09-29	First public release: a router over 8 video types, three review gates, playbook 00–08, 7 templates including the 20-item checklist, 11 case studies, the audio tools (voice, captions, music, 15 SFX, mix), bin/vh, the installer, showcase films 00–03
v0.2.0	2026-09-29	Effort levels; the intro film; the style library (26 presets with swatches); the 7-dimension scored review; bin/vh qa; Gemini TTS; 30 reference repos
v0.2.1	2026-09-30	Directed, beat-snapped narration; --align gemini; two-speaker dialogue; bin/vh voices; bin/vh readcheck; 28 styles
Unreleased	on main	Everything in the tables above and below

Each version is a GitHub Release with a v* tag; its notes are the version's CHANGELOG section.

What is on main and not yet released

Area	What landed	PRs
Concept and taste	concept cards at gate ① and playbook 12; floor items tagged and every other taste rule a default; 立意 as the eighth score; guidance written as advice, not fixed rules; the type docs' bans split into floors and common misuses; a case study of five community films; research note 06	#44, #43, #46, #63, #105, #112
Effort and review	effort levels set iteration, not quality; "just make it" without a level is quick; subagents follow the level; review rounds capped; reading time follows the film's pace; the review desk; gate, status and the activity log; gate ① on record before a whole film	#64, #65, #57, #54, #120, #95, #116
Director mode and decision tools	own / review / delegate for twelve decisions, checkpoints E0–E5, decision-first review pages; storyboard pages, the rhythm map, style comparison, cover preview, the piano roll; covers in other ratios and picked by cue	#19, #25, #91, #107
Ideas and research	bin/vh know, scout and ref, breakdown and looks, concept roulette and board, a target image and a critic for unsure keyframes, a topic card and title formulas; new --from for the next episode of a series	#144, #137, #142, #140, #150, #138, #146
Spec up front	Watch on and Resolution in the BRIEF, text-size floors by where the film is watched, 4K as a render setting; 4:5 and 3:4 frames	#47, #60
Page contract and rendering	window.film and bin/vh frames; render and determinism; the canvas-film engine; long renders in resumable chunks with an estimate; versions, patch by shot, proxies and thumbnails; patch; --alpha; --motion-blur N	#81, #82, #84, #113, #125, #90, #148, #160
Edit lists	pages, images, colours and slates; footage, other films and sound, with their sounds in the mix and the footage's words in the captions; a chunk cache	#157, #158, #159
3D	canvas-film's Three.js layer and model3d check; hdri and the build-up component; Blender for assets and model3d check --blender; ManimGX as an optional backend	#161, #162, #164, #165
Material and the ledger	the asset ledger and a budget for paid calls, and the ledger against what each page loaded; footage; image; the sound library; music --provider lyria; cast	#131, #133, #145, #149, #151, #152, #163
Library	shot recipes (24, then 47 more with sample sheets) and whole-film skeletons; shot-grammar cards; components/; the time map and a skeleton for data along a time axis; styles up to 32 (tabletop-miniature in Blender, pastel-ui, y2k-chrome, iso-anatomy) and the style reel	#27, #45, #154, #163, #143, #109, #117, #42, #49, #123, #124
Sound	music parts, motifs and the note map; mix profiles and the mix report; SFX variants; pace; the minimax voice; qa reading the score; local word timing, the film's loudness in check, places to listen, the off-beat check; one music map; a failed or stale mix refused at mux	#13, #21, #39, #72, #69, #115, #118, #153, #102, #100
Checks	check against the BRIEF, one-frame glitches, how the film moves, subtitles too short to read, a way out of each finding, confirmed alerts; textcheck, fonts, cues, timeline and remap	#59, #55, #93, #94, #147, #110, #68, #89, #85, #83
Delivery	deliver and clean; delivered copies kept through clean	#92, #104
CLI and engines	-h on every command; the command table and bin/vh commands; tools/modules.json and doctor --probe; HyperFrames 0.8.82 → 0.8.202 and its registry (bin/vh hf)	#50, #130, #132, #139, #141
Earlier on main (through #51)	three playbook docs (narrative, hooks and packaging, composition); type 09, the Blender guide and generated clips by task; sound for films 00–03 and a soundtrack for every swatch; word timings for 02 and 03; BT.709 for the hand-drawn engine; byte-identical swatch renders; install and mirror docs; research notes; ElevenLabs word timing	#23, #30, #29, #26, #32, #31, #40, #36, #28, #17, #22, #33, #7
Repo, install and docs	the installer's shallow clone; videos moved to the media release and the history rewritten without them; the intro film v5; the homepage; the READMEs rewritten with their counts checked; CI on macOS in two shards	#52, #53, #58, #51, #76, #166, #167

How releases work

• Every change reaches main through a squash-merged pull request, so each PR is one commit on main.
• A PR with a user-visible change adds an entry under Unreleased in the CHANGELOG.
• A release turns Unreleased into a version heading with its date.
• Each release gets a v* tag, protected by two rulesets: only admins create tags, and nobody can move or delete one. The steps are in CONTRIBUTING.md.