
lyric-mv-kit
代码 MV 创作包:用 Suno v6 写歌,用 HyperFrames 做逐字踩拍的歌词 MV(起步工程 + 工具 + Claude Code 导演技能 + 教程)
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up lyric-mv-kit (git-clone project) into my current project. Found on https://claudeers.com/lyric-mv-kit Repo: https://github.com/archerzjp-dev/lyric-mv-kit Homepage/docs: — Detected install method: git-clone → git clone https://github.com/archerzjp-dev/lyric-mv-kit Category: devtools. Platforms: cli. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
git clone https://github.com/archerzjp-dev/lyric-mv-kit
// compatibility
| Platforms | cli |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | JavaScript |
代码 MV 创作包:用 Suno v6 写歌,用 HyperFrames 做逐字踩拍的歌词 MV
这个仓库教你做一种 MV:画面全部由代码生成,每一帧只由歌曲时间决定,歌词逐字做进画面,所有冲击落在量出来的拍点上,最后逐帧渲成 1080p 或真 4K。 没有拍摄,没有素材库,也不是在视频软件里拖关键帧。
示范作品:《越界》(词曲:张狗剩)。做《越界》时我借鉴了 Giacomo Magnanini 的开源项目 mexicat/pdoom-video(MIT 许可),画面引擎就是在它的基础上改的,见文末“致谢”。
怎么用
先选一条路:
| 你是 | 走哪条 | 要多久上手 |
|---|---|---|
| 想做一支自己的 MV,用 Claude Code | 路线一:装技能,把歌交给 Claude,它带着你一步步做 | 十分钟 |
| 会写一点 JavaScript,想自己动手 | 路线二:拷一份起步工程,自己写场景 | 一小时 |
| 只想学方法 | 路线三:从“第一部分”往下读 | — |
三条路都要先装好:Node.js(新版)、Google Chrome、ffmpeg(Mac:brew install ffmpeg)。HyperFrames 不用单独装,npx hyperframes 会自己取。
先看一眼示范(两分钟)
git clone https://github.com/archerzjp-dev/lyric-mv-kit.git
cd lyric-mv-kit/starter
bash tools/demo-audio.sh # 生成一段 16 秒的示范音频
npx hyperframes preview # 打开预览,拖时间轴看三个示范场景
路线一:让 Claude Code 带你做
1. 装技能(在克隆下来的仓库里运行,只需一次;以后仓库更新了再跑一次就是升级)
bash install.sh # 装本仓库的导演技能,连同起步工程
npx hyperframes skills # 装 HyperFrames 官方技能
2. 准备一个文件夹,放进:
- 歌:
歌名.wav(尽量用 WAV,不要 MP3) - 歌词:
歌词.txt,一行一句,和实际唱的一致 - 分轨(有的话):人声、鼓……放进
分轨/子文件夹。Suno Studio 能导出(见第一部分 1.8)
3. 在这个文件夹里打开 Claude Code,说:
给这首歌做一支 MV。歌是 歌名.wav,歌词在 歌词.txt,分轨在 分轨/ 里。
先量拍点、对歌词,然后给我三个视觉方向的静帧让我选。
4. 它会一步一步停下来给你看,你看过点头它再往下:
- 拍点和逐字时间,加一页误差自检
- 段落表:每段的能量、情绪、能画的东西
- 三个视觉方向,每个一张真渲染的静帧,你选一个
- 视觉方案(颜色、字、母题、每段画什么)
- 一段 15–20 秒做到成片质量的样片
- 一段一段写场景,每段给你看关键帧
- 整片审片、返工
- 出 1080p 和 4K
随时可以在另一个终端里运行 npx hyperframes preview 自己拖着看。反馈越具体越好:“2:31 这一帧字太小读不出”比“不够炫”有用得多。
路线二:自己写
cp -R starter ~/我的MV && cd ~/我的MV # 每支片子拷一份起步工程
cp ~/路径/歌名.wav assets/song.wav
然后按顺序:
| 步 | 做什么 | 怎么做 |
|---|---|---|
| 1 | 改片长 | index.html 里三处 16 改成歌的秒数 |
| 2 | 量拍点 | 见第二部分的三条命令,生成 data/music.js |
| 3 | 逐字时间 | 双击 tools/tap.html,载入歌、贴歌词、按空格打点,导出的 lyrics.js 放进 data/ |
| 4 | 字体 | 开源重字体放到 assets/fonts/display.ttf,再按 index.html 里字体那段的注释换一行 |
| 5 | 写场景 | 照着 scenes.js 里的三个示范改,场景表在文件末尾 |
| 6 | 看 | npx hyperframes preview,npx hyperframes snapshot --at 12,45 |
| 7 | 查 | npx hyperframes check |
| 8 | 出片 | 见第七部分 |
lib/mv.js 里每个工具都有中文注释;写场景的手艺见第五部分。
仓库里有什么
| 东西 | 在哪 | 干什么 |
|---|---|---|
| 起步工程 | starter/ | 能直接渲染的 HyperFrames 工程:画布舞台、逐字卡拉 OK、踩拍工具库 lib/mv.js、三个示范场景 |
| 工具 | starter/tools/ | beatgrid.mjs 量拍点网格,tap.html 逐字打点,demo-audio.sh 生成示范音频 |
| 创作技能 | skill/lyric-mv-director/ | 给 Claude Code 的导演流程:视觉系统、歌词进画面的手法库、写场景的手艺、审片清单、模板 |
| 安装脚本 | install.sh | 把技能和起步工程装进 ~/.claude/skills/ |
| 这份教程 | README.md | 从写歌到出 4K 的完整方法 |
第一部分:用 Suno v6 写一首为画面准备的歌
大多数人把 Suno 当抽奖机:写一段词、打几个风格词、按生成、挑一首。做 MV 的歌要多走很多步,因为 MV 对歌的要求比“好听”多三条:每个字唱得清楚(逐字点亮时唱糊的字会露馅)、结构给画面留了位置(间奏、停顿、副歌的第一个字)、版本锁死以后不再动(改一个字,所有逐字时间都要重做)。
下面是一条完整的流程。Suno 的功能更新很快,界面上的名字以你看到的为准;这里写的功能以 Suno 帮助中心 2026 年的说明为依据(见文末出处)。
1.1 先写“能拍的词”
动笔前先想好画面会长什么样。一句好的 MV 歌词,里面要有一个能画出来的东西和一个能做出来的动作:
| 不好拍 | 好拍 | 为什么 |
|---|---|---|
| 我很痛苦 | 高墙无声林立 | 有物(墙)、有动作(立起来) |
| 时代很残酷 | 被时代拆解 | “拆解”能直接做成零件分离 |
| 我想要自由 | 誓要劈开这红色的黑夜 | “劈开”是一刀,能落在鼓上 |
写完把每句里的名词和动词圈出来。如果整首歌圈不出一个能贯穿全片的东西(一根线、一面墙、一盏灯),回去改词,比之后在画面上硬凑容易得多。
1.2 结构标签:先把剪辑结构写进歌里
Custom 模式的歌词框里,用结构标签告诉 Suno 每段是什么:
[Intro]
[Verse 1]
风停后 红旗盖住了星空
……
[Pre-Chorus]
……
[Chorus]
誓要劈开这 红色的黑夜
……
[Break]
[Verse 2]
……
[Bridge]
……
[Outro]
帮助中心列出的标签有 [Intro] [Verse 1] [Pre-Chorus] [Chorus] [Bridge] [Break] [Outro]。括号里可以写制作备注,比如 (reverb-heavy vocals)。
为 MV 设计结构时多想一步:
- 前奏留够 8–12 秒:画面要在前奏里建立全片那个“物”。
- 至少一段纯器乐的间奏(
[Break]):没有字的时候,画面才能做全片最大的动作。 - 副歌前断一拍:画面跟着停,副歌第一个字砸下来才有力。
- 最后一段副歌比前面多一次加码:调门升高、配器加满或者多唱一遍,给画面的高潮留位置。
- 尾奏要完整收住,不要淡出:淡出的尾巴画面很难收。
1.3 风格描述写成一份制作说明书
风格框里不要只写“摇滚,悲伤”。按这个顺序写,每一项都具体:
流派和年代:2000s 华语摇滚,后朋克
速度和拍子:132 BPM,4/4,副歌不加速
调式:小调
配器:失真吉他墙、紧凑的底鼓和军鼓、合成器长音铺底、副歌加弦乐
人声:男声,中音区,咬字清楚,主歌压着唱,副歌放开
空间:干声为主,副歌人声加长混响
结构备注:前奏 10 秒只有合成器和心跳一样的底鼓
(这是一个示例,按你这首歌改。)
几个要点:
- 写明速度和“副歌不加速”:生成的歌常常副歌比主歌快 1–3 BPM,后面量拍点时整段会漂。写明了不一定管用,但能减少。
- 写“咬字清楚”:中文的逐字点亮最怕唱糊。
- v6 有一个 Variety(多样性)滑块,按帮助中心的说法,它会改写你的风格提示;放到 0 时风格标签完全按你写的来。定稿阶段建议放到 0。
1.4 三个模型分工
v6 有三个版本(帮助中心):v6(旗舰)、v6-wild(更放飞)、v6-mini(快)。三个都能一次生成最长 8 分钟。v6 和 v6-wild 要 Pro 或 Premier 订阅,v6-mini 所有套餐都能用。
建议这样分工:
- v6-mini 试词:词还在改的时候,用最快的模型听“这句唱出来顺不顺、哪个字唱歪了”。一轮几分钟,改词改到每句都顺。
- v6-wild 找方向:词定了以后,用同一份词、三四种完全不同的风格描述,各生成几轮,找“这首歌原来还可以这样”的那个方向。
- v6 定稿:方向定了,用 v6 反复生成同一个方向,挑最好的那一版。超过两分钟的歌,可以开 Max Mode(帮助中心建议用在两分钟以上的歌和翻唱上,要多花积分)。
1.5 抽卡要有打分表
每次生成两首。定稿阶段一般要十几到几十轮。不要凭印象挑,每一版按这张表打分:
| 项 | 看什么 | 分 |
|---|---|---|
| 钩子 | 副歌第一句听一遍能不能记住 | 1–5 |
| 咬字 | 有没有唱错、唱糊、吞字的地方,记下时间 | 1–5 |
| 结构 | 前奏、间奏、断拍、尾奏是不是按词里的标签来了 | 1–5 |
| 速度 | 有没有明显变速(副歌冲快、尾段拖慢) | 1–5 |
| 音质 | 人声有没有电音感、齿音、底噪,高潮会不会糊成一片 | 1–5 |
最高分的两三版留着,下一步只修它们,不再从头抽。
1.6 局部修:别为一个字重抽整首
定稿版有一两处问题时,用局部修改,不要重新生成:
- Replace Section(替换段落):在波形上选一段,改这段的歌词,点 Recreate Section,Suno 给两个版本,挑一个,它会合成一首新的完整歌曲(帮助中心)。适合:某个字唱错了、某句想换词、桥段重写。选区要从一个乐句的开头选到结尾,接缝才自然。
- 一句话修改:v6 可以用自然语言改某一段或某一句歌词,其余部分保持不变(帮助中心 v6 说明)。
- Extend(续写):歌短了或者尾奏收得不好,从某个位置往后续。
- Crop(裁剪):裁掉开头或结尾多余的部分。
每修一次,回到打分表重新听一遍整首:局部修改有时会改变接缝附近的速度和音色。
1.7 变体:同一首歌的另一张脸
- Cover(翻唱):用另一种风格重做同一首歌,比如童声版、不插电版、慢版。MV 里可以在某一段切到童声版做对照,或者给短视频单独做一版。注意:有说明认为 Remix 类(包括 Cover)的产出只许个人非商业使用,商用前去看当前条款。
- Personas:把一首歌的声音保存下来,下一首接着用同一个“歌手”(Pro/Premier)。做系列作品时,人声统一很重要。
- Voices:录一段自己的声音做验证,用自己的嗓音唱(v5.5 引入)。
1.8 进 Studio:拆分轨、查对拍、导出
Suno Studio(Premier,建议用 Chrome)是浏览器里的多轨编辑器。做 MV 一定要走这一步,因为分轨是后面一切精度的来源:
- 拆分轨:Split from Mix 或 Advanced Split,拆出人声、鼓、贝斯、吉他、键盘、效果等,拆出来的轨在时间上是对齐的。
- 查对拍:帮助中心提醒,新生成的部分有时会稍微抢拍或拖拍。在 Studio 里把鼓轨放大看一遍,抢拖明显的地方回到 1.6 修。
- 导出:整首歌导出 32 位 WAV(不要 MP3),每条分轨也单独导出 WAV。
分轨在 MV 里的用处:
| 分轨 | 用来干什么 |
|---|---|
| 人声 | 逐字对齐:在干人声上找每个字的起点,比在混音上准得多 |
| 鼓 | 量拍点:没有贝斯和合成器干扰,网格不会被拖到反拍上 |
| 贝斯 | 驱动画面里“重”的东西:地面的震动、墙的下沉 |
| 合成器、效果 | 驱动“空气”:雪、雾、光的呼吸 |
1.9 交给 MV 之前
- 锁版本:从这一刻起歌不再改。文件名写上日期和“定稿”。
- 对一遍歌词表和实际演唱:Suno 常多唱一遍、改一个字、加一句和声。MV 照实际唱的做,差异记下来。
- 量响度:
npx hyperframes audio song.wav --only loudness --json。成片直接用这个 WAV,不再压动态。 - 权利:Suno 帮助中心的说法是,生成时是 Pro 或 Premier 订阅,你是这首歌的所有者,可以商用,退订以后也保留;免费版生成的不能商用。2026 年 9 月起的条款对下载渠道、下载次数有新规定。发布前自己去看 suno.com 的当前条款。
第二部分:拍点和逐字时间
这一步决定 MV 看着“准不准”。差 40 毫秒眼睛就看得出慢半拍。
拍点:
npx hyperframes audio assets/song.wav --only onsets --band 30,150 --json > low.json
npx hyperframes audio assets/song.wav --only onsets,envelope --hop-ms 20 --json > full.json
node tools/beatgrid.mjs --low low.json --full full.json --first-downbeat <第一个强拍的秒数> --out data/music.js
有鼓的分轨就用鼓轨量。为什么不直接用 hyperframes beats、这个工具怎么处理变速和反拍、怎么判断结果能不能信,见 skill/lyric-mv-director/references/sync.md。在一首 4 分钟、副歌会变速的歌上(只用混音,没用分轨),它和精细测量的拍点相比误差中位数 3.6 毫秒;鼓稀和变速的几段会偏几十毫秒,工具会把这些位置列出来,让你戴耳机核对。
逐字时间:先说结论,语音转写不能当歌词对齐用,伴奏一厚中文就会编字漏句。要么用 starter/tools/tap.html 逐字打点(0.5 倍速、修偏移,多数字在 ±40 毫秒内),要么在人声分轨上做强制对齐(进阶,见 sync.md)。
第三部分:视觉系统
代码 MV 最常见的失败不是技术,是没有一个统一的想法:每段换一种炫法,四分钟后什么也没记住。动手写代码之前定五件事:
- 一句话概念:一个具体的东西和它的一生(一根线被画出、绷紧、劈开、越过、断掉)。
- 段落表:每段的能量、情绪、能画的物、这段的大动作。副歌是“主场”,每次回来都加码;间奏做最大的动作;静场真的静。
- 三个方向:差在母题、材质、拍法上,不是换颜色。每个方向出同一时刻的一张静帧,选一个。
- 色板不超过五种,只有一个强调色能发光,可以有一个只属于一个时刻的颜色。
- 母题表:3–6 个母题,每个有固定的意思和使用规矩,逐段加码。
详细的方法、材质表、模板:references/visual-system.md、templates/TREATMENT.md。
第四部分:把歌词做进画面
规矩:任何时刻当前这句都在画面里、在安全区内、读得出;字不能在被唱出来之前点亮。
在这个规矩里,让字跟着这句歌词的“物理”走:唱“碾压”时字被压扁,唱“劈开”时字沿裂缝错开,唱“淹没”时水位漫过字,唱“沉默”时字刚唱完就被涂抹条盖住,唱“被同化”时卡拉 OK 反过来、唱到的字变灰。一句一种做法。
二十多种手法和它们的做法:references/lyrics-in-image.md。起步工程的 scenes.js 里示范了三种(字骑在弦上、被重板压扁、灰格子逼近)。
第五部分:写场景
起步工程的结构:
starter/
index.html HyperFrames 根节点:一块全屏 canvas + 一条音轨
lib/mv.js 工具库:缓动、确定的随机和噪声、拍点、歌词、逐字状态、舞台、运动模糊
scenes.js 场景和场景表
data/music.js 拍点网格(beatgrid.mjs 生成)
data/lyrics.js 逐字时间(tap.html 或强制对齐生成)
一个场景就是一个 draw(ctx, f):f.t 是歌曲时间,同一个 t 永远画出同一帧。HyperFrames 每跳到一个时间点发一次 hf-seek,MV.connect 在里面按那个时间画一帧,所以预览、草稿、4K 重渲完全一致。
几条最重要的手艺(详见 references/scene-craft.md):
- 猛—停—猛:一次变化 0.15–0.4 秒用强缓动做完,停住,等下一拍。匀速漂浮是屏保。
- 冲击是 0 毫秒的硬切:巨字砸下、切镜头在拍点那一帧直接变,缓动会把“砸”变成“滑”。要落在拍上的移动提前 40–190 毫秒开始。
- 时间按歌词查:
lyrics.get('那句歌词'),切点用小节线算,对齐数据改了画面自动跟上。 - 运动模糊要自己做:HyperFrames 的运动模糊只管 HTML 元素,canvas 里的东西靠
MV.Stage在快门时间里多画几遍取平均(正式片samples: 8–16)。 - 真 4K 要自己分配像素:
--resolution 4k不会让 canvas 变清楚,MV.Stage按devicePixelRatio分配 3840×2160 的像素,场景照样按 1920×1080 写。
第六部分:审片
先出整片联系表,再抽全分辨率的帧,最后用正常速度戴耳机完整看一遍。清单在 references/review.md,最常见的硬伤:安静段落的小字看不见、交接处位置跳、颜色跑出色板、某两三秒什么都没发生、快速运动一卡一卡。
第七部分:出片
| 档 | 命令 | 用途 |
|---|---|---|
| 草稿 | npx hyperframes render --fps 30 --quality draft | 看节奏和同步 |
| 1080p | npx hyperframes render --fps 60 | 发布 |
| 4K | npx hyperframes render --fps 60 --resolution 4k --video-bitrate 60M --max-bitrate 66M | YouTube 4K、存档 |
码率、体积、磁盘、长片分段渲染、交付前核对:references/render.md。
致谢
- mexicat/pdoom-video(作者 Giacomo Magnanini,MIT 许可):英文歌《I'm Upping My P(doom)》的代码生成 MV,是我做《越界》时借鉴的项目,《越界》的画面引擎就是在它的基础上改的。这套做法里最核心的几条思路也是从它学来的:每一帧只由歌曲时间决定,歌词逐字同步并做进画面,按歌词内容而不是秒数来定时间,在小节线上切镜头,用快门时间内多次采样做运动模糊。本仓库的代码是为 HyperFrames 重新写的,没有直接复制原项目的代码。
- HyperFrames(HeyGen):把网页逐帧渲染成视频的工具,本仓库的起步工程跑在它上面。
- Suno:写歌用的工具。
许可
- 本仓库的代码(
starter/、install.sh):MIT 许可,见LICENSE - 文档和技能(
README.md、skill/):CC BY 4.0,转载、改编、商用都可以,请署名“张狗剩”并附上本仓库链接,见LICENSE-docs.md - 示范音频由
starter/tools/demo-audio.sh用 ffmpeg 现场合成,示范歌词是随手写的,都不是真实作品 - 字体不随仓库分发,请自己下载开源字体(思源宋体等,SIL OFL)
- 你用 Suno 生成的歌,权利按 Suno 的条款和你的订阅来
出处
Suno 的功能和权利说明来自 Suno 帮助中心(2026 年 11 月查阅):
// faq
What is lyric-mv-kit?
代码 MV 创作包:用 Suno v6 写歌,用 HyperFrames 做逐字踩拍的歌词 MV(起步工程 + 工具 + Claude Code 导演技能 + 教程). It is open-source on GitHub.
Is lyric-mv-kit free to use?
lyric-mv-kit is open-source under the MIT license, so it is free to use.
What category does lyric-mv-kit belong to?
lyric-mv-kit is listed under devtools in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/lyric-mv-kit)
// retro hit counter
[](https://claudeers.com/lyric-mv-kit)
// reviews
// guestbook
// related in Developer Tools
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…
Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA