网站接入文档

一、这是什么

VDVD 影音是一款 Windows 桌面播放器（Win10 / Win11）。拿它当访客的播放端，你有两条路：

两条路可以同时存在，互不冲突。

对访客的好处（两种方式一致）：

• 走桌面播放器的硬解与网络栈，比浏览器里播更稳、更省电；
• 自动注入 Referer / User-Agent，防盗链源在浏览器里播不了、在这里能播；
• 弹幕、播放进度记忆。

对你的好处：不换播放器、不改后端。播放地址还是你站自己给的地址。

二、唤起式接入：vdvd://

访客在自己浏览器里浏览你的站点，点一下播放按钮 → 本机 VDVD 影音弹出来播放。 你不需要访客先打开播放器，也不需要知道访客装没装（怎么兜底见 2.4）。

2.1 链接长什么样

vdvd://play?url=<媒体地址>&title=<片名>&referer=<本页地址>&back=<返回地址>

所有参数值都要 encodeURIComponent（空格必须编成 %20，播放器不把 + 当空格）。

2.2 最小示例

<a href="vdvd://play?url=https%3A%2F%2Fcdn.example.com%2Fa%2Findex.m3u8&amp;title=%E7%89%87%E5%90%8D%20%E7%AC%AC1%E9%9B%86">用 VDVD 播放器播放</a>

用 JS 拼更省事：

function vdvdUrl(playUrl, title) {
  var q = 'url=' + encodeURIComponent(playUrl)
        + '&title=' + encodeURIComponent(title || document.title)
        + '&referer=' + encodeURIComponent(location.href)
        + '&back=' + encodeURIComponent(location.href);
  return 'vdvd://play?' + q;
}

document.querySelector('#play-btn').addEventListener('click', function () {
  location.href = vdvdUrl('https://cdn.example.com/a/index.m3u8', '片名 第 1 集');
});

2.3 参数

2.4 访客没装播放器怎么办（必看）

通用做法是「先唤起、再兜底跳下载页」：

function launchVdvd(uri, downloadUrl) {
  var left = false;
  // 唤起成功的话浏览器会失焦（播放器抢到前台）
  window.addEventListener('blur', function () { left = true; }, { once: true });

  var timer = setTimeout(function () {
    if (!left && !document.hidden) {
      location.href = downloadUrl;   // 没唤起成功 → 当作未安装，去下载页
    }
  }, 1500);

  location.href = uri;
}

• 这只是经验判断（失焦 ≈ 唤起成功），不是精确探测。弹窗确认框会占用这段时间，所以延迟别设太短；
• 下载页建议带上说明，告诉访客装完再回来点一次。

2.5 播放器收到唤起后做什么

1. 已经开着播放器 → 把这次播放转交给那一个窗口（不会多开一个），并把它还原到前台；
2. 没开着 → 启动播放器，直接进播放界面；
3. 登记为当前播放源，补上 Referer / User-Agent；
4. 有 back 就显示「返回网站」，点击回到你给的那个地址。

2.6 其他用法

• vdvd://open —— 只把播放器调出来（不播放）。适合「打开我的播放器」这类入口；
• play 后面漏了 url 时，等同于 open，不会报错。

如果你想知道访客是否在播放器内（而不是唤起），用第三节的 isEmbedded。

三、桥接式接入：window.VDVDPlayer

访客在 VDVD 影音内置浏览器里浏览你的站点时（例如从导航站跳进来）， 播放器会向页面注入全局对象 window.VDVDPlayer。站点可以用它把播放交给本机播放器。

3.1 方式 A：MacCMS 站点 —— 什么都不用做

播放页存在全局 window.VOD 的站点（MacCMS 一类），只要访客在播放器里打开播放页， 播放器会自动接管：取第一条线路第一集开播，并把全部线路 / 集数搬进「选集」面板。

自动接管需要同时满足：

时间点：等 document.readyState === 'complete' 后开始尝试（每 500ms 检查一次，最多 30 秒）， 避开站点的二次跳转与异步渲染。

3.2 方式 B：显式调用（任何站点）

<script>
  document.querySelector('#play-btn').addEventListener('click', function () {
    // 不在播放器内（比如普通浏览器）→ 什么都不做，走你自己的播放器 / 唤起式链接
    if (!window.VDVDPlayer || !window.VDVDPlayer.isEmbedded) return;

    window.VDVDPlayer.play('https://cdn.example.com/vod/a/index.m3u8', '片名 第 1 集');
  });
</script>

四、接口一览

window.VDVDPlayer = {
  version:    '1.1',     // string，接口版本
  isEmbedded: true,      // boolean，是否运行在 VDVD 影音内
  play:       function (url, title, options) { /* → boolean */ },
  openLibrary:function () { }
};

脚本在文档创建时注入，页面自己的 JS 可以直接用，不需要等 DOMContentLoaded。

五、play(url, title, options)

参数

options 字段：

返回值

六、剧集清单（选集）格式

window.VDVDPlayer.play(url, '片名', {
  playlist: [
    {
      name: '线路一',
      episodes: [
        { name: '第 1 集', url: 'https://cdn.example.com/1/index.m3u8' },
        { name: '第 2 集', url: 'https://cdn.example.com/2/index.m3u8' }
      ]
    },
    {
      name: '线路二',
      episodes: [
        { name: '第 1 集', url: 'https://cdn2.example.com/1/index.m3u8' }
      ]
    }
  ]
});

规则：

• 顶层是线路数组，每条线路含 name + episodes；
• 集对象只需要 name 与 url；url 为空的集会被忽略，整条线路没有有效集则整条丢弃；
• 一条也没有时清单视为空，只播你传的 url，不显示选集。

不传 playlist 时，播放器按下面规则自动读当前页面的 window.VOD：

七、openLibrary()

window.VDVDPlayer.openLibrary();

回到播放器自带的界面（资源库 / 搜索），同样带「返回网站」。无参数、无返回值。

播放器还会在你站点的页面上自动放一个小小的「播放器」悬浮按钮（右下角，id="__vdvd_entry"）， 点击等于调用 openLibrary()。

八、推荐写法：两种方式 + 优雅降级

function playVideo(mediaUrl, title, playlist) {
  var p = window.VDVDPlayer;

  // ① 正在播放器内置浏览器里浏览本站 → 直接交给桥接 API（可带选集）
  if (p && p.isEmbedded) {
    p.play(mediaUrl, title, playlist ? { playlist: playlist } : undefined);
    return;
  }

  // ② 在普通浏览器里 → 唤起式（装了就弹播放器，没装就跳下载页）
  launchVdvd(vdvdUrl(mediaUrl, title), 'https://pc.vdvd.net/');
}

要点：

• 判断用 isEmbedded，不要用 typeof window.VDVDPlayer !== 'undefined'——普通 Chrome 里未来可能出现同名对象，isEmbedded 才是准确信号；
• 手动调用与自动接管只会生效一次：显式调过 play() 后，自动接管不会再插一脚。

九、常见问题

十、版本与兼容

约定：只增不改、不删字段。新增能力会体现在 version 上，老代码不用跟着改。

排查问题第一步：console.log(window.VDVDPlayer.version)。

十一、边界与合规

• 唤起式只在 Windows 10 / 11 上有效；桥接式只在 VDVD 影音内置浏览器里有效；
• 播放器不代理、不存储、不分发视频内容，串流全程从你的地址直连访客设备；Referer 仅用于适配你站点的防盗链；
• 播放地址由站点提供，内容合法性由站点自行负责；
• 站点页面上的「播放器」悬浮按钮与「返回网站」是播放器提供的通用体验，不影响页面其他功能。