# kris-gupta/sonata architecture

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

- Interactive diagram: https://gitdiagram.com/kris-gupta/sonata
- Repository: https://github.com/kris-gupta/sonata

## Overview

Sonata is a command-line audio streamer: a user supplies a media URL, the program resolves an audio URL with yt-dlp, downloads byte ranges, decodes the audio, and plays samples through the system audio device. Its main implementation is concentrated in `src/main.rs`, with reader and buffer types in `src/audio/reader.rs`. A small terminal UI is also present, but the sampled entry point does not show it being connected to playback. The README is empty, and excerpts omit some orchestration details, so only supported runtime links are shown.

Main entry points: [`src/main.rs`](https://github.com/kris-gupta/sonata/blob/main/src/main.rs) (CLI orchestration), [`src/audio/reader.rs`](https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs) (Streaming buffers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_main["CLI orchestration<br/>[main.rs]"]
  node_resolver["yt-dlp resolver"]
end

subgraph group_stream["Streaming and decode"]
  node_fetch["Range fetcher<br/>[main.rs]"]
  node_ranges["Chunk iterator<br/>[reader.rs]"]
  node_streambuf["Streaming buffers<br/>[reader.rs]"]
  node_decode["Audio decoder<br/>[main.rs]"]
  node_mediareader["Media source reader<br/>[reader.rs]"]
  node_decodebuf["Decoded sample buffers<br/>[reader.rs]"]
end

subgraph group_output["Playback and interface"]
  node_playback["Audio playback<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[tui.rs]"]
end

node_user(("User"))
node_http["Media host"]
node_device["Audio output device"]

node_user -->|"provides URL"| node_main
node_main -->|"resolves stream"| node_resolver
node_resolver -->|"returns audio URL"| node_main
node_main -->|"starts thread"| node_fetch
node_main -->|"starts thread"| node_decode
node_main -->|"starts thread"| node_playback
node_fetch -->|"requests byte ranges"| node_http
node_fetch -->|"iterates chunks"| node_ranges
node_fetch -->|"writes bytes"| node_streambuf
node_decode -->|"reads bytes"| node_streambuf
node_decode -->|"builds media source"| node_mediareader
node_decode -->|"writes samples"| node_decodebuf
node_playback -->|"reads samples"| node_decodebuf
node_playback -->|"outputs audio"| node_device

click node_main "https://github.com/kris-gupta/sonata/blob/main/src/main.rs"
click node_fetch "https://github.com/kris-gupta/sonata/blob/main/src/main.rs"
click node_ranges "https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs"
click node_streambuf "https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs"
click node_decode "https://github.com/kris-gupta/sonata/blob/main/src/main.rs"
click node_mediareader "https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs"
click node_decodebuf "https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs"
click node_playback "https://github.com/kris-gupta/sonata/blob/main/src/main.rs"
click node_tui "https://github.com/kris-gupta/sonata/blob/main/src/audio/tui.rs"

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_main,node_resolver,node_user toneBlue
class node_fetch,node_ranges,node_streambuf,node_decode,node_mediareader,node_decodebuf toneAmber
class node_playback,node_tui toneMint
class node_http,node_device toneIndigo
```

## Components

### Entry and orchestration

- [CLI orchestration](https://github.com/kris-gupta/sonata/blob/main/src/main.rs): `src/main.rs`
- **yt-dlp resolver**

### Streaming and decode

- [Range fetcher](https://github.com/kris-gupta/sonata/blob/main/src/main.rs): `src/main.rs`
- [Chunk iterator](https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs): `src/audio/reader.rs`
- [Streaming buffers](https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs): `src/audio/reader.rs`
- [Audio decoder](https://github.com/kris-gupta/sonata/blob/main/src/main.rs): `src/main.rs`
- [Media source reader](https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs): `src/audio/reader.rs`
- [Decoded sample buffers](https://github.com/kris-gupta/sonata/blob/main/src/audio/reader.rs): `src/audio/reader.rs`

### Playback and interface

- [Audio playback](https://github.com/kris-gupta/sonata/blob/main/src/main.rs): `src/main.rs`
- [Terminal UI](https://github.com/kris-gupta/sonata/blob/main/src/audio/tui.rs): `src/audio/tui.rs`

### Other components

- **User**
- **Media host**
- **Audio output device**

## Connections

- User → CLI orchestration: provides URL
- CLI orchestration → yt-dlp resolver: resolves stream
- yt-dlp resolver → CLI orchestration: returns audio URL
- CLI orchestration → Range fetcher: starts thread
- CLI orchestration → Audio decoder: starts thread
- CLI orchestration → Audio playback: starts thread
- Range fetcher → Media host: requests byte ranges
- Range fetcher → Chunk iterator: iterates chunks
- Range fetcher → Streaming buffers: writes bytes
- Audio decoder → Streaming buffers: reads bytes
- Audio decoder → Media source reader: builds media source
- Audio decoder → Decoded sample buffers: writes samples
- Audio playback → Decoded sample buffers: reads samples
- Audio playback → Audio output device: outputs audio