SoundBrake — Hearing Protection

A cross-platform System Tray app for Windows, macOS, and Linux that monitors your speaker/headphone volume and protects your hearing.

SoundBrake sits silently in your system tray, watching your output volume in real time. When you've been listening too loud for too long, it sends a native desktop notification — and at critical levels it automatically lowers the volume to protect your hearing.

Download

Pre-built installers are available on the Releases page:

Platform	File
Windows	`SoundBrake-Setup-x.x.x.exe` (Inno Setup installer)
macOS	`SoundBrake-x.x.x.dmg` (disk image)
Linux	`soundbrake_x.x.x_amd64.deb` / `soundbrake-x.x.x-1.x86_64.rpm`

Want to build from source? Continue reading.

Windows SmartScreen warning: Because SoundBrake is not yet code-signed, Windows may show an "Unknown publisher" dialog when you run the installer. Click "More info" → "Run anyway" to proceed. If you prefer not to do that, you can build from source with go build and verify the code yourself.

1. Requirements

Tool	Version	Purpose
Go	1.21+	Compilation
Inno Setup	6.x	Windows installer
create-dmg	latest	macOS disk image
fpm	latest	Linux deb/rpm packaging
goversioninfo	latest	Embed icon + version info into Windows EXE
osslsigncode / signtool		Code signing

# goversioninfo (auto-installed by build.bat, or manually:)
go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest

# macOS
brew install create-dmg

# Linux (fpm)
sudo gem install fpm

2. Project Structure

soundbrake/
 main.go
 go.mod
 versioninfo.json          # Windows EXE metadata (icon, version)
 assets/
    icon.ico              # Windows multi-size icon (auto-generated)
    wizard_banner.bmp     # Inno Setup wizard banner (auto-generated)
    wizard_small.bmp      # Inno Setup small image (auto-generated)
    icon.png              # General PNG icon (auto-generated)
    app.manifest          # Windows UAC manifest
 internal/
    audio/                # Platform-specific volume control
    icon/                 # Runtime icon renderer (PNG for tray)
    monitor/              # Core monitoring state machine
    notification/         # Platform-specific notifications
    startup/              # Launch-on-login registration
    tray/                 # System Tray UI
    types/                # Shared type definitions
 setup/
     windows/
        soundbrake.iss    # Inno Setup script
        build.bat        # One-click build + package
     macos/
        build.sh         # .app + .dmg builder
        entitlements.plist
     linux/
         package.sh       # .deb + .rpm builder

3. Building & Running

Install dependencies

go mod tidy

Run directly (development)

go run .

Windows (no console window)

# Quick build
setup\windows\build.bat

# Or manually
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w -H windowsgui" -o soundbrake.exe .

macOS (universal binary)

./setup/macos/build.sh

Linux

./setup/linux/package.sh

4. Windows Installer (Inno Setup)

4.1 Setup

Download and install Inno Setup 6.
Run setup\windows\build.bat. The script will:
- Generate assets/icon.ico, wizard images, and resource.syso (embeds icon + version into EXE),
- Compile the Go binary,
- Produce setup\windows\Output\SoundBrake-Setup-1.0.0.exe with a 12-language wizard.

4.2 Installer Behaviour

Feature	Detail
Install directory	`%ProgramFiles%\SoundBrake` (admin) or `%LocalAppData%\SoundBrake` (user)
Start Menu	SoundBrake shortcut with icon
Desktop shortcut	Optional (checkbox during install)
Control Panel	Appears in Programs list; standard uninstall works
Startup entry	Optional (checkbox during install); app can also toggle this itself
Uninstall	Running process is killed via `taskkill`, registry key is removed

4.3 Languages

The installer wizard supports 12 languages: English, Turkish, German, French, Spanish, Italian, Russian, Portuguese, Dutch, Polish, Japanese, Korean.

The application UI supports an additional 13th language — Chinese (Simplified) — detected automatically via the LANG environment variable on macOS/Linux or by setting HKCU\Software\SoundBrake\Language = chinese on Windows.

5. macOS .dmg Package

brew install create-dmg

# Build with a Developer ID certificate
SIGNING_ID="Developer ID Application: Your Name (TEAMID)" \
  ./setup/macos/build.sh

Output: setup/macos/SoundBrake-1.0.0.dmg

Notarization (required for public distribution)

# Submit to Apple
xcrun notarytool submit setup/macos/SoundBrake-1.0.0.dmg \
  --apple-id "you@example.com" \
  --team-id   "YOURTEAMID" \
  --password  "app-specific-password" \
  --wait

# Staple the ticket after approval
xcrun stapler staple setup/macos/SoundBrake-1.0.0.dmg

6. Linux .deb / .rpm Package

sudo gem install fpm
./setup/linux/package.sh

