Overview

mastacraf is a command-line audio mastering pipeline that applies a configurable processing chain to audio files. It is built for self-produced, self-mixed experimental electronic music — material where no commercial loudness standard applies and the goal is a repeatable, documented process you own entirely.

It does not make aesthetic decisions. You define the targets, the filters, and the dynamics behavior in a preset file. mastacraf applies them, measures the result, and writes a report documenting exactly what happened.

What it does

• Measures integrated loudness (LUFS), true peak, loudness range, RMS, crest factor, dynamic range, DC offset, phase correlation, and spectral balance
• Applies a configurable filter chain: high-pass, optional low-pass, optional compression, peak limiting, two-pass EBU R128 loudness normalization
• Outputs all files for a track into a dedicated subfolder named after the track stem
• Generates before/after spectrogram and waveform images
• Writes a JSON report with all measurements, the exact FFmpeg filter string, and input/output delta

What it does not do

• Make EQ decisions
• Automatically match loudness to a reference track
• Alter the stereo field, phase, or any aspect of the mix outside the defined chain

How it works

The two-pass loudnorm process #

The core of every master run is FFmpeg's loudnorm filter, run twice.

Pass 1 (analysis): The entire file is decoded and fed through loudnorm in measurement-only mode. No audio is written. The filter outputs a JSON block containing the file's measured integrated loudness, true peak, loudness range, and threshold.

Pass 2 (processing): The file is decoded again through the full filter chain. The loudnorm filter on this pass receives the pass-1 measurements and applies a linear gain adjustment. Because it has full-file measurements, it can apply a precise, artifact-free gain change.

Extended analysis passes #

After pass 1, three additional FFmpeg passes collect extended analysis data:

• astats pass — RMS level, peak level (for crest factor), DC offset
• aphasemeter pass — per-frame stereo phase correlation, averaged across the file; skipped for mono
• Three band-energy passes — volumedetect on low/mid/high bandpass-filtered signal to compute spectral balance and centroid estimate

All extended passes are non-fatal. If any fail, the core analysis still completes.

Filter chain execution #

The filter chain is a comma-separated FFmpeg -af string built by build_filter_chain() in src/pipeline/process.rs. Disabled stages are omitted entirely — they do not exist in the graph and have zero overhead.

Installation

Prerequisites #

FFmpeg must be in your $PATH, or placed alongside the compiled mastacraf binary.

brew install ffmpeg rust

sudo apt install ffmpeg
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

sudo pacman -S ffmpeg rust

Build from source #

git clone <your-repo>
cd mastacraf
cargo build --release
# binary: ./target/release/mastacraf

Verify #

mastacraf --version
mastacraf --help

Quick start

mastacraf analyze track.wav

mastacraf master track.wav

mastacraf master track.wav --preset noise
mastacraf master track.wav --preset film -o ./deliverables/

mastacraf master track.wav --preset mypreset --dry-run

CLI — master

Runs the full mastering pipeline: pre-analysis, pre-visualization, processing, post-analysis, post-visualization, report.

mastacraf master <INPUT> [OPTIONS]

# Basic master, all defaults
mastacraf master track.wav

# Named preset, custom output directory
mastacraf master track.wav -p film -o ./deliverables/

# Override loudness without editing the preset
mastacraf master track.wav --lufs -14

# Verify what the pipeline would do without writing anything
mastacraf master track.wav -p noise --dry-run -v

# Custom filename suffix
mastacraf master track.wav --suffix _2024_v1
# → mastered/track/track_2024_v1.wav

CLI — analyze

Runs full analysis: loudnorm pass 1 + extended passes. Prints all measurements. No audio written.

mastacraf analyze <INPUT> [OPTIONS]

  [analysis]
    integrated loudness        -18.4 LUFS
    true peak                  -1.2 dBTP
    loudness range             14.6 LU
    duration                   00:07:43
    format                     pcm_s24le / 44100 Hz / 2 ch

  [extended analysis]
    RMS level                  -22.1 dBFS
    crest factor               19.7 dB
    dynamic range (DR)         DR17
    DC offset                  0.00012
    phase correlation          0.741  (in phase / wide stereo)
    spectral balance           low 38%  mid 44%  high 18%
    spectral centroid          1420 Hz

CLI — presets / preset

List all presets

mastacraf presets

Lists all presets found across all search directories. Prints name, LUFS target, true peak, LRA, and description.

