> ## 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

<Tabs>
  <Tab title="macOS">
    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    brew install tsirysndr/tap/rockbox
    ```
  </Tab>

  <Tab title="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>

  <Tab title="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>

  <Tab title="Arch Linux">
    ```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
    paru -S rockboxd-bin
    ```
  </Tab>

  <Tab title="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.
    </Note>

    <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`.
    </Tip>
  </Tab>
</Tabs>

For full distribution coverage, build instructions and Docker images, see
[Installation](/installation).

## 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](/configuration) 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

<CardGroup cols={2}>
  <Card title="Web UI" icon="globe" href="http://localhost:6062">
    Browse your library and control playback at
    [http://localhost:6062](http://localhost:6062).
  </Card>

  <Card title="GraphiQL" icon="code" href="http://localhost:6062/graphiql">
    Explore the API live at
    [http://localhost:6062/graphiql](http://localhost:6062/graphiql).
  </Card>

  <Card title="MPD client" icon="terminal">
    Point any MPD client (`ncmpcpp`, `mpc`, MALP, etc.) at `localhost:6600`.
  </Card>

  <Card title="HTTP REST" icon="bolt" href="http://localhost:6063">
    Quick `curl` testing — see the REST overview.
  </Card>
</CardGroup>

## 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](/sdks/typescript):

```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

<CardGroup cols={2}>
  <Card title="Configure" icon="sliders" href="/configuration">
    `settings.toml` reference — every key, every default.
  </Card>

  <Card title="Audio output" icon="speaker" href="/audio-output/overview">
    Send audio to AirPlay, Snapcast, Squeezelite, Chromecast or UPnP.
  </Card>

  <Card title="Pick an SDK" icon="code" href="/sdks/overview">
    Build clients in TypeScript, Python, Ruby, Elixir, Clojure or Gleam.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/reference/faq">
    Common gotchas and how to fix them.
  </Card>
</CardGroup>