Magnus Hedemarkandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2140d0d58d
Full lastfm-model rebuild of the jellyfin skill against the 12.0-era OpenAPI spec, core-dev authorization guidance, and server source: - Document the researched auth sequence end to end: complete pre-token Authorization: MediaBrowser Client/Device/DeviceId/Version header required by POST /Users/AuthenticateByName (400 "Error processing request." without it), AccessToken returned, then Token= on the same header (legacy X-Emby-Token deprecated, disableable since 10.11, targeted for removal at 12.0). - Extend scripts/jellyfin: new `login` subcommand demonstrating the pre-token header and printing session exports (password via stdin/prompt/env only), seasons/episodes TV navigation, next-up --series-id, browse --user-id (userId is required on non-API-key auth per the ItemsController guard), modern Token= header transport with X-Emby-Token fallback, 503 Retry-After handling, search Id/deprecated-ItemId fallback. - Add 5 cited reference files (auth/sessions, endpoint catalog, user-scoping matrix, gotchas field guide, worked recipes) plus quick-connect; all cite api.jellyfin.org and live-verified sources. - Upgrade relocated scripts/test_jellyfin_cli.py to the double-runner standard: 24 tests (was 8) covering help, argument errors, dry-run, mocked login header sequence, TV navigation, search-id fallback, and jq-executed pipeline-consumability chains; zero egress proven via proxy-trap rerun. - Add evals/evals.json (6 cases incl. emby-install-not-for-jellyfin negative probe); rewrite SKILL.md (224 lines) and README; sync root README blurb and skill-triggers row; regenerate marketplace.json and llms.txt (description-embedding artifacts). Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
3.1 KiB
Jellyfin Media Server from the Terminal
Query your Jellyfin media library — recently added movies and episodes, search and inspect items, walk series, seasons, and episodes, browse library contents, see next-up episodes, log in as a user, and check server stats.
Why Install This Skill
When your agent loads this skill, it can navigate your home media server without opening a browser. That means:
- See what's new — recently added movies and TV episodes, filtered server-side
- Search your library — find any movie, show, or episode by keyword
- Navigate series — walk a show's seasons and episodes, and see what's next unwatched
- Browse collections — list your libraries and page through everything in them
- Authenticate properly — log in as a user (or use Quick Connect) without fumbling
Jellyfin's unusual
MediaBrowserauthorization header, which trips up most scripts - Check server details — server name, version, operating system, user count, counts
Every command is read-only (plus a login helper), and --dry-run previews any request
without touching the network.
What You Get
| Path | Purpose |
|---|---|
SKILL.md |
Complete command reference with setup, gotchas, and recipes |
scripts/jellyfin |
CLI for Jellyfin API operations (--json, --dry-run) |
scripts/test_jellyfin_cli.py |
Offline test suite (all HTTP mocked) |
references/auth-and-sessions.md |
The MediaBrowser header scheme, login flow, token channels, deprecation timeline |
references/endpoint-catalog.md |
Endpoint-by-endpoint parameter and response-shape catalog |
references/user-scoping-and-errors.md |
Which calls need a user id, and why queries 400/404 without one |
references/gotchas-field-guide.md |
Wire-level failure signatures and version differences |
references/worked-recipes.md |
Multi-step curl/jq and CLI workflows |
references/quick-connect.md |
Passwordless Quick Connect login |
evals/evals.json |
Behavioral eval cases including negative triggers |
Quick Start
scripts/jellyfin --help
export JELLYFIN_URL="http://your-server:8096"
export JELLYFIN_API_KEY="your-api-key" # Dashboard → API Keys
export JELLYFIN_USER_ID="your-jellyfin-user-id" # required by user-scoped commands
scripts/jellyfin search --query "dune" --type Movie --json
scripts/jellyfin recent --movies --limit 5
No API key yet? Log in as a user instead — the script sends the pre-token
Authorization: MediaBrowser Client=..., Device=..., DeviceId=..., Version=... header
that POST /Users/AuthenticateByName requires and prints the values to export:
scripts/jellyfin login --username alice --prompt
Triggers
Load this when asking about Jellyfin, media server content, recently added movies or TV, next-up episodes, browsing your home media library, or Jellyfin API authentication.
Requirements
Python 3.8+ with requests. A running Jellyfin server (10.8+ behaviors assumed).
Authentication: an API key (Dashboard → API Keys), a user access token via login, or
Quick Connect. User-scoped commands also need a Jellyfin user id.