hyper-animator-codex 0.7.0 → 0.8.0

package/skills/hyper-animator-codex/references/shotcraft/references/pipeline.md

@@ -0,0 +1,357 @@
+# pipeline — 八阶段制作流水线
+
+八阶段，方向性问题不进昂贵的逐镜头阶段。
+实证细节来自多支已交付宣传片的复盘（模板片见 `template/`）。
+
+## 目录
+
+- 阶段 0：产品理解与执行约束
+- 阶段 1：视觉方向与 styleframe
+- 阶段 2：功能到镜头映射
+- 阶段 3：分镜与制作放行
+- 阶段 4：最终素材采集
+- 阶段 5：逐镜头实现
+- 阶段 6：声音设计
+- 阶段 7：独立终检与交付
+
+本文件是**自主自由创作**的完整流水线：阶段 0–3 的判断由 Agent 根据项目内容
+自主完成并记录，不逐阶段等待用户确认，然后连续进入阶段 4–7。用户已给出的
+用途、受众、功能、画幅、音频或数据要求都是硬约束。
+
+直接使用 Ink Press 模板不进入本流水线，按 `template/TEMPLATE.md` 的原有替换
+流程执行；模板文档引用阶段 4 时只借用其中的素材采集方法。
+
+**共同创作从 `guided-free-creation.md` 进入本文件时，不要从头重跑。** 该流程
+已经完成并确认阶段 0–3；直接从阶段 4 最终素材采集继续，不重新询问或重新设计。
+
+两处执行原则（实战复盘已吸收）：
+
+1. **最终设计 spec 与分镜共同构成制作放行。** 分镜表长在设计 spec 里
+   （`| # | 时间 | 镜头 | 关键动效 |` 四列）；确认放行不重新打开已确认的
+   业务或创意问题，只补实现必要的未决项。
+2. **验收贯穿全程，不是最后一个阶段。** 每个镜头任务以 `npx remotion still`
+   静帧肉眼验收收尾（产物按版本归档 `out/qa/`），每轮反馈修改后整片重渲。
+   阶段 7 只是把这套贯穿动作升级为对照 aesthetic-rules.md 的正式自检报告。
+
+另注顺序弹性：styleframe 可以先用 HTML 与少量安全预检素材；重要的是**逐镜头
+实现开始前最终素材必须依据已定案的分镜采集**——素材方向错误拖到逐镜头阶段后
+才暴露，代价是整套场景报废。
+
+---
+
+## 阶段 0：产品理解与执行约束
+
+在写视频代码或采集最终素材前，只读检查项目的定位、主要功能、页面状态、视觉
+tokens、启动方式和数据风险。根据项目证据和用户已有描述，生成产品简报与需求到
+执行决策表，明确用途、受众、核心卖点、必须展示功能、时长/画幅/语言、音频和
+数据口径对本片的实际影响。
+
+自主自由创作由 Agent 对缺省项作动态判断并写入设计 spec，不暂停要求用户确认。
+用户指定了 BGM 时，先按 `references/music-beat-sync.md` 分析节奏；未指定时由 Agent
+根据产品与发布场景在阶段 6 选型。公开演示数据可在确认其公开属性后使用；客户、
+个人、内部、密钥、实时或其他敏感数据一律先虚构、脱敏或冻结。
+
+**产出**：产品简报；需求到执行决策表；明确的数据与音频约束。
+
+---
+
+## 阶段 1：视觉方向与 styleframe
+
+**目标**：用最便宜的产物锁定全片色板、字体、光感与运镜气质，
+让所有方向性争论发生在写第一行 Remotion 代码之前。
+
+**具体操作**：
+
+1. 根据当前项目生成最多 3 个文字方向。每个方向附一组**动效性格 tokens**
+   （推导法见下方“品牌→动效参数”表），但不要把 Ink Press 作为固定选项。
+2. Agent 依据产品视觉、用途和受众自主选择最合适的方向，并把选择与取舍写入
+   设计 spec；不暂停等待用户选择。
+3. 对选定方向**不渲染视频、不写 Remotion 代码**，写一个纯 HTML/CSS
+   styleframe 页，包含 2–3 张 1920×1080 静态关键画面。
+4. 用 Playwright/Puppeteer 截图验证字体、色板、材质、构图、光感与信息密度；
+   缓动和运镜速度仍以 tokens、Gallery 样片或短运动测试判断。若已有严格品牌规范
+   或明确参考片，可记录理由后跳过 styleframe。
+5. 若用户给了参考片：下载后 ffmpeg 抽帧（`select=eq(n,…)` 抽 ~100 帧、
+   `tile=4x5` 拼 contact sheet），逐个动画/转场/特效做 motion breakdown，
+   写成"手法｜参考片实现｜取舍"三列表进设计 spec——**选择性适配，
+   不强行套用**。图片参考同理：它描述的是"某一类镜头"的感觉，
+   不是全片风格令。
+
+**品牌→动效参数推导**。不凭手感挑 easing/时长，先把品牌放到两根轴上，
+再从最近的预设起步：
+
+- **能量轴**：低（沉稳/premium/机构感）↔ 高（运动/startup/娱乐）——
+  决定时长、过冲、squash 幅度；
+- **调性轴**：严肃（金融/医疗/enterprise）↔ 活泼（消费/社交/儿童）——
+  决定路径曲直、次级动作多寡。产品视觉本身是证据（锐利几何形→工程感，
+  圆角+亮色→柔和活泼）；用户口述的品牌词覆盖视觉推断。
+
+| 预设（品类） | 主时长@30fps | 入场 easing | 过冲 | squash |
+|---|---|---|---|---|
+| 专业信赖（fintech/enterprise/B2B）| ~21f | bezier(0,0,0.2,1) | 1.0 不弹 | 0 |
+| 精致高端（奢侈品/时尚）| ~48f | bezier(0.4,0,0.6,1) | ≤1.02 | 0 |
+| 活力大胆（体育/游戏/startup）| ~18f | bezier(0.16,1,0.3,1) | 1.12 | 0.25 |
+| 活泼愉悦（消费/社交）| ~27f | bezier(0.34,1.56,0.64,1) | 1.08 | 0.18 |
+| 平静关怀（健康/教育）| ~42f | ease-in-out 对称 | 1.0 | ≤0.04 |
+| 亲和友好（小微/社区）| ~26f | bezier(0.25,0.46,0.45,0.94) | 1.04 | 0.08 |
+
+用法：定预设 → 按两轴微调 → tokens 写进设计 spec。自检两条：
+①用三个词描述成片动效，与品牌词对得上吗；②同一套 tokens 必须同时管
+入场/转场/hold 节奏——一个品牌一种动效嗓音，混用两套读作拼盘。
+注意预设值与库内硬判例冲突时判例赢：落地要弹的场合 y1 必须 >1，
+"专业信赖不弹"指的是无落地隐喻的淡入/推移类动作。
+
+**产出**：选定方向的 styleframe；色板/字体/光感 tokens + 动效性格 tokens；
+（有参考片时）motion breakdown 表。
+
+**常见坑**：
+
+- 用渲染视频做风格提案：太贵，改方向的心理成本也高。静态帧足够定调。
+- 参考驱动的风格 move 全局一刀切：风格化机位逐镜头决定（信息密集的
+  列表/堆叠镜头正视更可读）。
+
+---
+
+## 阶段 2：功能到镜头映射
+
+**目标**：为每个必须展示的功能选定合适的运动语法，不在此阶段提前写完整分镜。
+
+**具体操作**：
+
+1. **先列产品功能清单，逐一对应镜头**。核心功能漏拍等于返工；
+   一种动画手法（飞入/堆叠/翻页）全片只当一次主角，同质化即返工信号。
+2. 扫描 `references/shots/` 全部卡片的 frontmatter，根据用途、能量、建议时长、
+   限制和所需页面状态，为每项功能选择首选与备选卡；Agent 自主定案并记录依据。
+3. 完整读取选中卡片，并按“参考实现”定位准确 demo 源码。没有合适卡片时可新写，
+   但必须在设计 spec 中说明范围与验证风险。
+
+**产出**：功能到镜头映射表；选中卡名、变体、demo 源码和参考样片定位。
+
+---
+
+## 阶段 3：分镜与制作放行
+
+**目标**：把已定案的功能与镜头映射排成有能量曲线的完整镜头序列，并转成帧级
+实施计划。自主自由创作由 Agent 自行放行，不暂停等待确认。
+
+**具体操作**：
+
+1. 先查 `references/sequences/` 有无适用的桥段模板；有则按其填空流程分配段位
+   与帧预算，再把映射好的镜头排成低能量开场→功能段与呼吸位交替→高能量收尾。
+2. **已有指定 BGM 时**：先出音乐结构表（满能量起点/breakdown 拍号，
+   见 music-beat-sync.md §2），镜头边界全部锚到拍号，最强 hit 分给
+   全片 2–3 个大 slam；breakdown 段天然是品牌呼吸位。
+3. 写完整分镜表：镜头顺序、时长、功能信息、具体页面状态、镜头卡与变体、主动作、
+   素材来源、字幕、转场和 SFX。每镜只讲一个主要动效。
+4. 排时间线时**预留 hold/rest 帧预算**：品牌字标落定 hold ≥1s（30f）、
+   批量动效收尾 0.5s 静止、开场主体动作 ≥3s。节奏返工是单向的——
+   过快必返工、放慢从未被否。
+5. Agent 检查分镜与产品简报、需求决策、视觉方向和镜头映射一致后自行放行，
+   把分镜转译成帧级时间轴进实施计划：
+   `| shot | from | duration | 内容 |`（卡点片则 from/to 全用 `beatF(n)`
+   表达），并给每镜头指定源文件与验收帧号。
+
+**产出**：设计 spec（含风格 tokens + motion breakdown + 分镜表）；
+帧级时间轴。
+
+**常见坑**：
+
+- 没对功能清单，凭手感排镜头：核心功能漏拍、动画手法同质化，两种都返工。
+- 开场贪多：开场信息宁少而聚焦，一个主角、一条完整动作弧。
+- 时长预算不含呼吸位：动效排满每一帧，后期逐镜头补 hold 等于全线挪帧。
+
+---
+
+## 阶段 4：最终素材采集
+
+**前置条件**：最终设计 spec 与分镜已经放行。共同创作以用户确认作为放行；自主
+自由创作以 Agent 完成一致性检查并记录为放行。此前为 styleframe 采过的少量安全
+截图只能作为方向验证，不得直接替代最终素材。
+
+**目标**：严格按最终分镜拿到全部镜头所需的真实页面素材，包括全页纹理、元素
+切片和坐标表，为 2.5D 运镜与页面空间动画打地基。
+
+**具体操作**：
+
+1. 起产品本地 dev server（桌面端产品则用窗口截图工具，同样出三件套）。
+2. 复制 `assets/scripts/capture-template.mjs` 进项目，改 BASE_URL 与选择器，
+   跑一次产出三件套：
+   - **全页 2x 截图**：viewport 1920×1080、`deviceScaleFactor: 2`；截图前
+     `document.fonts.ready` + 600ms settle，实时同步页额外再等 1.5–2s。
+   - **per-element cutout**：按语义选择器逐元素截图；悬浮件用透明底，需要
+     “卡片飞入空板”的镜头则额外截空 backplate。
+   - **layout.json**：记录每个元素在整页坐标系下的 `{x,y,w,h}` bbox 与每页
+     `pageH`，供飞行目标位、遮罩位置和入场区域直接使用。
+3. 支持按页/按元素增量重采。活数据源先按阶段 0 的数据口径冻结、虚构或脱敏，
+   再进行最终采集。
+
+**产出**：`public/textures/` 全页图、元素切片与空 backplate；`layout.json`；
+可重跑的 capture 脚本。
+
+**常见坑**：
+
+- 在分镜放行前做全量采集：页面状态和素材范围尚未确定，会造成重复采集。
+- 手搓 HTML 复刻既有页面：复刻默认走真实截图；手搓 UI 只用于非复刻场景。
+- 活数据源不锁定，或只截整页不记录 layout 坐标。
+
+---
+
+## 阶段 5：逐镜头实现
+
+**前置条件**：需已有可跑的 Remotion 项目（30fps、1920×1080，`src/index.ts`
+注册 Composition；新项目可 `npx create-video@latest` 初始化后把
+`assets/lib/` 组件 copy 进去；走模板路线则直接从 `template/` 起步）。
+
+**目标**：按帧级时间轴逐镜头落地，每镜头完成即自证质量——
+验收在这个阶段就开始，不留到最后。
+
+**具体操作**：
+
+1. **每镜头先解析再三读**（硬规则，不可跳）：用
+   `gallery/api/library.json` 校验卡名和 `style-key` → 读对应配方卡全文 →
+   按卡片“参考实现”定位并读准确的 demo TSX 全文 → copy `assets/lib/`
+   对应组件进项目。同时保存该 style 的 Gallery 参考样片路径，供实现对照和终检。
+   标为“仅供参考，需要自定义实现”的样式不默认推荐，用户明确点名后才可实现并
+   标注风险；标为“缺少预览”的样式不得声称已按动态样片复刻。
+   demo 代码是调校过的参数真相（缓动、时值配比、
+   摘罩时机、已知坑的规避写法都在里面）——允许按目标产品做适配性
+   改动，但配方卡"已知坑/命门"标注的参数不得降档，质量标准只升不降。
+   凭卡名和理解新写＝放弃全部调校积累，实测质感差一档。
+2. **PageCam 是一切"真实页面"镜头的地基**：整页纹理 + 关键帧 2.5D 相机 +
+   页面空间 overlay，children 按页面 CSS px 定位、与 layout.json 共坐标系。
+3. **静帧验收（最高频动作）**：每镜头在计划里写死 2 个验收帧号，
+   完成即跑 `npx remotion still src/index.ts <Comp> out/qa/<name>.png
+   --frame=<N>`，自己肉眼检查构图/穿帮/文字锐度后才算完成。
+   静帧产物按迭代版本归档 `out/qa/`，用户贴帧反馈时可直接对号。
+4. **每轮修改后整片渲染**：`npx remotion render src/index.ts <Comp>
+   out/promo.mp4`，再用 `ffmpeg -i out/promo.mp4 -vf "select=eq(n,…)"`
+   从成片抽关键帧回看。实际形态是"改哪个镜头就 still 哪几帧，
+   然后整片重渲"，成本可接受且杜绝接缝意外。
+5. 像素级自检备小工具：裁剪放大看文字锐度（crop）、两帧像素 diff、
+   量元素 bbox 对构图。
+6. **确定性渲染铁律**：禁 `Date.now()` / `Math.random()` / 无参 `new Date()`。
+   一切伪随机用固定种子（mulberry32/哈希函数，seed 从 index 派生），
+   保证逐帧可复现、渲染间零抖动。
+7. 对照 `references/aesthetic-rules.md` 边做边自检（不等阶段 7）：
+   落地要弹的缓动 y1 必须 >1、光效裁进圆角、3D 下文字糊先查
+   栅格化路径（CSS `zoom` 布局级放大，而非 transform scale）而不是调 DoF。
+8. 指代含糊的用户反馈（"第一个标题"）先确认对象再动手；改错立即整
+   commit revert 重来，不在错误版本上打补丁——每个改动独立 commit
+   以便干净回滚。
+
+**产出**：逐镜头 commit；`out/qa/` 静帧档案；每轮全片渲染 mp4。
+
+**阶段输出**：整片渲染视频（每轮迭代一版）+ 关键静帧。自主自由创作不因该输出
+暂停等待确认；用户主动反馈时再纳入下一轮。
+用户可能以"从成片截帧贴图"方式给反馈，双方基于帧评审。
+
+**常见坑**：
+
+- 首检交给用户：交付前必须自己抽帧看片，"镜头视角很差，
+  而且有小抖动"这种问题不该由用户发现。
+- 跳过 demo 代码直接写：参数是几轮真实裁决调校出来的，
+  新写的版本几乎必然回踩已知坑。
+- 产品宣传片默认不加手持 shake；相机噪声只在明确追求纪实感时用。
+- 装饰性 glint/泛光群发：批量元素入场靠运动本身。单点高质量光效可做，
+  群发即廉价。
+- 3D 推进下文字发糊：根因是纹理源分辨率/栅格化路径，先查素材链路
+  （2x 纹理 + CSS zoom + 关键元素 4x 单独截图），别先动相机和景深。
+- 飞入动画终点悬空：元素必须落进页面布局的真实槽位（嵌入、归位、
+  排进滚动流），悬浮在页面上方不落地会显得假。
+
+---
+
+## 阶段 6：声音设计
+
+**目标**：BGM 定全片能量骨架，SFX 逐拍钉在动效关键帧上，
+音色符合"产品宣传片"片种而非 UI 事件语义。
+
+**前置条件（最贵的顺序教训）**：**画面时间线锁定后才开始。**
+画面每动一次，钉帧表就要全体重对。若画面确实又改了，收尾动作固定
+包含"全表 SFX 帧号重对"，音画错位是必查项。
+
+**具体操作**（细节与判例见 `references/sound-design.md`）：
+
+1. 读 `references/sound-design.md`，从 `assets/audio/` 复制音效
+   （免费商用授权，来源见 `assets/audio/ATTRIBUTION.md`）。
+2. **BGM**：用户已指定 → 阶段 0 已做节奏分析，此处只做混音
+   （音量压低 ~0.34 给 SFX 留 headroom，interpolate 首尾淡入淡出）。
+   未指定 → 按片种选强鼓点、强节奏的电子底（tech-house 类），判据是
+   "典型的产品宣传视频"气质而不是"好听"；候选曲必须垫进成片试听，
+   单听曲子选型不可靠；`assets/audio/bgm/` 有节奏感强的备选。
+3. **SFX 用电影系词汇按镜头语言选**：运镜=whoosh、落地=impact、
+   铺垫=riser、光效=sparkle、转场=transition；禁用游戏 UI 音包
+   （click/pluck/glass 类 tap 一耳朵出戏）。
+4. **声明式钉帧表集中管理 + 相对钉帧**：单文件 `{ from, src, volume }[]`
+   数组，逐条注释对应的画面动作，每条包 `<Sequence from={s.from}>`。
+   **from 一律写相对表达式**——`SHOTS.x.from + offset`，卡点片写
+   `beatF(n)`——绝不写裸数字帧号。时间线平移时钉帧表自动跟随，
+   免除全表重钉。长样本靠 Sequence duration 截断而非剪音频文件。
+5. 连发防机枪感三招：双样本交替、音量阶梯递减（如 pop 六连
+   0.40→0.25）、间隔加速贴动画曲线（密到糊成一片时让声音淡出成 swoosh）。
+6. 通用音之外留"贴画面定制"槽位：有辨识度的画面动作配它自己的拟音
+   （打字画面配键盘声、逐条落入配逐个 pop），泛用 swoosh 盖不住。
+7. 强鼓点 BGM 的片子 SFX 克制：鼓点本身就是节拍音，SFX 只钉画面
+   独有动作，大 slam 只给 2–3 处峰值。
+8. 结尾固定句式：riser（组装段起）→ impact（字标落地，全片音量峰值）
+   → sparkle（余韵）。
+
+**产出**：带声整片；SFX 钉帧表（相对帧表达式+音源+音量+注释）；
+音频文件入 repo 并记录来源授权。
+
+**阶段输出**：带声整片渲染。自主自由创作继续进入终检，不暂停等待确认。
+
+**常见坑**：
+
+- 画面没锁就铺音效：全表重对的连带成本（见前置条件）。
+- 按 UI 事件语义选音色（click/confirmation/minimize）：片种错位，整批推翻。
+- 凭感觉散铺音效不建表：帧号漂移后无法整体平移，也无法和分镜表对照。
+
+---
+
+## 阶段 7：验收
+
+**目标**：把贯穿全程的静帧/整片自检升级为一次正式的全片过检，
+同时验证成片是否忠实执行当前模式下确认或记录的产品简报、需求到执行决策表、视觉方向、镜头映射和分镜，
+对照终检与审美准则逐条出报告，然后终渲交付。
+
+**具体操作**：
+
+1. 全片渲染最新版，ffmpeg 抽全部关键帧（每镜头至少：入场中、
+   动作峰值、落定后三帧）。
+2. **独立终检（必做）**：派一个干净上下文的 subagent 做第三方审查。
+   不给它制作过程中的辩解、修改历史或“应该通过”的暗示，只提供：最新版成片、
+   抽出的关键帧、创作模式、产品简报、需求到执行决策表、确认或记录的视觉方向/tokens、styleframe 或跳过理由、
+   功能到镜头映射、
+   Gallery 卡名与具体变体、`library.json` 中对应记录、卡片文档定位到的准确
+   demo TSX、Gallery 参考样片或从中抽出的关键帧、最终分镜、选中的镜头卡、
+   `references/final-review.md` 和 `references/aesthetic-rules.md`。
+3. 审查 Agent 按 `final-review.md` 检查产品目标、功能完整性、视觉方向一致性、
+   镜头卡/变体还原度、分镜一致性、数据安全、音画同步和视觉技术质量。逐镜头
+   看帧+看片，给出 "F2 ✗（第 340 帧缺少已确认的知识图谱功能）" 或
+   "Q2 ✗（第 615 帧文字发糊）" 式结论，每条问题附可复核帧号/截图。
+   镜头卡适配不要求和 Gallery 样片像素级相同，但必须保留动作语法、关键时值、
+   已知坑/命门参数和用户点名的具体变体。
+4. 内容级自查：每个镜头问"给了什么新信息"，重复镜头/重复 tagline 删；
+   文案按最终画面重写一遍，纯动画段落也要有解说 caption，不留哑巴段落。
+5. 音画对齐终检：逐条 SFX 对帧回放，确认无错位（时间线若在阶段 6 后
+   还动过，先重对再验）。卡点片按 music-beat-sync.md §4 做渲后回测，
+   全部切点误差 ≤3f 才算过。
+6. 审查报告的修复项回到阶段 3/5/6 小循环：方案或分镜偏差回阶段 3，画面实现
+   问题回阶段 5，声音问题回阶段 6；直到 checklist 通过后终渲出片。
+
+**产出**：独立审查报告（final-review + aesthetic-rules checklist + 帧号证据）
++ 终渲成片。
+
+**交付物**：审查报告 + 成片。
+
+**常见坑**：
+
+- 把验收当"最后才做的事"：本阶段只是收口。若前五阶段没做静帧自检，
+  这里堆积的问题量会让 checklist 失去意义——验收贯穿全程是定式。
+- 自检报告流于"全部 ✓"：用户会读清屏幕上每个字、会自己截帧对比——
+  报告里每条结论都应附可复核的帧号/截图。
+- 制作 agent 自己出审查报告：确认偏差不可避免，独立 subagent 审查
+  不可省略。
+- 只查“好不好看”不查“是否符合当前模式的制作基准”：功能漏拍、视觉方向漂移、
+  镜头变体用错和未经确认的数据都属于终检失败。

