JohnsonZhangCN/music-mv-skill

Music MV

Orchestrates user assets into a 2D hand-painted music video with performance, lyrics sync, and transitions, delivering a playable MP4. Utilizes a built-in painted-animation engine (p5.js + p5.brush), examples, and Windows packaging; does not depend on another installed skill or require an external video generation API.

Current user parameters:

$ARGUMENTS

Parsing Requests

Accepts Chinese natural language or key=value format. Required: character image image, song audio, lyrics lyrics, start start, end end, style style. Supports quotes for paths containing spaces. Time accepts seconds, M:SS, or H:MM:SS. Lists all missing items at once when absent; does not ask again for already provided information.

Defaults: 1920×1080, 24fps, line-level lyrics, all clearly distinguishable characters in the image included, output to a new directory under the current project's outputs/music-mv. Follows user specification for single protagonist, no subtitles, or other frame rates. For complex character images, first define a model sheet and draw test frames; the image serves as identity and styling reference, not merely for image pasting, panning, or static slideshows.

When style=小镇姑娘, reads references/styles.md and checks assets/painted-animation/docs/xiaozhen-sheet.jpg. This name references the example's watercolor paper, ink lines, limited-frame performance, lyrics imagery, and coherent transitions, without copying the original song's plot exactly. Other styles map to achievable 2D painting languages; for realistic or 3D requests, first explain the boundaries of this engine.

Production

1. Check the three input files and examine the character image. First output a brief plan: characters, story outline, visual style, file locations; adhere to existing project approval requirements. When the user has authorized full generation, continue through to the final video; only stop after storyboarding if the user explicitly requests "storyboard first."
2. Read assets/painted-animation/template/ANIMATION_GUIDE.md and references/production.md. For music arrangement when needed, read references/music-video.md; its suggestions for expanding sections by measure cannot override the user's precise time interval. If mode=storyboard first, only read the image and lyrics, measure the beat, and write the storyboard; skip environment setup, scene creation, and rendering, and stop after delivering the storyboard.
3. Use file tools to write the normalized JSON to the current project's .cache/music-mv-request.json. Must provide an absolute path for output that does not yet exist in the current project. Prepare materials and project using the script:

   python "${CLAUDE_SKILL_DIR}/scripts/prepare_mv.py" --request "<absolute path to request JSON>" --install
   

   For Windows dependencies, caches, and browsers, see references/windows.md. The helper script only prepares the project; you still create the scenes.
4. Read the generated mv-task.json and analysis/lyrics.json; confirm BPM and beat_offset. On detection failure, fix dependencies and measure, or use user-provided BPM; do not pass off estimates as measurements. Preserve the specified audio range; do not add intros, tempo changes, or fades without authorization. Standard LRC provides only line-level timestamps; lyrics coloring is a best-effort estimate and cannot claim word-level precision.
5. Write a complete STORYBOARD.md: each shot's time range, lyrics, action, composition, and transition. Create scene files under src/scenes, register them in studio.html; remove demo scenes. Characters should have expressions, anticipation, weight shifts, follow-through, and readable performance. Each frame is a pure function of time t.
6. Use scripts/render_mv.mjs to render representative frames, action bars, and seams for each shot; open images for review and correction. For silent videos (no subtitles), remove the karaoke.js load in studio.html.
7. Render the full video; the packaging verifies duration, dimensions, frame rate, and audio track. Check the beginning, end, and all transitions, then deliver the absolute paths for the MP4, storyboard, and preview image. After modifying scenes, re-render only affected frames; avoid reusing outdated frames. Do not claim quality confirmation without opening previews or playing/verifying the video.

Default order: asset check -> storyboard -> scene creation -> preview correction -> MP4. Do not request approval repeatedly between normal steps. Use sub-agents only when explicitly requested by the user.

Example Invocation

/music-mv character="D:/mv/character.png" song="D:/mv/song.mp3" lyrics="D:/mv/song.lrc" trim="00:39-01:07" style="小镇姑娘"

Optional additions: character-mode=only orange protagonist, subtitle=none, mode=storyboard first. When multiple clearly distinguishable characters appear in the image, all are included by default, and the process continues through to the final video.

Source and credits in references/credits.md.