jellyfin

jellyfin — 在终端中使用 Jellyfin Media Server

通过 Jellyfin 服务的 REST API 查询最近添加的电影和电视剧集、搜索和检查媒体、按剧集 → 季 → 集逐级浏览、浏览媒体库、查看接下来要看的剧集、以用户身份登录，以及检查服务统计信息 —— 所有操作都通过 Jellyfin 服务的 REST API 完成。除 login 外，所有命令均为只读操作。

设置

1. 确保 Jellyfin 服务正在运行且可访问（默认地址为 http://localhost:8096）。
2. 选择一种身份验证方式：
   • API 密钥 — 仪表板 → API Keys → +。具有管理员级权限，不绑定用户身份： 因此，每个按用户范围执行的命令都需要显式指定用户 ID。
   • 用户令牌 — 运行一次 scripts/jellyfin login --username NAME --prompt；该命令会 打印要导出的值。
3. 设置以下环境变量：

export JELLYFIN_URL="http://your-server:8096"   # include protocol and port
export JELLYFIN_API_KEY="your-api-key-here"     # or JELLYFIN_TOKEN after `login`
export JELLYFIN_USER_ID="your-jellyfin-user-id" # required by recent, next-up, item, seasons, episodes

使用 scripts/jellyfin 运行捆绑的 CLI。无需凭据即可使用 --help 和 --dry-run。

身份验证的工作原理

Jellyfin 要求每次调用都携带 MediaBrowser 方案的 Authorization 标头。登录 端点要求在任何令牌生成之前提供 Client=...、Device=...、DeviceId=...、Version=... 这四项参数 ——— 否则服务会对 POST /Users/AuthenticateByName 返回 400 Error processing request.。之后，访问令牌（或 API 密钥）会通过同一个标头以 Token="..." 的形式传递；旧版 X-Emby-Token 标头含义相同，并计划在 Jellyfin 12.0 中移除。捆绑的 CLI 会发送现代格式，并且每次请求只通过这一个通道传递令牌（绝不会同时发送 X-Emby-Token）。 参见 references/auth-and-sessions.md。

基本命令

身份验证 — 获取会话

scripts/jellyfin login --username alice --prompt          # prints JELLYFIN_* exports
echo "pw" | scripts/jellyfin login --username alice --password-stdin
scripts/jellyfin login --username alice --dry-run --json  # preview the pre-token header

login 展示了完整的验证流程：完整的令牌生成前 MediaBrowser 标头 → POST /Users/AuthenticateByName → 获取 User.Id 和 AccessToken → 打印可重复使用的 令牌生成后标头。该命令绝不会回显密码。

info — 服务信息

scripts/jellyfin info              # server name, version, OS, user count
scripts/jellyfin info --json

recent — 最近添加的媒体

scripts/jellyfin recent                     # last 10 items added for JELLYFIN_USER_ID
scripts/jellyfin recent --movies --limit 5  # server-side includeItemTypes filter
scripts/jellyfin recent --episodes --limit 20 --json
scripts/jellyfin recent --user-id USER_ID   # override the env var

调用 /Items/Latest 并传入 userId；响应是一个纯 JSON 数组（没有 Items 包装对象），而 groupItems 会按剧集合并剧集，因此应将其视为“最新内容”。

search — 搜索媒体库

scripts/jellyfin search --query "dune"                  # everything
scripts/jellyfin search --query "dune" --type Movie     # comma-separated types
scripts/jellyfin search --query "star trek" --type Series,Episode --limit 5 --json

搜索会调用 /Search/Hints；结果包含 id（旧版服务还会提供已弃用的 ItemId 副本 —— CLI 已优先使用现代字段）。

导航 — 检查项目并逐级浏览剧集

scripts/jellyfin search --query "dune" --type Movie --json   # find an item ID
scripts/jellyfin item --id ITEM_ID                           # full metadata (needs user)
scripts/jellyfin seasons --series-id SERIES_ID               # list seasons
scripts/jellyfin episodes --series-id SERIES_ID --season-id SEASON_ID
scripts/jellyfin next-up --limit 10                          # next unwatched episodes
scripts/jellyfin next-up --series-id SERIES_ID --user-id USER_ID

item、seasons、episodes 和 next-up 按用户范围执行：它们需要 JELLYFIN_USER_ID 或 --user-id；如果未提供其中任何一个，会在发起网络调用前失败。

libraries — 浏览媒体库

scripts/jellyfin libraries                                   # library IDs and types
scripts/jellyfin browse --library-id LIBRARY_ID --type Movie --limit 50
scripts/jellyfin browse --library-id LIBRARY_ID --start-index 50   # paginate
scripts/jellyfin browse --library-id LIBRARY_ID --user-id USER_ID  # userId sent explicitly

libraries 会读取 /Library/MediaFolders，该接口仅限管理员 — 非管理员令牌会收到 403，应改用 /UserViews（参见参考资料）。browse 会使用 startIndex/limit 对 /Items 分页，并在提供 userId 时传入它，因为使用非 API 密钥 身份验证的服务会拒绝未指定范围的查询，并返回 400 userId is required。

stats — 媒体库统计信息

scripts/jellyfin stats    # movie, series, episode, song counts (/Items/Counts)

