# lieff/minimp3 architecture

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

- Interactive diagram: https://gitdiagram.com/lieff/minimp3
- Repository: https://github.com/lieff/minimp3

## Overview

minimp3 is a compact, single-header MP1/MP2/MP3 decoder; its optional high-level API adds file/buffer decoding, precise seeking, and track-length detection. The main user workflow supplies MP3 bytes and receives decoded PCM, while the bundled SDL player adds playlist selection and playback. The graph also preserves the player’s UI, rendering, image, font, and platform-support components. Core decode and player call paths are supported by excerpts; high-level API relationships are documented in the README, while some player internals were not sampled.

Main entry points: [`player/player.cpp`](https://github.com/lieff/minimp3/blob/master/player/player.cpp) (Player App), [`minimp3.h`](https://github.com/lieff/minimp3/blob/master/minimp3.h) (Frame Decoder), [`player/audio_sdl.c`](https://github.com/lieff/minimp3/blob/master/player/audio_sdl.c) (SDL Audio Output), [`player/decode.c`](https://github.com/lieff/minimp3/blob/master/player/decode.c) (Player Decoder Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_decoder["Decoder Library"]
  node_core["Frame Decoder<br/>[minimp3.h]"]
end

subgraph group_highlevel["Stream API"]
  node_ex["High-Level Decoder<br/>[minimp3_ex.h]"]
end

subgraph group_player["SDL Player"]
  node_app["Player App<br/>[player.cpp]"]
  node_adapter["Player Decoder Adapter<br/>[decode.c]"]
  node_decoder_api["Player Decoder API<br/>[decode.h]"]
  node_audio["SDL Audio Output<br/>[audio_sdl.c]"]
  node_audio_api["Audio API<br/>[audio_sdl.h]"]
  node_platform["Platform Primitives<br/>[system.cpp]"]
  node_platform_api["Platform API<br/>[system.h]"]
end

subgraph group_ui["Player UI"]
  node_ui_toolkit["Nuklear UI Backend<br/>[nuklear_sdl_gl3.h]"]
  node_ui_core["Nuklear UI<br/>[nuklear.h]"]
  node_theme["Theme Styling<br/>[style.h]"]
  node_font["Embedded Font<br/>[FreeSans.h]"]
  node_images["Image Loading<br/>[stb_image.h]"]
  node_graphics["OpenGL Loader<br/>[glad.h]"]
end

node_input(("MP3 Input"))
node_sound(("Audio Device"))

node_input -->|"decodes frames"| node_core
node_core -->|"consumes bytes"| node_input
node_core -->|"supports API"| node_ex
node_app -->|"opens track"| node_adapter
node_app -->|"controls output"| node_audio_api
node_audio_api -->|"declares interface"| node_audio
node_audio -->|"requests samples"| node_adapter
node_audio -.->|"plays PCM"| node_sound
node_app -->|"renders UI"| node_ui_toolkit
node_ui_toolkit -.->|"uses toolkit"| node_ui_core
node_app -->|"sets theme"| node_theme
node_app -->|"loads font"| node_font
node_app -.->|"loads images"| node_images
node_app -->|"uses graphics"| node_graphics
node_adapter -->|"implements API"| node_decoder_api
node_decoder_api -->|"includes API"| node_ex
node_app -.->|"uses primitives"| node_platform_api
node_platform_api -->|"implemented by"| node_platform

click node_core "https://github.com/lieff/minimp3/blob/master/minimp3.h"
click node_ex "https://github.com/lieff/minimp3/blob/master/minimp3_ex.h"
click node_app "https://github.com/lieff/minimp3/blob/master/player/player.cpp"
click node_adapter "https://github.com/lieff/minimp3/blob/master/player/decode.c"
click node_decoder_api "https://github.com/lieff/minimp3/blob/master/player/decode.h"
click node_audio "https://github.com/lieff/minimp3/blob/master/player/audio_sdl.c"
click node_audio_api "https://github.com/lieff/minimp3/blob/master/player/audio_sdl.h"
click node_ui_toolkit "https://github.com/lieff/minimp3/blob/master/player/nuklear_sdl_gl3.h"
click node_ui_core "https://github.com/lieff/minimp3/blob/master/player/nuklear.h"
click node_theme "https://github.com/lieff/minimp3/blob/master/player/style.h"
click node_font "https://github.com/lieff/minimp3/blob/master/player/FreeSans.h"
click node_images "https://github.com/lieff/minimp3/blob/master/player/stb_image.h"
click node_graphics "https://github.com/lieff/minimp3/blob/master/player/glad.h"
click node_platform "https://github.com/lieff/minimp3/blob/master/player/system.cpp"
click node_platform_api "https://github.com/lieff/minimp3/blob/master/player/system.h"

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_core toneBlue
class node_ex toneAmber
class node_app,node_adapter,node_decoder_api,node_audio,node_audio_api,node_platform,node_platform_api toneMint
class node_ui_toolkit,node_ui_core,node_theme,node_font,node_images,node_graphics toneRose
class node_input,node_sound toneIndigo
```

## Components

### Decoder Library

- [Frame Decoder](https://github.com/lieff/minimp3/blob/master/minimp3.h): `minimp3.h`

### Stream API

- [High-Level Decoder](https://github.com/lieff/minimp3/blob/master/minimp3_ex.h): `minimp3_ex.h`

### SDL Player

- [Player App](https://github.com/lieff/minimp3/blob/master/player/player.cpp): `player/player.cpp`
- [Player Decoder Adapter](https://github.com/lieff/minimp3/blob/master/player/decode.c): `player/decode.c`
- [Player Decoder API](https://github.com/lieff/minimp3/blob/master/player/decode.h): `player/decode.h`
- [SDL Audio Output](https://github.com/lieff/minimp3/blob/master/player/audio_sdl.c): `player/audio_sdl.c`
- [Audio API](https://github.com/lieff/minimp3/blob/master/player/audio_sdl.h): `player/audio_sdl.h`
- [Platform Primitives](https://github.com/lieff/minimp3/blob/master/player/system.cpp): `player/system.cpp`
- [Platform API](https://github.com/lieff/minimp3/blob/master/player/system.h): `player/system.h`

### Player UI

- [Nuklear UI Backend](https://github.com/lieff/minimp3/blob/master/player/nuklear_sdl_gl3.h): `player/nuklear_sdl_gl3.h`
- [Nuklear UI](https://github.com/lieff/minimp3/blob/master/player/nuklear.h): `player/nuklear.h`
- [Theme Styling](https://github.com/lieff/minimp3/blob/master/player/style.h): `player/style.h`
- [Embedded Font](https://github.com/lieff/minimp3/blob/master/player/FreeSans.h): `player/FreeSans.h`
- [Image Loading](https://github.com/lieff/minimp3/blob/master/player/stb_image.h): `player/stb_image.h`
- [OpenGL Loader](https://github.com/lieff/minimp3/blob/master/player/glad.h): `player/glad.h`

### Other components

- **MP3 Input**
- **Audio Device**

## Connections

- MP3 Input → Frame Decoder: decodes frames (evidence: `README.md`)
- Frame Decoder → MP3 Input: consumes bytes (evidence: `README.md`)
- Frame Decoder → High-Level Decoder: supports API (evidence: `README.md`)
- Player App → Player Decoder Adapter: opens track (evidence: `player/player.cpp`)
- Player App → Audio API: controls output (evidence: `player/player.cpp`)
- Audio API → SDL Audio Output: declares interface (evidence: `player/audio_sdl.h`)
- SDL Audio Output → Player Decoder Adapter: requests samples (evidence: `player/audio_sdl.c`)
- SDL Audio Output → Audio Device: plays PCM
- Player App → Nuklear UI Backend: renders UI (evidence: `player/player.cpp`)
- Nuklear UI Backend → Nuklear UI: uses toolkit
- Player App → Theme Styling: sets theme (evidence: `player/player.cpp`)
- Player App → Embedded Font: loads font (evidence: `player/player.cpp`)
- Player App → Image Loading: loads images (evidence: `player/player.cpp`)
- Player App → OpenGL Loader: uses graphics (evidence: `player/player.cpp`)
- Player Decoder Adapter → Player Decoder API: implements API (evidence: `player/decode.c`)
- Player Decoder API → High-Level Decoder: includes API (evidence: `player/decode.h`)
- Player App → Platform API: uses primitives
- Platform API → Platform Primitives: implemented by (evidence: `player/system.cpp`)
