REX Player接入Jellyfin教程:如何把自家媒体服务器变成mpv视频库

原创2026-10-27 13:35:142,216 阅读

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 仪表盘"现在播放"面板中的暂停、进度拖动、换音轨、切字幕等指令,会实时下发到手机播放器。

REX Player 基于 mpv 的 Android 播放器播放界面,配合 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 中:

  1. 打开设置:主界面进入"设置 → Integrations → Jellyfin",入口代码位于 PreferencesScreen.kt;
  2. 填写凭据:在 "Jellyfin Server" 卡片中依次输入 Server URL、Username、Password(密码框为掩码显示);
  3. 点击 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 仪表盘能"指挥"手机播放,继续在同一设置页操作:

  1. 打开 Enable remote target 开关,应用会启动前台服务并注册设备能力(POST /Sessions/Capabilities/Full,声明支持 Video/Audio、Play、SetVolume、切换音轨字幕等指令);
  2. 在 Device name 中给设备起个易识别的名字(最长 32 字符,默认是手机型号),点击 Save device name;
  3. 点击 Register now 立即注册,随后客户端会建立 WebSocket 长连接并保持 30 秒一次的 KeepAlive,断线后按 5s→60s 指数退避自动重连(核心逻辑在 JellyfinRemoteClient.kt)。

REX Player 接入 Jellyfin 后 Now Playing 播放列表窗口,远程设备播放控制效果

完成注册后,在 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。

REX Player 更多设置面板,远程受 Jellyfin 控制的 Extended Controls 播放控制项

进度检测的入口在播放器启动阶段:PlayerActivity.kt 调用 JellyfinExternalHelper.kt 判断 Intent 是否来自 Jellyfin,是则挂载整套同步逻辑。

六、接入后的播放体验

REX Player 本身基于 libmpv,播放 Jellyfin 流媒体时享受完整本地播放能力:章节菜单、逐帧步进、手势控制、音轨字幕切换等一应俱全。

REX Player 章节菜单界面,播放 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 标签,设置页底部也提示了这一点。

八、相关源码文件位置

如果你想深入这套集成,以下文件是最快的阅读路径:


📌 小结:REX Player 接入 Jellyfin 只需"填地址 → 登录 →(可选)开远程设备"三步。登录后它就是 mpv 驱动的专业外部播放器,进度自动回传;开启 Play on 后,手机还能变成媒体服务器的远程播放端。配合 libmpv 的完整解码与手势能力,自建媒体服务器的移动端体验会提升一个档次。

登录后查看全文
REX-Player