Class

ZegoAudioEffectPlayer

音效播放器

详情

当需要播放简短的声音效果，比如鼓掌，欢呼声等时，可以使用音效播放器来实现。

方法

start

start(audioEffectID: string, options?: ZegoAudioEffectPlayOptions, onStart?: Function, onEnd?: Function): void

开始播放音效。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。
options	ZegoAudioEffectPlayOptions	音效播放的选项设置。
onStart	Function	音效播放开始的回调方法。
onEnd	Function	音效播放结束的回调方法。

详情

开始播放指定音效 ID 上的音效。音效 ID 可以是 [loadAudioEffect] 预加载好的音效或者通过提供参数 [option.path] 指定在线音频资源来加载和播放。

业务场景：当需要播放简短的声音效果，比如鼓掌，欢呼声等时，可以使用该接口实现。
调用时机：在 [createAudioEffectPlayer] 之后可调用。
相关接口：调用停止播放音效接口 [stop] 或者音效播放结束会触发 [onEnd] 回调。

支持版本：2.15.0 及以上
注意事项：

音效 ID 的音效没有播放结束即触发 [onEnd] 回调前，不能重复播放同一个音效 ID。
暂停音效接口 [pause] 不会结束音效播放，不会触发 [onEnd] 回调。

stop

stop(audioEffectID?: string): boolean

结束播放音效。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID , 不传参则停止所有可停止的音效。

详情

结束播放音效。

调用时机：指定的 [audioEffectID] 已经 [start] 。
相关接口：结束播放音效会触发开始播放音效接口 [start] 的 [onEnd] 回调方法。

支持版本：2.15.0 及以上
注意事项：无。

返回值

接口是否调用成功。

pause

pause(audioEffectID?: string): boolean

暂停播放音效。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID，不传参数则暂停所有可暂停的音效。

详情

暂停播放指定的音效 [audioEffectID]。

调用时机：指定的 [audioEffectID] 已经 [start]。
相关接口：开始播放音效接口 [start] 、恢复播放接口 [resume]。

支持版本：2.15.0 及以上

返回值

接口是否调用成功。

resume

resume(audioEffectID?: string): boolean

恢复播放音效。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID，不传参数则恢复所有可恢复的音效。

详情

恢复播放指定的音效 [audioEffectID]。

调用时机：指定的 [audioEffectID] 处于 [pause] 状态。
相关接口：开始播放音效接口 [start] 、恢复播放接口 [pause]。

支持版本：2.15.0 及以上

返回值

接口是否调用成功。

setVolume

setVolume(audioEffectID: string, volume: number): boolean

设置单个音效的播放音量，会同时设置本地播放音量和推流音量。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。
volume	number	音量值，取值范围：范围为 [0,100]，默认值：100。

详情

设置单个音效的播放音量，会同时设置本地播放音量和推流音量。

业务场景：调节播放音效的声音大小。
调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：2.15.0 及以上

返回值

接口是否调用成功。

getTotalDuration

getTotalDuration(audioEffectID: string): number

获取指定音效资源的总时长。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。

详情

获取指定音效资源的总长度，单位为毫秒。

调用时机：必须在加载资源完成后才能调用，否则返回值为 0。
相关接口：开始播放音效接口 [start] 、加载音效接口 [loadAudioEffect]。

支持版本：2.15.0 及以上

返回值

音频总时长，单位为毫秒。

getCurrentProgress

getCurrentProgress(audioEffectID: string): number

获取当前播放进度。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。

详情

获取指定音效的当前播放进度。单位为毫秒。

调用时机：音效需要已经通过 [start] 播放，否则返回值为 0。
相关接口：开始播放音效接口 [start] 。

支持版本：2.15.0 及以上

返回值

音效播放进度，单位为毫秒。

seekTo

seekTo(audioEffectID: string, time: number): boolean

设置播放进度。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。
time	number	指定的播放进度的时长。取值范围 [0, 音效总时长] 。

详情

设置指定音效的播放进度，单位为毫秒。

业务场景：加载一个拥有多个音效的音频资源，通过该接口来播放对应位置的音效。
调用时机：指定的 [audioEffectID] 已经 [start]，且还没有播完。
相关接口：开始播放音效接口 [start] 。

支持版本：2.15.0 及以上

返回值

标识是否调用成功。

ZegoCopyrightedMusic

版权音乐

详情

常用于 KTV 唱歌场景中，用户可通过创建版权音乐实例对象使用正版音乐相关功能。

方法

getInstance

static

getInstance

getInstance(engine: any): ZegoCopyrightedMusic

名称	类型	描述
engine	any	-

destroyInstance

destroyInstance(): void

initCopyrightedMusic

initCopyrightedMusic(config: ZegoCopyrightedMusicConfig): Promise<number>

初始化版权音乐模块。

参数

名称	类型	描述
config	ZegoCopyrightedMusicConfig	版权音乐配置。

详情

初始化版权音乐，以便后续使用版权音乐的功能。

调用时机：在引擎实例调用登录房间[loginRoom] 之后。

支持版本：2.24.5 及以上
注意事项：必须传入真实用户信息，否则无法获取歌曲资源进行播放。2. 初始化版权音乐时设置的用户 ID 和用户名需要和登录房间时设置的用户 ID 和用户名一致。

返回值

错误码，详情请参考常见错误码文档。 https://doc-zh.zego.im/zh/4381.html

on

on<K extends keyof ZegoCopyrightedMusicEvent >(event: K, callBack: ZegoCopyrightedMusicEvent[K]): boolean

注册回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoCopyrightedMusicEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 ZegoCopyrightedMusicEvent 查看。

业务场景：用于注册版权音乐功能相关的业务事件的回调处理。
调用时机：调用接口 createCopyrightedMusic 创建实例之后并且在调用接口 loginRoom 登录房间之前。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：3.0.0 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

sendExtendedRequest

sendExtendedRequest(command: string, params: any): Promise<ZegoCopyrightedMusicSendExtendedRequestResponse>

发送扩展功能请求。

参数

名称	类型	描述
command	string	请求命令，具体支持的命令请参考 https://doc-zh.zego.im/article/17419。
params	any	请求参数，每个请求命令具备对应的请求参数，请参考 https://doc-zh.zego.im/article/17419。

详情

发送扩展功能请求，访问版权歌曲库获取相关歌单、榜单歌曲信息。

业务场景：用于获取歌曲列表。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.24.5 及以上。

返回值

Promise 异步返回请求结果。

requestResource

  requestResource(config: ZegoCopyrightedMusicRequestConfig, type: ZegoCopyrightedMusicResourceType): Promise<ZegoCopyrightedMusicRequestResourceResponse>

获取音乐资源。

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	获取分享歌曲资源的配置。
type	ZegoCopyrightedMusicResourceType	版权音乐资源类型。0 为普通歌曲，1 为伴奏，2 为高潮片段。

详情

可以获取到歌曲的基本信息（时长、歌名、歌手等），以及最重要的可以用于本地播放的资源 id，还有相关的一些鉴权信息。

业务场景：获取版权歌曲，用于本地播放与分享。
相关接口：房间内某个用户调用此接口获取某音乐资源成功后，房间内其他用户可以调用[getSharedResource] 接口免费获取一次该音乐资源。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 之后。

支持版本：2.24.5 及以上。
注意事项：该接口会触发计费。每个资源有唯一的资源 ID。

返回值

Promise 异步返回请求结果。

getSharedResource

  getSharedResource(config: ZegoCopyrightedMusicRequestConfig, type: ZegoCopyrightedMusicResourceType): Promise<ZegoCopyrightedMusicRequestResourceResponse>

获取分享歌曲资源。

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	获取分享歌曲资源的配置。
type	ZegoCopyrightedMusicResourceType	版权音乐资源类型。0 为普通歌曲，1 为伴奏，2 为高潮片段。

详情

可以获取到歌曲的基本信息（时长、歌名、歌手等），以及最重要的可以用于本地播放的资源 id，还有相关的一些鉴权信息。

业务场景：获取版权歌曲，用于本地播放。
相关接口：房间内某个用户调用 [requestResource] 接口获取某音乐资源成功后，房间内其他用户可以调用此接口免费获取一次该音乐资源。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 之后。

支持版本：2.24.5 及以上。
注意事项：每个资源有唯一的资源 ID。

返回值

Promise 异步返回请求结果。

getLrcLyric

getLrcLyric(songID: string, vendorID: ZegoCopyrightedMusicVendorID): Promise<ZegoCopyrightedMusicGetLrcLyricResponse>

获取 lrc 格式歌词。

参数

名称	类型	描述
songID	string	歌曲或伴奏的 ID，一首歌的歌曲和伴奏共用同一个 ID。
vendorID	ZegoCopyrightedMusicVendorID	版权方。

详情

获取 lrc 格式歌词，支持逐行解析歌词。

业务场景：用于逐行显示歌词。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.24.5 及以上。

返回值

Promise 异步返回 lrc 格式歌词结果。

getKrcLyricByToken

getKrcLyricByToken(krcToken: string): Promise<ZegoCopyrightedMusicGetKrcLyricByTokenResponse>

获取 krc 格式歌词。

参数

名称	类型	描述
krcToken	string	通过获取音乐资源 [requestResource] 中获取的 krcToken。详情请参考歌词资源接口说明 https://doc-zh.zego.im/article/15563#2_2。

详情

获取 krc 格式歌词，支持逐字解析歌词。

业务场景：用于逐字显示歌词。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.24.5 及以上。

返回值

Promise 异步返回请求结果。

download

download(resourceID: string): Promise<ZegoCopyrightedMusicDownloadResponse>

下载歌曲或伴奏。

参数

名称	类型	描述
resourceID	string	歌曲或伴奏对应的资源 ID。

详情

下载歌曲或伴奏，下载成功后才能进行播放。

业务场景：获取版权歌曲或伴奏授权后，利用本接口加载对应的歌曲或伴奏资源。
调用时机：在调用获取资源接口 [requestResource] 或 [getSharedResource] 获取到 resourceID 成功之后。

支持版本：2.24.5 及以上。
注意事项：加载歌曲或伴奏资源受网络影响。

返回值

Promise 异步返回请求结果。

clearCache

clearCache(): void

清除歌曲缓存。

在使用本模块时，可能产生一些缓存文件，可以通过本接口进行清除。

业务场景：用于歌曲的缓存。
调用时机：在创建版权音乐 [createCopyrightedMusic] 之后。

支持版本：2.24.5 及以上。

startScore

startScore(params: ZegoStartScoreParams): Promise<number>

开始评分。

参数

名称	类型	描述
params	ZegoStartScoreParams	开始打分任务相关参数。

详情

开始评分接口，需要指定采集麦克风的媒体流、歌曲播放器、歌曲资源的 resourceID， SDK 根据这些信息进行开启打分任务。

业务场景：可以用于在视图上显示唱歌评分。
调用时机：在获取到 krc 逐字歌词并播放版权音乐的伴奏资源之后可调用。
相关接口： stopScore 结束打分接口，用于结束打分任务。每次只能进行一个打分任务，需要先结束当前任务才能进行下一个。

支持版本：2.26.0 及以上。
注意事项：播放伴奏的 H5 播放器必须开始播放才能调用该接口开启打分，否则可能出现打分跟歌曲进度对不齐的问题。

返回值

异步返回调用结果状态码，0 为调用正常。

stopScore

stopScore(resourceID: string): number

开始评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

结束当前评分，将停止 [OnCurrentPitchValueUpdate] 回调，但依然可以正常获取平均分或总分。

业务场景：正在评分时可调用此接口结束评分。
调用时机：正在评分时可调用。
相关接口：开始打分接口 startScore 。

支持版本：2.26.0 及以上。

返回值

状态码，0 表示调用正常。

pauseScore

pauseScore(resourceID: string): number

暂停评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

暂停正在进行的评分。

业务场景：演唱过程中需要休停时调用。
调用时机：调开始评分接口 startScore 之后。
相关接口：恢复打分接口 resumeScore 。

支持版本：2.26.0 及以上。

返回值

状态码，0 表示调用正常。

resumeScore

resumeScore(resourceID: string): number

恢复评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

恢复当前暂停的评分。

业务场景：演唱过程中需要休停后恢复继续演唱和评分。
调用时机：调开始评分接口 startScore 并暂停评分之后。
相关接口：暂停评分接口 pauseScore 。

支持版本：2.26.0 及以上。

返回值

状态码，0 表示调用正常。

resetScore

resetScore(resourceID: string): number

恢复评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

重置掉本次评分任务已经打的分。

业务场景：本次评分任务演唱了部分但想要重头开始唱并重新评分。
调用时机：调开始评分接口 startScore 之后。

支持版本：2.26.0 及以上。

返回值

状态码，0 表示调用正常。

getPreviousScore

getPreviousScore(resourceID: string): Promise<number>

获取上一句的评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

返回值是获取上一句的评分。

业务场景：可以用于在视图上显示每一句的评分。
调用时机：在播放版权伴奏或高潮片段，并开始打分后可调用。

支持版本：2.26.0 及以上。

返回值

返回值是获取上一句的评分。

getAverageScore

getAverageScore(resourceID: string): Promise<number>

获取平均评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

获取平均评分。

业务场景：可以用于在视图上显示平均评分。
调用时机：在播放版权伴奏或高潮片段，并开始打分后可调用。

支持版本：2.26.0 及以上。

返回值

返回平均评分。

getTotalScore

getTotalScore(resourceID: string): Promise<number>

获取总评分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

获取总评分。

业务场景：可以用于在视图上显示总评分。
调用时机：在播放版权伴奏或高潮片段，并开始打分后可调用。

支持版本：2.26.0 及以上。

返回值

返回分数。

getFullScore

getFullScore(resourceID: string): Promise<number>

获取满分。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

获取满分。

业务场景：可以用于在视图上显示满分。
调用时机：在播放版权伴奏或高潮片段，并开始打分后可调用。

支持版本：2.26.0 及以上。

返回值

返回分数。

getStandardPitch

getStandardPitch(resourceID: string): Promise<ZegoCopyrightedMusicGetStandardPitchResponse>

获取标准音高数据。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

获取标准音高数据。

业务场景：可以用于在视图上显示标准音高线。
调用时机：调 requestResource 请求到对应版权伴奏或高潮片段后可调用。

支持版本：2.26.0 及以上。
注意事项：只有伴奏或高潮片段资源才有音高线。

返回值

返回标准音高数据结果。

getCurrentPitch

getCurrentPitch(resourceID: string): Promise<number>

获取实时音高数据。

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。

详情

获取实时音高数据。

业务场景：可以用于在视图上显示音高浮标位置。
调用时机：在播放版权伴奏或高潮片段，并开始打分后可调用。

支持版本：2.26.0 及以上。

返回值

返回实时音高数值。

setScoringLevel

setScoringLevel(level: number): void

设置打分难度级别。

参数

名称	类型	描述
level	number	打分难度级别。level 取值范围 0 ~ 4。打分难度由 0 到 4 逐级递减。

详情

用户可以通过该接口设置评分难度级别。

默认值：未调用该函数时，打分难度级别默认是 4，难度最低的级别。
调用时机：调用初始化版权音乐成功后，调用 [startScore] 开始打分前。

支持版本：2.26.0 及以上。

ZegoExpressEngine

实时音视频引擎

详情

该类用于初始化 Express SDK 引擎实例。

属性

version

static version: string

SDK 版本号。

方法

setGeoFence

static

setGeoFence

setGeoFence(type: ZegoGeoFenceType, areaList: number[]): void

设置地理围栏。

参数

名称	类型	描述
type	ZegoGeoFenceType	地理围栏类型。详情描述：用于设置地理围栏类型。
areaList	number[]	地理围栏区域列表。详情描述：用于描述地理围栏范围。

详情

开发者需要使用地理围栏功能时，需要调用此函数来完成配置。

调用时机：必须在调用 new 之前设置才生效，否则会失败。

支持版本：2.26.0 及以上。
使用限制：如果需要使用地理围栏功能，请联系 ZEGO 技术支持。

setEngineOptions

static

setEngineOptions

setEngineOptions(options: any): void

设置引擎进阶配置。

参数

名称	类型	描述
options	any	引擎进阶配置。

详情

设置引擎进阶配置。

业务场景：需要对SDK引擎进行特殊的配置操作时使用，详情可咨询 ZEGO 技术支持。
调用时机：在调用 new 创建引擎之前调用。

支持版本：2.26.0

use

static

use

use(module: any): void

引入模块，可以通过该接口按需引入其他模块。

参数

名称	类型	描述
module	any	功能模块。

详情

可以通过该接口来按需引入其他功能模块，如背景虚化、AI 降噪等功能模块。该方法是静态方法。

调用时机：初始化 ZegoExpressEngine 实例后。

支持版本：2.10.0 及以上。

presetLogConfig

static

presetLogConfig

presetLogConfig(config: ZegoLogConfig): boolean

预设日志配置

参数

名称	类型	描述
config	ZegoLogConfig	日志相关高级配置

详情

配置客户端打印日志级别和远端日志上传级别，日志是定位问题的重要手段。

业务场景：在多数场景下，客户不用调用该接口，使用默认配置即可。
默认值：本地日志和上传级别均为 info。
调用时机：在初始化之前。
相关回调：无
相关接口：跟 setLogConfig 的区别是可以在初始化实例之前调用。

支持版本：3.7.0
使用限制：无，但建议整个生命周期内只调用一次。
注意事项：除非有明确的特殊需求，否则请勿调用该接口更改默认配置。

返回值

调用是否成功; 失败情况: 输入参数格式有误

setCloudProxyConfig

static

setCloudProxyConfig

setCloudProxyConfig(proxyList: ZegoProxyInfo[], token: string, enable: boolean): void

设置云代理配置。

参数

名称	类型	描述
proxyList	ZegoProxyInfo[]	代理服务器信息列表。
token	string	鉴权信息。
enable	boolean	是否开启代理。

详情

设置云代理配置。

业务场景：处于如医院、政府、公司内部等有内网等限制性的网络环境下时，希望使用公有云 RTC 或 L3 服务。
调用时机：在初始化实例之前调用。

支持版本：3.1.0
使用限制：该接口在初始化实例后不可再调用修改配置，避免产生非预期的错误。

setLocalProxyConfig

static

setLocalProxyConfig

setLocalProxyConfig(proxyConfig: ZegoLocalProxyConfig, enable: boolean): void

设置本地代理配置。

参数

名称	类型	描述
proxyConfig	ZegoLocalProxyConfig	代理服务器的域名和路径配置信息。
enable	boolean	是否开启代理。

详情

设置本地代理配置。

业务场景：处于如医院、政府、公司等内部网络的防火墙限制不允许访问外网，只允许通过自己的代理服务器进行访问外网。
调用时机：在初始化实例之前调用。

支持版本：3.2.0 及以上
使用限制：1. 该接口在初始化实例后不可再调用修改配置，避免产生非预期的错误。2. 不能和 setCloudProxyConfig 同时使用。

createStreamCompositor

createStreamCompositor(): void

创建导播台

创建导播台实例对象，用于将多个媒体流合成一个。

业务场景：当需要将本地用户的多路视频流以及图片合为一路视频流，比如在线教育、远程会议、直播等场景，可以使用导播台来实现。

支持版本：3.0.0 及以上
注意事项：

每个导播台对象相对应只能输出一个混合流。
暂不支持移动端。

uploadLog

uploadLog(): Promise<{ errorCode: number; extendedData: string }>

上传离线日志

读取本地日志并上传。（3.11.0 以前版本需要联系 ZEGO 技术支持开启日志本地存储功能才能使用。）

业务场景：用户出现问题时，可点击上传 SDK 保存在浏览器的离线日志到 ZEGO 后台，以方便 ZEGO 技术人员帮忙协助排查用户问题。
调用时机：登录房间之后。
相关回调：无。
相关接口：无。

支持版本：2.26.0 及以上。
使用限制：需使用 token 04 版本的 token 登陆房间。
注意事项：无。

"errorCode" 是返回的错误码，为 0 表示上传成功，为 1103000 表示上传失败；"extendedData" 是错误码信息的描述。

setSEIConfig

setSEIConfig(config: ZegoSEIConfig): void

设置 SEI 相关配置信息

参数

名称	类型	描述
config	ZegoSEIConfig	SEI 功能相关配置。

详情

设置 SEI 额外的配置信息。

业务场景：开启 SEI 功能时若需要配置。
调用时机：初始化后。
相关回调：无。

支持版本：2.16.0 及以上。
注意事项：无。

setRoomScenario

setRoomScenario(scenario: ZegoScenario): boolean

设置房间场景

参数

名称	类型	描述
scenario	ZegoScenario	场景值

详情

开发者可设置房间的使用场景，SDK 会针对不同的场景采取不同的优化策略，以便获取更优的效果；此函数的作用与初始化引擎实例 [options] 配置中的 [scenario] 参数完全一致。

业务场景：此函数适用于多种音视频业务场景的设置修改，例如有 1v1 音视频通话场景和秀场直播场景；通过此函数可以实现在同一个引擎实例的前提下切换场景。
默认值：无
调用时机/通知时机：必须在调用 [loginRoom] 之前设置，生效于后面调用的 [createStream]或者[createZegoStream]相关采集的api ，对于已经创建生成的流不生效。

