微信小程序实时音视频功能简析(live-pusher与live-player)

使用须知

2017年下半年，微信6.5.21版本支持在线音视频功能。开发者可以通过两个音视频组件 和 实现实时地在线直播、视频通话、语音通话等功能。

上述功能需要用到两个小程序媒体组件中的两个： live-pusher 与 live-player 。下文简单介绍两这个组件的基础知识。仅可以带你入门，如果是高手请绕行。

注册小程序

注册小程序请单击 微信公众平台 ，完成注册后，在小程序管理页面的【开发】>【基本配置】中记录下小程序 AppID 供后面使用。

注意： 必须以非个人主体类型进行注册，否则无法开通 和 这两个标签。

开通标签使用权限

live-pusher 和 live-player 是小程序内部用于支持音视频上行能力的功能标签

出于政策和合规的考虑，微信暂时没有放开所有小程序对 live-pusher 和 live-player 标签的支持：

• 目前支持这两个标签的类目如下表格所示（只有非个人主体才有以下类目）：

主类目	子类目	小程序内容场景
社交	直播	涉及娱乐性质，如明星直播、生活趣事直播、宠物直播等。选择该类目后首次提交代码审核，需经当地互联网主管机关审核确认，预计审核时长7天左右
教育	在线视频课程	网课、在线培训、讲座等教育类直播
医疗	互联网医院，公立医院	问诊、大型健康讲座等直播
金融	银行、信托、基金、证券/期货、证券、期货投资咨询、保险、征信业务、新三板信息服务平台、股票信息服务平台（港股/美股）、消费金融	金融产品视频客服理赔、金融产品推广直播等
汽车	汽车预售服务	汽车预售、推广直播
政府主体帐号	-	政府相关工作推广直播、领导讲话直播等
工具	视频客服	不涉及以上几类内容的一对一视频客服服务，如企业售后一对一视频服务等

• 符合类目要求的小程序，需要在小程序管理后台的【开发】>【接口设置】中自助开通推拉流标签的使用权限

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Vni239TU-1586502758626)(/Users/mxj/百度云同步盘/学习笔记/前端全栈/微信小程序/img/image-20200409073506475.png)]

说明：如果以上设置都正确，但小程序依然不能正常工作，可能是微信内部的缓存没更新，请删除小程序并重启微信后，再进行尝试。

live-player

live-player是小程序内部用于支持音视频下行（播放）能力的功能标签。

版本支持

• 微信 App iOS 最低版本要求：6.5.21 。
• 微信 App Android 最低版本要求：6.5.19。
• 小程序基础库最低版本要求：1.7.0。

可以通过 wx.getSystemInfo 可以获取当前基础库版本信息。

属性定义

属性名	类型	默认值	说明
src	String	-	用于音视频下行的播放 URL，支持 RTMP、FLV 等协议
mode	String	live	模式。live（直播），RTC（实时通话，该模式时延更低）
autoplay	Boolean	false	是否自动播放
muted	Boolean	false	是否静音
orientation	String	vertical	vertical（垂直），horizontal（水平）
object-fit	String	contain	填充模式，可选值有 contain（图像长边填满屏幕，短边区域会被填充⿊⾊），fillCrop（图像铺满屏幕，超出显示区域的部分将被截掉）
background-mute	Boolean	false	当微信切到后台时，是否关闭播放声音
min-cache	Number	1	最小缓冲延迟， 单位：秒
max-cache	Number	3	最大缓冲延迟， 单位：秒
sound-mode	String	speaker	声音输出方式。speaker（扬声器），ear(听筒)
auto-pause-if-navigate	Boolean	true	当跳转到本小程序的其他页面时，是否自动暂停本页面的实时音视频播放
auto-pause-if-open-native	Boolean	true	当跳转到其它微信原生页面时，是否自动暂停本页面的实时音视频播放
picture-in-picture-mode	string/Array	-	设置小窗模式： push, pop 或通过数组形式设置多种模式（如： [“push”, “pop”]）（不常用）
bindstatechange	EventHandler	-	用于指定一个 javascript 函数来接受播放器事件.detail = {code}
bindfullscreenchange	EventHandler	-	用于指定一个 javascript 函数来接受全屏变化事件，detail = {direction, fullScreen}
bindnetstatus	EventHandler	-	网络状态通知，detail = {info}
bindaudiovolumenotify	EventHandler	-	播放音量大小通知，detail = {}（不常用）
debug	Boolean	false	是否开启调试模式

