104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 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. 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.
|