支持版本：2.21.0及以上。
使用限制：一旦登录了房间就不再允许修改房间场景，若需要修改场景需要先退出房间，若登录了多个房间则需要退出所有房间后才能修改。
注意事项：同一个房间内的用户建议使用同一种房间场景以获得最佳效果。设置场景会影响音视频码率、帧率、分辨率、编码类型、3A、耳返等音视频配置，若开发者有特殊需求可以在设置房间场景后再调用其他各种 API 来设置上述配置。调用此函数将覆盖 [new ZegoExpressEngine] 时指定的场景或上一次调用此函数设置的场景。

返回值

true 为设置成功，false 为设置失败。

setEngineConfig

setEngineConfig(config: any): void

设置引擎进阶配置。

参数

名称	类型	描述
config	any	引擎进阶配置。

详情

设置引擎进阶配置。

业务场景：需要对SDK引擎进行特殊的配置操作时使用，详情可咨询 ZEGO 技术支持。

支持版本：2.21.0 及以上。

destroyEngine

destroyEngine(): void

销毁引擎实例。

业务场景：不再需要使用实时音视频功能时。
调用时机：同一个引擎实例最后一个调用的接口。

支持版本：2.25.1
注意事项：销毁引擎后应及时将实例化对象置空，并不应再调用引擎对象的其他接口，否则可能出现报错。

setTurnServer

setTurnServer(turnServers: ZegoTurnServer[]): void

用于代理的 turn 服务器配置。

参数

名称	类型	描述
turnServers	ZegoTurnServer[]	代理服务器的域名和路径配置信息。

详情

设置用于代理的 turn 服务器配置。

调用时机：在发起推流或拉流之前调用。

支持版本：3.2.0 及以上

callExperimentalAPI

callExperimentalAPI(params: Object): Promise<any>

ZEGO 通过此 API 提供 RTC 业务中的部分技术预览或特别定制功能，需要获取功能的使用或详情其详情可咨询 ZEGO 技术支持

参数

名称	类型	描述
params	Object	传入的参数，格式为 JSON 对象，具体可咨询 ZEGO 技术支持。

详情

ZEGO 通过此 API 提供 RTC 业务中的部分技术预览或特别定制功能，需要获取功能的使用或详情其详情可咨询 ZEGO 技术支持。

调用时机：初始化后调用。

支持版本：3.3.0 及以上

checkSystemRequirements

 checkSystemRequirements<T extends keyof ZegoCheckSingleType>(checkType?: T, checkLevel: 0 | 1): Promise<ZegoCapabilityDetection>

支持能力检测接口

参数

名称	类型	描述
checkType	T	指定检查一项浏览器所能支持能力，如: webRTC, VP8 等，该参数不传默认检查所有可支持的能力。
checkLevel	0 \| 1	检测编码格式的等级，0 表示快速检测，准确率高。1 表示精准检测但可能消耗时间长，准确率更高。

详情

检测浏览器兼容性。

业务场景：音视频中很多功能只有较新版本的主流浏览器才支持，可以通过该接口来检测。
默认值：none
调用时机：初始化之后，创建流之前调用。
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：1. 真实支持度除了依赖浏览器外，还依赖系统，因此有较低概率监测不准的情况。

选择检查摄像头或麦克风能力时浏览器会弹框提示要求允许设备权限。
在仅使用拉流不推流的情况下不需要检查设备能力，只需要检查 "webRTC", "H264" 或 "VP8"。示例：const result = await zg.checkSystemRequirements("webRTC")。

off

off<K extends keyof ZegoEvent>(event: K, callBack?: ZegoEvent[K]): boolean

删除注册过的回调事件

参数

名称	类型	描述
event	K	监听事件名
callBack	ZegoEvent[K]	回调函数，可选

详情

ZegoEvent 包括了 ZegoRTCEvent 与 ZegoRTMEvent ，用于处理 SDK 主动通知开发者回调的接口，用于删除注册的同一类回调事件。

业务场景：通用接口，必选。
调用时机：注册之后，退出房间之前。
默认值：无
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：同类事件有多个时，都会被删除。

on

on<K extends keyof ZegoEvent>(event: K, callBack: ZegoEvent[K]): boolean

注册回调事件

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoEvent[K]	回调函数。

详情

ZegoEvent 包括了 ZegoRTCEvent 与 ZegoRTMEvent ，用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。

业务场景：通用接口，用于监听 SDK 的业务事件。
调用时机：初始化实例之后，调用接口 loginRoom 登录房间之前。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：1.0.0 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

getNetworkTimeInfo

getNetworkTimeInfo(): { timestamp: number; maxDeviation: number; }

获取同步网络时间信息。

获取当前网络时间（NTP），包括当前网络时间的时间戳和最大误差。

业务场景：在进行多端行为同步时，需要获取同步网络时间对当前时间进行校准。
调用时机：初始化 ZegoExpresEngine 实例后。

支持版本：3.0.0 及以上。

返回网络时间戳信息，timestamp 为同步后的网络时间戳，0表示尚未同步；maxDeviation 为最大误差值。

createStream

deprecated

createStream(source?: ZegoLocalStreamConfig): Promise<MediaStream>

创建推流数据源，包括摄像头麦克风采集源数据，屏幕共享数据，第三方源数据（能在页面播放的其他源数据）

参数

名称	类型	描述
source	ZegoLocalStreamConfig	创建媒体流的来源相关参数配置，不传默认是创建摄像头的媒体流

详情

创建媒体流并设置推流相关参数，包括摄像头采集流、屏幕共享捕捉流、本地或者在线媒体流等多种类型。

业务场景：用于获取摄像头画面或者当前屏幕画面。
默认值：默认为摄像头采集流，默认为高清格式。
调用时机：初始化且调用接口 checkSystemRequirements 检测返回的结果支持后可调用。
相关回调：推流质量回调 publishQualityUpdate 的质量报文内容会跟设置参数相关；屏幕共享中断回调 screenSharingEnded 触发时会自动将媒体流销毁。
相关接口：销毁创建的媒体流接口 destroyStream，开始推流接口 startPublishingStream。

支持版本：1.0.0 及以上。
注意事项：

移动端和 pc 端对视频宽高的理解不一样，两者恰好相反，同样的分辨率在 pc 端是横屏，在移动端就是竖屏。
必须在安全域名下（https,localhost,127.0.0.1）调用该接口。
推第三方流时，传入的 <video> 标签对应资源，必须加载成功后（媒体标签的 oncanplay 回调）才能调用该接口。
设置开始码率参数 startBitrate 为 “target” (仅 chrome 内核支持)，推流时码率将快速上升，网络较差的情况可能会出现卡顿或花屏，所以建议使用默认缓慢上升的方式。
如果有临时开闭音频或视频的需求，建议先推音视频流，再将对应不需要的音轨或视轨的 enable 设为 false, 推流后要开启音轨或视轨可以调用 replaceTrack 接口。
屏幕共享设置 source.screen.audio 为 true 时（仅windows 支持），只推送系统声音，不推送麦克风声音。
虽然 API 支持设置分辨率，但是很多设备对于自定义的分辨率并不支持，推荐使用参数 source.camera.videoQuality 或 source.screen.videoQuality 预设的几种分辨率。
camera.channelCount 和 custom.channelCount 仅 chrome 内核浏览器支持。

已废弃

此函数在 3.0.0 版本及以上已废弃，请参考 3.0.0 及以上版本升级指南更新逻辑。

返回值

