目录

Emby、Jellyfin 和 Plex 的连接信息

月光放映机连接 Emby、Jellyfin、Plex 时发送的客户端标识与请求头，供服务器管理员做路由与统计。

本页目录
  1. 通用标识
  2. User-Agent
  3. 请求超时
  4. Emby / Jellyfin
  5. 认证头
  6. 401 自动重连
  7. 播放进度上报
  8. Plex
  9. 令牌与直链
  10. 版本选择
  11. 极空间
  12. 反向代理配置提示
  13. 相关阅读

月光放映机可以作为客户端连接 Emby、Jellyfin 与 Plex 服务器，也支持极空间。

服务器管理员常常需要根据客户端标识做请求路由、统计或兼容处理。这里列出应用实际发送的标识信息，方便你在服务端配置规则。

通用标识

User-Agent

应用对所有服务端请求都会注入统一的 User-Agent：

MoonPlay/<版本名> (<版本号>; HarmonyOS)

例如 MoonPlay/1.2.11 (38; HarmonyOS)。

在测试或环境异常导致读不到版本信息时，回退为 MoonPlay/unknown。

少数服务端 SDK 要求特定的 UA（例如部分网盘 API 要求 pan.baidu.com 防盗链头），这类请求会显式覆盖默认 UA，不受上表影响。

请求超时

所有网络请求默认 15 秒超时，避免服务器不可达时客户端长时间无响应。

Emby / Jellyfin

认证头

应用使用 Emby 标准的 X-Emby-Authorization 头，格式为 MediaBrowser 方案加逗号分隔的键值对：

GET /Users/AuthenticateByName HTTP/1.1
Host: 192.168.1.10:8096
X-Emby-Authorization: MediaBrowser Client="<客户端名>", Device="<设备名>", DeviceId="<设备标识>", Version="<版本>", Token="<令牌>"
Accept: application/json
User-Agent: MoonPlay/1.2.11 (38; HarmonyOS)

字段含义：

  • Client —— 客户端名称，用于服务端识别接入的播放器
  • Device —— 设备名称
  • DeviceId —— 设备唯一标识
  • Version —— 客户端版本号
  • Token —— 登录后获得的访问令牌，仅在已认证后携带

首次认证时头中不含 Token；服务器返回令牌后，后续请求都会带上它。

401 自动重连

令牌失效时（例如在服务器上改过密码、或会话被踢），应用会用配置中的用户名密码自动重新认证并重试一次，不会直接报错中断。

并发触发 401 时只会发起一次重新认证，避免重复请求打爆服务端。

如果服务器配有客户端白名单或自定义鉴权，注意放行上述 Client 名称。

播放进度上报

播放过程中应用会向 Emby / Jellyfin 的会话端点上报状态：

时机端点
开始播放POST /Sessions/Playing
播放中 / 暂停恢复POST /Sessions/Playing/Progress
播放结束POST /Sessions/Playing/Stopped

请求体关键字段：

  • ItemId —— 正在播放的媒体条目 ID
  • PositionTicks —— 播放位置，单位为 .NET 的 100ns 刻度（1 秒 = 10,000,000 ticks），与 Emby / Jellyfin API 规范一致
  • IsPaused —— 暂停状态

这些端点成功时返回 204 No Content，属于正常情况。

服务端需要保证该账号有会话上报权限，否则进度不会同步回服务器。

Plex

Plex 使用自定义的 X-Plex-* 头族标识客户端：

GET /library/sections HTTP/1.1
Host: 192.168.1.10:32400
X-Plex-Product: 月光放映机
X-Plex-Client-Identifier: <本安装唯一标识>
X-Plex-Version: <应用版本>
X-Plex-Device-Name: HarmonyOS
X-Plex-Platform: HarmonyOS
X-Plex-Token: <访问令牌>
Accept: application/json
User-Agent: MoonPlay/1.2.11 (38; HarmonyOS)

字段说明：

  • X-Plex-Product —— 产品名，显示在 Plex 服务器的「已授权设备」列表中
  • X-Plex-Client-Identifier —— 客户端唯一标识。按 Plex 规范每次安装生成一个 UUID 并持久化，因此同一台设备重装后会呈现为新设备
  • X-Plex-Version —— 客户端版本
  • X-Plex-Device-Name / X-Plex-Platform —— 设备与平台信息，均为 HarmonyOS
  • X-Plex-Token —— 授权令牌

若持久化不可用（如异常环境），会回退到固定的 moonplay-default-client。

令牌与直链

Plex 的图片地址与媒体直链都要求携带 X-Plex-Token，因此部分请求会把令牌作为 URL 查询参数传递，而不是放在请求头里：

/photo/:/transcode?width=300&height=450&url=/library/metadata/1234/thumb/1699999999&X-Plex-Token=######

如果你在反向代理或日志中做脱敏，记得同时处理查询参数里的令牌。

版本选择

Plex 支持同一影片挂载多个版本（不同分辨率 / 不同来源）。应用会读取服务端返回的 Media 列表，在播放前提供清晰度选择，选择结果在当前设备上会被记住。

极空间

极空间通过其专有接口接入。应用以统一的文件源接口适配，对上层媒体库保持透明，因此极空间上的影片与其他来源在浏览体验上一致。

反向代理配置提示

把服务器通过反向代理暴露到公网时，注意：

  • 不要剥离或改写 X-Emby-Authorization、X-Plex-* 头
  • 确认代理放行了 Accept: application/json
  • /Sessions/Playing* 端点返回 204，代理不要把空响应体判为错误
  • 进度上报是定时请求，代理的超时时间不要设得太短
  • 若启用了 WAF，注意不要拦截带令牌的查询参数

相关阅读