Skip to content
projects

systems + tooling

Headphone Safety

Brings iOS's 'Reduce Loud Sounds' to macOS, Linux, Windows, and Android: a real-time peak limiter, not just a volume cap.

source

about

A volume cap alone does not protect hearing, because transients blow straight past it. This runs an actual peak-limiting signal processor in the audio path on four platforms, each through its native audio stack: CoreAudio on macOS, PipeWire on Linux, WASAPI on Windows, and DynamicsProcessing on Android. The macOS build routes audio through BlackHole, a virtual loopback driver, with watchdog and rollback logic that restores safe output within one second of a device disconnect, and a startup recovery check that guards against unclean crashes.

4

platforms

<1s

failsafe recovery

5

headroom presets

stack

  • Swift
  • Rust
  • C++
  • Kotlin
  • CoreAudio
  • PipeWire
  • WASAPI

how it works

  1. 1

    Detect

    Protection engages only when headphones - wired or Bluetooth - are the active output.

  2. 2

    Capture

    System audio is routed through a loopback on each platform: BlackHole on macOS, a PipeWire virtual sink on Linux, WASAPI loopback with a virtual cable on Windows.

  3. 3

    Limit

    A true-peak limiter caps the signal at a chosen headroom below full scale: Apple's PeakLimiter Audio Unit on macOS, ZaMaximX2 through LADSPA on Linux.

  4. 4

    Output

    The limited signal plays on the real headphone device, with tens of milliseconds of latency.

engineering notes

Measured, not assumed

On Windows, a 0 dBFS input came out at -9.9 dB with a 10 dB headroom setting, on real Bluetooth headphones. On Linux, a -1.1 dB tone came out at -10.1 dB against a -10 dB ceiling.

Recovery that cannot hang

Unplugging headphones mid-playback reverts output to a safe device within about a second, and a startup check undoes stray routing after a crash. Recovery never queries the disconnecting device, because those CoreAudio calls were observed to block indefinitely.

Research before code

Each port started with a written architecture study. The first Windows design, an Audio Processing Object, registered correctly but was never loaded by audiodg.exe - so what ships is a WASAPI-loopback design instead, and the study records why.

known limits

  • Android has no public API for a system-wide limiter: the Volume Cap works fully, the limiter covers apps per-app at a fixed, device-set ceiling.