background-music — Claude Code skill: video music and setup
background-music is a Claude Code skill that selects a soundtrack and configures automatic ducking under speech in Remotion videos. It runs when a brief requests background music or an edit asks to add or adjust it.
MIT ★ 147 updated 2026-11-13
npx skills add notivn/AIEVv2 --skill background-music -a claude-codeWhat background-music does
The skill picks one track from assets/music/, derives speech intervals from transcript timestamps, and writes the settings to meta.json. Remotion loops the track, fades it in and out, and lowers its volume during speech.
The music file is copied into the project instead of being linked from the shared library. The setup needs the assets/music/ library and speech timestamps; if the library is empty, the skill skips the soundtrack. Before final delivery, the instructions call for listening to the draft at the beginning, middle, and end. ffmpeg is only needed for optional volume measurements.
What it helps with
- choose a soundtrack that matches the video mood
- mark speech intervals for automatic music ducking
- set the music file and levels in
meta.json - check music volume in a draft render
Example prompts for the agent
- Add background music to this video and set it to duck under speech.
- Choose a track from
assets/music/and fill inaudio.musicinmeta.json. - Check the draft render so the soundtrack stays below the voice.
How to install background-music
1Skills CLI (Vercel)
npx skills add notivn/AIEVv2 --skill background-music -a claude-code2Manually: put the files in place
~/.claude/skills/background-music/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/background-music/
1Skills CLI (Vercel)
npx skills add notivn/AIEVv2 --skill background-music -a codex2Manually: put the files in place
.agents/skills/background-music/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add notivn/AIEVv2 --skill background-music -a cursor2Manually: put the files in place
.cursor/skills/background-music/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install notivn/AIEVv2 .claude/skills/background-music2Manually: put the files in place
.github/skills/background-music/SKILL.md1Skills CLI (Vercel)
npx skills add notivn/AIEVv2 --skill background-music -a gemini-cli2Platform CLI
gemini skills install https://github.com/notivn/AIEVv2 --path .claude/skills/background-musicManually: put the files in place
.devin/skills/background-music/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about background-music
How do I install background-music in Claude Code?
Run npx skills add notivn/AIEVv2 --skill background-music -a claude-code. The skill file is at ~/.claude/skills/background-music/SKILL.md.
What does background-music do?
It selects a track from assets/music/, marks speech intervals for automatic ducking, and adds the audio settings to meta.json.
What does background-music need to work?
It needs the assets/music/ library, transcript speech timestamps, and a Remotion project. ffmpeg is only needed for optional volume measurement.
Source text
SKILL.md · MIT
---
name: background-music
description: Pick background music from the assets/music/ library and configure auto-ducking (music dips automatically under speech) via meta.json audio.music for the Remotion assembly layer. Read when the brief/edit prompt has a "Nhạc nền" (background music) section set to auto, or when the user asks to add/adjust background music on a video.
---
# Background Music - music bed + auto-ducking
Background music is played by Remotion in the assembly layer (the `MusicTrack` component): the track loops, fades in over 0.5s at the start of the video, fades out over 1s at the end, and **auto-ducks** (smooth 0.4s volume dip) around every speech segment. Claude's job is to pick the track + generate the speech ranges + declare `audio.music` correctly in `meta.json` - everything else is deterministic inside Remotion.
## 1. Pick a track by mood
- Read `assets/music/library.json` - each entry has `file`, `tags` (mood: nang-luong, chill, cam-hung, cang-thang, vui-ve...), `durationMs`, `description`.
- Pick **ONE** track whose mood matches the video content (motivational video -> nang-luong/cam-hung; slow explainer -> chill...).
- A track shorter than the video is fine - `MusicTrack` loops it automatically, no need to concatenate files with ffmpeg.
## 2. Generate speech ranges from the transcript
Speech ranges = the segments that DO contain speech (in seconds, on the already-cut composition timeline) - these are the moments the music gets ducked.
1. Take the word timestamps from the transcript (already remapped if autoCut ran).
2. Merge adjacent words into one continuous range.
3. **Merge two ranges if the gap between them is < 0.6s** - a short breath between two sentences is not worth having the music swell back up and drop again.
4. Result: `[[startSec, endSec], ...]` - usually just a few ranges for a talking-head video (silent intro, body, outro).
## 3. Volume levels
| Context | volume | Notes |
|---|---|---|
| Speech present (`duckVolume`) | **0.10-0.15** | Music sits ~18-20dB below the voice - the voice is ALWAYS clearer than the music |
| No speech (`volume`): intro/outro/pauses | **0.30-0.40** | Music carries the emotion but does not bury the sfx |
Loud / bass-heavy tracks -> take the **lower bound** of both ranges (0.10 / 0.30).
## 4. Declare it in meta.json
**Copy the music file into the project's `assets/`** (same as sfx) so the project stays portable - NEVER point directly at the shared library:
```powershell
Copy-Item "assets/music/<file>" "video-projects/<id>/assets/music/<file>"
```
Then declare it (path relative to the project root):
```json
"audio": {
"voice": "...",
"sfx": [...],
"music": {
"file": "assets/music/<file>",
"volume": 0.35,
"duckVolume": 0.12,
"speech": [[1.2, 14.8], [16.1, 42.5]]
}
}
```
The server stages the file into the Remotion staging directory during assembly - nothing else to do.
## 5. Verify (mandatory before final)
1. Render a draft (assemble-draft) then **listen at 3 points**: start of the video (fade-in + intro level), middle of the video during speech (music must sit clearly under the voice), end of the video (clean fade-out).
2. The only standard: **the voice MUST be clearer than the music at every moment**. If you have to strain to make out the words -> lower `duckVolume`.
3. If in doubt about the levels, measure with `ffmpeg -i <draft.mp4> -af volumedetect -f null NUL` over a speech segment and a non-speech segment, and compare the two mean_volume values.
## Mistakes to avoid
- **Music louder than speech** - `duckVolume` is too high, or the speech ranges are missing a segment. Re-check transcript coverage: every spoken segment must fall inside a range.
- **Forgetting the final fade-out** - `MusicTrack` fades out over 1s based on `durationInFrames`; but if the composition's total duration is computed wrong, the music gets cut off abruptly. Verify the end point when listening to the draft.
- **Music with Vietnamese lyrics** - it fights the speech, the listener's brain cannot separate two layers of words. ONLY use instrumental music.
- **Downloading music from the internet** - FORBIDDEN (copyright). Only use the `assets/music/` library. If the library is empty -> skip background music and state that clearly in the report.
© notivn · MIT · notivn/AIEVv2