云直播 Web 推流 SDK API-SDK 实践-文档中心-腾讯云

API 概览
TXLivePusher
腾讯云直播推流器，主要用于浏览器 Web 推流。通过浏览器采集用户的画面和声音，通过 WebRTC 将视频流和音频流传输推送到腾讯云直播服务端。
API
描述
﻿checkSupport﻿
静态函数，检查浏览器支持性。
﻿setRenderView﻿
设置本地视频画面的预览容器。
﻿setVideoQuality﻿
设置推流视频质量。
﻿setAudioQuality﻿
设置推流音频质量。
﻿setProperty﻿
调用高级 API 接口。
﻿startCamera﻿
打开摄像头设备。
﻿stopCamera﻿
关闭摄像头设备。
﻿startMicrophone﻿
打开⻨克⻛设备。
﻿stopMicrophone﻿
关闭⻨克⻛设备。
﻿startScreenCapture﻿
开启屏幕采集。
﻿stopScreenCapture﻿
关闭屏幕采集。
﻿startVirtualCamera﻿
开始采集本地媒体文件流。
﻿stopVirtualCamera﻿
停止采集本地媒体文件流。
﻿startCustomCapture﻿
使用用户自定义的音视频流。
﻿stopCustomCapture﻿
关闭用户自定义的音视频流。
﻿startPush﻿
开始推流。
﻿stopPush﻿
停止推流。
﻿isPushing﻿
查询当前是否正在推流中。
﻿getMediaStream﻿
根据流 ID 获取采集到的音视频流。
﻿getDeviceManager﻿
获取设备管理对象。
﻿getVideoEffectManager﻿
获取视频效果管理对象。
﻿getAudioEffectManager﻿
获取音频效果管理对象。
﻿setVideoMute﻿
设置是否禁用视频流。
﻿setAudioMute﻿
设置是否禁用音频流。
﻿pauseVideo﻿
禁用视频流。
﻿pauseAudio﻿
禁用音频流。
﻿resumeVideo﻿
恢复视频流。
﻿resumeAudio﻿
恢复音频流。
﻿setVideoContentHint﻿
设置视频内容提示，用于提升在不同内容场景下的视频编码质量。
﻿setObserver﻿
设置推流事件回调通知。
﻿destroy﻿
离开⻚面或者退出时，清理 SDK 实例。
TXDeviceManager
设备管理接口，主要用于管理摄像头、⻨克⻛设备，进行设备的获取和切换操作。
API
描述
﻿getDevicesList﻿
获取设备列表。
﻿getCurrentDevice﻿
获取当前流的设备信息。
﻿switchDevice﻿
切换当前正在使用的设备。
﻿switchCamera﻿
切换摄像头设备。
﻿switchMicrophone﻿
切换⻨克⻛设备。
TXAudioEffectManager
音频效果管理接口，主要用于调整音量的操作。
API
描述
﻿setVolume﻿
设置音频流的音量大小。
TXVideoEffectManager
视频效果管理接口，主要用于设置画中画、镜像、滤镜、水印、文本等操作。
API
描述
﻿enableMixing﻿
开启本地视频画面混流功能。
﻿setMixingConfig﻿
设置混流参数。
﻿getMixingConfig﻿
获取最终采用的混流参数。
﻿setLayout﻿
设置视频流的画中画布局参数。
﻿getLayout﻿
获取指定流的画中画布局参数。
﻿setMirror﻿
设置视频流的镜像效果。
﻿setNormalFilter﻿
设置视频流的普通滤镜效果。
﻿setWatermark﻿
设置水印。
﻿setText﻿
设置文本。
TXLivePusher
腾讯云直播推流器，主要用于浏览器 Web 推流。通过浏览器采集用户的画面和声音，通过 WebRTC 将视频流和音频流传输推送到腾讯云服务端。如果需要开启本地混流功能，调用 TXVideoEffectManager 方法 enableMixing() 来启用。
请先创建实例对象，用于后续所有操作。
const livePusher = new TXLivePusher();
checkSupport
静态函数，检查浏览器支持性。
static checkSupport(): Promise<TXSupportResult>;
返回：
返回 Promise 对象，其中检查结果数据结构请参考 TXSupportResult 。
setRenderView
设置本地视频画面的预览容器，需提供一个 div 节点，本地采集的视频会在容器里渲染。如果开启了本地混流功能，容器里面会渲染混流处理之后的音视频。
setRenderView(container: string | HTMLDivElement): void;
参数：
字段
类型
说明
container
string | HTMLDivElement
容器的 ID 或者 dom 节点。
setVideoQuality
设置推流视频质量，SDK 已经内置了视频质量模板，直接通过预定义的模板来设置推流视频质量。
setVideoQuality(quality: string): void;
参数：
字段
类型
说明
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
说明：
1. 由于设备和浏览器的限制，视频分辨率不一定能够完全匹配，在这种情况下，浏览器会自动调整分辨率使其接近对应的分辨率。
2. 如果视频质量参数（分辨率、帧率和码率）不符合您的要求，您可以通过 setProperty() 单独设置自定义的值。
3. 此处视频分辨率主要表示本地采集的视频分辨率，推流时分辨率可能会低于采集的分辨率，浏览器会根据网络带宽等情况自动调整推流分辨率。
4. 默认使用 720p ，即 setVideoQuality('720p') 。
setAudioQuality
设置推流音频质量，SDK 已经内置了音频质量模板，直接通过预定义的模板来设置推流音频质量。
setAudioQuality(quality: string): void;
参数：
字段
类型
说明
quality
string
预定义的音频质量模板名称。
内置的音频质量模板如下所示：
模板名
采样率
码率（kbps）
standard
48000
40
high
48000
128
说明：
1. 如果音频质量参数（采样率和码率）不符合您的要求，您可以通过 setProperty() 单独设置自定义的值。
2. 默认使用 standard ，即 setAudioQuality('standard') 。
setProperty
主要用于调用一些高级功能，比如设置视频的分辨率、帧率和码率，设置音频的采样率和码率等。
setProperty(key: string, value: any): void;
参数：
字段
类型
说明
key
string
高级 API 对应的 key。
value
*
调用 key 所对应的高级 API 时需要的参数。
目前支持以下高级功能：
Key
Value
描述
示例
setVideoResolution
{ width: number; height:number; }
设置视频的分辨率
setProperty('setVideoResolution', { width: 1920, height: 1080 })
setVideoFPS
number
设置视频的帧率
setProperty('setVideoFPS', 25)
setVideoBitrate
number
设置视频的码率
setProperty('setVideoBitrate', 2000)
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)
enableAudioAEC
boolean
启用回声消除
setProperty('enableAudioAEC', true)
enableAudioAGC
boolean
启用自动增益
setProperty('enableAudioAGC', true)
enableAudioANS
boolean
启用噪声抑制
setProperty('enableAudioANS', true)
enableLog
boolean
是否在控制台打印日志
setProperty('enableLog', true)
说明：
1. 回声消除、自动增益和噪声抑制默认全部启用，最终是否起效依赖于设备和浏览器。这三个功能建议要么全部启用，要么全部禁用。
2. 请在采集流和推流之前进行设置。
startCamera
打开摄像头设备。需要用户授权允许浏览器访问摄像头，授权失败或者访问设备失败，返回的 Promise 对象会抛出错误。
startCamera(deviceId?: string): Promise<string>;
参数：
字段
类型
说明
deviceId
string
摄像头设备 ID，可选参数，指定打开的摄像头设备。设备 ID 可通过 TXDeviceManager 中的方法 getDevicesList() 获取。在移动设备上，可以通过传入 'user' 和 'environment' 来指定打开前置和后置摄像头。
返回：
返回 Promise 对象，成功时返回流 ID 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。
说明：
1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
2. 打开摄像头失败时返回的错误信息，可参考 getUserMedia 异常 。
stopCamera
关闭摄像头设备。
stopCamera(streamId?: string): void;
参数：
字段
类型
说明
streamId
string
流 ID，可选参数，指定需要关闭的摄像头流。启用本地混流之后，如果采集了多路摄像头流，可通过流 ID 关闭指定的摄像头流，否则关闭所有的摄像头流。
startMicrophone
打开⻨克⻛设备。需要用户授权允许浏览器访问⻨克⻛，授权失败或者访问设备失败，返回的 Promise 对象会抛出错误。
startMicrophone(deviceId?: string): Promise<string>;
参数：
字段
类型
说明
deviceId
string
麦克风设备 ID，可选参数，指定打开的麦克风设备。设备 ID 可通过 TXDeviceManager 中的方法 getDevicesList() 获取。
返回：
返回 Promise 对象，成功时返回流 ID 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。
说明：
1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
2. 打开麦克风失败时返回的错误信息，可参考 getUserMedia 异常 。
3. 如果出现回声现象，可以将本地用于播放预览的视频元素 video 静音，避免回声现象的出现。
livePusher.videoView.muted = true;
stopMicrophone
关闭⻨克⻛设备。
stopMicrophone(streamId?: string): void;
参数：
字段
类型
说明
streamId
string
流 ID，可选参数，指定需要关闭的麦克风流。启用本地混流之后，如果采集了多路麦克风流，可通过流 ID 关闭指定的麦克风流，否则关闭所有的麦克风流。
startScreenCapture
开启屏幕采集。需要用户授权允许浏览器访问屏幕，授权失败或者访问屏幕失败，返回的 Promise 对象会抛出错误。
startScreenCapture(audio?: boolean): Promise<string>;
参数：
字段
类型
说明
audio
boolean
是否采集系统声音或者标签⻚声音，true - 采集声音，false - 不采集声音，默认 false。
返回：
返回 Promise 对象，成功时返回流 ID 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。
说明：
1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
2. 打开屏幕采集失败时返回的错误信息，可参考 getDisplayMedia 异常 。
3. 目前只有 Chrome 74+ 和 Edge 79+ 支持采集声音，在 windows 系统可以采集整个系统的声音，在 Linux 和 Mac 上面只能采集标签⻚的声音。
4. 如果设置了 audio 为 true，在浏览器的屏幕分享弹窗中还需要确保弹窗最下面的采集声音选项是勾选状态，否则也不会采集声音。如果设置了 audio 为 false，浏览器的屏幕分享弹窗中不会出现采集声音的选项。
stopScreenCapture
关闭屏幕采集。
stopScreenCapture(streamId?: string): void;
参数：
字段
类型
说明
streamId
string
流 ID，可选参数，指定需要关闭的屏幕分享流。启用本地混流之后，如果采集了多路屏幕分享流，可通过流 ID 关闭指定的屏幕分享流，否则关闭所有的屏幕分享流。
startVirtualCamera
开始采集本地媒体文件流。目前支持的文件格式有视频 mp4，音频 mp3 和图片 jpg、png、bmp。
startVirtualCamera(file: File): Promise<string>;
参数：
字段
类型
说明
file
File
本地媒体文件，必传。文件格式必须是以下几种：mp4、mp3、jpg、png、bmp。
返回：
返回 Promise 对象，成功时返回流 ID 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。
说明：
1. 本地文件支持视频、音频和图片。视频文件采集视频流和音频流，音频文件只采集音频流，图片文件只采集视频流。
2. 必须手动传入 file 对象，需要提前使用 <input type="file"> 引导用户选择本地文件。
stopVirtualCamera
停止采集本地媒体文件流。
stopVirtualCamera(streamId?: string): void;
参数：
字段
类型
说明
streamId
string
流 ID，可选参数，指定需要关闭的媒体文件流。启用本地混流之后，如果采集了多路媒体文件流，可通过流 ID 关闭指定的媒体文件流，否则关闭所有的媒体文件流。
startCustomCapture
使用用户自定义的音视频流。将用户自己采集的流用于本地混流和推送。
startCustomCapture(stream: MediaStream): Promise<string>;
参数：
字段
类型
说明
stream
MediaStream
用户自定义的流。
返回：
返回 Promise 对象，成功时返回流 ID 作为流在 SDK 内部的唯一标识，失败时抛出对应的错误信息。
stopCustomCapture
关闭自定义的音视频流，仅移除自定义流，不会停止自定义流。
stopCustomCapture(streamId?: string): void;
参数：
字段
类型
说明
streamId
string
流 ID，可选参数，指定需要移除的自定义流。启用本地混流之后，如果添加了多路自定义流，可通过流 ID 移除指定的自定义流，否则移除所有的自定义流。
startPush
开始推流，建立 WebRTC 连接，往腾讯云服务器推送音视频流。如果开启了本地混流功能，推送的则是混流处理之后的流数据。
startPush(pushUrl: string): Promise<void>;
参数：
字段
类型
说明
pushUrl
string
WebRTC 推流地址。
返回：
返回 Promise 对象。
说明：
推流地址的格式参考 拼装推流 URL 。
stopPush
停止推送音视频流，关闭 WebRTC 连接。
stopPush(): void;
isPushing
查询当前是否正在推流中。
isPushing(): boolean;
返回：
布尔值，true - 正在推流，false - 未推流。
getMediaStream
根据流 ID 获取采集到的音视频流。
getMediaStream(streamId: string): MediaStream;
参数：
字段
类型
说明
streamId
string
流 ID，由 startCamera() 、 startMicrophone() 、 startScreenCapture() 等接口调用成功之后返回。
返回：
采集到的流对象，可以通过传给 video 标签的 srcObject 属性进行播放。
getDeviceManager
获取设备管理对象。通过设备管理，可以进行查询设备列表，切换设备等操作。
getDeviceManager(): TXDeviceManager;
返回：
设备管理对象，具体用法请参考 TXDeviceManager 。
getVideoEffectManager
获取视频效果管理对象。通过视频效果管理，可以进行画中画、镜像、滤镜、水印、文本等操作。
getVideoEffectManager(): TXVideoEffectManager;
返回：
视频效果管理对象，具体用法请参考 TXVideoEffectManager 。
getAudioEffectManager
获取音频效果管理对象。通过音频效果管理，可以进行调整音量的操作。
getAudioEffectManager(): TXAudioEffectManager;
返回：
音频效果管理对象，具体用法请参考 TXAudioEffectManager 。
setVideoMute
设置是否禁用视频流。如果开启了本地混流功能，禁用的是最终生成的视频流。
setVideoMute(mute: boolean): void;
参数：
字段
类型
说明
mute
boolean
true - 禁用，false - 启用。
说明：
1. 当前有视频流时，设置才会生效。
2. 禁用之后每一帧都会用黑色像素填充，实际上仍在采集视频流。
3. 建议直接使用 pauseVideo() 和 resumeVideo() 。
setAudioMute
设置是否禁用音频流。如果开启了本地混流功能，禁用的是最终生成的音频流。
setAudioMute(mute: boolean): void;
参数：
字段
类型
说明
mute
boolean
true - 禁用，false - 启用。
说明：
1. 当前有音频流时，设置才会生效。
2. 禁用之后是没有声音的，实际上仍在采集音频流。
3. 建议直接使用 pauseAudio() 和 resumeAudio() 。
pauseVideo
禁用视频流。等同于 setVideoMute(true) 。
pauseVideo(): void;
pauseAudio
禁用音频流。等同于 setAudioMute(true) 。
pauseAudio(): void;
resumeVideo
恢复视频流。等同于 setVideoMute(false) 。
resumeVideo(): void;
resumeAudio
恢复音频流。等同于 setAudioMute(false) 。
resumeAudio(): void;
setVideoContentHint
设置视频内容提示，用于提升在不同内容场景下的视频编码质量。
setVideoContentHint(contentHint: string): void;
参数：
字段
类型
说明
contentHint
string
内容提示，参考 MediaStreamTrack.contentHint 。
内容提示取值范围如下：
取值
说明
''
默认值，浏览器会自动评估视频内容，并选择合适的提示配置进行编码。
'motion'
表现为流畅度优先，用于视频内容为摄像头采集、电影、视频、游戏的情况。
'detail'
表现为清晰度优先，用于视频内容包含图片、文本混排的情况。在进行屏幕分享时，建议使用这个提示。
'text'
表现为清晰度优先，用于视频内容只包含大量文本的情况。
说明：
当前有视频流时，设置才会生效。
﻿
setObserver
设置推流事件回调通知。通过设置回调，可以监听推流的一些事件通知，包括推流状态、统计数据、警告和错误信息等。
setObserver(observer: TXLivePusherObserver): void;
参数：
字段
类型
说明
observer
﻿TXLivePusherObserver﻿
推流的回调目标对象。
说明：
目前部分回调事件通知，比如 onError、onWarning、onCaptureFirstAudioFrame、onCaptureFirstVideoFrame 也可以通过调用对应接口返回的 Promise 对象来获取。用户可以根据自己的使用习惯，自由选择获取相应事件通知的方式。例如：
startCamera().then() 等同于 onCaptureFirstVideoFrame() ，同样可以获取采集视频首帧成功的状态。
startCamera().catch() 等同于 onWarning() ，同样可以获取打开摄像头失败的错误。
﻿
destroy
离开⻚面或者退出时，清理 SDK 实例，避免可能会产生的内存泄露，调用前先执行 stop 相关的方法。
destroy(): void;
﻿
TXDeviceManager
设备管理接口。主要用于管理摄像头、⻨克⻛设备。如果开启了本地混流功能，需要传入对应的流 ID 进行操作。
﻿
通过 TXLivePusher 方法 getDeviceManager() 来获取对象实例。
const deviceManager = livePusher.getDeviceManager();
﻿
getDevicesList
获取设备列表。
getDevicesList(type?: string): Promise<TXMediaDeviceInfo[]>;
参数：
字段
类型
说明
type
string
取值 video 或者 audio，可选参数。不传返回所有设备列表，传 video 返回摄像头设备列表，传 audio 返回⻨克⻛设备列表。
返回：
返回 Promise 对象，其中设备信息结构请参考 TXMediaDeviceInfo 。
说明：
1. 该接口不支持在 http 协议下使用，请使用 https 协议部署您的网站。
2. 浏览器出于安全的考虑，在用户未授权摄像头或⻨克⻛访问权限前，deviceId 及 deviceName 字段可能都是空的。因此建议在用户授权访问后，再调用该接口获取设备详情。
getCurrentDevice
获取当前流的设备信息。如果启用了本地混流，必须指定流 ID。
getCurrentDevice(type: string, streamId?: string): Promise<TXMediaDeviceInfo>;
参数：
字段
类型
说明
type
string
设备类型：video - 摄像头设备，audio - ⻨克⻛设备。
streamId
string
流 ID，指定要获取设备信息的流，启用本地混流后必须传，对应的流必须是摄像头或者麦克风设备采集的流。
返回：
返回 Promise 对象，其中设备信息结构请参考 TXMediaDeviceInfo 。
switchDevice
切换当前正在使用的设备。如果启用了本地混流，必须指定流 ID。
switchDevice(type: string, deviceId: string, streamId?: string): Promise<void>;
参数：
字段
类型
说明
type
string
设备类型：video - 摄像头设备，audio - ⻨克⻛设备。
deviceId
string
设备 ID，可以通过调用 getDevicesList() 获取设备 ID。
streamId
string
流 ID，指定要切换设备的流，启用本地混流后必须传，对应的流必须是摄像头或者麦克风设备采集的流。
返回：
返回 Promise 对象。
说明：
1. 该方法仅适用于从摄像头和⻨克⻛采集音视频时调用，其他采集方式采集的流不支持调用该接口。
2. 如果还没开始推流，则只更新本地流；如果已经开始推流，同步更新推到服务器的音视频流。
3. 切换流的设备时，对应流的 ID 不会发生变化。
4. 指定流 ID 时，对应流的类型必须和 type 匹配，比如 type 是 video，对应的流必须是摄像头采集的流。
5. 建议直接使用 switchCamera() 和 switchMicrophone() 。
switchCamera
切换摄像头设备。等同于 switchDevice('video', deviceId, streamId) 。
switchCamera(deviceId: string, streamId?: string): Promise<void>;
参数：
字段
类型
说明
deviceId
string
设备 ID，可以通过调用 getDevicesList() 获取设备 ID。在移动设备上，可以通过传入 'user' 和 'environment' 来切换前置和后置摄像头。
streamId
string
流 ID，指定要切换摄像头设备的流，启用本地混流后必须传，对应的流必须是摄像头设备采集的流。
返回：
返回 Promise 对象。
switchMicrophone
切换⻨克⻛设备。等同于 switchDevice('audio', deviceId, streamId) 。
switchMicrophone(deviceId: string, streamId?: string): Promise<void>;
参数：
字段
类型
说明
deviceId
string
设备 ID ，可以通过调用 getDevicesList() 获取设备 ID 。
streamId
string
流 ID，指定要切换麦克风设备的流，启用本地混流后必须传，对应的流必须是麦克风设备采集的流。
返回：
返回 Promise 对象。
TXAudioEffectManager
音频效果管理接口。主要用于调整音量的操作。如果开启了本地混流功能，需要传入对应的流 ID 进行操作。
通过 TXLivePusher 方法 getAudioEffectManager() 来获取对象实例。
const audioEffectManager = livePusher.getAudioEffectManager();
setVolume
设置音频流的音量大小。如果启用了本地混流，必须指定流 ID。
setVolume(volume: number, streamId?: string): void;
参数：
字段
类型
说明
volume
number
音量大小，取值范围为 0 - 100，默认值是 100。
streamId
string
流 ID，指定要设置的流，启用本地混流后必须传。
说明：
如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 设置超过 100，但超过 100 的 volume 会有爆音的⻛险，请谨慎操作。
TXVideoEffectManager
视频效果管理接口。主要用于设置画中画、镜像、滤镜、水印、文本等操作。使用前需要先调用接口 enableMixing() 启用功能。
通过 TXLivePusher 方法 getVideoEffectManager() 来获取对象实例。
const videoEffectManager = livePusher.getVideoEffectManager();
enableMixing
开启本地视频画面混流功能。
enableMixing(enabled: boolean): void;
参数：
字段
类型
说明
enabled
boolean
是否开启本地混流功能，默认关闭。
说明：
1. 启用本地混流功能之前，预览和推送的流都是原始采集的流，启用之后，预览和推送的流都是经过浏览器本地混流处理之后的流，会有一定的浏览器性能开销。
2. 在调用 TXVideoEffectManager 其他方法前必须先调用该接口启用本地混流功能。
3. 没启用本地混流功能时，只能采集一路视频流和一路音频流。
4. 启用本地混流功能成功后，可以采集多路流，比如执行两个 startCamera 采集两个不同的摄像头画面，或者先执行 startCamera 采集摄像头画面，再执行 startScreenCapture 采集屏幕画面。采集的多路流的画面和声音都会出现在最终的混流输出结果中。
setMixingConfig
设置混流参数。不调用该接口进行设置时，默认混流参数直接使用 TXLivePusher 中方法 setVideoQuality() 和 setProperty() 设置之后的结果。
setMixingConfig(config: TXMixingConfig): void;
参数：
字段
类型
说明
config
﻿TXMixingConfig﻿
混流参数配置。
getMixingConfig
获取最终采用的混流参数，优先使用 setMixingConfig() 设置的结果，其次使用 TXLivePusher 中方法 setVideoQuality() 和 setProperty() 设置之后的结果。
getMixingConfig(): TXMixingConfig;
返回：
混流参数配置，数据结构请参考 TXMixingConfig 。
setLayout
设置视频流的画中画布局参数。
setLayout(config: TXLayoutConfig | TXLayoutConfig[]): void;
参数：
字段
类型
说明
config
﻿TXLayoutConfig | TXLayoutConfig[]
画中画布局配置，支持传对象或者对象数组。
说明：
1. 开启本地混流之后，所有采集的流都会自动添加到最终输出的视频流当中，默认的布局参数是保证视频流画面紧贴左上角原点出现。
2. 配置参数可以传对象数组，批量设置多个流的画中画布局效果，也可以只传对象单独设置指定的流。
3. 如果不想显示采集流的画面，只想保留声音，可以将布局宽度和高度设置为 0 。
getLayout
获取指定流的画中画布局参数。
getLayout(streamId: string): TXLayoutConfig | null;
参数：
字段
类型
说明
streamId
string
流 ID，指定要获取画中画布局参数的流。
返回：
返回指定流的画中画布局参数，数据结构请参考 TXLayoutConfig 。如果流不存在，返回 null 。
setMirror
设置视频流的镜像效果，包括左右镜像和上下镜像。
setMirror(config: TXMirrorConfig | TXMirrorConfig[]): void;
参数：
字段
类型
说明
config
﻿TXMirrorConfig | TXMirrorConfig[]
镜像效果配置，支持传对象或者对象数组。
说明：
配置参数可以传对象数组，批量设置多个流的镜像效果，也可以只传对象单独设置指定的流。
setNormalFilter
设置视频流的普通滤镜效果，包括对比度、亮度和饱和度。
setNormalFilter(config: TXNormalFilterConfig | TXNormalFilterConfig[]): void;
参数：
字段
类型
说明
config
﻿TXNormalFilterConfig | TXNormalFilterConfig[]
普通滤镜效果配置，支持传对象或者对象数组 。
说明：
配置参数可以传对象数组，批量设置多个流的普通滤镜效果，也可以只传对象单独设置指定的流。
setWatermark
设置水印，支持同时设置多个水印。
setWatermark(config: TXWatermarkConfig | TXWatermarkConfig[] | null): void;
参数：
字段
类型
说明
config
﻿TXWatermarkConfig | TXWatermarkConfig[] | null
水印配置参数，支持传对象、对象数组或者 null 。
说明：
1. 配置参数可以传对象数组，同时设置多个水印，也可以只传对象单独设置一个水印。
2. 配置参数传 null 或者空数组表示删除已有水印。
setText
设置文本，支持同时设置多个文本。
setText(config: TXTextConfig | TXTextConfig[] | null): void;
参数：
字段
类型
说明
config
﻿TXTextConfig | TXTextConfig[] | null
文本配置参数，支持传对象、对象数组或者 null 。
说明：
1. 配置参数可以传对象数组，同时设置多个文本，也可以只传对象单独设置一个文本。
2. 配置参数传 null 或者空数组表示删除已有文本。
类型定义
TXSupportResult
浏览器支持性检查结果。
数据结构：
字段
类型
说明
isWebRTCSupported
boolean
是否支持 WebRTC
isH264EncodeSupported
boolean
是否支持 H264 编码
isH264DecodeSupported
boolean
是否支持 H264 解码
isMediaDevicesSupported
boolean
是否支持获取媒体设备及媒体流
isScreenCaptureSupported
boolean
是否支持屏幕采集
isMediaFileSupported
boolean
是否支持获取本地媒体文件流
TXLivePusherObserver
推流的回调通知，回调包括推流器状态，统计信息，警告以及错误信息。
数据结构：
字段
类型
说明
onError
﻿onError﻿
推流错误通知。
onWarning
﻿onWarning﻿
推流警告通知。
onCaptureFirstAudioFrame
﻿onCaptureFirstAudioFrame﻿
首帧音频采集完成的回调通知。
onCaptureFirstVideoFrame
﻿onCaptureFirstVideoFrame﻿
首帧视频采集完成的回调通知。
onPushStatusUpdate
﻿onPushStatusUpdate﻿
推流连接状态回调通知。
onStatisticsUpdate
﻿onStatisticsUpdate﻿
推流统计数据回调通知。
onError
推流错误通知，推流出现错误时，会回调该通知。
onError(code: number, message: string, extraInfo: object): void;
参数：
字段
类型
说明
code
number
错误码。
message
string
错误信息。
extraInfo
object
扩展信息。
错误码参考如下：
枚举值
数值
描述
TXLIVE_ERROR_WEBRTC_FAILED
-1
WebRTC 接口调用失败。
TXLIVE_ERROR_REQUEST_FAILED
-2
请求服务器推流接口返回报错。
onWarning
推流警告通知。
onWarning(code: number, message: string, extraInfo: object): void;
参数：
字段
类型
说明
code
number
错误码。
message
string
错误信息。
extraInfo
object
扩展信息。
错误码参考如下：
枚举值
数值
描述
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 浏览器点击自带的停止共享按钮）。
说明：
1. 打开摄像头、⻨克⻛、屏幕分享失败时返回的错误信息，可参考 getUserMedia 异常 和 getDisplayMedia 异常 。
2. 摄像头、麦克风、屏幕分享异常中断时返回的扩展信息，会包含对应流的流 ID。
onCaptureFirstAudioFrame
首帧音频采集完成的回调通知。如果启用本地混流功能，则在最终混流生成音频流时进行回调通知。
onCaptureFirstAudioFrame(): void;
onCaptureFirstVideoFrame
首帧视频采集完成的回调通知。如果启用本地混流功能，则在最终混流生成视频流时进行回调通知。
onCaptureFirstVideoFrame(): void;
onPushStatusUpdate
推流连接状态回调通知。
onPushStatusUpdate(status: number, message: string, extraInfo: object): void;
参数：
字段
类型
说明
status
number
连接状态码。
message
string
连接状态信息。
extraInfo
object
扩展信息。
连接状态码参考如下：
枚举值
数值
描述
TXLIVE_PUSH_STATUS_DISCONNECTED
0
与服务器断开连接
TXLIVE_PUSH_STATUS_CONNECTING
1
正在连接服务器
TXLIVE_PUSH_STATUS_CONNECTED
2
连接服务器成功
TXLIVE_PUSH_STATUS_RECONNECTING
3
重连服务器中
onStatisticsUpdate
推流统计数据回调，主要是 WebRTC 相关的统计数据。
onStatisticsUpdate(statistics: object): void;
参数：
字段
类型
说明
statistics
object
推流统计数据。
statistics.timestamp
number
数据采样的时间，自 1970年1月1日（UTC）起经过的毫秒数。
statistics.video
object
视频流相关的数据。
statistics.video.bitrate
number
视频码率，单位：bit/s 。
statistics.video.framesPerSecond
number
视频帧率。
statistics.video.frameWidth
number
视频宽度。
statistics.video.frameHeight
number
视频高度。
statistics.video.framesEncoded
number
编码帧数。
statistics.video.framesSent
number
发送帧数。
statistics.video.packetsSent
number
发送包数。
statistics.video.nackCount
number
NACK（Negative ACKnowledgement）数。
statistics.video.firCount
number
FIR（Full Intra Request），关键帧重传请求数。
statistics.video.pliCount
number
PLI（Picture Loss Indication），视频帧丢失重传数。
statistics.video.frameEncodeAvgTime
number
平均编码时间，单位：ms 。
statistics.video.packetSendDelay
number
数据包发送之前本地缓存的平均时间，单位：ms 。
statistics.audio
object
音频流相关的数据。
statistics.audio.bitrate
number
音频码率，单位：bit/s 。
statistics.audio.packetsSent
number
发送包数。
说明：
1. 直播推流过程中，SDK 会以一秒一次的频率统计 WebRTC 相关的数据，然后调用该回调接口返回数据。
2. 如果返回的字段数据是空（undefined）的话，说明当前浏览器获取不到对应的数据，目前只有 Chrome 浏览器可以拿到全部的数据。
TXMediaDeviceInfo
设备信息。
数据结构：
字段
类型
说明
type
string
设备类型，video - 摄像头，audio - 麦克风。
deviceId
string
设备 ID。
deviceName
string
设备名称。
TXMixingConfig
混流参数配置。
数据结构：
字段
类型
说明
videoWidth
number
最终混流后的视频宽度。
videoHeight
number
最终混流后的视频高度。
videoFramerate
number
最终混流后的视频帧率。
backgroundColor
number
混合后画面的底色颜色，格式为十六进制数字，默认黑色，即 0x000000 。
TXLayoutConfig
画中画布局参数。
数据结构：
字段
类型
说明
streamId
string
流 ID，指定要设置的流。
x
number
布局 x 坐标。
y
number
布局 y 坐标。
width
number
布局宽度。
height
number
布局高度。
zOrder
number
布局层级。
说明：
1. 以左上⻆为原点 (0, 0)，元素的坐标属性描述元素中心点。例如一个分辨率为 100*100 的视频流紧贴原点完整出现在最终生成视频流中，那么它的 x 、 y 坐标都是50。
2. zOrder 值越大，视频流会出现在越上方，覆盖其他视频流画面。
TXMirrorConfig
镜像参数。
数据结构：
字段
类型
说明
streamId
string
流 ID，指定要设置的流。
mirrorType
number
镜像类型：0 - 无镜像效果，1 - 左右镜像，2 - 上下镜像，3 - 左右+上下镜像。
TXNormalFilterConfig
普通滤镜参数。
数据结构：
字段
类型
说明
streamId
string
流 ID，指定要设置的流。
contrast
number
对比度，取值范围 [-100, 100]，0 表示不处理。
brightness
number
亮度，取值范围 [-100, 100]，0 表示不处理。
saturation
number
饱和度，取值范围 [-100, 100]，0 表示不处理。
TXWatermarkConfig
水印配置参数。
数据结构：
字段
类型
说明
image
HTMLImageElement
水印图片对象。
x
number
水印 x 坐标。
y
number
水印 y 坐标。
width
number
水印宽度。
height
number
水印高度。
zOrder
number
水印层级。
说明：
1. 以左上⻆为原点 (0, 0)，元素的坐标属性描述元素中心点。例如一个分辨率为 100*100 的水印图片紧贴原点完整出现在最终生成视频流中，那么它的 x 、 y 坐标都是50。
2. zOrder 值越大，水印图片会出现在越上方，覆盖其他视频流画面。
TXTextConfig
文本配置参数。
数据结构：
字段
类型
说明
text
string
文本内容，不能为空字符串。
style
object
文本样式，可以参考对应的 css 样式设置。
style.font
string
字体名。
style.font_size
number
字体大小。
style.font_color
string
字体颜色，十六进制表示，例如 #000000 。
style.font_alpha
number
字体透明度，范围 [0, 100]，默认 100（不透明）。
style.bold
number
字体加粗，0 - 不加粗，1 - 加粗，默认 0 。
style.italic
number
字体倾斜，0 - 正常，1 - 斜体，默认 0 。
style.shadow_color
string
文字阴影颜色，十六进制表示，例如 #000000 。
style.shadow_alpha
number
文字阴影透明度，范围 [0, 100]，shadow_color 存在时有效，默认 100（不透明）。
style.stroke_color
string
文字描边颜色，十六进制表示，例如 #000000 。
style.stroke_thickness
number
文字描边粗细，默认 0，即没有描边。
style.background_color
string
背景颜色，十六进制表示，例如 #000000 。
style.background_alpha
number
背景透明度，范围 [0, 100]，background_color 存在时有效，默认 100（不透明）。
x
number
文本 x 坐标。
y
number
文本 y 坐标。
zOrder
number
文本层级。
说明：
1. 以左上⻆为原点 (0, 0)，元素的坐标属性描述元素中心点。假设文本的最终宽度是 100px，高度是 50px，如果文本要紧贴原点出现在最终生成视频流中的话，它的 x 坐标是 50， y 坐标是 25。
2. zOrder 值越大，文本会出现在越上方，覆盖其他视频流画面。
﻿

