audio-mix-maker git:20260803.e8ff76fA

Immutable. This exact content never changes and is served at /api/v1/blob/add8be440f3c8626.

---
name: audio-mix-maker
description: "Mix music/audio onto an existing video via ffmpeg. Modes: replace, overlay, duck (sidechain compressor lowers music under speech). Volume + fade controls. Pure ffmpeg, no API. Use when: 'mix this music onto the video', 'add background music to video', 'duck the music under voiceover', 'смешай музыку с видео', 'фоновая музыка для видео'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

<objective>
Mix a music / audio track onto an existing video with ffmpeg-driven post-processing. Returns a new MP4 with the music mixed according to the chosen mode.

Distinct from `reel-builder`:
- reel-builder ORCHESTRATES generation + stitching from scratch (script → shots → music → stitch). This skill is JUST the final-mix step on assets you already have.
- No script / no video / music generation — bring your own.

Distinct from `subtitle-burner`:
- subtitle-burner adds CAPTIONS. This skill adds AUDIO MIX.
- Both are pure-ffmpeg utilities — they share the lightweight wrapper pattern.

Distinct from `voiceover-maker`:
- voiceover-maker GENERATES TTS. This skill MIXES audio onto video.

This skill does NOT:
- Generate music (use `music-prompt --execute` first)
- Generate voiceover (use `voiceover-maker --execute` first)
- Stitch multiple video clips (use `reel-builder` for that, or raw ffmpeg `concat`)
- Cut / trim video segments (use ffmpeg / DaVinci Resolve / Premiere)
- Sync audio to specific moments (use a NLE — Final Cut / Premiere / DaVinci)
</objective>

## ROLE

Read video + music + mode + volume/fade controls → run ffmpeg with the right filter chain → save mixed MP4.

## PIPELINE

1. **Resolve inputs**:
   - `--video <path>` — source MP4 / MOV / WebM (required)
   - `--audio <path>` — music / SFX / voiceover (required)

2. **Pick mode**:
   - `--mode replace` (default) — drop the video's original audio, use music as sole track
   - `--mode overlay` — mix music ON TOP of original audio (both audible at constant volume)
   - `--mode duck` — overlay with sidechain compression (music auto-lowers when speech detected)

3. **Volume + fade controls**:
   - `--volume <multiplier>` — 0.0-2.0 music volume (default 0.8)
   - `--fade-in <seconds>` — fade in duration (default 0)
   - `--fade-out <seconds>` — fade out duration (default 0.5)
   - `--duck-amount <0-1>` — duck mode only: how much music attenuates (default 0.6)

4. **Detect ffmpeg** — print install instructions if missing.

5. **Run ffmpeg** — encoded as one of three filter chains depending on mode.

6. **Save**:
   - Default: `<video-stem>-mixed<ext>` next to source
   - Custom: `--output <path>`

## MODES

### Required

- `audio-mix-maker --video <path> --audio <path>`

### Mix mode

- `--mode replace|overlay|duck` (default `replace`)

### Volume

- `--volume <0.0-2.0>` (default 0.8)
- `--fade-in <seconds>` (default 0)
- `--fade-out <seconds>` (default 0.5)
- `--duck-amount <0.0-1.0>` (default 0.6, duck mode only)

### Output

- `--output <path>` (default: `<video-stem>-mixed<ext>`)

## REFERENCES (load on demand)

| File | When to load |
|---|---|
| [references/modes.md](references/modes.md) | Step 2 — when to pick replace vs overlay vs duck, and how each affects the listener |
| [references/troubleshoot.md](references/troubleshoot.md) | When ffmpeg fails, audio is clipped, ducking too aggressive / too subtle |

## EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: silent screen recording + background music (replace), voiceover-driven explainer + background music (duck), b-roll with original audio + music bed (overlay).

## CONSTRAINTS

- **ffmpeg required.** Install: `brew install ffmpeg` (Mac) / `apt-get install -y ffmpeg` (Debian). install.sh offers auto-install.

- **Video codec preserved.** This skill uses `-c:v copy` — no re-encode of video frames. Output video quality identical to source.

- **Audio re-encoded.** Output audio is AAC 192kbps (industry standard for video).

- **Music length usually exceeds video.** Skill uses `-shortest` flag — output truncates at the shorter of (video duration, music duration). Music is faded out at the cut point if `--fade-out > 0`.

- **Duck mode requires speech in the video.** If there's no speech / dialogue, duck mode behaves like overlay. For pure music-on-music: use overlay.

- **Volume max is ~2.0.** Past 2× the source volume, distortion appears. For louder music: re-master the input audio file first.

- **Fade timing is from the video start.** Fade-in starts at t=0; fade-out completes at the end of the shorter track. Custom mid-clip fades require DaVinci / Premiere / manual ffmpeg.

- **Output is MP4 by default.** If source is MOV / WebM, output preserves the container.

- **Cost = $0.** No API calls — local ffmpeg only.

- **No multitrack mixing.** v1 mixes ONE music track onto video. For multi-track (music + SFX + voiceover): chain calls or use a DAW.

- **Sample rate / channel layout handled implicitly.** ffmpeg resamples as needed. For exact control: use raw ffmpeg.

## INVOCATION HINTS

When the user says any of:

- "mix this music onto the video", "add background music"
- "duck the music under the voiceover", "lower music when speech"
- "replace audio with music"
- "смешай музыку с видео", "фоновая музыка для видео"
- "подложи трек под видосик"

If the user describes a podcast / explainer / interview workflow with voiceover, suggest `--mode duck`. If pure music video / silent footage, suggest `--mode replace`.

Defaults: `--mode replace --volume 0.8 --fade-out 0.5`. No `--execute` flag — the skill always executes (it's a local-only utility, no cost).

This skill is distinct from:
- `reel-builder` — generates + stitches; this is final-mix only
- `subtitle-burner` — captions, not audio
- `voiceover-maker` — generates TTS; this mixes
- `music-prompt` — generates music; this consumes the output of music-prompt
- `gif-maker` — produces GIF, no audio