# sergree/matchering architecture

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

- Interactive diagram: https://gitdiagram.com/sergree/matchering
- Repository: https://github.com/sergree/matchering

## Overview

Matchering is an audio-matching and mastering Python library. A caller supplies target and reference audio, invokes the public processing API, and receives mastered audio saved in requested formats; optional results include un-limited audio and previews. The documented Docker, desktop, and ComfyUI uses are integrations around this library, not runtime components in this repository. The graph follows the indexed imports and explicit README workflow; unsampled modules are included where their subsystem is clear, but no uncertain internal calls are inferred.

Main entry points: [`matchering/core.py`](https://github.com/sergree/matchering/blob/master/matchering/core.py) (Processing coordinator), [`matchering/__init__.py`](https://github.com/sergree/matchering/blob/master/matchering/__init__.py) (Public API), [`matchering/checker.py`](https://github.com/sergree/matchering/blob/master/matchering/checker.py) (Input validation), [`matchering/stages.py`](https://github.com/sergree/matchering/blob/master/matchering/stages.py) (Mastering stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Library API"]
  node_api["Public API<br/>[__init__.py]"]
  node_config["Processing config<br/>[defaults.py]"]
end

subgraph group_processing["Audio Processing"]
  node_input_check["Input validation<br/>[checker.py]"]
  node_audio_load["Audio loading<br/>[loader.py]"]
  node_process["Processing coordinator<br/>[core.py]"]
  node_level_match["Level matching<br/>[match_levels.py]"]
  node_frequency_match["Frequency matching"]
  node_stages["Mastering stages<br/>[stages.py]"]
  node_limiter["Hyrax limiter<br/>[hyrax.py]"]
end

subgraph group_outputs["Results and Outputs"]
  node_results["Result formats<br/>[results.py]"]
  node_saver["Audio export<br/>[saver.py]"]
  node_preview["Preview creation<br/>[preview_creator.py]"]
end

subgraph group_support["Shared Internals"]
  node_dsp["Audio DSP primitives<br/>[dsp.py]"]
  node_logging["Logging and errors"]
  node_utils["Audio utilities<br/>[utils.py]"]
end

node_caller(("Library caller"))
node_audio["Target and reference"]
node_files["Output audio files"]

node_caller -->|"calls"| node_api
node_audio -->|"provides audio"| node_api
node_api -->|"exposes"| node_process
node_api -->|"exposes"| node_config
node_api -->|"exposes"| node_results
node_api -->|"exposes"| node_audio_load
node_api -->|"exposes"| node_input_check
node_api -->|"exposes logging"| node_logging
node_process -->|"loads"| node_audio_load
node_process -->|"validates"| node_input_check
node_process -->|"processes audio"| node_stages
node_process -->|"saves results"| node_saver
node_process -->|"creates previews"| node_preview
node_process -->|"uses config"| node_config
node_process -->|"uses result specs"| node_results
node_audio_load -->|"checks audio"| node_input_check
node_stages -->|"uses"| node_level_match
node_stages -->|"uses"| node_frequency_match
node_stages -->|"limits output"| node_limiter
node_level_match -->|"uses"| node_dsp
node_frequency_match -->|"uses"| node_dsp
node_limiter -->|"uses"| node_dsp
node_input_check -->|"uses"| node_dsp
node_input_check -->|"uses"| node_utils
node_preview -->|"writes previews"| node_saver
node_preview -->|"selects and fades"| node_dsp
node_saver -->|"writes audio"| node_files
node_preview -->|"writes previews"| node_files
node_stages -->|"logs stages"| node_logging
node_process -->|"logs processing"| node_logging
node_audio_load -->|"reports load errors"| node_logging
node_input_check -->|"reports checks"| node_logging

click node_api "https://github.com/sergree/matchering/blob/master/matchering/__init__.py"
click node_config "https://github.com/sergree/matchering/blob/master/matchering/defaults.py"
click node_input_check "https://github.com/sergree/matchering/blob/master/matchering/checker.py"
click node_audio_load "https://github.com/sergree/matchering/blob/master/matchering/loader.py"
click node_process "https://github.com/sergree/matchering/blob/master/matchering/core.py"
click node_level_match "https://github.com/sergree/matchering/blob/master/matchering/stage_helpers/match_levels.py"
click node_frequency_match "https://github.com/sergree/matchering/blob/master/matchering/stage_helpers/match_frequencies.py"
click node_stages "https://github.com/sergree/matchering/blob/master/matchering/stages.py"
click node_limiter "https://github.com/sergree/matchering/blob/master/matchering/limiter/hyrax.py"
click node_dsp "https://github.com/sergree/matchering/blob/master/matchering/dsp.py"
click node_results "https://github.com/sergree/matchering/blob/master/matchering/results.py"
click node_saver "https://github.com/sergree/matchering/blob/master/matchering/saver.py"
click node_preview "https://github.com/sergree/matchering/blob/master/matchering/preview_creator.py"
click node_logging "https://github.com/sergree/matchering/tree/master/matchering/log"
click node_utils "https://github.com/sergree/matchering/blob/master/matchering/utils.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_api,node_config toneBlue
class node_input_check,node_audio_load,node_process,node_level_match,node_frequency_match,node_stages,node_limiter toneAmber
class node_results,node_saver,node_preview toneMint
class node_dsp,node_logging,node_utils toneRose
class node_caller,node_audio,node_files toneIndigo
```

## Components

### Library API

- [Public API](https://github.com/sergree/matchering/blob/master/matchering/__init__.py): `matchering/__init__.py`
- [Processing config](https://github.com/sergree/matchering/blob/master/matchering/defaults.py): `matchering/defaults.py`

### Audio Processing

- [Input validation](https://github.com/sergree/matchering/blob/master/matchering/checker.py): `matchering/checker.py`
- [Audio loading](https://github.com/sergree/matchering/blob/master/matchering/loader.py): `matchering/loader.py`
- [Processing coordinator](https://github.com/sergree/matchering/blob/master/matchering/core.py): `matchering/core.py`
- [Level matching](https://github.com/sergree/matchering/blob/master/matchering/stage_helpers/match_levels.py): `matchering/stage_helpers/match_levels.py`
- [Frequency matching](https://github.com/sergree/matchering/blob/master/matchering/stage_helpers/match_frequencies.py): `matchering/stage_helpers/match_frequencies.py`
- [Mastering stages](https://github.com/sergree/matchering/blob/master/matchering/stages.py): `matchering/stages.py`
- [Hyrax limiter](https://github.com/sergree/matchering/blob/master/matchering/limiter/hyrax.py): `matchering/limiter/hyrax.py`

### Results and Outputs

- [Result formats](https://github.com/sergree/matchering/blob/master/matchering/results.py): `matchering/results.py`
- [Audio export](https://github.com/sergree/matchering/blob/master/matchering/saver.py): `matchering/saver.py`
- [Preview creation](https://github.com/sergree/matchering/blob/master/matchering/preview_creator.py): `matchering/preview_creator.py`

### Shared Internals

- [Audio DSP primitives](https://github.com/sergree/matchering/blob/master/matchering/dsp.py): `matchering/dsp.py`
- [Logging and errors](https://github.com/sergree/matchering/tree/master/matchering/log): `matchering/log`
- [Audio utilities](https://github.com/sergree/matchering/blob/master/matchering/utils.py): `matchering/utils.py`

### Other components

- **Library caller**
- **Target and reference**
- **Output audio files**

## Connections

- Library caller → Public API: calls (evidence: `README.md`)
- Target and reference → Public API: provides audio (evidence: `README.md`)
- Public API → Processing coordinator: exposes (evidence: `matchering/__init__.py`)
- Public API → Processing config: exposes (evidence: `matchering/__init__.py`)
- Public API → Result formats: exposes (evidence: `matchering/__init__.py`)
- Public API → Audio loading: exposes (evidence: `matchering/__init__.py`)
- Public API → Input validation: exposes (evidence: `matchering/__init__.py`)
- Public API → Logging and errors: exposes logging (evidence: `matchering/__init__.py`)
- Processing coordinator → Audio loading: loads (evidence: `matchering/core.py`)
- Processing coordinator → Input validation: validates (evidence: `matchering/core.py`)
- Processing coordinator → Mastering stages: processes audio (evidence: `matchering/core.py`)
- Processing coordinator → Audio export: saves results (evidence: `matchering/core.py`)
- Processing coordinator → Preview creation: creates previews (evidence: `matchering/core.py`)
- Processing coordinator → Processing config: uses config (evidence: `matchering/core.py`)
- Processing coordinator → Result formats: uses result specs (evidence: `matchering/core.py`)
- Audio loading → Input validation: checks audio (evidence: `matchering/core.py`)
- Mastering stages → Level matching: uses (evidence: `matchering/stages.py`)
- Mastering stages → Frequency matching: uses (evidence: `matchering/stages.py`)
- Mastering stages → Hyrax limiter: limits output (evidence: `matchering/stages.py`)
- Level matching → Audio DSP primitives: uses (evidence: `matchering/stage_helpers/match_levels.py`)
- Frequency matching → Audio DSP primitives: uses (evidence: `matchering/stage_helpers/match_frequencies.py`)
- Hyrax limiter → Audio DSP primitives: uses (evidence: `matchering/limiter/hyrax.py`)
- Input validation → Audio DSP primitives: uses (evidence: `matchering/checker.py`)
- Input validation → Audio utilities: uses (evidence: `matchering/checker.py`)
- Preview creation → Audio export: writes previews (evidence: `matchering/preview_creator.py`)
- Preview creation → Audio DSP primitives: selects and fades (evidence: `matchering/preview_creator.py`)
- Audio export → Output audio files: writes audio (evidence: `README.md`)
- Preview creation → Output audio files: writes previews (evidence: `matchering/preview_creator.py`)
- Mastering stages → Logging and errors: logs stages (evidence: `matchering/stages.py`)
- Processing coordinator → Logging and errors: logs processing (evidence: `matchering/core.py`)
- Audio loading → Logging and errors: reports load errors (evidence: `matchering/loader.py`)
- Input validation → Logging and errors: reports checks (evidence: `matchering/checker.py`)