Promise 异步返回流媒体对象。创建失败返回错误码，1103064：表示媒体流相关设备权限限制，可能是系统没有给浏览器摄像头、麦克风或屏幕采集权限。1103065：表示指定设备不可用于采集媒体流，可能是摄像头或麦克风被其他应用占用。1103066：表示创建流的相关配置参数错误，可能是指定的设备 ID 无效。1103061：表示获取媒体流失败，具体失败原因可以参考文档 ”getUserMedia 异常“ (https://developer.mozilla.org/zh-CN/docs/Web/API/MediaDevices/getUserMedia#%E5%BC%82%E5%B8%B8)。

createZegoStream

createZegoStream(source?: ZegoStreamOptions): Promise<ZegoLocalStream>

创建一个推流对象ZegoLocalStream实例，ZegoLocalStream集成功能包括摄像头麦克风采集，屏幕共享采集，第三方源数据（能在页面播放的其他源数据），以及对采集流的播放预览等。

参数

名称	类型	描述
source	ZegoStreamOptions	创建媒体流的来源相关参数配置，不传默认是创建摄像头的媒体流

详情

创建一个推流对象ZegoLocalStream实例，并可设置采集、推流码率以及播放预览容器的相关参数。采集相关参数设置包括摄像头采集流、屏幕共享捕捉流、本地或者在线媒体流等多种类型。

业务场景：用于获取摄像头画面或者当前屏幕画面。
默认值：默认为摄像头采集，默认为高清格式。
调用时机：初始化且调用接口 checkSystemRequirements 检测返回的结果支持后可调用。
相关回调：推流质量回调 publishQualityUpdate 的质量报文内容会跟设置参数相关；屏幕共享中断回调 screenSharingEnded 触发时会自动将媒体流销毁。
相关接口：销毁创建的媒体流接口 destroyStream，开始推流接口 startPublishingStream。

支持版本：3.0.0及以上。
注意事项：

移动端和 pc 端对视频宽高的理解不一样，两者恰好相反，同样的分辨率在 pc 端是横屏，在移动端就是竖屏。
必须在安全域名下（https,localhost,127.0.0.1）调用该接口。
推第三方流时，传入的 <video> 标签对应资源，必须加载成功后（媒体标签的 oncanplay 回调）才能调用该接口。
设置开始码率参数 startBitrate 为 “target” (仅 chrome 内核支持)，推流时码率将快速上升，网络较差的情况可能会出现卡顿或花屏，所以建议使用默认缓慢上升的方式。
如果有临时开闭音频或视频的需求，建议先推音视频流，再调用[mutePublishStreamVideo]开闭视频，[mutePublishStreamAudio]开闭音频。推流后要更新采集的音频或视频可以调用ZegoLocalStream实例上的[startCaptureCamera]、 [startCaptureMicrophone]等采集方法，结合[updatePublishingStream] 更新推流中的音视频。
屏幕共享设置 source.screen.audio 为 true 时（仅windows 支持），只推送系统声音，不推送麦克风声音。
虽然 API 支持设置分辨率，但是很多设备对于自定义的分辨率并不支持，推荐使用参数 source.camera.video.quality 或 source.screen.video.quality 预设的几种分辨率。
camera.audio.channelCount 和 custom.audio.channelCount 仅 chrome 内核浏览器支持。

返回值

updatePublishingStream

updatePublishingStream(zegoStream: ZegoLocalStream, updateType: ZegoStreamUpdateType): Promise<ZegoServerResponse>

用于更新处于推流中的ZegoLocalStream实例的音视轨

参数

名称	类型	描述
zegoStream	ZegoLocalStream	通过createZegoStream创建的ZegoLocalStream实例对象
updateType	ZegoStreamUpdateType	更新类型，0为视频，1为音频，2为音视频

详情

用于更新处于推流中的ZegoLocalStream实例的音视轨。

业务场景：调用[createZegoStream]创建一个ZegoLocalStream实例对象，在[startPublishingStream]成功推流后，需要更新ZegoLocalStream实例处于推流中的音视频。

支持版本：3.0.0及以上。
注意事项：需要ZegoLocalStream有成功采集音视频流可用于更新。

getPublishingStreamQuality

getPublishingStreamQuality(streamID: string): ZegoPublishStats | null

获取推流质量。

参数

名称	类型	描述
streamID	string	流 ID

详情

主动获取正在推流的流质量。

业务场景：获取当前推流的分辨率、帧率、码率等质量参数。
调用时机：[startPublishingStream] 推流成功后。
相关回调：推流质量回调 [publishQualityUpdate]。

支持版本：2.15.0 及以上
使用限制：由于 SDK 的流质量参数每 3 秒更新一次，所以该接口的调用间隔建议不要小于 3 秒。

返回值

推流质量报文，如果获取失败会返回 null。

getElectronScreenSources

getElectronScreenSources(): Promise<ZegoElectronScreenSource[]>

在 Electron 框架下，需要使用屏幕共享功能时调用，返回屏幕列表数据

在 Electron 框架下，需要使用屏幕共享功能时调用，返回屏幕列表数据。

业务场景：在 Electron 框架下，需要使用屏幕共享功能时调用。
调用时机：初始化之后。
相关回调：无。
相关接口：createStream、createZegoStream。

支持版本：2.11.0
注意事项：无。

electron 屏幕源列表数据

setCaptureAudioFrameCallback

 setCaptureAudioFrameCallback(stream: MediaStream|ZegoLocalStream, callback: ((audioData:ZegoAudioFrame)=>void) | null, options?: AudioFrameOptions): Promise<ZegoServerResponse>

设置采集流的原始音频数据回调

参数

名称	类型	描述
stream	MediaStream\|ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象
callback	((audioData:ZegoAudioFrame)=>void) \| null	接收音频数据的回调函数，设置为 null 则不再回调音频数据
options?	AudioFrameOptions	音频数据回调配置项

详情

设置流原始音频数据(PCM)回调。

默认值：无
调用时机：采集流成功后。
影响范围：无
相关回调：无
相关接口：无。
平台差异：无

支持版本：3.8.0
使用限制：无
注意事项：1. 采集流有音频轨道。

只对 RTC 流或 L3 流有效，无法操作 CDN 拉流。
目前 Chrome 浏览器仅支持 85 以上版本。
由于浏览器限制，必须与页面产生交互后才有数据回调。

destroyStream

destroyStream(localStream: MediaStream | ZegoLocalStream): void

销毁创建的流数据

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象

详情

销毁流后对应的相关设备也会关闭，如摄像头、麦克风。

业务场景：本地预览和推流必选。
默认值：无
调用时机：创建流后才能调用。
影响范围：无
相关回调：无
相关接口：创建推流数据源 createStream 或者 createZegoStream。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：推流过程中，销毁流会导致推流中断，销毁流之前请先停止推流，否则对端画面会卡住。

checkVideoTrackIsActive

checkVideoTrackIsActive(stream: MediaStream | ZegoLocalStream): Promise<boolean>

检查视频轨是否为工作状态

参数

名称	类型	描述
stream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。

详情

检查视频轨是否为工作状态。

业务场景：本地创建预览流后，可以调用该接口检查视频轨是否为工作状态。
默认值：无
调用时机：创建流后才能调用。
影响范围：无
相关回调：无
相关接口：创建推流数据源 createStream或者createZegoStream。
平台差异：无

支持版本：2.25.5
使用限制：无
注意事项：仅对 createStream 或者 createZegoStream 生成的本地采集流有效。

返回值

true 为 active，false 为非 active。

checkAudioTrackIsActive

checkAudioTrackIsActive(stream: MediaStream): Promise<boolean>

检查音轨是否为工作状态

参数

名称	类型	描述
stream	MediaStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。

详情

检查音频轨是否为工作状态。

业务场景：本地创建预览流后，可以调用该接口检查音频轨是否为工作状态。
默认值：无
调用时机：创建流后才能调用。
影响范围：无
相关回调：无
相关接口：创建推流数据源 createStream 或者 createZegoStream。
平台差异：无

支持版本：2.25.5
使用限制：无
注意事项：仅对 createStream 或者 createZegoStream 生成的本地采集流有效。

返回值

true 为 active，false 为非 active。

startPublishingStream

 startPublishingStream(streamID: string, localStream: MediaStream | ZegoLocalStream, publishOption?: ZegoWebPublishOption): boolean

开始推流

参数

名称	类型	描述
streamID	string	流 ID，长度不超过 256 的字符串。注意事项： 1. 流 ID 由您自己定义。 2. 需要在整个 AppID 内全局唯一，若出现在同一个 AppID 内，不同的用户各推了一条流且流名相同，将会导致后推流的用户推流失败。 3. 仅支持数字，英文字符和 '-', '_'。
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象
publishOption	ZegoWebPublishOption	推拉附加参数（鉴权、视频编码），可选。

详情

将本地流推送到远端（即构服务器），推流状态回调通知推流成功后同一房间的其他用户可以通过 streamID 进行拉流。

业务场景：推流时必选。
默认值：publishOption.videoCodec 默认使用 H.264 推流，如果有特殊需求可选择 VP8，更多场景选择方案请先咨询 ZEGO 售前工程师。
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。
相关回调：推流质量回调 publishQualityUpdate，推流状态回调 publisherStateUpdate（可通过该接口来判断推流是否成功）。
相关接口：通过调用接口 stopPublishingStream 结束推流。

支持版本：1.0.0 及以上。

返回值

true 表示客户端发送请求成功，流成功推送到服务器需要通过流状态回调接口判断。

stopPublishingStream

stopPublishingStream(streamID: string): boolean

停止将本地流推送到远端（即构服务器）

参数

名称	类型	描述
streamID	string	推流 ID,和推流streamID保持一致

详情

停止推流。

业务场景：可以用于实时连麦、直播等场景下停止推流。
默认值：无
调用时机：推流成功后。
影响范围：无
相关回调：推流质量回调 publishQualityUpdate，推流状态回调 publisherStateUpdate。
相关接口：开始推流 startPublishingStream。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：停止推流不会导致渲染的 <video> 画面暂停，开发者需自行销毁 <video>。

sendSEI

sendSEI(streamID: string, inData: Uint8Array): boolean

发送媒体增强补充信息

参数

名称	类型	描述
streamID	string	流 ID
inData	Uint8Array	SEI 内容

详情

在推流传输音视频流数据同时，发送流媒体增强补充信息来同步一些其他附加信息。

业务场景：一般用于如同步音乐歌词或视频画面精准布局等场景，可选择使用发送 SEI。
调用时机：在开始推流 [startPublishingStream] 后。
相关接口：当推流方发送 SEI 后，拉流方可通过监听 [on] 方法监听事件 [playerRecvSEI] 的回调获取 SEI 内容。
相关回调：无。

支持版本：2.16.0 及以上。
使用限制：1 秒钟不要超过30次，SEI 数据长度限制为 4096 字节。
注意事项：

SEI 目前仅支持 Chrome 浏览器 86 及以上版本。
由于 SEI 信息跟随视频帧，由于网络问题有可能丢帧，因此 SEI 信息也有可能丢，为解决这种情况，可以在限制频率内多发几次。
SEI 对性能的要求较高，同时对多路流进行 SEI 操作可能会有影响。

setVideoConfig

 setVideoConfig(localStream: MediaStream | ZegoLocalStream, constraints: ZegoPublishStreamConfig): Promise<ZegoServerResponse>

修改推流参数

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
constraints	ZegoPublishStreamConfig	流的约束

详情

推流中修改推流相关参数，不建议频繁修改。

业务场景：推流不是主 C 位时，降低分辨率节省带宽。
默认值：默认视频采集分辨率为 640 * 480，帧率为 15，码率为 800 kbps。
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。2.15.0 及以前版本要推流成功后才能调用该接口。
影响范围：无
相关回调：推流质量回调 publishQualityUpdate。
相关接口：无
平台差异：无

支持版本：1.14.0
使用限制：无
注意事项：被修改的 localStream 必须是通过 SDK 调用 createStream 或者 createZegoStream方法得到的。

setAudioConfig

 setAudioConfig(localStream: MediaStream | ZegoLocalStream, constraints: ZegoPublishStreamAudioConfig): Promise<ZegoServerResponse>

修改推流音频相关参数

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
constraints	ZegoPublishStreamAudioConfig	流的约束

详情

推流中修改推流相关参数，不建议频繁修改。

业务场景：主播外放背景音乐时，暂时关闭3A，防止被当做噪声消除。
默认值：无
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。 2.15.0 及之前的版本只有在推流成功后才能调用该接口。
影响范围：无
相关回调：推流质量回调 publishQualityUpdate。
相关接口：无
平台差异：无

支持版本：1.14.0
使用限制：无
注意事项：被修改的 localStream 必须是通过 SDK 调用 createStream 或者 createZegoStream 方法得到的。

replaceTrack

deprecated

replaceTrack(localStream: MediaStream, mediaStreamTrack: MediaStreamTrack): Promise<ZegoServerResponse>

替换媒体流的音视频轨道

参数

名称	类型	描述
localStream	MediaStream	创建流得到的 stream
mediaStreamTrack	MediaStreamTrack	音视频轨道

详情

替换已经创建的推流视轨或音轨

业务场景：例如可以在摄像头、屏幕共享或视频之间切换视频轨道，在麦克风和 mp3 之间切换音频轨道。
默认值：无
调用时机：创建流成功后才能调用该接口。
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：1.13.0
使用限制：无
注意事项：被替换的 localStream 必须是通过 SDK 调用 createStream 方法得到的。

已废弃

此函数在 3.0.0 版本及以上已废弃，请参考 3.0.0 及以上版本升级指南更新逻辑。

addTrack

deprecated

addTrack(localStream: MediaStream, track: MediaStreamTrack): Promise<ZegoServerResponse>

给媒体流添加视频轨道。

参数

名称	类型	描述
localStream	MediaStream	创建流得到的 stream。
track	MediaStreamTrack	视频轨道。

详情

给媒体流添加视频轨道。

业务场景：只创建音频单轨道时只获取麦克风权限，后续需要打开摄像头时才获取摄像头权限创建视频轨道，通过 addTrack 添加到纯音频媒体流上。
默认值：无
调用时机：创建流成功后才能调用该接口。
相关接口：removeTrack 移除视轨。

支持版本：2.22.0
使用限制：无
注意事项：被替换的 localStream 必须是通过 SDK 调用 createStream 方法得到的。

已废弃

此函数在 3.0.0 版本及以上已废弃，请参考 3.0.0 及以上版本升级指南更新逻辑。

removeTrack

deprecated

removeTrack(localStream: MediaStream, track: MediaStreamTrack): Promise<ZegoServerResponse>

给媒体流移除音视频轨道。

参数

名称	类型	描述
localStream	MediaStream	创建流得到的 stream。
track	MediaStreamTrack	视频轨道。

详情

给媒体流移除视频轨道。

调用时机：创建流成功后才能调用该接口。
相关接口：addTrack 添加媒体轨。

支持版本：2.22.0
注意事项：被替换的 localStream 必须是通过 SDK 调用 createStream 方法得到的。

已废弃

此函数在 3.0.0 版本及以上已废弃，请参考 3.0.0 及以上版本升级指南更新逻辑。

setCaptureVolume

setCaptureVolume(localStream: MediaStream | ZegoLocalStream, volume: number): Promise<ZegoServerResponse>

创建流后可通过该接口调节采集音量

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	需要修改音量的流对象或者ZegoLocalStream实例对象
volume	number	音量大小，0-100

详情

调节当前采集的音量大小。

业务场景：需要中途动态控制推流声音大小时。
默认值：无
调用时机：创建流成功后。
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：2.3.0
使用限制：无
注意事项：创建流成功后才能调用该接口，进行混音后仅对采集的音轨有效，混音部分音量请使用setMixingAudioVolume 接口进行调节。

setDummyCaptureImagePath

setDummyCaptureImagePath(filePath: string, localStream: MediaStream | ZegoLocalStream): Promise<boolean>

设置关闭视频流时所推静态图片的路径

参数

名称	类型	描述
filePath	string	图片路径
localStream	MediaStream \| ZegoLocalStream	需要在该流关闭时发送图片的流对象或者ZegoLocalStream实例对象

详情

设置关闭视频流时所推静态图片的路径。

业务场景：需要关闭视频画面时推一个特定的背景图片。
调用时机：创建流成功后。

支持版本：2.15.0
注意事项：创建流成功后才能调用该接口，静态图片分辨率越高越消耗性能，所以建议根据所需推流分辨率来选择所需图片大小。

setStreamExtraInfo

setStreamExtraInfo(streamID: string, extraInfo: string): Promise<ZegoServerResponse>

设置流的附加信息

参数

名称	类型	描述
streamID	string	推流 ID
extraInfo	string	流附加信息; extraInfo为json格式字符串

详情

更改流附加信息。

业务场景：需要对推流进行更丰富的描述，且希望拉流端能接受到这些信息时使用。
默认值：无
调用时机：推流成功后。
影响范围：无
相关回调：初次登录房间用户可通过 roomStreamUpdate 获取流附加信息，已经在房间拉流的用户通过流附加信息更新回调 streamExtraInfoUpdate 获取更新后的流附加消息。
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：只支持字符串。

enableVideoCaptureDevice

enableVideoCaptureDevice(localStream: MediaStream | ZegoLocalStream, enable?: boolean): Promise<boolean>

开/关视频采集设备。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	创建流获取的摄像头媒体流或者ZegoLocalStream实例对象。
enable	boolean	标识开启或停止采集；true 表示开启采集；false 表示关闭采集；默认为 true。

详情

开启或关闭视频采集设备。

业务场景：主播在某一时段画面，不希望被拉流端看到摄像头画面也不希望摄像头设备一直被占用时调用。
调用时机：创建流成功后。
相关回调：调用停止采集摄像头接口会触发拉流端对应流的摄像头状态回调 [remoteCameraStatusUpdate]。
相关接口：相较于该接口，打开/关闭发送流视频数据接口 [mutePublishStreamVideo] 响应速度更快且不影响视频采集状态。

支持版本：2.15.0 及以上
使用限制：硬件上关闭或打开摄像头是耗时操作，用户频繁操作时有一定的性能开销，一般推荐使用 [mutePublishStreamVideo]。
注意事项：1. 打开/关闭流画面的前提是媒体流必须为摄像头流。

如果通过 replaceTrack 或 addTrack 接口做了替换视轨，则不支持调用该接口进行关闭摄像头采集，可以自行调用 MediaStreamTrack.stop 方法进行停止摄像头采集。

返回值

Promise 返回 boolean 标识是否调用成功。

addPublishCdnUrl

addPublishCdnUrl(streamID: string, targetURL: string): Promise<ZegoServerResponse>

通知即构服务器将流转推到CDN

参数

名称	类型	描述
streamID	string	推流 ID
targetURL	string	CDN 转推地址，支持的转推地址格式有 rtmp

详情

当需要将音视频流转推到其它指定的 CDN 时，需要调用此接口进行设置（调用前请先联系 ZEGO 技术支持配置转推 CDN 功能）。

业务场景：单向直播场景，拉流端使用 CDN 拉流。
默认值：无
调用时机：推流成功后。
影响范围：无
相关回调：无
相关接口：通知即构服务器停止将流转推到 CDN removePublishCdnUrl。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：建议使用服务端动态转推 CDN 中的增加转推 CDN 地址 API 替代该客户端 API。该接口调用有可能会失败，若返回成功，仅代表通知即构服务器成功，无法判断即构服务器是否转推 CDN 成功。

removePublishCdnUrl

removePublishCdnUrl(streamID: string, targetURL: string): Promise<ZegoServerResponse>

通知即构服务器停止将流转推到 CDN

参数

名称	类型	描述
streamID	string	推流 ID
targetURL	string	CDN 转推地址，支持的转推地址格式有 rtmp

详情

当已经添加了某个 CDN 转推地址，需要停止将流转推至该 CDN 时调用此接口（调用前请先联系 ZEGO 技术支持配置转推 CDN 功能）。

业务场景：单向直播场景，拉流端使用 CDN 拉流。
默认值：无
调用时机：转推成功后
影响范围：无
相关回调：无
相关接口：通知即构服务器将流转推到 CDN addPublishCdnUrl。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：建议使用服务端动态转推 CDN 中的增加转推 CDN 地址 API 替代该客户端 API。该接口调用有可能会失败，若返回成功，仅代表通知即构服务器成功，无法判断即构服务器是否转推 CDN 成功。

mutePublishStreamVideo

mutePublishStreamVideo(localStream: MediaStream | ZegoLocalStream, mute: boolean, retain?: boolean): boolean

关闭/打开正在推流的流画面

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
mute	boolean	是否停止发送视频流；true 表示不发送视频流；false 表示发送视频流；默认为 true。
retain	boolean	是否保留预览画面，布尔值，true 保留， false 不保留，默认为 false

详情

推流时可调用此函数实现不推视频流，本地摄像头仍能正常工作，能正常采集和处理视频画面且不向网络发送视频数据。

业务场景：主播在某一时段画面，不希望被拉流端看到时调用。
调用时机：创建流成功后。
相关回调：拉流摄像头状态回调 remoteCameraStatusUpdate。
相关接口：打开/关闭正在推流的流声音 mutePublishStreamAudio。

支持版本：1.0.0
注意事项：打开/关闭流画面的前提是原始流必须有视频轨道，创建流时不能为纯音频。

返回值

标识是否成功关闭推流画面

mutePublishStreamAudio

mutePublishStreamAudio(localStream: MediaStream, mute: boolean): boolean

打开/关闭正在推流的流声音，包括麦克风、混音背景音乐的声音

参数

名称	类型	描述
localStream	MediaStream	创建流获取的 stream
mute	boolean	是否停止发送音频流；true 表示不发送音频流；false 表示发送音频流；默认为 true。

详情

打开/关闭正在推流的流所有声音，包括麦克风、混音背景音乐的声音，音频轨依旧保留。

业务场景：主播在某一时段不想让观众端听到声音。如果想将推出去的所有音频数据静音，则可以参考调用 mutePublishStreamAudio 接口。对应的，如果您只是想静音麦克风的声音，例如您在混音功能时想关闭麦克风并保留混入的背景音乐，则调用 muteMicrophone 接口可以将麦克风静音，而不影响推流的背景音乐。
调用时机：创建流成功后。
相关回调：拉流麦克风状态回调 remoteMicStatusUpdate。
相关接口：关闭/打开正在推流的流画面 mutePublishStreamVideo；关闭/打开麦克风声音接口 muteMicrophone。

支持版本：1.0.0
注意事项：1. 打开/关闭流声音的前提是原始流必须有音频轨道，创建流时不能为纯视频。

该接口会关闭所有流声音，包括麦克风、混流的背景音乐等声音，而 muteMicrophone 只会关闭麦克风的声音。

setEffectsBeauty

  setEffectsBeauty(localStream: MediaStream | ZegoLocalStream, enable: boolean, options?: ZegoEffectsBeautyParam): Promise<ZegoServerResponse>

开启或关闭美颜

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
enable	boolean	是否开启美颜，true 表示开启，false 表示关闭。
options	ZegoEffectsBeautyParam	美颜选项，包含 smoothIntensity（磨皮）、whitenIntensity（美白）、rosyIntensity（红润）、sharpenIntensity（锐化）四个参数，可用来实现美颜效果。四个强度参数范围 [0,100]，默认值为 50, options 参数非必填。

详情

可以通过该接口开关美颜和调整美颜参数，实现自然的美颜效果。

业务场景：摄像头画面进行人像美颜。
调用时机：调用接口 createStream 或者 createZegoStream 获取到媒体流后。
相关回调：无。

支持版本：2.13.0 及以上。
注意事项：

美颜效果与对应的 MediaStream 绑定，当调用 useVideoDevice、replaceTrack 时不改变对应 MediaStream 的美颜效果。
美颜处理占用资源并消耗性能，当不需要使用美颜时需要及时调用 setEffectsBeauty(localStream,false) 关闭。
当调用 destroyStream 销毁流的同时 SDK 会关闭美颜效果, 其他情况 SDK 不会主动关闭美颜处理，需要自行调用 setEffectsBeauty(localStream,false) 关闭。
移动端设备的浏览器不支持开启美颜。
开启美颜是一个异步的接口，在开启过程中不能开始推流，如果需要在推流前开启美颜需要等美颜接口异步完成后再调用 startPublishingStream 接口。

setLowlightEnhancement

  setLowlightEnhancement(localStream: MediaStream | ZegoLocalStream, mode: ZegoLowlightEnhancementMode): Promise<ZegoServerResponse>

设置低照度增强。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
mode	ZegoLowlightEnhancementMode	低照度增强模式。

详情

根据设置的低照度增强模式，对摄像头采集的画面亮度进行增强，兼容美颜功能。用户可以在预览时观看效果，并实时切换低照度增强模式。

业务场景：推流端环境较暗，或者摄像头设置的帧率较高导致画面偏暗，无法正常显示或识别主体。
默认值：关闭。
调用时机：调用 createStream 或者 createZegoStream 创建预览流之后。

支持版本：2.18.0 及以上。
注意事项：接口兼容性同 setEffectsBeauty，不兼容移动端浏览器。

enableDualStream

enableDualStream(localStream: MediaStream | ZegoLocalStream): void

开启大小流

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。

详情

可以通过该接口开关大小流。

业务场景：需要不同终端显示不同质量的视频流或需要在较差的网络环境中保持连麦的流畅。
调用时机：在成功调用创建流接口后，推流接口前。
相关回调：无。

支持版本：2.18.0 及以上。
注意事项：无。

setLowStreamParameter

 setLowStreamParameter(localStream: MediaStream | ZegoLocalStream, param: { width: number; height: number; frameRate: number; bitRate: number }): void

设置小流参数

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
param	{ width: number; height: number; frameRate: number; bitRate: number }	小流参数，分辨率宽高，帧率及码率。

详情

可以通过该接口设置小流参数。

业务场景：需要不同终端显示不同质量的视频流或需要在较差的网络环境中保持连麦的流畅。
调用时机：在成功调用创建流接口后，推流接口前。
相关回调：无。

支持版本：2.18.0 及以上。
注意事项：无。

enableHardwareEncoder

enableHardwareEncoder(enable: boolean): void

开/关硬件编码。

参数

名称	类型	描述
enable	boolean	是否开启硬件编码；true 表示开启硬编；false 表示关闭硬编；默认为 false。

详情

推流时是否采用硬件编码的开关，开启硬件编码后会使用 GPU 进行编码，降低 CPU 使用率。

业务场景：减少视频编码对 CPU 占用。
调用时机：在推流前设置才能生效，如果在推流后设置，停推后重新推流可以生效。

支持版本：2.20.0 及以上
注意事项：由于少部分机型设备硬编支持不是特别好，SDK 默认使用软件编码的方式。若开发者在某些机型测试时发现推大分辨率音视频流时设备发热严重，可考虑调用此函数开启硬编的方式。

enableAutoSwitchDevice

enableAutoSwitchDevice(config: ZegoAutoSwitchDeviceConfig): void

开启或关闭相关设备的自动切换

参数

名称	类型	描述
config	ZegoAutoSwitchDeviceConfig	设备自动切换的相关配置

详情

传入相关配置，开启或关闭相关设备的自动切换，设备被拔除之后支持自动切换当前使用的其他可用设备。SDK默认关闭自动切换设备。

业务场景：SDK创建初始化之后，设备拔插的兼容操作。

支持版本：2.20.0 及以上。

initBackgroundModule

initBackgroundModule(segmentation: Segmentation, assetsURL: string): Promise<ZegoServerResponse>

初始化背景处理模块。

参数

名称	类型	描述
segmentation	Segmentation	背景分割模式。
assetsURL	string	资源文件路径。

详情

初始化背景处理模块。

业务场景：以自定义的图片替代真实的背景。
默认值：无
调用时机：初始化 SDK 后。

支持版本：2.24.0 及以上。
注意事项：1. 目前仅支持 PC 端使用，移动端暂不支持。

setBackgroundBlurOptions

setBackgroundBlurOptions(localStream: MediaStream | ZegoLocalStream, options: BackgroundBlurOptions): Promise<boolean>

设置背景虚化相关参数。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
options	BackgroundBlurOptions	背景虚化处理的参数。

详情

设置背景虚化相关参数。

业务场景：虚化用户周围的真实场景。
默认值：无
调用时机：调用接口 initBackgroundModule 初始化背景处理模块和调用接口 createStream 或者 createZegoStream 创建流成功后。

支持版本：2.24.0 及以上。
注意事项：1. 目前仅支持 PC 端使用，移动端暂不支持；

setVirtualBackgroundOptions

  setVirtualBackgroundOptions(localStream: MediaStream | ZegoLocalStream, options: BackgroundVirtualOptions): Promise<boolean>

设置虚拟背景相关处理参数。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
options	BackgroundVirtualOptions	虚拟背景处理相关参数。

详情

设置虚拟背景处理相关参数。

业务场景：对流进行虚拟背景相关处理。
默认值：无
调用时机：调用接口 initBackgroundModule 初始化背景处理模块调用接口 createStream 创建流成功后。

支持版本：2.24.0 及以上版本。
注意事项：1. 目前仅支持 PC 端使用，移动端暂不支持；

使用前需调 ZegoExpressEngine.use 方法引入虚拟背景模块。

setTransparentBackgroundOptions

setTransparentBackgroundOptions(localStream: MediaStream): Promise<boolean>

设置透明背景相关处理参数。

参数

名称	类型	描述
localStream	MediaStream	媒体流。

详情

设置透明背景相关处理参数。

业务场景：对流进行透明背景相关处理。
默认值：无
调用时机：调用接口 initBackgroundModule 初始化背景处理模块调用接口 createStream 或者 createZegoStream 创建流成功后。

支持版本：3.0.0 及以上版本。
注意事项：1. 目前仅支持 PC 端使用，移动端暂不支持；

使用前需调 ZegoExpressEngine.use 方法引入虚拟背景模块。

enableBackgroundProcess

  enableBackgroundProcess(localStream: MediaStream | ZegoLocalStream, enable: boolean, segmentation: Segmentation): Promise<ZegoServerResponse>

开启背景处理功能。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
enable	boolean	开启或关闭背景处理。
segmentation	Segmentation	背景处理分割模式。

详情

将推送的媒体流进行背景处理。

业务场景：对推的流进行背景的处理。
默认值：无
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。

支持版本：2.24.0 及以上。
注意事项：1. 目前仅支持 PC 端使用，移动端暂不支持；

setVoiceChangerParam

setVoiceChangerParam(localStream: MediaStream | ZegoLocalStream, voiceParam: number): Promise<ZegoServerResponse>

变声处理。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
voiceParam	number	音调参数 voiceParam，取值范围 [-12.0, 12.0]，数值越大声音越尖，设为 0.0 即关闭变声器。

详情

通过参数设置自定义变声效果。

业务场景：推流前或推流中切换变声。
默认值：无
调用时机：调用接口 [createStream] 或者 [createZegoStream] 创建流成功后。

支持版本：3.0.0 及以上版本。
注意事项：1. 目前仅支持对特定的一条流进行变声处理，不支持同时对多条流同时变声； 2.音调参数 voiceParam，取值范围 [-12.0, 12.0]，数值越大声音越尖，设为 0.0 即关闭变声器。

setVoiceChangerPreset

 setVoiceChangerPreset(preset: ZegoVoiceChangerPreset, localStream: MediaStream | ZegoLocalStream): Promise<ZegoServerResponse>

变声处理。

参数

名称	类型	描述
preset	ZegoVoiceChangerPreset	变声预设值。
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。

详情

将推送的媒体流进行变声处理。

业务场景：推流前或推流中切换变声。
默认值：无
调用时机：调用接口 [createStream] 或者 [createZegoStream]创建流成功后。

支持版本：2.23.0 及以上版本。
注意事项：1. 目前仅支持对特定的一条流进行变声处理，不支持同时对多条流同时变声；

setReverbPreset

setReverbPreset(localStream: MediaStream | ZegoLocalStream, preset: ZegoReverbPreset): Promise<ZegoServerResponse>

通过预设枚举设置混响。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	需要混响处理的媒体流或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
preset	ZegoReverbPreset	混响预设枚举值。

详情

可通过调用本函数设置预设混响效果。

业务场景：常用于直播、语聊房和 KTV 等场景。
默认值：无
调用时机：调用接口 [createStream] 或者 createZegoStream 创建流成功后，且在推流前或推流成功后调用。

支持版本：3.0.0 及以上版本。
注意事项：1. 目前仅支持对特定的一条流进行混音处理，不支持同时对多条流同时混响。

本函数与 [setVoiceChangerPreset] 同时使用效果可能和预期有差异，如需同时使用，建议先开启变声，再开启混响。

enableVirtualStereo

 enableVirtualStereo(localStream: MediaStream | ZegoLocalStream, enable: boolean, angle: number): Promise<ZegoServerResponse>

开启或关闭推流时的虚拟立体声效果。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	需要混响处理的媒体流或createZegoStream创建得到的 ZegoLocalStream实例对象。
enable	boolean	true 代表开启虚拟立体声，false 代表关闭虚拟立体声。
angle	number	虚拟立体声中声源的角度，范围为 -1 ~ 360，90 为正前方，0 / 180 / 270 分别对应最右边 / 最左边 / 正后方；特别的，设置 -1 时为全方位虚拟立体声效果。

详情

可通过调用本函数开启/关闭推流时的虚拟立体声效果。

业务场景：常用于直播、语聊房和 KTV 等场景。
默认值：无
调用时机：调用接口 [createStream] 或者 [createZegoStream] 创建支持双声道的流成功后，且在推流前或推流成功后调用。

支持版本：3.0.0 及以上版本。
注意事项：1. 目前仅支持对特定的一条流进行混音处理，不支持同时对多条流同时混响。

需要调用 [createStream] 或者 [createZegoStream] 时参数设置双声道虚拟立体声才能生效。
虚拟立体声和混响功能效果有冲突，产生的效果可能不符合预期，不要进行叠加使用。
Mac Safari 、移动端设备浏览器上暂不支持虚拟立体声功能。

enableAiDenoise

enableAiDenoise(localStream: MediaStream | ZegoLocalStream, enable: boolean): Promise<ZegoServerResponse>

传入媒体流，开启或关闭 AI 降噪

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	需要切换 AI 降噪的媒体流或者 createZegoStream创建得到的 ZegoLocalStream实例对象
enable	boolean	开启/关闭 AI 降噪

详情

将推送的媒体流进行 AI 降噪处理。

业务场景：推流前或推流中切换 AI 降噪。
默认值：无
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。

支持版本：2.19.0
注意事项：1. 目前使用 AI 降噪功能需要联系 ZEGO 技术支持进行特殊编包；

目前仅支持 PC 端使用，移动端暂不支持；
目前仅支持对特定的一条流进行 AI 降噪处理，不支持同时对多条流同时降噪；

setAiDenoiseMode

setAiDenoiseMode(localStream: MediaStream | ZegoLocalStream, mode: AiDenoiseMode): Promise<ZegoServerResponse>

设置AI降噪模式

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	需要切换 AI 降噪的媒体流或者 createZegoStream创建得到的 ZegoLocalStream实例对象
mode	AiDenoiseMode	AI 降噪模式

详情

设置AI降噪模式。

业务场景：需要切换AI降噪模式。
默认值：无
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。

支持版本：3.3.0
注意事项：1. 目前使用 setAiDenoiseMode 需要联系 ZEGO 技术支持进行特殊编包；

目前仅支持 PC 端使用，移动端暂不支持；

setStreamAlignmentProperty

setStreamAlignmentProperty(streamID: string, alignment: number): Promise<boolean>

开启或关闭混流精准对齐功能。

参数

名称	类型	描述
streamID	string	推流的 streamID。
alignment	number	是否开启对齐，0 是关闭，1是开启。

详情

对当前推流开启混流对齐，开启后混流会对该流与其他开启对齐的流进行对齐处理。

业务场景：常用于 KTV 等需要混流对齐的场景。
默认值：若未调该接口，默认为不对齐。
调用时机：推流成功后。
相关接口：开始混流接口 startMixerTask，混流任务开启精准对齐功能后会将开启对齐的流进行对齐处理。

支持版本：3.0.0 及以上。

返回值

异步返回布尔值，标识是否调用成功。

startPlayingStream

startPlayingStream(streamID: string, playOption?: ZegoWebPlayOption): Promise<MediaStream>

开始拉流

参数

名称	类型	描述
streamID	string	流 ID ，必填。
playOption	ZegoWebPlayOption	拉流附加参数，可选。

详情

通过流 ID 拉取远端用户的媒体流。

业务场景：拉流时必选。
调用时机：收到新增拉流，即 roomStreamUpdate 回调后。
相关回调：拉流质量回调 playQualityUpdate，拉流状态回调 playerStateUpdate （可通过该回调来判断拉流是否成功）。
相关接口：调用接口 stopPlayingStream 结束拉流。

支持版本：1.0.0 及以上。
注意事项：

拉流前确保该条流已经推成功（推送到 ZEGO 服务器），即拉流是在 roomStreamUpdate 回调后。

返回值

promise 异步返回流媒体对象。

stopPlayingStream

stopPlayingStream(streamID: string): void

停止拉取远端流（即构服务器）

参数

名称	类型	描述
streamID	string	流 ID，必填

详情

停止拉流，断开和即构服务器之间的连接，不再产生带宽。

业务场景：拉流必选。
默认值：无
调用时机：拉流成功后。
影响范围：无
相关回调：拉流质量回调 playQualityUpdate，拉流状态回调 playerStateUpdate。
相关接口：开始拉流 startPlayingStream。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：停止拉流后不会销毁播放器，播放器销毁需要开发者自己实现。

mutePlayStreamVideo

mutePlayStreamVideo(streamID: string, mute: boolean): Promise<boolean>

停止或恢复拉取视频流

参数

名称	类型	描述
streamID	string	流ID
mute	boolean	是否拉取视频流，true 表示停止拉取；false 表示恢复拉取

详情

只是将数据降低为很小，视频轨还在。

业务场景：观众在某一时段画面，不想看到主播画面时调用。
默认值：无
调用时机：拉流成功后。
影响范围：无
相关回调：无
相关接口：停止或恢复拉取音频流 mutePlayStreamAudio。
平台差异：无

支持版本：1.15.0
使用限制：无
注意事项：1. 停止或恢复拉取视频流的前提是原始流必须有视频轨道，拉流时不能为纯音频。

只对 RTC 流或 L3 流有效，无法操作 CDN 拉流。

setAudioFrameCallback

 setAudioFrameCallback(streamID: string, callback: ((audioData:ZegoAudioFrame)=>void) | null, options?: AudioFrameOptions): Promise<ZegoServerResponse>

设置拉流的原始音频数据回调。

参数

名称	类型	描述
streamID	string	拉流 ID
callback	((audioData:ZegoAudioFrame)=>void) \| null	接收音频数据的回调函数，设置为 null 则不再回调音频数据
options?	AudioFrameOptions	音频数据回调配置项

详情

设置流原始音频数据(PCM)回调。

默认值：无
调用时机：拉流成功后。
影响范围：无
相关回调：无
相关接口：无。
平台差异：无

支持版本：3.2.0
使用限制：无
注意事项：1. 拉流有音频轨道。

只对 RTC 流或 L3 流有效，无法操作 CDN 拉流。
目前 Chrome 浏览器仅支持 85 以上版本。
由于浏览器限制，必须与页面产生交互后才有数据回调。

setPlayStreamVideoType

setPlayStreamVideoType(streamID: string, streamType: number): Promise<boolean>

设置播放视频流类型

参数

名称	类型	描述
streamID	string	流ID
streamType	number	拉流大小流类型 0 为小流，1为大流，2为自动

详情

当推流方开启大小流后，拉流方可以动态设置选用不同的流类型。

业务场景：一般情况下，在网络较弱或者渲染的 UI 窗体较小的情况下，可以选择使用拉取小分辨率的视频来达到节省带宽的目的。
默认值：无
调用时机：拉流成功后。
影响范围：无
相关回调：无
相关接口：startPlayingStream。
平台差异：无

支持版本：3.8.0
使用限制：无
注意事项：无

muteAllPlayAudioStreams

muteAllPlayAudioStreams(mute: boolean): Promise<boolean>

拉流是否接收所有音频数据（包括之后在房间中新拉取的流）

参数

名称	类型	描述
mute	boolean	停止或恢复拉取所有音频流，true 表示停止拉取；false 表示恢复拉取。

详情

在实时音视频互动过程中，本地用户可根据需要，通过此函数控制拉流时是否接收所有远端用户的音频数据（包括在调用该函数后新加入房间的用户所推的音频流）。默认情况下，用户加入房间后可以接收所有远端用户推送的音频数据。当开发者不接收音频收据时，可降低硬件和网络的开销。

业务场景：当开发者需要快速关闭、恢复远端音频时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：初始化引擎之后。
相关接口：可调用 [mutePlayStreamAudio] 函数控制是否接收单条音频数据。

支持版本：3.3.0

muteAllPlayVideoStreams

muteAllPlayVideoStreams(mute: boolean): Promise<boolean>

拉流是否接收所有视频数据（包括之后在房间中新拉取的流）

参数

名称	类型	描述
mute	boolean	停止或恢复拉取所有视频流，true 表示停止拉取；false 表示恢复拉取。

详情

在实时音视频互动过程中，本地用户可根据需要，通过此函数控制拉流时是否接收所有远端用户的视频数据（包括在调用该函数后新加入房间的用户所推的视频流）。默认情况下，用户加入房间后可以接收所有远端用户推送的视频数据。当开发者不接收视频收据时，可降低硬件和网络的开销。

业务场景：当开发者需要快速关闭、恢复远端视频时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：初始化引擎之后。
相关接口：可调用 [mutePlayStreamVideo] 函数控制是否接收单条视频数据。

支持版本：3.3.0

mutePlayStreamAudio

mutePlayStreamAudio(streamID: string, mute: boolean): Promise<boolean>

停止或恢复拉取音频流

参数

名称	类型	描述
streamID	string	流ID
mute	boolean	是否拉取音频流，true 表示停止拉取；false 表示恢复拉取

详情

只是将数据降低为很小，音频轨还在。

业务场景：观众在某一时段画面，不想听到主播声音时调用。
默认值：无
调用时机：拉流成功后。
影响范围：无
相关回调：无
相关接口：停止或恢复拉取视频流 mutePlayStreamVideo。
平台差异：无

支持版本：1.15.0
使用限制：无
注意事项：1. 停止或恢复拉取音频流的前提是原始流必须有音频轨道，拉流时不能为纯视频。

只对 RTC 流或 L3 流有效，无法操作 CDN 拉流。

getPlayingStreamQuality

getPlayingStreamQuality(streamID: string): ZegoPlayStats | null

获取拉流质量。

参数

名称	类型	描述
streamID	string	流 ID

详情

主动获取正在拉流的流质量。

业务场景：获取当前拉流的分辨率、帧率、码率等质量参数。
调用时机：[startPlayingStream] 推流成功后。
相关回调：拉流质量回调 [playQualityUpdate]。

支持版本：2.15.0 及以上
使用限制：由于 SDK 的流质量参数每 3 秒更新一次，所以该接口的调用间隔建议不要小于 3 秒。

返回值

拉流质量报文，如果获取失败会返回 null。

createLocalStreamView

deprecated

createLocalStreamView(localStream: MediaStream): ZegoStreamView

创建本地媒体流播放器组件实例对象。

参数

名称	类型	描述
localStream	MediaStream	本地媒体流，通过 createStream 接口获取。

详情

创建媒体流播放器组件实例对象，用于播放预览流。

业务场景：需要在界面播放摄像头、屏幕共享等媒体流画面。
调用时机：需要调用接口 createStream 获取媒体流对象作为入参使用。

支持版本：2.17.0 及以上
注意事项：每个媒体流对象相对应只能创建一个媒体流播放器组件实例对象。

已废弃

此函数在 3.0.0 版本及以上已废弃，请参考 3.0.0 及以上版本升级指南更新逻辑。

返回值

媒体流播放器组件实例对象。

createRemoteStreamView

createRemoteStreamView(remoteStream: MediaStream): ZegoStreamView

创建远端媒体流播放器组件实例对象。

参数

名称	类型	描述
remoteStream	MediaStream	远端媒体流，通过 [startPlayingStream] 接口获取。

详情

创建媒体流播放器组件实例对象，用于播放拉流。

业务场景：需要在页面显示拉取的远端媒体流画面。
调用时机：需要调用接口 [startPlayingStream] 获取媒体流对象作为入参使用。

支持版本：2.17.0 及以上
注意事项：每个媒体流对象相对应只能创建一个媒体流播放器组件实例对象。

返回值

媒体流播放器组件实例对象。

startAutoMixerTask

startAutoMixerTask(task: ZegoAutoMixerTask): Promise<ZegoServerResponse>

开始自动混流任务

参数

名称	类型	描述
task	ZegoAutoMixerTask	自动混流任务对象。

详情

本地用户可调用该函数开始自动混流任务，对房间内的所有流进行混流，目前仅支持音频流自动混流。启动自动混流后，会自动混流该房间内所有流的音频，此房间内再发起的推流也会自动混入最后的输出流中。

业务场景：常用于语聊房场景下，需要由客户端发起自动混流任务时。
调用时机：在创建引擎后，如果目标房间已经创建，可调用该函数在目标房间开启自动混流。
相关接口：可调用 [stopAutoMixerTask] 函数，停止自动混流任务。

支持版本：3.5.0 及以上。
注意事项：在同一个房间内开启下一个自动混流任务前，请先调用 [stopAutoMixerTask] 函数结束上一次自动混流任务，以免造成当一个主播已经开启下一个自动混流任务与其他主播混流时，观众依然在一直拉上一个自动混流任务的输出流的情况。若用户未主动结束当前自动混流任务，该任务将在房间不存在之后或者输入流持续 90 秒不存在之后自动结束。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

startMixerTask

startMixerTask(mixStreamConfig: ZegoMixStreamConfig): Promise<ZegoServerResponse>

开始混流任务

参数

名称	类型	描述
mixStreamConfig	ZegoMixStreamConfig	混流参数配置

详情

将多条流按照调用要求合成一条流。由那个点于实际动作是在服务端操作，没有浏览器性能上的限制，且各个流之间延迟低，可以保证被混的多条流画面和声音同步。

业务场景：通常用于多个主播连麦PK的场景，将多个主播的音视频流混合成一条流，观众端只需要拉这一条流。
调用时机：调用接口 startPublishingStream 推流成功后。
相关接口：使用接口 stopMixerTask 来停止服务端混流，未及时停止混流功能会影响计费。

支持版本：1.5.2 及以上。
使用限制：混流前需要保证流还存在，避免发起混流和流删除操作同时触发，以免混流失败。被混的流如果中止推流，需要重新做混流处理，否则对端画面会卡住。
注意事项：1. 应用对应的 AppID 开启了混流功能；2. 被混的流必须在 ZEGO 服务器上存在”。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

stopAutoMixerTask

stopAutoMixerTask(task : { taskID: string; roomID: string; }): Promise<ZegoServerResponse>

停止服务端自动混流任务

参数

名称	类型	描述
task	{ taskID: string; roomID: string; }	停止混流任务相应的任务的 taskID 与房间的 roomID。

详情

本地用户可调用该函数结束自动混流任务。

业务场景：常用于语聊房场景下，需要由客户端发起自动混流任务时。
调用时机：在调用 [startAutoMixerTask] 函数开启自动混流任务后可调用该函数。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

相关接口：开始混流任务接口 [startAutoMixerTask]。

支持版本：3.5.0 及以上。

stopMixerTask

stopMixerTask(taskID: string): Promise<ZegoServerResponse>

停止服务端混流

参数

名称	类型	描述
taskID	string	混流任务 ID（客户自定义，务必保证唯一），必填，最大长度为 256 个字符，仅支持数字、英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '

详情

用于停止 taskID 对应的服务端混流任务。

业务场景：通常用于多个主播连麦 PK 的场景，混流画面使用结束后停止混流。
调用时机：调用接口 startMixerTask 混流成功之后。
相关接口：开始混流任务接口 startMixerTask

支持版本：1.5.2 及以上。
注意事项：关闭页面一定要发起停止混流，避免异常关闭导致混流没有停止，影响计费；被混的流若中止推流，需要重新做混流处理，否则对端画面会卡住。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

setMixerTaskConfig

setMixerTaskConfig(config: ZegoMixStreamAdvance): Promise<ZegoServerResponse>

混流高级配置

参数

名称	类型	描述
config	ZegoMixStreamAdvance	混流高级功能设置。

详情

混流功能进阶设置，可以设置视频背景和视频编码格式。

业务场景：1. 设置混流画面背景；2. 视频编码转换来兼容部分浏览器的播放。
调用时机：推流成功后，而且需在使用 startMixerTask 之前调用才能生效。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

相关接口：开始混流接口 startMixerTask

支持版本：1.5.2 及以上。

startMixingAudio

startMixingAudio(streamID: string | MediaStream | ZegoLocalStream, mediaList: Array<HTMLMediaElement>): boolean

开始混音

参数

名称	类型	描述
streamID	string \| MediaStream \| ZegoLocalStream	需要混音的流 ID 或 MediaStream 对象或者 ZegoLocalStream实例对象。
mediaList	Array<HTMLMediaElement>	1. 本地的 <audio> 或 <video> 对象数组。 2. 对音效的操作（包括暂停/恢复）需要通过操作 <audio> 或 <video> 对象来完成。

详情

将 HTMLMediaElement 对象正在播放的声音混入对应 streamID 的推流中，使正在推的流中包含混入的声音。

业务场景：通常用于背景音乐和音效。
调用时机：调用接口 createStream 或者 createZegoStream 创建流成功后。2.15.0 及以前版本要推流成功后才能调用该接口。
影响范围：大部分接口都需要在登录房间后才能调用。
相关接口：可调用接口 stopMixingAudio 来停止混音。

支持版本：1.7.0 及以上。
使用限制：混音不要同时包含 6 个以上，及 mediaList 长度不要大于 6，否则会出现性能问题，导致页面卡顿。
注意事项：- 需要保证 HTMLMediaElement 可以正常加载。例如为了避免跨域导致资源加载失败，可以在 HTMLMediaElement 上设置属性 crossOrigin = 'anonymous'。
Chrome 浏览器自 86 版本起本地音频标签设置为静音，拉流端也无法听到混入的背景音。
受Safari浏览器策略影响，将audio标签设置为静音，会出现播放后自动暂停、无法混入多条音频的情况。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

stopMixingAudio

stopMixingAudio(streamID: string | MediaStream, mediaList?: Array<HTMLMediaElement>): boolean

停止混音

参数

名称	类型	描述
streamID	string \| MediaStream	正在混音的流 ID 或 MediaStream 对象。
mediaList	Array<HTMLMediaElement>	1. 本地的 <audio> 或 <video> 对象数组，可选。 2. 对音效的操作（包括暂停/恢复）需要通过操作 <audio> 或 <video> 对象来完成。

详情

通过传入的 mediaList ，控制对某个或多个背景音乐或音效的暂停，不传入该参数则停止该流的所有混音。

业务场景：通常用于控制背景音乐和音效的暂停。
调用时机：调用 startMixingAudio 后。2.16.0 及以后版本支持预览阶段操作混音。
影响范围：大部分接口都需要在登录房间后才能调用。
相关接口：开始混音接口 startMixingAudio

支持版本：1.7.0 及以上。
注意事项：通过能力检测接口 checkSystemRequirements 检查到 "customCapture" 为 false ，即浏览器不支持获取媒体元素的 MediaStream，则不能使用该接口。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

setMixingAudioVolume

setMixingAudioVolume(streamID: string | MediaStream, volume: number, media: HTMLMediaElement): boolean

设置混音音量

参数

名称	类型	描述
streamID	string \| MediaStream	推流 ID 或 MediaStream 对象。
volume	number	音量值，范围为 0～100，100 表示原始音量。
media	HTMLMediaElement	媒体标签 <video> 或 <audio>。

详情

通过传入的音量值和媒体元素，调节指定媒体元素的混入音量。

业务场景：通常用于调节背景音乐或音效的音量大小。
调用时机：调用 startMixingAudio 后。2.16.0 及以后版本支持预览阶段操作混音。
影响范围：大部分接口都需要在登录房间后才能调用。
相关接口：开始混音接口 startMixingAudio

支持版本：1.18.0 及以上。
注意事项：Chrome 浏览器自 86 版本起本地音频标签设置为静音，拉流端得到的混入音频没有声音。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

enableLiveAudioEffect

  enableLiveAudioEffect(player: HTMLMediaElement, enable: boolean, mode: ZegoLiveAudioEffectMode): Promise<ZegoServerResponse>

开启或关闭音效增强的功能。

参数

名称	类型	描述
player	HTMLMediaElement	H5 audio 或 video 标签元素对象。
enable	boolean	是否开启现场音效。
mode	ZegoLiveAudioEffectMode	现场音效生效模式。

详情

开启现场音效后，空间感增强、乐器声音增强突出。

业务场景：一般用于语聊房、K 歌场景下，增强伴奏的现场音效。
调用时机：初始化 ZegoExpresEngine 实例后。

支持版本：3.0.0 及以上。
注意事项：1. 为了提升现场音效的体验,我们建议配置双声道编码。开发者可以通过使用 [startCaptureMicrophone] 接口时设置参数 [ZegoCaptureMicrophone.channelCount] 为 2 来实现此配置。如果不进行双声道编码配置,某些歌曲的效果可能会显著降低,因为在合成单声道时,左右声道的效果可能会相互抵消,导致效果不明显。

该接口只能对一个 h5 播放器生效，当对新的 audio 标签进行开启效果时会对其他开启效果的 h5 播放器进行关闭效果。

返回值

异步返回调用结果。

setAudioChangerParam

  setAudioChangerParam(player: HTMLMediaElement, pitch: number, mode: ZegoLiveAudioEffectMode): Promise<ZegoServerResponse>

对传入的歌曲进行变调处理。

参数

名称	类型	描述
player	HTMLMediaElement	H5 audio 或 video 标签元素对象。
pitch	number	音调值，范围[-12.0, 12.0]，数值越大声音越尖，设为 0.0 即关闭变调处理。
mode	ZegoLiveAudioEffectMode	现场音效生效模式。

详情

通过输入不同的pitch值，实现对player进行变调处理。

业务场景：一般用于语聊房、K 歌场景下，实现对伴奏进行升降调处理。
调用时机：初始化 ZegoExpresEngine 实例后。

支持版本：3.2.0 及以上。
注意事项：1. 歌曲变调 setAudioChangerParam 同音质增强接口enableLiveAudioEffect同时使用时，都只该接口只能对一个 h5 播放器生效，当对新的 audio 标签进行开启效果或者setAudioChangerParam与enableLiveAudioEffect传入的 h5 播放器不同时，先开启效果处理的 h5 播放器会进行关闭效果。即setAudioChangerParam与enableLiveAudioEffect不可对多个audio生效。

返回值

异步返回调用结果。

createAudioEffectPlayer

createAudioEffectPlayer(localStream: MediaStream | ZegoLocalStream): ZegoAudioEffectPlayer

创建音效播放器实例对象。

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。

详情

创建音效播放器实例对象，用于在媒体流对象上控制播放实时音效。

业务场景：当需要播放简短的声音效果，比如鼓掌，欢呼声等时，可以使用音效播放器来实现。
调用时机：需要调用接口 createStream 或者 createZegoStream 获取媒体流对象作为入参使用。

支持版本：2.15.0 及以上
注意事项：

每个媒体流对象相对应只能创建一个有效播放器实例对象。
2.15.0 版本需要先完成推流才可进行操作对应流的播放器。2.16.0 及以后版本支持在推流前操作流的音效播放器。

返回值

音效播放器实例对象。

loadAudioEffect

loadAudioEffect(audioEffectID: string, path: string): Promise<string>

加载音效资源。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。
path	string	指定在线音效文件的请求路径。支持以下音频格式：MP3，AAC 以及浏览器支持的其他音频格式。

详情

加载音效资源。

业务场景：在频繁播放相同音效场景中，SDK 为了减少重复读文件并解码的网络和性能资源浪费，提供了预加载音效文件到内存中的功能。
调用时机：在 [createAudioEffectPlayer] 之后可调用。
相关接口：播放音效接口 [ZegoAudioEffectPlayer.start]、释放音效接口 [unloadEffect]。

支持版本：2.15.0 及以上
注意事项：

在线音频文件需要符合浏览器的同源策略。
支持以下音频格式：MP3，AAC 以及浏览器支持的其他音频格式。

返回值

异步返回音效资源 ID。

unloadAudioEffect

unloadAudioEffect(audioEffectID: string): boolean

释放音效资源。

参数

名称	类型	描述
audioEffectID	string	音效资源的 ID。

详情

释放指定音效 ID 的音效资源。

业务场景：在音效使用完毕之后，可以通过该接口释放相关资源。
调用时机：在 [loadAudioEffect] 之后可调用。
相关接口：加载音效接口 [loadAudioEffect] 。

支持版本：2.15.0 及以上
注意事项：无。

返回值

接口是否调用成功。

enumDevices

enumDevices(): Promise<ZegoDeviceInfos>

获取设备硬件信息，为操作硬件设备接口提供设备id参数。

获取设备硬件信息，为控制硬件设备接口，提供设备 id 参数。

业务场景：需要指定采集设备和输出设备时使用。
默认值：无
调用时机：初始化之后，创建流之前调用。
影响范围：无
相关回调：无
相关接口：createStream 、createZegoStream、useAudioDevice、useVideoDevice。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：1. 需要在安全域名下（https,localhost,127.0.0.1）调用该接口。

调用该接口前需要获取设备权限，可以通过调用 checkSystemRequirements("camera") 来授权获取摄像头权限，通过调用 checkSystemRequirements("microphone") 来授权获取麦克风权限。
不能完全信赖该接口，要对获取不到设备信息的情况做降级处理，例如：提示客户更换浏览器。
某些平台浏览器（如：Safari，iOS）可能获取到的设备名称为空，建议再次调用此接口，即可获取到正确的设备名称。
页面刷新后设备 ID 可能会有变化，需要重新获取。
部分浏览器需要在调用 createStream 或者 createZegoStream 接口获取权限后，才可以获取到设备 ID。
safari 不支持获取扬声器信息。

getCameras

getCameras(): Promise<ZegoDeviceInfo[]>

获取摄像头设备列表，为操作硬件设备接口提供设备id参数。

该方法枚举可用的视频输入设备，比如摄像头。

业务场景：需要指定视频输入设备。
默认值：无
调用时机：初始化之后，创建流之前调用。
影响范围：无
相关回调：无
相关接口：createStream、useVideoDevice、 createZegoStream。
平台差异：无

支持版本：2.14.0 及以上
使用限制：无
注意事项：1. 由于浏览器对安全和隐私的保护，页面需要在安全环境下（https,localhost,127.0.0.1）调用该接口。参考 Privacy and security。

在没有授予页面设备权限的情况下，调用该方法会暂时打开摄像头以触发浏览器的摄像头设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

返回摄像头设备列表信息。

getMicrophones

getMicrophones(): Promise<ZegoDeviceInfo[]>

获取麦克风设备列表，为操作硬件设备接口提供设备id参数。

该方法枚举可用的音频输入设备，比如麦克风。

业务场景：需要指定采集音频设备。
默认值：无
调用时机：初始化之后，创建流之前调用。
影响范围：无
相关回调：无
相关接口：createStream、createZegoStream、useAudioDevice。
平台差异：无

支持版本：2.14.0 及以上
使用限制：无
注意事项：1. 由于浏览器对安全和隐私的保护，页面需要在安全环境下（https,localhost,127.0.0.1）调用该接口。参考 Privacy and security。

在没有授予页面设备权限的情况下，调用该方法会暂时打开麦克风以触发浏览器的麦克风设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
Windows Chrome 中会有一个 deviceID 为 'communications' 的麦克风设备，这个麦克风是 Chrome 基于真实麦克风做的一次封装，该麦克风会受 Windows 的声音通信配置受限。业务上避免使用该设备。

返回音频输入设备列表信息。

getSpeakers

getSpeakers(): Promise<ZegoDeviceInfo[]>

获取扬声器设备列表，为操作硬件设备接口提供设备id参数。

该方法枚举可用的音频输出设备，比如耳机、音箱。

业务场景：需要指定媒体流的音频输出设备。
默认值：无
调用时机：初始化之后，创建流之前调用。
影响范围：无
相关回调：无
相关接口：指定音频输出设备接口 [useAudioOutputDevice]。
平台差异：无

支持版本：2.14.0 及以上
使用限制：无
注意事项：1. 由于浏览器对安全和隐私的保护，页面需要在安全环境下（https,localhost,127.0.0.1）调用该接口。参考 Privacy and security。

在没有授予页面设备权限的情况下，调用该方法会暂时打开麦克风以触发浏览器的扬声器设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
Safari 不支持获取扬声器信息。

返回音频输出设备列表信息。

useFrontCamera

useFrontCamera(localStream: MediaStream | ZegoLocalStream, enable: boolean): Promise<ZegoServerResponse>

切换前后摄像头

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
enable	boolean	是否采用前置摄像头；"true" 表示使用前置摄像头；"false" 表示使用后置摄像头

详情

控制使用前置摄像头或者后置摄像头(仅 Android 和 iOS 支持)。

业务场景：主播切换摄像头设备。
默认值：无
调用时机：创建流成功后，且流类型必须是摄像头类型采集流。
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：3.2.0
使用限制：无
注意事项：如果切换摄像头失败，原来的流会保留，并返回错误。

useVideoDevice

useVideoDevice(localStream: MediaStream | ZegoLocalStream, deviceID: string): Promise<ZegoServerResponse>

切换摄像头

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
deviceID	string	需要切换的摄像头设备 ID

详情

切换当前推流使用的设备。

业务场景：主播切换摄像头设备。
默认值：无
调用时机：创建流成功后，且流类型必须是摄像头类型采集流。
影响范围：无
相关回调：无
相关接口：切换麦克风 useAudioDevice。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：如果切换摄像头失败，原来的流会保留，并返回错误。

useAudioDevice

useAudioDevice(localStream: MediaStream | ZegoLocalStream, deviceID: string): Promise<ZegoServerResponse>

切换麦克风

参数

名称	类型	描述
localStream	MediaStream \| ZegoLocalStream	createStream 创建得到的 stream 或者 createZegoStream创建得到的 ZegoLocalStream实例对象。
deviceID	string	需要切换的麦克风设备 ID

详情

切换当前推流使用的麦克风设备。

业务场景：主播切换外接麦克风，使用硬件自带的音效处理。
默认值：无
调用时机：创建流成功后，且流类型必须是 createStream 或者createZegoStream创建的 camera 类型麦克风媒体流。
影响范围：无
相关回调：无
相关接口：切换摄像头 useVideoDevice。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：如果切换麦克风失败，原来的流会保留，并返回错误。

useAudioOutputDevice

useAudioOutputDevice(media: HTMLMediaElement, deviceID: string): Promise<boolean>

切换音频输出设备。

参数

名称	类型	描述
media	HTMLMediaElement	媒体标签元素，<audio> 或 <video>。
deviceID	string	扬声器设备 ID。

详情

设置 html 媒体元素的音频输出设备。

调用时机：用 [getSpeakers] 获取音频输出设备列表后。
相关接口：获取扬声器列表接口 [getSpeakers]。

支持版本：2.15.0 及以上
注意事项：该接口当前只支持 Chrome 浏览器使用。

返回值

Promise 返回 boolean 标识是否调用成功。

setSoundLevelDelegate

setSoundLevelDelegate(bool: boolean, interval?: number, options?: SoundLevelDelegateOptions): void

设置是否监听音浪及音浪回调间隔时间

参数

名称	类型	描述
bool	boolean	开启或关闭音浪回调
interval	number	需要回调的时间间隔，默认1000ms，可选。最低可设置500ms，最高设置3000ms。
options	SoundLevelDelegateOptions	设置选项。

详情

设置后将通过 soundLevelUpdate 回调流的音量大小。

业务场景：图形化显示拉流音浪时调用。
默认值：无
调用时机：初始化实例后。
影响范围：无
相关回调：推拉流音浪回调 soundLevelUpdate 、本地预览流音浪回调 capturedSoundLevelUpdate。
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：无

isMicrophoneMuted

isMicrophoneMuted(): boolean

获取麦克风静音状态

获取麦克风静音状态。

业务场景：用于判断主播自己的麦克风是否打开了。
调用时机：调用 loginRoom 接口登录房间成功后。
相关接口：调用 muteMicrophone 关闭/打开麦克风声音接口。

支持版本：2.8.0 及以上。

是否静音，true 为静音，false 为打开麦克风声音。

muteMicrophone

muteMicrophone(mute: boolean): boolean

是否静音麦克风声音

参数

名称	类型	描述
mute	boolean	是否静音麦克风；true 表示静音麦克风；false 表示打开麦克风；不设置默认为 false。

详情

将麦克风的声音静音，推流时也不会带上麦克风采集的声音。

业务场景：主播在某一时段内，不希望被拉流端听到麦克风声音时调用。如果您在混音功能时需要保留混入的背景音乐，则调用 muteMicrophone 接口可以将麦克风静音，而不影响推流的背景音乐。对应的如果想将推出去的所有音频数据静音，则可以参考调用 mutePublishStreamAudio 接口。
调用时机：初始化实例后。
相关接口：调用 isMicrophoneMuted 接口获取麦克风静音状态；调用 mutePublishStreamAudio 接口关闭/打开正在推流的声音。

支持版本：2.8.0 及以上。
注意事项：是否静音麦克风的前提是原始流必须有音频轨道，创建流时不能为纯视频。

createRangeAudioInstance

createRangeAudioInstance(): ZegoExpressRangeAudio

创建范围语音实例对象。

业务场景：常用于语音游戏场景中，用户可通过创建的范围语音实例对象使用范围语音相关功能。
调用时机：创建 ZegoExpressEngine 实例后并在调用接口 loginRoom 登录房间前调用。

支持版本：2.10.0 及以上
注意事项：使用范围语音功能不能再调用 startPublishingStream 、startPlayingStream 这些推拉流接口以及相关回调。

范围语音实例对象

createRealTimeSequentialDataManager

createRealTimeSequentialDataManager(roomID: string): ZegoRealTimeSequentialDataManager

创建实时有序数据实例对象

参数

名称	类型	描述
roomID	string	房间ID

详情

实时有序数据实例对象。

业务场景：常用于远程控制场景中，用户可通过创建的实时有序数据实例对象使用实时有序数据令相关功能。
调用时机：创建 ZegoExpressEngine 实例后调用。

支持版本：2.12.2 及以上

返回值

实时有序数据实例对象

destroyRealTimeSequentialDataManager

destroyRealTimeSequentialDataManager(manager: ZegoRealTimeSequentialDataManager): void

销毁实时有序数据实例对象

参数

名称	类型	描述
manager	ZegoRealTimeSequentialDataManager	实时有序数据对象

详情

销毁实时有序数据实例对象。

业务场景：常用于远程控制场景中，用户可通过创建的实时有序数据实例对象使用实时有序数据相关功能。
调用时机：创建 ZegoExpressEngine 实例及 createRealTimeSequentialDataManager 后调用。

支持版本：2.12.2 及以上

createCopyrightedMusic

createCopyrightedMusic(): ZegoCopyrightedMusic

创建版权音乐实例对象。

业务场景：常用于在线 KTV 合唱场景中，用户可通过创建版权音乐实例对象使用相关功能。
调用时机：在初始化引擎实例之后。

支持版本：2.24.5 及以上
使用限制： SDK 只支持创建一个实例，多次调用此函数返回同一个对象。

版权音乐实例，多次调用此函数返回同一个对象。

destroyCopyrightedMusic

destroyCopyrightedMusic(): void

销毁版权音乐实例对象。

调用时机：在初始化引擎实例之后。

支持版本：2.24.5 及以上

enableMultiRoom

enableMultiRoom(enable: boolean): boolean

是否开启多房间模式

参数

名称	类型	描述
enable	boolean	是否开启，true 为开启，false 为关闭。

详情

是否需要开启多房间，同一个用户可以同时加入多个房间，并同时在多个房间内推流、拉流、发送实时消息和接收消息回调。

业务场景：用于跨房间连麦和在线教育的超级小班场景。
默认值：默认不开启多房间。
调用时机：需要在初始化 SDK 后，第一次登录房间 loginRoom 前调用。
相关接口：可调用 loginRoom 登录房间，调用 logoutRoom 退出房间，调用 startPublishingStream 开始推流。

支持版本：2.8.0 及以上。
使用限制：一次完整的生命周期内只能调用一次。

setLogConfig

setLogConfig(config: ZegoLogConfig): boolean

日志高级配置

参数

名称	类型	描述
config	ZegoLogConfig	日志相关高级配置

详情

配置客户端打印日志级别和远端日志上传级别，日志是定位问题的重要手段。

业务场景：在多数场景下，客户不用调用该接口，使用默认配置即可。
默认值：本地日志和上传级别均为 info。
调用时机：在初始化之后，其他任何接口之前调用。
相关回调：无
相关接口：无

支持版本：1.0.0
使用限制：无，但建议整个生命周期内只调用一次。
注意事项：除非有明确的特殊需求，否则请勿调用该接口更改默认配置。

返回值

调用是否成功; 失败情况: 输入参数格式有误

setDebugVerbose

setDebugVerbose(enable: boolean): void

是否开启Debug模式，打开时错误信息 alert 提示，默认测试环境开启

参数

名称	类型	描述
enable	boolean	是否打开 debug 模式;默认sdk会自动判断

详情

打开或关闭错误弹窗提示。

业务场景：用于开发环节提示错误。
默认值：测试环境默认值为 “true“，可以手动关闭。
调用时机：初始化后，立刻调用。
影响范围：所有 SDK 内部错误，都会弹框提示，中断整个进程。
相关回调：无
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：建议保持默认行为，尽量不使用该接口。

getVersion

getVersion(): string

获取当前SDK版本

需要查看当前版本时调用。

业务场景：日志收集时建议使用。
默认值：无
调用时机：初始化后任意时机可调用。
影响范围：无
相关回调：无
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：无

为 string 字符串，例如“1.0.0.标识”

loginRoom

loginRoom(roomID: string, token: string, user: ZegoUser, config?: ZegoRoomConfig): Promise<boolean>

登录房间

参数

名称	类型	描述
roomID	string	房间 ID，由开发者自己生成，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '/'。
token	string	登录验证 token，是通过在即构控制台注册项目获得密钥，加上指定算法获得。测试阶段可以通过 ZEGO 提供的接口获取，正式环境一定要用户自己实现。
user	ZegoUser	登录用户信息。
config?	ZegoRoomConfig	房间相关配置，可选。

详情

登录房间，同房间用户共享流、消息、用户等信息变化。

业务场景：通过登录房间来获取与其他用户进行音视频或消息互动的接口权限。
调用时机：初始化且获取到 token 之后。
隐私保护声明：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。
影响范围：大部分接口都需要在登录房间后才能调用。
相关回调：房间状态回调 roomStateChanged，2.16.0 之前请使用 roomStateUpdate。
相关接口：可调用 logoutRoom 接口退出房间。

支持版本：1.0.0 及以上。
注意事项：

token 是使用登录房间的钥匙，需要开发者自行实现，为保证安全，一定要在开发者自己的服务端生成 token，参考文章登录房间鉴权。
默认为单房间模式，同一个用户（即 userID 相同）不能同时登录两个及以上房间。
若想监听房间内其他用户的变化，则 config 对象下的 “userUpdate” 参数必须设置为 “true”。
如果房间不存在，loginRoom会创建并登录房间。

返回值

promise 异步返回登录结果，true 表示登录成功，false 表示登录失败。

switchRoom

switchRoom(fromRoomID: string, toRoomID: string, config: ZegoSwitchRoomConfig): Promise<boolean>

切换房间

参数

名称	类型	描述
fromRoomID	string	当前已经登录过的房间 ID，由开发者自己生成，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '/'。
toRoomID	string	需要切换的房间 ID（必须是未登录的房间 ID），由开发者自己生成，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '/'。
config	ZegoSwitchRoomConfig	房间相关配置，token 必填

详情

切换房间，快速的从当前房间切换到另外的房间。

业务场景：便捷的实现不同房间之间的切换，比如从直播切换到1v1房间。
调用时机：登录房间成功后。
隐私保护声明：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。
影响范围：大部分接口都需要在登录房间后才能调用。
相关回调：房间状态回调 roomStateChanged，2.16.0 之前请使用 roomStateUpdate。
相关接口：可调用 logoutRoom 接口退出房间。

支持版本：3.7.0 及以上。
注意事项：

token 是登录 toRoomID 房间的钥匙，需要开发者自行实现，为保证安全，一定要在开发者自己的服务端生成 token，参考文章登录房间鉴权。
fromRoomID 必须是已经登录的房间 ID，toRoomID 必须是未登录的房间 ID，若该房间不存在则会创建新的房间。
切换房间会停止当前房间的所有推流和拉流，但不会停止预览，如果要停止预览，用户可以调用 destroyStream 销毁预览流。
如果设置了CDN手动转推，切换房间时不会自动停止，需要用户自己手动停止CDN转推。

返回值

promise 异步返回登录结果，true 表示登录成功，false 表示登录失败。

logoutRoom

logoutRoom(roomID?: string): void

退出房间，不再接受各种房间内状态

参数

名称	类型	描述
roomID?	string	和登录房间的roomID保持一致，可选

详情

退出房间，结束同房间用户共享流、消息、用户等信息变化。

业务场景：结束音视频通话或其他功能后需要调用该接口退出房间，以保证对端能及时同步本端当前状态。调用该接口后会向 ZEGO 服务器发送退出房间信令，然后重置当前房间中用户与 ZEGO 服务器进行交互所需的关键数据，并置空 websocket 对象。
默认值：无
调用时机：登录房间成功后。
影响范围：大部分接口都在退出房间后，不能再调用。
相关回调：房间状态回调 roomStateChanged，2.16.0 之前请使用 roomStateUpdate。
相关接口：可调用 loginRoom 接口登录房间。
平台差异：无

支持版本：1.0.0
使用限制：无
注意事项：无

renewToken

renewToken(token: string, roomID?: string): boolean

更新房间权限token

参数

名称	类型	描述
token	string	指定算法生成的token, 即构提供生成token的不同语言版SDK;
roomID	string	房间 ID，最大长度为 128 字节的字符串。仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '/',

详情

token权限变更,或者token过期时调用,更新token权限

业务场景：登录权限和推流权限隔离时使用, 利用token控制权限
默认值：无
调用时机：登录房间后,主动变更用户在房间内的权限; 登录房间后,收到token将要过期回调;
影响范围：token内包含的过期时间,在过期前30s会触发tokenWillExpire回调
相关回调：房间token将要过期回调tokenWillExpire
相关接口：无
平台差异：无

支持版本：2.6.0
使用限制：无
注意事项：token是使用登录房间的钥匙, 这个是需要客户自己实现,为保证安全,一定要在自己的服务端生成token

返回值

true: 调用成功, false: 调用失败 (SDK 初步格式校验)

setRoomExtraInfo

setRoomExtraInfo(roomID: string, key: string, value: string): Promise<ZegoServerResponse>

设置房间附加消息

参数

名称	类型	描述
roomID	string	房间 ID
key	string	附加消息键
value	string	附加消息值

详情

该功能可以设置一个以房间为单位的附加消息，该消息跟随整个房间的生命周期，每个登录到房间的用户都能够同步消息。

业务场景：开发者可用于实现各种业务逻辑，如房间公告等等。
默认值：无
调用时机：登录房间成功之后。
影响范围：大部分接口都需要在登录房间后才能调用。
相关回调：房间附加信息回调 roomExtraInfoUpdate。
相关接口：无
平台差异：无

支持版本：1.0.0
使用限制：关于此接口的使用限制，请参考 https://doc-zh.zego.im/article/7584 或联系 ZEGO 技术支持。
注意事项：目前房间附加消息只允许设置一个键值对，且 key 最大长度为 10 字节，value 最大长度为 100 字节。

安全性提醒: 请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

sendBarrageMessage

sendBarrageMessage(roomID: string, message: string): Promise<ZegoServerResponse>

发送房间弹幕消息（消息不保证可靠）

参数

名称	类型	描述
roomID	string	房间Id
message	string	消息内容，长度不超过1024字节

详情

向 roomID 对应的房间内所有用户发送弹幕消息，消息不保证可靠。

业务场景：房间内用户发送弹幕消息互动。
调用时机：调用接口 loginRoom 登录房间成功之后。
相关回调：房间内用户可以通过房间弹幕消息通知回调 IMRecvBarrageMessage 来接收消息。

支持版本：1.0.0 及以上。
使用限制：关于此接口的使用限制，请参考 https://doc-zh.zego.im/article/7584 或联系 ZEGO 技术支持。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

sendBroadcastMessage

sendBroadcastMessage(roomID: string, message: string): Promise<ZegoServerResponse>

发送房间广播消息（消息保证可靠）

参数

名称	类型	描述
roomID	string	房间 ID。
message	string	消息内容，长度不超过1024 字节。

详情

向 roomID 对应的房间内所有用户发送文本消息。

业务场景：房间内用户发送消息聊天互动，例如语聊房。
调用时机：调用接口 loginRoom 登录房间成功之后。
影响范围：需要在登录房间后才能调用。
相关回调：其他房间用户可以通过广播消息通知回调 IMRecvBroadcastMessage 来接收消息。

支持版本：1.0.0 及以上。
使用限制：关于此接口的使用限制，请参考 https://doc-zh.zego.im/article/7584 或联系 ZEGO 技术支持。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

sendCustomCommand

sendCustomCommand(roomID: string, message: string, toUserIDList: string[]): Promise<ZegoServerResponse>

发送自定义信令（消息可靠）

参数

名称	类型	描述
roomID	string	房间 ID。
message	string	自定义消息内容，长度不超过 1024 字节。
toUserIDList	string[]	目标用户uerId 数组。传入空数组则表示是发送给房间内所有用户。

详情

向 roomID 对应的房间内指定用户发送自定义消息，消息保证可靠。

业务场景：私聊个别用户。
调用时机：登录房间成功之后。
影响范围：大部分接口都需要在登录房间后才能调用。
相关回调：房间内用户可以通过监听自定义命令信令回调 IMRecvCustomCommand 来接收消息。

支持版本：1.0.0 及以上。
使用限制：关于此接口的使用限制，请参考 https://doc-zh.zego.im/article/7584 或联系 ZEGO 技术支持。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

sendTransparentMessage

sendTransparentMessage(roomID: string, message: ZegoRoomSendTransparentMessage): Promise<ZegoServerResponse>

发送透传消息

参数

名称	类型	描述
roomID	string	房间 ID。
message	ZegoRoomSendTransparentMessage	发送透传消息的结构信息。

详情

向房间内发送透传消息。

业务场景：一般用于远程控制信令或用户与用户之间的消息发送。
调用时机：登录房间成功之后。
影响范围：大部分接口都需要在登录房间后才能调用。
相关回调：当发送的消息， mode 指定为 ZegoRoomTransparentMessageModeOnlyClient 或者 ZegoRoomTransparentMessageModeClientAndServer 可通过 [recvRoomTransparentMessage] 接收到发送消息的内容。

支持版本：3.11.0 及以上。
使用限制：同一房间内向单个用户发送的自定义消息频率不能高于 200条/s 。

安全性提醒：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

ZegoExpressPlayer

Zego Web Express SDK 播放器插件

详情

Web 端播放器插件，用于拉直播 CDN 流。

业务场景：直播拉取 CDN 流。

属性

played

played: boolean

只读，播放器播放状态，为 true 代表正在播放 CDN 资源。

paused

paused: boolean

只读，播放器暂停状态，为 true 代表播放器当前并没有在渲染 CDN 资源。

volume

volume: number

只读，播放器当前播放设置的音量大小，取值范围区间为 [0,100]，可通过 [setVolume] 接口修改。

currentTime

currentTime: number

只读，当前播放时间，即当前渲染帧的 pts 值，精度到后两位小数，单位是秒。使用事件回调 [onTimeUpdate] 可监听播放时间的变化。

muted

muted: boolean

只读，当前播放状态是否静音，为 true 时代表播放器被静音。

mediainfo

mediainfo: MediaInfo

只读，当前播放的媒体资源信息，可通过监听回调 [onMediaInfoUpdate] 得知该属性的变更。

src

src: string

当前拉取的 CDN 直播流的 URL 地址。设置该值后，播放器会立即请求并拉取对应的 CDN 直播流，拉取到媒体资源后不会自动播放，您还需要调用 [play] 接口开启渲染。

方法

ZegoExpressPlayer

static

ZegoExpressPlayer

ZegoExpressPlayer(engine: ZegoExpressEngine, config: ZegoExpressPlayerConfig): ZegoExpressPlayer

播放器插件构造函数

参数

名称	类型	描述
engine	ZegoExpressEngine	Zego Web Express SDK 的引擎实例对象
config	ZegoExpressPlayerConfig	播放器插件的初始化配置

详情

实例化播放器插件。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

返回值

播放器实例

verify

verify(token: string, userID: string): Promise<boolean>

播放器鉴权

参数

名称	类型	描述
token	string	输入 token，与房间登录的 token 生成方式一致。
userID	string	用户 userID，与生成 token 的 userID 保持一致，用于播放器鉴权。

详情

播放器鉴权

业务场景：初始化播放器之后，如果 SDK 没有登录房间，则需要对播放器插件进行鉴权。
调用时机：播放器实例化之后，在其他接口使用之前调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

返回值

鉴权结果，返回结果为 true 表示鉴权成功，为 false 是鉴权失败。

play

play(): void

播放器开始播放

开始播放 CDN 资源。

业务场景：播放器初始化和指定 CDN 资源后，开始播放 CDN 资源。
调用时机：播放器实例化、鉴权之后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

pause

pause(): void

播放器暂停播放

暂停播放 CDN 资源。

业务场景：在播放 CDN 资源时，暂停播放。
调用时机：播放器开始拉取 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。
注意事项：暂停播放时，为了尽可能同步到最新的 CDN 直播进度，在暂停过程中，播放器会进行丢帧处理。

resume

resume(): void

播放器重新拉取当前 CDN 直播流。

业务场景：如 CDN 资源异常等场景，需要重新拉取 CDN 资源时使用。
调用时机：播放器拉取 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

stop

stop(): void

停止播放资源，不在加载当前指定的媒体

停止播放 CDN 资源。

业务场景：播放器开始播放 CDN 资源后，停止播放资源。
调用时机：播放器实例化、鉴权之后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

fullScreen

fullScreen(): void

播放器全屏播放

播放器全屏播放。

业务场景：播放器全屏播放 CDN 资源。
调用时机：播放器开始拉取 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

destroy

destroy(): void

销毁播放器插件

销毁播放器，释放播放器占用等内存和 CPU 资源。

业务场景：播放器生命周期的终点，不再需要播放器播放媒体资源时，需要消耗播放器实例。
调用时机：播放器实例化之后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

setVolume

setVolume(): void

播放器设置音量大小

设置播放器的音量大小，取值区间范围为 [0, 100]。

业务场景：播放器设置当前播放资源的音量大小。
调用时机：播放器实例化和鉴权之后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

getPlayQuality

getPlayQuality(): QualityStats

播放器获取流质量

播放器获取流质量，流质量统计间隔为 1s。

业务场景：播放器获取流质量。
调用时机：播放器开始播放成功之后。

支持版本：播放器插件版本 1.3.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

setMuted

setMuted(mute: boolean): void

播放器设置播放静音开关

参数

名称	类型	描述
mute	boolean	设置静音状态，值为 true 时表示开启静音，为 false 时表示关闭静音。

详情

播放器播放静音开关。

业务场景：修改播放器播放静音状态。
调用时机：播放器实例化和鉴权之后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

setBufferInterval

setBufferInterval(intervals: BufferIntervals): void

播放器设置 buffer 间隔

参数

名称	类型	描述
intervals	BufferIntervals	buffer 间隔

详情

设置 buffer 间隔。

调用时机：播放器开始播放成功之后。

支持版本：播放器插件版本 1.3.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

enableSoundLevelMonitor

enableSoundLevelMonitor(enable: boolean, millisecond?: number, options?: SoundLevelDelegateOptions): void

设置是否开启监听音浪及音浪回调间隔时间

参数

名称	类型	描述
enable	boolean	开启或关闭音浪回调
millisecond	number	需要回调的时间间隔，默认1000ms，可选。最低可设置500ms，最高设置3000ms。
options	SoundLevelDelegateOptions	设置选项。

详情

获取播放器播放音频的实时音浪。

业务场景：图形化显示拉流音浪时调用。
默认值：无
调用时机：初始化实例后。
影响范围：无
相关回调：推拉流音浪回调 onSoundLevelUpdate 。
相关接口：无
平台差异：无

支持版本：1.5.0
使用限制：Safari 浏览器上使用 MSE (Media Source Extensions) 的解码方式播放音频无法获取音浪，如果需要获取音浪避免在 Safari 浏览器上使用 MSE 的解码方式。
注意事项：无

onCanPlay

onCanPlay(): void

播放器 CDN 资源可播放回调

已经解析出资源元数据，可以播放媒体文件了。您可以在这个回调中取消渲染 Loading 控件提示用户视频可以开始播放。

业务场景：可监听该回调提示用户当前 CDN 资源可以开始播放。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onPlay

onPlay(): void

播放器渲染（播放）开始回调

播放器开始播放 CDN 资源的回调，这个回调触发代表播放器已经开始渲染音视频资源。

业务场景：可监听该回调判断 CDN 资源是否已经开始渲染，并进行相关 UI 变化，如去除视频遮罩等。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onPaused

onPaused(): void

播放器渲染（播放）暂停的回调

播放器暂停渲染 CDN 资源的回调，这个回调触发代表播放器暂停了渲染音视频资源。

业务场景：可监听该回调判断 CDN 资源是否已经开始渲染，并进行相关 UI 变化，如打开视频遮罩或渲染播放按钮等。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onLoaded

onLoaded(): void

CDN 媒体资源加载结束回调

播放器加载到 CDN 媒体资源结束时会触发该回调。

业务场景：通过该回调判断是否 CDN 资源已经加载完。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onTimeUpdate

onTimeUpdate(): void

当前播放时间改变的回调

当前播放时间，即当前渲染帧的 pts 改变时触发该回调，触发频率最高 0.01s 一次，实际触发频率受 CDN 媒体资源的帧率、采样率等因素数据影响。

业务场景：可监听该回调获取当前直播资源的播放进度。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onWaiting

onWaiting(): void

由于暂时缺少数据，播放已停止。

播放器因缺少 CDN 媒体数据暂停渲染，以等待加载足够多的数据。相关的回调可以参考 [onPlaying]。

业务场景：您可以在这个回调中渲染 Loading 控件等 UI 界面，以提示用户视频正在加载。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onPlaying

onPlaying(): void

播放已经加载到足够多的数据，开始恢复播放。

播放加载到足够多的数据，开始恢复播放。通常是在触发 [onWaiting] 后，当播放器缓冲了足够数据后解除缓冲状态并恢复播放。如果播放器此时已经被暂停，则不会自动恢复渲染。

业务场景：您可以在这个回调中隐藏 Loading 控件等 UI 界面，以提示用户视频缓冲完成。
调用时机：播放器设置 CDN 资源后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onError

onError(err: ZegoExpressPlayerError): void

播放器错误回调

参数

名称	类型	描述
err	ZegoExpressPlayerError	错误码和错误信息

详情

播放器触发错误时，回调错误码和错误信息。

业务场景：您可以监听该回调，当播放器触发错误时，进行相关的业务处理。
调用时机：播放器初始化并鉴权后调用。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onMediaInfoUpdate

onMediaInfoUpdate(mediaInfo: MediaInfo): void

播放的 CDN 资源媒体信息更新回调

参数

名称	类型	描述
mediaInfo	MediaInfo	播放器解析到的 CDN 资源的媒体信息

详情

播放器解析到的 CDN 资源媒体信息更新回调，随着 CDN 资源中的媒体数据逐步被解析，该回调可能会被触发多次。

业务场景：您可以监听该回调以记录相关的媒体信息数据，进行相关的业务操作。
调用时机：播放器开始播放 CDN 资源后。

支持版本：播放器插件版本 1.0.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onResetPlayQuality

onResetPlayQuality(quality: QualityStats): void

播放器重置流质量统计数据时的回调

参数

名称	类型	描述
quality	QualityStats	播放器的流质量统计数据

详情

当播放器重置流质量统计数据时，会触发该回调并抛出上一次的统计数据。

业务场景：您可以监听该回调来准确的获取播放器重置前的流质量统计数据。当重新加载资源的时候，就会触发重置流质量统计数据（比如设置 src，调用 resume）。
调用时机：实例化播放器后。

支持版本：播放器插件版本 1.3.1 及以上，依赖 Express SDK 3.0.0 及以上版本。

onRecvSEI

onRecvSEI(byte: Uint8Array): void

播放器接收 SEI 数据的回调

参数

名称	类型	描述
byte	Uint8Array	播放器收到的 SEI 数据

详情

当播放器收到 SEI 数据时，会触发该回调。

业务场景：您可以监听该回调来获取视频的 SEI 数据。
调用时机：实例化播放器后。

支持版本：播放器插件版本 1.3.0 及以上，依赖 Express SDK 3.0.0 及以上版本。

onSoundLevelUpdate

onSoundLevelUpdate(soundLevel: number): void

播放音频的音浪回调

参数

名称	类型	描述
soundLevel	number	本地采集的声浪值，取值范围为 0.0 ~ 100.0 。

详情

通过 enableSoundLevelMonitor 开启获取音浪，播放声音时会触发该回调。

业务场景：您可以监听该回调来获取实时播放的音浪。
调用时机：实例化播放器后。

支持版本：播放器插件版本 1.5.0 及以上。

ZegoExpressRangeAudio

范围语音

详情

常用于语音游戏场景中，用户可通过创建的范围语音实例对象使用范围语音相关功能。

方法

getInstance

static

getInstance

getInstance(engine: any, logger: any): ZegoExpressRangeAudio

名称	类型	描述
engine	any	-
logger	any

setVoiceChangerParam

web setVoiceChangerParam(voiceParam: number): Promise<ZegoServerResponse>

范围语音对媒体流进行自定义参数设置变声处理。

参数

名称	类型	描述
voiceParam	number	变声自定义参数值，取值范围 [-12.0, 12.0]，数值越大声音越尖，设为 0.0 即关闭变声器

详情

将推送的媒体流进行自定义参数设置变声处理。

业务场景：推流前或推流中切换变声。
默认值：无

支持版本：3.0.0
注意事项：1. 目前仅支持对特定的一条流进行变声处理，不支持同时对多条流同时变声；

setVoiceChangerPreset

web setVoiceChangerPreset(preset: ZegoVoiceChangerPreset): Promise<ZegoServerResponse>

范围语音对媒体流进行变声处理。

参数

名称	类型	描述
preset	ZegoVoiceChangerPreset	变声预设值

详情

将推送的媒体流进行变声处理。

业务场景：推流前或推流中切换变声。
默认值：无
调用时机：调用接口 [createStream] 创建流成功后。

支持版本：2.24.0
注意事项：1. 目前仅支持对特定的一条流进行变声处理，不支持同时对多条流同时变声；

enableAudioSourceUpdateChecker

enableAudioSourceUpdateChecker(update: boolean, config?: ZegoRangeAudioUserUpdateCheckConfig): void

是否检查范围内用户的变更。

参数

名称	类型	描述
update	boolean	是否开启。
config?	ZegoRangeAudioUserUpdateCheckConfig	检查范围内用户变更的配置。

详情

是否检查范围内用户的变更。

调用时机/通知时机：调用接口 createRangeAudioInstance 创建 ZegoExpressRangeAudio 实例后。
相关回调：audioSourceWithinRangeUpdate。

支持版本：2.22.0 及以上

on

on<K extends keyof ZegoRangeAudioEvent >(event: K, callBack: ZegoRangeAudioEvent[K]): boolean

注册回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoRangeAudioEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 ZegoRangeAudioEvent 查看。

业务场景：用于注册范围语音功能相关的业务事件的回调处理。
调用时机：调用接口 createRangeAudioInstance 创建实例之后并且在调用接口 loginRoom 登录房间之前。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：2.10.0 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

off

off<K extends keyof ZegoRangeAudioEvent >(event: K, callBack?: ZegoRangeAudioEvent[K]): boolean

注销回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoRangeAudioEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。用于删除注册的同一类回调事件。

业务场景：用于注销范围语音功能相关的业务事件的回调处理。
调用时机：调用接口 createRangeAudioInstance 创建实例之后。

支持版本：2.10.0 及以上
注意事项：如果没有传要注销的回调方法，将会注销所有该事件的回调。

返回值

注销回调是否成功。

setAudioReceiveRange

setAudioReceiveRange(range: number): void

设置音频接收距离的最大范围。

参数

名称	类型	描述
range	number	音频范围, 取值必须大于等于 0。

详情

设置音频接收最大距离范围，超过该范围的音源声音会听不见，不设置的情况默认是无限范围。

业务场景：范围语音中设置收听者的听觉范围。
默认值：没有调用接口时默认是无距离限制，即听见房间内所有人的声音。
调用时机：调用接口 createRangeAudioInstance 创建 ZegoExpressRangeAudio 实例后。

支持版本：2.10.0 及以上
注意事项：该范围只对非同小队的发声者生效。

updateSelfPosition

updateSelfPosition(position: number[], axisForward: number[], axisRight: number[], axisUp: number[]): void

更新听者的位置和朝向。

参数

名称	类型	描述
position	number[]	自身在世界坐标系中的坐标，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。
axisForward	number[]	自身坐标系前轴的单位向量，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。
axisRight	number[]	自身坐标系右轴的单位向量，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。
axisUp	number[]	自身坐标系上轴的单位向量，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。

详情

自身的位置和朝向，以便 SDK 计算出用户与音源距离以及左右耳立体声效果。

业务场景：当用户在游戏中操作的角色在世界地图中移动时，更新角色的位置信息以及头部朝向。
调用时机：创建 ZegoExpressRangeAudio 实例后和调用接口，调用接口 enableSpeaker 之前。

支持版本：2.10.0 及以上
注意事项：在调用 enableSpeaker 打开扬声器之前，如果没有调用 updateSelfPosition 设置位置信息，则无法接收除小队以外其他人的声音。

updateAudioSource

updateAudioSource(userID: string, position: number[]): void

添加或更新音源位置信息。

参数

名称	类型	描述
userID	string	发声者用户 ID。
position	number[]	发声者在世界坐标系中的坐标，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。

详情

设置 userID 对应的音源在世界地图位置，以便 SDK 计算听者与音源的距离和方位。

业务场景：更新发声用户在游戏地图坐标中的位置。
调用时机：调用 loginRoom 登录房间后调用，登出房间后会清空记录的音源信息。

支持版本：2.10.0 及以上

enableSpatializer

enableSpatializer(enable: boolean): void

开关 3D 音效。

参数

名称	类型	描述
enable	boolean	是否开启，默认值是 true

详情

开启 3D 音效后将根据发声者相当于听者的位置模拟实际空间中的声音效果，可直观感受到就是音源远近和方位发生变化时，声音大小和左右声音差所产生的变化。enable 为true 时开启 3D 音效，为 false 时关闭 3D 音效。

业务场景：第一人称射击游戏或社交场景游戏中听声辨位功能。
默认值：在没有调用该接口前，默认是关闭3D音效。
调用时机：调用接口 createRangeAudioInstance 初始化实例后。
相关接口：开启 3D 音效后，可以调用 updateSelfPositon 和 updateAudioSource 更新位置和朝向来改变立体声效果。

支持版本：2.10.0 及以上
使用限制：3D 音效只对小队以外的人的声音起作用。

enableMicrophone

enableMicrophone(enable: boolean): void

开关麦克风。

参数

名称	类型	描述
enable	boolean	是否开启，默认值是 true

详情

enable 为 true 时开启麦克风并推送音频流，为 false 时关闭麦克风并停止推送音频流。

业务场景：用户在房间内打开或关闭麦克风交流。
默认值：在没有调用接口前，默认是关闭麦克风。
调用时机：调用接口 createRangeAudioInstance 创建实例和调用接口 loginRoom 登录房间成功后。
相关回调：通过回调 microphoneStateUpdate 来获取麦克风开关状态变化。

支持版本：2.10.0 及以上

selectMicrophone

selectMicrophone(deviceID: string): Promise<boolean>

指定麦克风设备。

参数

名称	类型	描述
deviceID	string	麦克风设备 ID。

详情

通过传入麦克风设备的 deviceID 来指定开启麦克风时使用的设备，deviceID 可以通过 ZegoExpressEngine.getMicrophones 接口获取。

业务场景：切换使用的麦克风设备。
默认值：在没有调用接口前，使用的是系统默认指定的麦克风设备。
调用时机：调用接口 createRangeAudioInstance 创建实例后。
相关接口：获取麦克风设备列表接口 getMicrophones。

支持版本：2.17.0 及以上

返回值

异步返回布尔值，表示切换设备是否成功。

selectSpeaker

selectSpeaker(deviceID: string): void

指定扬声器设备。

参数

名称	类型	描述
deviceID	string	扬声器设备 ID。

详情

通过传入扬声器设备的 deviceID 来指定范围语音播放音频使用的设备，deviceID 可以通过 ZegoExpressEngine.getSpeakers 接口获取。

业务场景：范围语音切换使用的扬声器设备。
默认值：在没有调用接口前，使用的是系统默认指定的扬声器设备。
调用时机：调用接口 createRangeAudioInstance 创建实例后。
相关接口：获取扬声器设备列表接口 getSpeakers。

支持版本：2.19.0 及以上
注意事项：该接口当前只支持 PC 端 Google Chrome 浏览器使用。

enableSpeaker

enableSpeaker(enable: boolean): void

开关扬声器。

参数

名称	类型	描述
enable	boolean	是否开启，默认值是 true

详情

开启扬声器后会接收房间内其他开启麦克风的音源声音，enable 为 true 时开始拉取和播放可拉取的音频流，为 false 时停止拉取和播放音频流。

业务场景：用户选择是否接收其他人的音频。
默认值：在没有调用接口前，默认是关闭接收音频。
调用时机：调用接口 createRangeAudioInstance 创建实例和调用接口 loginRoom 登录房间成功后。

支持版本：2.10.0 及以上

setRangeAudioCustomMode

setRangeAudioCustomMode(speakMode: ZegoRangeAudioSpeakMode, listenMode: ZegoRangeAudioListenMode): void

设置范围语音的高阶自定义模式。

参数

名称	类型	描述
speakMode	ZegoRangeAudioSpeakMode	范围语音发声模式，mode 为 0 表示发送所有人，为 1 表示仅范围内，为 2 表示仅小队。
listenMode	ZegoRangeAudioListenMode	范围语音收听模式，mode 为 0 表示收听所有人，为 1 表示仅范围内，为 2 表示仅小队。

详情

可以分别设置发声模式和收听模式，以控制在世界和小队中的发声和收听行为。

业务场景：用户可通过选择发声模式来决定谁能收听到他的声音，也可通过选择收听模式来决定收听谁的声音。
默认值：没有调用该接口时，默认使用 “发声到所有” 模式和 “收听所有” 模式，即通用范围语音模式的 “全世界” 模式。
调用时机：通过 [createRangeAudioInstance] 初始化实例后。
相关接口：当希望收听来自世界的声音时，需要设置声音接收范围 [setAudioReceiveRange]。当希望在小队中发声和收听时，需要设置 [setTeamID] 加入对应小队。

支持版本：2.24.0 及以上
使用限制：1. 不能与 [setRangeAudioMode] 混用。

与 2.24.0 之前的版本无法兼容。

setRangeAudioMode

setRangeAudioMode(mode: ZegoRangeAudioMode): void

设置范围语音模式。

参数

名称	类型	描述
mode	ZegoRangeAudioMode	收听模式，mode 为 0 表示收听所有人，为 1 表示仅小队

详情

设置收听模式，可设置为“全世界”模式或“仅小队”模式。

业务场景：用户想要只在小队范围交流或与可与房间内所有人交流。
默认值：在不调接口设置时默认是“全世界”，可以与所有人交流。
调用时机：通过 createRangeAudioInstance 初始化实例后。
相关接口：要调接口 setTeamID 加入对应小队才能听到小队内的声音。

支持版本：2.10.0 及以上

setTeamID

setTeamID(teamID?: string): void

设置队伍 ID。

参数

名称	类型	描述
teamID	string	队伍 ID，最大长度为 64 字节的字符串。

详情

设置队伍 ID 后，将能与同一队伍其他用户交流，且声音不会随距离方向产生变化。

业务场景：用户想要加入队伍交流或退出队伍。
默认值：默认值是 undefined , 表示不加入队伍。
调用时机：通过 createRangeAudioInstance 初始化实例后。
相关接口：调接口 etRangeAudioMode 设置为”仅小队“模式时只有队伍内进行交流。

支持版本：2.10.0 及以上
注意事项：参数 teamID 的最大长度为 64 字节。

setPositionUpdateFrequency

setPositionUpdateFrequency(frequency: number): void

设置 SDK 内部实时更新位置的频率。

参数

名称	类型	描述
frequency	number	更新频率，取值必须大于 15ms。

详情

设置 SDK 内部实时更新位置的频率最小 15ms。

业务场景：更新位置后，对音频渐变灵敏度要求很高。
默认值：默认 100ms。
调用时机：通过 createRangeAudioInstance 初始化实例后。

支持版本：2.19.0 及以上

setRangeAudioVolume

setRangeAudioVolume(volume: number): void

设置范围语音本地播放音量。

参数

名称	类型	描述
volume	number	音量大小，取值范围 [0,200] 。

详情

设置范围语音本地播放音量。

默认值：100。
调用时机：调用接口 createRangeAudioInstance 创建 ZegoExpressRangeAudio 实例后。

支持版本：2.19.0 及以上

enableAiDenoise

enableAiDenoise(enable: boolean): boolean

范围语音开启或关闭 AI 降噪。

参数

名称	类型	描述
enable	boolean	开启/关闭 AI 降噪

详情

对麦克风声音进行 AI 降噪处理。

业务场景：推流前或推流中切换 AI 降噪。
默认值：无
调用时机：调用接口 createStream 创建流成功后。

支持版本：2.21.0。
注意事项：1. 目前使用 AI 降噪功能需要联系 ZEGO 技术支持进行特殊编包；

目前仅支持 PC 端使用，移动端暂不支持；

返回值

标识接口是否调用成功。失败原因可能是浏览器不支持或没有使用特殊编包。

isAudioContextRunning

isAudioContextRunning(): boolean

判断 AudioContext 对象是否已启用。

该接口主要是为了处理浏览器对自动播放策略的兼容性问题。通过接口 isAudioContextRunning 检测当前的 AudioContext 对象是否启用，如果没有启用将不支持自动播放声音。

调用时机：调用 createRangeAudioInstance 创建实例后。
相关接口：如果 AudioContext 对象没有启用，可以通过接口 resumeAudioContext 重新启用 AudioContext 对象。

支持版本：2.10.0 及以上

AudioContext 对象是否启用

resumeAudioContext

resumeAudioContext(): Promise<boolean>

重新启用内部的 AudioContext 对象。

该接口主要是为了处理浏览器对自动播放策略的兼容性问题。若通过接口 isAudioContextRunning 检测当前的 AudioContext 对象没有启用，可以通过该接口重新启用。

调用时机：调用 createRangeAudioInstance 创建实例后。
相关接口：通过接口 isAudioContextRunning 检测当前的 AudioContext 对象没有启用。

支持版本：2.10.0 及以上
注意事项：该接口必须要在 JavaScript 的点击事件中调用才会生效。

是否重启成功

setStreamVocalRange

setStreamVocalRange(view: ZegoStreamView, range: number): void

设置拉流音频发送范围。

参数

名称	类型	描述
view	ZegoStreamView	拉流播放组件。
range	number	发送范围, 取值必须大于等于 0。

详情

设置音频发送最大距离范围，超过该范围的音源声音会听不见。

业务场景：范围语音中设置拉流发声源的发声范围。
默认值：默认为 0。
调用时机：调用接口 createRangeAudioInstance 创建 ZegoExpressRangeAudio 实例后。

支持版本：2.20.2 及以上

updateStreamPosition

updateStreamPosition(view: ZegoStreamView, position: number[]): void

更新拉流的位置。

参数

名称	类型	描述
view	ZegoStreamView	发声源，传播放 RTC 拉流的 ZegoStreamView。
position	number[]	发声者在世界坐标系中的坐标，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。

详情

设置拉流发声源对应的音源在世界地图位置，以便 SDK 计算听者与音源的距离和方位。

业务场景：更新自定义发声源在游戏地图坐标中的位置。
调用时机：调用 loginRoom 登录房间后调用，登出房间后会清空记录的音源信息。

支持版本：2.21.0 及以上

setCustomSourceVocalRange

setCustomSourceVocalRange(media: HTMLMediaElement, range: number): void

设置自定义发声源发送范围。

参数

名称	类型	描述
media	HTMLMediaElement	<video> 或 <audio> 标签对象。
range	number	发送范围, 取值必须大于等于 0。

详情

设置音频发送最大距离范围，超过该范围的音源声音会听不见。

业务场景：范围语音中设置自定义发声源的发声范围。
默认值：默认为 0。
调用时机：调用接口 createRangeAudioInstance 创建 ZegoExpressRangeAudio 实例后。

支持版本：2.20.2 及以上

updateCustomSourcePosition

updateCustomSourcePosition(media: HTMLMediaElement, position: number[]): void

添加或更新自定义发声源位置信息。

参数

名称	类型	描述
media	HTMLMediaElement	发声源，传播放本地或在线音频文件 <video> 或 <audio> 标签对象。
position	number[]	发声者在世界坐标系中的坐标，参数是长度为 3 的 number 数组，三个值依次表示前、右、上的坐标值。

详情

设置自定义发声源对应的音源在世界地图位置，以便 SDK 计算听者与音源的距离和方位。

业务场景：更新自定义发声源在游戏地图坐标中的位置。
调用时机：调用 loginRoom 登录房间后调用，登出房间后会清空记录的音源信息。

支持版本：2.21.0 及以上

ZegoLocalStream

zego本地流

详情

通过调用createZegoStream可以生成一个ZegoLocalStream实例，ZegoLocalStream集成了音视频的采集、播放API。

业务场景：创建一条本地流，用于预览与推流。

方法

playAudio

playAudio(options?: ZegoLocalAduioOptions): void

在页面上播放待推送或者已推送的媒体流的音频。

参数

名称	类型	描述
options	ZegoLocalAduioOptions	设置播放选项参数。

详情

SDK 将根据需要创建媒体流播放待推送或者正在推流中的媒体流的音频。在调用[startPublishingStream]推流前，媒体播放内容会同步当前最新采集的音频；推流成功后，ZegoLocalStream再次调用采集麦克风、屏幕共享或者第三方音频源，新采集的音频并不会同步更新到正在推流的音频，如需要更新，需要调用[updatePublishingStream]更新。

业务场景：播放待推送或者正在推流中的媒体流的音频。
调用时机：创建 ZegoLocalStream 实例，且开始采集音视频流后。
相关回调：调用 [playAudio] 接口播放视频失败时会触发 ZegoLocalStream 的自动播放失败事件回调 [autoplayFailed]。
相关接口：停止播放媒体流播放接口 [stopAudio] 。调用 [destroyStream] 也会卸载播放组件。

支持版本：3.0.0 及以上

playCaptureAudio

playCaptureAudio(options?: ZegoLocalAduioOptions): void

播放最新正在采集的媒体流音频。

参数

名称	类型	描述
options	ZegoLocalAduioOptions	设置播放选项参数

详情

SDK 将根据需要创建媒体流播放最新正在采集的媒体流音频。

业务场景：播放最新正在采集的媒体流音频。
调用时机：创建 ZegoLocalStream 实例，且开始采集音频流后。
相关回调：调用 [playCaptureAudio] 接口播放音频失败时，会触发 ZegoLocalStream 的自动播放失败事件回调 [autoplayCaptureFailed]。
相关接口：停止播放媒体流播放接口 [stopPlayCaptureAudio] 。调用 [destroyStream] 也会卸载播放组件。

支持版本：3.0.0 及以上

playCaptureVideo

playCaptureVideo(container: HTMLElement, options?: ZegoLocalViewOptions): void

在页面上播放最新正在采集的媒体流的视频。

参数

名称	类型	描述
container	HTMLElement	指定一个容器标签 DOM 元素，例如 div。SDK 将在这个元素下创建 <video> 元素播放视频轨道。
options	ZegoLocalViewOptions	设置播放选项参数（镜像、显示模式等）。

详情

指定一个 DOM 元素作为容器，SDK 将根据需要在元素下创建媒体播放最新正在采集的媒体流的视频。

业务场景：在界面上显示最新正在采集的媒体流内容。
调用时机：执行[createZegoStream]创建 ZegoLocalStream 实例，且开始采集视频流后。
相关回调：调用 [playCaptureVideo] 接口播放视频失败时会触发 ZegoLocalStream 的自动播放失败事件回调 [autoplayCaptureFailed]。
相关接口：停止播放媒体流播放接口 [stopPlayCaptureVideo] ，[stopPlayCaptureVideo]会卸载所有播放最新采集流的播放组件。调用 [destroyStream] 也会卸载播放组件。

支持版本：3.0.0 及以上
注意事项：一个 ZegoLocalStream 实例。只能通过[playCaptureVideo] 方法挂载在一个容器上，不可多次挂载。

playVideo

playVideo(container: HTMLElement, options?: ZegoLocalViewOptions): void

在页面上播放待推送或者已推送的媒体流的视频。

参数

名称	类型	描述
container	HTMLElement	指定一个容器标签 DOM 元素，例如 div。SDK 将在这个元素下创建 <video> 元素播放视频轨道。
options	ZegoLocalViewOptions	设置播放选项参数（镜像、显示模式等）。

详情

指定一个 DOM 元素作为容器，SDK 将根据需要在元素下创建媒体流播放待推送或者已推送的媒体流的视频。在执行[startPublishingStream]推流前，媒体播放内容会同步当前最新采集的视频内容；推流成功后，ZegoLocalStream再次调用采集摄像头、屏幕共享或者第三方视频源，新采集的视频并不会同步更新到正在推流的视频源，如需要更新，需要调用[updatePublishingStream]更新。

业务场景：在界面上显示媒体流内容。
调用时机：创建 ZegoLocalStream 实例，且开始采集音视频流后。
相关回调：调用 [playVideo] 接口播放视频失败时会触发 ZegoLocalStream 的自动播放失败事件回调 [autoplayFailed]。
相关接口：停止播放媒体流播放接口 [stopVideo] 。调用 [destroyStream] 也会卸载播放组件。

支持版本：3.0.0 及以上
注意事项：一个 ZegoLocalStream 实例只能通过 playVideo 方法挂载在一个容器上，不能同时挂载多个。

stopAudio

stopAudio(): void

停止播放待推流或者正在推流中的音频。

业务场景：停止播放待推流或者正在推流中的音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playAudio]后。
相关接口：调用 [destroyStream] 则卸载播放组件。

