# TV Normalizer

A macOS menu bar app that runs everything your Mac plays through the free
**GVST GMax** limiter, so quiet speech comes up and loud peaks stay under a
fixed ceiling. Audio is processed live on your Mac. Nothing is recorded or
uploaded.

Guide: https://paymenottowork.com/done/tv-normalizer/

## You need

- macOS with the Xcode Command Line Tools (`xcode-select --install`).
- **VB-Cable** from VB-Audio: https://vb-audio.com/Cable/
- **GMax** for Mac from GVST: https://gvst.uk/Downloads/GMax
  Put `GMax.vst` in `~/Library/Audio/Plug-Ins/VST/`.

GMax and VB-Cable are not included. Their licenses only allow their makers to
distribute them, so download them from the links above.

## Build

```sh
zsh build.sh
```

This builds `~/Applications/TV Normalizer.app`. Pass a different path to build
somewhere else. The build needs only the system frameworks: Cocoa, Core Audio,
Audio Unit and AVFoundation.

Check that GMax loads and limits correctly. This processes test tones in memory
and plays nothing:

```sh
"$HOME/Applications/TV Normalizer.app/Contents/MacOS/TVNormalizer" --self-test
```

A pass prints a gain of about 12 dB and a peak of 0.966051, the −0.3 dB ceiling.

## Use

Open the app. **GMax ON / GMax OFF** appears in the menu bar.

- **Enable / Disable normalization** switches between GMax and direct output.
- **Volume boost** sets 0 to 24 dB in 3 dB steps. The default is +12 dB.
- **Launch at login** adds or removes a login item.
- **Quit and restore audio** quits and puts your speakers back.

macOS asks for microphone permission the first time. VB-Cable counts as an
audio input, which is how the app receives your Mac's sound; it never uses your
microphone.

To change speakers, disable normalization, pick the new output in System
Settings → Sound, then enable it again.

## How it works

Enabling saves your current output, makes VB-Cable the default output, and
plays VB-Cable's signal through GMax to the saved output. Two Core Audio HAL
units do the capture and playback, joined by a 32 ms ring buffer with slow
resampling to absorb clock drift between the two devices. GMax adds 1 ms of
lookahead. The audio callbacks allocate no memory and do no file or network
work. GMax runs with a −0.3 dB ceiling and 0.5 second release.

A separate watchdog process restores your output if the app quits unexpectedly,
and the next launch checks a saved recovery record. Sleep, a changed output or
sample rate, or stalled audio switches back to direct output.

Diagnostics go to `~/Library/Application Support/TV Normalizer/status.json`
once a second: counters, peak levels and settings, never audio.

Other commands: `--devices` lists audio devices, `--restore` restores the saved
routing (quit the app first), and `--route-test` runs a short live routing test.

## License

TV Normalizer is MIT licensed; see LICENSE. GMax is © Graham Yeadon (GVST).
VB-Cable is © VB-Audio Software.
