使用场景
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 取得播放信息。
当前播放匹配依赖本地存储的路径映射和精确文件路径,不是拿文件名去搜索影片。
文件存在但没有匹配到时,优先检查:
- 分享是否启用了 Jellyfin。
- OpenList 挂载驱动是否为当前适配的
Local。 - 解析后的路径是否和 Jellyfin 数据库里的
Path一致。 - 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 文件预览与播放器交互。
效果截图




