Jellyfin Integration API¶

Referenced Files in This Document

Table of Contents¶

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction¶

This document provides comprehensive API documentation for Nexo’s integration with the Jellyfin media server and The Movie Database (TMDB). It covers endpoints for synchronizing video libraries, managing media metadata, coordinating with Jellyfin’s internal state, scanning operations, incremental synchronization, conflict resolution, user account management, playlists, watch history synchronization, error handling, setup examples, scheduling, troubleshooting, performance optimization, and caching strategies.

The goal is to enable developers and operators to integrate, operate, and troubleshoot the system effectively across large media libraries while maintaining reliability and performance.

Project Structure¶

Nexo exposes a FastAPI-based service under apps/service that orchestrates:

Jellyfin integration routes and client logic
TMDB API access and indexing helpers
Core scanning, matching, confidence scoring, and pipeline orchestration
Shared models and schemas for persistence and request/response contracts
Routes for users, history, decisions, logs, status, and configuration

graph TB

subgraph "Service Layer"

A["FastAPI App<br/>apps/service/app.py"]

B["Jellyfin Routes<br/>apps/service/routes/jellyfin.py"]

C["TMDB API<br/>apps/service/api/tmdb.py"]

D["TMDB Indexing<br/>apps/service/api/tmdb_index.py"]

E["Scan Orchestration<br/>apps/service/core/scan.py"]

F["Pipeline<br/>apps/service/core/pipeline.py"]

G["Matcher<br/>apps/service/core/matcher.py"]

H["Confidence Scoring<br/>apps/service/core/confidence.py"]

I["History Models/Schemas<br/>shared/models/history.py<br/>shared/schemas/history.py"]

J["User Models/Schemas<br/>shared/models/user.py<br/>shared/schemas/user.py"]

K["Users Route<br/>apps/service/routes/users.py"]

L["History Route<br/>apps/service/routes/history.py"]

end

subgraph "External Systems"

M["Jellyfin Server"]

N["TMDB API"]

end

subgraph "State"

O["Cache State<br/>cache/jellyfin_state.json"]

end

A --> B

A --> C

A --> D

A --> E

A --> F

A --> G

A --> H

A --> I

A --> J

A --> K

A --> L

B --> M

C --> N

D --> N

E --> F

F --> G

G --> H

F --> I

F --> J

B --> O

Diagram sources

Section sources

Core Components¶

Jellyfin Integration: Provides endpoints to list libraries, scan items, update metadata, sync watch progress, and manage Jellyfin-specific state.
TMDB Integration: Endpoints to fetch movie and TV show details, cast information, and poster images; includes an indexing helper for efficient lookups.
Scan and Pipeline: Orchestrates library scanning, item processing, matching against external references, confidence scoring, and decision application.
History and Users: Manages watch history records and user accounts with corresponding schemas and route handlers.
State Persistence: Maintains Jellyfin sync state and operational status in cache files for incremental syncs and recovery.

Key responsibilities:

Jellyfin routes coordinate with the Jellyfin client and persist state for incremental updates.
TMDB API layer abstracts remote calls and caches results where appropriate.
Core modules implement deterministic matching and confidence thresholds to resolve conflicts.
History and User routes expose CRUD and synchronization endpoints backed by shared models and schemas.

Section sources

Architecture Overview¶

The service exposes REST endpoints via FastAPI. Jellyfin routes call into the Jellyfin client and coordinate with core scanning and pipeline modules. TMDB routes call into the TMDB API and use indexing utilities for faster retrieval. History and Users routes interact with shared models and schemas for persistence and validation.

sequenceDiagram

participant Client as "Client"

participant App as "FastAPI App"

participant JellyfinRoute as "Jellyfin Routes"

participant JellyfinClient as "Jellyfin Client"

participant Scanner as "Scan/Pipeline"

participant Matcher as "Matcher"

participant Confidence as "Confidence"

participant TMDB as "TMDB API"

participant State as "Jellyfin State Cache"

Client->>App : "POST /api/jellyfin/sync"