支持版本：3.0.0及以上

stopCaptureAudio

stopCaptureAudio(): Promise<boolean>

停止采集音频。

停止采集音频，销毁正在音频预览的播放组件，若处于推流中，则推流中的音频停止采集成功后，预览流的音频采集才会停止，否则停止采集音频失败。

业务场景：停止采集音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。

支持版本：3.0.0及以上

stopCaptureVideo

stopCaptureVideo(): Promise<boolean>

停止采集视频。

停止采集视频，销毁正在视频预览的播放组件，若处于推流中，则推流中的视频停止采集成功后，预览流的视频采集才会停止，否则停止采集视频失败。

业务场景：停止采集视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。

支持版本：3.0.0及以上

stopPlayCaptureAudio

stopPlayCaptureAudio(): void

停止播放最新正在采集的媒体流的音频。

业务场景：停止播放最新正在采集的媒体流的音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playCaptureAudio]后。
相关接口：调用 [destroyStream] 也可以卸载播放组件。

支持版本：3.0.0及以上

stopPlayCaptureVideo

stopPlayCaptureVideo(): void

停止页面所有最新正在采集的媒体流视频的播放。

业务场景：在界面上不显示最新正在采集的媒体流内容。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playCaptureVideo]后。
相关接口：调用 [destroyStream] 也可以卸载播放组件。

