6.9 KiB

Raw Blame History

Configuration

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), 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)
`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.
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).

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:

providers = [
    "tidal",
    "youtube",
    "fyyd",
    "abs",
    "soundcloud",
    "jamendo",
    "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). 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:

[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

Every option 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):

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

`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 option in context, see The terminal client.

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 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.

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:

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

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

[audio]
device = "Headphones"

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

6.9 KiB Raw Blame History