# elevatormusic/ears-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/elevatormusic/ears-bridge
- Repository: https://github.com/elevatormusic/ears-bridge

## Overview

EARS Bridge is a desktop headphone-measurement bridge: the user selects EARS input, virtual-cable output, and left/right calibration files, then starts a Dirac sweep. The audio engine captures both channels, applies per-ear correction, routes the swept ear, and uses asynchronous resampling to deliver a single-microphone signal to Dirac. Separate branches support device/format checks, measurement-health feedback, reference-based grading, and diagnostics. The README documents the principal audio flow; some internal subsystem links are omitted where the excerpts and index do not establish who invokes whom.

Main entry points: [`src/audio/AudioEngine.cpp`](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/AudioEngine.cpp) (Audio engine), [`src/gui/MainComponent.cpp`](https://github.com/elevatormusic/ears-bridge/blob/main/src/gui/MainComponent.cpp) (Desktop interface), [`src/audio/DeviceManager.cpp`](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/DeviceManager.cpp) (Device selection), [`src/cal/CalFile.cpp`](https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/CalFile.cpp) (Calibration files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Desktop interface<br/>[MainComponent.cpp]"]
  node_devices["Device selection<br/>[DeviceManager.cpp]"]
  node_formats["Endpoint formats<br/>[EndpointFormat.cpp]"]
end

subgraph group_audio["Audio runtime"]
  node_engine["Audio engine<br/>[AudioEngine.cpp]"]
  node_routing["Per-ear routing"]
  node_clock["Clock conversion<br/>[ClockBridge.h]"]
  node_graph["Signal processing"]
end

subgraph group_cal["Calibration"]
  node_calfile["Calibration files<br/>[CalFile.cpp]"]
  node_validation["Pair validation"]
  node_fir["Correction FIRs<br/>[FirDesigner.cpp]"]
end

subgraph group_quality["Measurement quality"]
  node_health["Capture safeguards<br/>[HealthMonitor.cpp]"]
  node_loopback["Sweep reference"]
  node_grading["Reference grading"]
  node_deconv["Sweep deconvolution<br/>[Deconvolver.cpp]"]
end

subgraph group_support["State and diagnostics"]
  node_settings[("User settings<br/>[Settings.cpp]")]
  node_log[("Diagnostic log<br/>[DiagnosticLog.cpp]")]
end

node_user(("Operator"))
node_ears(("EARS microphones"))
node_dirac(("Dirac Live"))
node_cable(("Virtual cable"))

node_user -->|"configures and starts"| node_main
node_ears -->|"provides two channels"| node_engine
node_main -->|"selects devices"| node_devices
node_devices -->|"checks endpoint formats"| node_formats
node_main -.->|"persists configuration"| node_settings
node_main -->|"loads calibration files"| node_calfile
node_main -->|"validates calibration pair"| node_validation
node_calfile -->|"checks sides"| node_validation
node_main -->|"requests FIR rebuild"| node_fir
node_engine -->|"applies ear corrections"| node_fir
node_engine -->|"selects swept ear"| node_routing
node_engine -->|"resamples across clocks"| node_clock
node_engine -.->|"processes audio"| node_graph
node_engine -->|"detects capture faults"| node_health
node_engine -->|"captures Dirac sweep"| node_loopback
node_loopback -.->|"supplies reference"| node_grading
node_grading -->|"deconvolves capture"| node_deconv
node_main -->|"records diagnostics"| node_log
node_engine -->|"sends corrected signal"| node_cable
node_cable -->|"provides virtual microphone"| node_dirac

click node_main "https://github.com/elevatormusic/ears-bridge/blob/main/src/gui/MainComponent.cpp"
click node_devices "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/DeviceManager.cpp"
click node_formats "https://github.com/elevatormusic/ears-bridge/blob/main/src/platform/EndpointFormat.cpp"
click node_settings "https://github.com/elevatormusic/ears-bridge/blob/main/src/state/Settings.cpp"
click node_engine "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/AudioEngine.cpp"
click node_routing "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ScheduledEarRouter.h"
click node_clock "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ClockBridge.h"
click node_graph "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ProcessingGraph.cpp"
click node_calfile "https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/CalFile.cpp"
click node_validation "https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/CalibrationPairValidator.cpp"
click node_fir "https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/FirDesigner.cpp"
click node_health "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/HealthMonitor.cpp"
click node_loopback "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/LoopbackReference.cpp"
click node_grading "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ReferenceGradePoller.cpp"
click node_deconv "https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/Deconvolver.cpp"
click node_log "https://github.com/elevatormusic/ears-bridge/blob/main/src/diag/DiagnosticLog.cpp"

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_main,node_devices,node_formats toneBlue
class node_engine,node_routing,node_clock,node_graph toneAmber
class node_calfile,node_validation,node_fir toneMint
class node_health,node_loopback,node_grading,node_deconv toneRose
class node_settings,node_log,node_user,node_ears,node_dirac,node_cable toneIndigo
```

## Components

### Application

- [Desktop interface](https://github.com/elevatormusic/ears-bridge/blob/main/src/gui/MainComponent.cpp): `src/gui/MainComponent.cpp`
- [Device selection](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/DeviceManager.cpp): `src/audio/DeviceManager.cpp`
- [Endpoint formats](https://github.com/elevatormusic/ears-bridge/blob/main/src/platform/EndpointFormat.cpp): `src/platform/EndpointFormat.cpp`

### Audio runtime

- [Audio engine](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/AudioEngine.cpp): `src/audio/AudioEngine.cpp`
- [Per-ear routing](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ScheduledEarRouter.h): `src/audio/ScheduledEarRouter.h`
- [Clock conversion](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ClockBridge.h): `src/audio/ClockBridge.h`
- [Signal processing](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ProcessingGraph.cpp): `src/audio/ProcessingGraph.cpp`

### Calibration

- [Calibration files](https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/CalFile.cpp): `src/cal/CalFile.cpp`
- [Pair validation](https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/CalibrationPairValidator.cpp): `src/cal/CalibrationPairValidator.cpp`
- [Correction FIRs](https://github.com/elevatormusic/ears-bridge/blob/main/src/cal/FirDesigner.cpp): `src/cal/FirDesigner.cpp`

### Measurement quality

- [Capture safeguards](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/HealthMonitor.cpp): `src/audio/HealthMonitor.cpp`
- [Sweep reference](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/LoopbackReference.cpp): `src/audio/LoopbackReference.cpp`
- [Reference grading](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/ReferenceGradePoller.cpp): `src/audio/ReferenceGradePoller.cpp`
- [Sweep deconvolution](https://github.com/elevatormusic/ears-bridge/blob/main/src/audio/Deconvolver.cpp): `src/audio/Deconvolver.cpp`

### State and diagnostics

- [User settings](https://github.com/elevatormusic/ears-bridge/blob/main/src/state/Settings.cpp): `src/state/Settings.cpp`
- [Diagnostic log](https://github.com/elevatormusic/ears-bridge/blob/main/src/diag/DiagnosticLog.cpp): `src/diag/DiagnosticLog.cpp`

### Other components

- **Operator**
- **EARS microphones**
- **Dirac Live**
- **Virtual cable**

## Connections

- Operator → Desktop interface: configures and starts (evidence: `README.md`)
- EARS microphones → Audio engine: provides two channels (evidence: `README.md`)
- Desktop interface → Device selection: selects devices
- Device selection → Endpoint formats: checks endpoint formats (evidence: `src/audio/DeviceManager.cpp`)
- Desktop interface → User settings: persists configuration
- Desktop interface → Calibration files: loads calibration files
- Desktop interface → Pair validation: validates calibration pair (evidence: `src/gui/MainComponent.cpp`)
- Calibration files → Pair validation: checks sides
- Desktop interface → Correction FIRs: requests FIR rebuild
- Audio engine → Correction FIRs: applies ear corrections (evidence: `README.md`)
- Audio engine → Per-ear routing: selects swept ear (evidence: `README.md`)
- Audio engine → Clock conversion: resamples across clocks (evidence: `README.md`)
- Audio engine → Signal processing: processes audio
- Audio engine → Capture safeguards: detects capture faults (evidence: `README.md`)
- Audio engine → Sweep reference: captures Dirac sweep (evidence: `README.md`)
- Sweep reference → Reference grading: supplies reference
- Reference grading → Sweep deconvolution: deconvolves capture
- Desktop interface → Diagnostic log: records diagnostics
- Audio engine → Virtual cable: sends corrected signal (evidence: `README.md`)
- Virtual cable → Dirac Live: provides virtual microphone (evidence: `README.md`)