Output:

setup/linux/soundbrake_1.0.0_amd64.deb
setup/linux/soundbrake-1.0.0-1.x86_64.rpm

Installation

sudo dpkg -i soundbrake_1.0.0_amd64.deb   # Debian / Ubuntu
sudo rpm -i soundbrake-1.0.0-1.x86_64.rpm  # Fedora / RHEL

# Remove
sudo apt remove soundbrake   # Debian
sudo rpm -e soundbrake        # Fedora

7. Code Signing

Windows

The build script uses signtool (from the Windows SDK) if a certificate is available. To sign the EXE and installer manually:

signtool sign /fd sha256 /tr http://timestamp.digicert.com /td sha256 ^
  /f "MyCert.pfx" /p "password" soundbrake.exe
signtool sign /fd sha256 /tr http://timestamp.digicert.com /td sha256 ^
  /f "MyCert.pfx" /p "password" setup\windows\Output\SoundBrake-Setup-1.0.0.exe

macOS

Signing and notarization are handled inside setup/macos/build.sh. Set the SIGNING_ID environment variable before running:

SIGNING_ID="Developer ID Application: Your Name (TEAMID)" ./setup/macos/build.sh

After the build, submit for notarization:

xcrun notarytool submit setup/macos/SoundBrake-1.0.0.dmg \
  --apple-id "you@example.com" --team-id "YOURTEAMID" \
  --password "app-specific-password" --wait
xcrun stapler staple setup/macos/SoundBrake-1.0.0.dmg

Linux

Linux packages are not code-signed in the traditional sense. You can sign the .deb with dpkg-sig or .rpm with rpmsign if your distribution requires it.

8. How It Works

SoundBrake uses a poll-based monitor that runs on a background goroutine:

Volume Levels

Level	Volume Range	Warning Trigger	Action
Safe	0–74%	Never	—
Level 1	75–84%	After 60 min sustained	Desktop notification
Level 2	85–94%	After 20 min sustained	Desktop notification
Critical	≥ 95%	After 4 min sustained	Notification + auto-lower volume

The monitor polls the system audio API every 5 seconds.
Exposure time is cumulative: if you listen at Level 2 for 10 minutes, switch to Level 1 for another 10 minutes, the 20 minutes count together.
When the volume drops to Safe or you change audio output device, the exposure timer resets.

Dismiss Backoff

Clicking Dismiss on a notification starts a cooldown before the next warning can fire:

Level 1 / Level 2: 15 minutes initial cooldown, doubling with each consecutive dismiss (capped at 2 hours).
Critical: 10 minutes initial cooldown with the same backoff.

Pressing Silence 24 h from the tray suppresses all warnings for 24 hours; the state is persisted across reboots in %AppData%\SoundBrake\silence.dat (Windows) or ~/.config/SoundBrake/silence.dat (macOS/Linux).

Device Change Detection

The active audio output device is checked every 30 seconds. When a headphone plug/unplug is detected, all exposure and cooldown timers reset so the new device gets a fresh session.

Architecture

main.go
 ├─ singleinstance — prevents duplicate processes (mutex/lock-file)
 ├─ i18n           — auto-detects OS language (13 locales)
 ├─ startup        — registers/removes launch-on-login entry
 ├─ monitor        — polls audio, manages state machine, fires notifications
 │    ├─ audio/    — platform-specific volume read/write (WASAPI · osascript · pactl)
 │    └─ notification/ — platform-specific desktop notification
 └─ tray           — system tray icon, menu items, reacts to monitor state

Logs

Logs are written to:

Windows: %AppData%\SoundBrake\soundbrake.log
macOS / Linux: ~/.config/SoundBrake/soundbrake.log

The log file is rotated at 5 MB (renamed to soundbrake.log.old).

9. Contributing

Contributions are welcome! Please read CONTRIBUTING.md for:

Development environment setup
Code conventions
How to submit a pull request

For bug reports or feature requests, open an issue using the appropriate template:

License

SoundBrake is released under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
assets		assets
internal		internal
setup		setup
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
versioninfo.json		versioninfo.json

Folders and files

Latest commit

History

Repository files navigation

SoundBrake — Hearing Protection

Download

Table of Contents

1. Requirements

2. Project Structure

3. Building & Running

Install dependencies

Run directly (development)

Windows (no console window)

macOS (universal binary)

Linux

4. Windows Installer (Inno Setup)

4.1 Setup

4.2 Installer Behaviour

4.3 Languages

5. macOS .dmg Package

Notarization (required for public distribution)

6. Linux .deb / .rpm Package

Installation

7. Code Signing

Windows

macOS

Linux

8. How It Works

Volume Levels

Dismiss Backoff

Device Change Detection

Architecture

Logs

9. Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages