# colorgarden/ccnbslib architecture

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

- Interactive diagram: https://gitdiagram.com/colorgarden/ccnbslib
- Repository: https://github.com/colorgarden/ccnbslib

## Overview

CCNBSLib is a Lua library for decoding Note Block Studio files, analyzing and planning songs, and scheduling notes on CC:Tweaked speakers. Its principal workflow is bytes → decode → analyze → plan → play; the optional `nbsplay` example fetches a URL and uses the library to play it. The README documents these public stages and capabilities, but no source excerpts were provided, so internal module-to-module calls are not inferred.

Main entry points: [`nbsplay.lua`](https://github.com/colorgarden/ccnbslib/blob/main/nbsplay.lua) (NBS CLI Player), [`nbs/decode.lua`](https://github.com/colorgarden/ccnbslib/blob/main/nbs/decode.lua) (NBS Decode), [`nbs/analyze.lua`](https://github.com/colorgarden/ccnbslib/blob/main/nbs/analyze.lua) (Song Analysis), [`player/runtime.lua`](https://github.com/colorgarden/ccnbslib/blob/main/player/runtime.lua) (Playback Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Song Library"]
  node_decode["NBS Decode<br/>[decode.lua]"]
  node_reader["Binary Reader<br/>[reader.lua]"]
  node_header["Song Header<br/>[header.lua]"]
  node_layers["Song Layers<br/>[layers.lua]"]
  node_notes["Song Notes<br/>[notes.lua]"]
  node_analyze["Song Analysis<br/>[analyze.lua]"]
  node_plan["Event Planning<br/>[plan.lua]"]
  node_cp1252["CP1252 Display<br/>[cp1252.lua]"]
end

subgraph group_playback["Playback"]
  node_play["Playback Session<br/>[runtime.lua]"]
  node_dispatch["Event Dispatch<br/>[dispatch.lua]"]
  node_tempo["Tempo Timing<br/>[tempo.lua]"]
  node_clock["Playback Clock<br/>[clock.lua]"]
  node_mapping["Speaker Mapping<br/>[mapping.lua]"]
  node_fanout["Note Fanout<br/>[fanout.lua]"]
  node_speaker["Speaker Output<br/>[speaker.lua]"]
end

subgraph group_cli["CLI Example"]
  node_nbsplay["NBS CLI Player<br/>[nbsplay.lua]"]
end

node_caller(("Library Caller"))
node_bytes["Song Bytes"]
node_external_speakers["CC Speaker"]
node_http["HTTP Service"]

node_caller -->|"provides"| node_bytes
node_bytes -->|"decodes"| node_decode
node_caller -->|"analyzes"| node_analyze
node_decode -->|"returns song"| node_analyze
node_caller -->|"plans events"| node_plan
node_analyze -->|"supplies analysis"| node_plan
node_caller -->|"starts playback"| node_play
node_play -->|"plays notes"| node_external_speakers
node_nbsplay -->|"fetches song"| node_http
node_nbsplay -->|"decodes bytes"| node_decode
node_nbsplay -->|"plays song"| node_play
node_caller -->|"converts display"| node_cp1252

click node_decode "https://github.com/colorgarden/ccnbslib/blob/main/nbs/decode.lua"
click node_reader "https://github.com/colorgarden/ccnbslib/blob/main/nbs/reader.lua"
click node_header "https://github.com/colorgarden/ccnbslib/blob/main/nbs/header.lua"
click node_layers "https://github.com/colorgarden/ccnbslib/blob/main/nbs/layers.lua"
click node_notes "https://github.com/colorgarden/ccnbslib/blob/main/nbs/notes.lua"
click node_analyze "https://github.com/colorgarden/ccnbslib/blob/main/nbs/analyze.lua"
click node_plan "https://github.com/colorgarden/ccnbslib/blob/main/player/plan.lua"
click node_cp1252 "https://github.com/colorgarden/ccnbslib/blob/main/nbs/cp1252.lua"
click node_play "https://github.com/colorgarden/ccnbslib/blob/main/player/runtime.lua"
click node_dispatch "https://github.com/colorgarden/ccnbslib/blob/main/player/dispatch.lua"
click node_tempo "https://github.com/colorgarden/ccnbslib/blob/main/player/tempo.lua"
click node_clock "https://github.com/colorgarden/ccnbslib/blob/main/player/clock.lua"
click node_mapping "https://github.com/colorgarden/ccnbslib/blob/main/player/mapping.lua"
click node_fanout "https://github.com/colorgarden/ccnbslib/blob/main/player/fanout.lua"
click node_speaker "https://github.com/colorgarden/ccnbslib/blob/main/player/speaker.lua"
click node_nbsplay "https://github.com/colorgarden/ccnbslib/blob/main/nbsplay.lua"

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_decode,node_reader,node_header,node_layers,node_notes,node_analyze,node_plan,node_cp1252 toneBlue
class node_play,node_dispatch,node_tempo,node_clock,node_mapping,node_fanout,node_speaker toneAmber
class node_nbsplay toneMint
class node_caller,node_bytes,node_external_speakers,node_http toneIndigo
```

## Components

### Song Library

- [NBS Decode](https://github.com/colorgarden/ccnbslib/blob/main/nbs/decode.lua): `nbs/decode.lua`
- [Binary Reader](https://github.com/colorgarden/ccnbslib/blob/main/nbs/reader.lua): `nbs/reader.lua`
- [Song Header](https://github.com/colorgarden/ccnbslib/blob/main/nbs/header.lua): `nbs/header.lua`
- [Song Layers](https://github.com/colorgarden/ccnbslib/blob/main/nbs/layers.lua): `nbs/layers.lua`
- [Song Notes](https://github.com/colorgarden/ccnbslib/blob/main/nbs/notes.lua): `nbs/notes.lua`
- [Song Analysis](https://github.com/colorgarden/ccnbslib/blob/main/nbs/analyze.lua): `nbs/analyze.lua`
- [Event Planning](https://github.com/colorgarden/ccnbslib/blob/main/player/plan.lua): `player/plan.lua`
- [CP1252 Display](https://github.com/colorgarden/ccnbslib/blob/main/nbs/cp1252.lua): `nbs/cp1252.lua`

### Playback

- [Playback Session](https://github.com/colorgarden/ccnbslib/blob/main/player/runtime.lua): `player/runtime.lua`
- [Event Dispatch](https://github.com/colorgarden/ccnbslib/blob/main/player/dispatch.lua): `player/dispatch.lua`
- [Tempo Timing](https://github.com/colorgarden/ccnbslib/blob/main/player/tempo.lua): `player/tempo.lua`
- [Playback Clock](https://github.com/colorgarden/ccnbslib/blob/main/player/clock.lua): `player/clock.lua`
- [Speaker Mapping](https://github.com/colorgarden/ccnbslib/blob/main/player/mapping.lua): `player/mapping.lua`
- [Note Fanout](https://github.com/colorgarden/ccnbslib/blob/main/player/fanout.lua): `player/fanout.lua`
- [Speaker Output](https://github.com/colorgarden/ccnbslib/blob/main/player/speaker.lua): `player/speaker.lua`

### CLI Example

- [NBS CLI Player](https://github.com/colorgarden/ccnbslib/blob/main/nbsplay.lua): `nbsplay.lua`

### Other components

- **Library Caller**
- **Song Bytes**
- **CC Speaker**
- **HTTP Service**

## Connections

- Library Caller → Song Bytes: provides (evidence: `README.md`)
- Song Bytes → NBS Decode: decodes (evidence: `README.md`)
- Library Caller → Song Analysis: analyzes (evidence: `README.md`)
- NBS Decode → Song Analysis: returns song (evidence: `README.md`)
- Library Caller → Event Planning: plans events (evidence: `README.md`)
- Song Analysis → Event Planning: supplies analysis (evidence: `README.md`)
- Library Caller → Playback Session: starts playback (evidence: `README.md`)
- Playback Session → CC Speaker: plays notes (evidence: `README.md`)
- NBS CLI Player → HTTP Service: fetches song (evidence: `README.md`)
- NBS CLI Player → NBS Decode: decodes bytes (evidence: `README.md`)
- NBS CLI Player → Playback Session: plays song (evidence: `README.md`)
- Library Caller → CP1252 Display: converts display (evidence: `README.md`)
