Quickstart

Install Rockbox, point it at your music, and play your first track.

This guide gets you from zero to a running rockboxd with a usable web UI in about five minutes.

1. Install

macOS

brew install tsirysndr/tap/rockbox

Ubuntu / Debian

echo "deb [trusted=yes] https://apt.fury.io/tsiry/ /" | sudo tee /etc/apt/sources.list.d/fury.list
sudo apt-get update
sudo apt-get install rockbox

Fedora

Add /etc/yum.repos.d/fury.repo:

[fury]
name=Gemfury Private Repo
baseurl=https://yum.fury.io/tsiry/
enabled=1
gpgcheck=0

Then:

sudo dnf install rockbox

Arch Linux

paru -S rockboxd-bin

Docker

docker run -v $HOME/Music:/root/Music \
  -p 6062:6062 \
  -p 7882:7882 \
  tsiry/rockbox

Open the web UI at http://localhost:6062 and start playing — no config file, no external client. The page attaches to the HLS stream on port 7882 automatically and audio plays directly in the browser.

Prefer the terminal? Any HLS-capable player works:

ffplay http://localhost:7882/hls/master.m3u8

Port 6062 serves the web UI and GraphQL API. Port 7882 serves the HLS playlist (/hls/master.m3u8) and DASH manifest (/dash/manifest.mpd) — both are produced from the same in-memory CMAF (fMP4 + AAC-LC) ring buffer.

The image also ships snapserver for users who prefer Snapcast multi-room. Set audio_output = "fifo" in ~/.config/rockbox.org/settings.toml and add -p 1704:1704 -p 1705:1705 -p 1780:1780 to the docker run command, then connect with snapclient tcp://localhost.

For full distribution coverage, build instructions and Docker images, see Installation.

2. Point it at your music

Create ~/.config/rockbox.org/settings.toml:

music_dir    = "/path/to/your/Music"
audio_output = "builtin"

That’s the minimum. music_dir is the only required field; everything else has sensible defaults. See Configuration for the full list.

3. Start rockboxd

rockbox start

You should see logs like:

INFO  rockbox-cli  rockboxd starting...
INFO  rockbox-cli  graphql server listening on :6062
INFO  rockbox-cli  http server listening on :6063
INFO  rockbox-cli  mpd server listening on :6600
INFO  rockbox-cli  grpc server listening on :6061

4. Open a client

Web UI

Browse your library and control playback at http://localhost:6062.

GraphiQL

Explore the API live at http://localhost:6062/graphiql.

MPD client

Point any MPD client (ncmpcpp, mpc, MALP, etc.) at localhost:6600.

HTTP REST

Quick curl testing — see the REST overview.

5. Play something

From the web UI, search for a track and hit play. From the terminal:

mpc -h localhost -p 6600 update
mpc -h localhost -p 6600 search title "money"
mpc -h localhost -p 6600 play

Or with the TypeScript SDK:

import { RockboxClient } from '@rockbox-zig/sdk';

const client = new RockboxClient();
const { albums } = await client.library.search('dark side');
await client.playback.playAlbum(albums[0].id, { shuffle: true });

Next steps

Configure

settings.toml reference — every key, every default.

Audio output

Send audio to AirPlay, Snapcast, Squeezelite, Chromecast or UPnP.

Pick an SDK

Build clients in TypeScript, Python, Ruby, Elixir, Clojure or Gleam.

FAQ

Common gotchas and how to fix them.