package/skills/hyper-animator-codex/references/shotcraft/references/sound-design.md

@@ -0,0 +1,126 @@
+# sound-design — 声音设计
+
+来源：模板片（`template/`）声音设计实战。准则编号 S1–S4 见 `references/aesthetic-rules.md`。
+
+模板片的声音全部集中在一个文件里管理（`template/src/aifl/Main.tsx`：`SFX[]` 钉帧表），场景组件不含任何音频代码——声音是时间线级资产，不是镜头级资产。
+
+## 目录
+
+- 方法
+- BGM 选型
+- SFX 词汇表
+- 对齐技巧
+
+---
+
+## 1. 方法
+
+**顺序：画面结构基本锁定 → 先铺 BGM 定能量骨架 → 逐拍钉 SFX。**
+
+1. **BGM 先行，定能量骨架。** 一条 BGM 全片铺底，音量包络用 `interpolate` 做首尾淡入淡出（模板片 `[0, 30, TOTAL-50, TOTAL] → [0, 0.34, 0.34, 0]`，即 1s 淡入、1.7s 淡出）。BGM 音量压在 0.34 左右给 SFX 留 headroom。曲子的能量曲线要和分镜表的能量曲线对得上（低开 → 中段推进 → outro 峰值），候选曲必须垫进成片试听——单听曲子无法判断气质（S1）。
+2. **词汇表按"片种"选，不按"事件"选（S1）。** 产品宣传片的 SFX 词汇 = whoosh(运镜) / impact(落地) / riser(铺垫) / sparkle(光效) / transition(转场)，禁用游戏 UI 音包（click/pluck/glass 类 tap 音）。模板片第一版按 UI 事件语义选音（click/drop/confirmation），用户一耳朵判死刑"太像游戏了"。
+3. **SFX 逐拍钉帧、声明式表集中管理（S2）。** SFX 是 `{ from, src, volume }[]` 数组，逐条注释对应的画面动作（"hero card: whoosh up on the pop"），渲染时每条包一个 `<Sequence from={s.from}>`。杜绝凭感觉铺音效。
+4. **通用音之外留"贴画面定制"槽位。** 词汇表定稿后，有辨识度的画面动作仍会要专属拟音（打字揭示配键盘声、逐周落入配 pop）——泛用 swoosh 盖不住这些动作（S4）。
+
+时机教训：模板片的音频工作直到画面改了约 30 轮之后才开始（收尾最后几轮）；有一次把换 BGM 和画面重做混在同一轮改动里，画面随后继续改，SFX 全表报废重钉。**声音永远排在画面锁定之后**（S3），细节见第 4 节。
+
+---
+
+## 2. BGM 选型
+
+### 演进：三易其稿（34 分钟）
+
+| 稿 | 曲目 | 来源/授权 | 被换原因 |
+|---|---|---|---|
+| v1 | Kevin MacLeod – *Inspired*（暖色 ambient 钢琴底）；同批还下了备选 *Deliberate Thought*，从未引用 | incompetech，CC-BY | 用户："BGM换个更有节奏感，更激情欢快的"——钢琴 ambient 不够激情 |
+| v2 | Kevin MacLeod – *Life of Riley*（欢快 folk-pop） | incompetech，CC-BY | 用户："这个配乐和音效都太像游戏了。你帮我找那种鼓点强的，节奏感强的"——欢快≠宣传片气质 |
+| v3（定稿） | Mixkit tech-house 鼓底（`bgm-tech-house.mp3`），音量升至 0.34 | Mixkit license | 未再被换，沿用至成片 |
+
+v1→v2 只隔 22 分钟就又被否——说明选曲时根本没在成片语境里听。**候选曲必须垫进成片试听后再定**（S1 自检项）。
+
+### 选型判据（从用户原话反推）
+
+- **鼓点强、节奏感强**，优先电子底（tech-house 类）；"好听/欢快"不是判据。
+- 气质基准是"典型的产品宣传视频"——闭眼只听音轨，应像产品发布会预告，不像手机游戏（S1）。
+- 能量曲线能托住全片结构：平稳鼓底适合叠 SFX 层次，旋律太抢的曲子会和拟音打架。
+
+### 免费授权来源清单
+
+| 来源 | 授权 | 适用 | 备注 |
+|---|---|---|---|
+| [Mixkit](https://mixkit.co/) | Mixkit License（免费商用、免署名） | BGM + 电影系 SFX（whoosh/impact/riser/sparkle） | 模板片定稿的 BGM 和 SFX 主力来源；批量下载后 metadata 常被抹掉，**下载时就记录曲名/URL**，否则事后无法反查（模板片 `bgm-tech-house.mp3` 已无法逐曲对回 Mixkit 曲库，商用前需复核） |
+| [incompetech](https://incompetech.com/)（Kevin MacLeod） | CC-BY 4.0（需署名） | BGM，曲库大、按情绪筛选 | 模板片 v1/v2 出处；注意 CC-BY 的署名义务 |
+| [Kenney](https://kenney.nl/assets)（音包） | CC0 | 游戏类项目 | **产品宣传片禁用**（S1）——模板片引入后被整批删除，仅列此供授权档案参考 |
+
+---
+
+## 3. SFX 词汇表
+
+以下 14 个文件是 `assets/audio/` 的基础层（模板片实际使用的一批）；2026-07 扩充的 27 个新 SFX 与 `bgm/` 备选见 `assets/audio/ATTRIBUTION.md`。时长来自 ffprobe；"典型钉帧位置"引用模板片 `template/src/aifl/Main.tsx` SFX 表的定稿帧号（30fps、全片 1085f），复用时取其相对语义而非绝对数值。
+
+| 文件 | 时长 | 用途场景 | 典型钉帧位置（模板片） | 来源与授权 |
+|---|---|---|---|---|
+| `bgm-tech-house.mp3` | 288.7s | 整片鼓底 BGM，tech-house 电子 | 全片铺底，音量包络 0→0.34→0.34→0 | Mixkit（无法逐曲反查，商用前复核） |
+| `transition-soft.mp3` | 1.27s | 柔转场：品牌落定、场景切入 | f12 / f277 / f475 / f623 / f779（每次进新场景一发） | Mixkit |
+| `whoosh-fast.mp3` | 1.76s | 快速运镜、批量元素飞走 | f78 brand→dashboard、f340/356 发牌加速、f435 筛选网格飞走 | Mixkit |
+| `whoosh-big.mp3` | 2.32s | 大幅度运镜：弹起、拉远、回摆 | f127 hero 卡弹起、f308 orbit 拉远、f388 swoosh 回搜索栏 | Mixkit |
+| `sparkle.mp3` | 4.55s | 光效 reveal：扫描光束、收尾闪光 | f141 hero 卡光束、f1005 结尾 rule 闪光 | Mixkit |
+| `transition-snap.mp3` | 0.57s | 短促落定/贴回原位的 snap | f204 hero 卡 impact reseat | Mixkit |
+| `swoosh-quick.mp3` | 0.78s | 字卡出场统一音、轻推镜 | f220/565/725/885 四张 title card、f455 点击后 push-in | Mixkit |
+| `keyboard.mp3` | 19.6s | 真实键盘打字拟音（长样本，按段落裁剪用） | f401 搜索框输入（截 24f）、f781 周报页"自己写出来"（截 44f） | Mixkit |
+| `click-camera.mp3` | 0.35s | 点击确认/快门感（全片最响 vol 0.6） | f451 点击卡片进详情、f648 papers 计数落定 | Mixkit |
+| `riser-cine.mp3` | 4.81s | 电影系上升铺垫，进 finale | f945 outro 合影组装段起 | Mixkit |
+| `impact-cine.mp3` | 4.06s | 电影系重音钉点（vol 0.55 全片 SFX 峰值） | f980 字标 stamp 落地 | Mixkit |
+| `pop.mp3` | 0.48s | 列表条目逐个落入的短促 pop | f840–865 周报周列表 6 连发，每 5f 一发、音量 0.40→0.25 阶梯递减 | **来源待考** |
+| `impact-transition.mp3` | 4.87s | **死资产：全片未被引用**，与定稿 SFX 同批下载的备用 impact | 无 | Mixkit（同批），未接线 |
+| `typewriter.mp3` | 0.22s | **死资产：全片未被引用**。文档页揭示实际用的是 `keyboard.mp3` 截 44f，此文件下了没接线 | 无 | **来源待考** |
+
+小结：12/14 在片中实际发声；2 个死资产（`impact-transition.mp3`、`typewriter.mp3`）如实保留并标注；2 个来源待考（`pop.mp3`、`typewriter.mp3`）。"Mixkit" 的判定依据是模板片 Main.tsx 的批量声明，无逐文件 URL——**商用前应逐个回查授权**。
+
+---
+
+## 4. 对齐技巧
+
+### 4.1 钉帧方法
+
+- **声明式中央注册表**：`SFX: { from, src, volume }[]`，每条注释对应的画面动作；渲染层遍历数组，每条包 `<Sequence from={s.from}>`。帧号表与分镜表（`AIFL_SHOTS`）放同一文件对照（S2）。
+- **长样本靠 Sequence 截断，不剪音频文件**：`keyboard.mp3`（19.6s 原素材）按语境给 `durationInFrames` 24f 或 44f；其余统一 90f 让 ≤3s 素材自然播完。音频时长与画面动作严格等长（S4）。
+- **音量分层**：BGM 0.34 打底，SFX 0.2–0.6 分层——点击确认 0.6 最响、pop 连发尾音 0.25 最轻，用响度表达"这一拍多重要"（曾出现的 0.14 出自已删除的 v2 pluck 连发串，不属于定稿区间）。
+
+### 4.2 变调与防机枪感
+
+**本仓库实证无 playbackRate 变调**（模板片全仓 `grep playbackRate` 零命中）。同类元素连发防机枪感靠三招组合（S2），不靠变调：
+
+1. **双样本交替**：连发用两个近似样本轮流（模板片 deck-deal 8 连发 pluck_002/pluck_001 交替）。
+2. **音量阶梯递减**：沿序列线性衰减做"距离感"——定稿 pop 6 连发 0.40/0.37/0.34/0.31/0.28/0.25。
+3. **间隔跟随动画曲线加速**：连发间隔贴画面加速节拍收缩（8f→3f）；密到糊成一片时**主动让声音淡出成一条 swoosh**，不逐个配音——耳朵和眼睛一样，分辨不出糊掉的个体。
+
+目标听感：连发段落是"数得出来的节奏"，不是机械复读（S2 自检项）。
+
+### 4.3 riser→impact：镜头收束句式
+
+大镜头（尤其 outro）的固定三拍：
+
+```
+riser-cine（组装/铺垫段起） → 约 35f 后 impact-cine（主体 stamp 落地，全片响度峰值） → 25f 后 sparkle（余韵光效）
+```
+
+模板片 f945→f980→f1005，是定稿声音方向确立后唯一从未改动的段落句式——能量铺垫、钉点、余韵三件套一次成型。其它可复用的小句式：场景切换 = `transition-soft` 一发；字卡出场 = `swoosh-quick` 统一音；点击确认 = `click-camera`（给全片最高 SFX 响度）。
+
+### 4.4 返工教训：三次重钉的顺序账
+
+模板片 SFX 全表重钉了三次，其中**两次纯属画面返工的连带成本**（S3）：
+
+| 次 | 起因 | 性质 |
+|---|---|---|
+| 1 | 音色方向错误（游戏音包→电影系词汇） | 声音自身的返工，难免 |
+| 2 | 画面时间线变更（总长 1020→1085），全表 from 值平移 | **画面没锁就钉音的连带成本** |
+| 3 | 周报段画面加动画，该段 SFX 重写 | 同上（局部） |
+
+规则化：**声音在画面锁定后做；任何改变镜头时长/顺序的修改，收尾动作固定包含"全表 SFX 帧号重对"**（S3）。反面案例：有一次把换 BGM 和 deck-deal 画面重做塞进同一 commit，画面随后又改，音效白钉。
+
+### 4.5 钉帧一律相对 shot 起点，而非绝对帧（硬规则）
+
+模板片的 SFX 表钉**绝对帧号**，单文件数组便于整表平移（第 2 次重钉一个 diff 完成），但绝对帧意味着零结构复用——任何一个镜头改时长，其后所有条目全部失效。
+
+做法：钉帧写成 `SHOTS.<shot>.from + offset`（相对该镜头起点的偏移；卡点片写 `beatF(n)`，见 music-beat-sync.md）。这样镜头内部节拍不变时，改前面镜头的时长只需分镜表更新一处，SFX 自动跟随——绝大部分重钉可免除。新项目起手即按相对钉帧写，绝不写裸数字帧号。

package/skills/hyper-animator-codex/references/shotcraft/source/assets/lib/Caption.tsx

@@ -0,0 +1,50 @@
+// origin: template/src/aifl/Caption.tsx（模板片同源组件）
+import { interpolate, useCurrentFrame } from 'remotion';
+
+const MONO = 'ui-monospace, SFMono-Regular, Menlo, monospace';
+const AMBER = 'oklch(52% 0.115 65)';
+
+/** Screen-space narration caption: a mono UI info-strip at the bottom of the
+ * frame, led by a small amber square. Fades/rises in over 8 frames and fades
+ * out over the last 8 of its window. */
+export const Caption: React.FC<{ text: string; duration: number; bottom?: number }> = ({
+  text,
+  duration,
+  bottom = 72,
+}) => {
+  const frame = useCurrentFrame();
+  const inT = interpolate(frame, [0, 8], [0, 1], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  const outT = interpolate(frame, [duration - 8, duration], [1, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom,
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'baseline',
+        gap: 14,
+        fontFamily: MONO,
+        fontSize: 22,
+        letterSpacing: '0.14em',
+        textTransform: 'uppercase',
+        color: 'oklch(45% 0.006 82)',
+        opacity: inT * outT,
+        transform: `translateY(${(1 - inT) * 8}px)`,
+        pointerEvents: 'none',
+      }}
+    >
+      <span style={{ width: 6, height: 6, background: AMBER, display: 'inline-block' }} />
+      <span>{text}</span>
+    </div>
+  );
+};

package/skills/hyper-animator-codex/references/shotcraft/source/assets/lib/DigitRoll.tsx

@@ -0,0 +1,45 @@
+// origin: template/src/aifl/DigitRoll.tsx（模板片同源组件）
+import { interpolate, useCurrentFrame, Easing } from 'remotion';
+
+const DIGITS = '0123456789';
+
+/** Odometer-style digit column roll for monospace numerals. */
+export const DigitRoll: React.FC<{
+  value: string;
+  delay?: number;
+  fontSize?: number;
+  color?: string;
+}> = ({ value, delay = 0, fontSize = 30, color = 'oklch(52% 0.115 65)' }) => {
+  const frame = useCurrentFrame();
+  const lineH = fontSize * 1.15;
+  return (
+    <span style={{ display: 'inline-flex', overflow: 'hidden', height: lineH, verticalAlign: 'bottom' }}>
+      {value.split('').map((ch, i) => {
+        const target = DIGITS.indexOf(ch);
+        if (target < 0) {
+          return (
+            <span key={i} style={{ fontSize, lineHeight: `${lineH}px`, color }}>{ch}</span>
+          );
+        }
+        const t = interpolate(frame, [delay + i * 4, delay + i * 4 + 22], [0, 1], {
+          extrapolateLeft: 'clamp',
+          extrapolateRight: 'clamp',
+          easing: Easing.bezier(0.25, 0.8, 0.25, 1),
+        });
+        // roll through one full strip then land on the target digit
+        const offset = (10 + target) * t * lineH;
+        return (
+          <span key={i} style={{ display: 'inline-block', height: lineH }}>
+            <span style={{ display: 'block', transform: `translateY(${-offset}px)` }}>
+              {(DIGITS + DIGITS).split('').map((d, j) => (
+                <span key={j} style={{ display: 'block', fontSize, lineHeight: `${lineH}px`, color, fontVariantNumeric: 'tabular-nums' }}>
+                  {d}
+                </span>
+              ))}
+            </span>
+          </span>
+        );
+      })}
+    </span>
+  );
+};

package/skills/hyper-animator-codex/references/shotcraft/source/assets/lib/FlashCut.tsx

@@ -0,0 +1,20 @@
+// origin: template/src/aifl/FlashCut.tsx（模板片同源组件）
+import { AbsoluteFill, interpolate, useCurrentFrame } from 'remotion';
+
+/** Bright-field cut: a warm-white bloom that flashes over the hard cut. */
+export const FlashCut: React.FC<{ duration?: number }> = ({ duration = 10 }) => {
+  const frame = useCurrentFrame();
+  const o = interpolate(frame, [0, duration * 0.4, duration], [0, 0.85, 0], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+  return (
+    <AbsoluteFill
+      style={{
+        pointerEvents: 'none',
+        opacity: o,
+        background: 'radial-gradient(ellipse at 50% 45%, rgba(255,248,235,0.98), rgba(255,244,224,0.55) 55%, transparent 80%)',
+      }}
+    />
+  );
+};