Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add notivn/AIEVv2 --skill background-music -a claude-code
Open on GitHub

What 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 in audio.music in meta.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-code

2Manually: put the files in place

~/.claude/skills/background-music/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/background-music/

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

Similar skills

All skills for Marketing and content →

From the same set15

The whole set →
skill-authoring skill-authoring is a Claude Code skill that sets the rules for creating and revising skills for AI Edit Video. It activates on requests to write a skill or capture a lesson after a video is finished. CX Codex +1 ★ 147repo stars color-grading color-grading is a Claude Code skill that handles video color grading in the AI Edit Video pipeline. Runs when processing HDR or log clips, or upon a Chỉnh màu request. CX Codex +1 ★ 147repo stars key-layout key-layout is a Claude Code skill that places a video's main topic at the top and related points above the captions. It activates when keyLayoutEnabled is on in the brief or the edit prompt includes “Bố cục Key: BẬT”. CX Codex +1 ★ 147repo stars offline-voice offline-voice is a Claude Code skill that guides the setup of VieNeu-TTS narration and voice cloning. Activates when working on /api/tts, /api/voices, or narration debugging. CX Codex +1 ★ 147repo stars make-a-video make-a-video is a Claude Code skill that turns a concept into a finished MP4 with HyperFrames. It gathers requirements, builds a storyboard, and checks the preview before the final render. CX Codex +1 ★ 147repo stars auto-cut auto-cut is a Claude Code skill that cuts silences, stutters, and repeated takes from talking-head footage before editing. It activates when the autoCut brief setting is enabled. CX Codex +1 ★ 147repo stars ai-illustrations ai-illustrations is a Claude Code skill that adds generated images to a video edit. It activates when the brief enables AI illustrations or requests them for a video. CX Codex +1 ★ 147repo stars remotion-assemble remotion-assemble is a Claude Code skill that stitches HyperFrames scenes, footage, voiceovers, and SFX into a video via meta.json. It activates when editing files inside engines/remotion. CX Codex +1 ★ 147repo stars

Project sponsors

Companies that keep this analytics open