# mymindstorm/gnome-volume-mixer architecture

> Architecture diagram of the GitHub repository mymindstorm/gnome-volume-mixer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mymindstorm/gnome-volume-mixer
- Repository: https://github.com/mymindstorm/gnome-volume-mixer

## Overview

1. **Project type and runtime**
   - This is a **GNOME Shell extension** written in JavaScript for the **GJS/GTK** runtime, not a standalone app.
   - It integrates into the desktop’s **system menu / quick settings area** to expose per-application audio controls.

2. **Primary purpose**
   - The extension discovers **applications currently emitting audio** and adds a **volume slider for each one**.
   - The result is a desktop-level mixer UI layered on top of the GNOME Shell audio model.

3. **Main entrypoint**
   - `src/extension.js` is the activation boundary for the extension.
   - It is responsible for wiring the extension into GNOME Shell lifecycle events, creating/removing UI, and coordinating the other components.

4. **Audio-stream UI layer**
   - `src/applicationStreamSlider.js` appears to encapsulate the behavior of a **single per-application slider**.
   - This is likely the key bridge between the GNOME audio stream model and the user-facing control, handling display state and value changes for one stream.

5. **Popup/menu integration**
   - `src/volumeMixerPopupMenu.js` is the main UI container for the mixer inside the shell menu.
   - It likely collects active audio streams, instantiates one slider per stream, and keeps the menu content synchronized with the current audio state.

6. **Preferences and configuration**
   - `src/prefs.js` and `src/volumeMixerPrefsPage.js` implement the extension’s **preferences UI**.
   - These files define how the user configures the extension outside the shell menu, likely including stream filtering, display behavior, or other mixer options.

7. **Filtering and exceptions**
   - `src/volumeMixerAddFilterDialog.js` suggests the extension supports **excluding or filtering specific applications/streams**.
   - This is an important architectural boundary: some streams are shown in the mixer, while others are hidden based on user-configured rules.

8. **Persistent settings contract**
   - `schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml` defines the extension’s **GSettings schema**.
   - This is the persistent configuration layer used by both the preferences UI and the runtime extension logic.

9. **Data flow**
   - The runtime flow is: **GNOME audio stream state → extension discovers active application streams → popup menu builds a set of per-app sliders → user changes slider → stream volume updates**.
   - Preferences flow is: **preferences UI → GSettings schema-backed storage → extension reads settings at runtime to decide what to display and how to behave**.

10. **Packaging/build**
   - `package.json`, `package-lock.json`, and `rollup.config.js` indicate the JavaScript sources are **bundled for GNOME Shell distribution**.
   - The build produces a deployable extension package, and the README shows installation as a GNOME Extensions ZIP.

11. **Repository boundaries**
   - There are no backend services, databases, or network APIs in this repo.
   - The architecture is entirely **local desktop integration**: GNOME Shell UI, audio stream control, and persistent desktop settings.

12. **Diagram-friendly subsystem breakdown**
   - You can model the repo as four boxes:
     - **Extension lifecycle/controller**: `extension.js`
     - **Mixer UI components**: `volumeMixerPopupMenu.js`, `applicationStreamSlider.js`
     - **Preferences UI**: `prefs.js`, `volumeMixerPrefsPage.js`, `volumeMixerAddFilterDialog.js`
     - **Settings schema/persistence**: `schemas/*.gschema.xml`

13. **Key architectural boundary**
   - The most important boundary is between **GNOME Shell-managed state** and the extension’s own UI/configuration logic.
   - The extension does not own audio; it **observes and manipulates GNOME-provided application streams** through shell integration.

