crabidy/docs/src/providers.md

Providers

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.

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), 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, 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.
3. Did it initialize? Only a client that came up successfully is mounted.

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.
• /abs — audiobooks from a self-hosted audiobookshelf server. Needs a server URL and an API key (abs.toml).
• /fs — a local music folder: directories become nodes, *.cbd-track.toml files become tracks. No login (fsdy.toml).
• /fyyd — podcast search over fyyd's public API: find a podcast, drill into its episodes, play them. No account of any kind (fyyd.toml).
• /jamendo — 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 — podcast feeds you subscribe to by URL, including premium per-subscriber feeds. Always shows the newest episodes; nothing is cached (rss.toml).
• /soundcloud — SoundCloud search, link resolving, and playback with no credentials at all; an optional token adds your likes and playlists (soundcloud.toml).
• /tidal — a Tidal account: playlists, favorite artists and their albums, mixes, and search. Interactive device login on first start (tidaly.toml).
• /youtube — 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 for how that works across providers.