crabidy/docs/src/intro.md

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.

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

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:

/
├── 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 share one node/track model (see The library model) 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).

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); running one with no subcommand starts its usual mode.

Where to go next

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