示例代码

<view id='video-box'>  
    <live-player
        wx:for="{{player}}"
        id="player_{{index}}"
        mode="RTC"
        object-fit="fillCrop"
        src="{{item.playUrl}}" 
        autoplay='true'
        bindstatechange="onPlay">
   </live-player>
 </view> 

超低时延

的 RTC 模式支持500ms以内的超低时延链路，可以应用在视频通话和远程遥控等场景中，要使用超低时延播放，需要注意如下几点：
（1）推流端如果是微信小程序，请使用 的 RTC 模式。
（2）推流端如果是 iOS 或者 Android SDK，请使用 setVideoQuality 的 MAIN_PUBLISHER 模式。
（3）推流端如果是 Windows，请不要使用 OBS，延时太高，可以使用我们的 Windows SDK。
（4） 的 min-cache 和 max-cache 请不要自行设置，使用默认值。
（5）播放地址请使用超低延时播放地址，也就是带了防盗链签名的rtmp://地址，如下：

对比项目	示例	时延
普通直播 URL	rtmp://3891.liveplay.myqcloud.com/live/3891_test_clock_for_rtmpacc	>2s
超低延时 URL	rtmp://3891.liveplay.myqcloud.com/live/3891_test_clock_for_rtmpacc?bizid=bizid&txTime=5FD4431C&txSerect=20e6d865f462dff61ada209d53c71cf9	< 500ms

属性详解

src
用于音视频下行的播放 URL，支持 RTMP 协议（URL 以rtmp://打头）和 FLV 协议（URL 以http://打头且以.flv结尾）

说明：

标签是不支持 HLS（m3u8）协议的，因为 已经支持 HLS（m3u8）播放协议了。但直播观看不推荐使用 HLS（m3u8）协议，延迟要比 RTMP 和 FLV 协议高一个数量级。

mode
live 模式主要用于直播类场景，例如赛事直播、在线教育、远程培训等等。该模式下，小程序内部的模块会优先保证观看体验的流畅，通过调整 min-cache 和 max-cache 属性，您可以调节观众（播放）端所感受到的时间延迟的大小，文档下面会详细介绍这两个参数。

RTC 则主要用于双向视频通话或多人视频通话场景，例如金融开会、在线客服、车险定损、培训会议等等。在此模式下，对 min-cache 和 max-cache 的设置不会起作用，因为小程序内部会自动将延迟控制在一个很低的水平（500ms左右）。

min-cache 和 max-cache

这两个参数分别用于指定观看端的最小缓冲时间和最大缓冲时间。所谓缓冲时间，是指播放器为了缓解网络波动对观看流畅度的影响而引入的一个“蓄水池”，当来自网络的数据包出现卡顿甚至停滞的时候，“蓄水池”里的紧急用水可以让播放器还能坚持一小段时间，只要在这个短暂的时间内网速恢复正常，播放器就可以源源不断地渲染出流畅而平滑的视频画面。

“蓄水池”里的水越多，抗网络波动的能力就越强，但代价就是观众端的延迟就越大，所以要在不同的场景下，使用不同的配置来达到体验上的平衡：

• 码率比较低（1Mbps左右，画面以人物为主）的直播流，min-cache = 1，max-cache = 3 较合适。
• 码率比较高（2Mbps - 3Mbps的高清游戏画面为主）的直播流，min-cache = 3，max-cache = 5 较合适。

RTC 模式下这两个参数是无效的。

background-mute
微信切到后台以后是否继续播放声音，用于避免锁屏对于当前小程序正在播放的视频内容的影响。

debug
调试音视频相关功能，如果没有很好的工具会是一个噩梦，所以小程序为 live-pusher 标签支持了 debug 模式，开始 debug 模式之后，原本用于渲染视频画面的窗口上，会显示一个半透明的 log 窗口，用于展示各项音视频指标和事件，降低您调试相关功能的难度，具体使用方法我们在 FAQ 中有详细说明。

