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

Download the latest .pkg for your architecture from the Releases page and double-click to install.

Or via the universal installer:

curl -fsSL https://raw.githubusercontent.com/tsirysndr/rockbox-zig/HEAD/install.sh | bash

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 rockbox-zig-bin

Docker

docker run --rm -it \
  -p 6060-6063:6060-6063 \
  -p 6600:6600 \
  -v $HOME/Music:/music \
  -v $HOME/.config/rockbox.org:/root/.config/rockbox.org \
  tsiry/rockbox

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.