# abraxas-724/volumecontrol architecture

> Architecture diagram of the GitHub repository abraxas-724/volumecontrol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abraxas-724/volumecontrol
- Repository: https://github.com/abraxas-724/volumecontrol

## Overview

VolumeControl is a macOS menu-bar audio-control app. Its main workflow discovers active audio applications, lets a user enable per-app gain/mute, validates a live Process Tap session, and restores saved settings when eligible applications return. A parallel branch controls system volume and output selection; an advanced, mutually exclusive BlackHole routing test is also documented. The graph includes the principal UI, coordination, audio-session, and routing layers. Some subsystem links rely on README descriptions because their implementation files were not excerpted.

Main entry points: [`Sources/VolumeControl/VolumeControlModel.swift`](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/VolumeControlModel.swift) (Control Model), [`Sources/VolumeControl/Application/ProcessTapVolumeController.swift`](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/ProcessTapVolumeController.swift) (Process Tap Controller), [`Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift`](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift) (BlackHole Router), [`Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift`](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift) (HAL Route Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Menu Bar UI"]
  node_menu["Menu Bar Panel"]
  node_mixer["App Mixer"]
  node_settings["Settings<br/>[SettingsView.swift]"]
end

subgraph group_app["App Coordination"]
  node_model["Control Model"]
  node_discovery["App Discovery"]
  node_headphones["Headphone Policy"]
end

subgraph group_audio["Per-App Audio"]
  node_controller["Process Tap Controller"]
  node_session["Core Audio Session"]
  node_process_hal["Process Audio HAL"]
  node_family["Process Family"]
  node_validation["Session Validation"]
  node_dsp["Realtime PCM DSP<br/>[VolumeControlDSP.c]"]
end

subgraph group_routing["System Audio &amp; Routing"]
  node_system["System Audio Service<br/>[AudioService.swift]"]
  node_device_monitor["Device Monitor"]
  node_device_meta["Device Metadata"]
  node_device_router["BlackHole Router"]
  node_route_devices["Routing Devices"]
  node_route_engine["HAL Route Engine"]
  node_route_validation["Route Validation"]
end

subgraph group_prefs["Preferences &amp; DSP"]
  node_audio_prefs[("Saved App Audio")]
  node_interface_prefs["Interface Preferences"]
  node_interface_store[("Interface Store")]
end

node_user(("User"))

node_user -->|"opens panel"| node_menu
node_menu -.->|"shows controls"| node_mixer
node_mixer -.->|"changes app audio"| node_model
node_settings -->|"configures behavior"| node_model
node_model -->|"refreshes apps"| node_discovery
node_model -->|"enables and restores"| node_controller
node_model -->|"controls system audio"| node_system
node_model -->|"monitors devices"| node_device_monitor
node_model -->|"evaluates switching"| node_headphones
node_model -->|"starts test routing"| node_device_router
node_controller -.->|"creates session"| node_session
node_controller -->|"persists settings"| node_audio_prefs
node_session -->|"uses HAL"| node_process_hal
node_session -->|"uses process grouping"| node_family
node_controller -.->|"validates session"| node_validation
node_device_router -->|"queries and switches"| node_route_devices
node_device_router -.->|"starts engine"| node_route_engine
node_route_engine -->|"uses HAL helpers"| node_process_hal
node_route_engine -->|"renders PCM"| node_dsp
node_route_validation -->|"validates routing"| node_device_router
node_route_validation -->|"uses engine"| node_route_engine
node_device_meta -->|"reads device details"| node_process_hal
node_interface_prefs -.->|"loads and saves"| node_interface_store
node_menu -->|"reads appearance"| node_interface_prefs

click node_menu "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/MenuBarPopoverController.swift"
click node_mixer "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/AppMixerSection.swift"
click node_settings "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/SettingsView.swift"
click node_model "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/VolumeControlModel.swift"
click node_discovery "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/ApplicationDiscovery.swift"
click node_headphones "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/HeadphoneAutoSwitchPolicy.swift"
click node_system "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/AudioService.swift"
click node_device_monitor "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/AudioDeviceMonitor.swift"
click node_device_meta "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/OutputDeviceMetadata.swift"
click node_controller "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/ProcessTapVolumeController.swift"
click node_session "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/CoreAudioProcessSession.swift"
click node_process_hal "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioHAL.swift"
click node_family "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Domain/AudioProcessFamily.swift"
click node_validation "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioValidationRunner.swift"
click node_audio_prefs "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/UserDefaultsAppAudioPreferences.swift"
click node_device_router "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift"
click node_route_devices "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/CoreAudioRoutingDevices.swift"
click node_route_engine "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift"
click node_route_validation "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/AudioRoutingValidationRunner.swift"
click node_interface_prefs "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/InterfacePreferences.swift"
click node_interface_store "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/Preferences/UserDefaultsInterfacePreferences.swift"
click node_dsp "https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControlDSP/VolumeControlDSP.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_menu,node_mixer,node_settings,node_user toneBlue
class node_model,node_discovery,node_headphones toneAmber
class node_controller,node_session,node_process_hal,node_family,node_validation,node_dsp toneMint
class node_system,node_device_monitor,node_device_meta,node_device_router,node_route_devices,node_route_engine,node_route_validation toneRose
class node_audio_prefs,node_interface_prefs,node_interface_store toneIndigo
```

## Components

### Menu Bar UI

- [Menu Bar Panel](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/MenuBarPopoverController.swift): `Sources/VolumeControl/Presentation/MenuBarPopoverController.swift`
- [App Mixer](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/AppMixerSection.swift): `Sources/VolumeControl/Presentation/AppMixerSection.swift`
- [Settings](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Presentation/SettingsView.swift): `Sources/VolumeControl/Presentation/SettingsView.swift`

### App Coordination

- [Control Model](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/VolumeControlModel.swift): `Sources/VolumeControl/VolumeControlModel.swift`
- [App Discovery](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/ApplicationDiscovery.swift): `Sources/VolumeControl/ApplicationDiscovery.swift`
- [Headphone Policy](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/HeadphoneAutoSwitchPolicy.swift): `Sources/VolumeControl/Application/HeadphoneAutoSwitchPolicy.swift`

### Per-App Audio

- [Process Tap Controller](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/ProcessTapVolumeController.swift): `Sources/VolumeControl/Application/ProcessTapVolumeController.swift`
- [Core Audio Session](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/CoreAudioProcessSession.swift): `Sources/VolumeControl/Infrastructure/ProcessAudio/CoreAudioProcessSession.swift`
- [Process Audio HAL](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioHAL.swift): `Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioHAL.swift`
- [Process Family](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Domain/AudioProcessFamily.swift): `Sources/VolumeControl/Domain/AudioProcessFamily.swift`
- [Session Validation](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioValidationRunner.swift): `Sources/VolumeControl/Infrastructure/ProcessAudio/ProcessAudioValidationRunner.swift`
- [Realtime PCM DSP](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControlDSP/VolumeControlDSP.c): `Sources/VolumeControlDSP/VolumeControlDSP.c`

### System Audio & Routing

- [System Audio Service](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/AudioService.swift): `Sources/VolumeControl/AudioService.swift`
- [Device Monitor](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/AudioDeviceMonitor.swift): `Sources/VolumeControl/AudioDeviceMonitor.swift`
- [Device Metadata](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/OutputDeviceMetadata.swift): `Sources/VolumeControl/Infrastructure/OutputDeviceMetadata.swift`
- [BlackHole Router](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift): `Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift`
- [Routing Devices](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/CoreAudioRoutingDevices.swift): `Sources/VolumeControl/Audio/V2/CoreAudioRoutingDevices.swift`
- [HAL Route Engine](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift): `Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift`
- [Route Validation](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/AudioRoutingValidationRunner.swift): `Sources/VolumeControl/Infrastructure/ProcessAudio/AudioRoutingValidationRunner.swift`

### Preferences & DSP

- [Saved App Audio](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/ProcessAudio/UserDefaultsAppAudioPreferences.swift): `Sources/VolumeControl/Infrastructure/ProcessAudio/UserDefaultsAppAudioPreferences.swift`
- [Interface Preferences](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Application/InterfacePreferences.swift): `Sources/VolumeControl/Application/InterfacePreferences.swift`
- [Interface Store](https://github.com/abraxas-724/volumecontrol/blob/main/Sources/VolumeControl/Infrastructure/Preferences/UserDefaultsInterfacePreferences.swift): `Sources/VolumeControl/Infrastructure/Preferences/UserDefaultsInterfacePreferences.swift`

### Other components

- **User**

## Connections

- User → Menu Bar Panel: opens panel (evidence: `README.md`)
- Menu Bar Panel → App Mixer: shows controls
- App Mixer → Control Model: changes app audio
- Settings → Control Model: configures behavior (evidence: `Sources/VolumeControl/Presentation/SettingsView.swift`)
- Control Model → App Discovery: refreshes apps (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Control Model → Process Tap Controller: enables and restores (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Control Model → System Audio Service: controls system audio (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Control Model → Device Monitor: monitors devices (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Control Model → Headphone Policy: evaluates switching (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Control Model → BlackHole Router: starts test routing (evidence: `Sources/VolumeControl/VolumeControlModel.swift`)
- Process Tap Controller → Core Audio Session: creates session
- Process Tap Controller → Saved App Audio: persists settings (evidence: `Sources/VolumeControl/Application/ProcessTapVolumeController.swift`)
- Core Audio Session → Process Audio HAL: uses HAL (evidence: `Sources/VolumeControl/Infrastructure/ProcessAudio/CoreAudioProcessSession.swift`)
- Core Audio Session → Process Family: uses process grouping (evidence: `Sources/VolumeControl/Infrastructure/ProcessAudio/CoreAudioProcessSession.swift`)
- Process Tap Controller → Session Validation: validates session
- BlackHole Router → Routing Devices: queries and switches (evidence: `Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift`)
- BlackHole Router → HAL Route Engine: starts engine (evidence: `Sources/VolumeControl/Audio/V2/AudioDeviceRouter.swift`)
- HAL Route Engine → Process Audio HAL: uses HAL helpers (evidence: `Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift`)
- HAL Route Engine → Realtime PCM DSP: renders PCM (evidence: `Sources/VolumeControl/Audio/V2/HALAudioRoutingEngine.swift`)
- Route Validation → BlackHole Router: validates routing (evidence: `Sources/VolumeControl/Infrastructure/ProcessAudio/AudioRoutingValidationRunner.swift`)
- Route Validation → HAL Route Engine: uses engine (evidence: `Sources/VolumeControl/Infrastructure/ProcessAudio/AudioRoutingValidationRunner.swift`)
- Device Metadata → Process Audio HAL: reads device details (evidence: `Sources/VolumeControl/Infrastructure/OutputDeviceMetadata.swift`)
- Interface Preferences → Interface Store: loads and saves
- Menu Bar Panel → Interface Preferences: reads appearance (evidence: `Sources/VolumeControl/Presentation/MenuBarPopoverController.swift`)
