# Iopho Audio Director

> >

- **Type:** Skill
- **Install:** `agentstack add skill-iopho-team-iopho-skills-iopho-audio-director`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [iopho-team](https://agentstack.voostack.com/s/iopho-team)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [iopho-team](https://github.com/iopho-team)
- **Source:** https://github.com/iopho-team/iopho-skills/tree/main/skills/iopho-audio-director

## Install

```sh
agentstack add skill-iopho-team-iopho-skills-iopho-audio-director
```

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

## About

# iopho-audio-director

Plan and produce the complete audio layer for product videos: BGM + VO + SFX → master audio.

## Modes

### Mode 1: `plan` — Generate audio strategy

Read the project's storyboard and context, then output an `audio-plan.md` with:

**1. Architecture Decision**
```
Total duration: {X}s @ {fps}fps = {frames} frames
VO coverage: {Y}% of scenes have voiceover
BGM strategy: {continuous bed | scene-matched segments | minimal/ambient}
SFX density: {minimal | moderate | rich}
```

**2. BGM Specification**
- Genre, BPM, mood, instrument palette
- Suno prompt (use template from [references/audio-recipes.md](references/audio-recipes.md) §3)
- Scene-by-scene music energy map:
  ```
  Scene 1 (0:00-0:08): Low energy — ambient pad, space for hook
  Scene 2 (0:08-0:15): Rising — add percussion, build
  Scene 3 (0:15-0:30): Peak — full arrangement for demo
  ...
  ```

**3. VO Timing Table**
| Scene | Start (s) | Start (f) | VO Text | Est. Duration | Engine |
|-------|----------|----------|---------|---------------|--------|
| hook-1a | 5.3 | 160 | "..." | 3.5s | ElevenLabs |

**4. SFX Placement**
| Timestamp | SFX | Trigger | Duration |
|-----------|-----|---------|----------|
| 0:05 | UI click | Button press in demo | 0.3s |

**5. Duck Schedule**
| Time Range | BGM Level | Reason |
|-----------|-----------|--------|
| 0:00-0:05 | 0dB | Music-only intro |
| 0:05-0:09 | -18dB | VO speaking |
| 0:09-0:12 | -12dB | Instrumental visual |

### Mode 2: `assemble` — Execute the audio plan

Takes individual audio files and combines them into the master audio track.

**Inputs needed**:
- `bgm.mp3` — background music (trimmed to video length)
- `master-vo.mp3` — assembled voiceover (from `/iopho-voiceover-tts assemble`)
- SFX files (if any) — with target timestamps

**Assembly sequence**:
1. **Trim BGM** to video length with fade-out:
   ```bash
   ffmpeg -i bgm-full.mp3 -t {duration} -af "afade=t=out:st={duration-3}:d=3" bgm.mp3
   ```

2. **Duck BGM under VO** (sidechain compress):
   See [references/audio-recipes.md](references/audio-recipes.md) §2b for the ffmpeg command.

3. **Layer SFX** at timestamps:
   See [references/audio-recipes.md](references/audio-recipes.md) §2d for adelay placement.

4. **Normalize** to platform target:
   - YouTube: -16 LUFS
   - Social media: -14 LUFS
   See [references/audio-recipes.md](references/audio-recipes.md) §2c.

5. **Export** master audio:
   ```
   {project}/audio/master-audio.mp3       — final mix
   {project}/audio/master-audio-loud.mp3  — social media version (-14 LUFS)
   ```

### Mode 3: `analyze` — Inspect existing audio

Run `scripts/analyze_audio.py` on any audio file to get:
- BPM (global + dynamic), beats, onsets
- Energy envelope, key moments
- Structural sections

```bash
python3 scripts/analyze_audio.py path/to/audio.mp3 --output analysis.json
python3 scripts/analyze_audio.py path/to/audio.mp3 --gemini  # optional AI analysis
```

Use analysis output to:
- Match BGM tempo to scene cuts
- Verify duck timing aligns with VO segments
- Find beat-sync points for MG animations

## Decision Guide

| Question | Answer | Action |
|----------|--------|--------|
| Have a storyboard? | Yes | Start with `plan` mode |
| Have a storyboard? | No | Run `/iopho-video-director` Phase 1 first |
| Need BGM? | Generate new | Use Suno prompt template from recipes §3 |
| Need BGM? | Have a track | Skip to `assemble` mode |
| Need VO? | Yes | Run `/iopho-voiceover-tts` first, then `assemble` |
| Need VO? | No (music video / MG) | Simpler: just trim + normalize BGM |
| Platform? | YouTube | Target -16 LUFS |
| Platform? | TikTok/Reels | Target -14 LUFS (louder) |

## Proven Values

These settings are battle-tested in production (78s explainer, 10 VO segments):

| Parameter | Value | Source |
|-----------|-------|--------|
| VO duck level | -18dB | {project}-audio-plan.md |
| Instrumental duck | -12dB | {project}-audio-plan.md |
| Duck fade-down | 200ms | tested in ffmpeg |
| Duck fade-up | 500ms | tested in ffmpeg |
| VO rate-limit (ElevenLabs) | 0.5s between calls | API throttle |
| MP3 bitrate | 128-192kbps | balance quality/size |
| Sample rate | 44100Hz | standard (48kHz for App Store) |
| FPS constant | 30 | project-wide |

## Audio Recipes Reference

See [references/audio-recipes.md](references/audio-recipes.md) for:
- §1: Duck levels table (full reference)
- §2: FFmpeg commands (duck, sidechain, normalize, SFX, trim, analyze)
- §3: Suno music prompt templates with examples (reader app + CLI tool)
- §4: SFX catalog
- §5: 3-layer architecture diagram
- §6: Platform-specific audio specs

## Related Skills

- `/iopho-voiceover-tts` — produces master-vo.mp3 that this skill ducks under BGM
- `/iopho-video-director` — calls this at Phase 1 (plan) and Phase 2 (assemble)
- `/suno-music-creator` — generates BGM from Suno prompts (external skill)
- `/remotion-best-practices` → `rules/audio.md` — integrates master-audio into Remotion
- `/iopho-product-context` — reads context.md for brand tone → influences BGM mood

## Source & license

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

- **Author:** [iopho-team](https://github.com/iopho-team)
- **Source:** [iopho-team/iopho-skills](https://github.com/iopho-team/iopho-skills)
- **License:** MIT

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-iopho-team-iopho-skills-iopho-audio-director
- Seller: https://agentstack.voostack.com/s/iopho-team
- 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%.