Ubuntu 下 Jellyfin 播放器兼容性测试方案
一 测试目标与环境准备
- 目标：验证 Jellyfin 媒体服务器与 Ubuntu 客户端（浏览器与桌面应用）在不同编解码、字幕、HDR、网络条件下的播放兼容性与性能表现。
- 服务器部署方式：优先使用 APT 官方仓库或 Docker 部署，便于版本一致性与回滚；两者在 Ubuntu 上均被广泛采用且兼容性良好。若遇到安装阶段提示找不到包，需添加 Jellyfin 专用仓库后再安装。硬件加速方面，Jellyfin 支持 Intel Quick Sync、AMD AMF、nVidia NVENC/NVDEC 等，需提前安装对应驱动。客户端建议准备 Chrome/Edge、Firefox 与 Jellyfin Desktop（MPV 后端） 或 Kodi + Jellyfin 插件 两套方案，便于对比。
二 测试用例与判定标准
| 测试项 |
测试素材与条件 |
预期结果 |
判定标准 |
| 容器与基础连通 |
Docker/APT 部署后访问 http://服务器IP:8096 |
页面加载、登录、媒体库扫描正常 |
无 5xx/502，控制台无启动报错 |
| 浏览器播放 |
Chrome/Edge/Firefox 播放 H.264/H.265(HEVC) |
首帧起播 ≤ 2–3s，拖动流畅 |
CPU 占用合理（非硬解时不过载），无绿屏/花屏 |
| 桌面客户端播放 |
Jellyfin Desktop（MPV）或 Kodi 播放 |
音画同步，外挂字幕样式正确 |
外挂 SRT/ASS 渲染正常，无错位 |
| 字幕兼容性 |
SRT、ASS/SSA、PGS；UTF-8/GBK |
中文无方块乱码，样式生效 |
字幕字符完整、位置/描边正确 |
| HDR 与色调映射 |
HDR10/HLG 片源，SDR 显示器 |
画面不过曝/偏灰，色彩正确 |
启用硬解与色调映射后主观观感正常 |
| 硬件加速 |
Intel QSV、nVidia NVENC/NVDEC、AMD AMF |
硬解命中，CPU 占用显著下降 |
控制台显示解码为 QSV/NVDEC/AMF，CPU < 30%（视片源） |
| 4K 播放 |
4K/H.265、高码率（≥ 40 Mbps） |
起播 ≤ 3–5s，拖动顺畅 |
无卡顿/缓冲，网络抖动下可恢复 |
| 网络适应性 |
同一片源在 WAN/LAN 播放 |
自适应码率生效 |
自动回落到合适码率，无持续卡顿 |
| 音频格式 |
AAC、AC3、EAC3、DTS、FLAC |
声道、采样率、音轨切换正常 |
无爆音/无声/延迟 |
| 权限与挂载 |
媒体目录权限 755/644，SMB/NFS 挂载 |
媒体扫描与播放正常 |
控制台无权限报错，媒体可直读 |
三 关键配置与排错要点
- 硬件加速与驱动
- Intel QSV：在 Jellyfin 控制台将“硬件加速”设为 Intel Quick Sync (QSV)，并启用 色调映射（建议优先 OpenCL，与 VPP 二选一）。新版 jellyfin-ffmpeg ≥ 4.4.1-2 已内置 intel-media-driver（iHD），无需单独安装；旧版本可能需手动升级或使用带 iHD 的镜像。
- nVidia：安装 专有驱动 与 nvidia-container-toolkit，在 Docker 运行时添加 –gpus all 并将渲染设备映射至容器，Jellyfin 选择 NVENC/NVDEC。
- AMD：安装 AMF 驱动并在 Jellyfin 选择 AMF 加速路径。
- 字幕与字体
- 中文方块乱码通常由字体缺失导致，安装常用中文字体（如 Noto Sans CJK、文泉驿 等）后重启浏览器/客户端。
- 播放器选择
- 浏览器端优先 Chrome/Edge（H.264/H.265 支持较好）；若出现卡顿或字幕兼容问题，可改用 Jellyfin Desktop（MPV） 或 Kodi 作为外部播放器。
- 4K 与网络
- 4K 播放对 CPU/GPU、存储 I/O 与网络带宽较敏感；低配设备可能出现起播等待或卡顿，建议使用具备 Quick Sync 的 Intel 10 代及以上平台，并保证充足带宽与稳定的存储性能。
四 自动化与结果记录
- 自动化脚本建议
- 使用 ffmpeg 批量校验片源编码与分辨率：ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,width,height -of csv=p=0 input.mkv
- 使用 jellyfin-ffmpeg 验证硬解路径：jellyfin-ffmpeg -hwaccels 与 -decoders | grep h264_qsv/hevc_qsv/nvdec
- 使用 curl 与 jq 校验播放会话与转码状态：/Sessions 接口观察 PlayState 与 TranscodingInfo
- 记录模板
- 字段建议包含：Ubuntu 版本、Jellyfin 版本、客户端/浏览器、编解码/HDR、是否硬解、起播时延(s)、平均码率(Mbps)、CPU/GPU 占用(%)、结果（通过/失败）、备注。
