Architecture

How Rockbox C, Rust and Zig fit together inside one rockboxd binary.

Clients

Web UI · GTK · GPUI · macOS (Swift) · TUI · REPL · MPD · MPRIS

Protocols

gRPC :6061 · GraphQL :6062 · REST :6063 · MPD :6600

Rust services

playback · library · settings · search · playlists · airplay · slim · chromecast · upnp · netstream · cpal-sink · bluetooth · discovery

Rockbox C

audio engine · DSP · codecs · tag database

PCM sinks

cpal · fifo · airplay · squeezelite · chromecast · snapcast_tcp · upnp

The entire system ships as one binary, rockboxd, produced by Zig’s linker. There’s no separate “rockbox-server” service, no per-feature sidecar, no IPC.

What links into the binary

Artifact	Built by	Notes
build-lib/libfirmware.a	Make	Rockbox C audio engine + DSP
build-lib/librockbox.a	Make	App layer (playlist, database, plugins)
Codec libraries (librbcodec.a, …)	Make	rbcodec + fixedpoint + skin parser
target/release/librockbox_cli.a	Cargo	CLI entry point + Rust output sinks (incl. cpal-sink)
target/release/librockbox_server.a	Cargo	gRPC, GraphQL, HTTP (Actix-web), MPD servers
zig/zig-out/lib/librockboxd.a	Zig	Fat static archive for embedding in desktop GUIs (zig build lib)

The Zig build script (zig/build.zig) glues them together, ensuring force-included symbols stay in the staticlib through the link.

Repository layout

firmware/          Rockbox C firmware (audio engine, codecs, DSP)
  target/hosted/
    headless/      Headless host target — POSIX threads, CPAL audio, no SDL
    sdl/           SDL host target (legacy; still used for the SDL rockboxd build)
apps/              Rockbox application layer (playlist, database, plugins)
lib/               Codec libraries (rbcodec, fixedpoint, skin_parser, tlsf)
build-lib/         Out-of-tree Make build directory (generated; do not edit)
build-headless/    Headless Make build directory (no SDL)
include/           Public C header (rockboxd.h) for the embeddable library
crates/            Rust workspace
  airplay/         ALAC encoder + RAOP/RTP sender
  slim/            Slim Protocol + HTTP broadcast (squeezelite multi-room)
  cli/             Compiled to librockbox_cli.a (staticlib)
  embed/           Embeddable desktop library — daemon boot + C ABI rb_* exports
  server/          gRPC / HTTP (Actix-web) server
  settings/        load_settings() — reads settings.toml, applies sinks
  sys/             FFI bindings to the C firmware
  library/         SQLite library management
  cpal-sink/       CPAL audio sink (CoreAudio / WASAPI / ALSA)
  fts5/            SQLite FTS5 search backend (feature-flag alternative to Typesense)
  typesense/       Typesense client for search
  netstream/       HTTP streaming (Range-request fd multiplexing)
  chromecast/      Chromecast output
  rpc/             gRPC definitions / generated code
  graphql/         GraphQL schema and resolvers
  mpd/             MPD protocol server
  mpris/           MPRIS D-Bus integration
  playlists/       Playlist management
  tracklist/       Tracklist management
  bluetooth/       Bluetooth pairing and control
  discovery/       mDNS / LAN device discovery
  upnp/            UPnP/DLNA support
  rocksky/         Rocksky cloud sync / remote agent
  types/           Shared Rust types
  traits/          Shared Rust traits
zig/               Zig build script, main.zig (executable), lib.zig (embedded lib)
sdk/               Client SDKs (TypeScript, Python, Ruby, Elixir, Clojure, Gleam)
webui/rockbox/     React web UI — Tailwind CSS, built into the binary
gpui/              Desktop client (GPUI / Rust) — embeds daemon via librockboxd.a
macos/             Native macOS client (Swift / Xcode) — embeds daemon via librockboxd.a
gtk/               GTK4 desktop client

Cross-cutting concerns

macOS CPAL audio

CPAL uses CoreAudio natively on macOS. The built-in sink implementation lives in firmware/target/hosted/headless/pcm-cpal.c (C side) and crates/cpal-sink/ (Rust side, ring buffer + resampler). No extra initialisation is required beyond what CPAL performs at stream open time.

SIGTERM handling

crates/cli/src/lib.rs overrides SIGTERM/SIGINT to kill the typesense child process and _exit(0). The default Rockbox handler in system-hosted.c would otherwise loop forever waiting for a quit event from the audio subsystem.

Typesense subprocess

Typesense is spawned with Stdio::piped() and its stdout/stderr lines are forwarded to tracing in background threads — this keeps the PCM stdout stream clean when running in fifo_path = "-" mode.

HTTP streaming for cloud sources

HTTP file descriptors are encoded as values ≤ -1000 (the STREAM_HTTP_FD_BASE constant). stream_open/read/lseek/close in crates/netstream/ dispatch between HTTP and POSIX based on fd value, so the rest of the firmware doesn’t know it’s reading from the network.