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

```text
/
├── 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](https://devenv.sh):

```sh
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](tidaldy/README.md) |
| `ytdy.toml`    | YouTube   | [ytdy/README.md](ytdy/README.md)       |
| `fsdy.toml`    | local fs  | [fsdy/README.md](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](fsdy/README.md).

### `cbd-tui.toml`

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

```toml
# 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.

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.