Dolphin

A Windows audio volume limiter that automatically reduces system volume when audio exceeds a configurable threshold, protecting against sudden loud sounds.

Features

• Automatic volume limiting with configurable threshold
• Real-time audio peak monitoring via Windows Audio Session API (WASAPI)
• Compressor-style attack/release/hold timing controls
• Soft-knee limiting with adjustable leeway (dB)
• Stabilizer mode for dynamic leeway adjustment
• Dark/Light mode toggle
• Mini Mode toggle (compact window + always on top)
• Global hotkeys (Ctrl+Alt+Up/Down adjust Volume Cap, Ctrl+Alt+Y toggles enabled)
• System tray integration with minimize-to-tray support (requires pystray + Pillow)
• Windows startup integration (can start minimized when tray support is available)
• Persistent settings stored in %APPDATA%\dolphin\settings.json

Installation

Pre-built Executable

Download Dolphin.exe from the Releases page.

Build from Source

# Clone the repository
git clone https://github.com/FaintWhisper/Dolphin.git
cd Dolphin

# Run setup (creates venv, installs dependencies, configures git hooks)
setup.bat

# Activate virtual environment
venv\Scripts\activate.bat

# Run directly
python dolphin.py

# Build standalone executable
build.bat

Requirements

• Windows 10/11
• Python 3.8+ (for running from source)

Usage

1. Launch Dolphin.exe or run python dolphin.py
2. Adjust the Volume Cap slider to set your maximum output level (default: 20%)
3. The limiter monitors audio in real-time and reduces volume when peaks exceed the threshold
4. Close the window to minimize to system tray (configurable; only when tray support is available)

Mini Mode

Use the Mini Mode toggle to switch to a compact always-on-top window. The compact layout now keeps abbreviated audio (A), system (S), and threshold (T) readouts in view so you can watch the limiter state at a glance.

Global Hotkeys

• Ctrl+Alt+Plus (+) / Numpad+: Increase Volume Cap by 1%
• Ctrl+Alt+Minus (-) / Numpad-: Decrease Volume Cap by 1%
• Ctrl+Alt+Y: Toggle limiter enabled/disabled

Configuration

Basic Settings

Setting	Description	Default
Volume Cap	Maximum allowed output level (0-100%)	20%
Dark Mode	Enable dark theme (light theme available)	On
Run at Windows startup	Auto-start Dolphin when Windows boots	Off
Minimize to tray on close	Hide to tray instead of exiting (requires tray support; otherwise forced off)	On

Advanced Limiter Settings

Parameter	Description	Default	Range
Attack	Time audio must exceed threshold before limiting	50ms	1-100ms
Release	Time to restore volume after audio drops below threshold	500ms	100-3000ms
Hold	Delay before release begins after audio drops	150ms	0-500ms
Cooldown	Pause duration after manual volume adjustment	2.0s	0.5-5.0s
Leeway	Soft-knee range above threshold (dB)	3.0dB	0-12dB
Dampening	Maximum reduction multiplier for sustained peaks	1.0x	1.0-3.0x
Dampening Speed	Time to reach maximum dampening	0.0s	0-5s

Stabilizer Mode

The Stabilizer automatically adjusts the leeway (soft-knee) based on how frequently the audio limiter is triggering:

Parameter	Description	Default	Range
Enable	Toggle stabilizer on/off	Off	-
Window	Time window to track volume changes (seconds)	5.0s	1-30s
Count	Number of limiting triggers to increase leeway	5	2-20
Change	Minimum volume change to count as a trigger (%)	5%	1-20%
Max	Maximum leeway the stabilizer can reach (dB)	12.0dB	3-20dB
Step	dB increase/decrease per adjustment	1.0dB	0.5-3.0dB

How it works:

• If audio exceeds the threshold frequently (5+ times in 5s), the stabilizer increases leeway to reduce excessive limiting
• When triggers decrease, leeway gradually returns to its base value
• Useful for content with dynamic peaks (music, podcasts, gaming)

How the Limiter Works

1. Peak Detection: Monitors system audio output using IAudioMeterInformation from WASAPI
2. Threshold Check: Calculates potential output level based on current peak and system volume
3. Attack Phase: When audio exceeds threshold, waits for sustained peak (attack time) before limiting
4. Limiting: Reduces system volume proportionally, applying leeway curve and dampening factor
5. Hold Phase: After audio drops below threshold, maintains reduced volume for hold duration
6. Release Phase: Gradually restores volume to original level over release time

The limiter respects manual volume changes by pausing automatic control for the configured cooldown period.

Technical Details

Architecture

• Audio Interface: Windows Core Audio API (WASAPI) via pycaw
  • IAudioEndpointVolume for system volume control
  • IAudioMeterInformation for real-time peak metering
• GUI Framework: tkinter with custom toggle switch widgets and theme support
  • Dark mode: #1e1e1e background with light text (default)
  • Light mode: #f5f5f5 background with dark text
  • Real-time theme switching with persistent preferences
• System Tray: pystray with PIL for icon generation (optional; if not installed, tray/minimize features are disabled)
• Packaging: PyInstaller single-file executable

Dependencies

pycaw>=20230407      # Windows Core Audio Python bindings
comtypes>=1.2.0      # COM interface support
numpy>=1.24.0        # Numerical operations
pystray>=0.19.0      # System tray integration
Pillow>=10.0.0       # Image processing for tray icon
pyinstaller>=6.0.0   # Executable packaging (build only)

File Structure

Dolphin/
├── dolphin.py              # Main application with GUI, audio control, and limiter
├── Dolphin.spec            # PyInstaller configuration
├── build.bat               # Build script (builds Dolphin.exe)
├── setup.bat               # Development environment setup & git hooks config
├── requirements.txt        # Python dependencies
├── test_components.py      # Component verification script
├── .github/
│   └── workflows/
│       └── release.yml     # GitHub Actions: auto-build and release on tags
├── .githooks/
│   └── pre-push            # Git hook: verify build before push
└── dist/
    └── Dolphin.exe         # Built executable

Acknowledgments

Inspired by Mufflr by John Tringham (C#/Avalonia).

License

MIT License. No tracking, telemetry, or data collection.