# Introduction

Crabidy is a client/server music player. A headless server owns the music
library, the play queue, and audio output; thin clients connect to it over
gRPC and drive it. One server can be driven from several clients at once —
a terminal UI on your laptop, a browser tab, a shell script — and they all
see the same queue and playback state live.

This book describes **how the current version works**: the pieces, the
boundaries between them, the behaviour you can rely on, and every
configuration option. It is reference documentation — it describes the system
as it is, not the history of how it got there.

```admonish note
Crabidy is a personal, single-server music player for a trusted home
network. It is not multi-tenant and does not encrypt its transport itself
(see [Roles and authorization](./auth.md)).
```

## The shape of the system

```d2
direction: right

clients: Clients {
  tui: cbd-tui (terminal)
  web: cbd-web (browser)
  cli: cbd / CLI
}

server: crabidy-server {
  shape: rectangle
  library: Library (providers)
  queue: Queue
  playback: Playback + audio out
}

media: Media {
  streaming: "Tidal · YouTube\nSoundCloud · Jamendo"
  spoken: "audiobookshelf · fyyd"
  fs: "Local files\n+ the crabidy store"
}

clients -> server: gRPC (commands + update stream)
server.library -> media: fetch / stream
server.playback -> media: stream audio
```

The server exposes one gRPC service. Clients send **commands** (browse the
library, change the queue, control playback) and subscribe to an **update
stream** that pushes the current queue, play state, track position, and
capture progress as they change. Nothing is polled; the UI redraws from
pushed updates.

## The library

Everything you can play lives in one tree, addressed by path. Each top-level
segment is a **provider** mounted as a subtree:

```text
/
├── crabidy      your saves: queues, bookmarks, and captures
├── abs          audiobookshelf audiobooks
├── fs           a local music folder
├── fyyd         podcast search
├── jamendo      Creative-Commons music
├── soundcloud   SoundCloud search, likes, and playlists
├── tidal        Tidal streaming
├── youtube      YouTube search & playlists
└── orphans      store audio no save references any more
```

Which of these you see depends on what your binary was built with, what you
enabled, and which providers came up — see [Providers](./providers.md).

Providers share one node/track model (see [The library
model](./library.md)) so a client browses `/tidal` and `/fs` with the same
keys and the same code. The `crabidy` provider is special: it is where the
server writes the things you save, backed by a content-addressed store of
audio files (see [The crabidy store](./store.md)).

## Binaries

| Binary           | What it is                                            |
| ---------------- | ----------------------------------------------------- |
| `crabidy-server` | the server: providers, queue, playback, gRPC          |
| `cbd-tui`        | the terminal client                                   |
| `cbd-web`        | the browser client (WASM), embedded into the server   |
| `cbd`            | server + terminal client in one process               |

Every binary is also a command-line tool (see [Command
line](./clients/cli.md)); running one with no subcommand starts its usual
mode.

## Where to go next

- [Architecture](./architecture.md) — the server's internals and how a
  request flows.
- [The library model](./library.md) — nodes, tracks, paths, and links.
- [Providers](./providers.md) — how each media source is wired in.
- [The crabidy store](./store.md) — saves, captures, and de-duplication.
- [Queue and playback](./queue.md) — the queue, playback, and persistence.
- [Clients](./clients.md) — the TUI, the web client, and the CLI.
- [Configuration](./config.md) — every config file and option, including
  how to log in to each provider.
- [Tailored builds](./build-features.md) — dropping providers and features
  you do not need at compile time.
- [Roles and authorization](./auth.md) — locking a server down.