Title: 为您的视频播放器添加投屏功能，且不破坏原有功能

从浏览器向电视投屏视频看起来很简单，但大多数自定义 HTML5 播放器在尝试此操作时都会失效。最近的一份开发者指南列出了四个隐藏的故障点——令牌过期、CORS 拦截、无法访问的主机以及 MSE-blob 陷阱——并详细展示了如何避开每一个问题。

为什么投屏会让自定义播放器出错

当您点击 Cast 时，电视 并不会 运行您的 JavaScript 播放器。它会获取您传递给它的流 URL，并使用其自身的固件播放媒体。覆盖层、分析数据上报和自适应比特率逻辑仍留在浏览器中。如果电视无法在相同条件下获取相同的 URL，播放就会停止，且通常在控制台中不会显示任何明显的错误。

四个常见的罪魁祸首

  • Token expiry（令牌过期） – 短效安全令牌在浏览器中可以正常工作，但电视可能会持续播放该流长达 90 分钟。当令牌过期时，视频就会停止。请为投屏会话签发有效期更长的令牌。
  • CORS errors（CORS 错误） – CORS 决定了哪些域名可以请求资源。电视被视为一个独立的源（origin），因此如果您的视频服务器仅将页面域名列入白名单，那么即使相同的 URL 在浏览器中可以工作，电视的请求也会被拦截。
  • Unreachable hosts（无法访问的主机） – 开发环境通常使用 localhost、内部主机名或私有 IP 范围。电视位于不同的网络段，无法解析或路由到这些地址，从而导致静默失败。
  • The MSE trap（MSE 陷阱） – Media Source Extensions (MSE) 允许浏览器即时拼接数据块，通常会将视频暴露为 blob: URL。像 hls.js 这样的库会为自适应流生成此类 blob。电视无法获取 blob；它们需要实际的清单（例如 .m3u8 或 .mpd）URL。在调用投屏对话框之前，请将源切换为真实的清单 URL。

分步检查清单

  1. 检测投屏支持 – 使用 Chrome 的 Remote Playback API 或 Safari 的 WebKit 事件。这可以告诉您浏览器是否具备移交播放权限的能力。
  2. 监控连接状态 – 不要假设点击按钮就能保证连接稳定。请订阅 Remote Playback 对象中的 connecting、connected 和 disconnect 事件。将电视视为“事实来源”（source of truth）；仅在收到 connected 事件后才更新 UI。
  3. 切换到长效的直接 URL – 在调用 remotePlayback.prompt() 之前，将 video 元素的 src 替换为电视可以获取的清单 URL。保留原始的基于 blob 的源用于本地播放，但仅在投屏会话期间进行切换。
  4. 使用极简测试进行验证 – 创建一个简单的 HTML 页面，仅包含一个指向清单 URL 的 <video> 标签，不使用任何 JavaScript，并让其运行一小时。如果视频停止了，那么底层的流在电视上也会失败。在添加投屏按钮之前，请先修复令牌有效期、CORS 标头或主机可访问性问题。

开发者可以获得什么

在不破坏播放器其他功能的前提下，添加一个可靠的投屏按钮。

总结

对于自定义视频播放器来说，投屏并不是一个“即插即用”的功能；它会将播放权移交给一个完全不同的环境。通过提供长效且符合 CORS 要求的 URL、避免使用 blob 引用并监听电视的连接事件，您可以添加一个运行可靠的投屏按钮，而不是让整个播放器崩溃。