/mastering-engineer

name: mastering-engineer
description: 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.
argument-hint: <folder-path or "master for [platform]">
model: sonnet
effort: low
prerequisites:
  - import-audio
allowed-tools:
  - Read
  - Edit
  - Write
  - Grep
  - Glob
  - Bash
  - bitwize-music-mcp
requirements:
  python:
    - matchering
    - pyloudnorm
    - scipy
    - numpy
    - soundfile

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.

Never a Watermark-Removal Step

Mastering is loudness, dynamics and tonal balance. Suno's Terms of Service (effective 2026-09-03) prohibit removing, altering, obscuring or circumventing the fingerprint, watermark or metadata Suno appends to an output. No step in this workflow does that, and no step may be described that way.

---

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`:**

# Custom Mastering Presets

genres:
  dark-electronic:
    cut_highmid: -3         # More aggressive cut
    target_lufs: -12        # Louder master
    compress_ratio: 2.0     # Heavier compression
    compress_attack: 15.0   # Faster attack

  ambient:
    cut_highmid: -1         # Gentle cut
    target_lufs: -16        # Quieter, more dynamic
    compress_ratio: 1.2     # Very light compression

defaults:
  dither_bits: 24           # 24-bit output for archival

**Available preset fields:**

| Category | Fields | |----------|--------| | Loudness | `target_lufs`, `target_lra` | | EQ cuts | `cut_highmid`, `cut_highs` | | EQ high-mid | `eq_highmid_freq`, `eq_highmid_q` | | EQ highs | `eq_highs_freq`, `eq_highs_q` | | EQ low shelf | `eq_low_freq`, `eq_low_gain`, `eq_low_q` | | EQ sub-bass | `eq_sub_cut_freq` | | EQ options | `eq_linear_phase` | | Compression | `compress_ratio`, `compress_threshold`, `compress_attack`, `compress_release`, `compress_mix`, `compress_makeup` | | Multiband | `multiband_enabled`, `multiband_low_crossover`, `multiband_high_crossover`, `multiband_low_ratio`, `multiband_mid_ratio`, `multiband_high_ratio`, `multiband_low_threshold`, `multiband_mid_threshold`, `multiband_high_threshold` | | Mid/side EQ | `midside_low_gain`, `midside_low_freq`, `midside_high_gain`, `midside_high_freq` | | Stereo | `stereo_width`, `stereo_bass_mono_freq` | | De-essing | `deess_enabled`, `deess_freq`, `deess_bandwidth`, `deess_threshold`, `deess_ratio` | | Limiting | `limiter_lookahead_ms`, `limiter_release_ms` | | Processing | `dc_filter_freq`, `processing_oversample` | | Output | `output_bits`, `dither_bits`, `output_sample_rate`, `track_gap` |

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 (field-level merge) 4. Only specify fields you want to change — unset fields inherit from built-in

**Example:**

• Mastering "dark-electronic" genre
• Override has custom preset
• Result: Apply -3 highmid cut, 2.0:1 compression with 15ms attack, 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." 5. **Input format** — Suno Create-page WAVs are 44.1 kHz; Suno Studio exports are 32-bit float / 48 kHz. Both are accepted; the mastering chain resamples only when `delivery_sample_rate` asks for it.

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 gen