# Libraries, the catalog, and the screens

You tell the operator where your media is and which metadata
providers to use. It scans the media into a catalog, and every screen
in the namespace shows that catalog. The API has three resources, all
in a namespace:

* A `MetadataProvider` is one account with one metadata provider,
  such as TMDb. You declare it once.
* A `Catalog` is the namespace's shared catalog. You declare one for
  each namespace. It creates the catalog pod, which always holds a
  copy of the namespace's SQLite catalog, and it sets the size of
  every claim that holds a copy.
* A `Library` is one root directory on a volume, and it says which
  kind of media is there. You declare one for each directory.

For each `Library`, the operator runs `Jobs`, one at a time. A `Job`
scans the volume on the `Library`'s schedule and writes rows into the
namespace's catalog. A webhook from Radarr, Sonarr, or Jellyfin runs
the same scan over only the folders it names. In the same `Job`,
beside the scan, the enrichment phases ask each provider that the
`Library` names for metadata, and write the answers beside the media, as the `.nfo` files
and the art that Kodi and Jellyfin read. The `Job` ends when the
catalog pod confirms that it has the `Job`'s rows. Each `Job` reads
and writes the catalog through a Corrosion agent on the `Library`'s
catalog claim.

The catalog is built from the files on the volume, so the operator can
always build it again.

A screen is a `Player` that `media-operator` owns. When the
`Player`'s idle controller names this operator, the operator runs a
pod on the `Player`'s display with a Corrosion agent and the media
browser. The browser reads its own copy of the catalog, gets the
remote's presses over the message bus, and publishes what a person
picked. The operator turns that into a `Play`.

Every `Library` in a namespace writes to the same catalog, and every
screen in that namespace shows it.