App->>JellyfinRoute : "Dispatch to sync endpoint"

JellyfinRoute->>JellyfinClient : "List libraries and items"

JellyfinClient-->>JellyfinRoute : "Library and item data"

JellyfinRoute->>Scanner : "Start scan and pipeline"

Scanner->>Matcher : "Match items to external refs"

Matcher->>Confidence : "Compute confidence scores"

Confidence-->>Matcher : "Scores and decisions"

Scanner->>TMDB : "Fetch missing metadata/cast/posters"

TMDB-->>Scanner : "Metadata responses"

Scanner->>JellyfinClient : "Update metadata and progress"

JellyfinRoute->>State : "Persist incremental state"

JellyfinRoute-->>Client : "Sync job status"

Diagram sources

Detailed Component Analysis¶

Jellyfin Integration Endpoints¶

Primary responsibilities:

List and discover Jellyfin libraries and items
Trigger full or incremental scans
Update media metadata (titles, descriptions, posters)
Sync watch progress and resume points
Manage Jellyfin user accounts and playlists
Persist and restore incremental sync state

Typical endpoints include:

Library discovery and listing
Scan initiation (full/incremental)
Metadata update operations
Watch progress synchronization
User management (create/update/delete/list)
Playlist management (create/update/delete/list)
State inspection and reset

Operational notes:

Incremental sync relies on persisted state to avoid reprocessing unchanged items.
Conflict resolution uses confidence thresholds to decide whether to overwrite existing metadata or keep current values.
Network failures are retried with backoff where applicable; partial syncs record failures per item and continue processing.

Example flows:

Initial library setup: Discover libraries, run full scan, apply metadata, then switch to incremental mode.
Scheduled sync: Periodic jobs trigger incremental scans and apply pending updates.

Error handling:

Authentication errors return explicit codes and messages to guide credential fixes.
Network timeouts and rate limits are handled with retries and graceful degradation.
Partial syncs report per-item outcomes and allow resuming from failure checkpoints.

Section sources

Jellyfin Sync Sequence¶

sequenceDiagram

participant Admin as "Admin UI"

participant API as "Jellyfin Routes"

participant Client as "Jellyfin Client"

participant State as "State Cache"

Admin->>API : "Request incremental sync"

API->>State : "Load last sync checkpoint"

API->>Client : "Query updated items since checkpoint"

Client-->>API : "Updated items"

API->>API : "Apply metadata and progress updates"

API->>State : "Save new checkpoint"

API-->>Admin : "Sync result summary"

Diagram sources

TMDB Integration Endpoints¶

Responsibilities:

Fetch movie and TV show details (title, overview, release date, genres, etc.)
Retrieve cast lists and key roles
Download poster images and thumbnails
Provide indexed lookup helpers for faster queries

Typical endpoints include:

Get movie info by ID or search query
Get TV show info by ID or search query
Get cast details for a given title
Fetch poster image URLs and assets
Indexing helpers to precompute and cache popular titles

Caching strategy:

Responses are cached locally to reduce external API load and improve latency.
Indexing utilities maintain lightweight mappings for quick lookups.

Error handling:

Rate limiting and network errors are retried with exponential backoff.
Missing resources return structured errors indicating not found vs. transient failures.

Section sources

TMDB Lookup Flow¶

flowchart TD

Start(["Request Title Info"]) --> CheckIndex["Check TMDB Index Cache"]

CheckIndex --> |Hit| ReturnCached["Return Cached Result"]

CheckIndex --> |Miss| QueryTMDB["Call TMDB API"]

QueryTMDB --> Success{"Success?"}

Success --> |No| HandleError["Handle Error/Retry"]

Success --> |Yes| CacheResult["Cache Response"]

CacheResult --> ReturnResult["Return Data"]

HandleError --> ReturnError["Return Error"]

ReturnCached --> End(["Done"])

ReturnResult --> End

ReturnError --> End

Diagram sources

Scan and Pipeline Orchestration¶

Responsibilities:

