简体中文 · English · 日本語

VolumeGuard · Volume Limit Protection for macOS

Put a ceiling on your Mac's volume.

VolumeGuard is a free, open-source, native macOS menu bar app. It sets a maximum volume for the default output device, preventing sudden increases caused by accidental repeated input from a keyboard volume wheel, volume key, or headphone control.

For standard volume-up events, it does not wait until the volume has exceeded the limit and then turn it back down. Whenever possible, VolumeGuard determines whether the next increase would cross the limit before macOS raises the volume: within the safe range, it preserves the system's native behavior; at the boundary, it intercepts further increases and displays a clear notification.

Demo

Adjust the maximum volume, then keep increasing the system volume. When the limit is reached, VolumeGuard intercepts further increases and displays a notification.

Key Features

• Set a custom maximum volume from 10% to 100%, with quick presets for 30%, 40%, and 50%.
• Supports standard volume keys, as well as keyboard wheels and headphone controls that send standard media-key events.
• Intercepts only volume increases that could cross the limit; volume down, mute, and other keys are unaffected.
• Preserves native macOS volume adjustment and the system HUD within the safe range.
• Displays a lightweight notification when the limit is reached without stealing focus from the current window.
• Uses Core Audio to monitor the default output device's software master volume and pull it back after an external change crosses the limit.
• Shows the current volume, default output device, and protection status in the menu bar in real time.
• Supports launch at login and persistent settings.
• Supports instant switching between English, 中文, and 日本語; English is the default.
• Built natively in Swift, with no account, subscription, ads, or network services.

Why It Does More Than “Turn It Back Down Afterward”

A typical volume-monitoring approach can only pull the volume back to the limit after the system volume has already increased. With rapid, repeated input from a scroll wheel, the sound can still spike briefly.

VolumeGuard combines preemptive protection with fallback correction:

1. Preemptive interception: An active CGEventTap captures standard volume-up events and, whenever possible, decides whether to pass or intercept them before macOS processes them by default.
2. Core Audio fallback correction: It monitors the writable software master volume of the default output device and pulls it back to the limit after Control Center, scripts, or another path has already pushed it too high.

Within the safe range, the original event is handed straight back to macOS, preserving the system volume HUD and native feel. VolumeGuard blocks further increases only when the next step would cross the limit or the volume is already at the maximum.

Technical Implementation

flowchart LR
    A["Standard volume keys / media-key wheels"] --> B["CGEventTap pre-filter"]
    B --> C["VolumeUpGate predicts the next step"]
    C -->|"Below the limit"| D["Pass the original event"]
    D --> E["Native macOS adjustment + HUD"]
    C -->|"Would cross the limit"| F["Intercept the event"]
    F --> G["Hold at the limit + show notification"]

    H["Control Center / scripts"] --> I["Core Audio monitors software master volume"]
    I --> J["Post-change fallback correction"]

Loading

Component	Role
MediaKeyInterceptor	Uses an active CGEventTap to capture standard media keys and applies the interception policy only to volume increases.
VolumeUpGate	Predicts the next volume change in memory and reserves headroom for rapid consecutive events generated by a scroll wheel.
AudioDeviceController	Uses Core Audio to read, monitor, and constrain the volume of the default output device.
VolumeLimiterService	Coordinates event interception, audio devices, protection state, launch at login, and settings.
LimitReachedHUDController	Uses a non-activating NSPanel to show limit-reached feedback without interrupting the current task.

The limit check inside the event callback runs entirely in memory and performs no Core Audio I/O. During rapid scrolling, the gate tracks events that have already been allowed through but are not yet reflected in the system volume, preventing multiple rapid inputs from being granted the same remaining headroom.

Supported Scenarios

VolumeGuard is not tied to any particular keyboard brand. Standard volume keys, keyboard wheels, and some headphone controls all use the same preemptive check as long as they ultimately produce standard macOS volume media-key events.

Control Center, AppleScript, and similar methods do not go through the media-key path. If their changes are reflected in the default output device's software master volume and cross the limit, Core Audio pulls the volume back after the change occurs.

Installation

1. Download the newest available package from the repository's Releases page.
2. Move VolumeGuard.app to the Applications folder and launch it.
3. Once launched, VolumeGuard remains available in the menu bar.

The current GitHub package is an ad-hoc-signed, unnotarized Preview, so macOS blocks its first launch by default. If you trust this repository and have verified the published SHA-256, try opening the app once, then use System Settings → Privacy & Security → Open Anyway, following Apple's per-app override instructions. Do not disable Gatekeeper globally.

Usage

1. Launch VolumeGuard and click the shield-and-volume icon in the menu bar.
2. Enable the volume limit and choose an appropriate maximum volume.
3. When prompted on first launch, grant Accessibility permission in macOS.
4. Continue using your volume keys or scroll wheel as usual. Once the limit is reached, further standard media-key events that would increase the volume are intercepted.

System Requirements

• Build target: macOS 14.0 or later.
• The Universal build includes arm64 and x86_64.
• The default output device must expose writable software master-volume control.

Building from Source

Requires Xcode and XcodeGen:

xcodegen generate
open VolumeGuard.xcodeproj

Run the tests:

xcodebuild test \
  -project VolumeGuard.xcodeproj \
  -scheme VolumeGuard \
  -destination 'platform=macOS,arch=arm64' \
  CODE_SIGNING_ALLOWED=NO

The project includes automated XCTest coverage for volume boundaries, rapid consecutive input, event pairing, device monitoring, protection state, invalid settings, the limit-reached notification policy, and localization in all three languages.

License

VolumeGuard is released under the MIT License.