TXLivePusher

TXLivePusher

腾讯云直播推流器，主要用于浏览器快直播推流。通过浏览器采集用户的画面和声音，通过 WebRTC 将视频流和音频流传输推送到腾讯云服务端。

如果需要开启本地混流功能，调用 TXVideoEffectManager 方法 enableMixing() 来启用。

Constructor

new TXLivePusher()

创建实例对象，用于后续所有操作。

Example
const livePusher = new TXLivePusher();

Members

version :string

TXLivePusher SDK 版本号。

Type:
  • string
Example
console.log(TXLivePusher.version);

Methods

(static) checkSupport() → {Promise.<object>}

静态函数，检查浏览器支持性。

Example
TXLivePusher.checkSupport().then((data) => {
  if (!data.isWebRTCSupported) {
    console.log('WebRTC is not supported');
  }
});
Returns:

返回 Promise 对象，其中检查结果结构如下:

Name Type Description
isWebRTCSupported boolean 是否支持 WebRTC
isH264EncodeSupported boolean 是否支持 H264 编码
isH264DecodeSupported boolean 是否支持 H264 解码
isMediaDevicesSupported boolean 是否支持获取媒体设备及媒体流
isScreenCaptureSupported boolean 是否支持屏幕采集
isMediaFileSupported boolean 是否支持获取本地媒体文件流
Type
Promise.<object>

setRenderView(container)

设置本地视频画面的预览容器，需提供一个 div 节点，本地采集的视频会在容器里渲染。如果开启了本地混流功能，容器里面会渲染混流处理之后的音视频。

Example
livePusher.setRenderView('id_local_video');
Parameters:
Name Type Description
container string | HTMLDivElement

容器的 id 或者 dom 节点。

setVideoQuality(quality)

设置推流视频质量，SDK 已经内置了视频质量模板，直接通过预定义的模板来设置推流视频质量。

说明：

  1. 由于设备和浏览器的限制，视频分辨率不一定能够完全匹配，在这种情况下，浏览器会自动调整分辨率使其接近对应的分辨率。
  2. 如果视频质量参数（分辨率、帧率和码率）不符合您的要求，您可以通过 setProperty() 单独设置自定义的值。
  3. 此处视频分辨率主要表示本地采集的视频分辨率，推流时分辨率可能会低于采集的分辨率，浏览器会根据网络带宽等情况自动调整推流分辨率。
  4. 默认使用 720p ，即 setVideoQuality('720p') 。
Example
livePusher.setVideoQuality('720p');
Parameters:
Name Type Description
quality string

预定义的视频质量模板名称。内置的视频质量模板如下所示:

模板名 分辨率（宽 x 高） 帧率（fps） 码率（kbps）
120p 160 x 120 15 200
180p 320 x 180 15 350
240p 320 x 240 15 400
360p 640 x 360 15 800
480p 640 x 480 15 900
720p 1280 x 720 15 1500
1080p 1920 x 1080 15 2000
2K 2560 x 1440 30 4860
4K 3840 x 2160 30 9000

setAudioQuality(quality)

设置推流音频质量，SDK 已经内置了音频质量模板，直接通过预定义的模板来设置推流音频质量。

说明：

  1. 如果音频质量参数（采样率和码率）不符合您的要求，您可以通过 setProperty() 单独设置自定义的值。
  2. 默认使用 standard ，即 setAudioQuality('standard') 。
Example
livePusher.setAudioQuality('standard');
Parameters:
Name Type Description
quality string

预定义的音频质量模板名称。内置的音频质量模板如下所示：

模板名 采样率 码率（kbps）
standard 48000 40
high 48000 128

setProperty(key, value)

主要用于调用一些高级功能，比如设置视频的分辨率、帧率和码率，设置音频的采样率和码率等。

目前支持以下高级功能：