Inspect a preset

mastacraf preset noise
mastacraf preset film > mybase.toml   # copy as starting point

Preset search order

When you pass --preset name, mastacraf searches for name.toml in this order, using the first match:

1. ./presets/ relative to your current working directory (use this)
2. <exe_dir>/presets/ — next to the compiled binary (for bundled installs)
3. ~/.config/mastacraf/presets/ (or platform equivalent)

Creating a preset

A preset is a TOML file that fully defines one mastering configuration. Every audio-affecting field maps directly to one FFmpeg filter parameter. There is no hidden processing between what you write in the file and what FFmpeg executes.

mastacraf analyze track.wav

cp presets/default.toml presets/mypreset.toml

mastacraf master track.wav -p mypreset --dry-run

mastacraf master track.wav -p mypreset
cat mastered/track/track_master_report.json

Preset field reference — [target]

These three values define the loudness signature of the master. They are all direct inputs to FFmpeg's loudnorm filter on pass 2.

Preset field reference — [filters]

Preset field reference — [compressor]

Preset field reference — [limiter]

Preset field reference — [output]

Preset field reference — [visualization]

Analysis — core measurements (EBU R128)

Analysis — extended measurements

The filter chain

Structure and execution order #

Built in src/pipeline/process.rs, function build_filter_chain(). Disabled stages are omitted entirely from the FFmpeg filter graph — they have zero overhead.

Example output #

highpass=f=20.0,alimiter=level_in=1:level_out=0.891251:limit=0.891251:attack=5.0:release=50.0:asc=1,loudnorm=I=-16.0:TP=-1.0:LRA=11.0:measured_I=-18.43:measured_LRA=14.2:measured_TP=-2.1:measured_thresh=-28.7:offset=0.0:linear=true:print_format=summary

Viewing the chain used #

mastacraf master track.wav -v              # prints during run
cat mastered/track/track_master_report.json  # stored in report

True peak conversion #

The limiter's level_out takes linear amplitude. The tool converts target.true_peak from dBTP automatically: linear = 10 ^ (true_peak / 20)

Output folder structure

Each master run creates a dedicated subfolder inside the base output directory, named after the input file stem.

mastered/
  track01/
    track01_master.wav

    track01_pre_spectrogram.png        individual pre-master spectrogram
    track01_pre_waveform.png           individual pre-master waveform
    track01_post_spectrogram.png       individual post-master spectrogram
    track01_post_waveform.png          individual post-master waveform

    track01_compare_spectrogram.png    pre (top) + post (bottom), amber separator
    track01_compare_waveform.png       pre (top) + post (bottom), amber separator
    track01_diff_spectrogram.png       contrast-amplified pixel difference
    track01_diff_waveform.png          contrast-amplified pixel difference

    track01_master_report.json
  track02/
    ...

Visualization output

Six images per master run. Individual pre/post images are the raw material. Compare and diff images are the quick-review tools — open those first.

Individual visuals #

Spectrogram (_pre_spectrogram.png, _post_spectrogram.png)

FFmpeg: showspectrumpic=mode=combined:color=intensity:scale=log:legend=1 — X: time, Y: frequency (log scale), color: intensity. Legend on right edge.

Waveform (_pre_waveform.png, _post_waveform.png)

FFmpeg: showwavespic=split_channels=1 — X: time, Y: amplitude, L channel top, R channel below in distinct colors.

Stacked comparison (_compare_spectrogram.png, _compare_waveform.png) #

Pre on top, post below, amber 3px separator line between them. Both aligned on the same time axis — scan vertically to compare any moment.

[pre][post] → pad pre bottom +3px amber → vstack

Stacked spectrogram: Frequency content and brightness should be similar top and bottom. A band brighter in the bottom (post) image gained energy at those frequencies. Non-uniform differences — some bands brighter, some darker — indicate the compressor or limiter shaped specific moments rather than applying clean linear gain.

Stacked waveform: Envelope shape should look similar. A noticeably different envelope in the post (bottom) image means target.lra is set too low and loudnorm is compressing dynamics to fit.

Diff image (_diff_spectrogram.png, _diff_waveform.png) #

Absolute pixel difference between pre and post, contrast-amplified and saturation-boosted. Black = no change. Bright = change.

[pre][post] → blend=difference → curves (12% maps to 100%) → hue=s=6

