git:20261027.947a93e to git:20261027.0e914e4

26 added, 16 removed. Audit A to A.

---

name: add-music

- description: Generate background music and add it to your Remotion project. Describe the mood/genre you want, and this will generate a track via Suno and wire it into your composition with proper fade in/out.

+ description: Generate background music and add it to your Remotion project. Describe the mood/genre you want, and this will generate a commercially licensed track with Eleven Music (official ElevenLabs music skill) and wire it into your composition with proper fade in/out.

---

# Add Music — Generate & Integrate Background Music

You are helping the user add background music to their Remotion project.

- **Load the `remotion-production` skill** for the `music-scoring` and `audio-integration` rules.

+ **Load the `remotion-production` skill** for the `music-scoring` and `audio-integration` rules, and the official ElevenLabs **`music`** skill (`npx skills add elevenlabs/skills`) for the API details.

## Workflow

### 1. Understand the Mood

If not already described, ask the user:

- **Genre** — Electronic, jazz, classical, lo-fi, ambient, rock, orchestral, pop?

- **Mood** — Upbeat, calm, dramatic, inspiring, playful, cinematic?

- **Tempo** — Fast, medium, slow?

- **Vocals** — Instrumental only (recommended for background), or with vocals?

### 2. Generate Music

- Craft a descriptive prompt and generate:

+ Generate with Eleven Music (`music_v2_5`). It's cleared for commercial use on paid ElevenLabs plans, and the Music API needs one.

- ```

- Use remotion-media generate_music:

- - prompt: "[genre] background music, [mood], [tempo], no vocals, [additional descriptors]"

- - output_name: music-bg

- - instrumental: true

+ 1. If `ELEVENLABS_API_KEY` isn't set for the project, run `npx -y @elevenlabs/cli@latest onboard init` from the project root and follow what it prints. Never ask for the key in chat.

+ 2. `npm i @elevenlabs/elevenlabs-js`, then add a `music` entry to `scripts/generate-audio.ts` (create it from the `audio-integration` rule if it doesn't exist):

+ ```ts

+ const music = [

+ { name: "music-bg", prompt: "[genre] background music, [mood], [tempo], [additional descriptors]", lengthMs: 30_000 },

+ ];

```

- Files land in `public/` of the directory your agent was launched from, so start your agent (Claude Code, Codex, Gemini CLI…) from the Remotion project root.

+ 3. Set `lengthMs` to the video length plus a few seconds (measure the voiceover first if there is one). The script forces instrumental output; for a track with vocals, set `forceInstrumental: false`.

+ 4. Run `node scripts/generate-audio.ts` from the project root. The track lands at `public/music-bg.mp3`. To regenerate it, delete the file and run the script again.

**Good prompt examples:**

- - "upbeat electronic background music, energetic, no vocals, modern tech startup vibe"

- - "calm acoustic guitar, warm and friendly, no vocals, coffee shop atmosphere"

- - "epic cinematic orchestral, building tension and release, no vocals, trailer style"

- - "chill lo-fi hip hop beats, relaxed and dreamy, no vocals, study music vibe"

+ - "upbeat electronic background music, energetic, modern tech startup vibe"

+ - "calm acoustic guitar, warm and friendly, coffee shop atmosphere"

+ - "epic cinematic orchestral, building tension and release, trailer style"

+ - "chill lo-fi hip hop beats, relaxed and dreamy, study music vibe"

+ Don't name artists, bands or song lyrics in the prompt; Eleven Music rejects them and suggests a rewording.

+ **Alternatives:**

+ - The **ElevenLabs MCP** `compose_music` tool is deprecated (archived upstream) but still ships for quick interactive one-offs. It writes into `public/`; rename its output to `music-bg.mp3`.

+ - **KIE `generate_music`** (remotion-media, Suno) for cheap drafts: `prompt`, `output_name: music-bg`, `instrumental: true`. Suno and the other KIE-resold models aren't licensed by their owners through KIE. Use KIE audio for drafts and internal work, and generate final commercial audio with ElevenLabs.

### 3. Wire into Composition

Place it with `<Audio>` from `@remotion/media` (install with `npx remotion add @remotion/media`), following the official `remotion-markup` skill (audio.md), with fade in/out:

```tsx

import { Audio } from "@remotion/media";

import { interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();

const { durationInFrames, fps } = useVideoConfig();

<Audio

src={staticFile("music-bg.mp3")}

volume={interpolate(

frame,

[0, fps, durationInFrames - 2 * fps, durationInFrames],

[0, 0.25, 0.25, 0],

{ extrapolateLeft: "clamp", extrapolateRight: "clamp" },

)}

```

### 4. Adjust for Voiceover (if present)

If the project has a voiceover, implement volume ducking — lower music to 0.1 during narration, 0.3 during silent parts. See `audio-integration` rule for the pattern.

### 5. Preview in Studio

If Studio isn't running, start it with `npx remotion studio` (or `--no-open` with an in-app browser, then open the URL it prints). Ask the user to listen there. Don't render unless they ask for an MP4.

Offer adjustments:

- Volume too loud/quiet?

- - Wrong mood? Regenerate with a different prompt.

- - Music too short? Add `loop` to the `<Audio>`, or generate a longer track.

- - Need different music for different sections? Generate multiple tracks (`music-intro`, `music-main`, …) and give each its own `from` and `durationInFrames`.

+ - Wrong mood? Change the prompt, delete `public/music-bg.mp3` and run the script again.

+ - Music too short? Regenerate with a longer `lengthMs`, or add `loop` to the `<Audio>`.

+ - Need different music for different sections? Add more `music` entries (`music-intro`, `music-main`, …) and give each `<Audio>` its own `from` and `durationInFrames`, or use a composition plan (official `music` skill) for one track with sections.