OopsPlayer URL Scheme 使用指南｜iOS 播放与 Emby 导入

基本规则

Scheme 名称大小写不敏感，建议统一使用小写的 oopsplayer://。
查询参数值必须经过 URL 编码，尤其是嵌套 URL、中文、空格、&、? 和 #。同名参数请只传一次。
媒体地址支持 http、https、rtmp、rtsp、rtp、udp、mms；实际能否播放取决于媒体格式和网络环境。
示例域名只是占位符。网页唤起 Scheme 时，浏览器可能要求用户确认打开 App。

播放网络媒体

推荐使用 x-callback-url 路由。只有 url 为必填项。

oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv

参数	必填	说明
`url`	是	媒体 URL。需完整编码为一个查询参数值。
`name`	否	播放器中显示的名称，也用于扩展名识别。旧参数 `title` 仍可使用；两者同时存在时优先使用 `name`。
`position`	否	起播位置，单位秒，非负整数；省略时从 0 秒开始。
`sub`	否	HTTP 或 HTTPS 外挂字幕 URL；播放器会尝试自动选中。
`User-Agent`	否	请求媒体地址时使用的 User-Agent。参数名大小写必须一致。
`x-success`	否	用户关闭播放器后打开的调用方 Scheme 地址，详见下节。

带字幕、起播时间与 User-Agent

oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&name=Movie.mkv&position=915&sub=https%3A%2F%2Fmedia.example.com%2Fsubtitle.ass&User-Agent=MyApp

关闭播放器后返回调用方

传入 x-success 后，用户关闭播放器时，OopsPlayer 会在该地址的现有查询参数后追加 lastPlayedUrl 和 position。其中 position 为关闭时的非负整数秒数。调用方需自行注册接收回调的 Scheme。

oopsplayer://x-callback-url/play?url=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&x-success=myapp%3A%2F%2Fplayback-done%3Fsource%3Doops

回调示意：

myapp://playback-done?source=oops&lastPlayedUrl=https%3A%2F%2Fmedia.example.com%2Fmovie.mkv&position=120

只有实际进入播放器并由用户关闭时才发送此回调。x-success 必须是调用方自定义 Scheme；不接受 HTTP、HTTPS、file 或 OopsPlayer 自身 Scheme。

导入 Emby 服务器

打开链接后，OopsPlayer 会展示配置预览；用户确认后才保存服务器。密码由现有 Keychain 机制存储，导入的服务器默认只保存在本机。

oopsplayer://importserver?type=emby&address=https%3A%2F%2Femby.example.com%3A443%2Femby&name=Home%20Emby&username=alice&password=example

参数	必填	说明
`type`	是	目前仅支持 `emby`。
`address`	是	完整 HTTP 或 HTTPS 地址，可包含端口与基础路径。
`username`	是	Emby 登录用户名。
`password`	否	登录密码。也可导入后在 App 内补充。
`name`	否	服务器显示名称；省略时使用主机名。
`addressNname` + `addressN`	否	成对提供备用线路名称及 HTTP(S) 地址，N 为 1 至 20。例如 `address1name` 与 `address1`。

包含备用线路的示例

oopsplayer://importserver?type=emby&address=https%3A%2F%2Femby.example.com&username=alice&address1name=Backup&address1=https%3A%2F%2Fbackup.example.com

含密码的链接可能出现在浏览器历史、剪贴板或调用方日志中。请只通过可信渠道传递，尽量在 App 内输入密码。导入仍受 OopsPlayer 当前服务器数量限制；同地址的 Emby 服务器不会重复添加。