使用场景

Share 已经能通过 OpenList 浏览和分享文件,但“能下载视频”和“适合在网页里看视频”之间,还差音轨、字幕、格式兼容和转码这些东西。

Jellyfin 本身就有媒体库和播放协商能力,我想把这些能力接到微光集现有的文件预览里,打开分享后就能看,不需要再跳到另一套媒体界面找一遍影片。

整体介绍见 关于本站:微光集,文件入口和分享权限见 OpenList文件分享对接。

OpenList 决定这个文件能不能访问,Jellyfin 负责这个视频怎么播放,微光集负责把它们接到同一个界面里。

实现内容

功能实现方式
媒体识别从 OpenList 文件路径找到 Jellyfin 已入库的媒体
媒体展示读取电影、剧集、季、分集信息及海报,组织媒体列表和合集
播放协商根据浏览器能力、画质、码率、音轨和字幕请求播放方案
格式兼容使用直接播放、转封装或转码,编码工作交给 Jellyfin
音轨与字幕在现有播放器里切换,必要时重新协商播放源
播放记录当前浏览器记录进度,切换播放源时带上当前位置
章节与片段读取章节、媒体片段,组织播放器时间轴
弹幕通过独立的 DanmuApi 匹配、搜索并读取弹幕

本站 Video 页的 Bilibili 播放使用官方 iframe,和这条 Jellyfin 链路分开。

对接入口与部署关系

入口仍然在 Share。分享元数据中的 jellyfin: true 用来启用媒体匹配,普通文件浏览继续使用原有预览流程。

Share 文件 / 分享项目
    ↓ OpenList 校验文件权限
Go 解析文件实际路径
    ↓ 只读查询 Jellyfin 媒体库
匹配电影 / 剧集 / 分集
    ↓ Jellyfin PlaybackInfo 协商
浏览器播放器 ← 本站媒体接口 ← Jellyfin 播放资源

配置需要区分内部服务地址和浏览器公开地址:

  • api.jellyfin.url:Go 访问 Jellyfin 的内部地址。
  • api.jellyfin.publicUrl:浏览器使用的媒体服务公开地址。
  • api.jellyfin.token:后端调用 Jellyfin 的 API Key。
  • JELLYFIN_DB:Go 只读挂载的 Jellyfin 数据库路径。

公开媒体地址下的 /api/public/quartz/jellyfin/ 转给本站 Go 服务。文件服务和媒体服务可以使用不同域名。

当前代码在未配置 Token 时,还会尝试读取 Jellyfin 数据库中最新创建的 API Key。这是现有兼容行为,排查鉴权问题时需要留意实际使用的是哪一个密钥。

文件如何匹配到媒体

匹配先调用 OpenList 的 fs/get,确认文件或分享路径能够访问,再解析它对应的实际文件位置。

对于本地存储,Go 会读取 OpenList 挂载点与根目录,将虚拟路径转换成物理路径。分享内部的 /@s/{分享标识}/… 也要先还原到分享者的目录范围。

随后使用物理路径查找 Jellyfin 数据库 BaseItems 中的媒体条目,再通过 Jellyfin API 取得播放信息。

当前播放匹配依赖本地存储的路径映射和精确文件路径,不是拿文件名去搜索影片。

文件存在但没有匹配到时,优先检查:

  1. 分享是否启用了 Jellyfin。
  2. OpenList 挂载驱动是否为当前适配的 Local。
  3. 解析后的路径是否和 Jellyfin 数据库里的 Path 一致。
  4. Jellyfin 是否已扫描该文件,是否返回可用的媒体源。

其他存储驱动不会因为配置了 Jellyfin 地址,就自动获得这套本地路径匹配能力。

登录、授权与凭据

访问者不需要再登录一次 Jellyfin。文件访问范围沿用 OpenList 的访客、管理员或分享提取码规则。

匹配成功后,后端生成随机的匹配标识;开始播放时再生成播放会话,返回本站媒体地址。Jellyfin API Key 保留在服务端。

后续播放协商会重新校验匹配标识对应的文件访问权限。流资源使用会话内登记的资源标识,HLS 清单中的资源地址也会改写。

会话地址本身也属于临时访问凭据,不适合当成长期公开的下载链接。播放会话有失效与清理机制,后台重启后需要重新建立。

本站登录身份和 Jellyfin 用户不是逐个绑定的。 当前后端使用指定的Jellyfin账号。默认字幕等设置来自这个接入账号,不是每位访客都有独立的 Jellyfin 个人配置。

不过并非是用账号密码登录Jellyfin,而是用Jellyfin API Key获取用户列表来使用配置。

播放器与播放协商

前端沿用文件预览中的 Artplayer,在独立播放器页面中处理播放、字幕和弹幕。本站页面与播放器通过消息传递同步所需状态。

开始播放时,前端提交浏览器能力、画质、音轨、码率上限、字幕和播放位置。Go 把这些条件交给 Jellyfin 的 PlaybackInfo,再从返回结果中选择可用方案。

  • 直接播放:媒体本身满足当前播放条件。
  • 转封装:调整容器或传输方式,尽量保留可直接使用的视频流。
  • 转码:编码、画质或字幕烧录等条件要求重新处理媒体。

Go 不负责编码视频。 转码的 CPU、GPU、硬件加速及临时文件消耗仍发生在 Jellyfin 服务端。

切换画质、音轨或需要烧录的字幕时,可能需要更换播放源。请求会带上当前位置;离开页面、停止或清理会话时,后端会释放对应资源,并请求 Jellyfin 停止相关转码。

