Music Video Skill — PRISM Studios

PRISM STUDIOS · REUSABLE CLAUDE SKILL

Loading…

# Music Video Builder — PRISM Studios / VersAssist

Turn a set of video clips (and/or photos) + a song into a finished **~60-second music video**, edited and quality-checked, ready for review. Any team member can run this — you do **not** need to be technical.

## Our two apps (this is the whole toolkit)

| App | What it's for | URL |
|---|---|---|
| **Story Engine** | The *narrative* — turns the song's lyrics into a shot-by-shot plan + AI clip prompts | https://prism-story.srv1030637.hstgr.cloud |
| **Video Studio** | The *edit* — FFmpeg combines your clips into one polished video (title cards, transitions, color, beat-sync, captions, music) | https://video-studio.srv1030637.hstgr.cloud |

Both are already live. No install, no login. **Use Chrome or Edge.**

## House video specs (what "good" means here)
- **Length:** ~**60 seconds** (acceptable range **55–65s**).
- **Resolution / aspect:** **1920×1080 (16:9)** by default; **1080×1920 (9:16)** for reels/shorts.
- **Frame rate / codecs:** 30 fps, H.264 video, AAC audio.
- **Audio:** the song plays over the whole video and **fades out** at the end.
- **Captions (optional):** lyrics, only if requested — must match the song.
- **Look:** clean cuts or smooth transitions, a color preset, no black frames at the start/end, a title card at the front.

---

# HOW TO RUN IT

## Path A — The simple way (web apps, no Claude needed)

**Step 1 — Plan the story (Story Engine).** *Skip if you already have your clips planned.*
1. Open **Story Engine** → **New Project** → choose **🎵 Music Video**.
2. Paste the **song title, theme, lyrics**, and attach the **MP3**. Click **Create**.
3. Click **🎧 Analyze song** (Gemini listens + splits the lyrics into sections).
4. For each section click **Generate** to get **cinematic clip prompts** (one per lyric line). Use the **📋 Copy** button to take prompts into your AI video tool (Higgsfield / Runway / Veo / Seedance, etc.) and make the clips.
   → *Output of this step: your generated video clips, saved to a folder.*