Key Value 描述 示例
setVideoResolution { width: number; height:number; } 设置视频的分辨率 setProperty('setVideoResolution', { width: 1920, height: 1080 })
setVideoFPS number 设置视频的帧率 setProperty('setVideoFPS', 25)
setVideoBitrate number 设置视频的码率 setProperty('setVideoBitrate', 2000)
setVideoCodec string 设置视频的编码格式，默认值 'H264'；取值包括 'H264'，'H265'，'VP8'，'VP9'，'AV1'。 setProperty('setVideoCodec', 'H264')
setAudioSampleRate number 设置音频的采样率 setProperty('setAudioSampleRate', 44100)
setAudioBitrate number 设置音频的码率 setProperty('setAudioBitrate', 200)
setConnectRetryCount number 设置连接重试次数，默认值：3；取值范围：0 - 10。当 SDK 与服务器异常断开连接时，SDK 会尝试与服务器重连。 setProperty('setConnectRetryCount', 5)
setConnectRetryDelay number 设置连接重试延迟，默认值：1，单位为秒；取值范围：0 - 10。当 SDK 与服务器异常断开连接时， SDK 会尝试与服务器重连。 setProperty('setConnectRetryDelay', 2)
setMetadata object 设置推流 metadata 数据 setProperty('setMetadata', { videodatarate: 2000, audiodatarate: 40 })
enableAudioAEC boolean 启用回声消除 setProperty('enableAudioAEC', true)
enableAudioAGC boolean 启用自动增益 setProperty('enableAudioAGC', true)
enableAudioANS boolean 启用噪声抑制 setProperty('enableAudioANS', true)
enableLog boolean 是否在控制台打印日志 setProperty('enableLog', true)

说明：

  1. 回声消除、自动增益和噪声抑制默认全部启用，最终是否起效依赖于设备和浏览器。这三个功能建议要么全部启用，要么全部禁用。
  2. 请在采集流和推流之前进行设置。
  3. 默认使用 H264 编码，使用其他编码格式前需要提交工单进行开通。
Example
livePusher.setProperty('setVideoResolution', { width: 1920, height: 1080 });
Parameters:
Name Type Description
key string

高级 API 对应的 key。
value *

调用 key 所对应的高级 API 时需要的参数。

(async) startCamera(deviceIdopt) → {Promise.<string>}

打开摄像头设备。需要用户授权允许浏览器访问摄像头，授权失败或者访问设备失败，返回的 Promise 对象会抛出错误。

说明：

  1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
  2. 打开摄像头失败时返回的错误信息，可参考 getUserMedia 异常 。
Example
livePusher.startCamera().then((streamId) => {
  console.log('camera stream id is ' + streamId);
}).catch((error) => {
  console.log('start camera error: '+ error.toString());
});
Parameters:
Name Type Attributes Description
deviceId string <optional>

摄像头设备 id，可选参数，指定打开的摄像头设备。设备 id 可通过 TXDeviceManager 中的方法 getDevicesList() 获取。在移动设备上，可以通过传入 'user' 和 'environment' 来指定打开前置和后置摄像头。
Returns:

返回 Promise 对象，成功时返回流 id 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。

Type
Promise.<string>

stopCamera(streamIdopt)

关闭摄像头设备。

Example
livePusher.stopCamera();
Parameters:
Name Type Attributes Description
streamId string <optional>

流 id，可选参数，指定需要关闭的摄像头流。启用本地混流之后，如果采集了多路摄像头流，可通过流 id 关闭指定的摄像头流，否则关闭所有的摄像头流。

(async) startMicrophone(deviceIdopt) → {Promise.<string>}

打开⻨克⻛设备。需要用户授权允许浏览器访问⻨克⻛，授权失败或者访问设备失败，返回的 Promise 对象会抛出错误。

说明：

  1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
  2. 打开麦克风失败时返回的错误信息，可参考 getUserMedia 异常 。
  3. 如果出现回声现象，可以将本地用于播放预览的视频元素 video 静音，避免回声现象的出现。
const videoEl = livePusher.getRenderView();
if (videoEl) {
  videoEl.muted = true;
}
Example
livePusher.startMicrophone().then((streamId) => {
  console.log('microphone stream id is ' + streamId);
}).catch((error) => {
  console.log('start microphone error: '+ error.toString());
});
Parameters:
Name Type Attributes Description
deviceId string <optional>

麦克风设备 id，可选参数，指定打开的麦克风设备。设备 id 可通过 TXDeviceManager 中的方法 getDevicesList() 获取。
Returns:

