jellyfin

name: jellyfin description: > Jellyfin media server architecture reference for building self-hosted media management systems. Use when: (1) Designing or building a media library/streaming system similar to Jellyfin/Plex/Emby, (2) Implementing media transcoding pipelines, HLS streaming, or FFmpeg integration, (3) Designing plugin/extension systems, scheduled task frameworks, or event-driven architectures, (4) Building React frontends with TanStack Query, legacy migration, or multi-app architecture, (5) Designing RESTful APIs with custom authentication, WebSocket communication, or media-specific endpoints, (6) Implementing metadata scraping systems, media file naming parsers, or EF Core data models with single-table inheritance, (7) Any task involving self-hosted media server architecture decisions.

Jellyfin Architecture Reference

Reference skill based on deep analysis of Jellyfin (GPLv2 open-source media server). Server: C#/ASP.NET Core (25 projects, 60 API controllers, ~303K LOC). Web: TypeScript/React (1094 files, ~280K LOC).

How to Use This Skill

1. Identify which subsystem is relevant to the current task
2. Read the corresponding reference file(s) from references/
3. Apply Jellyfin's patterns and decisions as architectural guidance

Read references on demand — each file is 500-1200 lines. Never load all at once.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   Clients (Web/Mobile/TV)            │
└──────────────────────┬──────────────────────────────┘
                       │ REST API + WebSocket
┌──────────────────────▼──────────────────────────────┐
│  Jellyfin.Server (ASP.NET Core Host)                │
│  ├── 21-layer Middleware Pipeline                    │
│  ├── 60 API Controllers (Jellyfin.Api)              │
│  └── Custom Auth (opaque token, 17 policies)        │
├─────────────────────────────────────────────────────┤
│  Service Layer (Emby.Server.Implementations)        │
│  ├── LibraryManager      — media library ops        │
│  ├── TranscodeManager    — FFmpeg process mgmt      │
│  ├── ProviderManager     — metadata scraping        │
│  ├── TaskManager         — scheduled tasks          │
│  ├── PluginManager       — plugin lifecycle         │
│  └── EventManager        — event pub/sub            │
├─────────────────────────────────────────────────────┤
│  Domain (MediaBrowser.Controller — interfaces)      │
│  Model  (MediaBrowser.Model — DTOs & config)        │
├─────────────────────────────────────────────────────┤
│  Data   (EF Core + SQLite, single DB)               │
│  ├── BaseItemEntity (single-table inheritance)      │
│  ├── UserData (play progress, favorites, ratings)   │
│  └── 28 entities, 15+ composite indexes             │
└─────────────────────────────────────────────────────┘

Key Design Decisions

Data Directory Structure

{ProgramDataPath}/
├── root/default/{Library}/   # Library structure (filesystem-based)
│   ├── *.collection          # Type marker (movies/tvshows/music)
│   ├── *.mblink              # Media path shortcuts
│   └── options.xml           # Library config
├── data/jellyfin.db          # SQLite main database (EF Core)
├── metadata/                 # Internal metadata & images
│   ├── People/  artists/  Genre/  Studio/  Year/
│   └── library/{guid}/      # Per-item internal metadata
├── config/                   # Modular XML configuration
├── plugins/{Name}_{Ver}/     # Plugin isolation by version
├── cache/images/             # Image cache
├── log/                      # App + FFmpeg logs
└── transcodes/               # Temp HLS segments (auto-cleaned)

Reference Files Guide

By Development Scenario

Reference File Index

Core Patterns Quick Reference

1. Media Library — Dual Storage Model

• Structure (filesystem): root/default/{Library}/ with .collection type marker, .mblink path pointers, options.xml config
• Content (database): BaseItemEntity single-table inheritance, ParentId + AncestorId for hierarchy
• Scan: ILibraryManager.ValidateMediaLibrary() full scan + LibraryMonitor filesystem watcher for incremental
• Naming: Emby.Naming library with 900+ line NamingOptions, 20+ regex patterns

2. Video Playback — Five-Stage Pipeline

Click → Negotiate (POST /PlaybackInfo) → Build URL → Serve Stream → Report Status
         DeviceProfile + StreamBuilder        ↓
         DirectPlay | DirectStream | Transcode
                                    FFmpeg via TranscodeManager
                                    HLS: master.m3u8 → segments

3. Authentication — Custom Opaque Token

• NOT JWT. Server-generated tokens stored in DB, validated per-request
• 6 token extraction sources: Authorization header, X-Emby-Authorization, query param, cookie, etc.
• 17 authorization policies with IAuthorizationRequirement + IAuthorizationHandler pairs
• CustomAuthenticationHandler extracts claims from token

4. Plugin System — AssemblyLoadContext Isolation

plugins/{Name}_{Version}/
├── meta.json       # Manifest (guid, name, version, status, targetAbi)
├── *.dll           # Assemblies (loaded in isolated context)
└── ...

• IPluginServiceRegistrator for DI integration
• Multi-version coexistence, auto-activate highest compatible
• 5 lifecycle states: Active → Disabled → Uninstalled → Superceded → Restart

5. Scheduled Tasks — Trigger + Worker Pattern

• IScheduledTask interface with 4 trigger types: Daily, Weekly, Interval, Startup
• TaskManager with ConcurrentQueue + ScheduledTaskWorker execution engine
• 20+ built-in tasks (library scan, transcoding cleanup, image extraction, etc.)

6. Metadata Scraping — ProviderManager Pipeline

• 6 provider types: IRemoteMetadataProvider, ILocalMetadataProvider, IImageProvider, etc.
• Priority-based refresh queue, 7-step refresh pipeline
• 26 MetadataService subclasses (one per media type)
• Dual-layer sorting: HasOrder interface → MetadataProviderPriority enum fallback

7. Frontend State — TanStack Query Patterns

Three patterns, from simple to complex:

1. Basic: useQuery({ queryKey, queryFn }) inline
2. Factory: queryOptions() + separate hook file
3. Feature-scoped: use{Feature}Query + use{Feature}Mutation co-located

No Redux/Zustand — TanStack Query for server state, React Context for UI state only.

8. Frontend Migration — Legacy Bridge

• renderComponent(el, Component) mounts React inside Legacy containers
• RootContext wraps all bridge renders with full provider stack
• queryOptions factory enables Legacy code to access TanStack Query cache
• Event bus (Events.on/off/trigger) for cross-framework communication

Startup Sequence (Server, 13 Steps)

1. Parse CLI args → 2. Init paths + logging → 3. Create IHost → 4. Migrate DB →
2. Register 60+ DI services → 6. Build middleware pipeline → 7. Init IServerApplicationHost →
3. Discover plugins + assemblies → 9. Run code migrations → 10. Start IHostedServices →
4. Validate media libraries → 12. Start scheduled tasks → 13. Open network listener

Entity Relationship Core

User ──1:N──> Permission (library access, parental control)
User ──1:N──> UserData ──N:1──> BaseItemEntity
User ──1:N──> Device (sessions)

BaseItemEntity (single table, Type discriminator)
  ├── self-ref: ParentId (direct parent)
  ├── AncestorId table (ancestor chain for deep queries)
  ├── ItemValue table (genres/studios/tags, M:N normalized)
  ├── Chapter table (video chapters)
  ├── MediaStream table (video/audio/subtitle tracks)
  ├── People table (actors/directors, with role + sort order)
  └── TrickplayInfo table (thumbnail timeline previews)