Process Web Audio

A local-first batch utility for preparing audio for the web.

Process Web Audio matches loudness, standardizes delivery settings, cleans up filenames, and exports consistent MP3 files without modifying the originals. It is useful for podcasters, sound designers, SFX libraries, and anyone publishing audio online.

For mastered work, use it as a final web-delivery pass while keeping your high-quality WAV masters intact.

Agent skill

This repository is also an installable agent skill for Codex, Claude Code, Cursor, and other compatible coding agents.

npx skills add chairs44/process-web-audio --skill process-web-audio

The skill gives an agent the delivery standard, safety guardrails, and QC workflow. The command-line utility remains useful on its own.

What it does

• Accepts individual files, multiple files, or folders recursively.
• Reads WAV, AIFF, FLAC, MP3, M4A, AAC, OGG, and Opus.
• Uses FFmpeg two-pass loudness normalization.
• Targets -16 LUFS integrated loudness.
• Uses -2.0 dBTP processing headroom and verifies the final MP3 against a -1.5 dBTP ceiling.
• Exports 44.1 kHz stereo MP3 at 192 kbps.
• Converts output names to lowercase kebab-case.
• Optionally writes a CSV report with source, loudness, peak, and QC data.
• Never renames, moves, or overwrites source files.

macOS app

A graphical version is available through the Glaze Store:

Install Process Web Audio for macOS

The app provides file and folder selection, output and naming controls, optional CSV reporting, batch progress, and per-file quality-control results without requiring Terminal knowledge.

App requirements:

• Apple Silicon Mac
• macOS Tahoe
• Glaze installed and signed in
• FFmpeg and FFprobe installed with brew install ffmpeg

The Glaze app runs the processing workflow locally. Audio is never uploaded and source files are not modified. This release is distributed through Glaze and is not currently offered as a standalone DMG.

The command-line and Raycast versions below remain available for people who do not use Glaze.

Command-line requirements

• macOS or Linux
• Bash
• FFmpeg and FFprobe
• jq
• iconv

On macOS with Homebrew:

brew install ffmpeg jq

On Ubuntu or Debian:

sudo apt-get update
sudo apt-get install ffmpeg jq

Install

git clone https://github.com/chairs44/process-web-audio.git
cd process-web-audio
chmod +x process-web-audio.sh

For development or direct use of the bundled implementation:

chmod +x scripts/process-web-audio.sh

Use

Process one file:

./process-web-audio.sh \
  --output "./processed-audio" \
  "./source-audio/interview.wav"

Process several files:

./process-web-audio.sh \
  --output "./processed-audio" \
  "./clip-one.wav" \
  "./clip-two.aiff"

Process every supported file in a folder:

./process-web-audio.sh \
  --output "./processed-audio" \
  "./source-audio"

If --output is omitted, files are written to ./processed-web-audio.

Options

-o, --output DIR  Choose the output directory
    --overwrite   Replace existing processed files
    --report      Write loudness-report.csv (default)
    --no-report   Do not write a CSV report
    --version     Show the installed version
-h, --help        Show help

Existing outputs are preserved unless --overwrite is provided.

Quality-control report

The CSV report records the source format, input loudness, input true peak, final MP3 loudness, final true peak, output size, and a qc_status.

• pass: within 0.5 LU of the target and at or below the true-peak ceiling.
• review: outside either boundary. The file is preserved so it can be auditioned and handled editorially.

Some very short or highly dynamic sounds should not be heavily compressed just to force a numeric target. A review result is a prompt to listen, not necessarily a failure.

Optional: Raycast on macOS

The included Raycast Script Command processes audio selected in Finder.

1. Clone this repository.
2. Open Raycast Settings → Extensions → Script Commands.
3. Choose Add Script Directory.
4. Select the repository's raycast folder.
5. In Finder, select one audio folder or one or more audio files.
6. Open Raycast and run Process Web Audio.

Raycast may request permission to control Finder the first time. The command writes processed files to a sibling processed-web-audio folder.

The Terminal workflow remains the primary interface and gives you explicit control over output paths and options.

Advanced targets

The defaults can be overridden with environment variables:

TARGET_I=-14 \
PROCESS_TP=-2.0 \
FINAL_TP_LIMIT=-1.5 \
TARGET_LRA=11 \
OUTPUT_RATE=44100 \
OUTPUT_BITRATE=192k \
./process-web-audio.sh --output "./processed-audio" "./source-audio"

Scope

This tool is a delivery utility, not a mastering system. It does not apply EQ, noise reduction, creative compression, restoration, or other content-aware processing. Sources with more than two channels are rejected.

Development

Run the smoke test after changing the processor:

./tests/smoke-test.sh

The root process-web-audio.sh is kept as a compatibility entrypoint for Terminal and Raycast users. scripts/process-web-audio.sh is the canonical implementation bundled with the agent skill.

About

Built by David Sutrin.

License

MIT