Project Status

English · 中文

As of 2026-10-03, with everything merged through PR #50 and the intro film v5. The latest version is v0.2.1 (2026-09-30), and main carries a long list of unreleased changes. Every change is listed in CHANGELOG.md; 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 tagged, the 8-dimension scored review, director mode with decision-first review pages, the spec set up front with text-size floors by where the film is watched, 24 shot recipes and 8 full-film skeletons. All five showcase films were made by agents reading only these docs.
CLI	bin/vh and the commands listed in bin/vh help. tools/ci.sh runs on each pull request on Linux and macOS: shell, Python and JS syntax, a ban on commands that exist on only one platform, docs checked against the CLI, smoke tests of help, -h on every command, types, effort, style list, new (with --watch, --res and style references), style apply, install-skill, tts dependency selection, mux, gif, recipes, storyboard, review and readcheck (storyboard pages must come out byte-identical on a second run), and a static scan of every Blender style scene with a check for its GPL header.
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), and --align gemini. gemini-lite uses the same API 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 31 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. The intro film v5 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. The 28 swatches of the time and films 00–03 were re-rendered on it with no repetition warning.
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. Checked by measurement: pitch, level, damping, repeatability.
Styles	31 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	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 (Metal 92 dB, EEVEE 85 dB in the same test), so Blender swatches render on the CPU. The intro film's opening rendered on Metal: three frames re-rendered out of order in a fresh process stay above the 45 dB line.
Colour	Delivered mp4s are limited-range BT.709 with all four colour tags, the hand-drawn engine included. An audit on 2026-10-01 found two showcase films off that rule (01 and 03) and re-encoded them. bin/vh check now reports the colour format.

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 and no export opened in an editor. The tools its docs describe (gap probe, seam metrics, edit-list compiler) don't exist yet; transcript-cut.mjs is the quick route.
• Blender guide (engines/blender.md): partly verified. Blender 5.2.2 is installed on the maintainer's Mac; the tabletop-miniature swatch and the intro film's 15.8 s opening were rendered with it, and the smoke-test results (determinism on the CPU, Metal and EEVEE, speed, the sandbox, fonts, API changes) and the lessons from a million-point scene are written back and marked. A few smoke-test items, and the guide's own build and render commands, haven't been run yet. The sandbox is macOS-only (sandbox-exec); on Linux, render only Blender scenes you have read.
• Generative video + code (playbook/05): reorganised by task, with dated market and ledger pages checked against the official pages on 2026-10-01, and three helper tools (tools/motion.py, tools/match_grade.py, tools/grain_est.py) 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.
• dashscope and elevenlabs voices: written from the official docs, not yet run against the live APIs. ElevenLabs word timing groups its per-character timestamps into words (PR #7, merged); that is not live-tested either.
• Songs with vocals: ElevenLabs Music and local song models are reserved interfaces. Songs are imported from a service such as Suno.
• 3D and shader films: no type doc yet, one worked example (showcase 04, with its Blender opening).
• Linux: covered by CI, with a round of 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, and the three newest end on a lowest score of 7 (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.
• The final mixes haven't been judged by ear. Agents can't hear, so the swatch scores and the film mixes were measured. The maintainer heard first candidate mixes of films 00–03 and the flagged narration spots in 02, not the final profile mixes end to end, and no per-pair listening verdicts were recorded for the swatches. The seven-feature distance between soundtracks can't hear a melody or a harmony.
• Qwen3-TTS 0.6B on short English lines. It can keep mumbling for seconds after the words. Mitigations: Aiden is now the default English voice (Ryan went wrong on 9 of 40 lines across 8 runs, Aiden on none of 25); provider silence at line edges is trimmed; --align gemini flags run-on lines. Re-run a flagged line, use a 1.7B model, or switch to gemini.
• Audio QA blind spots. The pumping check misses long, shallow dips (only the −12 dB dropout check catches them); the cue check normalizes to the loudest onset and can't tell whose onset it found, so a cue can pass on the score's own onset or on a second note of the same sound; clicks are warnings for a human ear.
• 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; and the music's own room (reverb, width) isn't wired into bin/vh music yet.
• Beat detection. bin/vh beats can report half the real BPM on syncopated music, and plucked bass in the kick range is counted as kicks.
• Where built-in transitions land. The plain whoosh peaks about 34 ms after its landing point, and a shaped or varied swell lands on the middle of its loudest 50 ms; swish_rev, tape and riser end on their landing point with the energy earlier (swish_rev about 100–280 ms, tape about 0.5 s); shimmer starts on it and peaks 50–400 ms later.
• Gemini quotas. Tier 1 allows 10 transcriptions a minute and about 100 a day, so long scripts wait on 429s, and a spent daily quota stops the run (--resume continues it later).
• Docs language. The workflow docs are Chinese-first. The README, CHANGELOG, showcase notes and research notes are in English.
• Windows isn't covered: the requirements list macOS or Linux, and CI runs only those two.

Platforms

CI runs tools/ci.sh on ubuntu-latest and macos-latest for every pull request; on macOS it runs bin/vh under the system /bin/bash 3.2 that Macs ship with. Both checks must pass before anything merges into main.

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	Director mode, decision tools, concept first, the spec up front, shot recipes and full-film skeletons, four new playbook docs, mix profiles, a larger music engine and SFX variants, sound for every swatch and film, 31 styles (one rendered in Blender), the intro film v5, type 09 and the Blender guide, install and mirror docs, research notes (table below); also -h for every command, Linux fixes, fixes from a full review of v0.2.1, CI and branch rules, camera language for video models, ElevenLabs word timing, community files, and a plain MIT license with GPL-3.0-or-later for the files that import bpy

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	PR
Director mode	own / review / delegate for twelve decisions (concept and spec joined later), checkpoints E0–E5, bin/vh review pages, DECISIONS.md, templates for script, character and packaging	#19
Concept first	playbook 12 and concept cards at gate ①; the checklist's floor items tagged and every other taste rule a default a concept may override; the eighth score, 立意; a case study of five community films; five full-film skeletons that start from a concept; research note 06, an A/B of the workflow against floors only	#44, #43, #45, #46
Spec up front	Watch on and Resolution in the BRIEF, filled by bin/vh new (--watch, --res); text-size floors by where the film is watched; 4K written at 1080p and rendered at twice the size	#47
Decision tools	bin/vh storyboard, rhythm, style compare and apply, cover-preview, music --roll and --length, readcheck --budget and HyperFrames timing, new --aspect and --dir	#25
CLI	bin/vh <command> -h prints the usage instead of running the command; hf-init takes the scaffold's font from the machine, not Google Fonts; check reports the colour format; readcheck checks captions marked data-read="subtitle" as subtitles and captions lengthens short cues	#50, #35, #37, #38
Shot recipes	24 recipes, eight full-film skeletons (three by energy arc, five from a concept), bin/vh recipes list and check	#27, #45
Playbook	09 narrative, 10 hooks and packaging, 11 composition, 12 concept	#23, #44
Music	instrument parts, patterns and buses; plucked-string models; motifs, dynamics and stops; a note map for pictures driven note by note	#13, #16, #20, #24, #41
Mix and SFX	profiles, the mix report, a harder cue check; per-event SFX variants, shaping, six new transitions (21 built-ins), sfx audition, a repetition warning	#21, #39
Styles	tabletop-miniature, the first swatch rendered in Blender (Blender swatch scenes, sandboxed); pastel-ui and y2k-chrome (31 in all); presets attach as references, not templates	#42, #49, #48
Media	28 swatch soundtracks; sound for films 00–03, then 00–03 and the swatches re-rendered on the new SFX; word timings for 02 and 03; BT.709 for the hand-drawn engine, 01 and 03	#31, #32, #40, #36, #28
Intro film	v5: a 15.8 s Blender opening driven by code, handed to WebGL through the same camera, then the one-take body; v3 kept in v3/	showcase/04
Rendering	swatches render on the CPU and come out byte-identical	#17
Experimental	type 09, the Blender guide, generated clips by task with market and ledger pages and three tools	#30, #29, #26
Docs	what gets downloaded, mirrors for mainland China, a HyperFrames primer; research notes; the README's sample films one per row, with request, workflow and sound	#22, #33, #34

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 a line 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.