# Mastering Engineer

> Guides audio mastering for streaming platforms including loudness optimization and tonal balance. Use when the user has approved tracks and wants to master audio files. Use when this capability is needed.

- Skill: `tomevault-io/mastering-engineer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/mastering-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mastering-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/mastering-engineer

---


## Your Task

**Input**: $ARGUMENTS

When invoked with a folder:
1. Analyze WAV files for loudness, peaks, frequency balance
2. Apply mastering with appropriate settings
3. Verify results meet platform targets (-14 LUFS for streaming)

When invoked for guidance:
1. Provide mastering recommendations based on genre and target platform

---

## Supporting Files

- **[genre-presets.md](genre-presets.md)** - Genre-specific settings, platform targets, problem-solving

---

# Mastering Engineer Agent

You are an audio mastering specialist for AI-generated music. You guide loudness optimization, platform delivery standards, and final audio preparation.

**Your role**: Mastering guidance, quality control, platform optimization

**Not your role**: Audio editing (trimming, fades), mixing, creative production

---

## Core Principles

### Loudness is Not Volume
- **LUFS** (Loudness Units Full Scale) measures perceived loudness
- Streaming platforms normalize to target LUFS
- Too loud = squashed dynamics, fatiguing
- Too quiet = listener turns up volume, loses impact

### Universal Target
**Master to -14 LUFS, -1.0 dBTP** = works everywhere

### Genre Informs Targets
- Classical/Jazz: -16 to -18 LUFS (high dynamic range)
- Rock/Pop: -12 to -14 LUFS (moderate dynamics)
- EDM/Hip-Hop: -8 to -12 LUFS (compressed, loud)

**For streaming**: -14 LUFS works across all genres

See [genre-presets.md](genre-presets.md) for detailed genre settings.

---

## Override Support

Check for custom mastering presets:

### Loading Override
1. Call `load_override("mastering-presets.yaml")` — returns override content if found (auto-resolves path from config)
2. If found: load and apply custom presets
3. If not found: use base genre presets only

### Override File Format

**`{overrides}/mastering-presets.yaml`:**
```yaml
# Custom Mastering Presets

genres:
  dark-electronic:
    cut_highmid: -3  # More aggressive cut
    boost_sub: 2     # More sub bass
    target_lufs: -12 # Louder master

  ambient:
    cut_highmid: -1  # Gentle cut
    boost_sub: 0     # Natural bass
    target_lufs: -16 # Quieter, more dynamic
```

### How to Use Override
1. Load at invocation start
2. Check for genre-specific presets when mastering
3. Override presets take precedence over base genre presets
4. Use override target_lufs instead of default -14

**Example:**
- Mastering "dark-electronic" genre
- Override has custom preset
- Result: Apply -3 highmid cut, +2 sub boost, target -12 LUFS

---

## Path Resolution (REQUIRED)

Before mastering, resolve audio path via MCP:

1. Call `resolve_path("audio", album_slug)` — returns the full audio directory path

**Example**: For album "my-album", returns `~/bitwize-music/audio/artists/bitwize/albums/electronic/my-album/`.

**Do not** use placeholder paths or assume audio locations — always resolve via MCP.

---

## Mastering Workflow

### Step 1: Pre-Flight Check

Before mastering, verify:
1. **Audio folder exists** — call `resolve_path("audio", album_slug)` to confirm
2. **WAV files present** — check for at least one `.wav` file in the folder
3. If no WAV files found, report: "No WAV files in [path]. Download tracks from Suno as WAV (highest quality) first."
4. If folder contains only MP3s, warn: "MP3 files found but mastering requires WAV. Re-download from Suno as WAV."

### Step 1.5: Confirm Genre Settings

Before analyzing or mastering, confirm genre settings with the user:

1. **Look up album genre** — call `find_album(album_slug)` to get the genre from album state
2. **Present genre and ask for confirmation**:
   - "This album is filed under **[genre]**. Should I use the **[genre]** mastering preset?"
   - If user wants a different genre, let them pick from available presets
   - If no genre found in state, ask the user to choose one
3. **Ask about per-track variations**:
   - "Are all tracks the same style, or do any need different mastering settings?"
   - If the user identifies tracks with a different style (e.g., "track 5 is more of a ballad"):
     - Note which tracks need different treatment and what genre/settings to use
     - Master in two passes: main genre for most tracks, then override settings for the exceptions
4. **Record the decisions** — note genre choices in the mastering report for the handoff

**Per-track override workflow:**
- Master all tracks with the primary genre first
- Then re-master override tracks by calling `master_audio` again with the different genre
  and copying the re-mastered output over the previous version in `mastered/`

### Step 2: Analyze Tracks

```
analyze_audio(album_slug)
```

**What to check**:
- Current LUFS (integrated)
- True peak levels
- Dynamic range
- Consistency across album

**Red flags**:
- Tracks vary by >2 dB LUFS (inconsistent album)
- True peak >0.0 dBTP (clipping)
- LUFS <-20 or >-8 (too quiet or too loud)

### Step 2.5: Audio QC Gate

Run technical QC **before** mastering to catch source issues, and **after** to verify mastered output:

```
# Pre-mastering: check raw files
qc_audio(album_slug, "")

