Qiaomu Mtv Creator

Qiaomu MTV Creator - AI 音乐视频制作

将 Suno 生成的歌曲自动转换为两类 MV：稳定快速的传统配图字幕版，以及更像音乐视频的 HyperFrames/GSAP 动态歌词版。

V2.4 升级要点

• MTV 审美规则沉淀：新增“画面、字幕、转场、字体、验收”的设计原则。未来不要把 Hyper MV 做成固定底部字幕的幻灯片；每首歌都要有和歌词意象一致的 motion grammar。
• 字幕系统升级：默认 Hyper 模板要使用多安全区 anchor、轻微倾斜、词级 stagger、回声/描边/玻璃质感等可控变化。字幕可以不规则，但必须服务歌曲气质；避免逐帧抖动、过度缩放、粗糙旋转和一直居中。
• 转场系统升级：图片之间不只做淡入淡出。默认组合柔和溶解、玻璃擦拭、光扫、纹理遮罩、轻微场景分层，让镜头推进保留，同时让 scene change 有记忆点。
• 字体本地化：Hyper 模板默认打包 Anton + Space Grotesk 本地 woff2，避免渲染时回退到系统字体导致质感变差或不同机器表现不一致。
• 去模板痕迹：片头必须使用真实歌曲标题，优先从 LRC [ti:]、项目元数据或字幕文件名读取，并清理 clip/hash 后缀；motion profile、debug label、URL slug、占位文字不能出现在成片里。
• 固定作者署名：所有歌曲作者/artist/author 默认写 向阳乔木。不要从 Suno、文件名、URL、LRC [by:] 或模型输出里猜作者；片头需要署名时也使用 向阳乔木。
• 音频 UI 默认关闭：波形、频谱、进度条、节拍脉冲不再作为默认装饰。只有当歌曲概念明确需要“播放器/电台/信号/电子可视化”时才打开；冷感、叙事、梦幻歌曲默认不出现这些界面化元素。
• 渲染脚本稳定化：render_hyper_mtv.py 默认使用本机 Puppeteer headless shell、streaming encode、长超时、缓存限制和 SDR 输出，并按可回收内存选择 worker，减少手动拼环境变量和系统 Chrome 崩溃概率。

V2.3 升级要点

• 新名字：主 skill 名为 qiaomu-mtv-creator；旧名 mtv-creator 不再保留，避免别名误触发。
• 单源目录：skill 实体只放在 /Users/joe/.agents/skills/qiaomu-mtv-creator；不要再创建 .claude 兼容软链或 mtv-creator 旧名入口。
• 双模式：classic 保留传统 FFmpeg 配图字幕工作流；hyper 用 HyperFrames + GSAP 制作动态歌词、场景内排版、音频响应和更丰富转场。
• GSAP 官方技能吸收：已吸收 greensock/gsap-skills 的 core/timeline/plugins/utils/performance 规则，落到 references/gsap-mtv-motion.md，并由 scripts/create_hyper_mtv.py 自动生成更丰富的 HyperFrames/GSAP MTV 工程。
• 动效谱系：Hyper 模式新增 cinematic、poster、glitch、dream、minimal 五个 motion profile，用 GSAP timeline labels、position parameter、stagger、transform aliases、autoAlpha、gsap.utils.wrap() 等模式组织场景、歌词、粒子、光扫和节拍脉冲。
• 渲染加速策略：新增 scripts/render_hyper_mtv.py，根据可用内存选择 HyperFrames quality/fps/workers；低内存时先提示清理，不再默认硬开 auto workers。
• SRT/LRC 统一：自动识别 Suno 同版本 .srt / .lrc，LRC 会转换为项目内可烧录 SRT。
• 项目化输出：每次生成 project.json、timeline.json、preflight_report.json、storyboard.html。
• 可恢复阶段：通过 --stage preflight|prepare|storyboard|images|compose|hyper|all 分步运行。
• Codex 生图优先：--image-provider auto 在 Codex 环境中解析为 codex-plan，优先让 Codex 内置生图接管关键帧；只有 Codex 生图不可用或非 Codex 运行时才回退即梦。
• 字幕 fallback：如果本机 FFmpeg 没有 subtitles / drawtext filter，会自动用 Pillow 渲染透明字幕层再 overlay。

核心流程

Suno 歌曲（含 .srt / .lrc 精准歌词）
    ↓