管道用法示例

查找剧集，然后获取接下来要看的未观看剧集

scripts/jellyfin search --query "breaking bad" --type Series --json | jq -r '.results[0].id'
scripts/jellyfin next-up --series-id "$SERIES_ID" --user-id "$JELLYFIN_USER_ID" --json | jq -r '.items[0].name'

对整个媒体库进行分页浏览

scripts/jellyfin browse --library-id "$LIB_ID" --limit 100 --start-index 0 --json | jq -c '.items'
# loop: advance --start-index by the returned count until .total_record_count is reached

登录并持久保存会话

scripts/jellyfin login --username alice --prompt --json | jq -r '"\(.user_id) \(.access_token)"'

JSON 和 jq

将 --json 放在子命令之前或之后均可。输出键采用稳定的蛇形命名格式：items （包含 id、name、type、year、series、season_number、episode_number）、 results、libraries、total_record_count、start_index。--dry-run 会输出一个包含 dry_run、path 和 params 的计划（login 会额外添加 authorization_header；info 会组合一个 requests 列表），其内容与实际发送的请求一致，因此可以在实际执行前用 jq 验证命令链。退出码：成功（包括试运行）为 0，CLI/API 错误为 1，参数错误为 2。可使用 jq -r '.items[] | [.name, .year] | @tsv' 以制表符分隔的格式传递数据。

已知注意事项

• JELLYFIN_URL 必须包含协议和端口——例如 http://192.168.1.100:8096。
• 按用户范围执行的命令必须明确指定用户——如果没有 JELLYFIN_USER_ID/--user-id，recent、next-up、item、seasons、episodes 都会拒绝执行。CLI 不会替你选择管理员。使用用户令牌的请求若缺少 userId，服务端会返回 400 userId is required。
• API 密钥没有关联用户——出于设计原因，API 密钥访问 /Users/Me 会收到 400 Token is not owned by a user.；按用户查询需要明确指定用户 ID（参见 references/user-scoping-and-errors.md）。
• 登录时的 400 与 401 陷阱——缺少或不完整的 MediaBrowser 标头会返回带纯文本 Error processing request. 的 400；凭据错误则返回 401。同一端点，不同的失败结果。
• 不同端点的响应结构各异——/Items 和 /Shows/* 会将结果封装在 {Items, TotalRecordCount, StartIndex} 中；/Items/Latest 返回裸数组；搜索使用 SearchHints 键。通用客户端必须分情况处理（CLI 已处理）。
• 最近项目的类型筛选在服务端进行——--movies/--episodes 会在 limit 之前转换为 includeItemTypes；不会在本地筛选。
• NextUp 在所有服务端版本中都需要 userId——省略该参数会导致 ≤10.8 的服务端崩溃，并在 ≥10.9 时静默限定为会话用户。CLI 始终会发送该参数。
• libraries 仅限管理员使用——/Library/MediaFolders 需要管理员令牌；非管理员令牌会收到 403。
• 旧版身份验证即将弃用——X-Emby-Token、X-MediaBrowser-Token 和 api_key 查询参数已弃用；管理员已可禁用它们（10.11+），目标是在 12.0 移除。请优先使用 CLI 发送的现代 Authorization 标头。
• 延迟身份验证——无需凭据即可使用 --help 和 --dry-run；试运行绝不会访问网络。

适用场景

此技能适用于对运行中的 Jellyfin 服务进行只读交互：发现新增内容、搜索和检查项目、浏览剧集和季、规划接下来要观看的内容、查看媒体库清单，以及通过 login 或 Quick Connect 获取用户会话。

不适用场景

请勿将此技能用于服务端安装或管理（安装 Jellyfin 或 Emby、编辑媒体库、管理用户）——除 login 外，所有捆绑命令均为只读。它不适用于 Plex 或 Kodi（API 不同，请使用各自的工具），也不能用作播放远程控制工具：流媒体播放或远程控制自动化请使用 Jellyfin 官方客户端。

参考文件

文件	用途
references/auth-and-sessions.md	MediaBrowser 标头方案、登录流程、令牌渠道、旧版功能弃用、错误特征
references/endpoint-catalog.md	每个读取端点的参数、响应结构、图片 URL、分页循环
references/user-scoping-and-errors.md	userId 要求对照表、API 密钥身份特性、400 与 404 的诊断
references/gotchas-field-guide.md	网络层故障特征、版本差异记录、模拟数据结构
references/worked-recipes.md	多步骤 curl/jq 和 CLI 配方：登录 → 最新内容，媒体库 → 浏览，搜索 → 季 → 集
references/quick-connect.md	无密码 Quick Connect 登录流程

可用脚本和先决条件

• scripts/jellyfin——捆绑的 Python CLI（--json、--dry-run、延迟身份验证）。 仅导入标准库和 requests。
• scripts/test_jellyfin_cli.py——离线测试套件（兼容 pytest 和 unittest）； 所有 HTTP 行为均为模拟，不会产生任何网络流量。
• 需要 Python 3.8+ 和 requests。需要运行中的 Jellyfin 服务（假定为 10.8+；测试行为以 12.0 时代的 OpenAPI 规范为基准）。此技能不会启动任何服务。