视频直播
视频直播
- Documentation
视频直播Web SDKWeb 拉流 SDK功能集成自动播放
Copy page
Download PDFCopy pageDownload PDF本文介绍如何通过 Web 拉流 SDK（VePlayer）实现页面加载后的视频自动播放，涵盖常见浏览器和 WebView 环境的适配策略、配置方法及失败应对方式，帮助您在多平台上更稳定地实现自动播放体验。
适用版本
本文档适用于最新版本的 Web 拉流 SDK，版本信息请参考发布历史，历史版本请参考历史文档。
功能介绍
自动播放是指视频在页面加载完成后无需用户操作即可开始播放。受浏览器自动播放策略限制，是否允许自动播放取决于当前环境，常见条件包括静音播放、用户交互等。
tip
由于浏览器策略的限制，自动播放功能可能在部分设备和浏览器上受阻。在设计您的应用时，请充分考虑用户体验，避免强制性的自动播放行为。
前提条件
已完成 SDK 集成。
配置自动播放
VePlayer 通过 autoplay 配置项支持自动播放，详细配置说明请参考播放器配置。自动播放能否成功取决于运行环境是否满足相应的策略要求。
浏览器环境
在标准的 Web 浏览器中，自动播放至少需要满足以下任一条件：
| 条件类别 | 描述 |
|---|---|
| 静音播放 | 视频的音频被设置为静音（muted: true）或音量为 0。这是最常见的实现自动播放的方式。 |
| 用户交互 | 用户点击页面、滑动屏幕、按下键盘等操作后，页面可自动播放媒体内容。 |
| 站点白名单 | 浏览器会根据用户的历史浏览行为，评估网站的媒体播放体验。如果用户经常与某个网站的视频内容互动，浏览器可能会将该网站加入允许自动播放的白名单。 |
| 用户设置 | 部分浏览器允许用户手动开启或关闭某站点的自动播放权限。 |
| 权限委派 | 若视频嵌入在 <iframe> 中，且顶层页面已有自动播放权限，则可向 iframe 委派此权限。 |
tip
想了解更多信息，请参见 Google Chrome 和 WebKit 的自动播放策略。
WebView 环境
在 WebView 这种嵌入式浏览器环境中，自动播放需要额外的配置。
Android WebView
默认禁止有声音的自动播放。推荐使用静音自动播放的 VePlayer 配置，代码示例如下：
VePlayer.createLivePlayer({ autoplay: { muted: true } }).then(function(veplayer) { // 播放器实例 });
若要允许非静音自动播放（需谨慎评估用户体验），需在 WebView 中设置 setMediaPlaybackRequiresUserGesture 为 false，示例代码如下：
myWebView.getSettings().setMediaPlaybackRequiresUserGesture(false);
iOS WebView
iOS WebView 默认会阻止带音频的视频自动播放。推荐使用静音自动播放的 VePlayer 配置，代码示例如下：
VePlayer.createLivePlayer({ autoplay: { muted: true } }).then(function(veplayer) { // 播放器实例 });
若要允许非静音自动播放（需谨慎评估用户体验），需在 WebView 中设置 mediaTypesRequiringUserActionForPlayback 为 NO，示例代码如下：
[self.webView mediaTypesRequiringUserActionForPlayback:NO];
warning
在 iOS 设备处于低电模式时，系统可能会阻止视频自动播放。
微信内置浏览器环境
微信内置的 WebView 环境（即在微信中打开 H5 页面）对自动播放存在较强限制。
Android 微信内置 WebView
根据微信官方说明，安卓微信 WebView 禁止通过任何方式自动播放 m3u8 和 FLV 视频，即使设置了 muted: true，安卓微信环境下也无法自动播放 m3u8 和 FLV 视频。
因此，建议不要依赖自动播放功能，应在用户明确点击后再触发播放。
iOS 端微信内置 WebView
iOS 微信环境中可尝试使用 autoplay: { muted: true } 配置实现静音自动播放，但行为仍可能因微信版本和系统设置有所差异。以下为常用示例：
<!DOCTYPE html> <html lang="zh"> <head> <title>火山引擎VePlayer</title> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" /> <link rel="stylesheet" href="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.8.1/umd/veplayer.production.css"> <script src="https://lf-unpkg.volccdn.com/obj/vcloudfe/sdk/@volcengine/veplayer/2.8.1/umd/veplayer.production.js"></script> <script src="https://res.wx.qq.com/open/js/jweixin-1.0.0.js"></script> </head> <body> <div id="veplayer"></div> <script> VePlayer.createLivePlayer({ width: '100%', height: 360, // 或者 rtm 地址 url: 'https://pull-demo.volcfcdnrd.com/live/st-4536521_hd.m3u8', }).then(function(veplayer){ veplayer.on(VePlayer.live.Events.COMPLETE, function() { wx.config({ // 配置信息, 即使不正确也能使用 wx.ready debug: false, appId: '', timestamp: 1, nonceStr: '', signature: '', jsApiList: [] }); wx.ready(function() { console.log('ready'); var video= document.querySelector('video'); console.log('video ===>', video); video && video.play() }); }) }) </script> </body> </html>
判断自动播放是否成功
由于浏览器策略的复杂性，您需要通过以下方式判断自动播放是否成功。
方法一：监听 play() 方法的 Promise 返回
调用 veplayer.play() 会返回一个 Promise。
Resolved Promise：表示播放已成功开始。Rejected Promise (NotAllowedError)：表示自动播放被浏览器策略阻止。
示例代码如下：
let startPlayPromise = veplayer.play(); if (startPlayPromise !== undefined) { startPlayPromise .catch(error => { if (error.name === "NotAllowedError") { // 自动播放失败，浏览器策略阻止了播放 // 例如可以在此处静音后重试，或提示用户手动点击播放 } else { // 播放过程中发生了其他错误 } }) .then(() => { // 播放已成功开始，可在此处继续执行后续操作 }); }
方法二：监听 AUTOPLAY_PREVENTED 事件
VePlayer SDK 在自动播放被阻止时会触发 AUTOPLAY_PREVENTED 事件，示例代码如下：
VePlayer.createLivePlayer({ autoplay: { muted: false } }).then(function (veplayer) { // 监听自动播放被阻止的事件 veplayer.on(VePlayer.live.Events.AUTOPLAY_PREVENTED, () => { console.log('自动播放被浏览器阻止'); // 在此处添加备用处理逻辑，例如提示用户点击播放按钮 }); });