The mastering report

Written to <out_dir>/<stem>/<stem><suffix>_report.json after every master run.

{
  "generated_at": "2024-01-15T10:23:44Z",
  "input_file": "track.wav",
  "output_file": "mastered/track/track_master.wav",
  "preset": { ... full preset config ... },
  "pre_analysis": {
    "integrated_lufs": -18.4,
    "true_peak_dbtp": -2.1,
    "loudness_range_lu": 14.6,
    "extended": {
      "rms_dbfs": -22.1,
      "crest_factor_db": 20.0,
      "dynamic_range_dr": 17.0,
      "dc_offset": 0.00012,
      "phase_correlation": 0.74,
      "spectral_balance": { "low_pct": 38.2, "mid_pct": 44.1, "high_pct": 17.7 },
      "spectral_centroid_hz": 1420.0
    }
  },
  "post_analysis": { ... same structure ... },
  "filter_chain": "highpass=f=20.0,alimiter=...,loudnorm=...",
  "delta": {
    "lufs_change": 2.4,
    "true_peak_change": 1.8,
    "lra_change": -0.3,
    "crest_factor_change": -0.2
  }
}

The filter_chain field contains the exact string passed to FFmpeg. A master is fully reproducible:

ffmpeg -i input.wav -af "<filter_chain>" -acodec pcm_s24le -ar 44100 output.wav

Extending the pipeline

Adding a filter stage #

Four changes across two files. Example: adding a configurable high-shelf EQ.

pub struct Filters {
    pub highpass_hz:   f32,
    pub lowpass_hz:    f32,
    pub high_shelf_db: f32,   // new field
}

filters: Filters {
    highpass_hz:   20.0,
    lowpass_hz:    0.0,
    high_shelf_db: 0.0,   // 0 = disabled by convention
},

if preset.filters.high_shelf_db != 0.0 {
    filters.push(format!(
        "treble=g={:.1}:f=8000",
        preset.filters.high_shelf_db
    ));
}

[filters]
highpass_hz   = 20.0
lowpass_hz    = 0.0
high_shelf_db = 1.5   # gentle high shelf boost

Useful FFmpeg audio filters #

Full reference: ffmpeg.org/ffmpeg-filters.html

# Parametric EQ band
equalizer=f=1000:width_type=o:width=2:g=-3.0

# High shelf boost
treble=g=2.0:f=8000

# Low shelf boost
bass=g=1.0:f=100

# Stereo widening
extrastereo=m=1.5

# Noise gate
agate=threshold=-40dB:ratio=2:attack=20:release=250

# M/S encode
pan=stereo|c0=0.5*c0+0.5*c1|c1=0.5*c0-0.5*c1

# Static gain
volume=2dB

AI integration

matchering — reference-based mastering #

matchering analyzes a reference track and applies its spectral and loudness character to your track. Run it as a pre-pass before mastacraf.

pip install matchering

python3 << 'EOF'
import matchering as mg
mg.process(
    target='track.wav',
    reference='reference.wav',
    results=[mg.Result('track_matched.wav', use_limiter=False)]
)
EOF

mastacraf master track_matched.wav --preset default

Pass use_limiter=False to matchering. mastacraf's limiter handles the peak ceiling.

demucs — source separation #

demucs separates stems. For mastering experimental music this is primarily useful for analysis — inspecting spectral and dynamic character of individual elements before mastering decisions.

pip install demucs
python3 -m demucs --two-stems=vocals track.wav
# examine separated/ directory
mastacraf master track.wav --preset default

Bundling (Tauri)

When you are ready to wrap mastacraf in a desktop UI via Tauri:

1. mastacraf as a Tauri sidecar

"bundle": {
  "externalBin": ["../mastacraf/target/release/mastacraf"]
}

2. FFmpeg as a sidecar

Use the ffmpeg-sidecar crate for automatic platform-specific FFmpeg download on first run:

ffmpeg-sidecar = "1.1"

Update src/ffmpeg.rs to check the sidecar path before the $PATH lookup.

3. Preset resolution

The preset loader already searches <exe_dir>/presets/. Bundle your .toml files there and they resolve automatically.

4. Frontend interface

The Tauri frontend calls the sidecar, waits for exit, and reads the JSON report from the output directory. No additional IPC beyond filesystem reads is needed for the initial UI.

Troubleshooting