返回 Promise 对象，成功时返回流 id 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。

Type
Promise.<string>

stopMicrophone(streamIdopt)

关闭⻨克⻛设备。

Example
livePusher.stopMicrophone();
Parameters:
Name Type Attributes Description
streamId string <optional>

流 id，可选参数，指定需要关闭的麦克风流。启用本地混流之后，如果采集了多路麦克风流，可通过流 id 关闭指定的麦克风流，否则关闭所有的麦克风流。

(async) startScreenCapture(audioopt) → {Promise.<string>}

开启屏幕采集。需要用户授权允许浏览器访问屏幕，授权失败或者访问屏幕失败，返回的 Promise 对象会抛出错误。

说明：

  1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
  2. 打开屏幕采集失败时返回的错误信息，可参考 getDisplayMedia 异常 。
  3. 目前只有 Chrome 74+ 和 Edge 79+ 支持采集声音，在 windows 系统可以采集整个系统的声音，在 Linux 和 Mac 上面只能采集标签⻚的声音。
  4. 如果设置了 audio 为 true，在浏览器的屏幕分享弹窗中还需要确保弹窗最下面的采集声音选项是勾选状态，否则也不会采集声音。如果设置了 audio 为 false，浏览器的屏幕分享弹窗中不会出现采集声音的选项。
Example
livePusher.startScreenCapture().then((streamId) => {
  console.log('screen stream id is ' + streamId);
}).catch((error) => {
  console.log('start screen error: '+ error.toString());
});
Parameters:
Name Type Attributes Default Description
audio boolean <optional>
 false

是否采集系统声音或者标签⻚声音，true - 采集声音，false - 不采集声音，默认 false。
Returns:

返回 Promise 对象，成功时返回流 id 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。

Type
Promise.<string>

stopScreenCapture(streamIdopt)

关闭屏幕采集。

Example
livePusher.stopScreenCapture();
Parameters:
Name Type Attributes Description
streamId string <optional>

流 id，可选参数，指定需要关闭的屏幕分享流。启用本地混流之后，如果采集了多路屏幕分享流，可通过流 id 关闭指定的屏幕分享流，否则关闭所有的屏幕分享流。

(async) startVirtualCamera(file) → {Promise.<string>}

开始采集本地媒体文件流。目前支持的文件格式有视频 mp4，音频 mp3 和图片 jpg、png、bmp。

说明：

  1. 本地文件支持视频、音频和图片。视频文件采集视频流和音频流，音频文件只采集音频流，图片文件只采集视频流。
  2. 必须手动传入 file 对象，需要提前使用 <input type="file"> 引导用户选择本地文件。
Example
// file - local file
livePusher.startVirtualCamera(file).then((streamId) => {
  console.log('file stream id is ' + streamId);
}).catch((error) => {
  console.log('start file error: '+ error.toString());
});
Parameters:
Name Type Description
file File

本地媒体文件，必传。文件格式必须是以下几种：mp4、mp3、jpg、png、bmp。
Returns:

返回 Promise 对象，成功时返回流 id 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。

Type
Promise.<string>

stopVirtualCamera(streamIdopt)

停止采集本地媒体文件流。

Example
livePusher.stopVirtualCamera();
Parameters:
Name Type Attributes Description
streamId string <optional>

流 id，可选参数，指定需要关闭的媒体文件流。启用本地混流之后，如果采集了多路媒体文件流，可通过流 id 关闭指定的媒体文件流，否则关闭所有的媒体文件流。

startMediaFile()

Deprecated:

stopMediaFile()

Deprecated:

(async) startCustomCapture(stream) → {Promise.<string>}

使用用户自定义的音视频流。将用户自己采集的流用于本地混流和推送。

Example
const constraints = { audio: true, video: { width: 1280, height: 720 } };

navigator.mediaDevices.getUserMedia(constraints)
.then((mediaStream) => {
  livePusher.startCustomCapture(mediaStream).then((streamId) => {
    console.log('custom stream id is ' + streamId);
  }).catch((error) => {
    console.log('start custom error: '+ error.toString());
  });
}).catch((error) => {
  console.log(error.name + ': ' + error.message);
});
Parameters:
Name Type Description
stream MediaStream

