Media Server Integration¶

Referenced Files in This Document - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/app.py - apps/dashboard/src/pages/MediaServer.tsx - apps/shared/config.py - cache/jellyfin_state.json - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py - apps/service/deps.py - apps/service/main.py

Introduction¶

This document explains the media server integration interface, focusing on Jellyfin connectivity, library synchronization, and media file management via the web dashboard. It covers connection setup, sync status monitoring, error handling for connection issues, retry mechanisms for failed synchronizations, browsing and metadata synchronization, bulk operations, configuration options (including authentication and network timeouts), troubleshooting common connectivity problems, performance optimization for large libraries, and guidance for extending support to additional media servers.

Project Structure¶

The media server integration spans backend routes, a Jellyfin client, shared configuration, and the dashboard UI: - Backend API routes expose endpoints for connection testing, listing libraries, triggering scans/syncs, and retrieving status. - The Jellyfin client encapsulates HTTP interactions with the Jellyfin server. - Shared configuration centralizes settings such as server URL, API key, and timeout values. - The dashboard provides a user interface to configure connections, browse libraries, trigger syncs, and monitor progress. - State persistence captures last-known sync state for recovery and resume.

graph TB
subgraph "Dashboard"
D_UI["MediaServer.tsx"]
end
subgraph "Service"
R_JF["routes/jellyfin.py"]
APP["app.py"]
DEPS["deps.py"]
PIPE["core/pipeline.py"]
SCAN["core/scan.py"]
UC["core/usecases.py"]
end
subgraph "Jellyfin Client"
C_JF["server/jellyfin.py"]
end
subgraph "Config & State"
CFG["shared/config.py"]
ST["cache/jellyfin_state.json"]
end
D_UI --> R_JF
R_JF --> C_JF
R_JF --> PIPE
R_JF --> SCAN
R_JF --> UC
R_JF --> CFG
R_JF --> ST
APP --> R_JF
APP --> DEPS
DEPS --> CFG

Diagram sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/app.py - apps/dashboard/src/pages/MediaServer.tsx - apps/shared/config.py - cache/jellyfin_state.json - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py - apps/service/deps.py

Section sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/app.py - apps/dashboard/src/pages/MediaServer.tsx - apps/shared/config.py - cache/jellyfin_state.json - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py - apps/service/deps.py

Core Components¶

Jellyfin route handlers: Provide REST endpoints for connection validation, library enumeration, scan triggers, and status retrieval. They coordinate with the Jellyfin client and core processing modules.
Jellyfin client: Encapsulates HTTP calls to Jellyfin, including authentication headers, pagination, and error mapping.
Configuration: Centralized settings for server URL, API key, and network timeouts; consumed by both client and routes.
Dashboard page: Renders configuration forms, lists libraries, initiates syncs, and displays progress/status.
State persistence: Stores last sync positions and results to support resuming and reporting.

Key responsibilities: - Connection setup and validation - Library discovery and browsing - Metadata synchronization and scanning - Bulk operations (e.g., refresh or re-scan multiple items) - Status monitoring and error reporting - Retry and backoff strategies for transient failures

Section sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/shared/config.py - apps/dashboard/src/pages/MediaServer.tsx - cache/jellyfin_state.json

Architecture Overview¶

The integration follows a layered architecture: - Presentation layer: Dashboard UI interacts with backend endpoints. - API layer: FastAPI routes validate inputs, orchestrate tasks, and return structured responses. - Domain layer: Pipeline, scan, and usecase modules implement business logic for scanning, matching, and updating. - Integration layer: Jellyfin client communicates with external Jellyfin server over HTTP. - Persistence: JSON-based state file tracks sync progress and outcomes.

sequenceDiagram
participant UI as "Dashboard UI"
participant API as "Jellyfin Routes"
participant Client as "Jellyfin Client"
participant Core as "Pipeline/Scan/UseCases"
participant Store as "State File"
UI->>API : "Test connection"
API->>Client : "Ping server"
Client-->>API : "OK or error"
API-->>UI : "Connection status"
UI->>API : "List libraries"
API->>Client : "Fetch library list"
Client-->>API : "Libraries"
API-->>UI : "Library list"
UI->>API : "Trigger scan/sync"
API->>Core : "Start pipeline/scan"
Core->>Store : "Persist progress"
Core-->>API : "Progress updates"
API-->>UI : "Status stream"

Diagram sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py - cache/jellyfin_state.json - apps/dashboard/src/pages/MediaServer.tsx

Detailed Component Analysis¶

Jellyfin Route Handlers¶

Responsibilities: - Validate connection to Jellyfin using configured URL and API key. - Enumerate libraries and media items. - Trigger scans and metadata synchronization. - Expose status and logs for ongoing operations. - Handle errors and map them to user-friendly messages.

Operational flow: - Input validation and authorization checks. - Delegation to the Jellyfin client for remote calls. - Orchestration of background tasks via pipeline/scan/usecases. - Progress tracking persisted to state store. - Responses include success data or actionable error details.

Error handling: - Network timeouts and DNS resolution failures are caught and surfaced. - Authentication failures indicate invalid credentials or server access issues. - Rate limiting or server busy states trigger retries with exponential backoff.

Retry mechanism: - Transient errors (timeouts, 5xx) are retried with configurable attempts and delays. - Non-retryable errors (401/403, malformed requests) fail fast with clear messages.

Configuration usage: - Reads server URL, API key, and timeout from shared config. - Applies per-request timeouts and respects global limits.