Coordinate scanning of local media and Jellyfin libraries
Apply pipeline stages: parse, match, score, decide, update
Track progress and handle interruptions gracefully

Key modules:

Scan: Entry point for initiating scans and collecting items
Pipeline: Staged processing with hooks for each stage
Matcher: Matches items to external references using heuristics and identifiers
Confidence: Computes confidence scores and applies decision rules

Conflict resolution:

Uses confidence thresholds to determine whether to accept external matches or retain local metadata.
Supports manual overrides and audit trails for decisions.

Section sources

Matching and Decision Flow¶

flowchart TD

Item(["Media Item"]) --> Parse["Parse Metadata"]

Parse --> Match["Match External Ref"]

Match --> Score["Compute Confidence"]

Score --> Threshold{"Above Threshold?"}

Threshold --> |Yes| Accept["Accept External Match"]

Threshold --> |No| KeepLocal["Keep Local Metadata"]

Accept --> Update["Update Jellyfin/TMDB Assets"]

KeepLocal --> LogDecision["Log Decision"]

Update --> Done(["Complete"])

LogDecision --> Done

Diagram sources

History and User Management¶

Responsibilities:

Manage user accounts (create, update, delete, list)
Synchronize watch history between Jellyfin and local records
Provide schemas for consistent request/response structures

Endpoints:

User CRUD operations
History listing, creation, updates, and synchronization
Bulk operations for initial setup and reconciliation

Data models and schemas:

History model and schema define fields for timestamps, progress, and references
User model and schema define identity, roles, and preferences

Section sources

Dependency Analysis¶

The service exhibits clear separation of concerns:

Routes depend on API clients and core modules
Core modules depend on shared models and schemas
External dependencies are isolated behind API layers (Jellyfin, TMDB)
State persistence is centralized in cache files for incremental operations

graph LR

Routes["Routes"] --> Core["Core Modules"]

Core --> Models["Shared Models/Schemas"]

Routes --> External["External APIs"]

External --> TMDB["TMDB API"]

External --> Jellyfin["Jellyfin Server"]

Core --> State["State Cache"]

Diagram sources

Section sources

Performance Considerations¶

Use incremental syncs to minimize network overhead and processing time.
Cache TMDB responses and leverage indexing helpers to reduce repeated API calls.
Batch updates when updating Jellyfin metadata to reduce round trips.
Implement concurrency controls to avoid overwhelming external APIs.
Monitor and tune confidence thresholds to reduce unnecessary updates.
Persist checkpoints frequently to support resumable operations.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Common issues and resolutions:

Authentication failures: Verify credentials and permissions for Jellyfin and TMDB; check error codes returned by endpoints.
Network timeouts: Enable retries and adjust timeouts; inspect logs for transient failures.
Partial syncs: Review per-item outcomes and resume from the latest checkpoint.
Conflicts: Adjust confidence thresholds or manually override decisions for problematic items.
Large libraries: Increase batch sizes cautiously, monitor resource usage, and schedule off-peak operations.

Operational tips:

Inspect state cache files to verify incremental checkpoints.
Use status endpoints to monitor ongoing jobs and recent failures.
Validate external API availability before running heavy syncs.

Section sources

Conclusion¶

The Jellyfin Integration API provides robust endpoints for library synchronization, metadata management, and coordination with Jellyfin’s internal state. Combined with TMDB integration, scanning and pipeline orchestration, and strong error handling, it supports reliable operation across large media libraries. By leveraging incremental syncs, caching, and careful conflict resolution, operators can achieve high performance and resilience.

[No sources needed since this section summarizes without analyzing specific files]

Appendices¶

Example Workflows¶

Initial library setup:
Discover libraries and run a full scan
Apply metadata and posters
Switch to incremental sync mode
Scheduled sync operations:
Configure periodic jobs to trigger incremental scans
Monitor status and handle failures gracefully
Troubleshooting common problems:
Check authentication and network connectivity
Review per-item outcomes and resume from checkpoints
Adjust confidence thresholds and retry policies

[No sources needed since this section provides general guidance]