crabidy/README.md

crabidy

A client/server music player. A headless gRPC server owns the library, the play queue, and audio output; a terminal UI connects to it over localhost (or the network). Media comes from pluggable providers, each mounted as a subtree of one library:

/
├── tidal        Tidal streaming (see tidaldy/README.md)
├── youtube      YouTube search & playlists (see ytdy/README.md)
├── fs           a local music folder (see fsdy/README.md)
├── queues       saved play queues (managed by the server)
├── bookmarks    link snapshots of library subtrees (`w`)
└── captures     downloaded snapshots with local audio (`W`)

Binaries

• crabidy-server — the server: providers, queue, playback, gRPC on 0.0.0.0:50051.
• cbd-tui — the terminal client. Press ? inside for all key bindings.
• cbd — both in one process: starts the server, waits until it accepts connections, then runs the TUI. Adopts an already-running server instead of failing on an occupied port.

Quick start

The toolchain is managed by devenv:

devenv shell          # provides rust, yt-dlp, and friends
cargo run -p cbd      # server + TUI in one process

Or run the halves separately: cargo run -p crabidy-server and, in another terminal, cargo run -p cbd-tui.

Configuration

All configuration lives in ~/.config/crabidy/ (the platform config directory). Every file is optional; missing providers simply do not mount. Files are created/rewritten on first start with their defaults filled in.

File	Component	Documentation
tidaly.toml	Tidal	tidaldy/README.md
ytdy.toml	YouTube	ytdy/README.md
fsdy.toml	local fs	fsdy/README.md
cbd-tui.toml	TUI / cbd	below

The server-managed folders (queues/, bookmarks/, captures/) also live in ~/.config/crabidy/; they need no configuration and hold plain folders of track files in the format documented in fsdy/README.md.

cbd-tui.toml

Configuration of the TUI (and the TUI half of cbd):

# Where to find the server. Default shown.
address = "http://127.0.0.1:50051"

Every option is also available as a command-line flag (cbd-tui --address ...).

Using the library

Navigation is vim-style: j/k select, l enters the selected folder, h goes to the parent, Tab switches between library and queue, Enter replaces the queue with the selection. % creates a node where the pane title shows % to add (e.g. a search term), e renames, d deletes.

• w saves the selection as a bookmark (links; needs the source provider to replay) or, in the queue pane, saves the queue.
• W captures the selection: the subtree is mirrored under /captures/<name> with every track's audio downloaded next to its metadata — fully local playback afterwards. Captures are incremental: re-capturing the same name resumes and completes it; tracks whose source cannot be captured are recorded as skipped (red in the UI, skipped by playback). Download captures can take long; progress is shown in the library pane. Inside /captures, d deletes any folder or single track from disk (audio included) after a y/N confirmation.

Press ? for the full binding table.

Logs

cbd and cbd-tui log to ~/.local/state/crabidy/ (daily files); crabidy-server logs to stderr. Stream URLs and credentials are redacted from logs by design.

Development

Design documents live in architecture/, per-feature quality gates in quality/, and implementation plans in plan/. See CLAUDE.md / AGENTS.md for the development workflow and coding rules.