Skip to content

Jellyfin Integration API

Referenced Files in This Document

Table of Contents

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. 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]