支持版本：3.0.0及以上

stopVideo

stopVideo(): void

停止播放待推流或者正在推流中的视频。

业务场景：停止播放待推流或者正在推流中的视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playVideo]后。
相关接口：调用 [destroyStream] 则卸载播放组件。

支持版本：3.0.0及以上

resumeAudio

resumeAudio(): void

恢复播放页面上待推送或者正在推流中的音频。

当视频浏览器限制而阻止播放时，可以在 DOM 点击事件中调用该接口恢复播放页面上的音频。

业务场景：播放页面上待推送或者正在推流中的音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playAudio]后。

支持版本：3.0.0及以上

resumeVideo

resumeVideo(): void

恢复播放页面上待推送或者正在推流中的视频。

当视频浏览器限制而阻止播放时，可以在 DOM 点击事件中调用该接口恢复播放页面上的视频。

业务场景：在界面上显示媒体流内容。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playVideo]后。

支持版本：3.0.0及以上

startCaptureCamera

startCaptureCamera(options?: ZegoCaptureCamera): ZegoServerResponse

开始采集摄像头视频流。

参数

名称	类型	描述
options	ZegoCaptureCamera	采集摄像头配置参数

详情

开始采集摄像头流，不会同步更新正在推流中的视频，如需更新，可调用[updatePublishingStream]。