用户自定义的流。
Returns:

返回 Promise 对象，成功时返回流 id 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。

Type
Promise.<string>

stopCustomCapture(streamIdopt)

关闭自定义的音视频流，仅移除自定义流，不会停止自定义流。

Example
livePusher.stopCustomCapture();
Parameters:
Name Type Attributes Description
streamId string <optional>

流 id，可选参数，指定需要移除的自定义流。启用本地混流之后，如果添加了多路自定义流，可通过流 id 移除指定的自定义流，否则移除所有的自定义流。

(async) startPush(pushUrl) → {Promise.<void>}

开始推流，建立 WebRTC 连接，往腾讯云服务器推送音视频流。如果开启了本地混流功能，推送的则是混流处理之后的流数据。

Example
livePusher.startPush('webrtc://domain/AppName/StreamName?txSecret=xxx&txTime=xxx')
.then(() => {
  console.log('push stream is successful');
})
.catch((error) => {
  console.log(error.name + ': ' + error.message);
});
Parameters:
Name Type Description
pushUrl string

WebRTC 推流地址，请填写腾讯云的推流地址。推流地址的格式参考 拼装推流 URL ，只需要将 rtmp 推流地址前面的 rtmp:// 替换成 webrtc:// 即可。
Returns:

返回 Promise 对象。

Type
Promise.<void>

stopPush()

停止推送音视频流，关闭 WebRTC 连接。

Example
livePusher.stopPush();

isPushing() → {boolean}

查询当前是否正在推流中。

Example
if (livePusher.isPushing()) {
  console.log('stream is pushing');
}
Returns:

true - 正在推流，false - 未推流。

Type
boolean

getRenderView() → {HTMLVideoElement}

获取用于本地视频画面预览的 video 容器。

Example
const videoEl = livePusher.getRenderView();
if (videoEl) {
 videoEl.muted = true;
}
Returns:

用于本地采集预览的 video 元素，返回结果可能为 null。

Type
HTMLVideoElement

getMediaStream(streamId) → {MediaStream}

根据流 id 获取采集到的音视频流，用户可以放到 video 标签中进行播放。

Example
// stream id - xxxxxx
const mediaStream = livePusher.getMediaStream('xxxxxx');
const video = document.createElement('video');
video.srcObject = mediaStream;
Parameters:
Name Type Description
streamId string

流 id，由 startCamera() 、 startMicrophone() 、 startScreenCapture() 等接口调用成功之后返回。
Returns:

采集到的流对象，可以通过传给 video 标签的 srcObject 属性进行播放。

Type
MediaStream

getDeviceManager() → {TXDeviceManager}

获取设备管理对象。通过设备管理，可以进行查询设备列表，切换设备等操作。

Example
const deviceManager = livePusher.getDeviceManager();
Returns:

设备管理对象

Type
TXDeviceManager

getVideoEffectManager() → {TXVideoEffectManager}

获取视频效果管理对象。通过视频效果管理，可以进行画中画、镜像、滤镜、水印、文本等操作。

Example
const videoEffectManager = livePusher.getVideoEffectManager();
Returns:

视频效果管理对象

Type
TXVideoEffectManager

getAudioEffectManager() → {TXAudioEffectManager}

获取音频效果管理对象。通过音频效果管理，可以进行调整音量的操作。

Example
const audioEffectManager = livePusher.getAudioEffectManager();
Returns:

音频效果管理对象

Type
TXAudioEffectManager

setVideoMute(mute)

设置是否禁用视频流。如果开启了本地混流功能，禁用的是最终生成的视频流。

说明：

  1. 当前有视频流时，设置才会生效。
  2. 禁用之后每一帧都会用黑色像素填充，实际上仍在采集视频流。
  3. 建议直接使用 pauseVideo() 和 resumeVideo() 。
Example
livePusher.setVideoMute(true);
Parameters:
Name Type Description
mute boolean

true - 禁用，false - 启用。

setAudioMute(mute)

设置是否禁用音频流。如果开启了本地混流功能，禁用的是最终生成的音频流。

说明：

  1. 当前有音频流时，设置才会生效。
  2. 禁用之后是没有声音的，实际上仍在采集音频流。
  3. 建议直接使用 pauseAudio() 和 resumeAudio() 。