对象操作

wx.createLivePlayerContext()
通过 wx.createLivePlayerContext() 可以将 标签和 javascript 对象关联起来，之后即可操作该对象。

play
开始播放，如果 的 autoplay 属性设置为 false（默认值），那么就可以使用 play 来手动启动播放。

stop
停止播放。

pause
暂停播放，停留在最后画面。

resume
继续播放，与 pause 成对使用。

mute
设置静音。

requestFullScreen
进入全屏幕。

exitFullScreen
退出全屏幕。

代码实例

var player = wx.createLivePlayerContext('pusher');
player.requestFullScreen({
    success: function(){
            console.log('enter full screen mode success!')
        }
        fail: function(){
            console.log('enter full screen mode failed!')
        }
        complete: function(){
            console.log('enter full screen mode complete!')
        }
});

内部事件

通过live-player标签的 bindstatechange 属性可以绑定一个事件处理函数，该函数可以监听推流模块的内部事件和异常通知。

关键事件

code	事件定义	含义说明
2001	PLAY_EVT_CONNECT_SUCC	已经连接到云端服务器
2002	PLAY_EVT_RTMP_STREAM_BEGIN	服务器开始传输音视频数据
2003	PLAY_EVT_RCV_FIRST_I_FRAME	网络接收到首段音视频数据
2004	PLAY_EVT_PLAY_BEGIN	视频播放开始，可以在收到此事件之前先用默认图片代表等待状态
2006	PLAY_EVT_PLAY_END	视频播放结束
2007	PLAY_EVT_PLAY_LOADING	进入缓冲中状态，此时播放器在等待或积攒来自服务器的数据
-2301	PLAY_ERR_NET_DISCONNECT	网络连接断开，且重新连接亦不能恢复，播放器已停止播放

更多详细状态码请查看官方文档

说明：

播放 HTTP:// 打头的 FLV 协议地址时，如果观众遇到播放中直播流断开的情况，小程序是不会抛出 PLAY_EVT_PLAY_END 事件的，这是因为 FLV 协议中没有定义停止事件，所以只能通过监听 PLAY_ERR_NET_DISCONNECT 来替代之。

警告事件

内部警告并非不可恢复的错误，小程序内部的音视频 SDK 会启动相应的恢复措施，警告的目的主要用于提示开发者或者最终用户，例如：

code	事件定义	含义说明
2101	PLAY_WARNING_VIDEO_DECODE_FAIL	当前视频帧解码失败
2102	PLAY_WARNING_AUDIO_DECODE_FAIL	当前音频帧解码失败
2103	PLAY_WARNING_RECONNECT	网络断连，已启动自动重连恢复（重连超过三次就直接抛送 PLAY_ERR_NET_DISCONNECT 了）
2104	PLAY_WARNING_RECV_DATA_LAG	视频流不太稳定，可能是观看者当前网速不充裕
2105	PLAY_WARNING_VIDEO_PLAY_LAG	当前视频播放出现卡顿
2106	PLAY_WARNING_HW_ACCELERATION_FAIL	硬解启动失败，采用软解
2107	PLAY_WARNING_VIDEO_DISCONTINUITY	当前视频帧不连续，视频源可能有丢帧，可能会导致画面花屏
3001	PLAY_WARNING_DNS_FAIL	DNS解析失败（仅播放 RTMP:// 地址时会抛送）
3002	PLAY_WARNING_SEVER_CONN_FAIL	服务器连接失败（仅播放 RTMP:// 地址时会抛送）
3003	PLAY_WARNING_SHAKE_FAIL	服务器握手失败（仅播放 RTMP:// 地址时会抛送）

代码实例

Page({
    onPlay: function(ret) {
        if(ret.detail.code == 2004) {
                console.log('视频播放开始',ret);
        }
    },

    /**
     * 生命周期函数--监听页面加载
     */
    onLoad: function (options) {
    //...
    }
})

网络状态数据