播放进度由本站浏览器存储,不是 Jellyfin 多设备同步的观看记录。

字幕处理

字幕默认选择交给 Jellyfin,根据接入账号的语言、字幕模式和已有设置返回 DefaultSubtitleStreamIndex。本站明确保存过的选择或关闭状态优先,不再单凭文件名猜测应该打开哪条字幕。

类型处理方式
普通文字字幕使用浏览器字幕能力或本站文字层,可调整外观
ASS / SSA使用 libass 渲染,保留字幕自身样式及字体;加载期间可先使用 VTT 文字字幕
PGS当前默认由 Jellyfin 烧录到视频中
Safari / iOS按当前兼容策略,将选中的字幕交给 Jellyfin 烧录

Fontinass 参与现有字幕处理链路。文字字幕的字号、颜色、位置等外观保存在当前浏览器,影片之间共用;ASS 不套用这套文字外观,烧录字幕也不能由网页文字层直接修改。

Safari 开字幕可能触发视频转码,这是当前兼容策略的代价。遇到“关闭字幕正常,打开字幕卡顿”,需要检查服务端转码能力,而不只是网页渲染。

Fontinass缓存

Fontinass字幕加载会需要拉取Jellyfin的字幕并缓存,会存在一定等待时间影像播放体验。

解决方案:
使用Jellyfin插件Subtitle Extract设置计划任务,预先缓存字幕文件,Fontinass便可以直接读取缓存,缩短加载时间。

弹幕对接

弹幕来源是 DanmuApi,不是 Jellyfin 原生接口。

后端根据文件名及媒体信息请求匹配,也提供搜索作品、选择分集和读取弹幕的接口。浏览器负责显示、开关和播放时间同步。

DanmuApi 接口用途
/api/v2/match按文件名自动匹配
/api/v2/search/anime搜索作品
/api/v2/bangumi/{id}读取作品及分集信息
/api/v2/comment/{id}?format=json读取对应弹幕

自动匹配可能选错版本或集数,媒体识别成功也不代表弹幕一定准确。弹幕服务独立配置、独立缓存,排查时要把它和视频播放分开看。

使用的 API

以下是当前实现用到的主要 Jellyfin 原生接口,内部调用由 Go 携带 X-Emby-Token。

Jellyfin 接口用途
GET /Users确定可用的接入用户
GET /Users/{userId}/Items/{itemId}读取媒体详情
GET /Items/{itemId}/PlaybackInfo?UserId=…读取媒体源、音轨及默认字幕
POST /Items/{itemId}/PlaybackInfo按设备能力和播放参数协商
GET /Items?Ids=…批量读取合集相关条目
GET /Items/{itemId}/Images/{kind}海报、背景等图片
GET /MediaSegments/{itemId}媒体片段信息
GET /Playback/BitrateTest?Size=…播放链路码率测试
/Videos/{itemId}/…协商得到的视频流、HLS 及字幕资源
DELETE /Videos/ActiveEncodings?DeviceId=…&PlaySessionId=…结束对应转码

本站桥接接口统一位于 /api/public/quartz/jellyfin/ 下:

本站接口用途
POST lookup校验文件权限、匹配媒体,返回临时匹配标识
POST media、POST collections媒体列表与合集
POST aliases读取分享内的文件别名
POST playback建立播放会话、返回播放方案
POST danmaku弹幕匹配、搜索和读取
POST stop停止本站播放会话
GET player独立播放器页面
GET image/{id}读取授权范围内的媒体图片
GET / HEAD stream/{session}/{key}读取会话已登记的媒体资源
GET / HEAD subtitle/{match}/{index}/{file}读取匹配媒体的字幕资源

路径匹配、媒体列表和合集组织还会只读查询 Jellyfin 数据库。升级 Jellyfin 后,需要一起确认数据库结构和播放响应的兼容性。

缓存与异常处理

媒体索引、详情和合集使用短时缓存,弹幕按搜索、作品和评论分别缓存,减少重复访问上游。视频并没有提前全部同步到本站。

匹配记录和播放会话保存在后端内存中,有数量限制与清理任务。媒体流按请求代理,公开字体可以使用浏览器持久缓存,私有字幕和媒体不会混进这份字体缓存。

表现优先检查
没有媒体信息分享开关、存储驱动、路径映射、媒体扫描
能看到海报但不能播放PlaybackInfo、媒体源、浏览器编码支持
打开字幕后才变慢烧录策略、Jellyfin 转码与硬件加速
更换画质后失败新会话协商、转码日志、媒体代理请求
弹幕为空或不对应DanmuApi、作品匹配、分集选择
后端重启后播放失效返回页面重新建立匹配与播放会话

当前对接的目标是让 Share 获得现成媒体库的播放能力。媒体扫描、刮削、账号管理、转码配置和备份,仍在 Jellyfin 自己的管理范围内。

对应实现

  • quartz-server/internal/httpapi/jellyfin.go:本站媒体 HTTP 入口。
  • quartz-server/internal/jellyfin/access.go:文件权限、路径映射、凭据和账号选择。
  • quartz-server/internal/jellyfin/service.go:媒体匹配、播放协商、会话建立与清理。
  • quartz-server/internal/jellyfin/catalog.go、listing.go、collections.go:媒体列表、详情和合集。
  • quartz-server/internal/jellyfin/resources.go、hls.go、subtitles.go:媒体资源、HLS 和字幕处理。
  • quartz-server/internal/jellyfin/danmaku.go:弹幕服务适配。
  • quartz/components/scripts/drivePreview.ts:Share 文件预览与播放器交互。

效果截图





星轨图