# loteran/arctis-sound-manager architecture

> Architecture diagram of the GitHub repository loteran/arctis-sound-manager, 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/loteran/arctis-sound-manager
- Repository: https://github.com/loteran/arctis-sound-manager

## Overview

Arctis Sound Manager is a Linux desktop companion for SteelSeries Arctis headsets, combining headset controls with audio routing, mixing, and processing. The principal workflow is a user changing settings in the GUI, the application applying them through its audio and device-control layers, and audio being routed or processed by PipeWire/PulseAudio. The README also documents clips, profiles, themes, and Stream Guard as product capabilities. Some branches are represented at their owning module or directory because their implementation was not sampled; edges are limited to documented or indexed relationships.

Main entry points: [`src/arctis_sound_manager/core.py`](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/core.py) (Core engine), [`src/arctis_sound_manager/sonar_to_pipewire.py`](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/sonar_to_pipewire.py) (Sonar processing), [`src/arctis_sound_manager/pactl.py`](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/pactl.py) (Channel mixer), [`src/arctis_sound_manager/gui/sonar_page.py`](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/gui/sonar_page.py) (Sonar EQ interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_dbus["D-Bus service<br/>[dbus_service.py]"]
  node_core["Core engine<br/>[core.py]"]
  node_config["Device configuration<br/>[config.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

subgraph group_audio["Audio features"]
  node_mixer["Channel mixer<br/>[pactl.py]"]
  node_routing["Media routing<br/>[video_router.py]"]
  node_sonar["Sonar processing"]
  node_reconfig["Audio reconfiguration<br/>[audio_reconfig.py]"]
  node_profiles["Audio profiles<br/>[profile_manager.py]"]
  node_clips["Clip capture and library<br/>[clip_capture.py]"]
  node_stream_guard["Stream Guard<br/>[stream_guard.py]"]
end

subgraph group_headset["Headset features"]
  node_device["Device state<br/>[device_state.py]"]
  node_oled["Headset OLED<br/>[oled_manager.py]"]
end

subgraph group_presentation["Interface and sharing"]
  node_gui["Desktop GUI"]
  node_sonar_ui["Sonar EQ interface<br/>[sonar_page.py]"]
  node_themes["Theme management<br/>[theme.py]"]
  node_bug_report["Bug reporting<br/>[bug_reporter.py]"]
end

subgraph group_platform["Linux audio platform"]
  node_pipewire["PipeWire utilities<br/>[pw_utils.py]"]
  node_pulse["PulseAudio"]
  node_pw_service["PipeWire services"]
end

node_user(("Headset user"))
node_headset_hw["Arctis headset"]

node_user -->|"controls"| node_gui
node_gui -.->|"opens EQ"| node_sonar_ui
node_sonar_ui -->|"configures EQ"| node_sonar
node_sonar_ui -->|"sends commands"| node_dbus
node_sonar -->|"generates configs"| node_pw_service
node_sonar -->|"reads settings"| node_settings
node_sonar -->|"requests restart"| node_reconfig
node_dbus -->|"dispatches requests"| node_core
node_core -->|"reads state"| node_device
node_core -->|"uses device config"| node_config
node_core -->|"controls channels"| node_mixer
node_core -->|"manages processing"| node_sonar
node_core -->|"manages display"| node_oled
node_mixer -->|"controls sinks"| node_pulse
node_mixer -->|"uses utilities"| node_pipewire
node_routing -->|"detects native streams"| node_pipewire
node_routing -->|"coordinates changes"| node_reconfig
node_profiles -.->|"stores configuration"| node_settings
node_user -->|"saves captures"| node_clips
node_user -.->|"uses protection"| node_stream_guard
node_oled -->|"updates display"| node_headset_hw
node_user -->|"customizes appearance"| node_themes
node_user -->|"saves audio setup"| node_profiles
node_user -->|"reports problems"| node_bug_report

click node_gui "https://github.com/loteran/arctis-sound-manager/tree/main/src/arctis_sound_manager/gui"
click node_dbus "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/dbus_service.py"
click node_core "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/core.py"
click node_config "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/config.py"
click node_settings "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/settings.py"
click node_device "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/device_state.py"
click node_mixer "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/pactl.py"
click node_pipewire "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/pw_utils.py"
click node_routing "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/scripts/video_router.py"
click node_sonar_ui "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/gui/sonar_page.py"
click node_sonar "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/sonar_to_pipewire.py"
click node_reconfig "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/audio_reconfig.py"
click node_profiles "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/profile_manager.py"
click node_clips "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/clip_capture.py"
click node_stream_guard "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/stream_guard.py"
click node_oled "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/oled_manager.py"
click node_themes "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/gui/theme.py"
click node_bug_report "https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/bug_reporter.py"

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_dbus,node_core,node_config,node_settings,node_user toneBlue
class node_mixer,node_routing,node_sonar,node_reconfig,node_profiles,node_clips,node_stream_guard toneAmber
class node_device,node_oled toneMint
class node_gui,node_sonar_ui,node_themes,node_bug_report toneRose
class node_pipewire,node_pulse,node_pw_service,node_headset_hw toneIndigo
```

## Components

### Application

- [D-Bus service](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/dbus_service.py): `src/arctis_sound_manager/dbus_service.py`
- [Core engine](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/core.py): `src/arctis_sound_manager/core.py`
- [Device configuration](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/config.py): `src/arctis_sound_manager/config.py`
- [Settings](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/settings.py): `src/arctis_sound_manager/settings.py`

### Audio features

- [Channel mixer](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/pactl.py): `src/arctis_sound_manager/pactl.py`
- [Media routing](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/scripts/video_router.py): `src/arctis_sound_manager/scripts/video_router.py`
- [Sonar processing](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/sonar_to_pipewire.py): `src/arctis_sound_manager/sonar_to_pipewire.py`
- [Audio reconfiguration](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/audio_reconfig.py): `src/arctis_sound_manager/audio_reconfig.py`
- [Audio profiles](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/profile_manager.py): `src/arctis_sound_manager/profile_manager.py`
- [Clip capture and library](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/clip_capture.py): `src/arctis_sound_manager/clip_capture.py`
- [Stream Guard](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/stream_guard.py): `src/arctis_sound_manager/stream_guard.py`

### Headset features

- [Device state](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/device_state.py): `src/arctis_sound_manager/device_state.py`
- [Headset OLED](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/oled_manager.py): `src/arctis_sound_manager/oled_manager.py`

### Interface and sharing

- [Desktop GUI](https://github.com/loteran/arctis-sound-manager/tree/main/src/arctis_sound_manager/gui): `src/arctis_sound_manager/gui`
- [Sonar EQ interface](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/gui/sonar_page.py): `src/arctis_sound_manager/gui/sonar_page.py`
- [Theme management](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/gui/theme.py): `src/arctis_sound_manager/gui/theme.py`
- [Bug reporting](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/bug_reporter.py): `src/arctis_sound_manager/bug_reporter.py`

### Linux audio platform

- [PipeWire utilities](https://github.com/loteran/arctis-sound-manager/blob/main/src/arctis_sound_manager/pw_utils.py): `src/arctis_sound_manager/pw_utils.py`
- **PulseAudio**
- **PipeWire services**

### Other components

- **Headset user**
- **Arctis headset**

## Connections

- Headset user → Desktop GUI: controls
- Desktop GUI → Sonar EQ interface: opens EQ (evidence: `src/arctis_sound_manager/gui/home_page.py`)
- Sonar EQ interface → Sonar processing: configures EQ (evidence: `src/arctis_sound_manager/gui/sonar_page.py`)
- Sonar EQ interface → D-Bus service: sends commands (evidence: `src/arctis_sound_manager/gui/sonar_page.py`)
- Sonar processing → PipeWire services: generates configs (evidence: `src/arctis_sound_manager/sonar_to_pipewire.py`)
- Sonar processing → Settings: reads settings (evidence: `src/arctis_sound_manager/sonar_to_pipewire.py`)
- Sonar processing → Audio reconfiguration: requests restart (evidence: `src/arctis_sound_manager/sonar_to_pipewire.py`)
- D-Bus service → Core engine: dispatches requests (evidence: `src/arctis_sound_manager/dbus_service.py`)
- Core engine → Device state: reads state (evidence: `src/arctis_sound_manager/core.py`)
- Core engine → Device configuration: uses device config (evidence: `src/arctis_sound_manager/core.py`)
- Core engine → Channel mixer: controls channels (evidence: `src/arctis_sound_manager/core.py`)
- Core engine → Sonar processing: manages processing (evidence: `src/arctis_sound_manager/core.py`)
- Core engine → Headset OLED: manages display (evidence: `src/arctis_sound_manager/core.py`)
- Channel mixer → PulseAudio: controls sinks (evidence: `src/arctis_sound_manager/pactl.py`)
- Channel mixer → PipeWire utilities: uses utilities (evidence: `src/arctis_sound_manager/pactl.py`)
- Media routing → PipeWire utilities: detects native streams (evidence: `src/arctis_sound_manager/scripts/video_router.py`)
- Media routing → Audio reconfiguration: coordinates changes (evidence: `src/arctis_sound_manager/scripts/video_router.py`)
- Audio profiles → Settings: stores configuration
- Headset user → Clip capture and library: saves captures
- Headset user → Stream Guard: uses protection
- Headset OLED → Arctis headset: updates display (evidence: `src/arctis_sound_manager/oled_manager.py`)
- Headset user → Theme management: customizes appearance
- Headset user → Audio profiles: saves audio setup
- Headset user → Bug reporting: reports problems
