Document the providers and their configuration in READMEs
The root README covers the binaries, quick start, the config directory, and links per-provider READMEs; each provider README explains how the provider works, how it is used from the TUI, and its config file with every option and default (tidaly.toml, fsdy.toml, ytdy.toml, cbd-tui.toml). The fsdy README doubles as the reference for the .cbd-track.toml on-disk format shared by queues, bookmarks, and captures. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Test User
parent
c84dec9ca2
commit
383173046d
100
README.md
100
README.md
|
|
@ -1 +1,101 @@
|
|||
# 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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,61 @@
|
|||
# fsdy — the filesystem provider
|
||||
|
||||
Mounts a local directory at **`/fs`** in the crabidy library. The same
|
||||
engine also powers the server-managed mounts `/queues`, `/bookmarks`,
|
||||
and `/captures` — everything below applies to their on-disk format too.
|
||||
|
||||
## How it works
|
||||
|
||||
The provider walks one configured root directory. Every **directory**
|
||||
becomes a queueable library node; every file ending in
|
||||
**`.cbd-track.toml`** becomes a track; everything else (audio files,
|
||||
covers, hidden entries) is invisible to the library. Listing order is
|
||||
case-insensitive by file name — prefix files with numbers to fix an
|
||||
order (the capture/bookmark writers use `0001`-style prefixes for
|
||||
exactly this reason).
|
||||
|
||||
A track file carries the track's metadata plus a reference to the
|
||||
playable thing:
|
||||
|
||||
```toml
|
||||
title = "We Will Rock You" # required
|
||||
artist = "Queen" # optional
|
||||
duration = 122 # optional, seconds
|
||||
|
||||
[album] # optional
|
||||
title = "News of the World"
|
||||
release_date = "1977-10-28"
|
||||
|
||||
# Exactly ONE of the following four:
|
||||
[playable]
|
||||
file = "we-will-rock-you.flac" # local audio; absolute, or relative to
|
||||
# this file's directory (relocatable)
|
||||
# url = "https://example.org/radio.mp3" # http(s) stream
|
||||
# link = "/tidal/artists/1/2/3" # another provider's track
|
||||
# skipped = true # no audio: a capture recorded its
|
||||
# source as uncapturable; shown red,
|
||||
# skipped by playback
|
||||
```
|
||||
|
||||
Malformed track files are skipped with a warning; they never break the
|
||||
listing. `link` playables resolve exactly one hop (a link to a link
|
||||
fails at play time), which keeps cycles impossible.
|
||||
|
||||
## Configuration — `~/.config/crabidy/fsdy.toml`
|
||||
|
||||
```toml
|
||||
# Absolute path of the directory to expose under /fs.
|
||||
# Default: the platform music directory (e.g. ~/Music). When neither is
|
||||
# available the /fs mount is disabled — the rest of the server runs on.
|
||||
# root = "/home/me/music"
|
||||
```
|
||||
|
||||
## The server-managed instances
|
||||
|
||||
`/queues`, `/bookmarks`, and `/captures` are fsdy instances over
|
||||
`~/.config/crabidy/{queues,bookmarks,captures}/`, written by the server
|
||||
(queue persistence, `w`, `W`) and readable/editable with any file
|
||||
manager — they are just folders of the track files described above.
|
||||
Their top-level folders can be renamed (`e`) and deleted (`d`) from the
|
||||
TUI; `/queues/current` is the continuously persisted play queue and is
|
||||
protected.
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
# tidaldy — the Tidal provider
|
||||
|
||||
Mounts your Tidal account at **`/tidal`** in the crabidy library, using
|
||||
Tidal's web API.
|
||||
|
||||
## How it works
|
||||
|
||||
On first start the provider runs Tidal's OAuth **device login**: the
|
||||
server prints a `link.tidal.com` verification URL to its stdout (for
|
||||
`cbd`, check the log file) — open it in a browser, authorize, and the
|
||||
provider finishes logging in by itself. The obtained tokens are written
|
||||
back into the config file and refreshed automatically from then on; you
|
||||
should not need to log in again.
|
||||
|
||||
The tree offers your playlists, favorite artists (with their albums and
|
||||
tracks), and a **search** node: press `%` under `/tidal/search` to
|
||||
create a search term; the term becomes a persistent child node holding
|
||||
its results (tracks, artists, albums). Terms are renamable (`e`,
|
||||
re-runs the search) and deletable (`d`).
|
||||
|
||||
Everything queueable is also capturable: `w` bookmarks a subtree as
|
||||
links, `W` downloads a subtree's audio into `/captures/<name>`.
|
||||
|
||||
## Configuration — `~/.config/crabidy/tidaly.toml`
|
||||
|
||||
The file is rewritten on every server start with the current values
|
||||
(including refreshed tokens), so **it contains your credentials — keep
|
||||
it private**. All options with their defaults:
|
||||
|
||||
```toml
|
||||
# Tidal API endpoints. Change only if you know why.
|
||||
base_url = "https://api.tidal.com/v1"
|
||||
hifi_url = "https://api.tidalhifi.com/v1"
|
||||
|
||||
# Stream quality: "Low" | "High" | "Lossless" | "HiRes".
|
||||
audio_quality = "Lossless"
|
||||
|
||||
# Managed by the provider: filled in by the device login and refreshed
|
||||
# automatically. Delete this whole section to force a fresh login.
|
||||
[login]
|
||||
# device_code = ...
|
||||
# user_id = ...
|
||||
# country_code = ...
|
||||
# access_token = ...
|
||||
# refresh_token = ...
|
||||
# expires_after = ...
|
||||
|
||||
# OAuth client identity used for the device flow. Working defaults are
|
||||
# built in; override only to use your own client registration.
|
||||
[oauth]
|
||||
# client_id = ...
|
||||
# client_secret = ...
|
||||
base_url = "https://auth.tidal.com/v1/oauth2"
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- A missing or empty file is fine: defaults are used and the device
|
||||
login runs on the next start.
|
||||
- If Tidal ever invalidates the session (long offline periods), delete
|
||||
the `[login]` section and restart.
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
# ytdy — the YouTube provider
|
||||
|
||||
Mounts YouTube at **`/youtube`** in the crabidy library.
|
||||
|
||||
## How it works
|
||||
|
||||
Metadata comes from the pure-Rust [rustypipe] Innertube client:
|
||||
|
||||
- **`/youtube/search`** works without any login. Press `%` to create a
|
||||
search term; the term becomes a persistent child node listing the top
|
||||
video results as tracks. Terms are renamable (`e`, re-runs the
|
||||
search) and deletable (`d`). Terms live in memory — a server restart
|
||||
forgets them, but navigating to an old term path recreates it.
|
||||
- **`/youtube/playlists`** appears when a cookie login is configured
|
||||
and accepted: it lists the account's saved playlists.
|
||||
|
||||
**Stream URLs** are resolved through a minimal `yt-dlp` sidecar when
|
||||
the binary is available (one bounded subprocess call per played or
|
||||
captured track — no other functionality uses it). This is a deliberate
|
||||
concession: YouTube currently caps tokenless stream URLs at their
|
||||
leading ~1 MiB, and `yt-dlp` is the only maintained solver for the
|
||||
cipher challenges that lift the cap; its URLs stream whole files at a
|
||||
throttled ~32 KB/s (still ~2× audio bitrate). Without the binary the
|
||||
provider still works, but playback of a track stops after roughly a
|
||||
minute. Streams prefer `audio/mp4` (AAC), the format the built-in
|
||||
player decodes; captures therefore store `.m4a` files. See
|
||||
`architecture/youtube-rustypipe.md` for the full analysis.
|
||||
|
||||
Search results and playlists are downloadable: `W` captures them with
|
||||
audio into `/captures/<name>` (slow under the throttle, but captures
|
||||
are resumable — re-capture the same name to continue).
|
||||
|
||||
## Configuration — `~/.config/crabidy/ytdy.toml`
|
||||
|
||||
All options with their defaults:
|
||||
|
||||
```toml
|
||||
# Netscape cookies.txt export for the logged-in features (saved
|
||||
# playlists). Export with a browser extension like "Get cookies.txt
|
||||
# LOCALLY", ideally from an Incognito session you close afterwards.
|
||||
# The provider caches the rotated session cookie under
|
||||
# ~/.config/crabidy/rustypipe/, so the export only needs to be valid
|
||||
# once. Default: unset (logged out; search still works).
|
||||
# cookies = "/home/me/youtube-cookies.txt"
|
||||
|
||||
# Results per search term. Default: 20.
|
||||
# search_results = 20
|
||||
|
||||
# Per-request timeout in seconds (Innertube calls; the yt-dlp sidecar
|
||||
# gets at least 60 s). Default: 30.
|
||||
# call_timeout_secs = 30
|
||||
|
||||
# The yt-dlp binary used ONLY for stream URLs. A bare name resolves
|
||||
# via PATH. Default: "yt-dlp". Keep it fresh — a stale yt-dlp is the
|
||||
# first suspect when YouTube playback breaks.
|
||||
# binary = "yt-dlp"
|
||||
|
||||
# Optional rustypipe-botguard binary for PO-token attestation (also
|
||||
# auto-detected on PATH). Currently ineffective upstream, but once
|
||||
# rustypipe's web-client deciphering is fixed this makes streams work
|
||||
# without yt-dlp. Default: unset.
|
||||
# botguard_bin = "/home/me/.cargo/bin/rustypipe-botguard"
|
||||
```
|
||||
|
||||
Secrets: the cookies file and the rustypipe cache grant access to your
|
||||
YouTube session — keep both private. The provider never logs their
|
||||
contents (paths only), and stream URLs are redacted from logs.
|
||||
|
||||
## Failure behavior
|
||||
|
||||
- No network / broken client at startup: only `/youtube` is disabled,
|
||||
the server runs on.
|
||||
- Rejected or missing cookies: degrades to logged-out with a warning.
|
||||
- Missing `yt-dlp`: warning at startup; streams stop after ~1 MiB.
|
||||
- `403 Forbidden` on streams in the log: YouTube's per-IP/per-video
|
||||
enforcement fluctuates; usually transient. If it persists, update
|
||||
`yt-dlp`.
|
||||
|
||||
[rustypipe]: https://crates.io/crates/rustypipe
|
||||
Loading…
Reference in New Issue