REX Player接入Jellyfin教程:如何把自家媒体服务器变成mpv视频库
REX Player接入Jellyfin教程:如何把自家媒体服务器变成mpv视频库
REX Player 是一款基于 libmpv 的现代化 Android 视频播放器,通过内置的 Jellyfin 集成,它可以直接对接你自建的 Jellyfin 媒体服务器:既能作为"外部播放器"打开服务器里的影片并自动同步播放进度,也能注册为 Jellyfin 的 Play on 远程设备,用服务器大屏遥控器控制手机上的 mpv 播放。本文带你完成 REX Player 接入 Jellyfin 的全流程。
一、接入 Jellyfin 后你能得到什么 🎬
REX Player 与 Jellyfin 的打通是"双向"的,覆盖两种典型使用场景:
- 外部播放器模式:在 Jellyfin 网页端或客户端选择"用外部应用播放"时,影片流直接交给 mpv 引擎解码,播放位置每 10 秒自动回传服务器,下次打开自动续播;
- Play on 远程设备模式:手机向服务器注册为受控设备,Jellyfin 仪表盘"现在播放"面板中的暂停、进度拖动、换音轨、切字幕等指令,会实时下发到手机播放器。
这套能力全部由 jellyfin/ 模块实现,无需任何第三方插件。
二、接入前准备:Jellyfin 服务器地址与账号
登录 REX Player 只需要三样东西:
| 需要信息 | 说明 |
|---|---|
| 服务器地址 | 形如 https://jellyfin.example.com,手机能访问到即可(同局域网或外网均可) |
| 用户名 + 密码 | Jellyfin 任意一个账号即可,不区分权限 |
| HTTPS 证书有效 | 使用 http:// 时凭据以明文传输,界面会给出安全警告,建议走 HTTPS |
另外说明一下安全性:服务器地址、用户 ID、访问令牌都通过 Android Keystore 的 EncryptedSharedPreferences 加密落盘,实现见 JellyfinPreferences.kt。
三、三步登录 Jellyfin 服务器:设置入口与 Sign in
整个登录过程只需 3 步,界面在 JellyfinSettingsScreen.kt 中:
- 打开设置:主界面进入"设置 → Integrations → Jellyfin",入口代码位于 PreferencesScreen.kt;
- 填写凭据:在 "Jellyfin Server" 卡片中依次输入 Server URL、Username、Password(密码框为掩码显示);
- 点击 Sign in:应用调用
POST /Users/AuthenticateByName完成认证(实现见 JellyfinApi.kt),成功后状态显示 "Connected as 用户名",令牌自动保存。
⚠️ 若填入的是
http://开头的地址,按钮上方会出现 "Using insecure HTTP" 警告;点击 Sign out 可随时清除凭据并断开连接。
登录成功后,Rex Player 在打开 Jellyfin 流地址时会自动识别影片身份——它从 /Videos/{id}/stream 流 URL 中直接解析 Item ID,不依赖文件名匹配,因此服务器改名、移动目录都不影响进度同步(解析逻辑见 JellyfinIdentityResolver.kt)。
四、开启 Play on 远程设备:让手机出现在媒体服务器列表
如果想让 Jellyfin 仪表盘能"指挥"手机播放,继续在同一设置页操作:
- 打开 Enable remote target 开关,应用会启动前台服务并注册设备能力(
POST /Sessions/Capabilities/Full,声明支持 Video/Audio、Play、SetVolume、切换音轨字幕等指令); - 在 Device name 中给设备起个易识别的名字(最长 32 字符,默认是手机型号),点击 Save device name;
- 点击 Register now 立即注册,随后客户端会建立 WebSocket 长连接并保持 30 秒一次的 KeepAlive,断线后按 5s→60s 指数退避自动重连(核心逻辑在 JellyfinRemoteClient.kt)。
完成注册后,在 Jellyfin 网页端打开任意影片并选择"Play on → 你的设备名",手机会:
- 自动拉取影片标题(剧集会拼成 "剧名 - S01:E02 - 集名" 的完整格式);
- 直接以
DirectPlay方式播放/Videos/{id}/stream流地址,并按服务器给定的起始位置续播(自动启动逻辑见 JellyfinRemoteClient.kt)。
五、播放时发生了什么:进度自动同步原理
播放开始后,双方进入"实时对话"状态:
- 上行(手机 → 服务器):每 10 秒上报一次
PositionTicks播放位置,暂停/停止/退出时立即上报/Sessions/Playing/Stopped,保证仪表盘进度条与"继续观看"数据始终准确; - 下行(服务器 → 手机):Jellyfin 的 Pause / Seek / NextTrack / SetVolume / Mute / SetAudioStreamIndex / SetSubtitleStreamIndex 等指令通过 WebSocket 直达 mpv 引擎,逐帧生效;
- 结束即记账:外部播放器模式下,播放位置回传给服务器后,"已观看"状态随之更新,实现见 JellyfinApi.kt。
进度检测的入口在播放器启动阶段:PlayerActivity.kt 调用 JellyfinExternalHelper.kt 判断 Intent 是否来自 Jellyfin,是则挂载整套同步逻辑。
六、接入后的播放体验
REX Player 本身基于 libmpv,播放 Jellyfin 流媒体时享受完整本地播放能力:章节菜单、逐帧步进、手势控制、音轨字幕切换等一应俱全。
七、Jellyfin 接入常见问题排查 🛠️
| 现象 | 可能原因与解决办法 |
|---|---|
| Sign in 提示 "Auth failed 401" | 用户名或密码错误;确认账户未被禁用 |
| 登录提示连接超时 | 手机无法访问该地址,检查网络/代理;外网访问注意域名解析 |
| 提示 "Authentication response missing token/user" | 服务器响应异常,检查 Jellyfin 版本与网络中间件 |
| 设备不出现在 Play on 列表 | 确认开关已打开并点击 Register now;用 logcat 过滤 JellyfinRemote 查看注册日志 |
| 播放后进度不回传 | 检查 WebSocket 是否保持(同一 logcat 标签),或切换 HTTPS/HTTP 重试 |
排查时最有用的一条线索:所有 Jellyfin 相关日志都输出到 JellyfinRemote / JellyfinApi 标签,设置页底部也提示了这一点。
八、相关源码文件位置
如果你想深入这套集成,以下文件是最快的阅读路径:
- 设置界面(登录 + 远程开关):JellyfinSettingsScreen.kt
- 认证与进度上报 API:JellyfinApi.kt
- WebSocket 远程控制客户端:JellyfinRemoteClient.kt
- 前台注册服务:JellyfinRemoteService.kt
- 外部播放器身份解析:JellyfinIdentityResolver.kt
- 加密凭据存储:JellyfinPreferences.kt
- ticks 时间单位换算工具:JellyfinTicks.kt
- 单元测试参考:JellyfinShimTest.kt、JellyfinWatchedTest.kt
📌 小结:REX Player 接入 Jellyfin 只需"填地址 → 登录 →(可选)开远程设备"三步。登录后它就是 mpv 驱动的专业外部播放器,进度自动回传;开启 Play on 后,手机还能变成媒体服务器的远程播放端。配合 libmpv 的完整解码与手势能力,自建媒体服务器的移动端体验会提升一个档次。



