# 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
}

tidal: "/tidal — Tidal streaming"
youtube: "/youtube — YouTube search & playlists"
fs: "/fs — a local music folder"
crabidy: "/crabidy — your saves & captures"

root -> tidal: "route /tidal/*"
root -> youtube: "route /youtube/*"
root -> fs: "route /fs/*"
root -> crabidy: "route /crabidy/*"
```

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 is only mounted when its client initializes successfully. The
orchestrator holds each one as an optional handle and only adds its child
to the root listing when the client exists.

```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
orchestrator never fails to start because a single provider could not.
```

This means the exact set of top-level entries you see depends on your
configuration: `/tidal` needs a login, `/youtube` needs its client to
build, `/fs` needs a readable root directory, and `/crabidy` is always
present because the server owns it.

## Today's providers

- **[`/tidal`](./providers/tidal.md)** — streams from a Tidal account
  via the `tidaldy` crate: playlists, favorite artists and their albums,
  mixes, and search. Credentials live in `tidaly.toml`.
- **[`/youtube`](./providers/youtube.md)** — YouTube search and the
  logged-in account's playlists via the `ytdy` crate. Metadata is
  extracted in-process; config lives in `ytdy.toml`.
- **[`/fs`](./providers/fs.md)** — serves a local music folder. Folders
  become nodes and `*.cbd-track.toml` files become tracks. Config lives
  in `fsdy.toml`.
- **`/crabidy`** — where the server writes the things you save (saved
  queues, bookmarks, and downloaded captures), backed by a
  content-addressed store. It has its own page: [The crabidy
  store](./store.md).

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.