键名	说明
videoBitrate	当前视频编/码器输出的比特率，单位 kbps
audioBitrate	当前音频编/码器输出的比特率，单位 kbps
videoFPS	当前视频帧率
videoGOP	当前视频 GOP,也就是每两个关键帧(I帧)间隔时长，单位 s
netSpeed	当前的发送/接收速度
netJitter	网络抖动情况，为 0 时表示没有任何抖动，值越大表明网络抖动越大，网络越不稳定
videoWidth	视频画面的宽度
videoHeight	视频画面的高度

小窗特性说明

live-player 小窗支持以下三种触发模式（在组件上设置 picture-in-picture-mode 属性）：

1. push 模式，即从当前页跳转至下一页时出现小窗（页面栈push）
2. pop 模式，即离开当页面时触发（页面栈pop）
3. 以上两种路由行为均触发小窗

此外，小窗还支持以下特性：

• 小窗容器尺寸会根据原组件尺寸自动判断
• 点击小窗，用户会被导航回小窗对应的播放器页面
• 小窗出现后，用户可点击小窗右上角的关闭按钮或调用 context.exitPictureInPicture() 接口关闭小窗

特别说明

1. 组件是由客户端创建的原生组件，它的层级是最高的，不能通过z-index控制层级。可以使用 和 覆盖在上面。

2. 请勿在 ，，， 中使用 组件。

3. live-player 默认宽度300px、高度225px，可通过wxss设置宽高。

4. 开发者工具上暂不支持。

5. css 动画对 live-pusher 组件无效。

常见问题

开发和运行环境要求

• 微信 App iOS 最低版本要求：6.5.21。
• 微信 App Android 最低版本要求：6.5.19。
• 小程序基础库最低版本要求：1.7.0。
• 由于微信开发者工具不支持原生组件（即 和 标签），需要在真机上进行运行体验。

调试时为什么要开启调试模式？

开启调试可以跳过把这些域名加入小程序白名单的工作，否则可能会遇到登录失败，通话无法连接的问题。

live-pusher

属性定义

属性名	类型	默认值	说明
url	String	-	用于音视频上行的推流 URL
mode	String	RTC	SD，HD，FHD，RTC
autopush	Boolean	false	是否自动启动推流
muted	Boolean	false	是否静音
enable-camera	Boolean	true	开启\关闭摄像头
auto-focus	Boolean	true	手动\自动对焦
orientation	String	vertical	vertical，horizontal
beauty	Number	0	美颜指数，取值 0 - 9，数值越大效果越明显
whiteness	Number	0	美白指数，取值 0 - 9，数值越大效果越明显
aspect	String	9：16	3：4，9：16
zoom	Boolean	false	是否正常焦距，true 表示将摄像头放大
device-position	String	front	front 前置摄像头，back 后置摄像头
min-bitrate	Number	200	最小码率，该数值决定了画面最差的清晰度表现
max-bitrate	Number	1000	最大码率，该数值决定了画面最好的清晰度表现
audio-quality	String	low	low 适合语音通话，high 代表高音质
waiting-image	String	-	当微信切到后台时的垫片图片
waiting-image-hash	String	-	当微信切到后台时的垫片图片的校验值
background-mute	Boolean	false	当微信切到后台时是否禁用声音采集
bindstatechange	String	-	用于指定一个 javascript 函数来接收音视频事件
debug	Boolean	false	是否开启调试模式

示例代码

<view id='video-box'>  
    <live-pusher
          id="pusher"
          mode="RTC"
          url="{{pusher.push_url}}" 
          autopush='true'
          bindstatechange="onPush">
    </live-pusher>  
 </view> 

属性详解

• url
  用于音视频上行的推流 URL，以rtmp://协议前缀打头，腾讯云推流 URL 的获取方法见 快速获取 URL 文档。

  说明：

  小程序内部使用的 RTMP 协议是支持 UDP 加速的版本，在同样网络条件下，UDP 版本的 RTMP 会比开源版本的有更好的上行速度和抗抖动能力。

• mode
  SD、HD 和 FHD 主要用于直播类场景，例如赛事直播、在线教育、远程培训等等。SD、HD 和 FHD 分别对应三种默认的清晰度。该模式下，小程序会更加注重清晰度和观看的流畅性，不会过分强调低延迟，也不会为了延迟牺牲画质和流畅性。

  RTC 则主要用于双向视频通话或多人视频通话场景，例如金融开会、在线客服、车险定损、培训会议等。该模式下，小程序会更加注重降低点到点的时延，也会优先保证声音的质量，在必要的时候会对画面清晰度和画面的流畅性进行一定的缩水。