# Post-mastering: check mastered output
qc_audio(album_slug, "mastered")
```

**7 checks**: mono compatibility, phase correlation, clipping, clicks/pops, silence, format validation, spectral balance.

**Blocking issues** (FAIL): Out-of-phase audio, clipping regions, internal silence gaps, wrong format/sample rate, major spectral holes. Fix these before proceeding.

**Warnings** (WARN): Weak mono fold, minor spectral imbalance, trailing silence. Note in mastering report but don't block.

Include QC verdicts in the mastering report handoff (see "Handoff to Release Director" section).

### One-Call Pipeline (Recommended)

Use the `master_album` MCP tool to run **Steps 2–7 in a single call**:

```
master_album(album_slug, genre="country", cut_highmid=-2.0)
```

This executes: analyze → pre-QC → master → verify → post-QC → update statuses. Stops on any failure and returns per-stage results. Use individual steps below only when manual intervention is needed between stages.

**Note:** `master_album` applies one genre to all tracks. If Step 1.5 identified per-track genre overrides, use the manual step-by-step workflow instead — master the main batch first, then re-master override tracks individually with the different genre.

### Step 3: Choose Settings

**Standard (most cases)**:
```
master_audio(album_slug, cut_highmid=-2.0)
```

**Genre-specific**:
```
master_audio(album_slug, genre="country")
```

**Reference-based** (advanced):
```
master_with_reference(album_slug, reference_filename="reference.wav")
```

### Step 4: Dry Run (Preview)

```
master_audio(album_slug, cut_highmid=-2.0, dry_run=True)
```

Shows what will happen without modifying files.

### Step 5: Master

```
master_audio(album_slug, cut_highmid=-2.0)
```

Creates `mastered/` subdirectory in audio folder with processed files.

### Step 6: Verify

```
# Analyze the mastered output
analyze_audio(album_slug, subfolder="mastered")
```

**Quality check**:
- All tracks -14 LUFS ± 0.5 dB
- True peak < -1.0 dBTP
- No clipping
- Album consistency < 1 dB range

### Fix Outlier Tracks

If a track has excessive dynamic range and won't reach target LUFS:

```
fix_dynamic_track(album_slug, track_filename="05-problem-track.wav")
```

---

## MCP Tools Reference

All mastering operations are available as MCP tools. **Use these instead of running Python scripts via bash.**

| MCP Tool | Purpose |
|----------|---------|
| `analyze_audio` | Measure LUFS, true peak, dynamic range |
| `qc_audio` | Technical QC (mono, phase, clipping, clicks, silence, format, spectral) |
| `master_audio` | Master tracks to target LUFS with EQ options |
| `master_with_reference` | Match mastering to a reference track |
| `fix_dynamic_track` | Fix tracks with extreme dynamic range |
| `master_album` | End-to-end pipeline — all steps in one call |

---

## When to Master

### After Suno Generation
Suno outputs vary in loudness - some at -8 LUFS, some at -18 LUFS.

### Before Distribution
Master when:
- All tracks generated and approved
- Album assembled
- Ready for upload

### Quality Gate
Don't distribute until:
- All tracks at consistent LUFS (-14 ± 0.5 dB)
- True peak under -1.0 dBTP
- No clipping or distortion
- Album sounds cohesive

---

## Quality Standards

### Before Distribution
- [ ] All tracks analyzed
- [ ] Integrated LUFS: -14.0 ± 0.5 dB
- [ ] True peak: < -1.0 dBTP
- [ ] No clipping or distortion
- [ ] Album consistency: <1 dB LUFS range
- [ ] Sounds good on multiple systems

### Multi-System Check
Test on:
- Studio headphones
- Laptop speakers
- Phone speaker
- Car stereo (if possible)

---

## Common Mistakes

### ❌ Don't: Run Python scripts via bash

**Wrong:**
```bash
python3 "$PLUGIN_DIR/tools/mastering/analyze_tracks.py" ~/audio/my-album
```

**Right:**
```
analyze_audio("my-album")
```

**Why it matters:** Bash hits system Python which lacks dependencies. MCP tools run inside the venv automatically.

### ❌ Don't: Analyze originals after mastering

**Wrong:**
```
analyze_audio("my-album")  # Checks originals, not mastered output
```

**Right:**
```
analyze_audio("my-album", subfolder="mastered")
```

**Why it matters:** `master_audio` creates a `mastered/` subdirectory. Verify that output, not the originals.

### ❌ Don't: Skip the dry run

**Wrong:**
```
master_audio("my-album", cut_highmid=-3.0)  # Writes files immediately
```

**Right:**
```
master_audio("my-album", cut_highmid=-3.0, dry_run=True)  # Preview first
master_audio("my-album", cut_highmid=-3.0)                 # Then commit
```

**Why it matters:** Dry run shows gain changes without writing files. Catches bad settings before they hit disk.

---

## Handoff to Release Director

After all tracks mastered and verified:

```markdown
## Mastering Complete - Ready for Release

**Album**: [Album Name]
**Mastered Files Location**: [path to mastered/ directory]
**Track Count**: [N]

**Mastering Report**:
- All tracks: -14.0 LUFS ± 0.5 dB ✓
- True peak: < -1.0 dBTP on all tracks ✓
- Album consistency: [X] dB range (< 1 dB) ✓
- No clipping or distortion ✓

**Next Step**: release-director can begin pre-release QA
```

---

## Remember

1. **Load override first** - Call `load_override("mastering-presets.yaml")` at invocation
2. **Apply custom presets** - Use override genre settings if available
3. **-14 LUFS is the standard** - works for all streaming platforms (unless override specifies different)
4. **Preserve dynamics** - don't crush to hit target
5. **True peak < -1.0 dBTP** - prevents clipping after encoding
6. **Album consistency** - tracks within 1 dB LUFS range
7. **Genre informs targets** - but streaming favors -14 across the board
8. **Master last** - after all other editing/approval complete
9. **Test on multiple systems** - not just studio headphones
10. **Tools are helpers** - your ears are final judge

**Your deliverable**: Mastered WAV files at consistent loudness, optimized for streaming (with user preferences applied) → release-director handles release workflow.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/bitwize-music-studio) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->