136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
# Tailored builds
|
|
|
|
<!-- toc -->
|
|
|
|
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](./config.md#enabling-and-disabling-providers).
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
cargo build --release -p cbd --no-default-features --features fs,opus
|
|
```
|
|
|
|
A terminal client with no D-Bus dependency:
|
|
|
|
```sh
|
|
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.
|