mcpField
M
music-mv

music-mv

github.com/win-haoCreative & media4515 installsUpdated 1w ago
Repository

About music-mv

music-mv is a skill that guides a staged, code-based workflow for making a music video from a song. It is for creators who want frames drawn by code and synchronized to the music, with user approval at key stages.

Key features

  1. 01Analyze BPM, beats, and song sections
  2. 02Plan scenes around timed lyrics
  3. 03Compare code-drawn visual styles
  4. 04Create character sheets and storyboards
  5. 05Render frames and combine the original song
  6. 06Measure rhythm and review each version

Use cases

  1. 01Develop a music video from an audio file
  2. 02Turn timed lyrics into scene-by-scene visuals
  3. 03Adapt transferable traits from a reference video
  4. 04Revise a rendered cut using measured checks

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/win-hao/music-mv --skill music-mv

After installing, type/music-mvin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

LICENSE
README.md
.gitignore
NOTICE.md
requirements.txt
教程.md
examples/collage/
scene.html
examples/crayon/
scene.html
examples/diorama/
scene.html
examples/pixel/
scene.html
references/
character.md
learn-style.md
review.md
render.md
storyboard.md
transitions.md
styles.md
scripts/
check_env.py
_common.py
contact_sheet.py
analyze_song.py
srt2js.py
render_frames.mjs
finalize_audio.py
video_rhythm.py
templates/
lyrics-layer.js
templates/frames/
scene.html
templates/hf-canvas/
index.html
templates/hf-overlay/
index.html

Details

From the project README

用代码做一支音乐 MV

原理：不生成视频。代码把每一帧画出来（画面是时间 t 的函数），踩着歌的节拍和歌词编排，最后和原曲合成一条视频。下文 <skill> 指本文件所在的文件夹。

底线（每一步都守）

  1. 一切跟着音乐走：镜头在哪变、哪个画面最安静、最重要的画面放哪，都从歌里来（song.md、song-analysis.json）
  2. 一句歌词，一个画面：这句唱什么，画面就演什么。没听过这首歌的人只看画面，也能说出发生了什么
  3. 关键处停下来等用户点头：歌词、画风、角色设定图、分镜、草图。用户没确认，不往下做
  4. 画面只由 t 决定：同一个 t 永远画出同一帧，随机数用固定种子
  5. 一个镜头一个画布：背景、角色、道具画在同一个画布上、跟同一个镜头动，不把单独渲的角色视频叠在背景上
  6. 你看不了视频：节奏和动静靠脚本量（video_rhythm.py），画面靠接触表看（contact_sheet.py）。每版都跑，不凭感觉说「很流畅」
  7. 歌词有版权：不在对话、命令里整段打出歌词（会被内容过滤拦），脚本读文件，回复里只说第几句
  8. 歌词以外的字不自己加：片名、章节角标、印章徽章，用户要了再加

开始之前

  1. 文件夹里要有歌（song.mp3，wav、m4a 也行）；可选 lyrics.srt、reference.mp4（想学风格的那支视频）
  2. 跑 python3 <skill>/scripts/check_env.py。缺的东西把它打印的安装命令给用户，问过再装。出图要 puppeteer：在这个文件夹里 npm i puppeteer-core（用本机 Chrome）
  3. 一轮问完：画幅（横屏 1920×1080 / 竖屏 1080×1920 / 4:3 1920×1440）；整首还是一段；有没有想要的画风或参考视频；主角是谁（没想好就按歌来定）；歌词要不要上屏
  4. 给了参考视频：先做「学一支视频的风格」（最后一节），第 2 步按 style.md 来

文件这样放：

<歌的文件夹>/
  song.mp3  lyrics.srt  song.md  song-analysis.json
  styles/             第 2 步的样图
  character.js        character-sheet.png
  storyboard.md       sketches/  storyboard.png
  mv/                 HyperFrames 工程
  review/             每版的接触表、量出来的数
  mv-r1.mp4  mv-r2.mp4 …    每改一版存一个，不覆盖

第 1 步　听懂这首歌

  1. 歌词：有 lyrics.srt 就直接用。没有就用 Whisper 转成带时间轴的 lyrics.srt（whisper song.mp3 --model medium --output_format srt；Apple 芯片用 mlx-whisper 快得多）
    • 识别没把握的几句（第几句、几秒）列给用户，让他对着听改，不要自己猜着改。背景音重的歌常有错字
    • 模型说歌词有版权、不肯转，别硬来：请用户用剪辑软件的「识别歌词」导出 srt，或者从音乐软件复制歌词对好时间，命名 lyrics.srt 放进文件夹
  2. 骨架：python3 <skill>/scripts/analyze_song.py song.mp3 -o song-analysis.json，得到 BPM、每一拍、每小节第一拍、分段和每段多响、突然安静 / 低音撤掉 / 重新进来的点、最重的几下、最后一下重音。BPM 可能差一倍，请用户跟着拍手对一下
  3. 理解：上网搜这首歌的歌词解读、乐评、听众评论，归纳 3–5 种主流理解，每条附来源链接
  4. 写 song.md：主题和情绪走向（哪里起、哪里落）；分段表（时间、段名、情绪）；镜头该变的点；几种理解和链接；没把握的歌词

