Communitygithub.com

craft-music-video

指导AI助手规划、构建或剪辑音乐视频,确保输出结果可以逐镜头验证。流程涵盖 EffectCraft 和 FilmCraft 两大工具的使用、MCP 与沙箱环境检查、角色分工以及完整的制作流水线。

craft-music-video 是什么?

该技能(Skill)提供了一套可复用的工作流,用于制作与音频轨道同步的音乐视频。它结合了 EffectCraft(制作 2D 场景、动态图形、VFX 以及独立的透明歌词图层)和 FilmCraft(主多轨剪辑、节奏同步、音频混音/母带、全局调色、双轨导出(带歌词版与纯净版))。技能详细说明了 MCP 服务器和沙箱环境的初始化检查(包括 Flatpak 配置注意事项),并严格区分了 EffectCraft 和 FilmCraft 的职责范围:EffectCraft 负责动画场景和歌词图层(以 RGBA 格式导出),FilmCraft 负责最终的多轨剪辑、歌词与场景的精确帧对齐、颜色校正和双轨导出。核心工作流强调“用耳朵校准”——通过 44.1 kHz 音频分析和手动切片聆听来精确定位 BPM、乐句节奏和结尾点,所有时间信息统一存储在一个可编辑的 `audio/lyrics_timing.json` 文件中。歌词以独立的 RGBA 轨道(`V2`)叠加在 `V1` 场景之上,导出时可单独开关以生成带词和纯净两个版本。对于纯乐器段落,该技能禁止使用通用音频波形曲线等视觉“拐杖”,而是鼓励设计基于挑选出的音乐重音的、有叙事性的视觉动作(如门砰然关上、灯光逐个亮起)。最终交付物必须经过带声和无声双重审核,确保在无音频的情况下剧情依然清晰可辨。该技能依赖一系列共享工具(位于 `~/.t3/shared/craft-video/`),包括音频分析脚本、歌词叠加脚本和批量渲染脚本。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

制作音乐视频(FilmCraft + EffectCraft)

可复用的工作流,用于制作与音频轨道同步的音乐视频,结合 EffectCraft(2D 场景、动态图形、VFX、独立的透明歌词图层)和 FilmCraft(主多轨剪辑、节奏同步、音频混音/母带、全局调色、双轨导出 Master + Clean)。

常见的 2D 动画方法(构图、带预判的姿势变换、角色/摄像机锚点、EffectCraft 的父子级陷阱、图层的堆叠顺序以及文字的可读性):请遵循 craft-2d-animation。

完整的 MCP 参考、已验证的引擎命令和 Flatpak 配置:references/mcp-and-commands.md。


0. MCP 和沙箱前置条件(启动前检查)

  1. 检查当前会话中是否已暴露 effectcraft 和 filmcraft 的 MCP 服务器(或干净地切换到 effectcraft-cli / filmcraft-cli CLI)。
    • 如果缺失,不要凭空捏造调用:请查阅 references/mcp-and-commands.md 以获取准确的配置(Flatpak Linux ai.storyteller.filmcraft / ai.storyteller.effectcraft 或原生二进制,以 headless 或 bridge 模式运行)。
  2. 注意 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
  3. 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)。
  • 不透明视觉场景 (V1) 从 EffectCraft:
    • format: "prores", proresProfile: "hq", channels: "rgb", audio: "off"。
  • 从 FilmCraft 最终交付:
    • 网络/分发:format: "h264" (.mp4, 预设 "High Quality 1080p HD")。
    • 主存档:format: "prores"。(注意:在 Linux 上如果没有硬件编码器,hevc 和 av1 可能不可用。)

分辨率、帧率 (FPS) 和色彩管理对齐

  1. 从一开始就锁定 EffectCraft (comp.new) 和 FilmCraft (file.newSequence) 之间共享的唯一年 (width, height, fps) 对,例如 1920×1080 以 30 或 24 fps。
  2. 逐帧对齐段落:将每个段落的边界计算为整数帧数 (f0 / fps .. f1 / fps),以便所有段落的总和精确覆盖音频轨道的实际时长,没有漂移或间隙。
  3. 色彩空间:两个软件中均使用 SDR 的 workingSpace: "rec709"(EffectCraft 中的 file.projectSettings,FilmCraft 中的 sequence.colorSettings;如果使用 HDR/Log 素材则使用 autoToneMap: true)。
  4. 时间转换:EffectCraft 使用秒 (f64);FilmCraft 使用ticks (254016000000 ticks = 1 s),并且在 timeline.place 中也接受 frame / seconds。

3. 关键音乐方法(用耳朵校准、可编辑时间线、独立歌词与纯乐器段落)

