TXLivePlayerV2

概述

快直播概述

快直播（Live Event Broadcasting，LEB）是标准直播在超低延迟播放场景下的延伸，比传统直播协议延迟更低，为观众提供毫秒级的极致直播观看体验。能够满足一些对延迟性能要求更高的特定场景需求，例如在线教育、体育赛事直播、在线答题等。

方案优势

毫秒级超低延迟播放：采用 UDP 协议将传统直播中3秒 - 5秒延迟降低至1秒以内，同时兼顾秒开、卡顿率等核心指标，给用户带来极致的超低延迟直播体验。
功能完善，平滑兼容：兼容了标准直播包括推流、转码、录制、截图、鉴黄、播放等全功能，支持客户从现有的标准直播业务平滑迁移。
简单易用，安全可靠：采用标准协议，对接简单，在 Chrome 和 Safari 浏览器中无需任何插件即可进行播放。播放协议默认加密，更加安全可靠。

适用场景

体育赛事：快直播为体育赛事提供超低延迟的直播能力加持，使比赛赛事结果快速通过直播触达用户，让观众享受实时了解赛事动态的乐趣。
电商直播：电商直播中，商品拍卖、促销抢购等交易反馈对直播实时性要求很高，快直播的超低延迟能力，能让主播和观众能够及时得到交易反馈，提升边看边买的体验。
在线课堂师生通过直播完成在线的课堂教学，得力于快直播的超低延迟能力，使课堂互动能力得到提升，让在线课堂也能像线下授课一样自然。
在线答题：传统的在线答题由于存在延迟，观众端有时需要进行补帧才能让观众主持两端同时显示。快直播的超低延迟能够完美解决这个问题，让双方实时看到答题画面，降低了实现难度，也让体验更加流畅。
秀场互动：快直播适用于秀场直播场景，极大优化了在观众送礼等对画面实时性要求高的直播互动场景中的观众互动体验。

本插件封装了腾讯的快直播视频播放器。直播（LIVE）的视频源是主播实时推送的。因此，主播停止推送后，播放端的画面也会随即停止，而且由于是实时直播，所以播放器在播直播 URL 的时候是没有进度条的。

通常使用的直播协议如下，App 端推荐使用 FLV 协议的直播地址（以“http”打头，以“.flv”结尾）：

FLV：成熟度高、高并发无压力，播放延迟2-3s
RTMP：优质线路下理论延迟最低（1-3s），高并发情况下表现欠佳
HLS：手机浏览器支持度高，延迟也非常高（10-30s）

关于AVM方式

本插件支持 AVM 方式打开。通过 AVM 标签方式打开的插件，在 js 代码中需要通过 document.getElementById 的形式获取该插件实例对象然后进行其它逻辑的操作。否则会产生莫名其妙的问题。

该插件同时也支持 api.require 方式调用，通过 configView 接口相当于 AVM 的标签打开了一个视频播放区域的 frame（view）插件，用户点击全屏按钮后，插件自动代码一个 window 来全屏播放视频。

关于后台播放功能

如需支持后台播放功能请参考 config.xml 配置说明文档里关于 BackgroundMode 的配置

配置实例如下：

<preference name="backgroundMode" value="audio"/>

注意：iOS端1.0.1版（原生SDK 10.1版本）本开始增加授权校验，详情参考腾讯文档

插件接口

setLicence

设置验证

setLicence({params})

params

licenceURL：

类型：字符串
描述：腾讯直播平台申请的 url

licenceKey：

类型：字符串
描述：腾讯直播平台申请的 key

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setLicence({
  licenceURL:'',
  licenceKey:''
})

可用性

iOS 系统

可提供的 1.0.1 及更高版本

configPlayerView

配置直播播放器视图。

注意：本接口仅支持引擎2.0方式调用。引擎3.0上可直接通过 mo-txliveplayerv2 标签配置使用播放器。

configPlayerView({params})

params

rect：

类型：JSON 类型
描述：（可选项）视频播放器的位置及大小
内部字段：

{
    x: 0,        //（可选项）数字类型；插件左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认值：0
    y: 0,        //（可选项）数字类型；插件左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认值：0
    w:300,       //（可选项）数字类型;插件宽度（相对于所属的 Window 或 Frame;默认：100%
    h:600        //（可选项）数字类型;插件高度（相对于所属的 Window 或 Frame;默认：100%
}

fixedOn：

类型：字符串类型
描述：（可选项）插件添加到指定 frame 的名字（只指 frame，传 window 无效）
默认：预览窗口依附于当前 window

fixed:

