Guides
The guides are in the order a cluster uses them: the install, a library over a volume, what a scan reads, the catalog it writes, the browser on a screen, enrichment from the providers, the webhooks that rescan an import, franchises as a library of their own, and what to expect on a small machine.
How the pieces fit
Three resources, all namespaced, are the whole API.
A MetadataProvider is one account with one provider, declared once.
A Catalog is declared once per namespace. It creates the catalog pod,
the one permanent member of the namespace’s replicated SQLite catalog,
and it sizes every catalog claim. A Library is declared once per root
directory on a volume, and it names the kind of media there.
The operator reconciles a Library into a CronJob. Each of its
Jobs walks the volume with a catalog agent beside it, writes rows
into the namespace’s catalog, and exits when the catalog pod echoes
its run back. A webhook from Radarr, Sonarr, or Jellyfin runs the same
walk over one folder. An enrich Job asks the providers a Library
names and writes the answers beside the media, as the sidecars and
art Kodi and Jellyfin read. The volume stays the source of truth, and
the catalog is derived from it.
A screen is a Player that media-operator owns. When its idle
controller names this operator, the operator runs a pod on the
Player’s display with the same catalog agent and the media browser.
The browser reads its own copy of the catalog, takes the remote’s
presses over the bus, and publishes what a person chose. The operator
turns that into a Play.
A namespace is the boundary. Every Library in it writes one catalog,
and every screen in it shows that catalog.