# Audio Mix Maker

> 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', 'смешай музыку с видео', 'фоновая музыка для видео'.

- **Type:** Skill
- **Install:** `agentstack add skill-mikefluff-skills-audio-mix-maker`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Mikefluff](https://agentstack.voostack.com/s/mikefluff)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Mikefluff](https://github.com/Mikefluff)
- **Source:** https://github.com/Mikefluff/skills/tree/main/skills/audio-mix-maker
- **Website:** https://www.npmjs.com/package/@mikefluff/skills

## Install

```sh
agentstack add skill-mikefluff-skills-audio-mix-maker
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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)

## ROLE

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

## PIPELINE

1. **Resolve inputs**:
   - `--video ` — source MP4 / MOV / WebM (required)
   - `--audio ` — 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 ` — 0.0-2.0 music volume (default 0.8)
   - `--fade-in ` — fade in duration (default 0)
   - `--fade-out ` — fade out duration (default 0.5)
   - `--duck-amount ` — 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: `-mixed` next to source
   - Custom: `--output `

## MODES

### Required

- `audio-mix-maker --video  --audio `

### Mix mode

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

### Volume

- `--volume ` (default 0.8)
- `--fade-in ` (default 0)
- `--fade-out ` (default 0.5)
- `--duck-amount ` (default 0.6, duck mode only)

### Output

- `--output ` (default: `-mixed`)

## 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Mikefluff](https://github.com/Mikefluff)
- **Source:** [Mikefluff/skills](https://github.com/Mikefluff/skills)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mikefluff-skills-audio-mix-maker
- Seller: https://agentstack.voostack.com/s/mikefluff
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.