crabidy/docs/src/config.md

# Configuration

<!-- toc -->

Crabidy reads its configuration from TOML files in `~/.config/crabidy/`,
the platform config directory. Every file is optional. On first start
each component writes its own file filled in with defaults, then reads
it back — so a fresh install runs with sensible values and leaves you an
editable file for each piece. A provider whose config fails to load
simply does not mount; it does not stop the server.

Which providers mount at all is controlled by `crabidy-server.toml` (see
[Enabling and disabling providers](#enabling-and-disabling-providers)),
which the server now also writes on first start.

## The config files

| File                  | Component        | Credentials needed          |
| --------------------- | ---------------- | --------------------------- |
| `abs.toml`            | audiobookshelf   | server URL + API key        |
| `fsdy.toml`           | local files      | none                        |
| `fyyd.toml`           | podcasts         | none                        |
| `jamendo.toml`        | Jamendo          | none (a key is shipped)     |
| `rss.toml`            | podcast feeds    | the feed URLs themselves    |
| `soundcloud.toml`     | SoundCloud       | none (token optional)       |
| `tidaly.toml`         | Tidal            | device login (interactive)  |
| `ytdy.toml`           | YouTube          | none (cookies optional)     |
| `cbd-tui.toml`        | `cbd-tui`        | server role + password      |
| `cbd.toml`            | `cbd`            | server role + password      |
| `crabidy-server.toml` | server           | its own `[auth]` hashes     |

Every file is auto-created with defaults on first start.

- The provider files each get a full option reference — **including how to log
  in** — on that provider's page under [Providers](./providers.md).
- `cbd-tui.toml` and `cbd.toml` are client configs (below).
- `crabidy-server.toml` holds the enabled-providers list (below), the audio
  output device (below), and server auth (see [Roles and
  authorization](./auth.md)).

```admonish warning
Provider credentials and client passwords are stored in **cleartext** — the
files are configuration, not a keyring. Keep `~/.config/crabidy/` private
(`chmod 700` is a reasonable habit). Crabidy redacts secrets from its logs,
error messages, and config dumps.
```

## Enabling and disabling providers

On first start the server writes `crabidy-server.toml` with every provider
enabled:

```toml
providers = [
    "tidal",
    "youtube",
    "fyyd",
    "abs",
    "soundcloud",
    "jamendo",
    "rss",
    "fs",
    "crabidy",
    "orphans",
]
```

**Remove a name to disable that provider** — it no longer mounts and drops
out of the library tree; its own config file (e.g. `tidaly.toml`) is then
left unread. Deleting the whole `providers` line re-enables everything (the
same as a fresh install with no file). Because `orphans` is a view over the
store, disabling `crabidy` disables `orphans` too.

The list can only offer what the binary was **built** with: providers are
also selectable at compile time (see [Tailored
builds](./build-features.md)). The default list written on first start
therefore names only the providers this build has, and if you add one it
does not have, the server logs a warning at startup and ignores it. Run
`crabidy-server features` to see what a binary contains.

## Client config: `cbd-tui.toml` and `cbd.toml`

`cbd-tui` (the standalone terminal client) reads `cbd-tui.toml`; `cbd`
(server plus TUI in one process) reads its own `cbd.toml`. They are
**separate files with the same options** so the two can run side by side
on one machine: a common setup is `cbd` playing locally against its
in-process server while `cbd-tui`, pointed at a remote server (a
Raspberry Pi, say), acts as a remote control. A single shared file would
force one use to follow the other's `address`.

Both live under a `[server]` table:

```toml
[server]
# Where to find the server. Default (both files): localhost, which is
# what cbd's own in-process server listens on. Point cbd-tui.toml at a
# remote server to drive it as a remote control.
address = "http://127.0.0.1:50051"

# Credentials, used only when the server has [auth] configured.
# `user` is the role name (see ./auth.md); leave both empty against an
# open server.
user = ""
password = ""

# Show the frequency-spectrum bars under the track progress.
spectrum = true

# Color of those bars: a "#rrggbb" hex triple, a color name ("red",
# "light-blue", …), or a 0-255 index into the terminal palette. The
# default is the red the queue marks the playing track with. An
# unparsable value warns on stderr and falls back to that default.
spectrum_color = "#bf616a"

# Shade the bars from dim at the floor to bright at the top instead of
# one flat color. Only hex colors can be shaded — a name or a palette
# index has no RGB value the client may interpolate.
spectrum_gradient = true

# Color the shading reaches at the top of the bars, in the same three
# forms as spectrum_color. "none" (or "off") shades brightness alone.
spectrum_top_color = "#b48ead"

# Color of the peak-hold shadows trailing above the bars, in the same
# three forms as spectrum_color. "none" (or "off") draws no shadows.
spectrum_peak_color = "#81a1c1"

# Fill the shadow from the bar up to its peak. false draws a thin rule at
# the peak alone.
spectrum_peak_fill = true

# Seconds a full-scale shadow takes to fall to the floor, 0.05-60.
spectrum_peak_fall = 4.0

# Least bar width in cells, 1-16. Bars take any spare columns beyond
# this, so raise it only to force wider bars and fewer bands.
spectrum_bar_width = 1

# Width in cells of the seam dividing two bars, 0-8. The seam is the bar
# itself dimmed, so the bars stay one connected field; 0 removes it.
spectrum_bar_gap = 1

# Height of the line dividing two value rows, in eighths of a row, 0-4.
# This is what makes the segments of a bar visible; 0 stacks them solid.
spectrum_row_gap = 1
```

Every option except the `spectrum_*` appearance settings (everything below
`spectrum` itself) is also a command-line flag, given before the subcommand
(`cbd-tui --address http://pi:50051 --user owner`, `cbd --spectrum false`).
A provided flag overrides the file value; an omitted flag
leaves the file value in place. To write credentials into the config
once instead of editing by hand, use the `auth` subcommand (see
[Command line](./clients/cli.md)):

```sh
cbd-tui auth owner 'my-password'
cbd-tui auth queue-owner 'pw' --address http://pi:50051
```

```admonish warning
`password` is stored in **plaintext** — the client always holds a
plaintext credential, not a hash. Keep the client config file private.
The password is never written to logs.
```

For the client's `spectrum` options in context — shading, and the
peak-hold markers — see [The terminal client](./clients/tui.md).

## Where the server's own data lives

The server-managed `crabidy` provider does **not** live under
`~/.config`. Following the XDG split, its two parts sit in two roots:

- `~/.local/state/crabidy/` — the provider's TOML tree: the track files
  for your saved queues, bookmarks, and captures (the `/crabidy`
  library subtree). This is *state*.
- `~/.local/share/crabidy/` — the content-addressed audio store: the
  actual playable files that captures download, shared and
  de-duplicated across every save. This is *data*.

Neither needs configuration; both start empty and the server manages
them. See [The crabidy store](./store.md) for how saves, captures, and
de-duplication work.

Client and TUI log files also go to `~/.local/state/crabidy/`. The
provider ignores non-track files there, so the logs do not show up in
the library.

```admonish note
A binary built without the `fs` feature has no content store at all: no
`/crabidy`, no bookmarks or captures, and the queue is not persisted across
restarts. See [Tailored builds](./build-features.md).
```

## The audio output device

By default the server plays to the system default output device. On a
Raspberry Pi that is often HDMI, so playback runs but nothing comes out of the
headphone jack or a USB DAC. Ask the server what it can see:

```console
$ crabidy-server audio-devices
Audio output devices (* = selected by the current config):
    hdmi:CARD=vc4hdmi,DEV=0
    sysdefault:CARD=Headphones
    ...
```

Then pin one by passing it to the same command, and restart the server:

```console
$ crabidy-server audio-devices Headphones
Set [audio] device = "Headphones" in .../crabidy-server.toml
```

The value is matched case-insensitively as a **substring** of the device
name, so a memorable fragment is enough. It writes:

```toml
[audio]
device = "Headphones"
```

If the fragment matches nothing, both the command and the server warn, and
the server falls back to the system default.