# lintsinghua/paint-mv-skills architecture

> Architecture diagram of the GitHub repository lintsinghua/paint-mv-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lintsinghua/paint-mv-skills
- Repository: https://github.com/lintsinghua/paint-mv-skills

## Overview

paint-mv-skills is an AI-agent workflow for turning a song and lyrics into a hand-painted animated music video. The main path runs from project setup and audio/lyric timing through storyboard, shared art direction, chapter animation, review, and MP4 rendering. The graph also captures the separately documented skill guidance and generated-project inputs. Engine, storyboard, and render internals are not present in the tree, so those nodes use existing enclosing directories; their links rely on README statements.

Main entry points: [`skills/paint-mv/scripts/new_project.mjs`](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/new_project.mjs) (Project setup), [`skills/paint-mv/SKILL.md`](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/SKILL.md) (Director skill), [`skills/paint-mv/scripts/lyrics_to_ly.mjs`](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/lyrics_to_ly.mjs) (Lyric conversion), [`skills/paint-mv/template/src/ch`](https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template/src/ch) (Chapter animation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow guidance"]
  node_director["Director skill<br/>[SKILL.md]"]
  node_storyboard["Storyboard skill<br/>[SKILL.md]"]
  node_animation_guide["Animation guide<br/>[SKILL.md]"]
  node_render_guide["Render guide<br/>[SKILL.md]"]
end

subgraph group_preparation["Project preparation"]
  node_setup["Project setup<br/>[new_project.mjs]"]
  node_audio_analysis["Beat analysis<br/>[analyze_audio.mjs]"]
  node_lyric_alignment["Lyric alignment<br/>[align_lyrics.py]"]
  node_lyric_conversion["Lyric conversion<br/>[lyrics_to_ly.mjs]"]
  node_upstream["Engine retrieval<br/>[fetch_upstream.mjs]"]
  node_song_config["Song configuration<br/>[song.js]"]
  node_lyric_data["Timed lyrics<br/>[lyrics.js]"]
end

subgraph group_creative["Creative production"]
  node_cast["Shared cast<br/>[characters.js]"]
  node_sets["Shared sets<br/>[sets.js]"]
  node_chapters["Chapter animation"]
end

subgraph group_rendering["Review and output"]
  node_engine["Animation engine"]
  node_review["Contact-sheet review<br/>[SKILL.md]"]
  node_renderer["Frame rendering"]
  node_video["MP4 video"]
end

node_creator(("MV creator"))
node_audio["Song audio"]
node_lyrics["Lyrics"]

node_creator -->|"starts workflow"| node_director
node_director -->|"scaffolds project"| node_setup
node_setup -->|"analyzes audio"| node_audio_analysis
node_audio -->|"provides audio"| node_audio_analysis
node_setup -->|"converts timed lyrics"| node_lyric_conversion
node_lyrics -->|"aligns plain text"| node_lyric_alignment
node_lyric_alignment -->|"writes SRT"| node_lyric_conversion
node_lyrics -->|"provides timed lyrics"| node_lyric_conversion
node_setup -->|"fetches engine"| node_upstream
node_audio_analysis -->|"returns beat data"| node_setup
node_lyric_conversion -->|"returns lyric data"| node_setup
node_setup -->|"writes song settings"| node_song_config
node_setup -->|"writes lyric data"| node_lyric_data
node_director -->|"directs story design"| node_storyboard
node_storyboard -->|"specifies characters"| node_cast
node_storyboard -->|"specifies settings"| node_sets
node_director -->|"assigns chapters"| node_animation_guide
node_animation_guide -->|"guides drawing"| node_chapters
node_chapters -->|"uses animation engine"| node_engine
node_cast -->|"shares characters"| node_chapters
node_sets -->|"shares settings"| node_chapters
node_lyric_data -->|"drives karaoke timing"| node_engine
node_song_config -->|"provides render settings"| node_renderer
node_director -->|"coordinates review"| node_review
node_render_guide -->|"guides inspection"| node_review
node_review -->|"checks rendered sheets"| node_renderer
node_renderer -->|"encodes MP4"| node_video
node_audio -->|"mixes into video"| node_video

click node_director "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/SKILL.md"
click node_storyboard "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-storyboard/SKILL.md"
click node_animation_guide "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-animate/SKILL.md"
click node_render_guide "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-render/SKILL.md"
click node_setup "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/new_project.mjs"
click node_audio_analysis "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/analyze_audio.mjs"
click node_lyric_alignment "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/align_lyrics.py"
click node_lyric_conversion "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/lyrics_to_ly.mjs"
click node_upstream "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/fetch_upstream.mjs"
click node_song_config "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/song.js"
click node_lyric_data "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/lyrics.js"
click node_cast "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/characters.js"
click node_sets "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/sets.js"
click node_chapters "https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template/src/ch"
click node_engine "https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template"
click node_review "https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-render/SKILL.md"
click node_renderer "https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_director,node_storyboard,node_animation_guide,node_render_guide toneBlue
class node_setup,node_audio_analysis,node_lyric_alignment,node_lyric_conversion,node_upstream,node_song_config,node_lyric_data toneAmber
class node_cast,node_sets,node_chapters toneMint
class node_engine,node_review,node_renderer,node_video toneRose
class node_creator,node_audio,node_lyrics toneIndigo
```

## Components

### Workflow guidance

- [Director skill](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/SKILL.md): `skills/paint-mv/SKILL.md`
- [Storyboard skill](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-storyboard/SKILL.md): `skills/paint-mv-storyboard/SKILL.md`
- [Animation guide](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-animate/SKILL.md): `skills/paint-mv-animate/SKILL.md`
- [Render guide](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-render/SKILL.md): `skills/paint-mv-render/SKILL.md`

### Project preparation

- [Project setup](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/new_project.mjs): `skills/paint-mv/scripts/new_project.mjs`
- [Beat analysis](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/analyze_audio.mjs): `skills/paint-mv/scripts/analyze_audio.mjs`
- [Lyric alignment](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/align_lyrics.py): `skills/paint-mv/scripts/align_lyrics.py`
- [Lyric conversion](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/lyrics_to_ly.mjs): `skills/paint-mv/scripts/lyrics_to_ly.mjs`
- [Engine retrieval](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/scripts/fetch_upstream.mjs): `skills/paint-mv/scripts/fetch_upstream.mjs`
- [Song configuration](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/song.js): `skills/paint-mv/template/src/song.js`
- [Timed lyrics](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/lyrics.js): `skills/paint-mv/template/src/lyrics.js`

### Creative production

- [Shared cast](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/characters.js): `skills/paint-mv/template/src/characters.js`
- [Shared sets](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv/template/src/sets.js): `skills/paint-mv/template/src/sets.js`
- [Chapter animation](https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template/src/ch): `skills/paint-mv/template/src/ch`

### Review and output

- [Animation engine](https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template): `skills/paint-mv/template`
- [Contact-sheet review](https://github.com/lintsinghua/paint-mv-skills/blob/main/skills/paint-mv-render/SKILL.md): `skills/paint-mv-render/SKILL.md`
- [Frame rendering](https://github.com/lintsinghua/paint-mv-skills/tree/main/skills/paint-mv/template): `skills/paint-mv/template`
- **MP4 video**

### Other components

- **MV creator**
- **Song audio**
- **Lyrics**

## Connections

- MV creator → Director skill: starts workflow (evidence: `README.md`)
- Director skill → Project setup: scaffolds project (evidence: `README.md`)
- Project setup → Beat analysis: analyzes audio (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Song audio → Beat analysis: provides audio (evidence: `README.md`)
- Project setup → Lyric conversion: converts timed lyrics (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Lyrics → Lyric alignment: aligns plain text (evidence: `README.md`)
- Lyric alignment → Lyric conversion: writes SRT (evidence: `skills/paint-mv/scripts/align_lyrics.py`)
- Lyrics → Lyric conversion: provides timed lyrics (evidence: `README.md`)
- Project setup → Engine retrieval: fetches engine (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Beat analysis → Project setup: returns beat data (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Lyric conversion → Project setup: returns lyric data (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Project setup → Song configuration: writes song settings (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Project setup → Timed lyrics: writes lyric data (evidence: `skills/paint-mv/scripts/new_project.mjs`)
- Director skill → Storyboard skill: directs story design (evidence: `README.md`)
- Storyboard skill → Shared cast: specifies characters (evidence: `README.md`)
- Storyboard skill → Shared sets: specifies settings (evidence: `README.md`)
- Director skill → Animation guide: assigns chapters (evidence: `README.md`)
- Animation guide → Chapter animation: guides drawing (evidence: `README.md`)
- Chapter animation → Animation engine: uses animation engine (evidence: `README.md`)
- Shared cast → Chapter animation: shares characters (evidence: `README.md`)
- Shared sets → Chapter animation: shares settings (evidence: `README.md`)
- Timed lyrics → Animation engine: drives karaoke timing (evidence: `README.md`)
- Song configuration → Frame rendering: provides render settings (evidence: `skills/paint-mv/template/src/song.js`)
- Director skill → Contact-sheet review: coordinates review (evidence: `README.md`)
- Render guide → Contact-sheet review: guides inspection (evidence: `README.md`)
- Contact-sheet review → Frame rendering: checks rendered sheets (evidence: `README.md`)
- Frame rendering → MP4 video: encodes MP4 (evidence: `README.md`)
- Song audio → MP4 video: mixes into video
