How tfourj/earie works
1. What this repo is
- Earie is a Windows per-app audio mixer built with C++/Qt 6 + QML.
- It runs tray-only: the tray icon opens the main flyout, with a separate settings window and hidden-items window.
- The core job is to enumerate Windows audio devices and sessions, filter/sort them, and let the user manage visibility and labels.
2. Application entry and bootstrapping
- main.cpp is the application entry point.
- Startup likely wires together the Qt application, COM initialization, the central controller, QML engine, and the models exposed to QML.
- include/ComInit.h / src/ComInit.cpp indicate COM is initialized as part of startup because the app depends on Windows Core Audio APIs.
3. Top-level orchestration
- AppController is the central coordinator between UI, persistence, and audio state.
- It is the main boundary between the QML frontend and the audio/device backend.
- The controller likely handles actions such as toggling windows, applying hidden-device/process rules, changing mode, and refreshing state after audio events.
4. UI layer: QML views
- The UI is implemented in qml/.
- Main.qml is the primary tray flyout or mixer view.
- SettingsWindow.qml contains application preferences such as device visibility and session display options.
- HiddenItemsWindow.qml likely surfaces hidden devices/processes for management.
- Reusable controls live in qml/components/, and theming/styling is in qml/styles/.
5. View-model / data exposure layer
- DeviceListModel, SessionListModel, and DeviceDirectionProxyModel are the Qt model layer exposed to QML.
- These models are the bridge from backend state to the visual lists in QML.
- The proxy model suggests the UI can present devices by direction or category without duplicating backend state.
- This is a key architectural boundary: backend objects are normalized into Qt models before reaching QML.
6. Audio domain and Windows Core Audio integration
- AudioBackend is the main audio-system abstraction.
- AudioDevice and AudioSession are domain objects wrapping Windows audio concepts like IMMDevice and per-process sessions.
- AudioWorker implies audio enumeration and updates run off the UI thread to avoid blocking the interface.
- The app’s core domain flow is:
- enumerate devices/sessions,
- build device/session objects,
- filter by settings,
- expose them through models.
7. State updates and responsiveness
- UpdateCoalescer indicates the app batches rapid backend changes into fewer UI refreshes.
- That matters in an audio mixer because Windows session/device changes can be noisy and frequent.
- This component sits between low-level audio change notifications and the Qt models/UI, preventing excessive redraws or model churn.
8. Configuration and persistence
- ConfigStore persists user settings to %APPDATA%/Earie/config.json.
- The config is JSON-based and versioned (schemaVersion: 2).
- Persisted state includes:
- operating mode (default vs all),
- whether to show system sessions,
- whether to show input devices,
- device display names and colors,
- hidden devices,
- hidden processes globally and per device.
- The config layer is the source of truth for user preferences and filtering rules.
9. Filtering and identity rules
- Devices are tracked by stable IMMDevice IDs.
- Processes are hidden by full executable path resolved from session PID, which makes the hidden-process logic more stable than using only process names.
- This is important for architecture because visibility is not just a UI concern; it is part of the persisted domain model and affects how sessions are included in the mixer.
10. Windows-specific UI integration
- WinAcrylic and WinTrayPositioner are Windows UI helpers.
- These likely adapt Qt windows to Windows 11-style acrylic effects and position the flyout relative to the system tray.
- This is a small but distinct platform layer separate from the main audio logic and QML UI.
11. Platform/support headers
- include/win/ComPtr.h, Hr.h, and Utf.h are utility wrappers for safer Windows API usage.
- They reduce boilerplate around COM pointers, HRESULT handling, and UTF conversion.
- include/Audio* and include/Device* headers define the main backend interfaces consumed by the rest of the app.
12. Packaging and deployment
- installer/ contains an NSIS installer and release scripts.
- The README notes both an installer build and a portable ZIP build.
- The installer adds system integration such as Start Menu entries and auto-update support, while the portable build intentionally avoids that integration.
13. Assets and resources
- resources.qrc bundles runtime assets into the application.
- assets/ and .github/assets/ contain branding and showcase images.
- The packaged icon and QML styling support the app’s tray-centric visual identity.
14. Overall data flow to draw in a diagram
- Windows audio system → AudioBackend / AudioWorker → AudioDevice / AudioSession
- then into DeviceListModel / SessionListModel / proxy models
- then into QML screens (Main, Settings, HiddenItems)
- with AppController mediating actions and ConfigStore persisting changes
- plus Windows-specific helpers for tray placement and window styling.
Main entry points: AppController.h AppController · Main.qml Main.qml · main.cpp main.cpp · AudioBackend.h AudioBackend
Components 20
Runtime
Application startup and cross-cutting coordination
- main.cpp · Qt application entry and startup wiring
main.cpp - COM init · Initializes Windows COM for Core Audio use
include/ComInit.h - AppController · Coordinates UI actions, persistence, and backend state
include/AppController.h
Audio core
Windows audio enumeration, domain objects, and refresh flow
- AudioBackend · Main boundary to Windows audio enumeration and updates
include/AudioBackend.h - AudioWorker · Runs audio enumeration and refresh work off the UI thread
include/AudioWorker.h - AudioDevice · Represents a Windows audio device and its metadata
include/AudioDevice.h - AudioSession · Represents a per-process audio session
include/AudioSession.h - UpdateCoalescer · Batches noisy backend changes into fewer UI updates
include/UpdateCoalescer.h - DeviceListModel · Exposes devices to QML lists
include/DeviceListModel.h - SessionListModel · Exposes sessions to QML lists
include/SessionListModel.h - Direction proxy · Filters or groups devices by direction for the UI
include/DeviceDirectionProxyModel.h
Qt UI
QML views and reusable presentation components
- Main.qml · Primary tray flyout mixer UI
qml/Main.qml - SettingsWindow.qml · Application preferences and visibility controls
qml/SettingsWindow.qml - HiddenItemsWindow.qml · Window for managing hidden devices and processes
qml/HiddenItemsWindow.qml - DeviceCell · Reusable device row element
qml/components/DeviceCell.qml - SessionRow · Reusable session row element
qml/components/SessionRow.qml
Platform
Windows-specific window and COM helpers
- WinAcrylic · Applies Windows acrylic styling to Qt windows
include/WinAcrylic.h - Tray positioner · Positions the flyout relative to the system tray
include/WinTrayPositioner.h
Storage
Configuration persistence and user state
- ConfigStore · Persists settings, visibility rules, and labels as JSON
include/ConfigStore.h
Packaging
Installer and deployment scripts
- Installer · NSIS installer and release scripts
installer/installer/installer.nsi
Connections 28
- main.cpp → COM init: initializes · Startup prepares COM before Core Audio access
- main.cpp → AppController: creates · Entry point constructs the central controller
- main.cpp → AudioBackend: boots · Startup wires backend state into the app
- main.cpp → DeviceListModel: exposes · Models are registered for QML consumption
- main.cpp → SessionListModel: exposes · Models are registered for QML consumption
- AppController → ConfigStore: loads/saves · Controller applies persisted preferences and updates config
- AppController → AudioBackend: drives · Controller requests refreshes and applies user actions
- AppController → DeviceListModel: feeds · Controller supplies device state to the UI model
- AppController → SessionListModel: feeds · Controller supplies session state to the UI model
- AppController → Direction proxy: configures · Controller sets up presentation-level device grouping
- AudioBackend → AudioWorker: delegates · Backend offloads enumeration and refresh work
- AudioBackend → AudioDevice: builds · Backend normalizes Windows devices into domain objects
- AudioBackend → AudioSession: builds · Backend normalizes Windows sessions into domain objects
- AudioWorker → UpdateCoalescer: notifies · Worker events are throttled before reaching models
- UpdateCoalescer → DeviceListModel: refreshes · Batched changes update the device list model
- UpdateCoalescer → SessionListModel: refreshes · Batched changes update the session list model
- DeviceListModel → Main.qml: renders in · Device data is displayed in the main mixer view
- SessionListModel → Main.qml: renders in · Session data is displayed in the main mixer view
- Direction proxy → Main.qml: filters for · Proxy shapes device presentation in the UI
- Main.qml → SettingsWindow.qml: opens · Main flyout links to settings
- Main.qml → HiddenItemsWindow.qml: opens · Main flyout links to hidden-items management
- Main.qml → DeviceCell: uses · Main view composes reusable device controls
- Main.qml → SessionRow: uses · Main view composes reusable session controls
- SettingsWindow.qml → ConfigStore: edits · Settings change persisted visibility and labeling rules
- HiddenItemsWindow.qml → ConfigStore: edits · Hidden-item management updates persisted rules
- AppController → WinAcrylic: applies · Controller coordinates platform-specific window styling
- AppController → Tray positioner: positions · Controller helps place tray flyouts correctly
- Installer → main.cpp: packages · Installer delivers the application build