Intro film v5: a Blender galaxy opening, 150.5 s, and HD players in the READMEs

.gitignore

@@ -13,7 +13,17 @@ projects/*
 __pycache__/
 *.pyc
 
-# showcase 04: proxies rebuilt by tools/make_clips.sh from showcase 00–03; the film's regenerable audio
+# showcase 04: proxies rebuilt by tools/make_clips.sh from showcase 00–03; the film's regenerable audio;
+# the film atlases (tools/opening_export.sh, film_atlas.py, ai_atlas.py), the Blender frames and plate, the grid state
 showcase/04-intro-film/assets/clips/
 showcase/04-intro-film/audio/*.wav
 showcase/04-intro-film/audio/sfx/
+showcase/04-intro-film/audio/sfxlib/
+showcase/04-intro-film/audio/stems/
+showcase/04-intro-film/assets/plate.mp4
+showcase/04-intro-film/assets/state.json
+showcase/04-intro-film/assets/hero-earth.png
+showcase/04-intro-film/assets/films*.jpg
+showcase/04-intro-film/assets/films*.png
+showcase/04-intro-film/blender/out/
+showcase/04-intro-film/opening/node_modules

AGENTS.md

@@ -100,7 +100,7 @@ effort 管 agent 自己查得多细，导演模式管人拍板哪些事，两个
 |---|---|---|---|
 | 数学、物理、算法的原理讲解，3b1b 风格 | `video-types/01-math-science-explainer.md` | Manim CE | `showcase/03-math-fourier/`、`cases/explainer-code2video.md`、`cases/opus55-gallery.md` 第 7 节（抽象代数宣传片深读） |
 | 知识科普短视频，竖屏或横屏（抖音、B站、小红书、视频号、Shorts） | `video-types/02-knowledge-short.md` | HyperFrames | `showcase/02-short-leo-doppler/`、`cases/explainer-interstellar-blackhole.md` |
-| 产品宣传、发布片、App 或 SaaS 介绍、功能演示 | `video-types/03-product-promo.md` | HyperFrames | `showcase/00-promo-launch-film/`、`showcase/04-intro-film/`（一镜到底 3D + 代码作曲）、`cases/promo-hyperframes-launches.md` |
+| 产品宣传、发布片、App 或 SaaS 介绍、功能演示 | `video-types/03-product-promo.md` | HyperFrames | `showcase/00-promo-launch-film/`、`showcase/04-intro-film/`（Blender 星河开场 + 一镜到底 3D + 代码作曲）、`cases/promo-hyperframes-launches.md` |
 | 歌词视频、MV、配合音乐的动画 | `video-types/04-lyric-music-video.md` | ClaudeAnimationBase（手绘）或 HyperFrames（排版） | `cases/mv-pdoom.md`、`cases/mv-functional-emotions.md`、`cases/mv-claude-pop.md` |
 | 数据故事、动画图表、数字可视化 | `video-types/05-data-story.md` | HyperFrames + SVG | — |
 | 论文讲解、会议视频、学术报告 | `video-types/06-paper-explainer.md` | Manim（机制）或 HyperFrames（结构、结果） | `cases/paper-paper2video.md`、`cases/explainer-code2video.md` |
@@ -116,7 +116,7 @@ effort 管 agent 自己查得多细，导演模式管人拍板哪些事，两个
 | 3 分钟以上的长片，或靠故事、谜题推进的片子（角色短片、长讲解） | 主类型文档，加上 `playbook/09-narrative.md`（骨架、节拍表、张力曲线、换挡） | 按主类型 | — |
 | 要发短视频平台：开头钩子、标题、封面 | `playbook/10-hooks-and-packaging.md`，加上主类型文档 | 按主类型 | — |
 | 要写有篇章、有主题的配乐（MV、介绍片和发布片、45 s 以上靠音乐撑起结构的片子、`studio` 档位，或者人要亲自定主题和 BGM） | `playbook/11-composition.md`；`score.json` 的写法见 `playbook/04-audio.md` | `bin/vh music` | — |
-| 3D 场景、着色器短片（Three.js） | 暂无专门的类型文档：以 `03-product-promo.md` 的运动规则为准，加上 `playbook/08-vfx-and-motion-sources.md`（一镜到底、特效预设栈、子帧运动模糊）。要路径追踪的光影（玻璃、皮肤、体积光）、物理模拟或真实景深时，读 `engines/blender.md`（部分验证：风格样片 `tabletop-miniature` 已用 Blender 5.2.2 渲染，项目用的命令还有几条没跑过；渲染时间先渲 3–5 帧校准） | HyperFrames + Three.js 层；重光影的镜头用 Blender | `showcase/04-intro-film/`、`cases/opus55-gallery.md` 的 3D 一节和第 6 节（Austerlitz 长片深读） |
+| 3D 场景、着色器短片（Three.js） | 暂无专门的类型文档：以 `03-product-promo.md` 的运动规则为准，加上 `playbook/08-vfx-and-motion-sources.md`（一镜到底、特效预设栈、子帧运动模糊）。要路径追踪的光影（玻璃、皮肤、体积光）、物理模拟或真实景深时，读 `engines/blender.md`（部分验证：风格样片 `tabletop-miniature` 和介绍片 v5 的开场已用 Blender 5.2.2 渲染，项目用的命令还有几条没跑过；渲染时间先渲 3–5 帧校准） | HyperFrames + Three.js 层；重光影的镜头用 Blender | `showcase/04-intro-film/`、`cases/opus55-gallery.md` 的 3D 一节和第 6 节（Austerlitz 长片深读） |
 | 想要新点子、立意，一句话需求想做得出彩，或者不想千篇一律 | `playbook/12-ideation.md`，再加主类型文档 | 按主类型 | `cases/oneshot-five.md`、`cases/explainer-interstellar-blackhole.md` |
 | 想要某种风格、参考某部名作，或者不想每支片子都一个口味 | `styles/README.md`，再读选中预设的 `styles/<slug>/STYLE.md` | 随主引擎 | 每个预设的 `media/swatch.mp4`，总览 `styles/gallery.jpg` |
 | 想知道某种镜头怎么动（开场、字卡、转场、卡点、收尾），或想要"专业的节奏" | `recipes/README.md`，再读 `recipes/sequences/` 里合适的骨架 | 随主引擎 | `cases/promo-video-shotcraft.md` |

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+**The intro film v5: a Blender-rendered galaxy of films, then one take through the repo (150.5 s)**
+- Why: at gate ① the maintainer found the old opening "not stunning enough… the waterfall looks like the same film over and over" and asked for glass, cosmos and a starry sky that makes you dizzy; after a WebGL look-dev, "a bit of a cheap-effects feel… could the films be shown as a galaxy, as stars? Or use Blender? Hollywood blockbuster quality"; after the first Blender version, less jitter, Blender only for the first 15 s, "just make the final version". The old film also showed stale numbers (8 types, 9 playbook docs).
+- `showcase/04-intro-film/` is now v5 (v3's docs and media are kept in `v3/`, its source at 7057c74). The opening (0–15.8 s) is path-traced in Blender 5.2 (Cycles, Metal) by `blender/galaxy.py` (GPL-3.0-or-later): numpy computes 1.18 million stars and 16,000 film cards per frame, with `velocity` attributes for motion blur and volume shaders written as expressions (`blender/nodexpr.py`); it runs sandboxed in resumable chunks (`tools/bl.sh`, `tools/bl_render.sh`). Over 15.0–15.6 s it dissolves into a WebGL grid that redraws the same cards through the same camera (`tools/export_state.py` exports both from `galaxy.py` without Blender). The body is v3's one-take world at 80 BPM instead of 90, with 26 holds stretched so every read meets the reading-time floor (`js/tmap.js`; `tools/retime.py` moves the score and the SFX by the same map), today's counts, a wall of the 31 style samples, the opening's films drifting beside the path, and a workflow section rebuilt after review (9 reads instead of 17; gates as doors made of what they review). 109 film sources: 28 shaders (`opening/`), 41 cuts of the repo's own films, 40 AI stills (`assets/ai/`, prompts kept). `tools/build_audio.sh` rebuilds the soundtrack byte for byte; `tools/deliver.sh` renders and encodes.
+- 150.5 s at 1080p30; the Blender opening, 475 frames, rendered in 1 h 28 min on an M3 Max; five fresh-context review rounds (the last: concept 7, hook 7, desktop read 8, motion 8, variety 6, finish 7, accuracy 7, sync 7; round 5's fixes were not re-reviewed, at the maintainer's request); −14.0 LUFS, 62/62 cues within one frame. `media/final.mp4` is a 2.5 Mbit/s two-pass encode whose x264 zones give the Blender opening 3× the bits (48 MB). Eight watermarked 1080p chapters, and the four sample films and the style reel, play inline in the READMEs (GitHub user-attachments, under 10 MB each).
+- README (en/zh): the hero caption and the 04 row describe v5; the Blender section's numbers; `docs/assets/blender-strip.jpg`; galaxy.py in the license note. `video-types/03-product-promo.md`, CLAUDE.md / AGENTS.md (route table), `recipes/seam/gate-as-door.md` follow.
+- Lessons into the playbooks: 08 (atmosphere layers draw first and give way to type; type that must be read stays under the glow threshold; a departure key after a hold takes the hold's tangent; 80 BPM on a 30 fps grid), 02 (camera jitter and lunges are checked with numbers: a frame-difference curve for plates, velocity reversals for keyframed cameras).
+
+**Docs: counts and wording after #41–#50**
+- The overview and architecture diagrams, CITATION.cff, `recipes/README.md`, both READMEs, `playbook/02`, `playbook/04` and `styles/README.md` had counts and wording from before #41–#50 (28 or 29 styles, 12 playbook docs, "20+ repos", 7 scores, "3 weakest spots"). `styles/_swatch/lib.js`: a preset that names its foreground `ink` or `text` (pastel-ui) no longer falls back to magenta.
+
 **`bin/vh <command> -h` prints its usage instead of running the command**
 - Before, `-h` and `--help` reached the command as an argument: `setup -h` ran the whole install, `sync-agents -h` rewrote AGENTS.md, `doctor -h` and `types -h` ran as usual; `sheet`, `check`, `gif`, `hf-init`, `mux` and `beats` took `-h` as a video, project or audio file (`basename`, ffmpeg and libsndfile errors, "no such project", a bash parameter error, or ffprobe's own help), and `qa -h` as a mix (a JSON traceback; `qa --help` printed the docstring but exited 1); `style -h` checked the swatch renderer's npm install and printed `render.sh`'s help, and `style check -h` reached `determinism.sh` as a preset name; `new`, `effort`, `install-skill` and `music` printed a usage but exited 1 (`music --help`: "unknown option"); `tts -h` built the mlx-audio environment before showing its help.
 - Now the dispatcher answers `bin/vh <command> -h|--help` with that command's lines from the help header at the top of `bin/vh` (with their continuation lines) and exits 0. `tts -h` adds `tts.py`'s full option list, read with the plain python3, so nothing is installed first. Commands with a fuller help of their own keep it: `captions`, `readcheck`, `review`, `storyboard`, `rhythm`, `cover-preview`, `voices`, `mix`, `recipes`, `sfx` and `qa`; `qa` now prints its docstring for `-h` or `--help` anywhere in the arguments (also `qa mix -h`) and exits 0. `style check -h` prints its own line, and the header's `style` entry points to `render.sh -h` for the swatch render's other options. Without `-h`, every command behaves as before.

CITATION.cff

@@ -12,7 +12,7 @@ date-released: "2026-09-30"
 abstract: >-
   A video-as-code harness that turns coding agents such as Claude Code and Codex into a multi-genre video studio:
   every frame is a pure function of time, the agent reviews its own rendered frames, and people approve the outline,
-  the storyboard and the first draft. It ships 8 video types, 28 style presets with rendered swatches, and code-composed
+  the storyboard and the first draft. It ships 9 video types (one experimental), 31 style presets with rendered swatches, and code-composed
   music, voice, captions, mixing and audio QA.
 keywords:
   - video-as-code

CLAUDE.md

@@ -97,7 +97,7 @@ effort 管 agent 自己查得多细，导演模式管人拍板哪些事，两个
 |---|---|---|---|
 | 数学、物理、算法的原理讲解，3b1b 风格 | `video-types/01-math-science-explainer.md` | Manim CE | `showcase/03-math-fourier/`、`cases/explainer-code2video.md`、`cases/opus55-gallery.md` 第 7 节（抽象代数宣传片深读） |
 | 知识科普短视频，竖屏或横屏（抖音、B站、小红书、视频号、Shorts） | `video-types/02-knowledge-short.md` | HyperFrames | `showcase/02-short-leo-doppler/`、`cases/explainer-interstellar-blackhole.md` |
-| 产品宣传、发布片、App 或 SaaS 介绍、功能演示 | `video-types/03-product-promo.md` | HyperFrames | `showcase/00-promo-launch-film/`、`showcase/04-intro-film/`（一镜到底 3D + 代码作曲）、`cases/promo-hyperframes-launches.md` |
+| 产品宣传、发布片、App 或 SaaS 介绍、功能演示 | `video-types/03-product-promo.md` | HyperFrames | `showcase/00-promo-launch-film/`、`showcase/04-intro-film/`（Blender 星河开场 + 一镜到底 3D + 代码作曲）、`cases/promo-hyperframes-launches.md` |
 | 歌词视频、MV、配合音乐的动画 | `video-types/04-lyric-music-video.md` | ClaudeAnimationBase（手绘）或 HyperFrames（排版） | `cases/mv-pdoom.md`、`cases/mv-functional-emotions.md`、`cases/mv-claude-pop.md` |
 | 数据故事、动画图表、数字可视化 | `video-types/05-data-story.md` | HyperFrames + SVG | — |
 | 论文讲解、会议视频、学术报告 | `video-types/06-paper-explainer.md` | Manim（机制）或 HyperFrames（结构、结果） | `cases/paper-paper2video.md`、`cases/explainer-code2video.md` |
@@ -113,7 +113,7 @@ effort 管 agent 自己查得多细，导演模式管人拍板哪些事，两个
 | 3 分钟以上的长片，或靠故事、谜题推进的片子（角色短片、长讲解） | 主类型文档，加上 `playbook/09-narrative.md`（骨架、节拍表、张力曲线、换挡） | 按主类型 | — |
 | 要发短视频平台：开头钩子、标题、封面 | `playbook/10-hooks-and-packaging.md`，加上主类型文档 | 按主类型 | — |
 | 要写有篇章、有主题的配乐（MV、介绍片和发布片、45 s 以上靠音乐撑起结构的片子、`studio` 档位，或者人要亲自定主题和 BGM） | `playbook/11-composition.md`；`score.json` 的写法见 `playbook/04-audio.md` | `bin/vh music` | — |
-| 3D 场景、着色器短片（Three.js） | 暂无专门的类型文档：以 `03-product-promo.md` 的运动规则为准，加上 `playbook/08-vfx-and-motion-sources.md`（一镜到底、特效预设栈、子帧运动模糊）。要路径追踪的光影（玻璃、皮肤、体积光）、物理模拟或真实景深时，读 `engines/blender.md`（部分验证：风格样片 `tabletop-miniature` 已用 Blender 5.2.2 渲染，项目用的命令还有几条没跑过；渲染时间先渲 3–5 帧校准） | HyperFrames + Three.js 层；重光影的镜头用 Blender | `showcase/04-intro-film/`、`cases/opus55-gallery.md` 的 3D 一节和第 6 节（Austerlitz 长片深读） |
+| 3D 场景、着色器短片（Three.js） | 暂无专门的类型文档：以 `03-product-promo.md` 的运动规则为准，加上 `playbook/08-vfx-and-motion-sources.md`（一镜到底、特效预设栈、子帧运动模糊）。要路径追踪的光影（玻璃、皮肤、体积光）、物理模拟或真实景深时，读 `engines/blender.md`（部分验证：风格样片 `tabletop-miniature` 和介绍片 v5 的开场已用 Blender 5.2.2 渲染，项目用的命令还有几条没跑过；渲染时间先渲 3–5 帧校准） | HyperFrames + Three.js 层；重光影的镜头用 Blender | `showcase/04-intro-film/`、`cases/opus55-gallery.md` 的 3D 一节和第 6 节（Austerlitz 长片深读） |
 | 想要新点子、立意，一句话需求想做得出彩，或者不想千篇一律 | `playbook/12-ideation.md`，再加主类型文档 | 按主类型 | `cases/oneshot-five.md`、`cases/explainer-interstellar-blackhole.md` |
 | 想要某种风格、参考某部名作，或者不想每支片子都一个口味 | `styles/README.md`，再读选中预设的 `styles/<slug>/STYLE.md` | 随主引擎 | 每个预设的 `media/swatch.mp4`，总览 `styles/gallery.jpg` |
 | 想知道某种镜头怎么动（开场、字卡、转场、卡点、收尾），或想要"专业的节奏" | `recipes/README.md`，再读 `recipes/sequences/` 里合适的骨架 | 随主引擎 | `cases/promo-video-shotcraft.md` |