# yogesh-yogi-s/yogesh-vocal-music-audio architecture

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

- Interactive diagram: https://gitdiagram.com/yogesh-yogi-s/yogesh-vocal-music-audio
- Repository: https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio

## Overview

VMA packages already-separated audio streams in a V1 PCM-WAV container, serves creation/open/info/validation/extraction through a local FastAPI app, and provides synchronized browser playback with independent stream controls. The library also implements a separate V2 opaque-byte container and format-identification registry, but V2 has no application/API workflow. Edges reflect README statements or the supplied excerpts/SOURCE INDEX; frontend-to-HTTP wiring and unsampled V1/V2 internals are not mapped beyond documented behavior.

Main entry points: [`backend/vma/reader.py`](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/reader.py) (V1 Reader), [`backend/vma/v2/reader.py`](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/reader.py) (V2 Reader), [`backend/app/main.py`](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/main.py) (FastAPI Routes), [`backend/app/vma_service.py`](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/vma_service.py) (Upload Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_browser["Browser UI<br/>[app.js]"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_service["Upload Adapter<br/>[vma_service.py]"]
  node_session[("Temporary Sessions<br/>[main.py]")]
end

subgraph group_v1["V1 Audio Container"]
  node_wavparse["WAV Parser<br/>[audio.py]"]
  node_v1writer["V1 Writer<br/>[writer.py]"]
  node_v1reader["V1 Reader<br/>[reader.py]"]
  node_v1extract["V1 Extractor<br/>[extractor.py]"]
  node_v1validate["V1 Validator<br/>[validator.py]"]
  node_v1format["V1 Layout<br/>[format.py]"]
  node_v1models["V1 Models<br/>[models.py]"]
end

subgraph group_v2["V2 Opaque Container"]
  node_v2writer["V2 Writer<br/>[writer.py]"]
  node_v2reader["V2 Reader<br/>[reader.py]"]
  node_v2extract["V2 Extractor<br/>[extractor.py]"]
  node_v2validate["V2 Validator<br/>[validator.py]"]
  node_v2wire["Wire Encoding<br/>[wire.py]"]
  node_v2info["Format Info TLV<br/>[format_info.py]"]
  node_v2models["V2 Models<br/>[models.py]"]
  node_dispatch["Version Dispatch<br/>[dispatch.py]"]
end

subgraph group_formats["Format Identification"]
  node_registry[("FORMAT_ID Registry<br/>[registry.py]")]
  node_formatmodels["Registry Models<br/>[models.py]"]
  node_identify["Format Recognition<br/>[identify.py]"]
  node_riff["RIFF/WAVE Check<br/>[riff_wave.py]"]
  node_waveprobe["Wave Probe<br/>[wave_probe.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_browser
node_browser -->|"requests routes"| node_api
node_api -->|"delegates uploads"| node_service
node_api -->|"stores sessions"| node_session
node_service -->|"creates container"| node_v1writer
node_service -->|"reads container"| node_v1reader
node_service -->|"validates container"| node_v1validate
node_service -->|"extracts streams"| node_v1extract
node_api -->|"opens container"| node_v1reader
node_api -->|"extracts tracks"| node_v1extract
node_v1writer -->|"parses WAV"| node_wavparse
node_v1reader -->|"uses layout"| node_v1format
node_v1reader -->|"builds models"| node_v1models
node_v1writer -->|"uses layout"| node_v1format
node_v1writer -->|"uses models"| node_v1models
node_wavparse -->|"uses WAV layout"| node_v1format
node_wavparse -->|"builds audio model"| node_v1models
node_v1extract -->|"reads container"| node_v1reader
node_v1validate -->|"validates via read"| node_v1reader
node_dispatch -->|"routes V1"| node_v1reader
node_dispatch -->|"routes V2"| node_v2reader
node_v2writer -->|"encodes fields"| node_v2wire
node_v2writer -->|"serializes TLVs"| node_v2info
node_v2reader -->|"decodes fields"| node_v2wire
node_v2reader -->|"parses TLVs"| node_v2info
node_v2reader -->|"builds models"| node_v2models
node_v2writer -->|"uses models"| node_v2models
node_v2extract -->|"reads container"| node_v2reader
node_v2validate -->|"validates via read"| node_v2reader
node_registry -->|"uses entries"| node_formatmodels
node_identify -->|"looks up IDs"| node_registry
node_identify -->|"recognizes RIFF"| node_riff
node_waveprobe -->|"uses registry"| node_registry
node_waveprobe -->|"probes RIFF"| node_riff
node_waveprobe -->|"returns models"| node_formatmodels

click node_browser "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/frontend/js/app.js"
click node_api "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/main.py"
click node_service "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/vma_service.py"
click node_session "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/main.py"
click node_wavparse "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/audio.py"
click node_v1writer "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/writer.py"
click node_v1reader "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/reader.py"
click node_v1extract "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/extractor.py"
click node_v1validate "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/validator.py"
click node_v1format "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/format.py"
click node_v1models "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/models.py"
click node_v2writer "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/writer.py"
click node_v2reader "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/reader.py"
click node_v2extract "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/extractor.py"
click node_v2validate "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/validator.py"
click node_v2wire "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/wire.py"
click node_v2info "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/format_info.py"
click node_v2models "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/models.py"
click node_dispatch "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/dispatch.py"
click node_registry "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/registry.py"
click node_formatmodels "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/models.py"
click node_identify "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/identify.py"
click node_riff "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/riff_wave.py"
click node_waveprobe "https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/wave_probe.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_browser,node_api,node_service,node_session,node_user toneBlue
class node_wavparse,node_v1writer,node_v1reader,node_v1extract,node_v1validate,node_v1format,node_v1models toneAmber
class node_v2writer,node_v2reader,node_v2extract,node_v2validate,node_v2wire,node_v2info,node_v2models,node_dispatch toneMint
class node_registry,node_formatmodels,node_identify,node_riff,node_waveprobe toneRose
```

## Components

### Application

- [Browser UI](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [FastAPI Routes](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/main.py): `backend/app/main.py`
- [Upload Adapter](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/vma_service.py): `backend/app/vma_service.py`
- [Temporary Sessions](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/app/main.py): `backend/app/main.py`

### V1 Audio Container

- [WAV Parser](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/audio.py): `backend/vma/audio.py`
- [V1 Writer](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/writer.py): `backend/vma/writer.py`
- [V1 Reader](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/reader.py): `backend/vma/reader.py`
- [V1 Extractor](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/extractor.py): `backend/vma/extractor.py`
- [V1 Validator](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/validator.py): `backend/vma/validator.py`
- [V1 Layout](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/format.py): `backend/vma/format.py`
- [V1 Models](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/models.py): `backend/vma/models.py`

### V2 Opaque Container

- [V2 Writer](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/writer.py): `backend/vma/v2/writer.py`
- [V2 Reader](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/reader.py): `backend/vma/v2/reader.py`
- [V2 Extractor](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/extractor.py): `backend/vma/v2/extractor.py`
- [V2 Validator](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/validator.py): `backend/vma/v2/validator.py`
- [Wire Encoding](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/wire.py): `backend/vma/v2/wire.py`
- [Format Info TLV](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/format_info.py): `backend/vma/v2/format_info.py`
- [V2 Models](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/v2/models.py): `backend/vma/v2/models.py`
- [Version Dispatch](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/dispatch.py): `backend/vma/dispatch.py`

### Format Identification

- [FORMAT_ID Registry](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/registry.py): `backend/vma/formats/registry.py`
- [Registry Models](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/models.py): `backend/vma/formats/models.py`
- [Format Recognition](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/identify.py): `backend/vma/formats/identify.py`
- [RIFF/WAVE Check](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/riff_wave.py): `backend/vma/formats/riff_wave.py`
- [Wave Probe](https://github.com/yogesh-yogi-s/yogesh-vocal-music-audio/blob/main/backend/vma/formats/wave_probe.py): `backend/vma/formats/wave_probe.py`

### Other components

- **User**

## Connections

- User → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI Routes: requests routes (evidence: `README.md`)
- FastAPI Routes → Upload Adapter: delegates uploads (evidence: `backend/app/main.py`)
- FastAPI Routes → Temporary Sessions: stores sessions (evidence: `backend/app/main.py`)
- Upload Adapter → V1 Writer: creates container (evidence: `backend/app/vma_service.py`)
- Upload Adapter → V1 Reader: reads container (evidence: `backend/app/vma_service.py`)
- Upload Adapter → V1 Validator: validates container (evidence: `backend/app/vma_service.py`)
- Upload Adapter → V1 Extractor: extracts streams (evidence: `backend/app/vma_service.py`)
- FastAPI Routes → V1 Reader: opens container (evidence: `backend/app/main.py`)
- FastAPI Routes → V1 Extractor: extracts tracks (evidence: `backend/app/main.py`)
- V1 Writer → WAV Parser: parses WAV (evidence: `backend/vma/writer.py`)
- V1 Reader → V1 Layout: uses layout (evidence: `backend/vma/reader.py`)
- V1 Reader → V1 Models: builds models (evidence: `backend/vma/reader.py`)
- V1 Writer → V1 Layout: uses layout (evidence: `backend/vma/writer.py`)
- V1 Writer → V1 Models: uses models (evidence: `backend/vma/writer.py`)
- WAV Parser → V1 Layout: uses WAV layout (evidence: `backend/vma/audio.py`)
- WAV Parser → V1 Models: builds audio model (evidence: `backend/vma/audio.py`)
- V1 Extractor → V1 Reader: reads container (evidence: `backend/vma/extractor.py`)
- V1 Validator → V1 Reader: validates via read (evidence: `backend/vma/validator.py`)
- Version Dispatch → V1 Reader: routes V1 (evidence: `backend/vma/dispatch.py`)
- Version Dispatch → V2 Reader: routes V2 (evidence: `backend/vma/dispatch.py`)
- V2 Writer → Wire Encoding: encodes fields (evidence: `backend/vma/v2/writer.py`)
- V2 Writer → Format Info TLV: serializes TLVs (evidence: `backend/vma/v2/writer.py`)
- V2 Reader → Wire Encoding: decodes fields (evidence: `backend/vma/v2/reader.py`)
- V2 Reader → Format Info TLV: parses TLVs (evidence: `backend/vma/v2/reader.py`)
- V2 Reader → V2 Models: builds models (evidence: `backend/vma/v2/reader.py`)
- V2 Writer → V2 Models: uses models (evidence: `backend/vma/v2/writer.py`)
- V2 Extractor → V2 Reader: reads container (evidence: `backend/vma/v2/extractor.py`)
- V2 Validator → V2 Reader: validates via read (evidence: `backend/vma/v2/validator.py`)
- FORMAT_ID Registry → Registry Models: uses entries (evidence: `backend/vma/formats/registry.py`)
- Format Recognition → FORMAT_ID Registry: looks up IDs (evidence: `backend/vma/formats/identify.py`)
- Format Recognition → RIFF/WAVE Check: recognizes RIFF (evidence: `backend/vma/formats/identify.py`)
- Wave Probe → FORMAT_ID Registry: uses registry (evidence: `backend/vma/formats/wave_probe.py`)
- Wave Probe → RIFF/WAVE Check: probes RIFF (evidence: `backend/vma/formats/wave_probe.py`)
- Wave Probe → Registry Models: returns models (evidence: `backend/vma/formats/wave_probe.py`)
