Rockbox open source high quality audio player as a Music Player Daemon
mpris
rockbox
mpd
libadwaita
audio
rust
zig
deno
Rewrite README to add features, quickstart, build
+231
-101
+231
-101
README.md
+231
-101
README.md
···
13
13
14
14
15
15
16
-
A modern take on the [Rockbox](https://www.rockbox.org) open source high quality
17
-
audio player with enhancements in Zig and Rust. This project offers:
18
-
19
-
- gRPC & GraphQL APIs for seamless interaction and control
20
-
- Chromecast support for streaming to your TV
21
-
- [MPD](https://mpd.readthedocs.io/en/stable/protocol.html) server for
22
-
compatibility with existing clients
23
-
- [MPRIS](https://specifications.freedesktop.org/mpris-spec/) support for
24
-
desktop integration
25
-
- TypeScript support for building powerful extensions
26
-
27
-
Take advantage of modern tooling while preserving the core functionality of
28
-
Rockbox.
29
-
30
-
> [!NOTE] **🐲 It is a work in progress and is not yet ready for use. 🏗️🚧**
16
+
A modern take on the [Rockbox](https://www.rockbox.org) open source audio
17
+
player, extended with Rust and Zig. Rockbox Zig exposes the full Rockbox audio
18
+
engine — gapless playback, DSP, 20+ codecs, tag database — through gRPC,
19
+
GraphQL, HTTP, and MPD APIs, and adds multi-room output via AirPlay, Snapcast,
20
+
and Squeezelite.
31
21
32
22
33
23
34
-
35
-
24
+
25
+
36
26
27
+
---
37
28
38
29
## ✨ Features
39
30
40
-
- [x] Zig Build System
41
-
- [x] Rockbox API FFI for Rust
31
+
### Audio output
32
+
- [x] Built-in SDL audio
33
+
- [x] AirPlay (RAOP) — stream to Apple TV, HomePod, Airport Express, shairport-sync
34
+
- [x] Snapcast (FIFO/pipe) — synchronised multi-room via snapserver
35
+
- [x] Squeezelite (Slim Protocol + HTTP broadcast) — synchronised multi-room
36
+
- [x] Chromecast
37
+
- [x] Gapless playback and crossfading
38
+
- [x] Supports 20+ codecs: MP3, OGG, FLAC, WAV, AAC, Opus, and more
39
+
40
+
### APIs & integrations
42
41
- [x] [gRPC API](https://buf.build/tsiry/rockboxapis/docs/main:rockbox.v1alpha1)
43
42
- [x] GraphQL API
44
-
- [x] HTTP API
45
-
- [x] Web Client (React)
46
-
- [x] Fast search engine, built with
47
-
[Typesense](https://typesense.org)
48
-
- [x] Desktop Client (Electron/Gtk)
43
+
- [x] HTTP REST API
44
+
- [x] [MPD](https://mpd.readthedocs.io/en/stable/protocol.html) server — compatible with all MPD clients
45
+
- [x] [MPRIS](https://specifications.freedesktop.org/mpris-spec/) — desktop media key and taskbar integration
46
+
- [x] Fast search powered by [Typesense](https://typesense.org)
47
+
- [x] Navigate by folders or tag database
48
+
49
+
### Clients
50
+
- [x] Web client (React)
51
+
- [x] Desktop client (Electron / GTK4)
52
+
- [x] Terminal client (TUI)
49
53
- [x] Rockbox REPL
50
-
- [x] Terminal Client (TUI)
51
-
- [x] Systemd service
52
-
- [x] Gapless playback and crossfading
53
-
- [x] Navigate music by folders or tag database
54
-
- [x] Supports over 20 sound codecs: MP3, OGG, WAV, FLAC and many more
55
-
- [ ] Android Library
56
-
- [ ] Mobile version (React Native)
57
-
- [ ] Stream from Youtube (audio only)
58
-
- [ ] Stream from Spotify
59
-
- [ ] Stream from Tidal
60
-
- [x] Stream to Chromecast
61
-
- [ ] Stream to Kodi
54
+
55
+
### Planned
56
+
- [ ] Android library
57
+
- [ ] Mobile app (React Native)
58
+
- [ ] Stream from YouTube / Spotify / Tidal
62
59
- [ ] TuneIn Radio
63
-
- [x] MPD Server
64
-
- [x] MPRIS
65
60
- [ ] UPnP/DLNA
66
-
- [x] Airplay
67
-
- [x] Snapcast
68
-
- [x] Slim Protocol
69
-
- [ ] TypeScript ([Deno](https://deno.com)) API (for writing plugins)
61
+
- [ ] Kodi output
62
+
- [ ] TypeScript ([Deno](https://deno.com)) plugin API
70
63
- [ ] Wasm extensions
71
64
65
+
---
66
+
67
+
## 🚀 Quick Start
68
+
69
+
1. **Install** (see [Installation](#-installation) below).
70
+
71
+
2. **Create `~/.config/rockbox.org/settings.toml`**:
72
+
73
+
```toml
74
+
music_dir = "/path/to/your/Music"
75
+
audio_output = "builtin" # SDL audio — see Audio Output for other options
76
+
```
77
+
78
+
3. **Run the daemon**:
79
+
80
+
```sh
81
+
rockboxd
82
+
```
83
+
84
+
4. **Open the web UI** at [http://localhost:6062/graphiql](http://localhost:6062) or connect any MPD client to `localhost:6600`.
85
+
86
+
---
87
+
88
+
## 🔌 Ports
89
+
90
+
| Service | Default port | Protocol |
91
+
|---|---|---|
92
+
| gRPC | 6061 | gRPC / gRPC-Web |
93
+
| GraphQL + Web UI | 6062 | HTTP |
94
+
| HTTP REST API | 6063 | HTTP |
95
+
| MPD server | 6600 | MPD protocol |
96
+
| Slim Protocol (squeezelite) | 3483 | TCP |
97
+
| HTTP PCM stream (squeezelite) | 9999 | HTTP |
98
+
99
+
---
100
+
101
+
## ⚙️ Audio Output Configuration
102
+
103
+
Rockbox reads `~/.config/rockbox.org/settings.toml` at startup.
104
+
`music_dir` is always required. `audio_output` defaults to `"builtin"` if
105
+
omitted.
106
+
107
+
### Built-in SDL — default
108
+
109
+
```toml
110
+
music_dir = "/path/to/Music"
111
+
audio_output = "builtin"
112
+
```
113
+
114
+
Uses SDL2 audio — plays through the OS default device. No extra setup needed.
115
+
116
+
### Snapcast (FIFO / pipe)
117
+
118
+
```toml
119
+
music_dir = "/path/to/Music"
120
+
audio_output = "fifo"
121
+
fifo_path = "/tmp/snapfifo" # named FIFO for snapserver; use "-" for stdout
122
+
```
123
+
124
+
Writes raw **S16LE stereo 44100 Hz** PCM to a named FIFO. Feed it into
125
+
[Snapcast](https://github.com/badaix/snapcast) for synchronised multi-room
126
+
playback:
127
+
128
+
```ini
129
+
# /etc/snapserver.conf (or /usr/local/etc/snapserver.conf on macOS)
130
+
[stream]
131
+
source = pipe:///tmp/snapfifo?name=default&sampleformat=44100:16:2
132
+
```
133
+
134
+
> **Startup order**: start `rockboxd` before `snapserver`. Rockbox holds a
135
+
> permanent write reference on the FIFO so snapserver never sees a premature
136
+
> EOF between tracks.
137
+
138
+
Pipe to any PCM consumer with `fifo_path = "-"`:
139
+
140
+
```sh
141
+
rockboxd | ffplay -f s16le -ar 44100 -ac 2 -
142
+
```
143
+
144
+
### AirPlay (RAOP)
145
+
146
+
```toml
147
+
music_dir = "/path/to/Music"
148
+
audio_output = "airplay"
149
+
airplay_host = "192.168.1.50" # IP of the AirPlay receiver
150
+
airplay_port = 5000 # optional, default 5000
151
+
```
152
+
153
+
Streams ALAC-encoded audio over RTP to any RAOP-compatible receiver — Apple
154
+
TV, HomePod, Airport Express, or
155
+
[shairport-sync](https://github.com/mikebrady/shairport-sync).
156
+
157
+
### Squeezelite (Slim Protocol — multi-room)
158
+
159
+
```toml
160
+
music_dir = "/path/to/Music"
161
+
audio_output = "squeezelite"
162
+
squeezelite_port = 3483 # Slim Protocol TCP port, default 3483
163
+
squeezelite_http_port = 9999 # HTTP PCM broadcast port, default 9999
164
+
```
165
+
166
+
Rockbox acts as a minimal Logitech Media Server. Any number of
167
+
[squeezelite](https://github.com/ralph-irving/squeezelite) clients can connect
168
+
simultaneously; Rockbox sends a `sync` packet to every client once per second
169
+
so they all align to the same playback clock:
170
+
171
+
```sh
172
+
squeezelite -s localhost -n "Living Room"
173
+
squeezelite -s localhost -n "Kitchen"
174
+
squeezelite -s localhost -n "Bedroom"
175
+
```
176
+
177
+
Select a specific output device:
178
+
179
+
```sh
180
+
squeezelite -s localhost -l # list available devices
181
+
squeezelite -s localhost -o "" # system default
182
+
squeezelite -s localhost -o "Built-in Output"
183
+
```
184
+
185
+
---
186
+
72
187
## 🚚 Installation
73
188
74
-
### Ubuntu/Debian
189
+
### Ubuntu / Debian
75
190
76
191
```sh
77
192
echo "deb [trusted=yes] https://apt.fury.io/tsiry/ /" | sudo tee /etc/apt/sources.list.d/fury.list
···
83
198
84
199
Add the following to `/etc/yum.repos.d/fury.repo`:
85
200
86
-
```
201
+
```ini
87
202
[fury]
88
203
name=Gemfury Private Repo
89
204
baseurl=https://yum.fury.io/tsiry/
···
103
218
paru -S rockbox-zig-bin
104
219
```
105
220
106
-
### Bash / Linux / MacOS
221
+
### Universal (curl installer)
107
222
108
223
```sh
109
224
curl -fsSL https://raw.githubusercontent.com/tsirysndr/rockbox-zig/HEAD/install.sh | bash
110
225
```
111
226
227
+
---
228
+
112
229
## 📦 Downloads
113
230
114
-
- `Linux`: intel:
115
-
[rockbox_2026.04.20_x86_64-linux.tar.gz](https://github.com/tsirysndr/rockbox-zig/releases/download/2026.04.20/rockbox_2026.04.20_x86_64-linux.tar.gz)
116
-
arm64:
117
-
[rockbox_2026.04.20_aarch64-linux.tar.gz](https://github.com/tsirysndr/rockbox-zig/releases/download/2026.04.20/rockbox_2026.04.20_aarch64-linux.tar.gz)
118
-
- `macOS`: intel:
119
-
[rockbox-2026.04.20-x86_64.pkg](https://github.com/tsirysndr/rockbox-zig/releases/download/2026.04.20/rockbox-2026.04.20-x86_64.pkg)
120
-
arm64:
121
-
[rockbox-2026.04.20-aarch64.pkg](https://github.com/tsirysndr/rockbox-zig/releases/download/2026.04.20/rockbox-2026.04.20-aarch64.pkg)
231
+
Pre-built binaries for the latest release are available on the
232
+
[Releases page](https://github.com/tsirysndr/rockbox-zig/releases/latest).
122
233
123
-
## 🧙♂️ Systemd Service
234
+
| Platform | Architecture | Package |
235
+
|----------|-------------------------|-----------|
236
+
| Linux | x86_64 | `.tar.gz` |
237
+
| Linux | aarch64 | `.tar.gz` |
238
+
| macOS | x86_64 | `.pkg` |
239
+
| macOS | aarch64 (Apple Silicon) | `.pkg` |
124
240
125
-
Rockbox daemon can be started as a systemd service. To enable and start the
126
-
service, run the following command:
241
+
---
127
242
128
-
```sh
129
-
rockbox service install
130
-
```
131
-
132
-
To disable and stop the service, run the following command:
133
-
134
-
```sh
135
-
rockbox service uninstall
136
-
```
137
-
138
-
To check the status of the service, run the following command:
243
+
## 🧙♂️ Systemd Service
139
244
140
245
```sh
141
-
rockbox service status
246
+
rockbox service install # enable and start
247
+
rockbox service uninstall # stop and disable
248
+
rockbox service status # check status
142
249
```
143
250
144
-
251
+
145
252
146
-
## Compiling from Source
253
+
---
147
254
148
-
Run the following commands to build the project:
255
+
## 🏗️ Compiling from Source
149
256
150
-
Before building the project, you need to install the necessary dependencies for
151
-
your operating system.
257
+
### Dependencies
152
258
153
-
### On Ubuntu/Debian
259
+
**Ubuntu / Debian**
154
260
155
-
```bash
261
+
```sh
156
262
sudo apt-get install libsdl2-dev libfreetype6-dev libunwind-dev zip protobuf-compiler cmake
157
263
```
158
264
159
-
### On Fedora40/41:
265
+
**Fedora**
160
266
161
267
```sh
162
268
sudo dnf install SDL2-devel freetype-devel libunwind-devel zip protobuf-compiler cmake
163
269
```
164
270
165
-
### Build Instructions
166
-
167
-
1. Clone the repository
271
+
**macOS**
168
272
169
273
```sh
170
-
git clone https://github.com/tsirysndr/rockbox-zig.git
171
-
git submodule update --init --recursive
274
+
brew install sdl2 freetype cmake protobuf
172
275
```
173
276
174
-
2. Navigate to the project directory
277
+
You also need [Zig](https://ziglang.org/download/) ≥ 0.13 and a recent stable
278
+
Rust toolchain (`rustup update stable`).
279
+
280
+
### Build
175
281
176
282
```sh
283
+
# 1. Clone
284
+
git clone https://github.com/tsirysndr/rockbox-zig.git
177
285
cd rockbox-zig
178
-
```
286
+
git submodule update --init --recursive
179
287
180
-
3. Build the webui
181
-
182
-
```sh
288
+
# 2. Build the web UI
183
289
cd webui/rockbox
184
290
deno install
185
291
deno run build
292
+
cd ../..
293
+
294
+
# 3. Configure and build the C firmware (one-time setup)
295
+
mkdir -p build-lib && cd build-lib
296
+
../tools/configure --target=sdlapp --type=N --lcdwidth=320 --lcdheight=240 --prefix=/usr/local
297
+
cp ../autoconf/autoconf.h .
298
+
make lib
299
+
cd ..
300
+
301
+
# 4. Build Rust crates
302
+
cargo build --release -p rockbox-cli -p rockbox-server
303
+
304
+
# 5. Link everything with Zig
305
+
cd zig && zig build
186
306
```
187
307
188
-
4. Run the following command to build the project
308
+
The binary is at `zig/zig-out/bin/rockboxd`.
189
309
190
-
```sh
191
-
mkdir -p build-lib && cd build-lib
192
-
../tools/configure --target=sdlapp --type=N --lcdwidth=320 --lcdheight=240 --prefix=/usr/local && cp ../autoconf/autoconf.h .
193
-
make zig
194
-
```
310
+
> **Rebuilding after changes**: after editing C code run `make lib` in
311
+
> `build-lib`; after editing Rust run `cargo build --release`. Then re-run
312
+
> `zig build`. Zig only re-links when the `.a` files are newer than the binary.
195
313
196
-
### Build GUI (Gtk4)
314
+
### Build the GTK4 desktop app
197
315
198
316
```sh
199
317
sudo apt-get install flatpak
···
208
326
flatpak run org.flatpak.Builder --run flatpak_app build-aux/io.github.tsirysndr.Rockbox.json rockbox-gtk
209
327
```
210
328
329
+
---
330
+
211
331
## 🧑🔬 Architecture
212
332
213
-
333
+
334
+
335
+
The Rockbox C firmware (audio engine, codecs, DSP) is compiled into
336
+
`libfirmware.a` and linked with two Rust static libraries
337
+
(`librockbox_cli.a`, `librockbox_server.a`) and SDL2 by the Zig build script.
338
+
The result is a single `rockboxd` binary. Rust crates expose the firmware over
339
+
gRPC, GraphQL, HTTP, and MPD, and implement output sinks (AirPlay, Squeezelite,
340
+
Snapcast) and the Typesense search integration.
214
341
215
-
## 📚 GraphQL API
342
+
---
216
343
217
-
Open [http://localhost:6062/graphiql](http://localhost:6062/graphiql) in your
218
-
browser.
344
+
## 📚 APIs
345
+
346
+
### GraphQL
347
+
348
+
Open [http://localhost:6062/graphiql](http://localhost:6062/graphiql) in your browser.
219
349
220
350
<p style="margin-top: 20px; margin-bottom: 20px;">
221
351
<img src="./docs/graphql.png" width="100%" />
222
352
</p>
223
353
224
-
## 📚 HTTP API
354
+
### HTTP REST
225
355
226
356
Open [http://localhost:6063](http://localhost:6063) in your browser.
227
357
···
229
359
<img src="./docs/http-api.png" width="100%" />
230
360
</p>
231
361
232
-
## 📚 gRPC API
362
+
### gRPC
233
363
234
-
[https://buf.build/tsiry/rockboxapis/docs/main:rockbox.v1alpha1](https://buf.build/tsiry/rockboxapis/docs/main:rockbox.v1alpha1)
364
+
Docs: [buf.build/tsiry/rockboxapis](https://buf.build/tsiry/rockboxapis/docs/main:rockbox.v1alpha1)
235
365
236
-
Try Rockbox gRPC API using
366
+
Try it live with
237
367
[Buf Studio](https://buf.build/studio/tsiry/rockboxapis/rockbox.v1alpha1.LibraryService/GetAlbums?target=http%3A%2F%2Flocalhost%3A6061&selectedProtocol=grpc-web).
238
368
239
369
<p style="margin-top: 20px; margin-bottom: 20px;">