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
}

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), 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.

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 — streams from a Tidal account via the tidaldy crate: playlists, favorite artists and their albums, mixes, and search. Credentials live in tidaly.toml.
• /youtube — YouTube search and the logged-in account's playlists via the ytdy crate. Metadata is extracted in-process; config lives in ytdy.toml.
• /fs — 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.

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.