用途
guided-music-video 用于制作以歌词为核心的歌词与卡拉OK音乐视频。画面随节拍运动，文字随人声逐字点亮，每个场景对歌词做不同的视觉处理。整个视频是一个 window.renderAt(t) 页面，遵循 make-video 约定；音乐相关部分（helios analyze、节拍图、同步规则）参考 make-video 的音乐文档，本技能在其上补充歌词视频所需内容。
主要能力
歌词时间对齐
按可用条件分为三级：
- Tier 0：用户提供含行时间的 .srt/.lrc，或只有文本。从文件取行时间（或跟随敲击），按音节数把每行时间跨度拆分为词时间，并在文件中标记 "approx": true。精度为行 ±100 ms，词较粗。
- Tier 1：有 Python 环境时，用 demucs --two-stems=vocals 分离人声，再用 stable-ts 或 WhisperX 将已知歌词对齐到音轨。词精度 ±50–100 ms。
- Tier 2：需要词落在辅音上时，用 torchaudio 的 MMS_FA 在人声音轨上做强制对齐，外加起音细化与 Whisper 交叉校验。词起始 ±30–50 ms。
无论哪级，都先把歌曲解码为 WAV 一次，并让分析、对齐与 --audio 使用同一文件，避免 MP3 编码器延迟造成 20–50 ms 偏差。结果转换成一份 lyrics.json，供页面与 helios verify --cues 共同读取，结构包含 approx、lines（text/start/end/first/last）与 words（w/start/end/syl）。
同步规则
- 动作对齐节拍，词对齐人声。词在演唱起点精确点亮，并在终点完全点亮；一行可提前约 0.4 秒暗显；高亮绝不超前于人声。
- 不得伪造时间。按字母数计算擦除速度、或用猜测 BPM 构造节拍网格，会在数秒内漂移。需使用真实词时间与 helios analyze 生成的真实节拍图。
- 按内容查找歌词而非硬编码时间，例如 lyric('through the night').words[0].start，重新计时歌词即重新计时整个视频。
视觉方案与分镜
编码前先写 TREATMENT.md：以随机种子开头，由歌曲与种子生成概念，而非套用默认音乐视频套路。写三个不同概念与三个母题，由种子中可验证的模式（数字串、重复、字母簇）在概念、配色与各段歌词处理方式之间做选择，并记录种子与“模式→选择”映射。方案包含：一段式概念与贯穿变化角色的母题；配色与一个由某时刻或某元素独占的强调色；二到三种字体声音及各自职责；反套路清单（如发光大脑、代码雨、粒子星云、为霓虹而霓虹、库存音频可视化条）；每段的视觉创意而非字面插图；副歌复用同一场景或模板并逐次升级；歌词在每场中的呈现方式（沿曲线运动、逐词键入、压印在表单上、雕刻、笔写、逐块揭开），避免全程同一条普通字幕条。
分镜按 helios analyze 输出的段落与强拍进行，逐段列出时间、歌词首词、镜头内容、歌词处理与转场（Out）。每个镜头都有事件与镜头运动，低能量段落用平静镜头；强度大致为前奏 40%、主歌 70%、副歌 100%；相邻剪辑不重复姿态与构图；转场需有动机（穿过眼睛的变焦、形状变为下一场景、动作衔接剪辑等）。节拍图噪声大时（合成或稀疏音轨），只保留落在拍上的底鼓，段落粗糙时改用歌词内容锚定结构。角色对歌曲做出反应，不做对口型。
构建
从数据推导剪辑，而非手写秒数：用 lastAt 找到一行首词之前最后一个拍点作为切点；当上一词跨越该拍点时，改在词边界切或让镜头穿过拍点不切。一个场景函数通过 params 服务每次副歌，每遍递进。references/lyrics.md 提供卡拉OK配方：逐字形擦除与字距安全位置、完成色突变而非渐变、词起始小弹跳、长音拉伸、行布局与安全区域、笔写歌词。画布上绘制的每个词必须用 window.heliosDrawnText?.add(word) 声明。
校验与渲染
- verify video.html --duration 156 --cues lyrics.json：检查每个词在其时间出现在屏幕上。
- sheet video.html --strip 28.4:29.2 --fps 30：把一段帧拼成图检查副歌起始。
- sheet video.html --at 9.4,28.6,47.8,67.0 --cols 4：检查各段首帧。
检查要点：每段开始新想法是否清晰、副歌是否逐次升级；词起始帧是否准确、不提前；歌词是否在标题安全边距内（1080p 至少 96 px）并与背景形成足够对比；转场是否吞词（verify --cues 会指出）；节奏是否被锁定在半速、倍速或 2/3 速（可用 analyze --tempo-range 重跑）。
渲染命令：npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 156 --audio song.wav --preset medium，再用 check video.mp4 检查结果。
适用场景
适合为用户自有歌曲制作歌词视频、卡拉OK视频，或需要对歌词逐词逐音节精确同步的代码驱动音乐视频。需要具备 helios 视频项目与命令行工具的使用环境；高精度对齐依赖 Python、demucs、stable-ts/WhisperX 或 torchaudio MMS_FA 等工具。
限制
歌词通常受版权保护，应使用用户自己的歌曲与歌词，不要把歌词文本提交到公开示例。所有时间必须来自真实对齐与真实节拍分析，不能用估算。画面中人物不应伪造演唱对口型。