# Providers

<!-- toc -->

Everything crabidy can play lives in one library tree addressed by path.
The tree is not one monolithic source: it is composed from several
**providers**, each mounted as a subtree under a top-level path prefix.
A single **orchestrator** owns the synthetic root, lists the mounted
providers as its children, and routes every request to a provider by the
first segment of the path.

```d2
direction: right

root: "/ (orchestrator)" {
  shape: rectangle
}

crabidy: "/crabidy — your saves & captures"
abs: "/abs — audiobookshelf audiobooks"
fs: "/fs — a local music folder"
fyyd: "/fyyd — podcast search"
jamendo: "/jamendo — Creative-Commons catalogue"
rss: "/rss — podcast subscriptions"
soundcloud: "/soundcloud — SoundCloud"
tidal: "/tidal — Tidal streaming"
youtube: "/youtube — YouTube search & playlists"
orphans: "/orphans — unreferenced store audio"

root -> crabidy: "route /crabidy/*"
root -> abs: "route /abs/*"
root -> fs: "route /fs/*"
root -> fyyd: "route /fyyd/*"
root -> jamendo: "route /jamendo/*"
root -> rss: "route /rss/*"
root -> soundcloud: "route /soundcloud/*"
root -> tidal: "route /tidal/*"
root -> youtube: "route /youtube/*"
root -> orphans: "route /orphans/*"
```

The root lists its children in a fixed order: `crabidy` first, `orphans`
last, and everything else alphabetically in between.

Because routing is purely by prefix, the providers are independent of
one another. They all speak the same node/track model (see [The library
model](./library.md)), so a client browses `/tidal` and `/fs` with the
same keys and the same code, and a track reached through one provider
can be queued alongside a track from another.

## Each provider is optional

A provider appears in the library only if it got that far, and three
independent things decide it:

1. **Was it built in?** Every provider sits behind a Cargo feature (all on by
   default). A binary built without one can never mount it — see [Tailored
   builds](./build-features.md), and `crabidy-server features` to see what a
   binary has.
2. **Is it enabled?** The `providers` list in `crabidy-server.toml` turns
   compiled-in providers on and off without a rebuild — see
   [Configuration](./config.md#enabling-and-disabling-providers).
3. **Did it initialize?** Only a client that came up successfully is mounted.

```admonish note
Initialization failure is **non-fatal**. A broken config file, missing
credentials, or a missing helper binary drops that one subtree with a
warning — the server and every other provider keep running. The only
exception is Tidal: a Tidal config that exists but cannot be loaded aborts
startup rather than silently dropping your account.
```

So the exact set of top-level entries depends on your build *and* your
configuration: `/tidal` needs a login, `/abs` needs
credentials, `/youtube` needs its client to build, `/fs` needs a readable
root directory, and `/crabidy` needs a writable state directory.

## Today's providers

Listed in the order the library root serves them.

- **`/crabidy`** — where the server writes everything you save: saved queues,
  bookmarks, and downloaded captures, backed by a content-addressed audio
  store. It has its own page: [The crabidy store](./store.md).
- **[`/abs`](./providers/abs.md)** — audiobooks from a self-hosted
  audiobookshelf server. Needs a server URL and an API key (`abs.toml`).
- **[`/fs`](./providers/fs.md)** — a local music folder: directories become
  nodes, `*.cbd-track.toml` files become tracks. No login (`fsdy.toml`).
- **[`/fyyd`](./providers/fyyd.md)** — podcast search over fyyd's public
  API: find a podcast, drill into its episodes, play them. No account of any
  kind (`fyyd.toml`).
- **[`/jamendo`](./providers/jamendo.md)** — Jamendo's catalogue of
  Creative-Commons music, by search or album. Works out of the box on a
  shipped app key; bring your own for your own rate limit (`jamendo.toml`).
- **[`/rss`](./providers/rss.md)** — podcast feeds you subscribe to by URL,
  including premium per-subscriber feeds. Always shows the newest episodes;
  nothing is cached (`rss.toml`).
- **[`/soundcloud`](./providers/soundcloud.md)** — SoundCloud search, link
  resolving, and playback with no credentials at all; an optional token adds
  your likes and playlists (`soundcloud.toml`).
- **[`/tidal`](./providers/tidal.md)** — a Tidal account: playlists,
  favorite artists and their albums, mixes, and search. Interactive device
  login on first start (`tidaly.toml`).
- **[`/youtube`](./providers/youtube.md)** — YouTube search, plus an
  account's saved playlists when cookies are configured (`ytdy.toml`).
- **`/orphans`** — store audio that no save references any more, surfaced so
  you can reclaim it (rename it into a save, queue it, or delete it). It is a
  view over the store, not a separate source, so it comes and goes with
  `/crabidy`.

Each provider page documents its tree, how to log in where that applies, and
every option in its config file.

Several providers expose a **search** subtree in which you create nodes
whose titles are your search terms; see [Search](./providers/search.md)
for how that works across providers.