直播 SDK 小程序（多端框架）

<live-player> 是小程序内部用于支持音视频下行（播放）能力的功能标签，支持 多端框架。
说明：
多端框架编译成 Android/iOS 应用需要参见 新增与续期 License 获取 License 信息后在微信开发者工具 project.miniapp.json 勾选 Live SDK，并且完成相关配置。
﻿
工具版本支持
开发者工具版本 ≥ 1.06.2506252
iOS SDK：需使用版本号 ≥ 1.6.16
﻿
Android SDK：需使用版本号 ≥ 1.6.15
﻿
属性定义
属性名
类型
默认值
说明
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。
min-cache
number
1
最小缓冲延迟， 单位：秒。
max-cache
number
3
最大缓冲延迟， 单位：秒。
bindstatechange
eventhandle
-
用于指定一个 JavaScript 函数来接收播放器事件。
bindfullscreenchange
eventhandle
-
用于指定一个 JavaScript 函数来接收全屏事件。
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> 
超低延时
<live-player> 的 RTC 模式支持500ms以内的超低延时链路，可以应用在视频通话和远程遥控等场景中，要使用超低延时播放，需要注意如下几点：
推流端如果是微信小程序或多端应用，请使用 <live-pusher> 的 RTC 模式。
<live-player> 的 min-cache 和 max-cache 请不要自行设置，使用默认值。
播放地址请使用超低延时播放地址，也就是带了防盗链签名的 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&txSecret=20e6d865f462dff61ada209d53c71cf9
< 500ms
属性详解
src
用于音视频下行的播放 URL，支持 RTMP 协议（URL 以 “rtmp://” 打头）和 FLV 协议（URL 以 “http://” 打头且以 “.flv” 结尾） ，腾讯云推流 URL 的获取方法见 DOC。
说明
  <live-player> 标签是不支持 HLS(m3u8) 协议的，因为 <video> 已经支持 HLS(m3u8) 播放协议了。但直播观看不推荐使用 HLS(m3u8) 协议，延迟要比 RTMP 和 FLV 协议高一个数量级。