A. 用耳朵校准并在母带音频上精确测量结尾

  1. 始终以 44.1 kHz 测量原始音轨 (hop = 441 = 精确的 10,000 ms) 通过 audio_cues.py analyze(切勿使用四舍五入的 22.05 kHz 步长,这会在 3 分钟内造成数百毫秒的漂移)。
  2. 在锁定剪辑之前在 MP3/WAV 上验证精确结尾:找到最后一个强重音,最后一个鼓/乐器敲击(例如切黑点),以及实际混响结束直到最终寂静。
  3. 分段实际聆听音轨:将曲目切成重叠的片段(例如 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

  1. 没有永久的黑边:将每个句子放置在场景的空白区域中(参见 craft-2d-animation §5),带有柔和的投影、安全边距和自动连续性 (isContIn / isContOut),当 display_end_ms 跨越场景切变时。
  2. 专用透明轨道:在独立的合成 L01..Lnn 中生成歌词(省略纯乐器段落),渲染为 ProRes 4444 RGBA,并在 FilmCraft 中放置在 V2 上。
  3. 将场景内的文字保留在 V1 上:标志、屏幕、副本、表格保留在场景 V01..Vnn 中。
  4. 严格相同的双轨导出:导出带歌词的版本(V2 启用),然后禁用 V2 (timeline.setTrack {"track": "V2", "enabled": false}) 以导出纯净版本,其剪辑和音频 100% 相同,然后在最终保存 .fcproj 之前重新启用 V2。

D. 纯乐器段落期间的视觉动作(零泛用音频曲线)

  1. 禁止使用泛用视觉拐杖:在介绍、独奏或间奏中没有音频曲线、示波器锯齿、装饰性浮动圆圈。
  2. 针对用耳朵挑选的重音编排手绘动作:门砰然关上,一排顶灯一个接一个亮起,布景像纸板/3D 纸一样在连复段上展开,物体滑动或角色带有预判和保持的姿势变化。
  3. 在重音之间保持镜头:在两个强拍之间保持清晰稳定的图像,使动作保持可读性。
  4. 应用通用的 2D 规则:变化的构图(全景 / 过肩镜头 / 侧面 / 特写镜头)、完整的剪影、在变换之前的中性锚点层次结构(参见 craft-2d-animation)。

4. 逐步工作流

步骤 1 — 用耳朵分析音频和时间线骨架

  1. 以 44.1 kHz 探测母带 (audio_cues.py analyze) 以获得精确时长、10 ms 瞬态和音轨结尾细节。
  2. 提取聆听片段 (audio_cues.py slice) 并聆听以确定精确的 BPM、对齐到帧的段落边界、乐句、回声和最终切点。
  3. 初始化并填充 audio/lyrics_timing.json,用 "uncertain": true + "review_note" 标记可疑标记,然后验证 JSON (lyrics_overlay.py --validate)。

步骤 2 — 分解/简短故事板(在任何大型渲染之前)

  1. 编写一个简短剪辑计划(表格:时间 / 段落 / 地点与构图 / 手绘视觉动作 / 歌词处理)。
  2. 在启动完整渲染之前,向用户展示分解计划(以及为纯乐器段落选择的 accents)。

步骤 3 — 在 EffectCraft 中创建场景 (V01..Vnn) 和歌词 (L01..Lnn)

  1. 遵循 craft-2d-animation 中的锚点、中性父子级和堆叠规则(使用 ec_runtime.py)构建 2D 场景 (V01..Vnn)。
  2. 直接从 audio/lyrics_timing.json 通过 lyrics_overlay.py 生成透明歌词合成 (L01..Lnn,省略纯乐器部分)。
  3. 通过关键帧的截图 (render-frame --max-side 960) 进行快速检查(以及在歌词上使用 --transparent),以便在视频渲染前立即纠正任何重叠或锚点偏移。
  4. 带音频的短视频 MP4 预览(例如 1 段副歌 + 1 段独奏):仅渲染这 1-2 个段落,与母带音频的精确片段混合,观看并聆听以根据需要重新调整回声入口、镜头间最后一个单词的保持以及独奏的可读性。
  5. 完整低功耗渲染到 ./renders_vfx/,通过 render_ec_batch.sh(一次顺序渲染一个,ProRes HQ RGB 用于 V*,ProRes 4444 RGBA 用于 L*,通过 ffprobe 自动恢复)。
  6. 保存 projects/<clip>.ecproj。

步骤 4 — 在 FilmCraft 中组装和双轨导出

  1. 通过 assemble_filmcraft.py(或通过 MCP file.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)
  2. 验证序列 (inspect sequence) + 渲染几帧复合的 V1+V2 和仅 V1,以确认 alpha 分割和纯净版本中场景内文字的存在。
  3. 导出带歌词的版本 (*_lyrics.mp4),禁用 V2,导出纯净版本 (*_clean.mp4),然后重新启用 V2 并保存 projects/<clip>.fcproj。

步骤 5 — 强制最终审核(带声 + 无声)

  1. 带声审核 *_lyrics.mp4 导出:检查乐句结尾、副歌切点、回声入口、精确的切黑点以及原始音频轨道的干净结尾。
  2. 无声审核(静音)*_clean.mp4 导出中的纯乐器段落(独奏、间奏):验证角色的目标和视觉进展在无音频的情况下 100% 可理解,没有任何残留的音频曲线,并且场景内文字完整。
  3. 展示交付物,并明确列出 lyrics_timing.json 中标记为 "uncertain": true 的标记。

5. 共享的 T3 Code 工具与依赖项

可重用的工具位于 ~/.t3/shared/craft-video/:

工具路径音乐视频用途
44.1 kHz 音频分析与切片~/.t3/shared/craft-video/audio_cues.py时长...

[已截断以进行翻译]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能