Example
livePusher.setAudioMute(true);
Parameters:
Name Type Description
mute boolean

true - 禁用，false - 启用。

pauseVideo()

禁用视频流。等同于 setVideoMute(true) 。

Example
livePusher.pauseVideo();

pauseAudio()

禁用音频流。等同于 setAudioMute(true) 。

Example
livePusher.pauseAudio();

resumeVideo()

恢复视频流。等同于 setVideoMute(false) 。

Example
livePusher.resumeVideo();

resumeAudio()

恢复音频流。等同于 setAudioMute(false) 。

Example
livePusher.resumeAudio();

setVideoContentHint(contentHint)

设置视频内容提示，用于提升在不同内容场景下的视频编码质量。

说明：

  1. 当前有视频流时，设置才会生效，请先采集视频流。
  2. 目前 Firefox 浏览器不支持该设置。
Example
livePusher.startScreenCapture().then(() => {
  livePusher.setVideoContentHint('detail');
});
Parameters:
Name Type Description
contentHint string

内容提示，参考 MediaStreamTrack.contentHint 。取值范围如下：

  • '' - 默认值，浏览器会自动评估视频内容，并选择合适的提示配置进行编码。
  • 'motion' - 表现为流畅度优先，用于视频内容为摄像头采集、电影、视频、游戏的情况。
  • 'detail' - 表现为清晰度优先，用于视频内容包含图片、文本混排的情况。在进行屏幕分享时，建议使用这个提示。
  • 'text' - 表现为清晰度优先，用于视频内容只包含大量文本的情况。

setObserver(observer)

设置推流事件回调通知。通过设置回调，可以监听推流的一些事件通知，包括推流状态、统计数据、警告和错误信息等。

说明：

目前部分回调事件通知，比如 onError、onWarning、onCaptureFirstAudioFrame、onCaptureFirstVideoFrame 也可以通过调用对应接口返回的 Promise 对象来获取。用户可以根据自己的使用习惯，自由选择获取相应事件通知的方式。

举个例子，startCamera().then() 等同于 onCaptureFirstVideoFrame() ，同样可以获取采集视频首帧成功的状态。 startCamera().catch() 等同于 onWarning() ，同样可以获取打开摄像头失败的错误。

Example
livePusher.setObserver({
  // warning message
  onWarning: function (code, message) {
    console.log(code, message);
  },
  // connection status
  onPushStatusUpdate: function (status, message) {
    console.log(status, message);
  },
  // WebRTC statistics data
  onStatisticsUpdate: function (data) {
    console.log('video fps is ' + data.video.framesPerSecond);
  }
});
Parameters:
Name Type Description
observer object

推流的回调目标对象。

Properties
Name Type Attributes Description
onError TXLivePusher~onError <optional>

推流错误通知。函数结构请参考 onError 。
onWarning TXLivePusher~onWarning <optional>

推流警告通知。函数结构请参考 onWarning 。
onCaptureFirstAudioFrame TXLivePusher~onCaptureFirstAudioFrame <optional>

首帧音频采集完成的回调通知。函数结构请参考 onCaptureFirstAudioFrame 。
onCaptureFirstVideoFrame TXLivePusher~onCaptureFirstVideoFrame <optional>

首帧视频采集完成的回调通知。函数结构请参考 onCaptureFirstVideoFrame 。
onPushStatusUpdate TXLivePusher~onPushStatusUpdate <optional>

推流连接状态回调通知。函数结构请参考 onPushStatusUpdate 。
onStatisticsUpdate TXLivePusher~onStatisticsUpdate <optional>

推流统计数据回调通知。函数结构请参考 onStatisticsUpdate 。

destroy()

离开⻚面或者退出时，清理 SDK 实例，避免可能会产生的内存泄露，调用前先执行 stop 相关的方法。

Example
livePusher.destroy();

Type Definitions

onError(code, message, extraInfo)

推流错误通知，推流出现错误时，会回调该通知。具体使用请参考 setObserver() 。

Parameters:
Name Type Description
code number

错误码，参考如下：

