What Volume Range Does Vorssaint-Utils’ Audio Mixer Support?

Vorssaint-Utils’ audio mixer supports a normalized volume range of 0.0 to 2.0, where 0.0 represents complete silence, 1.0 is the default 100% passthrough, and 2.0 provides a 200% boost for quiet sources.

The vorssaint-utils library provides a per-application audio mixer for macOS that normalizes volume control to a specific numeric scale. Unlike traditional audio APIs that may use decibels or arbitrary scales, this open-source utility defines a clear volume range that supports both attenuation and amplification. According to the source code in the vorssaint/vorssaint-utils repository, the mixer operates on a 0.0 to 2.0 scale, allowing developers to silence apps completely or boost quiet sources up to 200% of their original level.

Understanding the Normalized Volume Scale

The audio mixer in vorssaint-utils uses a floating-point range where each value has a specific acoustic meaning:

• 0.0 – Complete silence. This mutes the application entirely.
• 1.0 – Default passthrough. The audio plays at its original 100% level with no gain adjustment applied.
• 2.0 – Maximum boost. This represents a 200% volume increase for sources that play too quietly.

This normalized volume range provides headroom beyond standard unity gain, which is particularly useful when dealing with quiet video conferencing tools or legacy applications with low output levels.

Implementation in the Source Code

The enforcement of this range appears in two critical locations within the codebase.

Maximum Volume Constant in AppVolumeMixer.swift

In Sources/Vorssaint/Services/Audio/AppVolumeMixer.swift, the library declares the upper boundary as a static constant. Lines 73–75 define the maxVolume property and document the intended behavior:

/// Volumes run 0...2: 1.0 is 100% (untouched passthrough), up to 2.0 is a
/// 200% boost for sources that play too quietly.
static let maxVolume: Double = 2.0

This constant establishes the contract for the volume range supported by vorssaint-utils' audio mixer, ensuring that no component within the library attempts to apply gain beyond 200%.

Input Validation in Defaults.swift

To prevent invalid values from corrupting the audio pipeline, Sources/Vorssaint/Core/Defaults.swift implements a sanitization function. The sanitizedAppVolume(_:) method, found at lines 34–37, clamps any incoming double to the valid range:

static func sanitizedAppVolume(_ volume: Double) -> Double {
    guard volume.isFinite else { return 1 }
    return min(max(volume, 0), 2)
}

This utility function guarantees that even if a caller passes a negative number or a value exceeding 2.0, the mixer receives a clamped value between 0 and 2. Values outside this range are automatically corrected to the nearest boundary.

Practical Usage Examples

When integrating the AppVolumeMixer into your macOS application, you interact with this volume range through the shared instance. The following Swift examples demonstrate how to set volumes safely within the 0.0–2.0 boundaries:

import Vorssaint

// Access the shared mixer instance
let mixer = AppVolumeMixer.shared

// Set system output to 75% (0.75)
mixer.setCurrentOutputVolume(0.75)

// Apply maximum 200% boost to a specific application
if let firstApp = mixer.apps.first {
    mixer.setVolume(2.0, for: firstApp)  // Maximum allowed value
}

// Attempting to exceed the range triggers automatic clamping
mixer.setVolume(3.5, for: firstApp)      // Internally treated as 2.0

Because the sanitizedAppVolume function runs on all inputs, your application can safely accept user-defined volume levels without manual range checking. The library automatically handles edge cases, converting infinite or NaN values to the default 1.0 passthrough level.

Summary

• Vorssaint-utils defines a volume range of 0.0 to 2.0 for its per-app audio mixer.
• 0.0 mutes the source completely, while 2.0 applies a 200% boost.
• The maxVolume constant in AppVolumeMixer.swift hard-codes the upper limit of 2.0.
• sanitizedAppVolume(_:) in Defaults.swift enforces these boundaries by clamping out-of-range values.
• All inputs are automatically validated, preventing crashes from invalid floating-point numbers.

Frequently Asked Questions

What happens if I set a volume above 2.0 in vorssaint-utils?

The sanitizedAppVolume function in Sources/Vorssaint/Core/Defaults.swift automatically clamps the value to 2.0. If your code calls setVolume(3.5, for: app), the mixer internally treats this as 2.0, preventing distortion or digital clipping from excessive gain.

Is 1.0 equivalent to the system's volume level?

A value of 1.0 represents 100% passthrough with no gain adjustment applied by the mixer. However, this operates independently of the macOS system volume. The AppVolumeMixer applies its multiplier to the application’s audio stream before it reaches the system output, meaning 1.0 plays the app at its natural level relative to the current system volume setting.

How do I completely mute an application using the audio mixer?

Set the volume parameter to 0.0. This represents complete silence in the vorssaint-utils volume range. You can implement this via mixer.setVolume(0.0, for: targetApp), which will effectively mute that specific application while leaving others unaffected.

Why does vorssaint-utils support volume values above 1.0?

The 0.0–2.0 range provides headroom for audio boosting. Many applications, particularly older software or certain video conferencing tools, output signals that are too quiet even at 100% system volume. The ability to set values up to 2.0 allows the mixer to amplify these quiet sources up to 200% of their original level, ensuring consistent loudness across all running applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}