解析为统一 timeline.json → preflight 检查 → storyboard.html
    ↓
Claude/Codex 读歌词 → 分析歌曲结构 → 生成 visual_config.json
    ↓
生图：优先 Codex 内置生图计划；失败或不可用时才用即梦批量落盘 fallback
    ↓
合成 MV：classic 用 FFmpeg；hyper 用 HyperFrames + GSAP kinetic timeline
    ↓
输出: MTV 视频 (MP4)

⚠️ 重要原则

1. 用 Suno SRT，不用 Whisper：Suno 生成歌曲时已自动生成精准 SRT，路径与 mp3 同目录，优先使用
2. Claude 直接生成描述：Claude Code 本身就是大模型，读 SRT 后直接生成视觉描述，不调第三方 API
3. 音频选版本：Suno 会生成两个版本（.mp3 和 -1.mp3），选时长更长、覆盖所有 SRT 时间戳的版本
4. skill 单源在 .agents：所有新增和修改都落在 /Users/joe/.agents/skills/qiaomu-mtv-creator；不要恢复 .claude 兼容软链或旧 mtv-creator 别名
5. Codex 生图优先，不先跑即梦：Codex 内置生图质量通常更适合关键帧；脚本生成 codex_image_requests.md 供 Codex 接管。只有 Codex 生图不可用、用户明确要求 fallback、或非 Codex 自动运行时，才使用即梦。
6. Suno 资料先走 qiaomu-suno-master：遇到 Suno URL、clip ID、下载音频、导出 LRC/SRT，先使用 /Users/joe/.agents/skills/qiaomu-suno-master，不要先手写抓页面。
7. Hyper 渲染先看内存：hyperframes render --workers auto 在可用内存很低时会同时启动多个浏览器并失败；最终渲染前先跑 render_hyper_mtv.py --dry-run，低于阈值时请用户清理内存，除非用户接受慢速 --allow-low-memory。
8. GSAP 只用可渲染时间线：HyperFrames 里 GSAP 必须同步创建 paused timeline，注册到 window.__timelines.main；不要 tl.play()、不要 Date.now() / Math.random() / 网络 fetch / 无限 repeat。
9. MV 不是歌词 PPT：默认避免“整首歌固定底部居中字幕 + 每张图同一种淡入淡出”。字幕、转场、镜头和氛围层都要有歌曲自己的节奏，但不能抢歌词。
10. 字幕稳定优先：字幕动效可以丰富，但不能抖。优先使用 autoAlpha、y、低幅度 rotation、词级 stagger 和长一点的 sine/power ease；少用大幅 scale、rotationX、短促抖动和频繁 filter 切换。
11. 从歌词意象生成 motion grammar：玻璃、雨、盐、霓虹、纸张、广播、海、风等意象要变成对应的视觉动效语言，例如 glass wipe、rain streak、salt grain、signal scan、paper slip，而不是套同一套模板。
12. 不要让模板身份露出：片头可以有设计标题，但不能出现 Poster Motion、cinematic motion、placeholder、URL slug、clip id/hash、脚本调试名。真实歌名优先从 LRC [ti:] 获取，例如 Salt On Glass，不要显示 salt-on-glass-ba258447。
13. 不要把 MV 做成播放器界面：波形、频谱、进度条、均衡器、底部节拍线默认关闭。除非歌曲主题是广播、电台、信号、俱乐部、电子设备或用户明确要求，否则这些元素会破坏沉浸感。
14. 作者固定为向阳乔木：项目元数据、HyperFrames mtv-data.json、片头署名、发布说明中的歌曲作者统一写 向阳乔木，不要使用 Suno AI、下载账号、文件名、URL slug 或 LRC [by:] 作为作者。

MTV 设计原则与风格原则

做 Hyper MTV 时先定一个 4 层视觉系统，而不是直接套模板：

