制作音乐视频(FilmCraft + EffectCraft)
可复用的工作流,用于制作与音频轨道同步的音乐视频,结合 EffectCraft(2D 场景、动态图形、VFX、独立的透明歌词图层)和 FilmCraft(主多轨剪辑、节奏同步、音频混音/母带、全局调色、双轨导出 Master + Clean)。
常见的 2D 动画方法(构图、带预判的姿势变换、角色/摄像机锚点、EffectCraft 的父子级陷阱、图层的堆叠顺序以及文字的可读性):请遵循 craft-2d-animation。
完整的 MCP 参考、已验证的引擎命令和 Flatpak 配置:references/mcp-and-commands.md。
0. MCP 和沙箱前置条件(启动前检查)
- 检查当前会话中是否已暴露
effectcraft和filmcraft的 MCP 服务器(或干净地切换到effectcraft-cli/filmcraft-cliCLI)。- 如果缺失,不要凭空捏造调用:请查阅 references/mcp-and-commands.md 以获取准确的配置(Flatpak Linux
ai.storyteller.filmcraft/ai.storyteller.effectcraft或原生二进制,以 headless 或 bridge 模式运行)。
- 如果缺失,不要凭空捏造调用:请查阅 references/mcp-and-commands.md 以获取准确的配置(Flatpak Linux
- 注意 Flatpak (Linux):默认情况下,
ai.storyteller.effectcraft只能访问xdg-documents、xdg-pictures和xdg-videos。如果项目位于其他位置(例如~/.t3/projects/...),请传递--filesystem=<project_root>或配置 override:flatpak override --user --filesystem=home ai.storyteller.effectcraft - GUI 与 Headless 冲突:切勿同时在图形应用程序和 MCP/CLI headless 中打开同一个
.ecproj或.fcproj文件。使用--bridge来操控一个已打开的窗口。
1. 角色分工:EffectCraft vs FilmCraft
| 领域 | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| 主要用途 | 2D 动画场景 (V01..Vnn)、独立透明图层上的歌词 (L01..Lnn)、动感标题、粒子、2D/3D 合成 | 主多轨剪辑 (V1场景 + V2 RGBA歌词 + A1 母带音频)、逐帧同步、转场、全局调色、双轨导出(带歌词版 + 纯净版) |
| 创建 | comp.new, layer.newText, layer.newShape, layer.newSolid, layer.newAdjustment, add_effect, JSX 脚本 (ec_runtime.py) | file.newSequence, timeline.place, timeline.setTrack, timeline.razor, timeline.trim, timeline.move, clip.speedDuration |
| 音乐同步 | 源自 audio/lyrics_timing.json 的精确标记 + 用耳朵听;可选地 keys.audioToKeyframes 仅在需要测量响应式效果时使用 | markers.add 在每个段落、最后一个重音和切黑处;精确到帧 (frame: f0) |
| 风格与色彩 | 图层样式、蒙版、贝塞尔曲线、辉光、投影、预合成 (layer.precompose) | Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition |
| 音频 | 中间渲染不导出任何音频 (--audio off) | 在 A1 轨道上保留原始母带(默认保持 0.0 dB 以保留原始母带;仅在要求时使用 essentialSound.* 或 sequence.normalizeMixTrack) |
2. 文件交换管线与技术一致性
项目文件夹约定
<project_root>/
├── audio/ # 母带音频 (WAV/FLAC/MP3) + lyrics_timing.json (唯一的可编辑源)
├── footage/ # 视频素材、照片、可能的 logo
├── renders_vfx/ # EffectCraft 中间渲染:V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/ # PNG 截图 (render-frame) + 带音频的短视频预览 MP4(例如副歌、独奏段)
├── projects/ # .ecproj 和 .fcproj 文件
├── scripts/ # 特定于该视频的生成器(重要:共享的 T3 Code 工具)
└── exports/ # 最终交付物 1080p:*_lyrics.mp4 和 *_clean.mp4
兼容的交换格式
- 带透明度的歌词与叠加层 (
V2) 从 EffectCraft → FilmCraft:- 推荐(单一文件):QuickTime Apple ProRes 4444 (
.mov),format: "prores",proresProfile: "4444",channels: "rgba",audio: "off"。 - 无损替代方案:PNG 或 OpenEXR 序列 (
channels: "rgba"),在 FilmCraft 中以image_sequence: true导入。 - Alpha 通道禁止用于:
H264、Hevc和Av1不支持 alpha 通道 (alpha: false)。
- 推荐(单一文件):QuickTime Apple ProRes 4444 (
- 不透明视觉场景 (
V1) 从 EffectCraft:format: "prores",proresProfile: "hq",channels: "rgb",audio: "off"。
- 从 FilmCraft 最终交付:
- 网络/分发:
format: "h264"(.mp4, 预设"High Quality 1080p HD")。 - 主存档:
format: "prores"。(注意:在 Linux 上如果没有硬件编码器,hevc和av1可能不可用。)
- 网络/分发:
分辨率、帧率 (FPS) 和色彩管理对齐
- 从一开始就锁定 EffectCraft (
comp.new) 和 FilmCraft (file.newSequence) 之间共享的唯一年(width, height, fps)对,例如1920×1080以30或24fps。 - 逐帧对齐段落:将每个段落的边界计算为整数帧数 (
f0 / fps .. f1 / fps),以便所有段落的总和精确覆盖音频轨道的实际时长,没有漂移或间隙。 - 色彩空间:两个软件中均使用 SDR 的
workingSpace: "rec709"(EffectCraft 中的file.projectSettings,FilmCraft 中的sequence.colorSettings;如果使用 HDR/Log 素材则使用autoToneMap: true)。 - 时间转换:EffectCraft 使用秒 (
f64);FilmCraft 使用ticks (254016000000ticks =1s),并且在timeline.place中也接受frame/seconds。
3. 关键音乐方法(用耳朵校准、可编辑时间线、独立歌词与纯乐器段落)
A. 用耳朵校准并在母带音频上精确测量结尾
- 始终以 44.1 kHz 测量原始音轨 (
hop = 441= 精确的 10,000 ms) 通过audio_cues.py analyze(切勿使用四舍五入的 22.05 kHz 步长,这会在 3 分钟内造成数百毫秒的漂移)。 - 在锁定剪辑之前在 MP3/WAV 上验证精确结尾:找到最后一个强重音,最后一个鼓/乐器敲击(例如切黑点),以及实际混响结束直到最终寂静。
- 分段实际聆听音轨:将曲目切成重叠的片段(例如 18 秒,重叠 2 秒),然后提取过渡、副歌、和声和乐句结尾附近的短片段 (
audio_cues.py slice),并用耳朵聆听以锁定精确的 BPM 和每个声音入口。
B. 可编辑时间线的单一文件 (audio/lyrics_timing.json) 和不确定标记
将所有歌词时间集中在一个可手动编辑的单一 JSON 文件 (audio/lyrics_timing.json) 中,由 EffectCraft 生成器读取:
meta:音频文件、音频/视频时长(毫秒)、fps、bpm、first_drum_hit_ms、last_accent_ms、black_cut_ms。sections:边界start_ms/end_ms对齐到帧。phrases:start_ms、end_ms和display_end_ms(需要时延长+250到+600 ms,以便即使场景或段落改变,最后一个单词仍然可读)。type: "lead"用于主唱,type: "echo"作为独立条目 用于和声、应答和即兴演唱。words(逐词/词组拆分)仅当某个动画或视觉重音需要时才使用;否则,简洁地显示整个句子。"uncertain": true+"review_note": "..."应用于所有模糊标记(和声、回声、叠加的声乐即兴、短促的叫喊),以便用户轻松手动调整,无需触及代码。
C. 独立歌词图层 (V2 RGBA) 和双轨导出 Master / Clean
- 没有永久的黑边:将每个句子放置在场景的空白区域中(参见 craft-2d-animation §5),带有柔和的投影、安全边距和自动连续性 (
isContIn/isContOut),当display_end_ms跨越场景切变时。 - 专用透明轨道:在独立的合成
L01..Lnn中生成歌词(省略纯乐器段落),渲染为 ProRes 4444 RGBA,并在 FilmCraft 中放置在V2上。 - 将场景内的文字保留在
V1上:标志、屏幕、副本、表格保留在场景V01..Vnn中。 - 严格相同的双轨导出:导出带歌词的版本(
V2启用),然后禁用V2(timeline.setTrack {"track": "V2", "enabled": false}) 以导出纯净版本,其剪辑和音频 100% 相同,然后在最终保存.fcproj之前重新启用V2。
D. 纯乐器段落期间的视觉动作(零泛用音频曲线)
- 禁止使用泛用视觉拐杖:在介绍、独奏或间奏中没有音频曲线、示波器锯齿、装饰性浮动圆圈。
- 针对用耳朵挑选的重音编排手绘动作:门砰然关上,一排顶灯一个接一个亮起,布景像纸板/3D 纸一样在连复段上展开,物体滑动或角色带有预判和保持的姿势变化。
- 在重音之间保持镜头:在两个强拍之间保持清晰稳定的图像,使动作保持可读性。
- 应用通用的 2D 规则:变化的构图(全景 / 过肩镜头 / 侧面 / 特写镜头)、完整的剪影、在变换之前的中性锚点层次结构(参见 craft-2d-animation)。
4. 逐步工作流
步骤 1 — 用耳朵分析音频和时间线骨架
- 以 44.1 kHz 探测母带 (
audio_cues.py analyze) 以获得精确时长、10 ms 瞬态和音轨结尾细节。 - 提取聆听片段 (
audio_cues.py slice) 并聆听以确定精确的 BPM、对齐到帧的段落边界、乐句、回声和最终切点。 - 初始化并填充
audio/lyrics_timing.json,用"uncertain": true+"review_note"标记可疑标记,然后验证 JSON (lyrics_overlay.py --validate)。
步骤 2 — 分解/简短故事板(在任何大型渲染之前)
- 编写一个简短剪辑计划(表格:时间 / 段落 / 地点与构图 / 手绘视觉动作 / 歌词处理)。
- 在启动完整渲染之前,向用户展示分解计划(以及为纯乐器段落选择的 accents)。
步骤 3 — 在 EffectCraft 中创建场景 (V01..Vnn) 和歌词 (L01..Lnn)
- 遵循 craft-2d-animation 中的锚点、中性父子级和堆叠规则(使用
ec_runtime.py)构建 2D 场景 (V01..Vnn)。 - 直接从
audio/lyrics_timing.json通过lyrics_overlay.py生成透明歌词合成 (L01..Lnn,省略纯乐器部分)。 - 通过关键帧的截图 (
render-frame --max-side 960) 进行快速检查(以及在歌词上使用--transparent),以便在视频渲染前立即纠正任何重叠或锚点偏移。 - 带音频的短视频 MP4 预览(例如 1 段副歌 + 1 段独奏):仅渲染这 1-2 个段落,与母带音频的精确片段混合,观看并聆听以根据需要重新调整回声入口、镜头间最后一个单词的保持以及独奏的可读性。
- 完整低功耗渲染到
./renders_vfx/,通过render_ec_batch.sh(一次顺序渲染一个,ProRes HQ RGB 用于V*,ProRes 4444 RGBA 用于L*,通过ffprobe自动恢复)。 - 保存
projects/<clip>.ecproj。
步骤 4 — 在 FilmCraft 中组装和双轨导出
- 通过
assemble_filmcraft.py(或通过 MCPfile.newProject、file.newSequence、media_import、timeline.place、markers.add)组装 Rec.709 序列:A1:原始母带音频不变 (volumeDb: 0.0)V1:V01..Vnn.mov放置在其精确帧 (frame: f0)V2:L01..Lnn.mov(ProRes 4444 RGBA) 放置在相同的精确帧 (audio: false)
- 验证序列 (
inspect sequence) + 渲染几帧复合的V1+V2和仅V1,以确认 alpha 分割和纯净版本中场景内文字的存在。 - 导出带歌词的版本 (
*_lyrics.mp4),禁用V2,导出纯净版本 (*_clean.mp4),然后重新启用V2并保存projects/<clip>.fcproj。
步骤 5 — 强制最终审核(带声 + 无声)
- 带声审核
*_lyrics.mp4导出:检查乐句结尾、副歌切点、回声入口、精确的切黑点以及原始音频轨道的干净结尾。 - 无声审核(静音)
*_clean.mp4导出中的纯乐器段落(独奏、间奏):验证角色的目标和视觉进展在无音频的情况下 100% 可理解,没有任何残留的音频曲线,并且场景内文字完整。 - 展示交付物,并明确列出
lyrics_timing.json中标记为"uncertain": true的标记。
5. 共享的 T3 Code 工具与依赖项
可重用的工具位于 ~/.t3/shared/craft-video/:
| 工具 | 路径 | 音乐视频用途 |
|---|---|---|
| 44.1 kHz 音频分析与切片 | ~/.t3/shared/craft-video/audio_cues.py | 时长... |
[已截断以进行翻译]