API	描述
checkSupport	静态函数，检查浏览器支持性。
setRenderView	设置本地视频画面的预览容器。
setVideoQuality	设置推流视频质量。
setAudioQuality	设置推流音频质量。
setProperty	调用高级 API 接口。
startCamera	打开摄像头设备。
stopCamera	关闭摄像头设备。
startMicrophone	打开⻨克⻛设备。
stopMicrophone	关闭⻨克⻛设备。
startScreenCapture	开启屏幕采集。
stopScreenCapture	关闭屏幕采集。
startVirtualCamera	开始采集本地媒体文件流。
stopVirtualCamera	停止采集本地媒体文件流。
startCustomCapture	使用用户自定义的音视频流。
stopCustomCapture	关闭用户自定义的音视频流。
startPush	开始推流。
stopPush	停止推流。
isPushing	查询当前是否正在推流中。
getMediaStream	根据流 ID 获取采集到的音视频流。
getDeviceManager	获取设备管理对象。
getVideoEffectManager	获取视频效果管理对象。
getAudioEffectManager	获取音频效果管理对象。
setVideoMute	设置是否禁用视频流。
setAudioMute	设置是否禁用音频流。
pauseVideo	禁用视频流。
pauseAudio	禁用音频流。
resumeVideo	恢复视频流。
resumeAudio	恢复音频流。
setVideoContentHint	设置视频内容提示，用于提升在不同内容场景下的视频编码质量。
setObserver	设置推流事件回调通知。
destroy	离开⻚面或者退出时，清理 SDK 实例。