Section sources - apps/service/routes/jellyfin.py - apps/service/deps.py - apps/service/app.py

Jellyfin Client¶

Responsibilities: - Build authenticated requests to Jellyfin endpoints. - Paginate through large result sets efficiently. - Normalize responses into internal models. - Map HTTP errors to domain-specific exceptions.

Authentication: - Uses API key header or token-based auth depending on server configuration. - Supports optional TLS verification flags if required by environment.

Network behavior: - Configurable connect and read timeouts. - Retries on transient network errors with backoff. - Connection pooling and keep-alive where supported.

Section sources - src/server/jellyfin.py - apps/shared/config.py

Dashboard Page (MediaServer)¶

Responsibilities: - Present configuration form for Jellyfin server URL and API key. - Display connection test results and warnings. - List available libraries and allow selection. - Initiate scans/syncs and show real-time progress. - Surface errors and provide retry actions.

User interactions: - Save configuration to backend. - Test connection before saving. - Browse libraries and filter by type. - Trigger bulk operations (refresh/metadata update). - Monitor sync status and view logs.

Section sources - apps/dashboard/src/pages/MediaServer.tsx

Configuration and State¶

Configuration: - Centralized settings for Jellyfin server URL, API key, and timeouts. - Consumed by client and routes to ensure consistent behavior.

State persistence: - Last known sync position and results stored in a JSON file. - Enables resume after restart and accurate progress reporting.

Section sources - apps/shared/config.py - cache/jellyfin_state.json

Core Processing Modules¶

Pipeline: - Orchestrates multi-step workflows for scanning and syncing. - Coordinates between Jellyfin client and local processing.

Scan: - Iterates over media items, applies rules, and updates metadata. - Emits progress events and persists intermediate state.

Use cases: - Encapsulate business logic for specific operations like refresh or bulk updates. - Provide clean interfaces for routes to call.

Section sources - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py

Dependency Analysis¶

High-level dependencies: - Routes depend on client, config, and core modules. - Client depends on config for network parameters. - Dashboard depends on routes for all operations. - State file is used by routes and core modules for persistence.

graph LR
UI["Dashboard MediaServer.tsx"] --> R["routes/jellyfin.py"]
R --> C["server/jellyfin.py"]
R --> P["core/pipeline.py"]
R --> S["core/scan.py"]
R --> U["core/usecases.py"]
R --> CFG["shared/config.py"]
R --> ST["cache/jellyfin_state.json"]

Diagram sources - apps/dashboard/src/pages/MediaServer.tsx - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/core/pipeline.py - apps/service/core/scan.py - apps/service/core/usecases.py - apps/shared/config.py - cache/jellyfin_state.json

Section sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/service/app.py - apps/dashboard/src/pages/MediaServer.tsx - apps/shared/config.py - cache/jellyfin_state.json

Performance Considerations¶

Pagination: Use efficient pagination when enumerating large libraries to avoid memory spikes.
Concurrency: Limit concurrent requests to Jellyfin to respect server rate limits and reduce contention.
Timeouts: Tune connect and read timeouts based on network conditions and server responsiveness.
Caching: Cache stable metadata and library listings where appropriate to reduce repeated calls.
Batch operations: Prefer bulk endpoints for updates to minimize round trips.
Backpressure: Implement throttling and backoff to handle server load gracefully.
Indexing: Ensure Jellyfin server indexes are up-to-date to speed up queries.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Common connectivity issues: - Invalid server URL or unreachable host: Verify DNS resolution and firewall rules. - Incorrect API key or missing permissions: Confirm credentials and server-side access controls. - TLS/SSL errors: Check certificate validity and trust chain; adjust verification settings if necessary. - Timeouts: Increase timeout values or optimize server-side indexing.

Symptoms and resolutions: - Connection test fails: Re-check URL format, port, and API key; ensure service is running. - Sync stalls or slow progress: Reduce concurrency, enable pagination, and verify server health. - Frequent retries: Investigate server load and network stability; adjust retry policy.

Recovery steps: - Clear stale state file entries if sync was interrupted. - Restart services to reset connections. - Review logs for detailed error context.

Section sources - apps/service/routes/jellyfin.py - src/server/jellyfin.py - apps/shared/config.py - cache/jellyfin_state.json

Conclusion¶

The media server integration provides a robust interface for connecting to Jellyfin, synchronizing libraries, and managing media files through the dashboard. It emphasizes reliable connectivity, clear error reporting, and resilient retry mechanisms. With thoughtful configuration and performance tuning, it scales effectively to large media libraries. Extending support to additional media servers can follow the same layered pattern by implementing a new client and wiring it into the existing routes and UI.

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

Appendices¶

Configuration Options¶

Jellyfin server URL: Base address including scheme and port.
API key: Secret token for authenticated requests.
Network timeouts: Connect and read timeouts for HTTP calls.
Retry policy: Maximum attempts and backoff strategy for transient errors.
TLS verification: Enable/disable certificate verification as needed.

Section sources - apps/shared/config.py

Extending Support for Additional Media Servers¶

Steps: - Implement a new client module mirroring the Jellyfin client’s interface. - Add route handlers that delegate to the new client and core modules. - Update dashboard pages to support the new server’s configuration and features. - Persist state consistently and reuse existing retry/backoff patterns.

Section sources - src/server/jellyfin.py - apps/service/routes/jellyfin.py - apps/dashboard/src/pages/MediaServer.tsx