crabidy/docs/src/build-features.md

Tailored builds

Every provider, Opus decoding, the spectrum bars, the embedded web UI and the TUI's desktop notifications sit behind a Cargo feature. All of them are on by default, so a plain cargo build gives you the full player. Turning some off gives you a smaller binary that pulls fewer dependencies — useful for a single-purpose box (a Raspberry Pi playing a local flac collection) or a build environment you want to keep lean.

This is the compile-time half of provider selection. The runtime half — the providers list in crabidy-server.toml — still works exactly as before; see Configuration. The two compose in one direction: a provider that is not compiled in cannot be enabled in the config, and if you name one anyway the server logs a warning and carries on.

What this build has

crabidy-server features   # or: cbd features

prints one feature per line — the providers it can mount, then the extras. The same list goes into the server's startup log, so a support question ("why is /tidal missing?") is answerable from the binary and its log.

The features

Feature	Turning it off drops
tidal	the /tidal provider (tidaldy)
youtube	the /youtube provider (ytdy, and with it rustypipe)
fyyd	the /fyyd podcast provider
abs	the /abs audiobookshelf provider
soundcloud	the /soundcloud provider
jamendo	the /jamendo provider
fs	local files and persistent state — see below
opus	Ogg-Opus decoding (symphonia + a bundled libopus C build)
spectrum	the server-side FFT feeding clients' spectrum bars
web-ui	the embedded web client (tonic-web + the wasm bundle)

Plus two conveniences: all-providers enables the seven provider features at once, and cbd (the bundle) mirrors every feature above and adds notifications for the TUI's desktop "now playing" popups (notify-rust, which on Linux pulls a D-Bus stack).

fs is more than /fs

The /fs provider, the content store, and everything built on it are all written against the same crate, so they share one feature. With fs off you lose:

• the /fs mount (your local music folder);
• /crabidy — saved queues, bookmarks (w) and captures (W);
• /orphans, which is a view over the store;
• queue persistence: the queue lives in memory, so a restart starts empty;
• the scan command (it fails with a message naming the feature);
• captured-track markers in library listings.

The capture and save-queue RPCs answer Unimplemented on such a server, so clients report an ordinary error instead of hanging.

If you want /fs but not /crabidy, keep the feature and prune the providers list at runtime instead — that is what it is for.

opus and the libopus build

symphonia (and so rodio) has no Opus decoder, so Ogg-Opus files are decoded through a bundled libopus, which needs cmake at build time. Turning opus off removes both the crates and that build requirement.

The feature also decides whether scan treats .opus files as playable at all, so a build that cannot decode Opus will not index Opus files either. An Opus file that reaches such a build fails to decode with a message naming the missing feature and is skipped, exactly like any unplayable file.

spectrum and web-ui

spectrum only affects the server: with it off no frames are computed or broadcast, and clients simply show no bars — nothing else changes, and no client needs rebuilding. web-ui drops the embedded browser client; the gRPC service on port 50051 still serves cbd-tui and the CLI.

Examples

A local-files appliance — no network providers, no web UI, no FFT:

cargo build --release -p crabidy-server \
  --no-default-features --features fs,opus

A streaming box with the browser client and the bars, no local library:

cargo build --release -p crabidy-server \
  --no-default-features --features tidal,web-ui,opus,spectrum

The bundle, tailored the same way (its features forward to the server):

cargo build --release -p cbd --no-default-features --features fs,opus

A terminal client with no D-Bus dependency:

cargo build --release -p cbd-tui --no-default-features

--no-default-features on its own is legal and compiles: you get a server that starts, serves an empty library and plays nothing. It is the base case the feature matrix checks, not a useful deployment.

What is not behind a feature

• Authorization. [auth] and its password hashing always ship. A build that ignored configured role hashes would silently run an intended-to-be-locked server open — a fail-open hole not worth a small dependency.
• Audio output. The server is the player; a server without audio has no purpose.
• HLS streaming and the spectrum tap. They bring no dependencies of their own, so gating them would add build complexity and save nothing.

Checking combinations

devenv shell -- check-features runs the curated matrix — defaults, no features, each provider alone, each extra dropped, both examples above, and the client crates — and requires every one to be clippy-clean. Run it after changing anything that sits behind a feature.