• orientation 和 aspect
  横屏（horizontal）模式还是竖屏（vertical）模式，默认是竖屏模式，即 home 键朝下。这时，小程序推出的画面的宽高比是3：4或者9：16这两种竖屏宽高比的画面，也就是宽 < 高。如果改成横屏模式，小程序推出的画面宽高比即变为4：3或者16：9这种横屏宽高比的画面，也就是宽 > 高。

  具体的宽高比是有 aspect 决定的 ，默认是9：16， 也可以支持3：4。 这是在 orientation 的属性值为 vertical 的情况下。如果 orientation 的属性值为 horizontal，那么3：4的效果等价于4：3，9：16的效果等价于16：9。

• min-bitrate 和 max-bitrate
  这里首先要科普一个概念 —— 视频码率，指视频编码器每秒钟输出的视频数据的多少。在视频分辨率确定的情况下，视频码率越高，即每秒钟输出的数据越多，相应的画质也就越好。

  所以 min-bitrate 和 max-bitrate 这两个属性，分别用于决定输出画面的最低清晰度和最高清晰度。这两个数值并非越大越好，因为用户的网络上行不是无限好的。但也不是越小越好，因为实际应用场景中，清晰与否是用户衡量产品体验的一个重要指标。具体的数值设定我们会在**“参数设置”**部分详细介绍。

  小程序内部会自动处理好分辨率和码率的关系，例如2Mbps的码率，小程序会选择720p的分辨率进行匹配，而300kbps的码率下，小程序则会选择较低的分辨率来提高编码效率。所以您只需要关注 min-bitrate 和 max-bitrate 这一对参数就可以掌控画质了。

• waiting-image 和 waiting-image-hash
  出于用户隐私的考虑，在微信切到后台以后，小程序希望停止摄像头的画面采集。但是对于另一端的用户而言，画面会变成黑屏或者冻屏（停留在最后一帧），这种体验是非常差的。为了解决这个问题，我们引入了 waiting-image 属性，您可以设置一张有 “稍候” 含义的图片（waiting-image 是该图片的 URL，waiting-image-hash 则是该图片对应的 md5 校验值）。当微信切到后台以后，小程序会使用该图片作为摄像头画面的替代，以极低的流量占用维持视频流3分钟时间。

• debug
  调试音视频相关功能，如果没有很好的工具会是一个噩梦，所以小程序为 live-pusher 标签支持了 debug 模式，开始 debug 模式之后，原本用于渲染视频画面的窗口上，会显示一个半透明的 log 窗口，用于展示各项音视频指标和事件，降低您调试相关功能的难度，具体使用方法我们在 FAQ 中有详细说明。

参数设置

场景	mode	min-bitrate	max-bitrate	audio-quality	说明
标清直播	SD	300kbps	800kbps	high	窄带场景，例如户外或者网络不稳定的情况下适用
高清直播	HD	600kbps	1200kbps	high	目前主流的 App 所采用的参数设定，普通直播场景推荐使用这一档
超清直播	FHD	600kbps	1800kbps	high	对清晰度要求比较苛刻的场景，普通手机观看使用 HD 即可
视频客服（用户）	RTC	200kbps	500kbps	high	这是一种声音为主，画面为辅的场景，所以画质不要设置的太高
车险定损（车主）	RTC	200kbps	1200kbps	high	由于可能要看车况详情，画质上限会设置的高一些
多人会议（主讲）	RTC	200kbps	1000kbps	high	主讲人画质可以适当高一些，参与的质量可以设置的低一些
多人会议（参与）	RTC	150kbps	300kbps	low	作为会议参与者，不需要太高的画质和音质

如果不是对带宽特别没有信心的应用场景，audio-quality 选项请不要选择 low，其音质和延迟感都要会比 high 模式差很多。

对象操作

• wx.createLivePusherContext()
  通过 wx.createLivePusherContext() 可以将 标签和 javascript 对象关联起来，之后即可操作该对象。
