Plex photo library as an artwork source

[danmunz]

Problem

Docent currently supports two artwork sources: direct file uploads and Google Drive folder sync. Users with existing Plex Media Server setups have curated photo libraries that they would like to browse and send to their Frame TV without re-uploading everything manually.

Source: Reddit comment — user asked about running Docent on/with Plex from a home server.

Context

Plex cannot replace Docent (it has no Samsung Art Mode integration), but Plex can serve as an image source. Plex exposes photo libraries via its HTTP API, including metadata, thumbnails, and full-resolution downloads. Docent already has a pattern for external sources (Google Drive sync), so this would be a second source integration following the same model.

Proposed Design

New endpoints

GET  /api/plex/status          → connection status, library count
GET  /api/plex/libraries       → list photo libraries on the server
GET  /api/plex/libraries/{id}  → paginated browse with thumbnails
POST /api/plex/import          → pull selected images into Docent → TV

Configuration

Add to .env:

PLEX_URL=http://192.168.1.x:32400
PLEX_TOKEN=<token>

Plex tokens are obtained from the user's Plex account (Settings → Authorized Devices or via X-Plex-Token in any Plex web request). No OAuth flow needed — just a static token.

Import flow

1. Browse — User opens a "Plex" source tab in the Docent UI. Docent calls GET /api/plex/libraries which proxies to GET {PLEX_URL}/library/sections?X-Plex-Token={token} and returns photo-type libraries.

2. Preview — User browses a library. Docent calls Plex's /library/sections/{id}/all for photo metadata and /photo/:/transcode?width=400&height=400&url=... for thumbnails. Results are paginated and displayed in a grid matching the existing gallery layout.

3. Select & Import — User picks one or more images. Docent fetches full-resolution files from Plex (/library/metadata/{id}/...), applies the standard image pipeline (downscale to ≤3840×2160, convert to JPEG if needed), uploads to TV via art.upload(), and saves metadata with "source": "plex" and "plex_metadata_id" for dedup tracking.

4. AI analysis — If auto-analyze is enabled, imported images go through the same Claude/OpenAI vision pipeline as any other upload.

Dedup

Track plex_metadata_id in artwork_meta.json (same pattern as drive_file_id for Google Drive). Skip already-imported images during browse and warn on re-import attempts.

UI

• New source tab/section in the import area alongside existing upload and Google Drive options
• Grid view of Plex library contents with thumbnail previews
• Multi-select with batch import
• Import progress indicator (reuse existing loading overlay)
• Connection status indicator in Settings panel

Dependencies

• python-plexapi package (or raw HTTP calls to Plex API — no SDK strictly required since it is a simple REST API)
• Plex Media Server running on the local network with at least one photo library

Out of scope

• Plex music/video libraries (photo libraries only)
• Two-way sync (Docent → Plex)
• Plex OAuth login flow (use static token)
• Automatic re-sync / watch for changes (manual import only for v1)

Verification

1. Configure PLEX_URL and PLEX_TOKEN in .env
2. GET /api/plex/status returns connected with library count
3. Browse a photo library — thumbnails render in the Docent UI
4. Import a photo — appears on TV with source: "plex" in metadata
5. Re-browse — already-imported photos are marked/skipped
6. Import with auto-analyze on — AI metadata is populated