枚举值 数值 描述
TXLIVE_ERROR_WEBRTC_FAILED -1 WebRTC 接口调用失败
TXLIVE_ERROR_REQUEST_FAILED -2 请求服务器推流接口返回报错
message string

错误信息。
extraInfo object

扩展信息。

onWarning(code, message, extraInfo)

推流警告通知。具体使用请参考 setObserver() 。

说明：

  1. 打开摄像头、⻨克⻛、屏幕分享失败时返回的错误信息，可参考 getUserMedia 异常 和 getDisplayMedia 异常 。
  2. 摄像头、麦克风、屏幕分享异常中断时返回的扩展信息，会包含对应流的流 id 。
Parameters:
Name Type Description
code number

错误码，参考如下：

枚举值 数值 描述
TXLIVE_WARNING_CAMERA_START_FAILED -1001 打开摄像头失败
TXLIVE_WARNING_MICROPHONE_START_FAILED -1002 打开麦克风失败
TXLIVE_WARNING_SCREEN_CAPTURE_START_FAILED -1003 打开屏幕分享失败
TXLIVE_WARNING_VIRTUAL_CAMERA_START_FAILED -1004 打开本地媒体文件失败
TXLIVE_WARNING_CAMERA_INTERRUPTED -1005 摄像头被中断（设备被拔出或者权限被用户取消）
TXLIVE_WARNING_MICROPHONE_INTERRUPTED -1006 麦克风被中断（设备被拔出或者权限被用户取消）
TXLIVE_WARNING_SCREEN_CAPTURE_INTERRUPTED -1007 屏幕分享被中断（Chrome浏览器点击自带的停止共享按钮）
message string

错误信息。
extraInfo object

扩展信息。

onCaptureFirstAudioFrame()

首帧音频采集完成的回调通知。如果启用本地混流功能，则在最终混流生成音频流时进行回调通知。具体使用请参考 setObserver() 。

onCaptureFirstVideoFrame()

首帧视频采集完成的回调通知。如果启用本地混流功能，则在最终混流生成视频流时进行回调通知。具体使用请参考 setObserver() 。

onPushStatusUpdate(status, message, extraInfo)

推流连接状态回调通知。具体使用请参考 setObserver() 。

Parameters:
Name Type Description
status number

连接状态码，参考如下：

枚举值 数值 描述
TXLIVE_PUSH_STATUS_DISCONNECTED 0 与服务器断开连接
TXLIVE_PUSH_STATUS_CONNECTING 1 正在连接服务器
TXLIVE_PUSH_STATUS_CONNECTED 2 连接服务器成功
TXLIVE_PUSH_STATUS_RECONNECTING 3 重连服务器中
message string

连接状态信息。
extraInfo object

扩展信息。

onStatisticsUpdate(statistics)

推流统计数据回调通知，主要是 WebRTC 相关的统计数据。具体使用请参考 setObserver() 。

说明：

  1. 直播推流过程中，SDK 会以一秒一次的频率统计 WebRTC 相关的数据，然后调用该回调接口返回数据。
  2. 如果返回的字段数据是空（undefined）的话，说明当前浏览器获取不到对应的数据，目前只有 Chrome 浏览器可以拿到全部的数据。
Parameters:
Name Type Description
statistics object

推流统计数据。

Properties
Name Type Description
timestamp number

数据采样的时间，自 1970年1月1日(UTC) 起经过的毫秒数。
video object

视频流相关的数据。

Properties
Name Type Description
bitrate number

视频码率，单位：bit/s 。
framesPerSecond number

视频帧率。
frameWidth number

视频宽度。
frameHeight number

视频高度。
framesEncoded number

编码帧数。
framesSent number

发送帧数。
packetsSent number

发送包数。
nackCount number

NACK(Negative ACKnowledgement) 数。
firCount number

FIR(Full Intra Request)，关键帧重传请求数。
pliCount number

PLI(Picture Loss Indication)，视频帧丢失重传数。
frameEncodeAvgTime number

平均编码时间，单位：ms 。
packetSendDelay number

数据包发送之前本地缓存的平均时间，单位：ms 。
audio object

音频流相关的数据。

Properties
Name Type Description
bitrate number

音频码率，单位：bit/s 。
packetsSent number

发送包数。