mode
live 模式主要用于直播类场景，例如赛事直播、在线教育和远程培训等。该模式下，SDK 内部的模块会优先保证观看体验的流畅，通过调整 min-cache 和 max-cache 属性，您可以调节观众（播放）端所感受到的时间延迟的大小，文档下面会详细介绍这两个参数。
RTC 则主要用于双向视频通话或多人视频通话场景，例如金融开会、在线客服、车险定损和培训会议等。在此模式下，对 min-cache 和 max-cache 的设置不会起作用，因为 SDK 内部会自动将延迟控制在一个很低的水平（500ms左右）。
min-cache 和 max-cache
这两个参数分别用于指定观看端的最小缓冲时间和最大缓冲时间。所谓缓冲时间，是指播放器为了缓解网络波动对观看流畅度的影响而引入的一个“蓄水池”，当来自网络的数据包出现卡顿甚至停滞的时候，“蓄水池”里的紧急用水可以让播放器还能坚持一小段时间，只要在这个短暂的时间内网速恢复正常，播放器就可以源源不断地渲染出流畅而平滑的视频画面。
“蓄水池”里的水越多，抗网络波动的能力就越强，但代价就是观众端的延迟就越大，所以要在不同的场景下，使用不同的配置来达到体验上的平衡：
码率比较低（1Mbps左右，画面以人物为主）的直播流，min-cache = 1，max-cache = 3较合适。
码率比较高（2Mbps - 3Mbps的高清游戏画面为主）的直播流，min-cache = 3，max-cache = 5较合适。
RTC 模式下这两个参数是无效的。
orientation
画面渲染角度，horizontal 代表是原始画面方向，vertical 代表向右旋转90度。
object-fit
画面填充模式，contain 代表把画面显示完成，但如果视频画面的宽高比和 <live-player> 标签的宽高比不一致，那么您将看到黑边。fillCrop 代表把屏幕全部撑满，但如果视频画面的宽高比和 <live-player> 标签的宽高比不一致，那么画面中多余的部分会被裁剪掉。
sound-mode
设置播放模式，可设值为： ear 与 speaker，ear 代表使用听筒播放， speaker 代表使用扬声器，默认为扬声器。
debug
为了很好地调试音视频的相关功能，SDK 为 live-pusher 标签提供了 debug 模式，开始 debug 模式之后，原本用于渲染视频画面的窗口上，会显示一个半透明的 log 窗口，用于展示各项音视频指标和事件，降低您调试相关功能的难度，具体使用方法我们在 FAQ 中有详细说明。
对象操作
参数
说明
wx.createLivePlayerContext()
通过 wx.createLivePlayerContext() 可以将 <live-player> 标签和 JavaScript 对象关联起来，之后即可操作该对象。
play
开始播放，如果 <live-player> 的 autoplay 属性设置为 false（默认值），那么就可以使用 play 来手动启动播放。
stop
停止播放。
pause
暂停播放，停留在最后画面。
resume
继续播放，与 pause 成对使用。
mute
设置静音。
requestFullScreen
进入全屏幕。
exitFullScreen
退出全屏幕。
var player = wx.createLivePlayerContext('player');
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 协议地址时，如果观众遇到播放中直播流断开的情况，SDK 是不会抛出 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_SERVER_CONN_FAIL
服务器连接失败（仅播放 RTMP:// 地址时会抛送）。
3003
PLAY_WARNING_SHAKE_FAIL
服务器握手失败（仅播放 RTMP:// 地址时会抛送）。
示例代码
Page({
    onPlay: function(ret) {
        if(ret.detail.code == 2004) {
                console.log('视频播放开始',ret);
        }
    },
﻿
    /**
     * 生命周期函数--监听页面加载
     */
    onLoad: function (options) {
    //...
    }
})
特别说明
<live-player> 组件是由客户端创建的原生组件，它的层级是最高的，可以使用 <cover-view> 和 <cover-image> 覆盖在上面。
请勿在 <scroll-view> 中使用 <live-player> 组件。
<live-player>组件的 RTC 模式有并发播放限制，目前最多同时10路并发播放。
说明：
设置该限制原因并非技术能力限制，而是希望您只考虑在互动场景中使用（例如连麦时只给主播使用，或者夹娃娃直播中只给操控娃娃机的玩家使用），避免因为盲目追求低延时而产生不必要的费用损失（低延迟线路的价格要高于 CDN 线路的价格）。

属性名	类型	默认值	说明
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。
min-cache	number	1	最小缓冲延迟，单位：秒。
max-cache	number	3	最大缓冲延迟，单位：秒。
bindstatechange	eventhandle	-	用于指定一个 JavaScript 函数来接收播放器事件。
bindfullscreenchange	eventhandle	-	用于指定一个 JavaScript 函数来接收全屏事件。
debug	boolean	false	是否开启调试模式。

对比项目	示例	时延
普通直播 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&txSecret=20e6d865f462dff61ada209d53c71cf9	< 500ms

参数	说明
wx.createLivePlayerContext()	通过 wx.createLivePlayerContext() 可以将 <live-player> 标签和 JavaScript 对象关联起来，之后即可操作该对象。
play	开始播放，如果 <live-player> 的 autoplay 属性设置为 false（默认值），那么就可以使用 play 来手动启动播放。
stop	停止播放。
pause	暂停播放，停留在最后画面。
resume	继续播放，与 pause 成对使用。
mute	设置静音。
requestFullScreen	进入全屏幕。
exitFullScreen	退出全屏幕。

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	网络连接断开，且重新连接亦不能恢复，播放器已停止播放。

小程序（多端框架）

本页目录：

工具版本支持

属性定义

示例代码

超低延时

属性详解

对象操作

内部事件

关键事件

警告事件

示例代码

特别说明