业务场景：采集摄像头流用于预览或者更新推流中的视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的视频，可以调用[startCaptureCamera]成功后，再调用[updatePublishingStream]将[startCaptureCamera]采集的麦克风更新到推流中的视频。 2、调用[stopCaptureVideo]可以停止当前正在采集的视频。 3、调用[mutePublishStreamVideo]可以打开/关闭正在推流的流视频。

支持版本：3.0.0及以上

startCaptureCameraAndMicrophone

  startCaptureCameraAndMicrophone(cameraOptions?: ZegoCaptureCamera, microphoneOptions?: ZegoCaptureMicrophone): ZegoServerResponse

开始采集摄像头和麦克风音视频流。

参数

名称	类型	描述
cameraOptions	ZegoCaptureCamera	采集摄像头配置参数
microphoneOptions	ZegoCaptureMicrophone	采集麦克风配置参数

详情

开始采集摄像头和麦克风流，不会同步更新正在推流中的音视频，如需更新，可调用[updatePublishingStream]。

业务场景：采集摄像头和麦克风流用于预览或者更新推流中的音视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的音视频，可以调用[startCaptureCameraAndMicrophone]成功后，再调用[updatePublishingStream]将[startCaptureCameraAndMicrophone]采集的摄像头视频和麦克风音频更新到推流中的音视频。 2、调用[stopCaptureAudio]或者[stopCaptureVideo]可以停止当前正在采集的音频或者视频。 3、调用[mutePublishStreamAudio]或者[mutePublishStreamVideo]可以打开/关闭正在推流的流音频或视频。

