# sound-copy/orientation_processor architecture

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

- Interactive diagram: https://gitdiagram.com/sound-copy/orientation_processor
- Repository: https://github.com/sound-copy/orientation_processor

## Overview

This repository converts MIDI files, optionally paired with WAV audio, into JSON containing filename-derived metadata, MIDI notes, and audio measurements. The main workflow is implemented in Stage 1; Stage 2 currently consists of placeholder modules and a skeleton entry point, with no demonstrated processing flow between them. The Stage 1 config file is read by the converter. Stage 2 internals were not sampled beyond their placeholder contents, so no behavior or connections are inferred for them.

Main entry points: [`stage1/midi_and_wav_to_json.py`](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py) (Converter CLI), [`stage1/config_stage1.yaml`](https://github.com/sound-copy/orientation_processor/blob/main/stage1/config_stage1.yaml) (Stage 1 Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stage1["Stage 1 Conversion"]
  node_converter["Converter CLI"]
  node_metadata["Filename Metadata"]
  node_midi_extract["MIDI Extraction"]
  node_wav_analysis["WAV Analysis"]
  node_json_build["JSON Assembly"]
  node_stage1_config["Stage 1 Config<br/>[config_stage1.yaml]"]
end

subgraph group_stage2["Stage 2 Skeleton"]
  node_stage2_entry["Stage 2 Entry<br/>[stage2.py]"]
  node_stage2_io["I/O Placeholder<br/>[io.py]"]
  node_stage2_miners["Miners Placeholder<br/>[miners.py]"]
  node_stage2_plots["Plots Placeholder<br/>[plots.py]"]
  node_stage2_utils["Utilities Placeholder<br/>[utils.py]"]
end

node_user(("Operator"))
node_midi_files["MIDI Files"]
node_wav_files["WAV Files"]
node_json_output["JSON Files"]

node_user -->|"runs"| node_converter
node_converter -->|"reads"| node_stage1_config
node_converter -->|"scans"| node_midi_files
node_converter -->|"parses names"| node_metadata
node_converter -->|"extracts notes"| node_midi_extract
node_converter -.->|"checks matches"| node_wav_files
node_converter -.->|"analyzes optionally"| node_wav_analysis
node_converter -->|"assembles data"| node_json_build
node_converter -->|"writes"| node_json_output

click node_converter "https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py"
click node_metadata "https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py"
click node_midi_extract "https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py"
click node_wav_analysis "https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py"
click node_json_build "https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py"
click node_stage1_config "https://github.com/sound-copy/orientation_processor/blob/main/stage1/config_stage1.yaml"
click node_stage2_entry "https://github.com/sound-copy/orientation_processor/blob/main/stage2.py"
click node_stage2_io "https://github.com/sound-copy/orientation_processor/blob/main/stage2/io.py"
click node_stage2_miners "https://github.com/sound-copy/orientation_processor/blob/main/stage2/miners.py"
click node_stage2_plots "https://github.com/sound-copy/orientation_processor/blob/main/stage2/plots.py"
click node_stage2_utils "https://github.com/sound-copy/orientation_processor/blob/main/stage2/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_converter,node_metadata,node_midi_extract,node_wav_analysis,node_json_build,node_stage1_config toneBlue
class node_stage2_entry,node_stage2_io,node_stage2_miners,node_stage2_plots,node_stage2_utils toneAmber
class node_user,node_midi_files,node_wav_files,node_json_output toneIndigo
```

## Components

### Stage 1 Conversion

- [Converter CLI](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py): `stage1/midi_and_wav_to_json.py`
- [Filename Metadata](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py): `stage1/midi_and_wav_to_json.py`
- [MIDI Extraction](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py): `stage1/midi_and_wav_to_json.py`
- [WAV Analysis](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py): `stage1/midi_and_wav_to_json.py`
- [JSON Assembly](https://github.com/sound-copy/orientation_processor/blob/main/stage1/midi_and_wav_to_json.py): `stage1/midi_and_wav_to_json.py`
- [Stage 1 Config](https://github.com/sound-copy/orientation_processor/blob/main/stage1/config_stage1.yaml): `stage1/config_stage1.yaml`

### Stage 2 Skeleton

- [Stage 2 Entry](https://github.com/sound-copy/orientation_processor/blob/main/stage2.py): `stage2.py`
- [I/O Placeholder](https://github.com/sound-copy/orientation_processor/blob/main/stage2/io.py): `stage2/io.py`
- [Miners Placeholder](https://github.com/sound-copy/orientation_processor/blob/main/stage2/miners.py): `stage2/miners.py`
- [Plots Placeholder](https://github.com/sound-copy/orientation_processor/blob/main/stage2/plots.py): `stage2/plots.py`
- [Utilities Placeholder](https://github.com/sound-copy/orientation_processor/blob/main/stage2/utils.py): `stage2/utils.py`

### Other components

- **Operator**
- **MIDI Files**
- **WAV Files**
- **JSON Files**

## Connections

- Operator → Converter CLI: runs (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → Stage 1 Config: reads (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → MIDI Files: scans (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → Filename Metadata: parses names (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → MIDI Extraction: extracts notes (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → WAV Files: checks matches (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → WAV Analysis: analyzes optionally (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → JSON Assembly: assembles data (evidence: `stage1/midi_and_wav_to_json.py`)
- Converter CLI → JSON Files: writes (evidence: `stage1/midi_and_wav_to_json.py`)