Main entry points: [`src/extension.js`](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/extension.js) (Extension), [`schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml`](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml) (GSettings schema), [`src/volumeMixerPopupMenu.js`](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPopupMenu.js) (Popup menu), [`src/volumeMixerPrefsPage.js`](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPrefsPage.js) (Prefs page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell runtime"]
  node_extension["Extension<br/>lifecycle controller<br/>[extension.js]"]
end

subgraph group_ui["Mixer UI"]
  node_popup["Popup menu<br/>ui container"]
  node_slider["App slider<br/>stream control"]
end

subgraph group_prefs["Preferences"]
  node_prefs_page["Prefs page<br/>preferences ui"]
  node_filter_dialog["Filter dialog<br/>filter editor"]
  node_prefs_entry["Prefs entry<br/>prefs bootstrap<br/>[prefs.js]"]
end

subgraph group_settings["Settings"]
  node_schema[("GSettings schema<br/>persistent settings")]
end

subgraph group_build["Build"]
  node_package["Package config<br/>bundle metadata<br/>[package.json]"]
  node_rollup["Rollup build<br/>bundler config<br/>[rollup.config.js]"]
end

node_extension -->|"creates"| node_popup
node_popup -->|"renders"| node_slider
node_slider -->|"updates"| node_extension
node_extension -->|"reads settings"| node_schema
node_prefs_entry -->|"opens"| node_prefs_page
node_prefs_page -->|"uses"| node_filter_dialog
node_prefs_page -->|"writes settings"| node_schema
node_filter_dialog -->|"stores rules"| node_schema
node_popup -->|"applies filters"| node_schema
node_package -->|"drives"| node_rollup
node_rollup -->|"bundles"| node_extension

click node_extension "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/extension.js"
click node_popup "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPopupMenu.js"
click node_slider "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/applicationStreamSlider.js"
click node_prefs_page "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPrefsPage.js"
click node_filter_dialog "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerAddFilterDialog.js"
click node_prefs_entry "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/prefs.js"
click node_schema "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml"
click node_package "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/package.json"
click node_rollup "https://github.com/mymindstorm/gnome-volume-mixer/blob/master/rollup.config.js"

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_extension toneBlue
class node_popup,node_slider toneAmber
class node_prefs_page,node_filter_dialog,node_prefs_entry toneMint
class node_schema toneRose
class node_package,node_rollup toneIndigo
```

## Components

### Shell runtime

GNOME Shell extension code that activates, discovers audio streams, and drives the mixer UI.

- [Extension](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/extension.js): lifecycle controller · GNOME Shell activation boundary that wires the extension into shell lifecycle events and coordinates the mixer pieces. · `src/extension.js`

### Mixer UI

User-facing popup/menu components that render per-application volume controls.

- [Popup menu](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPopupMenu.js): ui container · Shell menu container that collects active application audio streams and keeps the mixer list in sync. · `src/volumeMixerPopupMenu.js`
- [App slider](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/applicationStreamSlider.js): stream control · Represents a single application audio stream and bridges stream state to a user-facing volume slider. · `src/applicationStreamSlider.js`

### Preferences

Extension preferences pages and dialogs used to configure filtering and display behavior.

- [Prefs page](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerPrefsPage.js): preferences ui · Main preferences page for configuring extension behavior outside the shell menu. · `src/volumeMixerPrefsPage.js`
- [Filter dialog](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/volumeMixerAddFilterDialog.js): filter editor · Dialog for adding or editing application and stream filtering exceptions. · `src/volumeMixerAddFilterDialog.js`
- [Prefs entry](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/src/prefs.js): prefs bootstrap · GNOME preferences entrypoint that exposes the extension settings UI to the desktop. · `src/prefs.js`

### Settings

Persistent configuration contract shared by runtime and preferences.

- [GSettings schema](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml): persistent settings · Schema defining the extension's stored configuration shared by runtime and preferences. · `schemas/net.evermiss.mymindstorm.volume-mixer.gschema.xml`

### Build

Packaging and bundling files for GNOME Shell distribution.

- [Package config](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/package.json): bundle metadata · Node and bundler configuration used to package the extension for GNOME Shell distribution. · `package.json`
- [Rollup build](https://github.com/mymindstorm/gnome-volume-mixer/blob/master/rollup.config.js): bundler config · Build configuration that bundles the JavaScript sources into a deployable extension package. · `rollup.config.js`

## Connections

- Extension → Popup menu: creates · The extension instantiates and attaches the mixer popup UI during activation.
- Popup menu → App slider: renders · The popup builds one slider per active application audio stream.
- App slider → Extension: updates · Slider changes flow back through the extension to control application volume state.
- Extension → GSettings schema: reads settings · Runtime behavior is driven by persisted GSettings values.
- Prefs entry → Prefs page: opens · The preferences entrypoint exposes the main settings page.
- Prefs page → Filter dialog: uses · The preferences UI launches the filter editor for exceptions management.
- Prefs page → GSettings schema: writes settings · Preferences persist user choices into the shared schema-backed store.
- Filter dialog → GSettings schema: stores rules · Filter additions and edits are saved as persistent settings.
- Popup menu → GSettings schema: applies filters · The popup reads stored rules to decide which streams to show.
- Package config → Rollup build: drives · Package metadata works with the bundler configuration to produce distributable output.
- Rollup build → Extension: bundles · The build process packages the extension sources for GNOME Shell.