完成：用户确认了歌词；song.md、song-analysis.json 都在

第 2 步　定画风

照 references/styles.md：按情绪挑 3 种（拿不准就用像素游戏风、纸艺拼贴绘本、蜡笔手绘绘本），用代码把同一个开场画面按每种风格自己的画法从头各画一张 1920×1080 样图放 styles/（不是画好一张再套滤镜，四种的原生示范在 examples/；出图用 render_frames.mjs --times，见 references/render.md「出静态图」），每张一句适配理由。不用图像生成模型。停，等用户选。用户已经说了画风，就只画那一种确认。

选定后把画法（颜色 HEX、线条、纹理、动起来的手感、歌词放哪）写进 song.md 的「画风」一节。

完成：用户选定了

第 3 步　画角色

照 references/character.md 写 character.js：统一的绘制接口（朝向、表情、动作、拿着的道具），表情至少开心、害羞、难过，动作至少走、跳、拥抱、拿东西（按故事要的加）。画一张 character-sheet.png：三视图 + 表情表 + 动作定格。停，等用户确认。

之后所有镜头都通过 character.js 画角色。

完成：用户确认了设定图

第 4 步　剧本和分镜

照 references/storyboard.md 写 storyboard.md：每句歌词一个镜头，起止以 lyrics.srt 为准、切换对齐拍点；抽象的歌词拆成看得懂的连续动作（用户说了自己的理解就照用户的）；每个镜头写场景、角色动作、景别运镜、情绪色调、卡在哪一拍。

转场照 references/transitions.md：从一镜到底、卡点切换、拼贴快切里推荐一种并说明理由，再给每两个相邻镜头写明怎么接。

整体要有情感起伏，结尾留余味（用户要欢快的就写欢快的）。停，等用户确认。故事被否就整个重写，不在旧的上面修。

完成：用户确认了分镜

第 5 步　先出草图，再做整片

  1. 草图：每个镜头用选定的画风画一张关键帧（render_frames.mjs --times 出 sketches/01.png…），拼成 storyboard.png（contact_sheet.py --images sketches -o storyboard.png）。停，等用户确认。在这时候改最省事
  2. 整片：照 references/render.md 选路线。同步画得完的（Canvas 2D、SVG）用路线 A，直接写在 HyperFrames 里；p5.brush 这类一帧要等的用路线 B，先逐帧渲再叠歌词。歌词 srt2js.py 转成 lyrics.js，在最上层、不跟镜头动。先渲最难的 10–20 秒给用户看手感，再渲整片
  3. 声音：python3 <skill>/scripts/finalize_audio.py render.mp4 song.mp3 -o mv-r1.mp4，把原曲按原音量封回去（渲染器常把歌压小 2 dB 以上）
  4. 自检：照 references/review.md「每一版交给用户之前」，接触表、歌词对照、节奏量一遍，过线了再交

完成：mv-r1.mp4 自检通过；告诉用户文件在哪、多长、量出来的结果、哪些地方拿不准

第 6 步　看片、修改

用户看完提意见，照 references/review.md 的毛病清单改（像幻灯片、运镜晃、表现力不够、道具不对、歌词没演出来，还有别的）。每改一版存新文件、说清改了什么在哪几秒、只重渲改过的段、重跑自检。剧情被否回第 4 步。

完成：用户说可以了

发布前（提醒用户）

  • 平台有「内容由 AI 生成」声明的，选上
  • 封面用片子里最好看的一帧，别另外套模板
  • 标题写上歌名和画风（「像素风」「绘本」）
  • 歌的版权归原作者，发布前确认平台允许用这首歌

学一支视频的风格（可选）

用户给了 reference.mp4：照 references/learn-style.md，裁掉录屏的边，测音乐、量每个镜头停多久和切点卡不卡拍，抽帧看画面，写成 style.md（一句话风格、配色 HEX、画法、节奏和运镜、转场、画面里的字、量出来的规律）。只记能迁移的规律，不搬它的画面和角色。新片做完，同一段落两边抽帧对照，列差距逐条改。

脚本和模板

文件干什么
scripts/check_env.py查 ffmpeg、Node、Python 库、Whisper 在不在，只查不装
scripts/analyze_song.py歌的骨架：BPM、拍点、分段、突变点、重音
scripts/srt2js.pylyrics.srt → lyrics.js（合成页面用）
scripts/contact_sheet.py视频抽成带时间的接触表；--srt 按歌词抽；--images 拼草图
scripts/video_rhythm.py切点、每个镜头停多久、几乎不动的段、黑帧、卡不卡拍
scripts/render_frames.mjs调网页的 renderAt(t) 出图：--times 出样图、设定图、草图；路线 B 逐帧渲整片、接成视频
scripts/finalize_audio.py原曲按原音量封回成片，量三个响度
templates/hf-canvas/路线 A 的 HyperFrames 合成
templates/frames/scene.html路线 B 的逐帧页面（p5.js + p5.brush）
templates/hf-overlay/路线 B 叠歌词、配歌的合成
templates/lyrics-layer.js歌词层（逐字弹出，不跟镜头动）
examples/<风格>/scene.html四种画风的原生示范（同一段 5 秒，renderAt(t) 接口），读代码学画法

Comments

Markdown supported