• start
  开始推流，如果 的 autopush 属性设置为 false（默认值），那么就可以使用 start 来手动开始推流。
• stop
  停止推流。
• pause
  暂停推流。
• resume
  恢复推流，请与 pause 操作配对使用。
• switchCamera
  切换前后摄像头。
• snapshot
  推流截图，截图大小跟组件的大小一致。截图成功图片的临时路径为ret.tempImagePath。

代码实例

var pusher = wx.createLivePusherContext('pusher');
pusher.start({
    success: function(ret){
            console.log('start push success!')
        }
        fail: function(){
            console.log('start push failed!')
        }
        complete: function(){
            console.log('start push complete!')
        }
});

内部事件

通过 标签的 bindstatechange 属性可以绑定一个事件处理函数，该函数可以监听推流模块的内部事件和异常通知。

常规事件

code	事件定义	含义说明
1001	PUSH_EVT_CONNECT_SUCC	已经成功连接到云端服务器
1002	PUSH_EVT_PUSH_BEGIN	与服务器握手完毕，一切正常，准备开始上行推流
1003	PUSH_EVT_OPEN_CAMERA_SUCC	已成功启动摄像头，摄像头被占用或者被限制权限的情况下无法打开

严重错误

code	事件定义	含义说明
-1301	PUSH_ERR_OPEN_CAMERA_FAIL	打开摄像头失败
-1302	PUSH_ERR_OPEN_MIC_FAIL	打开麦克风失败
-1303	PUSH_ERR_VIDEO_ENCODE_FAIL	视频编码失败
-1304	PUSH_ERR_AUDIO_ENCODE_FAIL	音频编码失败
-1305	PUSH_ERR_UNSUPPORTED_RESOLUTION	不支持的视频分辨率
-1306	PUSH_ERR_UNSUPPORTED_SAMPLERATE	不支持的音频采样率
-1307	PUSH_ERR_NET_DISCONNECT	网络断连，且经三次重连无效，可以放弃，更多重试请 自行重启推流

警告事件

内部警告并非不可恢复的错误，小程序内部的音视频 SDK 会启动相应的恢复措施，警告的目的主要用于提示开发者或者最终用户，例如：

• PUSH_WARNING_NET_BUSY
  上行网速不给力，建议提示用户改善当前的网络环境，例如让用户离家里的路由器近一点，或者切到 Wi-Fi 环境下再使用。
• PUSH_WARNING_SERVER_DISCONNECT
  请求被后台拒绝了，出现这个问题一般是由于 URL 里的 txSecret 计算错了，或者是 URL 被其他人占用了（跟播放不同，一个推流 URL 同时只能有一个用户使用）。
• PUSH_WARNING_HANDUP_STOP
  当用户单击小程序右上角的圆圈或者返回按钮时，微信会将小程序挂起，此时 会抛出5000这个事件。

code	事件定义	含义说明
1101	PUSH_WARNING_NET_BUSY	上行网速不够用，建议提示用户改善当前的网络环境
1102	PUSH_WARNING_RECONNECT	网络断连，已启动重连流程（重试失败超过三次会放弃）
1103	PUSH_WARNING_HW_ACCELERATION_FAIL	硬编码启动失败，自动切换到软编码
1107	PUSH_WARNING_SWITCH_SWENC	由于机器性能问题，自动切换到硬件编码
3001	PUSH_WARNING_DNS_FAIL	DNS 解析失败，启动重试流程
3002	PUSH_WARNING_SEVER_CONN_FAIL	服务器连接失败，启动重试流程
3003	PUSH_WARNING_SHAKE_FAIL	服务器握手失败，启动重试流程
3004	PUSH_WARNING_SERVER_DISCONNECT	服务器主动断开连接，启动重试流程
3005	PUSH_WARNING_SERVER_DISCONNECT	socket 链路异常断开 ，启动重试流程
5000	PUSH_WARNING_HANDUP_STOP	小程序被用户挂起

代码实例

Page({
    onPush: function(ret) {
        if(ret.detail.code == 1002) {
                console.log('推流成功了',ret);
        }
    },

    /**
     * 生命周期函数--监听页面加载
     */
    onLoad: function (options) {
    //...
    }
})