API	描述
getDevicesList	获取设备列表。
getCurrentDevice	获取当前流的设备信息。
switchDevice	切换当前正在使用的设备。
switchCamera	切换摄像头设备。
switchMicrophone	切换⻨克⻛设备。

API	描述
enableMixing	开启本地视频画面混流功能。
setMixingConfig	设置混流参数。
getMixingConfig	获取最终采用的混流参数。
setLayout	设置视频流的画中画布局参数。
getLayout	获取指定流的画中画布局参数。
setMirror	设置视频流的镜像效果。
setNormalFilter	设置视频流的普通滤镜效果。
setWatermark	设置水印。
setText	设置文本。

字段	类型	说明
container	string \| HTMLDivElement	容器的 ID 或者 dom 节点。

模板名	分辨率（宽 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

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

Key	Value	描述	示例
setVideoResolution	{ width: number; height:number; }	设置视频的分辨率	setProperty('setVideoResolution', { width: 1920, height: 1080 })
setVideoFPS	number	设置视频的帧率	setProperty('setVideoFPS', 25)
setVideoBitrate	number	设置视频的码率	setProperty('setVideoBitrate', 2000)
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)
enableAudioAEC	boolean	启用回声消除	setProperty('enableAudioAEC', true)
enableAudioAGC	boolean	启用自动增益	setProperty('enableAudioAGC', true)
enableAudioANS	boolean	启用噪声抑制	setProperty('enableAudioANS', true)
enableLog	boolean	是否在控制台打印日志	setProperty('enableLog', true)

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

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

