# vandorb12/sloproom architecture

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

- Interactive diagram: https://gitdiagram.com/vandorb12/sloproom
- Repository: https://github.com/vandorb12/sloproom
- Video tour (about a minute): https://gitdiagram.com/vandorb12/sloproom/video

## Overview

Sloproom is research software for encoding Type B HDCD control signals into stereo audio, then checking the result against FFmpeg. The main workflow runs through the single-file encoder: read audio, prepare its gain and optional PE/LLE processing, plan controls, quantize, inject packets, and write a WAV. Separate tools verify files and inspect decoder effects, including a read-only interactive visualizer. The README documents capabilities beyond the sampled excerpts; paths and links for those capabilities are included only where supported by the tree and evidence.

Main entry points: [`hdcd_encoder.py`](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py) (Encoder CLI), [`hdcd_verify.py`](https://github.com/vandorb12/sloproom/blob/master/hdcd_verify.py) (HDCD verifier), [`hdcd_visualizer.py`](https://github.com/vandorb12/sloproom/blob/master/hdcd_visualizer.py) (Decode-impact reports), [`hdcd_interactive_visualizer.py`](https://github.com/vandorb12/sloproom/blob/master/hdcd_interactive_visualizer.py) (Interactive visualizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_encoding["Audio encoding"]
  node_encoder_cli["Encoder CLI<br/>[hdcd_encoder.py]"]
  node_audio_ingest["Audio ingest<br/>[hdcd_encoder.py]"]
  node_gain_planning["Gain planning<br/>[hdcd_encoder.py]"]
  node_pe_lle_dsp["PE and LLE DSP<br/>[hdcd_encoder.py]"]
  node_control_timeline["Control timeline<br/>[hdcd_encoder.py]"]
  node_quantization["Quantize and dither<br/>[hdcd_encoder.py]"]
  node_packet_injection["Type B injection<br/>[hdcd_encoder.py]"]
end

subgraph group_verification["Verification"]
  node_verifier["HDCD verifier<br/>[hdcd_verify.py]"]
end

subgraph group_inspection["Audio inspection"]
  node_static_visualizer["Decode-impact reports<br/>[hdcd_visualizer.py]"]
  node_interactive_visualizer["Interactive visualizer"]
  node_inspection_core["Inspection and PE preview"]
end

node_user(("Encoder user"))
node_source_audio["Source audio"]
node_wav_output["Encoded WAV"]
node_ffmpeg["FFmpeg hdcd"]

node_user -->|"runs"| node_encoder_cli
node_source_audio -->|"supplies"| node_encoder_cli
node_encoder_cli -->|"loads"| node_audio_ingest
node_encoder_cli -->|"plans gain"| node_gain_planning
node_encoder_cli -->|"applies DSP"| node_pe_lle_dsp
node_encoder_cli -->|"plans controls"| node_control_timeline
node_encoder_cli -->|"quantizes"| node_quantization
node_encoder_cli -->|"injects packets"| node_packet_injection
node_encoder_cli -->|"writes"| node_wav_output
node_user -->|"runs"| node_verifier
node_wav_output -->|"checks"| node_verifier
node_verifier -->|"runs decoder"| node_ffmpeg
node_user -->|"runs"| node_static_visualizer
node_wav_output -->|"inspects"| node_static_visualizer
node_static_visualizer -->|"decodes"| node_ffmpeg
node_user -->|"opens file"| node_interactive_visualizer
node_interactive_visualizer -->|"requests analysis"| node_inspection_core
node_inspection_core -->|"decodes carrier"| node_ffmpeg

click node_encoder_cli "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_audio_ingest "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_gain_planning "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_pe_lle_dsp "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_control_timeline "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_quantization "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_packet_injection "https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py"
click node_verifier "https://github.com/vandorb12/sloproom/blob/master/hdcd_verify.py"
click node_static_visualizer "https://github.com/vandorb12/sloproom/blob/master/hdcd_visualizer.py"
click node_interactive_visualizer "https://github.com/vandorb12/sloproom/blob/master/hdcd_interactive_visualizer.py"
click node_inspection_core "https://github.com/vandorb12/sloproom/blob/master/hdcd_interactive_core.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_encoder_cli,node_audio_ingest,node_gain_planning,node_pe_lle_dsp,node_control_timeline,node_quantization,node_packet_injection,node_user toneBlue
class node_verifier toneAmber
class node_static_visualizer,node_interactive_visualizer,node_inspection_core toneMint
class node_source_audio,node_wav_output,node_ffmpeg toneIndigo
```

## Components

### Audio encoding

- [Encoder CLI](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [Audio ingest](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [Gain planning](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [PE and LLE DSP](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [Control timeline](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [Quantize and dither](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`
- [Type B injection](https://github.com/vandorb12/sloproom/blob/master/hdcd_encoder.py): `hdcd_encoder.py`

### Verification

- [HDCD verifier](https://github.com/vandorb12/sloproom/blob/master/hdcd_verify.py): `hdcd_verify.py`

### Audio inspection

- [Decode-impact reports](https://github.com/vandorb12/sloproom/blob/master/hdcd_visualizer.py): `hdcd_visualizer.py`
- [Interactive visualizer](https://github.com/vandorb12/sloproom/blob/master/hdcd_interactive_visualizer.py): `hdcd_interactive_visualizer.py`
- [Inspection and PE preview](https://github.com/vandorb12/sloproom/blob/master/hdcd_interactive_core.py): `hdcd_interactive_core.py`

### Other components

- **Encoder user**
- **Source audio**
- **Encoded WAV**
- **FFmpeg hdcd**

## Connections

- Encoder user → Encoder CLI: runs
- Source audio → Encoder CLI: supplies
- Encoder CLI → Audio ingest: loads
- Encoder CLI → Gain planning: plans gain
- Encoder CLI → PE and LLE DSP: applies DSP
- Encoder CLI → Control timeline: plans controls
- Encoder CLI → Quantize and dither: quantizes
- Encoder CLI → Type B injection: injects packets
- Encoder CLI → Encoded WAV: writes
- Encoder user → HDCD verifier: runs
- Encoded WAV → HDCD verifier: checks
- HDCD verifier → FFmpeg hdcd: runs decoder
- Encoder user → Decode-impact reports: runs
- Encoded WAV → Decode-impact reports: inspects
- Decode-impact reports → FFmpeg hdcd: decodes
- Encoder user → Interactive visualizer: opens file
- Interactive visualizer → Inspection and PE preview: requests analysis
- Inspection and PE preview → FFmpeg hdcd: decodes carrier