Media Images

Media images (posters, backdrops, logos and similar artwork) come from your configured library managers during the library sync, and Sovereign downloads and converts them on demand: Radarr supplies movie artwork, Sonarr supplies TV series, season, and episode artwork, and cast/crew headshots come from TMDb. Titles imported from a filesystem media source take all of their artwork from TMDb. Unlike trickplay and subtitles, images belong to the media item itself (a movie or TV series) rather than any individual file, so all versions of a title share the same artwork.

---

How It Works

1. During a library sync, Sovereign records the remote URLs for each image associated with a movie or TV series. It doesn’t download the images yet.
2. When a client asks for an image’s address, Sovereign checks whether the converted image is already on disk. If it isn’t, Sovereign queues a download job and the client gets no URL yet.
3. A background worker downloads the image from the remote source and converts it to JPEG, scaling it to suit its type (posters and headshots to 640 pixels wide, everything else to 1920).
4. Once the converted image is on disk, the client’s next request gets a signed URL for it.
5. Smaller copies for a particular display size are cut from that image the first time a client asks for one, and kept beside it.

sequenceDiagram
  participant C as Client device
  participant S as Sovereign
  participant W as Background worker
  participant R as Artwork source

  Note over S: The library sync recorded<br/>each image's remote address
  C->>S: Address for this image?
  alt Not on disk yet
    S->>W: Queue a download
    S-->>C: No address yet
    W->>R: Download the image
    W->>W: Convert and scale it
    C->>S: Address for this image?
  end
  S-->>C: A signed address
  C->>S: The image, at that address

---

Supported Image Types

Poster, Backdrop, Banner, Logo, Thumbnail, Screenshot, Fanart, and Headshot (cast/crew).

---

Storage

Each image is stored as a JPEG file, named by its type, under the directory for its parent media item. The {kind} segment is feature (movies), series (TV), or person (headshots). Display-sized copies sit in a subdirectory named for their width:

{assets}/images/{kind}/{shard}/{mediaId}/{ImageType}.jpg
{assets}/images/{kind}/{shard}/{mediaId}/w{width}/{ImageType}.jpg

---

Caching

Once an image is converted and its status is Ready, Sovereign serves it from disk on every later request without downloading it again. If the file has gone missing despite a Ready status, the server queues the download again on its own.