# morgan-mordata/morsounds-audio-indexer architecture

> Architecture diagram of the GitHub repository morgan-mordata/morsounds-audio-indexer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/morgan-mordata/morsounds-audio-indexer
- Repository: https://github.com/morgan-mordata/morsounds-audio-indexer

## Overview

This is a command-line audio-analysis and source-separation tool that prepares analysis data for realtime visualization. Users invoke analysis, separation, pipeline, inspection, or conversion commands; the pipeline separates audio and analyzes both the original and separated files. Analysis extracts continuous features and peaks, then writes versioned MessagePack or optional JSON data. Inspection plots saved analyses, and conversion switches formats. The README also describes Unity Timeline readers, but no reader implementation appears in the supplied tree; unsampled subsystems are represented only where the README supports them.

Main entry points: [`sonosthesia_audio_pipeline/__main__.py`](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/__main__.py) (Command dispatch), [`sonosthesia_audio_pipeline/analysis.py`](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/analysis.py) (Feature analysis), [`sonosthesia_audio_pipeline/separation.py`](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/separation.py) (Source separation), [`sonosthesia_audio_pipeline/utils.py`](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/utils.py) (File and serialization utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["Command dispatch<br/>[__main__.py]"]
  node_pipeline["Combined pipeline<br/>[pipeline.py]"]
end

subgraph group_audio["Audio processing"]
  node_analysis["Feature analysis<br/>[analysis.py]"]
  node_separation["Source separation<br/>[separation.py]"]
end

subgraph group_artifacts["Analysis files"]
  node_utils["File and serialization utilities<br/>[utils.py]"]
  node_analysis_files["Versioned analysis files<br/>[utils.py]"]
  node_conversion["Format conversion<br/>[conversion.py]"]
  node_check["Schema validation<br/>[check.py]"]
  node_schemas["Output schemas"]
end

subgraph group_consumption["Inspection and readers"]
  node_inspection["Analysis inspection<br/>[inspection.py]"]
  node_plots["Feature plots<br/>[inspection.py]"]
  node_unity["Unity Timeline reader"]
end

node_user(("Audio-tool user"))
node_librosa["Librosa audio features"]
node_demucs["Demucs separation"]

node_user -->|"invokes commands"| node_cli
node_cli -->|"dispatches analysis"| node_analysis
node_cli -->|"dispatches separation"| node_separation
node_cli -->|"dispatches pipeline"| node_pipeline
node_cli -->|"dispatches inspection"| node_inspection
node_cli -->|"dispatches conversion"| node_conversion
node_pipeline -->|"calls separation"| node_separation
node_pipeline -->|"calls analysis"| node_analysis
node_analysis -->|"extracts features"| node_librosa
node_analysis -->|"uses file helpers"| node_utils
node_analysis -->|"writes results"| node_analysis_files
node_separation -->|"runs separation"| node_demucs
node_separation -->|"finds input files"| node_utils
node_separation -->|"creates separated audio"| node_analysis_files
node_conversion -->|"reads and writes"| node_utils
node_conversion -->|"converts formats"| node_analysis_files
node_inspection -->|"loads analysis data"| node_utils
node_inspection -->|"reads analysis"| node_analysis_files
node_inspection -->|"plots features"| node_plots
node_unity -.->|"reads alongside audio"| node_analysis_files
node_check -->|"loads packed data"| node_utils
node_check -->|"validates against"| node_schemas

click node_cli "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/__main__.py"
click node_pipeline "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/pipeline.py"
click node_analysis "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/analysis.py"
click node_separation "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/separation.py"
click node_utils "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/utils.py"
click node_analysis_files "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/utils.py"
click node_conversion "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/conversion.py"
click node_inspection "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/inspection.py"
click node_plots "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/inspection.py"
click node_check "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/check.py"
click node_schemas "https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/schemas/schema-version2.json"

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_cli,node_pipeline,node_user toneBlue
class node_analysis,node_separation toneAmber
class node_utils,node_analysis_files,node_conversion,node_check,node_schemas toneMint
class node_inspection,node_plots,node_unity toneRose
class node_librosa,node_demucs toneIndigo
```

## Components

### Command entry

- [Command dispatch](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/__main__.py): `sonosthesia_audio_pipeline/__main__.py`
- [Combined pipeline](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/pipeline.py): `sonosthesia_audio_pipeline/pipeline.py`

### Audio processing

- [Feature analysis](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/analysis.py): `sonosthesia_audio_pipeline/analysis.py`
- [Source separation](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/separation.py): `sonosthesia_audio_pipeline/separation.py`

### Analysis files

- [File and serialization utilities](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/utils.py): `sonosthesia_audio_pipeline/utils.py`
- [Versioned analysis files](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/utils.py): `sonosthesia_audio_pipeline/utils.py`
- [Format conversion](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/conversion.py): `sonosthesia_audio_pipeline/conversion.py`
- [Schema validation](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/check.py): `sonosthesia_audio_pipeline/check.py`
- [Output schemas](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/schemas/schema-version2.json): `schemas/schema-version2.json`

### Inspection and readers

- [Analysis inspection](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/inspection.py): `sonosthesia_audio_pipeline/inspection.py`
- [Feature plots](https://github.com/morgan-mordata/morsounds-audio-indexer/blob/main/sonosthesia_audio_pipeline/inspection.py): `sonosthesia_audio_pipeline/inspection.py`
- **Unity Timeline reader**

### Other components

- **Audio-tool user**
- **Librosa audio features**
- **Demucs separation**

## Connections

- Audio-tool user → Command dispatch: invokes commands (evidence: `README.md`)
- Command dispatch → Feature analysis: dispatches analysis (evidence: `sonosthesia_audio_pipeline/__main__.py`)
- Command dispatch → Source separation: dispatches separation (evidence: `sonosthesia_audio_pipeline/__main__.py`)
- Command dispatch → Combined pipeline: dispatches pipeline (evidence: `sonosthesia_audio_pipeline/__main__.py`)
- Command dispatch → Analysis inspection: dispatches inspection (evidence: `sonosthesia_audio_pipeline/__main__.py`)
- Command dispatch → Format conversion: dispatches conversion (evidence: `sonosthesia_audio_pipeline/__main__.py`)
- Combined pipeline → Source separation: calls separation (evidence: `sonosthesia_audio_pipeline/pipeline.py`)
- Combined pipeline → Feature analysis: calls analysis (evidence: `sonosthesia_audio_pipeline/pipeline.py`)
- Feature analysis → Librosa audio features: extracts features (evidence: `sonosthesia_audio_pipeline/analysis.py`)
- Feature analysis → File and serialization utilities: uses file helpers (evidence: `sonosthesia_audio_pipeline/analysis.py`)
- Feature analysis → Versioned analysis files: writes results (evidence: `sonosthesia_audio_pipeline/analysis.py`)
- Source separation → Demucs separation: runs separation (evidence: `sonosthesia_audio_pipeline/separation.py`)
- Source separation → File and serialization utilities: finds input files (evidence: `sonosthesia_audio_pipeline/separation.py`)
- Source separation → Versioned analysis files: creates separated audio (evidence: `README.md`)
- Format conversion → File and serialization utilities: reads and writes (evidence: `sonosthesia_audio_pipeline/conversion.py`)
- Format conversion → Versioned analysis files: converts formats (evidence: `sonosthesia_audio_pipeline/conversion.py`)
- Analysis inspection → File and serialization utilities: loads analysis data (evidence: `sonosthesia_audio_pipeline/inspection.py`)
- Analysis inspection → Versioned analysis files: reads analysis (evidence: `sonosthesia_audio_pipeline/inspection.py`)
- Analysis inspection → Feature plots: plots features (evidence: `sonosthesia_audio_pipeline/inspection.py`)
- Unity Timeline reader → Versioned analysis files: reads alongside audio (evidence: `README.md`)
- Schema validation → File and serialization utilities: loads packed data (evidence: `sonosthesia_audio_pipeline/check.py`)
- Schema validation → Output schemas: validates against (evidence: `sonosthesia_audio_pipeline/check.py`)