**Step 2 — Compile the video (Video Studio).**
1. Open **Video Studio** → sidebar **✛ New project** → name it (e.g. "Kai — Cyberpunk"). Use **✎ Rename / project details** anytime.
2. **Drag ALL your clips (and any photos) in at once.** They auto-save (survive refresh). Use the **▲▼** buttons to set the order; **🗑** to remove a clip; thumbnails help you tell them apart.
3. **Music:** upload the song under **Music (optional)**.
4. **Title card:** set the title text + seconds (e.g. 3). Add an **End card** if you want.
5. **Aspect ratio:** 16:9 (standard) or 9:16 (reels).
6. **Look & effects:** pick a **Color preset** (Cinematic is a safe default), a **Transition style** (Crossfade), optionally **Vignette**/**Grain**, and a **Fade in/out** of ~1s. For a punchy edit, turn on **🥁 Beat-synced cuts** (cut every 4 beats).
7. **Captions (optional):** paste the lyrics in **Subtitles**, toggle **Burn subtitles** on.
8. Click **🎬 Combine into one video** → preview it → **⬇ Download MP4**.

**Step 3 — QA it** (see the rubric below) and deliver.

> **Hitting ~1 minute:** the video length ≈ total of your clip durations + cards. To land near 60s, include roughly **8–10 clips of ~6–8 seconds** (or fewer clips + Ken Burns stills). If it's too long, remove clips; too short, add more. Beat-sync mode auto-fills the song length.

## Path B — The automated way (inside Claude Code)

If you're running this in Claude Code with a folder of clips + a song, Claude can do the compile and QA directly. Tell Claude the **clips folder**, the **song file**, the **title**, and **aspect ratio**, then:

1. **Order the clips** (by filename, or as the user specifies).
2. **Normalize + concat + add the song** with FFmpeg (see commands below), targeting ~60s.
3. **Run the QA rubric** automatically (ffprobe checks) and report PASS/FAIL.
4. Only deliver if QA passes; otherwise fix and re-run.

### FFmpeg reference commands (Path B)
Normalize each clip to the canvas (16:9 example) so mismatched clips splice cleanly:
```bash
ffmpeg -y -i CLIP.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black,fps=30,format=yuv420p,setsar=1" -an -c:v libx264 -preset veryfast -crf 20 normN.mp4
```
Concatenate (after normalizing all clips):
```bash
printf "file 'norm0.mp4'\nfile 'norm1.mp4'\n..." > list.txt
ffmpeg -y -f concat -safe 0 -i list.txt -c copy silent.mp4
```
Lay the song over it with a fade out, and finish:
```bash
DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 silent.mp4)
ffmpeg -y -i silent.mp4 -i SONG.mp3 -map 0:v -map 1:a -c:v libx264 -crf 20 -preset veryfast \
  -af "afade=t=out:st=$(echo "$DUR-2" | bc):d=2" -c:a aac -b:a 192k -shortest final.mp4
```
*(The Video Studio engine at `prism-video-studio/tools/assemble/assemble.py` does all of this — plus transitions, color, beat-sync, captions — if the repo is available; prefer driving that engine when present.)*

---

# ✅ QA RUBRIC — run this on the FINAL file before delivering

Do **not** deliver until every check passes. In Claude Code these run automatically; for a human, it's a 60-second checklist.

Let `FINAL` = the exported MP4.

### 1. Video length (~1 minute)
```bash
ffprobe -v error -show_entries format=duration -of csv=p=0 FINAL.mp4
```
- ✅ **PASS** if duration is **55–65 seconds**.
- ❌ FAIL → add/remove clips (or adjust clip durations) and re-export.

### 2. Audio sync & presence
```bash
ffprobe -v error -show_entries stream=codec_type -of csv=p=0 FINAL.mp4
ffprobe -v error -select_streams a:0 -show_entries stream=duration -of csv=p=0 FINAL.mp4
```
- ✅ **PASS** if there **is an audio stream** AND audio duration is within ~1s of the video duration (the song isn't cut off early or running long over black).
- Also watch the first 5s of playback: the song should start with the video, not after a silent gap.
- ❌ FAIL → re-mux the song (use `-shortest`) and re-check.

### 3. Caption accuracy (only if captions were requested)
- ✅ **PASS** if burned captions **match the song's lyrics** (correct words, correct order) and are **readable** (not cut off, good contrast).
- Spot-check 3 caption moments against the lyric sheet. Timing is *approximate by design* (it's auto-synced) — flag only if a caption is clearly on the wrong line or unreadable.
- ❌ FAIL → fix the lyric text / turn captions off, re-export. *(If precise karaoke timing is required, that needs a timed `.lrc` file — note it, don't block on it.)*

### 4. Overall quality
```bash
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,avg_frame_rate -of csv=p=0 FINAL.mp4
```
- ✅ **PASS** if: resolution is **≥1280×720** (target 1920×1080 / 1080×1920); **no black/frozen frames** at the start or end (a **title card** should open it); transitions look smooth (no jarring jumps); colors look intentional (a preset applied); and the ending **fades out** rather than cutting abruptly.
- ❌ FAIL → fix the offending item in Video Studio and re-export.

### QA report format (what to hand back)
```
QA REPORT — <project name>
1. Length .......... <duration>s  → PASS/FAIL
2. Audio sync ...... <audio present? aligned?> → PASS/FAIL
3. Captions ........ <match lyrics? or N/A> → PASS/FAIL
4. Quality ......... <res / no black frames / transitions / fade> → PASS/FAIL
VERDICT: READY FOR REVIEW  /  NEEDS FIXES (list them)
```

---

# Delivery
- When all four checks PASS, the file is **READY FOR REVIEW**.
- Hand off the **downloaded MP4** + the **QA report** to the reviewer (Dr. Jeff / the client lead).
- Keep the Video Studio project (it's saved) so revisions are one click away.

# If something breaks
- **Uploads fail / files show red:** hard-refresh (Ctrl+Shift+R) and re-drop them.
- **Video too long/short:** add or remove clips; each ~6–8s clip ≈ that many seconds of runtime.
- **Black bars on a vertical clip:** turn on **🌫 Blur background**.
- **Looks like a slideshow:** add a **Crossfade** (~0.5s) or turn on **Beat-synced cuts**.
- **Stuck:** ask James, or run this skill in Claude Code and let it compile + QA automatically.