embycovers/AGENT.MD

Emby Cover App Maintenance Guide

Purpose

This app is a FastAPI-based internal tool for generating and applying custom Emby artwork.

It currently supports:

• Searching Emby movies and series
• Generating a wide Thumb image
• Optionally generating a matching tall Primary poster
• Using Emby-known logos and backdrops already attached to the item
• Reframing any Emby or imported image in a premium artwork editor
• Exporting editor output as Primary, Thumb, or Backdrop
• Searching provider-backed external image sources and importing remote images into cache
• Applying generated artwork back to Emby
• Adding optional studio badges and a red NEW EPISODES series tag

The codebase is intentionally small and centralized:

• Backend and image pipeline: app.py
• Frontend UI, CSS, and browser logic: templates/index.html
• Static studio logos: static/studios/
• Generated cache files: cache/

Runtime Model

The app is mostly a single-server process with one HTML page.

• FastAPI serves the UI and JSON/image endpoints
• httpx.AsyncClient is reused for Emby API calls
• Pillow is used for all image composition
• The browser page is a single template with inline CSS and JS

There is no frontend build system and no database.

Configuration

Environment variables:

• EMBY_URL
• EMBY_API_KEY

Defaults are currently hard-coded in app.py. That is convenient for local usage but should be treated carefully if this app is ever shared more broadly.

Key Files

app.py

This file contains:

• App startup/shutdown
• Emby API helpers
• Image loading and upload helpers
• Font selection helpers
• The entire artwork render pipeline
• Search/image/apply API routes

This is the core of the system. Most behavior changes happen here.

templates/index.html

This file contains:

• Full UI markup
• Full CSS
• Full browser-side state management
• Search/pagination logic
• Asset picker logic for Emby-known logos and backdrops
• Generate/apply button behavior

There is no JS framework. Everything is plain DOM code.

How The App Works

1. Search flow

Browser:

• User types into the search box
• JS debounces and cancels stale requests
• GET /api/search is called with q, start, and limit
• Results are rendered in the left sidebar with lightweight poster images

Server:

• /api/search queries Emby /Items
• Returns paginated search results with metadata needed by the UI
• Search result posters are served via /api/poster/{item_id} using reduced dimensions for speed

2. Item image discovery flow

When an item is selected:

• The browser immediately starts a preview generate call
• In parallel, it calls GET /api/images/{item_id}

That endpoint returns the Emby-known images already attached to the item:

• logos
• backdrops
• primaries

The UI uses that to populate:

• Logo asset picker
• Backdrop asset picker
• Accurate backdrop counts

Important:

• This is Phase 1 of image browsing only
• It only exposes images Emby already knows for the item
• It does not yet perform remote/provider image lookup

3. Generate flow

Browser:

• POST /api/generate
• Sends the selected options:
  • background mode
  • selected backdrop index
  • selected logo index
  • logo position
  • logo size
  • darkness
  • studio badge
  • series tag
  • whether to also generate a matching primary poster

Server:

• Pulls Primary, selected Logo, and selected Backdrop from Emby
• Builds the wide thumb with generate_thumbnail(...)
• Writes the thumb to cache
• Optionally builds and caches a tall primary via generate_primary_cover(...)
• Returns the thumb image stream to the browser

4. Apply flow

Browser:

• POST /api/apply
• Sends the same effective rendering settings as generate

Server:

• Rebuilds the same cache key
• Reads the cached thumb if present
• If missing, regenerates on demand to avoid cache-miss 400 failures
• Uploads the thumb to Emby as Thumb
• If generate_primary is enabled, uploads the cached or regenerated tall poster as Primary

Important:

• Apply must remain tolerant of cache misses
• Do not reintroduce a hard dependency on a pre-existing cache file only

5. Artwork editor flow

Browser:

• The editor appears after an Emby item is selected
• Editor state is kept separate from the existing thumb-generator state object
• The editor has three panels:
  • source image panel
  • fixed-ratio editor canvas
  • export panel
• Users can choose Emby Primary, selected Emby Backdrop, Emby Thumb, or an imported remote image
• Users can target poster, thumb, or backdrop
• Users can drag, zoom, reset, and switch cover / contain
• Landscape-to-portrait conversion supports blurred, mirrored, or solid background fill
• POST /api/artwork/export generates a live preview and returns cache headers
• POST /api/artwork/apply uploads the cached or regenerated export to the matching Emby image type

Server:

• Editor rendering is separate from generate_thumbnail(...)
• render_artwork_editor_image(...) handles fixed-frame reframing and high-quality JPEG output
• fit_image_positioned(...) is the shared crop/contain positioning helper
• build_editor_fill(...) handles blurred, mirrored, and solid background fill
• resolve_editor_source_bytes(...) loads either Emby source bytes or cached remote imports
• Editor exports are cached as <cache_key>.editor.jpg
• Remote imports are cached under cache/imports/

Remote image search:

• Provider lookup is intentionally abstracted behind ImageSearchProvider
• GET /api/artwork/providers exposes available providers to the UI
• GET /api/artwork/search calls the selected provider
• POST /api/artwork/import downloads, validates, size-limits, and caches a selected remote image
• Current providers are Wikimedia Commons, optional TMDB, and optional Google Custom Search
• TMDB is enabled with TMDB_BEARER_TOKEN or TMDB_API_KEY
• Google Custom Search is enabled with GOOGLE_CUSTOM_SEARCH_API_KEY and GOOGLE_CUSTOM_SEARCH_ENGINE_ID
• Add future providers by implementing ImageSearchProvider and registering it in IMAGE_SEARCH_PROVIDERS

