How daudk3/jellycli works
Project Type and Purpose
• This is a standalone, terminal-based (TUI) client for a Jellyfin media server.
• It provides a keyboard-focused interface (built with Textual) that lets users browse libraries, search, play media via mpv, and synchronize playback progress via Jellyfin’s REST API and OIDC SSO.
High-Level Architecture
┌──────────────────┐ HTTP/API ┌────────────────────┐
│ │ ────────────────> │ │
│ UI Layer │ │ Jellyfin Server │
│ (Textual TUI) │ <─────────────── │ (Media + SSO) │
│ │ Webhooks │ + OIDC Provider │
└──────────────────┘ └────────────────────┘
│
│ mpv CLI invocation
▼
┌───────────┐
│ mpv │
│ Player │
└───────────┘
Main Internal Components
• UI (ui/):
• app.py – starts the Textual application.
• css.py – styling.
• screens/ – library, login, media detail, server setup, modals.
• API Client (api/jellyfin.py):
• Wraps HTTP calls (requests) to fetch libraries, items, resume/progress endpoints.
• Handles authentication flows (password vs. OIDC SSO via browser redirect).
• Models (models/media.py):
• Domain objects (MediaItem, Series, Episode, etc.) used by UI and persistence.
• Playback (playback/tracker.py):
• Launches mpv as a detached process with appropriate URL/headers.
• Polls or listens for progress, posts updates back to server.
• Configuration (config.py + config.json at runtime):
• Reads/writes user preferences, server URL, credentials, oidc provider name, greeting toggle.
• Utilities (utils/):
• time.py – formatting timestamps and durations.
• generic helpers for JSON I/O, error handling, etc.
Component Relationships & Data Flow
• UI triggers user actions (e.g., “Enter” to play item) → calls API client to get playback URL → hands URL to Playback module → mpv process starts.
• Playback module reports resume position requests to API client, which issues HTTP PATCH/POST for progress sync.
• On startup, UI calls API client to authenticate:
• Password flow → direct HTTP POST.
• OIDC flow → API client opens browser, listens for callback, exchanges code for tokens.
• UI uses Models to represent API responses; Models are passed to screens for rendering.
• Config loader populates UI login screen or server URL screen if config missing.
Architectural Patterns & Principles
• Layered architecture:
• Presentation (UI)
• Application/API client
• Domain models
• Infrastructure (playback, config, utils)
• Single-process, modular design: separate Python packages by responsibility.
• Clear separation of concerns: UI code does not deal with HTTP or OS calls directly.
• External dependencies injected or wrapped (e.g., mpv binary on PATH, requests library).
Technologies & Frameworks
• Python 3.10+
• Textual (rich + curses-style TUI)
• Requests (HTTP client)
• mpv (media playback CLI)
• OIDC SSO plugin on Jellyfin
• JSON file for config persistence