类型：布尔
描述：（可选项）预览窗口是否随所属 window 或 frame 滚动
默认值：true（不随之滚动）

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.configPlayerView({
  rect:{
    x:,
    y:,
    w:,
    h:
  },
  fixedOn:'',
  fixed:false
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

resizePlayerView

重设播放器位置和大小

注意：本接口仅对 configPlayerView 打开的播放器有效

resizePlayerView({params})

params

rect：

类型：JSON 类型
描述：（可选项）预览窗口的位置及大小
内部字段：

{
    x: 0,        //（可选项）数字类型；插件左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认值：原x坐标
    y: 0,        //（可选项）数字类型；插件左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认值：原y坐标
    w:300,       //（可选项）数字类型;插件宽度（相对于所属的 Window 或 Frame;默认：原宽度
    h:600        //（可选项）数字类型;插件高度（相对于所属的 Window 或 Frame;默认：原高度
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.resizePlayerView({
  rect:{
    x:,
    y:,
    w:,
    h:
  }
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

hidePlayerView

隐藏播放试图的 frame

hidePlayerView()

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.hidePlayerView()

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

showPlayerView

恢复显示播放试图的 frame

showPlayerView()

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.showPlayerView()

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

initPlayer

初始化播放器

initPlayer()

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.initPlayer()

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

closePlayer

关闭播放器

closePlayer()

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.closePlayer()

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setRenderRotation

设置本地摄像头预览画面的旋转角度。

setRenderRotation({params},callback(ret))

params

rotation：

类型：字符串
描述：（可选项）旋转角度
默认：0
取值范围：
- 0:不旋转
- 90:顺时针旋转90度
- 180:顺时针旋转180度
- 270:顺时针旋转270度

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setRenderRotation({
  rotation:90
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setRenderFillMode

设置画面的填充模式。

setRenderFillMode({params},callback(ret))

params

mode：

类型：字符串
描述：（可选项）画面填充模式
默认：fit
取值范围：
- fill:图像铺满屏幕，超出显示视窗的视频部分将被裁剪，画面显示可能不完整
- fit:图像长边填满屏幕，短边区域会被填充黑色，画面的内容完整

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setRenderFillMode({
  mode:'fill'
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

startPlay

开始播放

startPlay({params},callback(ret))

params

videoURL：

类型：字符串
描述：视频拉流地址

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.startPlay({
    videoURL:'http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8'
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

stopPlay

停止播放音视频流

stopPlay(callback(ret))

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.stopPlay(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

isPlaying

isPlaying()

是否正在播放

callback

ret:

类型：JSON对象
描述：返回值

{ 
   isPlaying:,              //布尔类型；是否正在播放
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.isPlaying(function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

pauseAudio

暂停音频播放

pauseAudio(callback(ret))

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.pauseAudio(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

resumeAudio

恢复音频播放

resumeAudio(callback(ret))

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.resumeAudio(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

pauseVideo

暂停视频播放

pauseVideo(callback(ret))

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.pauseVideo(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

resumeVideo

恢复视频播放

resumeVideo(callback(ret))

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.resumeVideo(function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setPlayoutVolume

设置音量

setPlayoutVolume({params},callback(ret))

params

volume：

类型：数字
描述：（可选项）设置音量大小，取值范围0 - 100
默认：100

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setPlayoutVolume({
    volume: 1
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setCacheParams

设置播放器缓存自动调整的最小和最大时间 ( 单位：秒 )。

注意：要在开始播放之前设置！

setCacheParams({params},callback(ret))

params

minTime：

类型：数字
描述：（可选项）缓存自动调整的最小时间，取值需要大于0
默认：1

maxTime：

类型：数字
描述：（可选项）缓存自动调整的最大时间，取值需要大于0
默认：5

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setCacheParams({
    minTime: 1,
    maxTime: 5
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

enableVolumeEvaluation

启用播放音量大小提示。

enableVolumeEvaluation({params},callback(ret))

params

intervalMs：

类型：数字
描述：（可选项）回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms
默认：0

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode，仅首次回调有值
    volume:    //数字类型；音量大小，首次回调无值
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.enableVolumeEvaluation({
    intervalMs: 100
},function(ret){
   console.log(JSON.stringify(ret));
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

snapshot

获取截图

snapshot(callback(ret))

callback(ret)

ret:

类型：JSON对象
描述：返回值

{
   status:,          //布尔类型；是否获取成功
   path:             //字符串类型；截图路径
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.snapshot(function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

enableReceiveSeiMessage

开启接收 SEI 消息

enableReceiveSeiMessage({params},callback(ret))

params

enable：

类型：布尔
描述：（可选项）开启/关闭接收 SEI 消息
默认：false

payloadType：

类型：数字
描述：（可选项）指定接收 SEI 消息的 payloadType，支持 5、242，请与发送端的 payloadType 保持一致。
默认：5

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.enableReceiveSeiMessage({
    payloadType: 5,
    enable: true
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

showDebugView

是否显示播放器状态信息的调试浮层

showDebugView({params},callback(ret))

params

showDebug：

类型：布尔
描述：（可选项）是否显示
默认：false

callback(ret)

ret：

类型：JSON对象
内部字段：
注意：Android端不支持回调

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.showDebugView({ 
    showDebug: true
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

setProperty

调用高级 API 接口。该接口用于调用一些高级功能。

setProperty({params},callback(ret))

params

key：

类型：字符串
描述：高级 API 对应的 key

value：

类型：字符串
描述：调用 key 所对应的高级 API 时，需要的参数。

callback(ret)

ret：

类型：JSON对象
内部字段：

{
    status:    //数字类型；状态码，详情参考 V2TXLiveCode
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.setProperty({ 
    key: '',
    value:''
},function(ret){
   api.alert({msg:JSON.stringify(ret)});
})

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

addEventListener

addEventListener(callback(ret))

添加直播事件监听

callback(ret)

ret:

类型：JSON对象
描述：返回值

{
   eventType: '',           //字符串类型；回调事件类型，取值范围：
                            //onError
                            //onWarning
                            //onVideoPlayStatusUpdate
                            //onAudioPlayStatusUpdate
                            //onStatisticsUpdate
                            //onReceiveSeiMessage
   payloadType:,            //字符串类型；仅当onReceiveSeiMessage时有值
   data:'',                 //字符串类型；仅当onReceiveSeiMessage时有值
   statistics: {            //JSON对象；仅当onStatisticsUpdate时有值
      appCpu:,       //数字类型；当前 App 的 CPU 使用率（％）
       systemCpu:,    //数字类型；当前系统的 CPU 使用率（％）
       width:,        //数字类型；视频宽度
       height:        //数字类型；视频高度
       fps:           //数字类型；帧率（fps）
       videoBitrate:  //数字类型；视频码率（Kbps）
       audioBitrate:  //数字类型；音频码率（Kbps）
   }
   status:'',        //数字类型；状态码，仅当onVideoPlayStatusUpdate和onAudioPlayStatusUpdate时有值
   reason:'',        //数字类型；状态对应的原因，仅当onVideoPlayStatusUpdate和onAudioPlayStatusUpdate时有值
   code:,            //数字类型；错误码，仅当onError和onWarning时有值
   msg:'',           //字符串类型；错误信息，仅当onError和onWarning时有值 
}

示例代码

var TXLivePlayerV2 = api.require('TXLivePlayerV2');
TXLivePlayerV2.addEventListener(function(ret){
    api.alert({msg: JSON.stringify(ret)});
});

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

V2TXLiveCode

/// 没有错误 V2TXLIVE_OK = 0,

/// 暂未归类的通用错误
V2TXLIVE_ERROR_FAILED = -1,

/// 调用 API 时，传入的参数不合法
V2TXLIVE_ERROR_INVALID_PARAMETER = -2,

/// API 调用被拒绝
V2TXLIVE_ERROR_REFUSED = -3,

/// 当前 API 不支持调用
V2TXLIVE_ERROR_NOT_SUPPORTED = -4,

/// license 不合法，调用失败
V2TXLIVE_ERROR_INVALID_LICENSE = -5,

/// 请求服务器超时
V2TXLIVE_ERROR_REQUEST_TIMEOUT = -6,

/// 服务器无法处理您的请求
V2TXLIVE_ERROR_SERVER_PROCESS_FAILED = -7,

/////////////////////////////////////////////////////////////////////////////////
//
//      网络相关的警告码
//
/////////////////////////////////////////////////////////////////////////////////

/// 网络状况不佳：上行带宽太小，上传数据受阻
V2TXLIVE_WARNING_NETWORK_BUSY = 1101,

/// 当前视频播放出现卡顿
V2TXLIVE_WARNING_VIDEO_BLOCK = 2105,

/////////////////////////////////////////////////////////////////////////////////
//
//             摄像头相关的警告码
//
/////////////////////////////////////////////////////////////////////////////////

/// 摄像头打开失败
V2TXLIVE_WARNING_CAMERA_START_FAILED = -1301,

/// 摄像头正在被占用中，可尝试打开其他摄像头
V2TXLIVE_WARNING_CAMERA_OCCUPIED = -1316,

/// 摄像头设备未授权，通常在移动设备出现，可能是权限被用户拒绝了
V2TXLIVE_WARNING_CAMERA_NO_PERMISSION = -1314,

/////////////////////////////////////////////////////////////////////////////////
//
//             麦克风相关的警告码
//
/////////////////////////////////////////////////////////////////////////////////

/// 麦克风打开失败
V2TXLIVE_WARNING_MICROPHONE_START_FAILED = -1302,

/// 麦克风正在被占用中，例如移动设备正在通话时，打开麦克风会失败
V2TXLIVE_WARNING_MICROPHONE_OCCUPIED = -1319,

/// 麦克风设备未授权，通常在移动设备出现，可能是权限被用户拒绝了
V2TXLIVE_WARNING_MICROPHONE_NO_PERMISSION = -1317,

/////////////////////////////////////////////////////////////////////////////////
//
//             屏幕分享相关警告码
//
/////////////////////////////////////////////////////////////////////////////////

/// 当前系统不支持屏幕分享
V2TXLIVE_WARNING_SCREEN_CAPTURE_NOT_SUPPORTED = -1309,

/// 开始录屏失败，如果在移动设备出现，可能是权限被用户拒绝了
V2TXLIVE_WARNING_SCREEN_CAPTURE_START_FAILED = -1308,

/// 录屏被系统中断
V2TXLIVE_WARNING_SCREEN_CAPTURE_INTERRUPTED = -7001,

是否仍需要帮助？请保持联络！

最后更新于 2024/04/24