1. 画面层：关键帧要有统一摄影/插画风格、稳定色彩、重复母题。镜头推进可以慢，但每个段落的推进方向、焦点和速度要略有差别。
2. 字幕层：字幕是 MV 的表演者，不是外挂字幕。每行歌词可以在 4-7 个安全 anchor 中切换：左下、右上、右中、左墙、低位桌面、居中宽屏等。位置变化要和画面负空间匹配，不能遮住主要主体。
3. 字体层：每支 MV 至少有明确字体气质。优先选择凝练、有音乐感的 display sans / condensed sans；不要默认系统粗体一直居中。温柔歌用窄体、细腻阴影、低对比回声；强烈歌再用红色描边、glitch、切片。
4. 转场层：每个 scene change 至少叠加两种转场语言，例如 cross-dissolve + glass sweep、soft bloom + texture wipe、rain scan + parallax drift。避免所有图片之间同一种 xfade。
5. 氛围层：粒子、波形、光扫、噪声、进度条要低调服务节奏。不要为了“动”而动；能表达歌词母题的动效优先。
6. 片头层：片头是作品的一部分，不是模板封面。只显示真实歌名或经过设计的短标题；作者署名统一写 向阳乔木。不要显示 motion profile、工程名、哈希后缀、下载文件名、调试标签。

字幕风格要按歌曲气质调节：

• 梦幻/怀旧/冷感：位置有轻微漂移但不跳；文字可偏左/偏右，带玻璃回声、柔和描边、低透明度重复影；转场用长溶解、光扫、雾化遮罩。
• 摇滚/脏感/强节拍：可使用更大字号、upper-case、红色/暖色强调词、切片、扫描线和短促冲击，但要控制在副歌或强拍。
• 民谣/叙事/安静：减少字词拆分，使用低位、侧边或画面负空间的排版；用纸张、影子、窗光、慢变焦表达段落。
• 电子/赛博/不稳定：允许 glitch、scanline、短促位移和硬切，但要避免全程抖动造成阅读疲劳。

质量门槛：

• 抽帧时不能整首歌都像同一个字幕位置的重复截图。
• 相邻两三帧字幕边缘不应出现肉眼可见抖动。
• 转场不能黑屏，不能只有硬淡出；至少几处 scene change 要能看出歌曲母题。
• 标题/水印式模板文字默认只用于片头，不能整首歌常驻左上角干扰歌词；片头也不能出现 profile label、slug 或 hash。
• 波形、频谱、进度条、节拍线这类播放器 UI 默认不出现；抽帧看到它们时，需要能说清楚它们为什么属于这首歌。

标准工作流（Claude Code 操作）

Step 1：准备项目与 Storyboard

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --stage prepare

检查输出：

project.json
timeline.json
preflight_report.json
storyboard.html
visual_config.json
codex_image_requests.md

Step 2A：Codex 内置生图接管关键帧（默认优先）

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --stage prepare

然后由 Codex 读取 codex_image_requests.md 逐张生成 images/scene_XX.png。完成后：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage compose

Step 2B：即梦 fallback（仅 Codex 生图不可用时）

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --style ink-painting \
    --ratio 16:9 \
    --output ~/Videos/MTV/项目名/ \
    --skip-transcribe \
    --subtitle "/path/to/song.srt" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage images \
    --image-provider jimeng \
    --workers 5

Step 2C：HyperFrames / GSAP 动态歌词 MV（推荐模式）

适合用户明确要求“不像幻灯片”“歌词更酷”“画面随音乐动”“参考 HyperFrames”的任务。传统 classic 模式仍然保留；hyper 是更高表现力、更慢但更像 MV 的模式。

工作流：

1. 先用本 skill 的 prepare 生成 timeline.json、visual_config.json、关键帧生图计划。
2. 用 Codex 内置生图生成 images/scene_XX.png。
3. 运行 --stage hyper 自动生成 hyper-mv/：复制音频/关键帧，写入 assets/mtv-data.js，创建本地 assets/gsap.min.js 和 GSAP-rich index.html。
4. 先运行 npm run check 和 npx hyperframes inspect --samples 24，确认没有 console error、对比度问题、歌词越界。
5. 快速预览用 draft profile，最终版用 final profile。

生成 HyperFrames 工程：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio "/path/to/song-1.mp3" \
    --subtitle "/path/to/song.srt" \
    --visual-config "/path/to/project/visual_config.json" \
    --stage hyper \
    --motion-profile cinematic

动效谱系：

快速预览：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile review

最终渲染：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile final \
    --check

优先使用 render_hyper_mtv.py 而不是手写 npx hyperframes render。脚本会自动：