支持版本：3.0.0及以上

startCaptureCustomAudio

startCaptureCustomAudio(options: ZegoCustomAudio): ZegoServerResponse

开始采集第三方音频流。

参数

名称	类型	描述
options	ZegoCustomAudio	采集第三方音频流参数配置

详情

开始采集第三方音频流，不会同步更新正在推流中的音频，如需更新，可调用[updatePublishingStream]。

业务场景：采集第三方音频用于预览或者更新推流中的音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的音频，可以调用[startCaptureCustomAudio]成功后，再调用[updatePublishingStream]将[startCaptureCustomAudio]采集的自定义音频更新到推流中的音频。 2、调用[stopCaptureAudio]可以停止当前正在采集的音频。 3、调用[mutePublishStreamAudio]可以打开/关闭正在推流的流音频。

支持版本：3.0.0及以上
注意事项：第三方音频流来自于同一个audio的采集，再次采集会导致前一次采集停止，若音频来自于同个audio不建议多次调用[startCaptureCustomVideoAndAudio]和[startCaptureCustomAudio]。

startCaptureCustomVideo

startCaptureCustomVideo(options: ZegoCustomVideo): ZegoServerResponse

开始采集第三方视频流。

参数

名称	类型	描述
options	ZegoCustomVideo	采集第三方视频流参数配置

详情

开始采集第三方视频流，不会同步更新正在推流中的视频，如需更新，可调用[updatePublishingStream]。

业务场景：采集第三方视频用于预览或者更新推流中的视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的视频，可以调用[startCaptureCustomVideo]成功后，再调用[updatePublishingStream]将[startCaptureCustomVideo]采集的自定义视频更新到推流中的视频。 2、调用[stopCaptureVideo]可以停止当前正在采集的视频。 3、调用[mutePublishStreamVideo]可以打开/关闭正在推流的流视频。

支持版本：3.0.0及以上
注意事项：第三方音视频流来自于同一个video的采集，再次采集会导致前一次采集停止，若音视频来自于同个video不建议多次调用[startCaptureCustomVideoAndAudio]、[startCaptureCustomVideo]。

startCaptureCustomVideoAndAudio

startCaptureCustomVideoAndAudio(videoOptions: ZegoCustomVideo, audioOptions: ZegoCustomAudio): ZegoServerResponse

开始采集第三方音视频流。

参数

名称	类型	描述
videoOptions	ZegoCustomVideo	采集第三方视频流参数配置
audioOptions	ZegoCustomAudio	采集第三方音频流参数配置

详情

开始采集第三方音视频流，不会同步更新正在推流中的音视频，如需更新，可调用[updatePublishingStream]。

业务场景：采集第三方音视频用于预览或者更新推流中的音视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的音视频，可以调用[startCaptureCustomVideoAndAudio]成功后，再调用[updatePublishingStream]将[startCaptureCustomVideoAndAudio]采集的自定义音视频更新到推流中的音视频。 2、调用[stopCaptureAudio]或者[stopCaptureVideo]可以停止当前正在采集的音频或者视频。 3、调用[mutePublishStreamAudio]或者[mutePublishStreamVideo]可以打开/关闭正在推流的流音频或视频。

