OpenMontage/skills/creative/music-gen-usage.md

Music Generation Usage for OpenMontage

Sources: ElevenLabs Music API documentation, ElevenLabs best practices guide, Artlist BPM guide, existing Layer 3 skills at .agents/skills/music/ and .agents/skills/elevenlabs/

Quick Reference Card

API MODEL:        music_v1
MIN DURATION:     3,000ms (3s)
MAX DURATION:     600,000ms (10 min)
INSTRUMENTAL:     Always set force_instrumental=true for video background
COST:             ~$0.05 per 30 seconds
KEY RULE:         Music must be 18-20 dB below narration (see sound-design.md)

BPM Selection by Video Type

Video Type	BPM Range	Prompt Fragment
Educational explainer	80-100	"gentle ambient electronic, 90 BPM"
Corporate / tech	100-120	"upbeat corporate pop, 110 BPM, positive"
Epic / dramatic reveal	60-80	"cinematic orchestral, 70 BPM, building tension"
Fast-paced montage	120-140	"energetic electronic, 130 BPM, driving beat"
Meditation / calm	50-70	"ambient drone, 60 BPM, peaceful"
Comedy / lighthearted	100-130	"playful ukulele pop, 120 BPM, whimsical"
Sad / reflective	60-80	"melancholic piano, 65 BPM, minor key"
Action / hype	140-170	"high-intensity drum and bass, 160 BPM"

Key and Mood Mapping

Mood	Key	Musical Characteristics
Happy / upbeat	C major, G major	Bright, resolved, energetic
Serious / professional	D minor, A minor	Grounded, authoritative
Mysterious / curious	E minor, B minor	Tension, anticipation
Triumphant / inspiring	D major, Bb major	Expansive, climactic
Melancholic / thoughtful	F minor, C minor	Reflective, emotional
Neutral / ambient	C major, Am (no strong key)	Unobtrusive, background

Prompt Engineering

Structure

[GENRE/STYLE], [BPM], [KEY/MOOD], [INSTRUMENTS], [ENERGY LEVEL], [PURPOSE]

Examples

Educational explainer:

Gentle lo-fi ambient electronic, 90 BPM, C major, soft synth pads and light
percussion, calm and steady energy, background music for narration

Corporate product demo:

Modern upbeat corporate pop, 110 BPM, G major, acoustic guitar and light drums,
positive energy building gradually, underscore for product walkthrough

Technical deep-dive:

Minimal ambient electronic, 80 BPM, A minor, soft Rhodes piano and subtle
bass, contemplative and focused, background music for technical explanation

Key Prompting Rules

1. Always include "background" or "underscore" — tells the model to stay dynamically even
2. Always use force_instrumental=true — lyrics compete with narration
3. Specify BPM explicitly — don't rely on genre to set tempo
4. Avoid "bright hi-hats" or "prominent vocals" — high-frequency busy elements compete with speech in the 2-4 kHz intelligibility band
5. Include energy direction — "steady energy" for explainers, "building gradually" for reveals

Duration Matching

Exact Duration

result = music_gen.execute({
    "prompt": "Gentle ambient, 90 BPM, background underscore",
    "duration_seconds": 150,  # Match video length
    "output_path": "assets/music/background.mp3"
})

Section-Mapped (Advanced)

For videos with distinct acts, generate sections separately:

Video Section	Duration	Music Style
Intro / hook	8-10s	Soft, building
Main explanation	90-120s	Steady, neutral
Key reveal	20-30s	Intensified, fuller
Outro	10-15s	Fading, gentle

Generate each as a separate track and crossfade in the audio_mixer.

Looping for Long Videos

For videos longer than the generated track:

1. Generate a track 30-60% of video length
2. Use FFmpeg to create a seamless loop:

   ffmpeg -stream_loop 2 -i music.mp3 -c copy music_looped.mp3
   

3. Add a 2-3 second crossfade at loop points in audio_mixer

Better approach: Generate at the exact video duration. ElevenLabs supports up to 10 minutes per generation.

Stem Isolation

For cleaner ducking control, generate isolated stems:

• "solo electric guitar in E minor, 90 BPM" — guitar-only track
• "soft ambient pad in C major, 80 BPM" — synth pad only
• Layer stems in FFmpeg during composition for precise ducking control

Applying to OpenMontage

When using the music_gen tool:

1. Match BPM to content type using the table above — don't default to a generic prompt
2. Always set force_instrumental=true — no lyrics under narration
3. Include "background" or "underscore" in every prompt
4. Set duration to match video length — avoid looping when possible
5. Budget check — at $0.05/30s, a 3-minute video costs ~$0.30 for music
6. Duck music 18-20 dB below narration — see skills/creative/sound-design.md for ducking rules
7. Cut 2-4 kHz on the music bed in audio_mixer to clear the speech intelligibility band
8. Test on phone speakers — if narration disappears behind music, duck more aggressively
9. One track per video — avoid switching music styles mid-video unless there's a clear narrative shift