• 选择本机 Puppeteer chrome-headless-shell，避免系统 Chrome 版本/权限导致渲染不稳。
• 开启 streaming encode，长视频不先堆满帧缓存。
• 设置 Puppeteer 启动/协议超时、帧缓存上限和 --sdr。
• 按内存自动选择 worker；需要更快时先看 --dry-run 输出，再决定是否显式 --workers 2/3。

如果脚本提示 LOW MEMORY，先请用户清理内存或关闭重型应用，再重新渲染。只有用户明确接受“慢一点也行”时，才使用：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/render_hyper_mtv.py \
    --project "/path/to/project/hyper-mv" \
    --profile final \
    --allow-low-memory

刚才实测教训：hyperframes render --workers auto 在 0.3GB immediate free memory 时会校准后尝试多 worker，随后多个浏览器进程同时启动失败；--workers 1 可以完成，但 220 秒 1080p 视频耗时约 7 分 39 秒。因此默认策略是：内存足够时多 worker 换速度，内存低时先问用户清理，而不是静默退到慢速。

参数说明

风格推荐

完整风格列表见 qiaomu-image-generator skill。

工作流详解

Step 1: 字幕与时间轴

优先使用 Suno 同目录字幕：

• 精确匹配 歌名.mp3 → 歌名.srt / 歌名.lrc
• 精确匹配 歌名-1.mp3 → 歌名-1.srt / 歌名-1.lrc
• LRC 自动转换为项目内 SRT
• 只有找不到 Suno 字幕时才调用 whisper-transcribe
• 输出 timeline.json 和 preflight_report.json

Step 2: 分析歌词生成配图描述

Claude 分析歌词，为每个段落生成视觉描述：

• 提取核心意象和情感
• 转换为纯视觉语言（无文字）
• 生成 visual_config.json

示例：

歌词: "午夜的终端闪烁着光，键盘就是我的战场"
描述: "深夜办公室，一个人影坐在发光的屏幕前，手指悬停在键盘上，周围是代码的光影"

Step 3: 生成配图

默认优先 Codex 内置生图：

• --image-provider auto 在 Codex 环境中生成 codex_image_requests.md
• 审阅 codex_image_requests.md
• 用 Codex 内置生图生成 images/scene_XX.png

即梦只作为 fallback：

• Codex 生图不可用、用户明确接受 fallback，或非 Codex 环境中 auto 运行时，才调用 qiaomu-image-generator
• fallback 时显式使用 --image-provider jimeng

Step 4: 合成视频

classic 模式调用内置 FFmpeg 合成：

• 音频 + 图片 + 字幕 → MP4
• 平滑转场效果
• 专业字幕烧录
• 自动修正 xfade 重叠造成的时长缩短

hyper 模式调用 scripts/create_hyper_mtv.py：

• 读取 project.json、timeline.json、visual_config.json
• 复制音频和 images/scene_XX.* 到 hyper-mv/assets/
• 安装并复制本地 gsap.min.js，避免 CDN 在渲染时失败
• 生成一个 paused GSAP master timeline：scene layers、kinetic lyrics、beat pulse、wave bars、particles、progress
• 后续用 scripts/render_hyper_mtv.py 做 review/final 渲染

输出结构

~/Videos/MTV/代码丛林_20260125/
├── 代码丛林.mp4           # 最终 MTV
├── project.json           # MTV 项目元数据
├── timeline.json          # 统一字幕/场景时间轴
├── preflight_report.json  # 输入、依赖、字幕覆盖率检查
├── storyboard.html        # 可审阅分镜预览
├── codex_image_requests.md # Codex 内置生图 prompt 清单
├── audio/
│   └── 代码丛林.mp3       # 原始音频
├── subtitles/
│   ├── 代码丛林.srt       # 字幕文件
│   └── 代码丛林.json      # 时间轴 JSON
├── images/
│   ├── scene_01.png       # 配图 1
│   ├── scene_02.png       # 配图 2
│   └── ...
├── visual_config.json     # 配图配置
├── metadata.json          # 项目元数据
└── hyper-mv/              # HyperFrames/GSAP 动态歌词工程（--stage hyper）
    ├── index.html
    ├── package.json
    └── assets/
        ├── mtv-data.js
        ├── gsap.min.js
        ├── song.mp3
        └── images/

与其他 Skills 的关系

GSAP / HyperFrames 动效规则

详细规则见 references/gsap-mtv-motion.md。做 Hyper MTV 时至少遵守：