Web 推流 SDK API

本页目录：

API 概览

TXLivePusher

TXDeviceManager

TXAudioEffectManager

TXVideoEffectManager

TXLivePusher

checkSupport

setRenderView

setVideoQuality

setAudioQuality

setProperty

startCamera

stopCamera

startMicrophone

stopMicrophone

startScreenCapture

stopScreenCapture

startVirtualCamera

stopVirtualCamera

startCustomCapture

stopCustomCapture

startPush

stopPush

isPushing

getMediaStream

getDeviceManager

getVideoEffectManager

getAudioEffectManager

setVideoMute

setAudioMute

pauseVideo

pauseAudio

resumeVideo

resumeAudio

setVideoContentHint

setObserver

destroy

TXDeviceManager

getDevicesList

getCurrentDevice

switchDevice

switchCamera

switchMicrophone

TXAudioEffectManager

setVolume

TXVideoEffectManager

enableMixing

setMixingConfig

getMixingConfig

setLayout

getLayout

setMirror

setNormalFilter

setWatermark

setText

类型定义

TXSupportResult

TXLivePusherObserver

onError

onWarning

onCaptureFirstAudioFrame

onCaptureFirstVideoFrame

onPushStatusUpdate

onStatisticsUpdate

TXMediaDeviceInfo

TXMixingConfig

TXLayoutConfig

TXMirrorConfig

TXNormalFilterConfig

TXWatermarkConfig

TXTextConfig