Rendering Pipeline

The central renderer is generate_thumbnail(...).

It is used for:

• Wide thumbs
• Tall primary covers, through generate_primary_cover(...)

Pipeline stages:

1. Resolve background
2. Crop/fit to target aspect ratio
3. Apply darkening and vignette
4. Resolve logo or fallback title text
5. Position logo/text based on selected alignment
6. Add studio logo overlay
7. Add optional NEW EPISODES tag
8. Encode as PNG

Layout assumptions

The renderer now contains separate behavior for tall layouts.

This matters because:

• Wide thumbnails and tall posters cannot share the same padding rules
• Tall primary posters need different bottom spacing and logo height caps

When changing artwork layout, always test both:

• 800x450 thumb
• 1000x1500 primary

Caching

Cache files live in cache/.

Current cache helpers:

• Thumb cache: <cache_key>.png
• Primary cache: <cache_key>.primary.png
• Artwork editor export cache: <cache_key>.editor.jpg
• Imported remote image cache: cache/imports/<sha256>.img

The cache key is derived from rendering inputs such as:

• item id
• backdrop index
• logo index
• colors
• logo position
• scale
• darkness
• studio settings
• series tag state

Important:

• If you add any new visual option, add it to build_cache_key(...)
• If you forget, the app will reuse stale cached artwork from a different configuration

Image Selection Rules

Logo images

Logo selection is index-based.

Notes:

• The app should always treat invalid or non-image logo responses as optional
• emby_get_image_optional(...) already guards against non-image content-types
• generate_thumbnail(...) also guards against invalid logo bytes and falls back to text

Do not make logo loading a hard-fail path.

Backdrops

Backdrop selection is index-based and uses the asset picker.

If a backdrop is unavailable:

• The render should still succeed
• The fallback is blurred poster or solid background

Upload Rules

Uploading back to Emby is done through emby_upload_image(...).

Current behavior:

• Upload source image is normalized to RGB JPEG
• Thumb and Primary uploads both use that path

Be careful when changing upload behavior:

• Emby may accept source formats differently than display formats
• The preview proxy can preserve PNG content-type
• The upload path currently standardizes to JPEG intentionally

Frontend State

The browser keeps a single state object in templates/index.html.

Key fields:

• item
• backdropIndex
• logoIndex
• imageInfo
• searchQuery
• searchStart
• searchLimit
• searchTotal
• generated

When adding a new visual option:

1. Add UI control
2. Add local JS state if needed
3. Include it in POST /api/generate
4. Include it in POST /api/apply
5. Add it to build_cache_key(...)
6. Apply it in the render pipeline

If any of those steps are skipped, behavior will drift.

Artwork editor state is intentionally separate:

• editorState.sourceKind
• editorState.sourceType
• editorState.sourceIndex
• editorState.importId
• editorState.cacheKey
• transform controls from the editor sliders

Keep editor payloads aligned across:

• /api/artwork/export
• /api/artwork/apply
• build_editor_cache_key(...)
• render_artwork_editor_image(...)

Laptop UX Constraints

The app has custom responsive rules for laptop-sized screens.

Areas that have already needed tuning:

• Preview area height
• Controls bar spacing
• Sidebar width
• Results panel layout

When changing layout:

• Test desktop wide view
• Test laptop-height view
• Test narrow desktop widths before mobile breakpoints

The controls container is particularly sensitive because the preview and controls compete vertically.

Known Fragile Areas

1. Cache key drift

Symptoms:

• Apply uploads unexpected artwork
• Generate/apply feel out of sync

Cause:

• A new option was added to rendering but not to build_cache_key(...)

2. Emby returns non-image content for optional assets

Symptoms:

• PIL UnidentifiedImageError

Cause:

• Emby returned HTML, JSON, or another unexpected response for an optional asset

Current guardrails already exist. Preserve them.

3. Tall poster layout quality

Symptoms:

• Tall primary poster logo sits too low
• Title/logo scale looks like a stretched thumb layout

Cause:

• Using wide-layout spacing assumptions on primary posters

Always treat primary layout as distinct.

4. Search feels slow

Symptoms:

• Listing poster thumbnails load slowly
• Search UI feels laggy

Current mitigations:

• Paginated search
• Smaller poster fetches
• Shared HTTP client
• Stale request cancellation

Avoid switching result posters back to full-size originals.

Safe Maintenance Workflow

When changing this app:

1. Read both app.py and the relevant section of templates/index.html
2. Keep generate/apply payloads aligned
3. Keep cache key aligned with render options
4. Test thumb and primary rendering
5. Run:

python -m py_compile app.py

6. Manually verify:
   • search
   • item select
   • generate
   • apply
   • optional primary generation
   • logo/backdrop asset switching

Recommended Future Enhancements

Likely next improvements:

• Additional image search providers from Emby metadata sources
• Better poster-specific typography/layout rules
• Better user-visible error reporting for partial apply failures
• Cache cleanup strategy

Rules For Future Agents

• Do not split backend logic into multiple files unless there is a strong reason. This app is currently maintainable specifically because it is centralized.
• Do not introduce a frontend framework casually. The current plain JS approach is appropriate for the app’s size.
• Do not remove the cache-miss regeneration fallback from apply.
• Do not assume Emby optional image endpoints always return valid images.
• Do not change wide-thumb behavior without checking tall-primary behavior too.
• If adding a new render option, update both generate and apply paths and the cache key in the same change.