Core concepts¶
A short tour of the entities Stillwater is built around. If you've followed Getting started, you've already used most of these in passing. This section explains the shape of each one and how they connect.
-
Artists and libraries
The two foundational entities. Libraries are folders (or remote sources) of music; artists are the people and groups inside them.
-
Auto-provisioning
How Stillwater creates a local account for a federated user on first sign-in, the guard rails that restrict who qualifies, and how roles are assigned.
-
Conflict gate
How Stillwater detects when a connected media server is configured to write files that would collide with its own writes, and pauses output until the collision source is resolved.
-
Field locks
The mechanism that keeps your manual edits from being overwritten by refreshes, fixers, or connected platforms.
-
Images
Four image slots per artist -- thumb, fanart, logo, banner -- with platform-specific naming, multi-fanart, and resolution thresholds.
-
NFO files
The XML metadata format every supported platform reads. Stillwater parses, edits, and writes Kodi-compatible artist.nfo files.
-
Platform profiles
Named bundles of image filename conventions and NFO field-map settings that tell Stillwater how to write files for a specific media server.
-
Providers
Ten metadata providers, queried in per-field priority order with caching and ID propagation.
-
Rules
Checks that run against artists. Each rule has three meaningful states (disabled, manual, auto) and a fixer that resolves violations.
How the pieces fit¶
Library ---owns---> Artists
| |
| +--- has an NFO file
| +--- has 4 image slots
| +--- can be locked (whole or per-field)
| +--- is evaluated by Rules
| |
| +--- which call Providers
| +--- and produce fixable violations
|
+--- decides scan + watch behavior
+--- holds the connection to Emby / Jellyfin / Lidarr (or "manual")
+--- NFO + image writes shaped by the active Platform profile
+--- NFO + image writes gated by the Conflict gate
Users sign in via a local account or a federated provider (Emby, Jellyfin, OIDC). Auto-provisioning creates a local account from the federated identity on first sign-in, subject to the provider's guard rail.
Most workflows touch three or four of these at once. A "refresh this artist's biography" run walks: artist → providers (in priority order) → field locks (which fields to skip) → platform profile (which NFO field map to use) → NFO file (atomic write) → conflict gate (paused if a platform is meddling). Knowing the pieces makes the workflow legible.