支持版本：3.0.0及以上
注意事项：第三方音视频流来自于同一个audio或者video的采集，再次采集会导致前一次采集停止，若音视频来自于同个audio或者video不建议多次调用[startCaptureCustomVideoAndAudio]、[startCaptureCustomVideo]和[startCaptureCustomAudio]。

startCaptureMicrophone

startCaptureMicrophone(options?: ZegoCaptureMicrophone): ZegoServerResponse

开始采集麦克风音频流。

参数

名称	类型	描述
options	ZegoCaptureMicrophone	采集麦克风配置参数

详情

开始采集麦克风流，不会同步更新正在推流中的音频，如需更新，可调用[updatePublishingStream]。

业务场景：采集麦克风流用于预览或者更新推流中的音频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的音频，可以调用[startCaptureMicrophone]成功后，再调用[updatePublishingStream]将[startCaptureMicrophone]采集的麦克风更新到推流中的音频。 2、调用[stopCaptureAudio]可以停止当前正在采集的音频。 3、调用[mutePublishStreamAudio]可以打开/关闭正在推流的流音频。

支持版本：3.0.0及以上

startCaptureScreen

startCaptureScreen(options?: ZegoCaptureScreenVideo): ZegoServerResponse

开始采集屏幕共享视频流。

参数

名称	类型	描述
options	ZegoCaptureScreenVideo	采集屏幕共享配置参数

详情

开始采集屏幕共享视频流，不会同步更新正在推流中的视频，如需更新，可调用[updatePublishingStream]。

业务场景：采集屏幕共享视频流用于预览或者更新推流中的视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的视频，可以调用[startCaptureScreen]成功后，再调用[updatePublishingStream]将[startCaptureScreen]采集的屏幕视频更新到推流中的视频。 2、调用[mutePublishStreamVideo]可以打开/关闭正在推流的流视频。

支持版本：3.0.0及以上

startCaptureScreenWithAudio

  startCaptureScreenWithAudio(screenVideoOptions?: ZegoCaptureScreenVideo, screenAudioOptions?: ZegoCaptureScreenAudio): ZegoServerResponse

开始采集屏幕共享视频和共享音频流。

参数

名称	类型	描述
screenVideoOptions	ZegoCaptureScreenVideo	采集屏幕共享视频配置参数
screenAudioOptions	ZegoCaptureScreenAudio	采集屏幕共享音频配置参数

详情

开始采集屏幕共享视频和共享音频流，不会同步更新正在推流中的视频，如需更新，可调用[updatePublishingStream]。

业务场景：开始采集屏幕共享视频和共享音频流用于预览或者更新推流中的音视频。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例后。
相关接口：1、推流成功后，需要更新推流的音视频，可以调用[startCaptureScreenWithAudio]成功后，再调用[updatePublishingStream]将[startCaptureScreenWithAudio]采集的视频音视频更新到推流中的音视频。 2、调用[stopCaptureAudio]或者[stopCaptureVideo]可以停止当前正在采集的音频或者视频。 3、调用[mutePublishStreamAudio]或者[mutePublishStreamVideo]可以打开/关闭正在推流的流音频或视频。

支持版本：3.0.0及以上

setVolume

setVolume(volume: number): boolean

设置播放待推送或者正在推流中的音频的音量。

参数

名称	类型	描述
volume	number	音量大小，取值范围 [0,100] 。

详情

设置播放待推送或者正在推流中的音频的音量。

调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，且已经开始采集流以及执行[playAudio]后。

支持版本：3.0.0及以上

返回值

接口是否调用成功。

useAudioOutputDevice

useAudioOutputDevice(media: HTMLMediaElement, deviceID: string): Promise<boolean>

切换音频输出设备。

参数

名称	类型	描述
media	HTMLMediaElement	媒体标签元素，<audio> 或 <video>。
deviceID	string	扬声器设备 ID。

详情

设置 html 媒体元素的音频输出设备。

调用时机：用 [getSpeakers] 获取音频输出设备列表后。
相关接口：获取扬声器列表接口 [getSpeakers]。

支持版本：3.8.0及以上
注意事项：该接口当前只支持 Chrome 浏览器使用。

返回值

Promise 返回 boolean 标识是否调用成功。

on

on<K extends keyof ZegoLocalStreamEvent >(event: K, callback: ZegoLocalStreamEvent[K]): boolean

注册回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callback	ZegoLocalStreamEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 ZegoLocalStreamEvent 查看。

业务场景：用于注册 ZegoLocalStream 媒体流功能相关的业务事件的回调处理。
调用时机：通过调用[createZegoStream]创建 ZegoLocalStreamEvent 实例之后。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：3.0.0 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

off

off<K extends keyof ZegoLocalStreamEvent >(event: K, callback?: ZegoLocalStreamEvent[K]): boolean

注销回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callback	ZegoLocalStreamEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。用于删除注册的同一类回调事件。

业务场景：用于注销 ZegoLocalStream 媒体流功能相关的业务事件的回调处理。
调用时机：通过调用[createZegoStream]创建 ZegoLocalStreamEvent 实例之后。

支持版本：3.0.0 及以上
注意事项：如果没有传要注销的回调函数参数 [callback]，将会注销所有该事件的回调函数。

返回值

注销回调是否成功。

takeStreamSnapshot

takeStreamSnapshot(option?: ZegoSnapshotOptions): string

客户端截图

参数

名称	类型	描述
option?	ZegoSnapshotOptions	截图相关配置选项

详情

获取当前播放的待推流或者正在推流中的视频帧数据。

业务场景：对当前播放的待推流或者正在推流中的视频画面进行截图。
调用时机：通过[createZegoStream]创建ZegoLocalStream 实例，已经开始采集流且执行[playVideo]后。

支持版本：3.0.0 及以上。

返回值

包含 data URI 的 DOMString。

ZegoRealTimeSequentialDataManager

实时有序数据对象

详情

实时有序数据，依托于 ZEGO RTC 服务，可为开发者提供实时、有序、高频的数据传输与分发功能

方法

startBroadcasting

startBroadcasting(streamID: string): Promise<boolean>

开始广播

参数

名称	类型	描述
streamID	string	推流 ID，长度不超过256的字符串，仅支持数字，英文字符和 '~', '!', '@', '#', '$', '', '^', '&', '*', '(', ')', '_', '+', '=', '-', ', ';', '’', ',', '.', '<', '>', '/', ''

详情

开始广播名为 streamID 的实时有序数据通道。

业务场景：远程控制场景中由控制端发送指令到受控端。
调用时机：调用接口 createRealTimeSequentialDataManager 创建 ZegoRealTimeSequentialDataManager实例后。

支持版本：2.12.2 及以上
注意事项：可复用 RTC 推流通道。

返回值

true 表示客户端发送请求成功，流成功推送到服务器需要通过流状态回调接口判断。

stopBroadcasting

stopBroadcasting(streamID: string): boolean

停止广播

参数

名称	类型	描述
streamID	string	推流 ID,和广播 streamID保持一致

详情

停止广播名为 streamID 的实时有序数据通道。

业务场景：远程控制场景控制端停止传输指令到受控端。
调用时机：调用接口 createRealTimeSequentialDataManager 创建 ZegoRealTimeSequentialDataManager实例后。

支持版本：2.12.2 及以上
注意事项：在复用 RTC 通道的情况下，停止实时有序数据的广播不会影响 RTC 通道。

返回值

布尔值

sendRealTimeSequentialData

sendRealTimeSequentialData(streamID: string, data: ArrayBuffer): boolean

发送实时有序数据

参数

名称	类型	描述
streamID	string	流 ID
data	ArrayBuffer	数据

详情

发送实时有序数据。

业务场景：远程控制场景中由控制端发送指令到受控端。
调用时机：调用接口 createRealTimeSequentialDataManager 创建 ZegoRealTimeSequentialDataManager实例后，并调用 startBroadcasting 进行广播后。

支持版本：2.12.2 及以上
注意事项：在弱网下数据可能存在丢失。

返回值

布尔值

startSubscribing

startSubscribing(streamID: string): Promise<boolean>

开始订阅

参数

名称	类型	描述
streamID	string	流 ID

详情

开始订阅通道为 streamID 的实时有序数据频道。

业务场景：远程控制场景中，受控端从控制端接收指令。
调用时机：调用接口 createRealTimeSequentialDataManager 创建 ZegoRealTimeSequentialDataManager实例后。

支持版本：2.12.2 及以上
注意事项：可复用 RTC 推流通道。

返回值

布尔值

stopSubscribing

stopSubscribing(streamID: string): boolean

停止订阅

参数

名称	类型	描述
streamID	string	流 ID

详情

停止订阅名为 streamID 的实时有序数据频道。

业务场景：远程控制场景中，受控端停止从控制端接收指令。
调用时机：调用接口 createRealTimeSequentialDataManager 创建 ZegoRealTimeSequentialDataManager实例后。

支持版本：2.12.2 及以上
注意事项：在复用 RTC 通道的情况下，停止实时有序数据的广播不会影响 RTC 通道。

返回值

布尔值

on

on<K extends keyof ZegoDataChannelEvent>(event: K, callBack: ZegoDataChannelEvent[K]): void

注册回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoDataChannelEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 ZegoDataChannelEvent查看。

业务场景：用于注册实时有序数据功能相关的业务事件的回调处理。
调用时机：调用接口 createRealTimeSequentialDataManager 创建实例之后。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：2.12.2 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

off

off<K extends keyof ZegoDataChannelEvent>(event: K, callBack: ZegoDataChannelEvent[K]): void

注销回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callBack	ZegoDataChannelEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 ZegoDataChannelEvent查看。

业务场景：用于注销实时有序数据功能相关的业务事件的回调处理。
调用时机：调用接口 createRealTimeSequentialDataManager 创建实例之后。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：2.12.2 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

ZegoStreamCompositor

导播台

方法

addImage

addImage(img: HTMLImageElement, option: ZegoStreamCompositorInputOption): void

创建导播台的图片输入图层

参数

名称	类型	描述
img	HTMLImageElement	输入的 image
option	ZegoStreamCompositorInputOption	输入图层的属性

详情

创建导播台的图片输入图层。

业务场景：设置图片在输出画布上的显示。
调用时机：创建导播台 ZegoStreamCompositor 后。

支持版本：3.0.0 及以上

removeImage

removeImage(img: HTMLImageElement): void

删除导播台的图片输入图层

参数

名称	类型	描述
img	HTMLImageElement	输入的 image

详情

删除导播台的图片输入图层。

业务场景：删除图片在输出画布上的显示。
调用时机：创建导播台的图片输入图层后。

支持版本：3.0.0 及以上

setInputEndpoint

setInputEndpoint(stream: MediaStream | ZegoLocalStream, option: ZegoStreamCompositorInputOption): Promise<void>

创建导播台的输入图层

参数

名称	类型	描述
stream	MediaStream \| ZegoLocalStream	输入的 MediaStream或者 createZegoStream创建得到的 ZegoLocalStream实例对象
option	ZegoStreamCompositorInputOption	输入图层的属性

详情

创建导播台的输入图层。

业务场景：设置输入流在输出画布上的显示。
调用时机：创建导播台 ZegoStreamCompositor 后。

支持版本：3.0.0 及以上

setOutputConfig

setOutputConfig(config: ZegoStreamCompositorOutputConfig): void

设置导播台输出视频的属性

参数

名称	类型	描述
config	ZegoStreamCompositorOutputConfig	输出流的选项

详情

设置导播台输出视频的属性。

业务场景：当需要将本地用户的多路视频流以及图片合为一路视频流，比如在线教育、远程会议、直播等场景，可以使用导播台来实现。
调用时机：创建导播台 ZegoStreamCompositor 后。

支持版本：3.0.0 及以上

startComposingStream

startComposingStream(): Promise<MediaStream>

开始合成流

导播台会对所有输入图层的内容进行合并，输出音视频。

业务场景：当需要将本地用户的多路视频流以及图片合为一路视频流，比如在线教育、远程会议、直播等场景，可以使用导播台来实现。
调用时机：创建导播台 ZegoStreamCompositor 后。

支持版本：3.0.0 及以上

stopComposingStream

stopComposingStream(): Promise<boolean>

停止合成流

导播台停止合成流。

业务场景：当需要结束合成流时。
调用时机：导播台开始合成流后。

支持版本：3.0.0 及以上

ZegoStreamView

媒体流播放器组件

详情

媒体流播放器组件类。

业务场景：在界面上播放媒体流。

方法

play

play(container: string | HTMLElement, options?: ZegoStreamViewOptions): void

在页面上播放媒体流的音视频。

参数

名称	类型	描述
container	string \| HTMLElement	指定一个容器，SDK 将在这个容器下创建 <video> 元素播放视频轨道。参数值可以是 DOM 元素对象（例如 div）或者是 DOM 元素的 ID。
options	ZegoStreamViewOptions	设置播放选项参数（镜像、显示模式、静音等）。

详情

指定一个 DOM 元素作为容器，SDK 将根据需要在元素下创建媒体流播放组件播放音视频。

业务场景：在界面上显示媒体流内容。
调用时机：创建 ZegoStreamView 实例后。
相关回调：调用 play 接口播放视频失败时会触发 ZegoStreamView 的自动播放失败事件回调 [autoplayFailed]。
相关接口：卸载媒体流播放组件接口 [stop] 。调用 [stopPlayingStream] 或 [destroyStream] 也会卸载播放组件。

支持版本：2.17.0 及以上
注意事项：- 一个 ZegoStreamView 播放组件只能通过 play 方法挂载在一个容器上，不能同时挂载多个。
由于浏览器自动播放策略的限制，页面无任何用户交互的情况下调用play方法，可能会导致播放失败，可通过事件回调 [autoplayFailed] 捕捉错误并引导用户进行交互播放

playVideo

playVideo(container: string | HTMLElement, options?: ZegoStreamViewOptions): void

在页面上播放媒体流的视频。

参数

名称	类型	描述
container	string \| HTMLElement	指定一个容器，SDK 将在这个容器下创建 <video> 元素播放视频轨道。参数值可以是 DOM 元素对象（例如 div）或者是 DOM 元素的 ID。
options	ZegoStreamViewOptions	设置播放选项参数（镜像、显示模式等视频相关控制参数）。

详情

业务场景：在界面上显示媒体流内容。
调用时机：创建 ZegoStreamView 实例，且开始采集音视频流后。
相关回调：调用 [playVideo] 接口播放视频失败时会触发 ZegoStreamView 的自动播放失败事件回调 [autoplayFailed]。
相关接口：停止播放媒体流播放接口 [stopVideo] 。调用 [destroyStream] 也会卸载播放组件。[playVideo] 和 [playAudio] 是 [play] 方法进行区分细化对视频和音频的播放操作。

支持版本：3.8.0 及以上
注意事项：一个 ZegoStreamView 实例只能通过 playVideo 方法挂载在一个容器上，不能同时挂载多个。

playAudio

playAudio(options?: ZegoStreamViewOptions): void

播放媒体流的音频。

参数

名称	类型	描述
options	ZegoStreamViewOptions	设置播放选项参数。

详情

播放媒体流的音频。

业务场景：只想要播放媒体流的音频，不需要播放视频。
调用时机：创建 ZegoStreamView 实例后。
相关回调：调用 [playAudio] 接口播放视频失败时会触发 ZegoStreamView 的自动播放失败事件回调 [autoplayFailed]。
相关接口：停止播放媒体流播放接口 [stopAudio] 。调用 [destroyStream] 也会卸载播放组件。[playVideo] 和 [playAudio] 是 [play] 方法进行区分细化对视频和音频的播放操作。

支持版本：3.8.0 及以上

stop

stop(): void

停止在页面上播放音视频。

卸载媒体流播放组件来结束显示音视频。

业务场景：结束在界面上展现媒体流内容。
调用时机：创建 ZegoStreamView 实例后。
相关接口：调用 [stopPlayingStream] 或 [destroyStream] 也会卸载播放组件。

支持版本：2.17.0 及以上

stopVideo

stopVideo(): void

停止播放媒体流的视频。

业务场景：界面上不再需要展示媒体流视频内容。
调用时机：创建 ZegoStreamView 实例后，且已经开始采集流以及执行[playVideo]后。
相关接口：调用 [stopPlayingStream] 或 [destroyStream] 也会卸载播放组件。

支持版本：3.8.0 及以上

stopAudio

stopAudio(): void

停止播放媒体流的音频。

业务场景：界面上不再需要展示媒体流视频内容。
调用时机：创建 ZegoStreamView 实例后，且已经开始采集流以及执行[playAudio]后。
相关接口：调用 [stopPlayingStream] 或 [destroyStream] 也会卸载播放组件。

支持版本：3.8.0及以上

resume

resume(): void

恢复播放页面上的音视频。

当视频浏览器限制而阻止播放时，可以在 DOM 点击事件中调用该接口恢复播放页面上的音视频。

业务场景：在界面上显示媒体流内容。
调用时机：创建 ZegoStreamView 实例后。

支持版本：2.17.0 及以上

setAudioMuted

setAudioMuted(muted: boolean): boolean

开关音频的播放。

参数

名称	类型	描述
muted	boolean	是否禁止，true 表示禁止，false 表示恢复开启。

详情

开关音频的播放。

业务场景：停止或恢复播放媒体流的音频。
调用时机：调用 ZegoStreamView 实例的 [play] 方法进行挂载组件后调用。

支持版本：2.17.0 及以上
注意事项：该接口只会停止播放媒体流的音频，不会影响媒体流的音频传输内容。停止发送音频需要调用 [mutePublishStreamAudio] 接口，停止接收音频调用 [mutePlayStreamAudio] 接口。

返回值

标识接口是否调用成功。

setVideoMuted

setVideoMuted(muted: boolean): boolean

开关视频的播放。

参数

名称	类型	描述
muted	boolean	是否禁止，true 表示禁止，false 表示恢复开启。

详情

开关视频播放。

业务场景：停止或恢复播放媒体流的视频。
调用时机：调用 ZegoStreamView 实例的 [play] 方法进行挂载组件后调用。

支持版本：2.17.0 及以上
注意事项：该接口只会停止播放媒体流的视频，不会影响媒体流的视频传输内容。停止发送视频需要调用 [mutePublishStreamVideo] 接口，停止接收视频调用 [mutePlayStreamVideo] 接口。

返回值

标识接口是否调用成功。

useAudioOutputDevice

useAudioOutputDevice(deviceID: string): Promise<void>

切换音频输出设备。

参数

名称	类型	描述
deviceID	string	扬声器设备 ID。

详情

设置音频输出设备。

调用时机：用 [getSpeakers] 获取音频输出设备列表后。
相关接口：获取扬声器列表接口 [getSpeakers]。

支持版本：2.17.0 及以上。
注意事项：该接口当前只支持 Chrome 浏览器使用。

setVolume

setVolume(volume: number): boolean

设置音频播放音量。

参数

名称	类型	描述
volume	number	音量大小，取值范围 [0,100] 。

详情

设置音频播放音量。

调用时机：创建 ZegoStreamView 实例后。

支持版本：2.17.0 及以上
注意事项：在 Safari 中设置音量为 0，可能不起效，可以使用 setAudioMuted 将音频静音播放。

返回值

接口是否调用成功。

on

on<K extends keyof StreamViewEvent >(event: K, callback: StreamViewEvent[K]): boolean

注册回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callback	StreamViewEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。可监听的事件回调可以通过 StreamViewEvent 查看。

业务场景：用于注册媒体流组件功能相关的业务事件的回调处理。
调用时机：创建 ZegoStreamView 实例之后。
相关接口：调用接口 off 来注销对应回调事件处理。

支持版本：2.17.0 及以上
注意事项：同样的事件可以注册多个, 相同的注册事件，会根据注册的先后顺序依次触发。

返回值

注册是否成功。

off

off<K extends keyof StreamViewEvent >(event: K, callback?: StreamViewEvent[K]): boolean

注销回调事件。

参数

名称	类型	描述
event	K	监听事件名。
callback	StreamViewEvent[K]	回调函数。

详情

用于处理 SDK 主动通知开发者回调的接口，通过注册不同 event 的事件，可以收到不同功能的回调。用于删除注册的同一类回调事件。

业务场景：用于媒体流播放组件的业务事件的回调处理。
调用时机：创建 ZegoStreamView 实例之后。

支持版本：2.17.0 及以上
注意事项：如果没有传要注销的回调函数参数 [callback]，将会注销所有该事件的回调函数。

返回值

注销回调是否成功。

takeStreamSnapshot

takeStreamSnapshot(option?: ZegoSnapshotOptions): string

客户端截图

参数

名称	类型	描述
option?	ZegoSnapshotOptions	截图相关配置选项

详情

获取当前渲染的视频帧数据。

业务场景：对当前（推流/拉流）渲染的视频画面进行截图。
调用时机：创建 view.play 之后。

支持版本：2.18.0 及以上。

返回值

包含 data URI 的 DOMString。