# Vorssaint Audio Mixer Permission: System Audio Recording Requirements

> Discover the System Audio Recording permission Vorssaint needs to capture and route app audio streams on macOS. Learn about its audioCapture flag.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-06

---

**Vorssaint requires the System Audio Recording permission (internally flagged as `audioCapture`) for its audio mixer to intercept and route application audio streams on macOS.**

The vorssaint-utils repository provides a sophisticated audio routing system that relies on specific macOS entitlements to function. When users enable per-application volume controls, the audio mixer must first obtain system-level authorization to tap into audio streams. Without this permission, the mixer cannot apply independent volume adjustments or routing logic, forcing the application to fall back to the default audio path.

## Understanding the System Audio Recording Permission

macOS guards access to system audio through the **System Audio Recording** permission, which controls whether applications can capture output from other apps. This permission appears in the **Audio Capture** feature flag within the Vorssaint codebase. The [`docs/PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/PERMISSIONS.md) file documents that this gate protects all audio tap functionality, ensuring users explicitly consent before the mixer can monitor application sound output.

## Implementation in the Vorssaint Codebase

### Permission Documentation

According to [`docs/PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/PERMISSIONS.md), the System Audio Recording permission is the primary security barrier protecting audio taps. This documentation explains that granting this permission allows the Vorssaint audio mixer to create per-application volume controls and custom routing chains.

### Feature Flag Architecture

The codebase exposes audio capture functionality through a dedicated feature flag. In [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift), unit tests verify that the mixer is the sole consumer of the `audioCapture` capability using the `activeSet(.audioCapture)` check. This ensures no other components in the vorssaint-utils repository can enable system audio recording without explicitly registering through the feature hub.

The feature registration occurs through the `AppFeature` enumeration:

```swift
// In the feature-flag hub the mixer is the only component that
// registers for `.audioCapture`.
enum AppFeature: String, CaseIterable {
    case mixer          // ↳ System audio capture
    case screenRecorder // ↳ Microphone + video
    // …
}

```

### Entitlement Declaration

The `Resources/Vorssaint.entitlements` file declares the necessary entitlement that macOS requires for audio-capture access. This plist entry works in conjunction with the runtime permission request to satisfy both compile-time and system-level security requirements.

## Requesting Audio Capture Permission

When users toggle "Capture System Audio" in the Volume Mixer settings, the application triggers a permission request through `AVAudioSession`. The following implementation from the Vorssaint UI layer handles the authorization flow:

```swift
// Request the System Audio Recording permission when the user enables
// “Capture System Audio” in the Volume Mixer settings.
import AVFoundation

func requestSystemAudioPermission(completion: @escaping (Bool) -> Void) {
    let audioPerm = AVAudioSession.sharedInstance()
    audioPerm.requestRecordPermission { granted in
        // macOS treats system‑audio taps as an “audio capture” permission.
        completion(granted)
    }
}

// Example usage in the Mixer UI
if userWantsSystemAudio {
    requestSystemAudioPermission { granted in
        if granted {
            Mixer.shared.enableSystemAudioCapture()
        } else {
            // Fallback: keep using the default system audio path
            Mixer.shared.disableSystemAudioCapture()
        }
    }
}

```

This pattern ensures the mixer only attempts to tap audio streams after the user explicitly grants the System Audio Recording permission.

## Enabling the Audio Mixer

Once permission is granted, the mixer activates its capture capability through the singleton interface. The `Mixer.shared.enableSystemAudioCapture()` method initializes the audio tap infrastructure, while `Mixer.shared.disableSystemAudioCapture()` provides a clean fallback when permission is denied or revoked. Settings persistence and UI state management are handled in the settings layer, likely within files such as [`Sources/Vorssaint/UI/Settings/AudioCaptureSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/AudioCaptureSettings.swift).

## Summary

- **System Audio Recording** is the macOS permission required for Vorssaint's audio mixer to capture streams.
- The feature is internally flagged as **`audioCapture`** and verified in [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) to ensure exclusive mixer usage.
- **[`docs/PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/PERMISSIONS.md)** documents the permission requirements and security implications.
- **`Resources/Vorssaint.entitlements`** declares the necessary entitlement for system-level audio access.
- The permission request flow uses **`AVAudioSession`** to prompt users, with fallback logic that disables capture if denied.

## Frequently Asked Questions

### What permission does Vorssaint need for its audio mixer to capture audio streams?

Vorssaint requires the **System Audio Recording** permission from macOS, which the codebase references as the **audioCapture** feature. This permission allows the mixer to tap into application audio output for per-app volume control and routing.

### Which source files define the audio capture permission logic?

The permission logic spans four key locations: [`docs/PERMISSIONS.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/PERMISSIONS.md) contains the documentation, [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) validates the `activeSet(.audioCapture)` usage, `Resources/Vorssaint.entitlements` declares the system entitlement, and the UI settings classes (such as [`AudioCaptureSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/AudioCaptureSettings.swift)) handle the user-facing toggle and request flow.

### How does the application behave if the user denies the System Audio Recording permission?

If permission is denied, the Vorssaint audio mixer calls `Mixer.shared.disableSystemAudioCapture()` and falls back to the default system audio path. This ensures the application continues functioning without per-application volume controls, using standard macOS audio routing instead.

### Is the audio capture feature available on all platforms?

The vorssaint-utils implementation targets macOS specifically, as evidenced by the `Vorssaint.entitlements` plist and the use of macOS-specific **System Audio Recording** permission gates. The code structure assumes macOS audio APIs and entitlement requirements.