• 用 gsap.timeline({ paused: true })，注册 window.__timelines.main。
• 用 labels 和 position parameter 编排场景、歌词、节拍，不用散乱 delay。
• 优先 transform aliases 和 autoAlpha；少动画 layout 属性。
• gsap.utils.wrap() / clamp() / toArray() 用于确定性映射，不用 Math.random()。
• 默认核心 GSAP 足够；SplitText、ScrambleText、MotionPath、DrawSVG、MorphSVG 等插件只在本地 asset 可用且显式注册时使用。

推荐工作流（Claude 生成描述）

最佳实践：让 Claude 分析歌词并生成视觉描述，而不是使用简单的关键词匹配。

Step 1: 准备阶段

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识库/04.素材/AI音乐/代码丛林.mp3 \
    --prepare-only \
    --scenes 8

这会输出每个场景的歌词，等待 Claude 生成视觉描述。

Step 2: Claude 生成描述

在 Claude Code 对话中：

用户：为以下歌词场景生成视觉描述（纯视觉语言，不要文字）：

场景 1: "午夜的终端闪烁着光，键盘就是我的战场"
场景 2: "代码在眼前不停旋转，这个 Bug 藏得太深太远"
...

Claude：
场景 1: 深夜办公室，一个人影坐在发光的屏幕前，手指悬停在键盘上，周围是代码的光影
场景 2: 迷宫般的电路板，一个人在其中寻找出路，远处有微弱的光点
...

Step 3: 更新配置并生成

将 Claude 生成的描述更新到 visual_config.json，然后：

python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识库/04.素材/AI音乐/代码丛林.mp3 \
    --visual-config ~/Videos/MTV/代码丛林_20260125/visual_config.json \
    --skip-transcribe

完整示例

从 Suno 歌曲到 MTV

# 1. 生成歌曲（suno-music-creator）
python /Users/joe/.agents/skills/suno-music-creator/scripts/generate_music.py \
    '{"title":"代码丛林","prompt":"[Verse 1]...","tags":"rock"}' \
    --download

# 2. 一键生成 MTV（本 skill）
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio ~/乔木新知识��/04.素材/AI音乐/代码丛林.mp3 \
    --style newyorker \
    --ratio 9:16

自定义配图数量

# 指定生成 6 张配图
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --scenes 6 \
    --style watercolor

使用已有素材

# 跳过转录，使用已有 SRT
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --skip-transcribe \
    --subtitle existing.srt

# 跳过生图，使用已有图片
python /Users/joe/.agents/skills/qiaomu-mtv-creator/scripts/create_mtv.py \
    --audio song.mp3 \
    --skip-images \
    --images-dir ./my_images/

常见问题

字幕位置优化

根据各平台 UI 安全区域研究：

9:16 竖屏（TikTok/抖音）

• 底部安全区域：250px（被 UI 按钮覆盖）
• 字幕位置：距离底部 280px
• 字体大小：32px
• 右侧边距：120px（避开点赞/评论按钮）

16:9 横屏（YouTube/B站）

• 底部安全区域：60px
• 字幕位置：距离底部 60px
• 字体大小：28px

视频格式兼容性

为确保社交媒体平台兼容，视频自动使用：

• 编码：H.264 High Profile Level 4.0
• 像素格式：yuv420p（不是 yuv444p）
• 宽高比：SAR 1:1 + 正确的 DAR

依��安装

# Whisper
pip install faster-whisper

# FFmpeg (macOS)
brew install ffmpeg

# 图片处理
pip install Pillow

注意事项

1. 音乐转录：必须禁用 VAD（--no-vad），否则唱歌会被过滤
2. 配图描述：使用纯视觉语言，不要包含文字
3. 视频比例：抖音/TikTok 用 9:16，B站/YouTube 用 16:9
4. 生成时间：完整流程约 5-10 分钟（取决于配图数量）
5. SRT 版本必须匹配：Suno 为每个版本生成独立 SRT（歌名.srt 对应 歌名.mp3，歌名-1.srt 对应 歌名-1.mp3），两者时间轴不同，混用会导致画面和歌词错位约10秒。使用 将进酒-1.mp3 时必须用 将进酒-1.srt。
6. Suno 可能生成重叠时间戳：部分条目 start 时间相同（如同时演唱），脚本已自动去重，不影响效果。