akomlik/assemble-timeline

原子 MCP 时间线装配与验证 (/assemble-timeline)

选项 A：FilmCraft MCP 执行 (filmcraft MCP 服务器 — 需要 FilmCraft v0.17.0+)

1. 环境与桥接验证

1. 首先运行 python3 ./.agents/skills/assemble-timeline/scripts/check_filmcraft_env.py 以验证 FilmCraft $\ge$ v0.17.0，自动同步 filmcraft-cli 与 FilmCraft.app，并将任何新添加的 MCP 命令显示在 00_Archive_Indexes/filmcraft_capabilities.json 中。
2. 确保 FilmCraft 以桥接模式运行，且缓存路由到 ~/Movies/Cache_And_Previews：

   mkdir -p ~/Movies/Cache_And_Previews && cd ~/Movies/Cache_And_Previews
   open -a FilmCraft --args --control 9876
   

2. 实时可视化装配模式（默认且推荐）

在打开的 FilmCraft GUI 中实时观看时间线装配，总套接字执行时间增加不到 1.5 秒（本地桥接上每次调用耗时 $< 20\text{ ms}$），并提供即时视觉验证：

1. 在第 0 秒打开空白画布： 立即通过 command_run（{"id": "file.open", "params": {"path": "<fcproj_path>"}}）或 sequence.new 在 FilmCraft 中创建并打开干净的 .fcproj 外壳。用户将在第 0 秒看到空的 4K 序列出现。
2. 流式媒体导入： 使用所有选定视频剪辑、照片、档案拉取以及所选 03_Audio_Library/01_Curated_BGM/ 曲目（A2）的绝对文件路径调用 media_import。
3. 实时逐场景流： 当处理经过批准的 Cut Table 中的每个场景时，通过 9876 桥接实时流式传输 command_batch 调用：
   • playhead.set：将播放头移动到场景开始时间码。
   • source.overwrite / timeline.insertClip：将视觉剪辑放置到 V1（或用于叠加/画中画的 V2）上，并将同步音频放置到 A1 上。
   • motion.apply：对静态图像注入 Ken Burns EaseIn/EaseOut 缩放和平移关键帧（100% $\rightarrow$ 108%，或 4:3 照片上为 134% $\rightarrow$ 142%，以防止信箱式裁剪）。
   • audio.append：放置 A2 背景音乐，具有 1.5 秒淡入和渐强。
   • voiceover.insert：在每个音频提示完成合成时，将 A4 画外音片段实时放置到时间线上。
4. 广播级抛光：
   • 同语言现场对话尊重法则： 切勿将语言 $L$ 的 A4 画外音放置在用同一种语言 $L$ 说出的 A1 现场摄像机对话之上（EN VO 尊重现场 EN 对话；RU VO 尊重现场 RU 对话；UA VO 尊重现场 UA 对话）。当 A4 VO 翻译包含外语摄像机对话的剪辑时（edition_lang != clip_dialog_lang），在 VO 提示活动期间将 A1 降低 -12 dB。
   • 自然 1.00x 语音速度、1:1 V1 == A1 唇形同步与开场音乐引入法则： 切勿对现场摄像机语音（A1）或合成的画外音（A4）应用 atempo > 1.0 或内部停顿剥离（stop_periods=-1）。始终调整说话视觉剪辑（V1）的大小，使其适合完整的 1.00x 说话句子（src_in，dur），以便 V1 和 A1 在帧和样本同步中保持 1:1 锁定（通过 atrim=start=...:end=...,asetpts=PTS-STARTPTS 切片，并在 amix 之后一次性应用 dynaudnorm=f=150:g=7:p=0.90），并且永远不会溢出到不相关的场景。始终在每个时间线和渲染的 .mp4 开头包含一个 1.5s–2.0s 的音乐引入，然后再开始第一个画外音提示。
   • RMS 校准音乐闪避（语音下平均 -28.5 dB）： 通过 ffmpeg volumedetect（compute_bgm_ducked_gain_db）测量每个 A2 音乐曲目的 mean_volume，并设置 gain_db = -28.5 - raw_mean_db，以便闪避后的 BGM 的平均水平保持在 -28.5 dB —— 比标准化的 -16.0 dB 平均画外音和现场对话低整整 12.5 dB，即使在热母带处理的快节奏曲目上也是如此。
   • 将 A4 画外音和 A1 对话标记为 Dialogue（clarity.eqPreset: "Balanced Voice"），并在 A2 音乐上执行 essentialSound.generateDucking（reduceDb: -6.0，fadeS: 0.45）。
   • 在结束的视觉剪辑上应用原生的 1.5 秒到 2.0 秒 dip_to_black 过渡。
   • 强制同步结尾音频淡出： 主音频输出（[fullout]）和 A2 上的音乐必须执行同步的 2.0s–2.5s 半正弦淡出（afade=t=out:st=<TOTAL_DUR - FADE_DUR>:d=<FADE_DUR>:curve=hsin），以便所有音频（音乐、摄像机噪音、SFX 尾音）在最后一帧或之前达到完全静音（-infinity dB）。在 .fcproj 中，轨道 A2 必须带有 EndAtCut 音频淡出过渡（from: Some(clip.id), to: None, align: "EndAtCut"）。声音绝不能突然中断。
   • 将多语言字幕轨道写入 caption_tracks (C1)，并设置 enabled: false（burnCaptions: false 默认）。

3. 无头批处理回退 (assemble_engine.py)

如果 FilmCraft GUI 未运行或桥接模式离线，则通过 assemble_engine.py 在 $< 1$ 秒内自动直接装配 .fcproj，并通过 filmcraft-cli 渲染 4K 主 MP4。

• 仓库卫生规则： 将 .agents/skills/assemble-timeline/scripts/ 严格保留给通用的、与项目无关的引擎（assemble_engine.py，gpx_widgets.py，generate_voiceover.py，check_filmcraft_env.py）。如果为特定项目创建了自定义或特定于项目的装配脚本，请始终将其保存在该项目的 git 忽略目录文件夹内（04_Project_Catalog/YEAR/<project_name>/），切勿保存在 .agents/skills/ 内。

4. 视觉验证与主渲染

1. 在三个时间戳（第一幕引入、中点、尾声）调用 render_frame 以确认构图。
2. 将主 4K MP4 渲染到 ~/Movies/Exports/YEAR/<project_name>.mp4。
3. 如果请求了多语言版本（option_b），则将其与 _UA.mp4 和 _RU.mp4 本地化主干重新混流。

选项 B：DaVinci Resolve Studio MCP 执行 (davinci-resolve)

1. 创建新时间线（1920x1080 或 3840x2160，29.97 fps，DaVinci YRGB Color Managed Rec.709）。
2. 通过 media_pool 将选定的媒体导入 Selects 素材箱，通过 timeline_edit 将剪辑追加到 V1/V2/A1 并将音乐追加到 A2，通过 transitions 应用 Cross Dissolve 过渡，通过 keyframes 设置 Ken Burns 缩放关键帧，并通过 audio / inspector 设置音频闪避。
3. 在三个时间戳调用 export_still 以视觉验证剪辑，将 .drp/.drt 备份导出到 04_Project_Catalog/YEAR/<project_name>/，并通过 render 将最终的 .mp4 渲染排队到 ~/Movies/Exports/YEAR/。