用途 film-breakdown 是一组 Node + ffmpeg 脚本，用来把一部影片拆成数字与审阅图，并在复刻过程中把自建版本与参考片逐帧比对。脚本位于 /workspace/skills/film-breakdown/scripts/。
主要能力
- breakdown.mjs：提取剪辑点、联系表、静帧、运动能量、声轨、草案镜头表与时间线。
- grab.mjs：抓取帧精确静帧，支持按时间或帧号指定，可缩放、输出 JPG 或联系表。
- analyze-audio.mjs：把声轨或任意音乐转为节拍网格、击打点与响度，可输出 timeline 片段。
- compare.mjs：把复刻版本与参考片对比，输出配对图（含 SSIM）、带时间码与帧号的并排视频，以及含逐秒运动能量、相关性、全局延迟、剪辑点逐帧匹配和静帧审计的 compare.json。
使用方式 按任务选择路径：要“复刻这个视频”则走完整流程，逐幕构建、每次修改后比对；要“做一个类似的”则先拆解，再读取联系表与草案镜头表，借鉴节奏、网格、配色逻辑与转场类型，内容与品牌需自行撰写；要“分析它为何成立”则依据拆解数字回答剪辑节奏、剪辑落点与重音词的对应、能量弧线与重复系统；要“匹配这个节奏”或“对齐这首曲子”则用 analyze-audio.mjs 分析音轨，并把 BPM、GRID0、HITS 写入项目的 timeline.js。
拆解后按顺序阅读审阅图：overview-1fps.jpg 看全片（硬切为红框）；section-NN_.jpg 为每秒 4 帧、每张 5 秒；cut-NN_.jpg 为每个剪辑点前后每秒 10 帧（切前最后一帧橙框、切后第一帧红框）；stills/ 存放全分辨率帧，用于读取位置与颜色，不应从联系表取。breakdown.json 记录全部数值：cuts、transitions、moves、shots、motion 与 audio。
随后补全 SHOTLIST.draft.md 镜头表：将每个 ____ 按目视替换，镜头按硬切分段并在快速运动处拆分，文案逐字记录。timeline.draft.js 生成项目的 timeline.js，含 FPS、DUR、CUT_FRAMES、CUTS、SHOTS、BPM、BEAT、GRID0、beat(k)、DOWNBEAT、HITS 与 VO；场景从其中读取时间，不硬编码。渲染按参考片帧率进行，例如 hyperframes render --fps 30000/1001。
测量以数据为准：用 grab.mjs 取关键姿态的精确帧，在全分辨率 PNG 上读取像素位置与尺寸，在命名点采样颜色并映射到最近的品牌色，用几何关系拟合相机。构建后先做秒级内循环：对自建合成用 hyperframes snapshot，对参考片同一时刻用 grab.mjs，再生成两者对照联系表；草稿渲染后运行 compare.mjs 完整对比，先修最大差异。
并行分工 仅按硬切拆分，每个委派边界都对应 CUT_FRAMES 条目；跨越连续运动的幕留给同一构建者。每份任务简报需包含所属区间 [C.a, C.b)、镜头表行、分段联系表、两端剪辑点联系表、关键姿态全分辨率静帧、区间内文字与击打点、共享模块的真实导出（只读）、对比命令及回报内容。
保真度评分 按 compare.json 先评分，再看配对图并以全速观看并排视频：5 分播放时难以区分，剪辑点全部精确、运动相关性 r ≥ 0.98、版式误差数像素；4 分镜头、文案、版式与时间一致，仅材质与光线不同；3 分节拍位置相同、版式接近，部分元素为语义还原而非描摹；2 分可识别但时间或版式明显偏差或元素缺失；1 分仅保留思路顺序与大致配色。
数值含义与限制 剪辑点判定需同时满足高场景分、帧差相对前后 5 帧突增、且该帧不处于相邻帧中间（以排除淡入淡出、叠化与闪光衰减）；可通过 --cut-threshold、--scene-floor、--min-shot 调参。节拍网格的起始包络与 librosa 一致，起音能量峰值处为原点，鼓点攻击可能早 10-20 毫秒，帧级对齐强拍需用耳朵复核；人声下强拍常不明确。运动能量为 160 像素模糊帧差的平均亮度。颜色按文件声明的矩阵转换（高清为 BT.709），JPEG 静帧按 BT.601 全范围重编码。可变帧率（屏幕与手机录制）按平均帧率计算，grab.mjs 回退为按时间定位。拆解为一次解码加并行音频，完整对比需解码两部影片；长片或 4K 建议作为后台任务运行。
限制 参考片为他人作品，只可研究，不得输出其画面、素材或文案；此沙箱无 Python 语音模型，breakdown.mjs 会跳过词级步骤，需用宿主工具 transcribe_audio 获取参考音频的词时间戳。