> ## Documentation Index
> Fetch the complete documentation index at: https://rockboxzig.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [tab] macOS
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> brew install tsirysndr/tap/rockbox
> ```

> [tab] Ubuntu / Debian
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> 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
> ```

> [tab] Fedora
>
> Add `/etc/yum.repos.d/fury.repo`:
>
> ```ini theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> [fury]
> name=Gemfury Private Repo
> baseurl=https://yum.fury.io/tsiry/
> enabled=1
> gpgcheck=0
> ```
>
> Then:
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> sudo dnf install rockbox
> ```

> [tab] Arch Linux
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> paru -S rockboxd-bin
> ```

> [tab] Docker
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> docker run -v $HOME/Music:/root/Music \
>   -p 6062:6062 \
>   -p 7882:7882 \
>   tsiry/rockbox
> ```
>
> Open the web UI at [http://localhost:6062](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:
>
> ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
> ffplay http://localhost:7882/hls/master.m3u8
> ```
>
> > [!NOTE]
> >
> > 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.
>
> > [!TIP]
> >
> > 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](https://rockboxzig.mintlify.site/installation.md).

## 2. Point it at your music

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

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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](https://rockboxzig.mintlify.site/configuration.md) for the full list.

## 3. Start `rockboxd`

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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

> [card] [Web UI](http://localhost:6062)
>
> Browse your library and control playback at
> [http://localhost:6062](http://localhost:6062).

> [card] [GraphiQL](http://localhost:6062/graphiql)
>
> Explore the API live at
> [http://localhost:6062/graphiql](http://localhost:6062/graphiql).

> [card] MPD client
>
> Point any MPD client (`ncmpcpp`, `mpc`, MALP, etc.) at `localhost:6600`.

> [card] [HTTP REST](http://localhost:6063)
>
> Quick `curl` testing — see the REST overview.

## 5. Play something

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

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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](https://rockboxzig.mintlify.site/sdks/typescript.md):

```ts theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
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

> [card] [Configure](https://rockboxzig.mintlify.site/configuration.md)
>
> `settings.toml` reference — every key, every default.

> [card] [Audio output](https://rockboxzig.mintlify.site/audio-output/overview.md)
>
> Send audio to AirPlay, Snapcast, Squeezelite, Chromecast or UPnP.

> [card] [Pick an SDK](https://rockboxzig.mintlify.site/sdks/overview.md)
>
> Build clients in TypeScript, Python, Ruby, Elixir, Clojure or Gleam.

> [card] [FAQ](https://rockboxzig.mintlify.site/reference/faq.md)
>
> Common gotchas and how to fix them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.