Provider 使用手册
SyncTV 的 Provider 把外部平台、媒体服务器和 NAS 资源转换成可播放媒体。App 会消费 Provider 返回的 typed source config、封面、缩略图、字幕、弹幕、清晰度和代理地址。
- 在 App 的账号中心打开 平台绑定，选择 Provider 和 Provider instance。
- 按 Provider 要求登录、扫码或填写 Cookie、token、API key。
- 进入房间媒体库，打开添加媒体，选择对应 Provider。
- 输入 URL、资源 ID，或使用 Provider 的分类、搜索、收藏、历史、目录浏览入口。
- 先预览资源。列表项会携带可直接添加的 typed media 或 playlist source config。
- 添加单个媒体、选择部分预览结果，或创建动态播放列表。
- 播放时从 Provider 返回的 mode 中选择清晰度、直连或 proxy mode。
Provider instance 表示资源解析发生的位置。默认 instance 在 SyncTV 主进程内运行；管理员也可以配置远程 instance。绑定凭据、媒体来源和播放请求始终保留 instance 归属。
使用房主凭据 会把来源绑定到房间所有者的 Provider 凭据。个人收藏、历史、关注列表和私有媒体库适合使用该选项。关闭时，浏览和播放使用当前用户的凭据。
| Provider | 绑定方式 | 单媒体 | 动态播放列表与浏览 | 播放增强 |
|---|---|---|---|---|
| Bilibili | 二维码或短信 | 视频、多 P、番剧单集、直播 | 热门、推荐、UP、收藏夹、合集、系列、稍后观看、历史、追番、番剧时间表与索引、直播首页/关注/分区 | DASH、清晰度、字幕、弹幕、封面、分 P 缩略图 |
| Twitch | OAuth access token；Followed Live 需要 user:read:follows | 直播、VOD、Clip | 频道 Videos/Highlights/Uploads/Clips、关注直播、分类直播、直播搜索 | HLS 清晰度、章节、Storyboard、聊天、频道排期 |
| YouTube | 公开资源可匿名；可绑定 Visitor Data、PO Token、Cookie | 视频、Shorts、直播 | 播放列表、频道 Videos/Shorts/Live、搜索、热门、订阅、喜欢、稍后观看 | 原生/自适应格式、字幕、Storyboard、封面 |
| 抖音 | 可绑定 Cookie | 视频、直播 | 用户作品 | 多码率、封面、直播聊天 |
| TikTok | 可绑定 Cookie | 视频、直播 | 用户作品 | 多格式、字幕、封面、图集音频 |
| 虎牙 | 公开解析 | 直播、视频 | URL/房间入口 | HLS/FLV、CDN、清晰度、直播聊天 |
| 斗鱼 | 公开解析 | 直播 | 房间号、别名或 URL | HLS/FLV、CDN、清晰度、编码、直播聊天 |
| AcFun | 公开解析 | 视频、番剧、直播 | URL/资源 ID | 清晰度、标签、点播/直播弹幕、封面 |
| CCTV | 公开解析 | 栏目页、节目页和可识别资源 | URL/资源 ID | HLS/MP4、章节、元数据、封面 |
| Emby/Jellyfin | 服务器地址、用户名和密码或 API key | 影片、剧集、视频 | 继续观看、Next Up、最近添加、收藏影片、收藏演员及作品、播放列表、合集、分类 | 原始流、服务端转码、字幕、封面、播放进度回写 |
| Alist | 地址、用户名、密码，可带 OTP | 文件 | 目录、搜索 | 缩略图、字幕、原始流/转码、Range |
| Cloudreve | 地址、邮箱和密码 | 文件 | 目录、搜索，自动适配 page/cursor 分页 | 签名播放 URL、封面/缩略图、Range |
| FNOS | 主端点、用户名、密码，可带 2FA；可发现 WebDAV 和影视端点 | 文件、影视库条目 | 文件目录、影视库、收藏、历史 | 文件级预览、影视海报、原生转码、收藏/已看状态、播放进度 |
| QNAP QTS / QuTS hero | 地址、用户名和密码 | 文件 | File Station 目录与搜索 | 缩略图、预转码清晰度、实时转码能力探测、Range |
| Synology DSM | 地址、用户名、密码，可带 OTP | File Station 文件、Video Station 条目 | 文件、电影、剧集、家庭视频、电视录像 | 缩略图、海报、字幕/音轨、remux、播放进度 |
| Nextcloud | 地址、用户名和应用密码，或 Login Flow | 文件 | 文件夹、收藏、搜索 | Preview API、BlurHash、尺寸和时长元数据、Range |
| Seafile | 地址、用户名和密码；加密资料库另行解锁 | 文件 | 资料库目录、星标、搜索 | 缩略图、下载链接、加密资料库浏览、Range |
| TrueNAS | 地址和 API key | 文件 | /mnt 范围内目录与搜索 | 文件元数据、ACL/ZFS 属性、Range |
| Direct URL | 无 | HTTP(S) 文件、HLS 等 | 固定来源 | 自定义 header、Range、HLS segment proxy |
| RTMP / Live Proxy | 房间权限或管理员配置 | 推流、外部 RTMP/HTTP-FLV | 直播来源 | SyncTV HLS/FLV、生命周期管理 |
Bilibili
Section titled “Bilibili”绑定后可以访问收藏、稍后观看、历史、关注直播和追番等账号数据。公开视频、番剧和直播也可以匿名解析。
App 提供两种添加路径：
- URL 解析：输入视频、番剧季度/单集、直播间、UP 空间、收藏夹、合集、系列或直播分区 URL。后端返回多个 typed candidate；多 P 视频可以选择部分分 P，也可以创建完整动态播放列表。
- 资源发现：直接选择热门、推荐、UP 视频、收藏夹、历史、追番、直播首页、关注直播、直播分区、番剧时间表或番剧索引。
番剧时间表支持番剧、影视和国创，时间范围为前后 0 到 7 天。预览同时展示已发布、待播和延期条目；已发布条目携带真实 episode ID 与 CID。番剧索引支持类别、排序、升降序、连载状态、地区、年份和风格筛选，选择季度后可以继续预览完整剧集列表。
动态播放列表保留上游分页语义。历史使用 Bilibili 原生 cursor，热门、UP、收藏、季度和索引使用各自的 page/cursor 规则。顺序、单曲循环、列表循环和随机播放均由 Core 根据 typed target 推进。
Twitch
Section titled “Twitch”绑定时填写 OAuth access token。SyncTV 会保存 Twitch 用户 ID、client ID 和 scopes。关注直播入口需要 user:read:follows scope；App 会根据当前 instance 的绑定能力控制入口。
媒体 URL 支持直播频道、VOD 和 Clip。频道动态播放列表可以选择 Videos、Highlights、Uploads 或 Clips。发现入口包括关注直播、Top Categories、分类直播、直播频道搜索和 Broadcaster Schedule。
YouTube
Section titled “YouTube”公开视频可以直接解析。绑定 Visitor Data 或 PO Token 可以提高受限请求的成功率；订阅、喜欢和稍后观看需要 Cookie。Cookie 只在服务端凭据存储和上游请求中使用。
视频输入支持 ID、watch、youtu.be、shorts 和 live URL。播放列表支持 URL 或 ID。频道支持 UC... ID 和 /channel/UC... URL，并可以分别创建 Videos、Shorts、Live 动态播放列表。
预览列表支持多选添加，也可以把整个来源保存为动态播放列表。个人 feed 会根据当前 Provider instance 的 Cookie 能力启用；房主共享凭据模式使用房主绑定。
抖音与 TikTok
Section titled “抖音与 TikTok”两者都有独立的数据模型和解析流程。输入视频或直播 URL 可以预览平台元数据和播放变体；输入用户主页可以解析稳定用户标识并创建用户作品动态播放列表。Cookie 绑定适用于需要登录态或地区/风控上下文的请求。
虎牙、斗鱼、AcFun 与 CCTV
Section titled “虎牙、斗鱼、AcFun 与 CCTV”这些 Provider 以公开解析为主：
- 虎牙支持直播间和视频，预览清晰度、CDN、HLS/FLV 和聊天能力。
- 斗鱼支持数字房间号、别名和 URL，预览编码、清晰度与 CDN。
- AcFun 支持视频、番剧和直播，点播与直播弹幕使用各自协议。
- CCTV 支持已知栏目、节目和嵌入页，预览原生流、章节和元数据。
媒体服务器与文件服务
Section titled “媒体服务器与文件服务”Emby 和 Jellyfin
Section titled “Emby 和 Jellyfin”两者共用 emby Provider。绑定时填写服务器根地址、目标用户名和密码，或使用 API key。上游用户权限决定可浏览的媒体库、转码和字幕能力。
动态来源包括继续观看、Next Up、最近添加、收藏影片、收藏演员、演员作品、服务端播放列表、合集、分类和分类作品。预览中的文件夹项携带 typed playlist source config，可以继续进入演员、分类或播放列表内容。
播放开始、进度、暂停和停止会回写上游。SyncTV 会根据客户端播放能力请求 Emby/Jellyfin playback info，并同时暴露可用的直连和转码 mode。播放协商会话按房间隔离；停止、租约回收和服务关闭都会终止该房间的 active encoding。
Alist 与 Cloudreve
Section titled “Alist 与 Cloudreve”Alist 支持目录、搜索、缩略图、字幕、原始流和上游转码。目录密码作为来源配置的一部分保存，账号密码保存在加密凭据中。
Cloudreve 支持目录、搜索、签名播放 URL 和缩略图。服务器返回 page 分页时 App 使用页码；服务器返回 cursor 时动态播放列表使用 opaque cursor。响应中的分页 oneof 是当前服务器分页方式的事实来源。
NAS 与私有云
Section titled “NAS 与私有云”FNOS 登录支持主端点、可选 WebDAV/影视端点、2FA 和信任设备。登录发现结果会标记影视服务能力。
App 提供 文件 与 影视库 两套入口。文件入口使用文件级缩略图和下载/Range；影视入口使用影视海报、媒体元数据、收藏、历史、已看状态、播放进度和原生转码。创建来源时会分别保存 File 或 LibraryItem typed source。原生转码会话在规格切换、播放停止、租约回收和服务关闭时发送 media.quit，瞬时失败由后台回收器继续重试。
QNAP 使用 File Station API 浏览和搜索。能力探测会返回设备声明的实时转码、硬件转码、QTranscode、Multimedia Codec 和 HD Station 支持，这些字段用于绑定诊断。播放模式提供原始文件和已经完成的预转码文件；文件项会列出可用的预转码高度。
Synology
Section titled “Synology”Synology 登录支持 OTP。File Station 用于普通文件；Video Station 用于电影、电视剧、分集、家庭视频和电视录像。Video Station 条目携带海报、音轨、字幕和可播放文件标识，播放进度会回写 DSM。SyncTV 会跟踪 Video Station 返回的 stream_id，并在播放停止、租约回收和服务关闭时调用 DSM close。
Nextcloud
Section titled “Nextcloud”推荐使用应用密码或官方 Login Flow。目录项会保留 file ID、ETag、MIME、所有者、收藏、Preview 能力、BlurHash、尺寸和时长。App 的封面使用 Nextcloud Preview API，经 SyncTV 签名路由访问。
Seafile
Section titled “Seafile”登录后先选择资料库。加密资料库会提示输入资料库密码并执行 unlock。动态来源支持目录、星标和资料库内搜索；文件条目保留 object ID 和 thumbnail 能力。
TrueNAS
Section titled “TrueNAS”使用 API key 登录。浏览范围限制在存储挂载点 /mnt 下。目录和搜索结果会保留真实路径、mount ID、权限、ACL、扩展属性和 ZFS 属性。
Page 与 Cursor
Section titled “Page 与 Cursor”动态列表响应使用明确的分页 oneof：
page适合可按页码随机访问的上游。cursor适合 Cloudreve、Bilibili 历史、Twitch、YouTube 等上游原生 continuation。
App 在响应声明 page 时发送下一页页码，在响应声明 cursor 时回传 next_cursor。Cursor 是 opaque value，客户端只负责保存和回传。
顺序自动播放会继续扫描后续页，直到找到当前 target 和下一条可播放媒体。随机播放使用受控采样上限，避免对大型目录产生无限请求。
每条凭据同时绑定用户、Provider、server ID 和 Provider instance。同一个上游主机可以在多个 instance 中分别绑定。删除绑定前，应先迁移引用该绑定的媒体和动态播放列表。
- 确认 App 选择的 Provider instance 与绑定记录一致。
- 在平台绑定页刷新账号状态和 scopes/capabilities。
- 重新执行预览，确认错误发生在列表、解析、播放信息或 proxy 请求阶段。
- 检查 source config 中的 server ID、资源 ID、分页方式和共享凭据选项。
- 对直连失败的带 header、DASH 或 HLS 来源选择
proxy_*mode。 - 查看 Provider 配置、播放与代理 和 用户排障。