Class

ZegoAudioEffectPlayer

Declared in ZegoExpressAudioEffectPlayer.js

方法

start

start(audioEffectID: number, path?: string, config?: ZegoAudioEffectPlayConfig): void

开始播放音效。

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	音效资源的 ID。SDK 内部使用 audioEffectID 进行音效的播放控制，SDK 不强制用户以固定形式的值传入该参数，最好保证每个音效可以有唯一的 ID，推荐的方式有静态自增 ID 和传入音效文件路径的 hash 两种方式。
path	string	音效资源的路径。<br>取值范围：目前仅支持播放本地文件，不支持 "assets://"、"ipod-library://" 和网络资源等。如果之前使用 [loadResource] 预先加载了音效，可传入 nil 或 ""。
config	ZegoAudioEffectPlayConfig	音效播放配置。<br>默认值：传空则仅播放一次，且不会混音入推流中。

详情

开始播放音效，默认仅播放一次，且不会将音效混入推流中，如需修改请配置 [config] 参数。

业务场景：当需要播放简短的声音效果，比如鼓掌，欢呼声等时，可以使用该接口实现，进一步通过 [config] 参数配置播放次数，将音效混入推流中。
调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：无。

stop

stop(audioEffectID: number): void

停止播放音效。

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

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

调用时机：指定的 [audioEffectID] 已经 [start] 。

支持版本：1.16.0 及以上。
使用限制：无。

pause

pause(audioEffectID: number): void

暂停播放音效。

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

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

调用时机：指定的 [audioEffectID] 已经 [start]。

支持版本：1.16.0 及以上。
使用限制：无。

resume

resume(audioEffectID: number): void

恢复播放音效。

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

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

调用时机：指定的 [audioEffectID] 处于 [pause] 状态。

支持版本：1.16.0 及以上。
使用限制：无。

stopAll

stopAll(): void

停止播放所有音效。

Declared in ZegoExpressAudioEffectPlayer.js

停止播放所有音效。

调用时机：正在播放音效。

支持版本：1.16.0 及以上。
使用限制：无。

pauseAll

pauseAll(): void

暂停播放所有音效。

Declared in ZegoExpressAudioEffectPlayer.js

暂停播放所有音效。

调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：无。

resumeAll

resumeAll(): void

恢复播放所有音效。

Declared in ZegoExpressAudioEffectPlayer.js

恢复播放所有音效。

调用时机：在 [pauseAll] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：无。

seekTo

seekTo(audioEffectID: number, millisecond: number): Promise<Object>

设置播放进度。

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	音效资源的 ID。
millisecond	number	指定的播放进度的时间点。

详情

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

调用时机：指定的 [audioEffectID] 已经 [start]，且还没有播完。

支持版本：1.16.0 及以上。
使用限制：无。

返回值

指定播放进度结果。

setVolume

setVolume(audioEffectID: number, volume: number): void

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

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	音效资源的 ID。
volume	number	音量值。<br>取值范围：范围为 0 ~ 200。 <br>默认值：默认为 100。

详情

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

调用时机：指定的 [audioEffectID] 已经 [start]。

支持版本：1.16.0 及以上。
使用限制：无。

setVolumeAll

setVolumeAll(volume: number): void

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

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
volume	number	音量值。<br>取值范围：范围为 0 ~ 200。 <br>默认值：默认为 100。

详情

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

调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：无。

setPlaySpeed

setPlaySpeed(audioEffectID: number, speed: number): void

设置指定音效的播放速度，会同时设置本地播放速度和推流速度（不支持单独设置）。

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	音效资源的 ID。
speed	number	播放的倍速。<br>取值范围：范围为 0.5 ~ 2.0。 <br>默认值：默认为 1.0。

详情

设置指定音效的播放速度，会同时设置本地播放速度和推流速度（不支持单独设置）。

调用时机：指定的 [audioEffectID] 已经 [start]。

支持版本：2.18.0 及以上。
使用限制：无。

getTotalDuration

getTotalDuration(audioEffectID: number): number

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

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

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

调用时机：必须在加载资源完成后才能调用，否则返回值为 0。
相关接口：[start]，[loadResource]。

支持版本：1.16.0 及以上。
使用限制：在 [createAudioEffectPlayer] 之后可调用。

返回值

音效资源的总长度，单位为毫秒。

getCurrentProgress

getCurrentProgress(audioEffectID: number): number

获取当前播放进度。

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

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

调用时机：必须在加载资源完成后才能调用，否则返回值为 0。
相关接口：[start]，[loadResource]。

支持版本：1.16.0 及以上。
使用限制：无。

返回值

当前播放进度。

loadResource

loadResource(audioEffectID: number, path: string): Promise<Object>

加载音效资源。

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	音效资源的 ID。
path	string	音效资源路径，不能传入 nil 或 ""。<br>取值范围：目前仅支持播放本地文件，不支持 "assets://"、"ipod-library://" 和网络资源等。

详情

加载音效资源。

业务场景：在频繁播放相同音效场景中，SDK 为了优化重复读文件并解码的性能，提供了预加载音效文件到内存中的功能。
调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：预加载支持最多同时加载 15 个音效文件，并且音效文件时长不能超过 30s，否则加载会报错。

返回值

加载音效资源结果回调。

unloadResource

unloadResource(audioEffectID: number): void

卸载音效资源。

Declared in ZegoExpressAudioEffectPlayer.js

参数

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

详情

卸载指定音效的音效资源。

调用时机：在音效使用完毕之后，可以通过此函数释放相关资源；否则 SDK 将在 AudioEffectPlayer 实例销毁时释放加载的资源。
相关接口：[loadResource]。

支持版本：1.16.0 及以上。
使用限制：无。

getIndex

getIndex(): number

获取音效播放器索引。

Declared in ZegoExpressAudioEffectPlayer.js

获取音效播放器索引。

调用时机：在 [createAudioEffectPlayer] 之后可调用。

支持版本：1.16.0 及以上。
使用限制：无。

音效播放器索引。

onAudioEffectPlayStateUpdate

onAudioEffectPlayStateUpdate(audioEffectID: number, state: ZegoAudioEffectPlayState, errorCode: number): void

音效播放状态回调。

Declared in ZegoExpressAudioEffectPlayer.js

参数

名称	类型	描述
audioEffectID	number	触发此次回调的音效资源的 ID。
state	ZegoAudioEffectPlayState	音效的播放状态。
errorCode	number	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

当音效播放器的某条音效的播放状态改变时会触发此回调。

通知时机：当音效的播放状态变化时会触发这个回调。

支持版本：1.16.0 及以上。
使用限制：无。

ZegoCopyrightedMusic

Declared in ZegoExpressCopyrightedMusic.js

方法

initCopyrightedMusic

initCopyrightedMusic(config: ZegoCopyrightedMusicConfig): Promise<Object>

初始化版权音乐模块。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

调用时机：在创建版权音乐 [createCopyrightedMusic] 和登录房间 [loginRoom] 之后。

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

返回值

初始化版权音乐结果通知。

getCacheSize

getCacheSize(): number

获取缓存大小。

Declared in ZegoExpressCopyrightedMusic.js

在使用本模块时，可能产生一些缓存文件，可以通过本接口获取缓存文件的大小。

业务场景：用于展示 App 的缓存大小。
调用时机：在创建版权音乐 [createCopyrightedMusic] 之后。

支持版本：2.13.0 及以上。

获取缓存大小。

clearCache

clearCache(): void

清除缓存。

Declared in ZegoExpressCopyrightedMusic.js

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

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

支持版本：2.13.0 及以上。

sendExtendedRequest

sendExtendedRequest(command: string, params: string): Promise<Object>

发送扩展功能请求。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

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

支持版本：2.13.0 及以上。

返回值

发送扩展功能请求结果回调

getLrcLyricWithVendorID

getLrcLyricWithVendorID(songID: string, vendorID: ZegoCopyrightedMusicVendorID): Promise<Object>

获取 lrc 格式歌词。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

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

支持版本：3.2.1 及以上。

返回值

获取 lrc 格式歌词完成回调。

getLrcLyricWithConfig

getLrcLyricWithConfig(config: ZegoCopyrightedMusicGetLyricConfig): Promise<Object>

获取 lrc 格式歌词。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicGetLyricConfig	获取歌词的配置。

详情

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

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

支持版本：3.12.0 及以上。

返回值

获取 lrc 格式歌词完成回调。

getKrcLyricByToken

getKrcLyricByToken(krcToken: string): Promise<Object>

获取逐字歌词。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
krcToken	string	通过调用 [requestResource] 点伴奏或点高潮片段、或调用 [getSharedResource] 接口获取分享资源时获取的 krcToken。详情请参考 https://doc-zh.zego.im/article/15079#2_2

详情

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

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

支持版本：2.13.0 及以上。

返回值

获取逐字格式歌词完成回调。

requestResource

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

获取音乐资源。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	获取音乐资源的配置。
type	ZegoCopyrightedMusicResourceType	版权音乐资源类型。

详情

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

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

支持版本：3.0.2 及以上。
注意事项： 1. 每个资源有唯一的资源 ID。 2. 每调用一次此接口，都会触发一次计费，详情请咨询 ZEGO 商务人员。 3. 调用本接口获取到的资源，具有时效性，有效时长为 “SDK 初始化生命周期结束” 与 “24 小时资源有效期” 两者之间的最小值。

返回值

获取音乐资源结果回调。

requestResourceWithConfigV2

requestResourceWithConfigV2(config: ZegoCopyrightedMusicRequestConfigV2): Promise<Object>

获取音乐资源。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfigV2	获取音乐资源的配置。

详情

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

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

支持版本：3.12.0 及以上。
注意事项： 1. 每个资源有唯一的资源 ID。 2. 每调用一次此接口，都会触发一次计费，详情请咨询 ZEGO 商务人员。 3. 调用本接口获取到的资源，具有时效性，有效时长为 “SDK 初始化生命周期结束” 与 “24 小时资源有效期” 两者之间的最小值。

返回值

获取音乐资源结果回调。

getSharedResource

  getSharedResource(config: ZegoCopyrightedMusicGetSharedConfig, type: ZegoCopyrightedMusicResourceType): Promise<Object>

获取分享歌曲资源。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicGetSharedConfig	获取分享歌曲资源的配置。
type	ZegoCopyrightedMusicResourceType	版权音乐资源类型。

详情

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

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

支持版本：3.0.2 及以上。
注意事项：每个资源有唯一的资源 ID。调用本接口获取到的资源，具有时效性，有效时长为 “SDK 初始化生命周期结束” 与 “24 小时资源有效期” 两者之间的最小值。

返回值

获取分享音乐资源结果回调。

getSharedResourceWithConfigV2

getSharedResourceWithConfigV2(config: ZegoCopyrightedMusicGetSharedConfigV2): Promise<Object>

获取分享歌曲资源。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicGetSharedConfigV2	获取分享歌曲资源的配置。

详情

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

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

支持版本：3.12.0 及以上。
注意事项：每个资源有唯一的资源 ID。调用本接口获取到的资源，具有时效性，有效时长为 “SDK 初始化生命周期结束” 与 “24 小时资源有效期” 两者之间的最小值。

返回值

获取分享音乐资源结果回调。

download

download(resourceID: string): Promise<Object>

下载音乐资源。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

下载音乐资源，下载成功后才能进行播放。

业务场景：获取音乐资源授权后，利用本接口下载对应的资源。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。
注意事项：下载版权音乐资源受网络影响。

返回值

下载歌曲或伴奏完成回调。

queryCacheWithConfig

queryCacheWithConfig(config: ZegoCopyrightedMusicQueryCacheConfig): boolean

查询资源是否有缓存。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicQueryCacheConfig	查询资源缓存的配置。

详情

查询资源是否有缓存

业务场景：可以用于在查询歌曲资源是否有缓存。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：3.9.0 及以上。

返回值

资源缓存是否存在。

queryCacheWithConfigV2

queryCacheWithConfigV2(config: ZegoCopyrightedMusicQueryCacheConfigV2): boolean

查询资源是否有缓存。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicQueryCacheConfigV2	查询资源缓存的配置。

详情

查询资源是否有缓存

业务场景：可以用于在查询歌曲资源是否有缓存。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：3.12.0 及以上。

返回值

资源缓存是否存在。

getDuration

getDuration(resourceID: string): number

获取歌曲或伴奏文件的播放时长。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取歌曲或伴奏文件的播放时长。

业务场景：可以用于在视图上显示歌曲或伴奏的播放时长信息。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。

返回值

歌曲或伴奏文件的播放时长。

setScoringLevel

setScoringLevel(level: number): void

设置打分难度级别。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

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

支持版本：2.22.0 及以上。
注意事项：该方法不支持动态设置，调用该方法成功后，下一次调用 [startScore] 生效。

startScore

startScore(resourceID: string, pitchValueInterval: number): number

开始评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
resourceID	string	伴奏或高潮片段对应的资源 ID。
pitchValueInterval	number	实时音高线回调的时间间隔, 单位毫秒，默认 50 毫秒。

详情

开始评分后，将会根据设置的回调时间间隔，收到评分结果 [OnCurrentPitchValueUpdate] 回调。

业务场景：可以用于在视图上显示唱歌评分。
调用时机：在获取到逐字歌词，并播放版权音乐的伴奏资源之后可调用。

支持版本：2.15.0 及以上。
注意事项：目前仅支持在推流开始 [startPublishingStream] 后，才能开始打分。

返回值

错误码。

pauseScore

pauseScore(resourceID: string): number

暂停评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

暂停正在进行的评分，将停止 [OnCurrentPitchValueUpdate] 回调。

业务场景：正在评分时可调用此接口暂停评分功能。
调用时机：正在评分时可调用。

支持版本：2.15.0 及以上。

返回值

错误码。

resumeScore

resumeScore(resourceID: string): number

恢复评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

恢复当前暂停的评分。

业务场景：当前有暂停的评分时可调用此接口恢复评分功能。
调用时机：当前有暂停的评分时可调用。

支持版本：2.15.0 及以上。

返回值

错误码。

stopScore

stopScore(resourceID: string): number

结束评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

业务场景：正在评分时可调用此接口结束评分。
调用时机：正在评分时可调用。

支持版本：2.15.0 及以上。

返回值

错误码。

resetScore

resetScore(resourceID: string): number

重置评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

重置已经进行过的评分，将停止 [OnCurrentPitchValueUpdate] 回调，获取平均分或总分将为 0。

业务场景：常用于重唱同一首歌的场景。
调用时机：已经进行过评分后可以调用。

支持版本：2.15.0 及以上。

返回值

错误码。

getPreviousScore

getPreviousScore(resourceID: string): number

获取上一句的评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

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

支持版本：2.15.0 及以上。

返回值

上一句的评分。

getAverageScore

getAverageScore(resourceID: string): number

获取平均评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取平均评分。

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

支持版本：2.15.0 及以上。

返回值

平均评分。

getTotalScore

getTotalScore(resourceID: string): number

获取总评分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取总评分。

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

支持版本：2.15.0 及以上。

返回值

总评分。

getFullScore

getFullScore(resourceID: string): number

获取满分。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取满分。

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

支持版本：3.0.2 及以上。

返回值

满分。

getStandardPitch

getStandardPitch(resourceID: string): Promise<Object>

获取标准音高数据。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取标准音高数据。

业务场景：可以用于在视图上显示标准音高线。

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

返回值

获取标准音高数据完成回调。

getCurrentPitch

getCurrentPitch(resourceID: string): number

获取实时音高数据。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

获取实时音高数据。

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

支持版本：2.15.0 及以上。

返回值

实时音高数据。

requestSong

deprecated

requestSong(config: ZegoCopyrightedMusicRequestConfig): Promise<Object>

【已废弃】点歌。此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	请求配置。

详情

点歌不仅可以获取到歌曲的基本信息（时长、歌名、歌手等），还可以用于本地播放的资源 ID 或用于分享给他人播放的 share_token，还有相关的一些鉴权信息。支持按次点歌方式。

业务场景：获取版权歌曲，用于本地播放与分享。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。
注意事项：该接口会触发计费。一首歌曲可能存在普通、高清、无损三种音质，每种音质都有不同的资源文件，每个资源文件有唯一的资源 ID。

已废弃

此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

返回值

点歌完成回调。

requestAccompaniment

deprecated

requestAccompaniment(config: ZegoCopyrightedMusicRequestConfig): Promise<Object>

【已废弃】点伴奏。此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	请求配置。

详情

可以获取 songID 对应歌曲的伴奏资源，包括 resource_id、krc_token、share_token 等。支持按次点伴奏方式。

业务场景：获取版权歌曲伴奏，用于本地播放与分享。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。
注意事项：该接口会触发计费。

已废弃

此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

返回值

点伴奏完成回调。

requestAccompanimentClip

deprecated

requestAccompanimentClip(config: ZegoCopyrightedMusicRequestConfig): Promise<Object>

【已废弃】点伴奏高潮片段。此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
config	ZegoCopyrightedMusicRequestConfig	请求配置。

详情

可以获取 songID 对应歌曲的高潮片段资源，包括 resource_id、krc_token、share_token 等。支持按次点伴奏高潮片段方式。

业务场景：获取版权歌曲伴奏高潮片段，用于本地播放与分享。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。
注意事项：该接口会触发计费。

已废弃

此函数在 3.0.2 版本及以上已废弃，请使用 [requestResource] 函数代替。

返回值

点伴奏高潮片段完成回调。

getMusicByToken

deprecated

getMusicByToken(shareToken: string): Promise<Object>

【已废弃】获取歌曲或伴奏。此函数在 3.0.2 版本及以上已废弃，请使用 [getSharedResource] 函数代替。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
shareToken	string	访问一首歌曲或伴奏的对应授权 token。

详情

通过他人分享的歌曲或伴奏 token，获取对应的一首歌曲或伴奏。

业务场景：在线 KTV 场景中，合唱者收到主唱分享的歌曲或伴奏 token 后，通过本接口获取对应的一首歌曲或伴奏，然后在本端进行播放。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。

已废弃

此函数在 3.0.2 版本及以上已废弃，请使用 [getSharedResource] 函数代替。

返回值

通过授权 token 获取歌曲或伴奏完成回调。

getLrcLyric

deprecated

getLrcLyric(songID: string): Promise<Object>

【已废弃】获取 lrc 格式歌词。此函数在 3.2.1 版本及以上已废弃，请使用 [getLrcLyricWithVendorID]。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

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

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

支持版本：2.13.0 及以上。

已废弃

此函数在 3.2.1 版本及以上已废弃，请使用 [getLrcLyricWithVendorID]。

返回值

获取 lrc 格式歌词完成回调。

queryCache

deprecated

queryCache(songID: string, type: ZegoCopyrightedMusicType): boolean

【已废弃】查询资源是否有缓存。此函数在 3.2.1 版本及以上已废弃，请使用 [queryCacheWithVendorID]。

Declared in ZegoExpressCopyrightedMusic.js

参数

名称	类型	描述
songID	string	歌曲或伴奏的 ID，一首歌的歌曲和伴奏共用同一个 ID。
type	ZegoCopyrightedMusicType	歌曲资源类型。

详情

查询资源是否有缓存。

业务场景：可以用于在查询歌曲资源是否有缓存。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：2.13.0 及以上。

已废弃

此函数在 3.2.1 版本及以上已废弃，请使用 [queryCacheWithVendorID]。

返回值

是否有缓存。

queryCacheWithVendorID

deprecated

  queryCacheWithVendorID(songID: string, type: ZegoCopyrightedMusicType, vendorID: ZegoCopyrightedMusicVendorID): boolean

【已废弃】查询资源是否有缓存。此函数在 3.9.0 版本及以上已废弃，请使用带 [config] 参数的函数 [queryCacheWithConfig] 代替。

Declared in ZegoExpressCopyrightedMusic.js

参数

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

详情

查询资源是否有缓存

业务场景：可以用于在查询歌曲资源是否有缓存。
调用时机：在初始化版权音乐 [initCopyrightedMusic] 成功之后。

支持版本：3.2.1 及以上。

已废弃

此函数在 3.9.0 版本及以上已废弃，请使用带 [config] 参数的函数 [queryCacheWithConfig] 代替。

返回值

是否有缓存。

ZegoExpressEngine

Declared in ZegoExpressEngine.js

方法

createEngine

static

createEngine

createEngine(profile: ZegoEngineProfile): Promise<Object>

创建 ZegoExpressEngine 单例对象并初始化 SDK。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
profile	ZegoEngineProfile	用来创建引擎的基础配置信息。

详情

创建 ZegoExpressEngine 单例对象并初始化 SDK。

调用时机：SDK 其他实例方法调用之前。

支持版本：2.14.0 及以上。
使用限制：无。
注意事项：SDK 只支持创建一个实例，如需重复调用 [createEngine] ，则需在第二次调用 [createEngine] 前先调用 [destroyEngine] 函数销毁引擎，否则再次调用此函数返回的都是上次创建的对象。

返回值

创建引擎的结果通知回调。

destroyEngine

static

destroyEngine

destroyEngine(): void

销毁 ZegoExpressEngine 单例对象并反初始化 SDK。

Declared in ZegoExpressEngine.js

销毁 ZegoExpressEngine 单例对象并反初始化 SDK。

调用时机：当不再使用 SDK 时，可以通过本接口释放 SDK 使用的资源。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：使用 [createEngine] 创建单例后，如果单例对象未被创建或已被销毁，调用此函数时，不会收到相关回调。

setEngineConfig

static

setEngineConfig

setEngineConfig(config: ZegoEngineConfig): void

设置引擎进阶配置。

Declared in ZegoExpressEngine.js

参数

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

详情

用于开启进阶功能。

调用时机：不同的配置有不同的调用时机要求，详情可咨询 ZEGO 技术支持。

支持版本：1.1.0 及以上。
使用限制：无。

setLogConfig

static

setLogConfig

setLogConfig(config: ZegoLogConfig): void

设置日志配置。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	ZegoLogConfig	日志配置。

详情

开发者当需要自定义日志文件大小和路径时，需要调用此函数来完成配置。

调用时机：必须在调用 [createEngine] 之前设置才生效，若在 [createEngine] 之后设置，则在 [destroyEngine] 后的下一次 [createEngine] 时生效。

支持版本：2.3.0 及以上。
使用限制：无。
注意事项：一旦调用了本接口，通过 [setEngineConfig] 设置日志大小和路径的方式将无效。因此，不建议使用[setEngineConfig] 设置日志大小和路径。

setRoomMode

static

setRoomMode

setRoomMode(mode: ZegoRoomMode): void

设置房间模式。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoRoomMode	房间模式。详情描述：用于设置房间模式。业务场景：当需要同时进入多个房间进行推拉流时，可以通过本接口开启多房间模式。是否必填：是。默认值：ZEGO_ROOM_MODE_SINGLE_ROOM。

详情

开发者需要使用多房间功能时，需要调用此函数来完成配置。

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

支持版本：2.9.0 及以上。
使用限制：如果需要使用多房间功能，请与即构技术支持联系配置服务端支持。
注意事项：无。

setGeoFence

static

setGeoFence

setGeoFence(type: ZegoGeoFenceType, areaList: Array<number>): void

设置地理围栏。

Declared in ZegoExpressEngine.js

参数

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

详情

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

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

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

getVersion

static

getVersion

getVersion(): string

获取 SDK 版本号。

Declared in ZegoExpressEngine.js

在 SDK 在运行过程中若遇到异常，可将问题、日志等信息提交 ZEGO 技术人员定位与排障。开发者也可通过该 API 收集当前 SDK 版本信息，便于 App 运营统计以及关联问题。

调用时机：任意时刻。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：无。

SDK 版本号。

isFeatureSupported

static

isFeatureSupported

isFeatureSupported(featureType: ZegoFeatureType): boolean

查询当前 SDK 是否支持指定的功能特性。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
featureType	ZegoFeatureType	要查询的功能特性类型。

详情

由于 SDK 支持特性裁包，部分特性可能已被裁剪；可以使用此函数快速判断当前 SDK 是否支持指定的功能特性，例如，查询是否支持媒体播放器功能。

调用时机：任意时刻。

支持版本：2.22.0 及以上。

返回值

是否支持指定功能特性。true 表示支持；false 表示不支持。

init

static

init

deprecated

init(appID: number, appSign: string, isTestEnv: boolean, scenario: ZegoScenario): Promise<Object>

【已废弃】初始化引擎。此函数在 2.14.0 版本及以上已废弃，请使用 [createEngine] 函数代替。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
appID	number	ZEGO 为开发者签发的应用 ID，请从 ZEGO 管理控制台 https://console-express.zego.im 申请。appID 取值范围 0~4294967295。
appSign	string	每个 AppID 对应的应用签名，请从 ZEGO 管理控制台申请。该参数为包含 64 个字符的字符串，字符取值范围：'0' ~ '9', 'a' ~ 'z'。例："9dc9a25bh2f2137446897071c8c033fa33b91c3dd2a85e0c000ae82c0dad3"。2.17.0 及以上版本 appSign 允许传空或者不传。如果传空或者不传，则必须在调用 [loginRoom] 接口登录房间时将 token 填入 [ZegoRoomConfig] 参数中，用于鉴权。token 的生成方式请参考使用 Token 鉴权。
isTestEnv	boolean	【已废弃】为提供更便捷、更标准的服务，ZEGO 已统一环境概念，2021-11-16 之后，不再有正式环境/测试环境之分，2021-11-16 及之前在 ZEGO 控制台创建项目的用户，可参考测试环境废弃说明进行 SDK 升级和调整相关代码。
scenario	ZegoScenario	房间场景，SDK 会针对指定的场景的做一些音视频配置优化以达成在此场景下最优的效果。指定场景后，开发者可以使用 [setRoomScenario] 来实现在不销毁引擎 [destroyEngine] 的前提下切换其他场景。指定场景后，开发者可以调用其他 API 来继续调整音视频配置。各个场景之间的差异以及如何选择合适的场景请参考 https://doc-zh.zego.im/article/16316

详情

在调用其他函数前需要先创建并初始化引擎

已废弃

此函数在 2.14.0 版本及以上已废弃，请使用 [createEngine] 函数代替。

返回值

引擎单例对象

setRoomScenario

setRoomScenario(scenario: ZegoScenario): void

设置房间场景。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
scenario	ZegoScenario	房间场景。

详情

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

业务场景：此函数适用于多种音视频业务场景的 App，例如有 1v1 音视频通话场景和秀场直播场景；通过此函数可以实现在不销毁引擎 [destroyEngine] 的前提下切换场景。
调用时机：必须在调用 [createEngine] 之后且调用 [loginRoom] 之前设置。

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

uploadLog

uploadLog(): void

上传日志到 ZEGO 服务器。

Declared in ZegoExpressEngine.js

默认情况下，SDK 会在 App 默认目录创建日志文件并打印，每个日志文件默认最大 5MB，三个日志文件循环覆盖写入。当调用此函数时 SDK 会自动将日志文件打包并上传到 ZEGO 服务器。

业务场景：开发者可在 App 提供业务上的“反馈”渠道，当用户反馈的问题属于 ZEGO SDK 时，可调用此函数将 SDK 的本地日志信息上传，并联系 ZEGO 技术支持协助定位用户问题。
调用时机：在 [createEngine] 后。

支持版本：1.1.0 及以上。
使用限制：限频每分钟1次。
注意事项：1.在调用本接口上传日志后，如果过快的调用 [destroyEngine] 或退出 App，则可能存在失败的情况。建议等待几秒，等收到上传成功回调后，再调用 [destroyEngine] 或退出 App。2.如果希望在 [createEngine] 之前调用，请调用 [submitLog] 接口。

enableDebugAssistant

enableDebugAssistant(enable: boolean): void

开启调试助手。注意，请勿在线上版本开启此功能！仅在开发阶段使用！

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启调试助手。

详情

开启后，SDK 将会打印日志到控制台，并且将会在 SDK 其他函数的调用发生问题时 UI 弹窗提示错误。

默认值：默认不开启。
调用时机：可在创建引擎 [createEngine] 后立刻调用此函数。
平台差异：弹窗提示功能仅支持 Android / iOS / macOS / Windows，而输出控制台日志功能支持全平台。

支持版本：2.17.0 及以上。
使用限制：无。
注意事项：请务必在 App 发布前确认此功能已关闭，以避免在正式版本中当发生错误时弹出 UI 提示。建议将此函数的 [enable] 参数与 App 的 DEBUG 变量相关联，即仅在 DEBUG 环境下开启调试助手。

callExperimentalAPI

callExperimentalAPI(params: string): string

调用实验性 API。

Declared in ZegoExpressEngine.js

参数

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

详情

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

调用时机：在 [createEngine] 后。

支持版本：2.7.0 及以上。

返回值

返回的参数，格式为 JSON 字符串，具体可咨询 ZEGO 技术支持。

onDebugError

onDebugError(errorCode: number, funcName: string, info: string): void

调试错误信息回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
errorCode	number	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
funcName	string	函数名。
info	string	错误的详细信息。

详情

调用 SDK 函数出现异常时，会通过该回调提示详细的异常信息。

业务场景：开发者在集成 SDK 的开发、测试阶段，可以通过本回调中的详细异常信息快速定位问题。
通知时机：在 SDK 出现异常时通知开发者。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：无。

onEngineStateUpdate

onEngineStateUpdate(state: ZegoEngineState): void

音视频引擎状态更新的回调通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
state	ZegoEngineState	音视频引擎状态。

详情

音视频引擎状态更新的回调通知，当启用音视频功能时，比如预览、推流、本地媒体播放器、原始音频数据获取等，音视频引擎会进入开始状态，当退出房间或停用所有音视频功能时，音视频引擎会进入停止状态。

通知时机：开发者调用了相关函数改变了音视频引擎的状态。例如：1. 调用了ZegoExpressEngine的 [startPreview]、[stopPreview]、[startPublishingStream]、[startPlayingStream]、[startAudioDataObserver] 等函数。2. 调用了 MediaPlayer 的相关函数等。3. 调用了 [logoutRoom] 函数。4.调用了 RealTimeSequentialDataManager 的相关接口等。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项： 1. 开发者调用 [destroyEngine] 时，由于 SDK 的资源被完全释放，并不会触发此通知。 2. 如无特殊需要，开发者可以不必关注本回调。

onRecvExperimentalAPI

onRecvExperimentalAPI(content: string): void

实验性 API 回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
content	string	回调的内容，JSON 字符串格式。

详情

接收实验性 API 回调，请在 ZEGO 技术支持的帮助下使用此功能。

支持版本：2.7.0 及以上。

loginRoom

loginRoom(roomID: string, user: ZegoUser, config: ZegoRoomConfig): void

使用带配置进阶属性的方式登录房间，通过回调参数返回登录结果，推拉流前必须登录房间。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，不得为空，最大长度小于 128 字节的字符串。注意事项： 1.房间 ID 由您自己定义。 2. 仅支持数字，英文字符和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。 3. 如果需要与 Web SDK 互通，请不要使用 '%'。
user	ZegoUser	用户对象实例，配置用户 ID、用户名。注意事项：注意用户 ID 需要在相同的 appID 下全局唯一，否则会出现后登录的用户踢掉先登录的用户的情况。
config	ZegoRoomConfig	房间进阶配置。

详情

如果房间不存在，[loginRoom] 会创建并登录房间。SDK 用"房间"概念来组织用户，用户必须首先登录某个房间，才能进行一系列关键操作，比如推流 [startPublishingStream]、拉流[startPlayingStream]、收发广播消息 [sendBroadcastMessage] 等。为了防止 App 被恶意用户模拟登录，可以在登录房间之前加上鉴权验证，即 [config] 参数传入的 ZegoRoomConfig 对象中的 [token] 参数。

业务场景：在同一个房间内用户可以进行直播、音视频通话等。
调用时机：在 [createEngine] 初始化 SDK 之后调用该函数。
相关回调： 1. 当用户开始登录房间、登录房间成功或登录房间失败后，将会触发 [onRoomStateChanged] (2.18.0 之前版本不支持，请使用 [onRoomStateUpdate]) 回调通知开发者当前用户连接房间的状态。 2. 登录同一个房间的不同用户可以得到以相同房间为单位的房间信令通知（例如：[onRoomUserUpdate], [onRoomStreamUpdate] 等），一个房间内的用户收不到另一个房间房间信令的通知。 3. 如果由于网络质量原因导致网络临时中断，SDK 内部会自动进行重连。可通过监听 [onRoomStateChanged] (2.18.0 之前版本不支持，请使用 [onRoomStateUpdate]) 回调获取本端当前房间连接状态的变化情况，同时同房间其他用户会接收到 [onRoomUserUpdate] 回调通知。详情请参考 https://doc-zh.zego.im/faq/reconnect 4. 一个房间发的消息（例如 [setStreamExtraInfo], [sendBroadcastMessage], [sendBarrageMessage], [sendCustomCommand] 等）在别的房间无法收到（例如 [onRoomStreamExtraInfoUpdate], [onIMRecvBroadcastMessage], [onIMRecvBarrageMessage], [onIMRecvCustomCommand] 等），目前 ZegoExpressEngine 未提供跨房间消息的能力。开发者可以集成 IM 的 SDK 来实现。
相关接口： 1. 可调用 [logoutRoom] 退出登录，如果没有退出登录而重复调用登录接口(roomID 和 user 保持相同的情况下)，控制台会报错，打印错误码 1002001。 2. 如果需要登录多个房间，请在创建引擎前通过 [ZegoRoomMode] 选择多房间模式，然后调用 [loginRoom] 接口登录多房间。 3. 调用 [destroyEngine] 也会使用户自动退出登录。

支持版本：2.18.0 及以上。
使用限制：同一房间登录接口的调用频率 (QPS) 有一定限制，详情查阅 https://doc-zh.zego.im/article/7581 或联系 ZEGO 技术支持。
注意事项： 1. 使用不同 appID 的 App 不能互通。 2. SDK 支持拉相同 appID 下非同一个房间的流，即跨房间拉流。由于 SDK 的房间信令的相关回调通知是以相同房间为单位，当开发者想要跨房间拉流时，开发者需自行维护相关的消息及信令通知。 3. 强烈建议 userID 与业务 APP 的用户 ID 一一对应，即一个 userID 与一个真实用户是固定且唯一的，而不应该是以随机的 userID 的方式传给 SDK 的方式。因为唯一且固定的 userID 可以让 ZEGO 技术人员快速定位线上问题。 4. 首次因网络原因登录失败或者房间断开连接之后，SDK 重连默认时间为 20min。隐私保护申明：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

logoutRoom

logoutRoom(roomID: string): void

退出指定房间 ID 的房间。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，最大长度为 128 字节的字符串。注意事项： 1. 仅支持数字，英文字符和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。 2. 如果需要与 Web SDK 互通，请不要使用 '%'。 3. 如果不传该参数，SDK 会退出当前用户已登录的房间，若开启了多房间，则全部房间均会被退出。

详情

该接口会退出房间名为 roomID 的房间。

业务场景：在同一个房间内用户可以进行直播、音视频通话等。
调用时机：登录房间成功后，若不再使用房间功能，用户可以调用函数 [logoutRoom]。
相关回调：调用此函数后会收到 [onRoomStateChanged] (2.18.0 之前版本不支持，请使用 [onRoomStateUpdate]) 回调通知成功退出房间，同时同房间其他用户会接收到 [onRoomUserUpdate] 回调通知（开启 isUserStatusNotify 配置的前提下）。
相关接口：用户可以调用 [loginRoom]、[switchRoom] 函数登录或更换房间。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：1. 退出房间会停止该用户的所有推拉流，引擎会停止，SDK 内部会主动停止本地预览。如果切换房间想保留预览能力，请使用 [switchRoom] 函数。2. 若用户登出房间，但传入 roomID 与已登录房间名不同，SDK 会返回失败。

switchRoom

switchRoom(fromRoomID: string, toRoomID: string, config: ZegoRoomConfig): void

使用配置进阶属性的方式切换房间。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
fromRoomID	string	当前处于的房间 ID。
toRoomID	string	需要登录的下一个房间 ID。
config	ZegoRoomConfig	房间进阶配置。

详情

使用此函数可以让用户快速从一个房间切换到另外一个房间。

业务场景：若需要快速切换到下一个房间，可调用此函数。
调用时机：登录房间成功后。
相关回调：当用户调用 [switchRoom] 函数时，将会触发 [onRoomStateChanged] (2.18.0 之前版本不支持，请使用 [onRoomStateUpdate]) 回调通知开发者当前用户连接房间的状态。
相关接口：用户可以调用 [logoutRoom] 函数退出房间。

支持版本：1.15.0 及以上。
使用限制：无。
注意事项： 1. 当调用此函数后，当前正在推或拉的所有流都将会停止（但本地预览不会停止）。 2. 为了防止 App 被恶意用户模拟登录，可以在切换房间之前加上鉴权验证，即 [config] 参数传入的 ZegoRoomConfig 对象中的 [token] 参数。此参数配置作用于即将切换过去的房间。 3. 3.5.0 版本开始支持多房间模式（使用函数 [setRoomMode] 设置 ZegoRoomMode 为 ZEGO_ROOM_MODE_MULTI_ROOM）。 4. 若登录房间 [loginRoom] 时传入了 Token 进行登录，则调用 [switchroom] 切换房间时，必须使用带有 config 参数的 [switchroom] 接口切换房间，并传入对应 Token 值。隐私保护申明：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

renewToken

renewToken(roomID: string, token: string): void

更新 token 鉴权信息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID。
token	string	需要更新的 token。

详情

当开发者收到 [onRoomTokenWillExpire] 之后，可使用此 API 更新 token 鉴权信息，保障后续 RTC 功能正常。

业务场景：Token 将要过期时使用。
调用时机：收到 [onRoomTokenWillExpire] 之后。

支持版本：2.8.0 及以上。
使用限制：无。
注意事项：Token 中包含用户的房间权限、推流权限、有效时间等重要信息，详情请参考 https://doc-zh.zego.im/article/10360 。

setRoomExtraInfo

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

设置房间附加消息。

Declared in ZegoExpressEngine.js

参数

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

详情

用户调用此函数设置房间的附加消息。

业务场景：可以设置一些房间相关的业务属性，比如是否有人在上麦。
调用时机：登录房间成功后。
相关回调：相同房间内的其他用户会通过 [onRoomExtraInfoUpdate] 回调函数获得通知。
相关接口：无。

支持版本：1.13.0 及以上。
使用限制：关于此函数的使用限制，请参考 https://doc-zh.zego.im/article/7581 或联系 ZEGO 技术支持。
注意事项：key、value 的限制，请参考“使用限制”。新设置的 value 会覆盖旧的设置。

返回值

设置房间附加信息执行结果通知

onRoomStateUpdate

onRoomStateUpdate(roomID: string, state: ZegoRoomState, errorCode: number, extendedData: string): void

房间状态变化通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，最大长度为 128 字节的字符串。
state	ZegoRoomState	变化后的房间状态。
errorCode	number	错误码，详情请参考常见错误码。
extendedData	string	状态更新附带的扩展信息。当房间登录成功时，可通过"room_session_id" key 获取每一次音视频通信唯一的 RoomSessionID，标识房间内首个用户发起音视频通信到最后一个用户结束通信的持续通信。可用于通话质量评分、通话问题诊断等场景中。

详情

当房间的连接状态改变时触发该回调，并通知改变的原因。2.18.0 及以上版本推荐使用 onRoomStateChanged 回调来替代 onRoomStateUpdate 回调监听房间状态变化。

业务场景：开发者可以通过这个回调来判断房间内当前用户的状态。
通知时机： 1. 开发者调用 [loginRoom]、[logoutRoom]、[switchRoom] 函数时会收到此通知。

用户设备的网络情况变化时也可能收到此通知 (SDK 在断线时会自动重新登录房间，详情请参考 SDK 是否支持断线重连机制。

相关接口：[loginRoom]、[logoutRoom]、[switchRoom]。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：若长时间处于正在请求连接状态（ZegoRoomStateConnecting），一般是因为用户端网络不稳定导致。

onRoomStateChanged

onRoomStateChanged(roomID: string, reason: ZegoRoomStateChangedReason, errorCode: number, extendedData: string): void

房间状态变化通知，包含具体的状态变化原因。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，最大长度为 128 字节的字符串。
reason	ZegoRoomStateChangedReason	房间状态变化原因。
errorCode	number	错误码，详情请参考常用错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	string	状态更新附带的扩展信息。当房间登录成功时，可通过 "room_session_id" key 获取每一次音视频通信唯一的 RoomSessionID，标识房间内首个用户发起音视频通信到最后一个用户结束通信的持续通信。可用于通话质量评分、通话问题诊断等场景中。

详情

当房间的连接状态改变时触发该回调，并通知改变的原因。2.18.0 及以上版本推荐使用 onRoomStateChanged 回调来替代 onRoomStateUpdate 回调监听房间状态变化。

业务场景：开发者可以通过这个回调来判断房间内当前用户的状态。
通知时机： 1. 开发者调用房间相关函数 (参考 "相关接口") 时会收到此通知。 2. 用户设备的网络情况变化时也可能收到此通知 (SDK 在断线时会自动重新登录房间，详情请参考 https://doc-zh.zego.im/faq/reconnect )。
相关接口：[loginRoom], [logoutRoom], [switchRoom]

支持版本：2.18.0 及以上。
使用限制：无。
注意事项：若长时间处于正在请求连接状态 [ZegoRoomStateConnecting]，一般是因为用户端网络不稳定导致。

onRoomUserUpdate

onRoomUserUpdate(roomID: string, updateType: ZegoUpdateType, userList: ZegoUser[]): void

房间内其他用户增加或减少的回调通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
updateType	ZegoUpdateType	更新类型（添加/删除）。
userList	ZegoUser[]	当前房间内变更的用户列表。

详情

当房间内有其他用户上线或下线时，导致房间内用户列表发生变化，会通过本回调通知开发者。

业务场景：开发者可以通过这个回调来实时更新房间内的用户列表展示。
通知时机： 1. 用户首次登录房间时，如果房间内有其他用户，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知，此时 "userList" 为房间内的其他用户。 2. 用户已在房间内，如果有其他用户通过 [loginRoom]、[switchRoom] 函数登录到本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知。 3. 用户已在房间内，有其他用户通过 [logoutRoom]、[switchRoom] 函数登出本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。 4. 用户已在房间内，如果有其他用户从服务端被踢出本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。
相关接口：[loginRoom]、[logoutRoom]、[switchRoom]。

支持版本：1.1.0 及以上。
使用限制：调用 [loginRoom] 登录房间时设置 [ZegoRoomConfig] 参数中的 "isUserStatusNotify" 属性为 "true" 时，才会接收到这个回调通知。如果开发者需要使用在回调通知中处理相关业务，请确保每个登录的用户都将 "isUserStatusNotify" 设置为 "true"。

onRoomOnlineUserCountUpdate

onRoomOnlineUserCountUpdate(roomID: string, count: number): void

房间内当前在线用户数量回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
count	number	当前在线用户数量。

详情

此方法会通知用户当前房间内的在线人数。

业务场景：开发者可根据此回调来来展示当前房间内的在线人数。
通知时机：登录房间成功后。

支持版本：1.7.0 及以上。
使用限制：无。
注意事项：1. 此函数 30 秒回调一次。2. 因设计如此，当房间内用户超过 500 后，对房间内在线人数的统计会有一些误差。

onRoomStreamUpdate

onRoomStreamUpdate(roomID: string, updateType: ZegoUpdateType, streamList: ZegoStream[], extendedData: string): void

相同房间内其他用户推的流增加或减少的通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
updateType	ZegoUpdateType	更新类型（添加/删除）。
streamList	ZegoStream[]	更新的流列表。
extendedData	string	流更新附带的扩展信息。收到流删除通知时，开发者可将该字符串转为 json 对象得到 stream_delete_reason 字段，该字段为流删除原因的数组，stream_delete_reason[].code 字段可能为如下值：1（用户主动停止推流）； 2（用户心跳超时）； 3（用户重复登录）； 4（用户被踢出）； 5（用户断线）； 6（被服务端移除）。

详情

当房间内有其他用户开始推流或停止推流时，导致房间内流列表发生变化，会通过本回调通知开发者。

业务场景：开发者可根据此回调来判断指定房间内其他用户是否新增推流或停止推流，并根据情况选择调用 [startPlayingStream] 主动拉流或调用[stopPlayingStream] 停止拉流，同时也可以变更拉流的 UI 控件。
通知时机： 1. 用户首次登录房间时，如果房间内其他用户正在推流，SDK 会触发 updateType 为 [ZegoUpdateTypeAdd] 的回调通知，此时 "streamList" 为已存在的流列表。 2. 用户已在房间内，如果有其他用户新增推流，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知。 3. 用户已在房间内，如果有其他用户停止推流，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。 4. 用户已在房间内，如果有其他用户退出房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。

支持版本：1.1.0 及以上。
使用限制：无。

onRoomStreamExtraInfoUpdate

onRoomStreamExtraInfoUpdate(roomID: string, streamList: ZegoStream[]): void

房间内流附加信息更新通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
streamList	ZegoStream[]	流附加信息更新的流列表。

详情

房间内流附加信息更新时所有房间内用户会收到通知。

业务场景：用户可通过流附加信息与流生命周期一致的特性实现一些业务功能。
通知时机：当相同房间内一个正在推流的用户更新了流的附加信息时，相同房间内的其他用户会收到该回调。
相关接口：推流用户可以通过 [setStreamExtraInfo] 设置流附加信息。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：不同于流 ID 在推流过程中不可修改，流附加信息可以在对应流 ID 的生命周期中更新。

onRoomExtraInfoUpdate

onRoomExtraInfoUpdate(roomID: string, roomExtraInfoList: ZegoRoomExtraInfo[]): void

房间附加信息更新通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
roomExtraInfoList	ZegoRoomExtraInfo[]	更新的房间附加信息列表。

详情

房间附加信息更新后，除更新房间附加信息的用户外，房间内所有用户会收到通知。

业务场景：为房间附加信息。
通知时机：当相同房间内其他用户更新了房间附加信息时，相同房间内的其他用户会收到该回调。
相关接口：用户可以通过 [setRoomExtraInfo] 更新房间附加信息。

支持版本：1.1.0 及以上。
使用限制：无。

onRoomTokenWillExpire

onRoomTokenWillExpire(roomID: string, remainTimeInSecond: number): void

房间 Token 鉴权将要过期的回调通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	用户已登录的房间 ID，最大长度为 128 字节的字符串。
remainTimeInSecond	number	token 过期前的剩余时间。

详情

房间 Token 鉴权将要过期的回调通知，请用户通过 [renewToken] 函数更新房间 Token 鉴权。

业务场景：为了防止炸麦场景，需要对登录房间、推流等操作进行鉴权控制，提高安全性。
通知时机：在 Token 过期前 30 秒，SDK 会通过 onRoomTokenWillExpire 回调发出通知。
相关接口：当开发者收到此回调后，可通过 [renewToken] 来更新 token 鉴权信息。

支持版本：2.8.0 及以上。
使用限制：无。
注意事项：Token 中包含用户的房间权限、推流权限、有效时间等重要信息，详情请参考 https://doc-zh.zego.im/article/10360 。

startPublishingStream

startPublishingStream(streamID: string, config?: ZegoPublisherConfig, channel: ZegoPublishChannel): void

开始推流，支持多房间模式

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID，长度不超过 256 的字符串。注意事项： 1. 流 ID 由您自己定义。 2. 需要在整个 AppID 内全局唯一，若出现在同一个 AppID 内，不同的用户各推了一条流且流名相同，将会导致后推流的用户推流失败。 3. 仅支持数字，英文字符和 '-', '_'。
config	ZegoPublisherConfig	推流进阶配置。
channel	ZegoPublishChannel	推流通道。

详情

用户将自己本地的音视频流推送到 ZEGO RTC 服务器或 CDN，同一房间的其他用户通过 "streamID" 或 CDN 拉流地址就可以拉取该音视频流进行观看。

业务场景：可以用于实时连麦、直播等场景下进行推流。
调用时机：调用 [loginRoom] 加入房间后调用该函数。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项： 1. 开始推流前，用户可选择调用 [setVideoConfig] 设置相关视频参数，调用 [startPreview] 进行视频预览。 2. 当推流成功之后，同房间内其他用户可通过监听 [onRoomStreamUpdate] 回调来获取流的新增情况。 3. 在网络质量不佳的情况下，用户推流可能出现中断，SDK 会尝试重连并推流（连接成功后 SDK 会自动进行推流），开发者可通过监听 [onPublisherStateUpdate] 事件来获知当前推流状态以及错误信息。详情请参考 https://doc-zh.zego.im/faq/reconnect 4. 调用 [SetRoomMode] 函数选择多房间，必须明确指定房间 ID。

stopPublishingStream

stopPublishingStream(channel: ZegoPublishChannel): void

停止推流，可停止指定通道的音视频流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

用户停止发送本地的音视频流，房间内其他用户会收到流删除通知。

业务场景：可以用于实时连麦、直播等场景下停止推流。
调用时机：调用 [startPublishingStream] 开始推流后。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项： 1. 在停止推流之后，同房间内其他用户可通过监听 [onRoomStreamUpdate] 回调来收到流的删除通知。 2. 如果用户已经启动推流，在推送新流（与之前的 streamID 不同）之前，必须要调用此函数停止当前流的推送，否则新流推送会返回失败。 3. 在停止推流之后，开发者应该根据业务情况来决定是否需要停止本地预览。

setStreamExtraInfo

setStreamExtraInfo(extraInfo: string, channel: ZegoPublishChannel): Promise<Object>

设置指定推流通道的流附加信息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
extraInfo	string	流附加信息，长度不超过1024的字符串。
channel	ZegoPublishChannel	推流通道。

详情

可通过此函数设置当前推流的流附加信息。流附加信息是流 ID 的附加信息标识，不同于流 ID 在推流过程中不可修改，流附加信息可以在对应流 ID 的推流中途修改。开发者可根据流附加信息来实现流 ID 相关的可变内容的同步。

调用时机：在创建引擎 [createEngine] 之后，在推流 [startPublishingStream] 前后调用都可生效。
相关回调：结果会通过 [ZegoPublisherSetStreamExtraInfoCallback] 回调通知。

支持版本：1.1.0 及以上。
使用限制：无。

返回值

设置流附加信息执行结果通知。

startPreview

startPreview(view: ZegoView, channel: ZegoPublishChannel): void

启动/更新本地预览，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
view	ZegoView	启动预览时用于显示画面的视图。
channel	ZegoPublishChannel	推流通道

详情

用户通过调用此函数可以看到自己本地的画面。

业务场景：可以用于实时连麦、直播等场景下的本地预览。
调用时机：调用 [createEngine] 后。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：1. 预览功能不需要先登录房间或推流，但是在退出房间之后 SDK 内部默认会主动停止预览。2. 可以通过再次调用此函数来切换视图或修改预览模式(ZegoViewMode)。用户只能在一个视图上预览，如果再次调用 [startPreview] 传入新的视图，则预览画面只会在新视图展现。3. 可以通过调用 [setVideoMirrorMode] 函数来设置预览画面的镜像模式，移动端默认开启预览画面的镜像效果。4. 调用此函数后，SDK 会启动音视频引擎，并尝试采集音频与视频。

stopPreview

stopPreview(channel: ZegoPublishChannel): void

停止本地预览，支持设置其他通道的推流

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道

详情

当本地不需要预览时可调用此函数停止预览。

支持版本：1.1.0 及以上。
注意事项：停止预览不会影响推流、拉流功能。

setVideoConfig

  setVideoConfig(config: ([ZegoVideoConfigPreset](/javascript_electron/enum/ZegoVideoConfigPreset)|ZegoVideoConfig), channel: ZegoPublishChannel): void

设置视频配置，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	([ZegoVideoConfigPreset](/javascript_electron/enum/ZegoVideoConfigPreset)\|ZegoVideoConfig)	视频配置，SDK 提供常用的分辨率、帧率和码率的组合值，也可自定义分辨率、帧率和码率。
channel	ZegoPublishChannel	推流通道。

详情

设置视频帧率、码率、视频采集分辨率、视频编码输出分辨率等视频配置。

业务场景：不同业务场景下的建议配置 https://doc-zh.zego.im/article/10365
默认值：默认视频采集分辨率为 360p，视频编码输出分辨率为 360p，码率为 600 kbps，帧率为 15 fps。
调用时机：调用 [createEngine] 之后。

支持版本：1.1.0 及以上。
使用限制：需要在 [startPreview] 前调用。在 [startPreview] 之后调用无法修改采集分辨率，仅支持修改编码分辨率、码率和帧率。
注意事项：移动端分辨率的宽高与 PC 端分辨率的宽高是相反的，例：移动端的 360p 的分辨率为 360x640，而 PC 端 360p 的分辨率为 640x360。

getVideoConfig

getVideoConfig(channel: ZegoPublishChannel): ZegoVideoConfig

获取当前视频配置，支持设置其他通道的推流

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道

详情

可通过此函数获取指定推流通道当前的视频帧率、码率，视频采集分辨率，视频编码输出分辨率。

返回值

视频配置对象

setVideoMirrorMode

setVideoMirrorMode(mirrorMode: ZegoVideoMirrorMode, channel: ZegoPublishChannel): void

设置镜像模式，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mirrorMode	ZegoVideoMirrorMode	预览或推流的镜像模式。
channel	ZegoPublishChannel	推流通道。

详情

设置本地预览视频以及推送的视频是否开启镜像模式，具体镜像模式可以参考 https://doc-zh.zego.im/article/10365

调用时机：调用 [createEngine] 之后。

支持版本：1.1.0 及以上。
使用限制：只有 SDK 负责渲染时该设置才有效。

setAudioConfig

  setAudioConfig(config: ([ZegoAudioConfigPreset](/javascript_electron/enum/ZegoAudioConfigPreset)|ZegoAudioConfig)): void

设置音频质量配置。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	([ZegoAudioConfigPreset](/javascript_electron/enum/ZegoAudioConfigPreset)\|ZegoAudioConfig)	音频质量配置。

详情

可通过此函数设置音频编码类型、码率、音频声道的组合值。若预设的值无法满足开发者的场景，开发者可自行根据业务要求设置符合的参数。

默认值：默认的音频配置参考 [ZegoAudioConfig] 的默认值。
调用时机：在创建引擎 [createEngine] 后，且在推流 [startPublishingStream] 前设置。
相关接口：[getAudioConfig]。

支持版本：1.3.4 及以上。
使用限制：无。
注意事项：作用于主推流通道 ZegoPublishChannel.Main。

setAudioConfigWithChannel

  setAudioConfigWithChannel(config: ([ZegoAudioConfigPreset](/javascript_electron/enum/ZegoAudioConfigPreset)|ZegoAudioConfig), channel: ZegoPublishChannel): void

设置指定推流通道的音频质量配置。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	([ZegoAudioConfigPreset](/javascript_electron/enum/ZegoAudioConfigPreset)\|ZegoAudioConfig)	音频质量配置。
channel	ZegoPublishChannel	推流通道。

详情

可通过此函数设置音频编码类型、码率、音频声道的组合值。若预设的值无法满足开发者的场景，开发者可自行根据业务要求设置符合的参数。

默认值：默认的音频配置参考 [ZegoAudioConfig] 的默认值。
调用时机：在创建引擎 [createEngine] 后，且在推流 [startPublishingStream] 前设置。
相关接口：[getAudioConfig]。

支持版本：1.3.4 及以上。
使用限制：无。

getAudioConfig

getAudioConfig(): ZegoAudioConfig

获取当前音频质量配置。

Declared in ZegoExpressEngine.js

可通过此函数获取当前的音频编码类型、码率、音频声道的组合值。

调用时机：在创建引擎 [createEngine] 后。
相关接口：[setAudioConfig]。

支持版本：1.8.0 及以上。
使用限制：无。
注意事项：作用于主推流通道 ZegoPublishChannel.Main。

音频质量配置。

setPublishStreamEncryptionKey

setPublishStreamEncryptionKey(key: string, channel: ZegoPublishChannel): void

设置指定推流通道的推流加密密钥。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
key	string	加密密钥，注意密钥长度仅支持 16/24/32 字节。
channel	ZegoPublishChannel	推流通道。

详情

支持在推流中途调用此函数更新加密密钥。

调用时机：在创建引擎 [createEngine] 后，在推流 [startPublishingStream] 前后调用都可生效。
相关接口：调用 [stopPublishingStream] 或 [logoutRoom] 都将会清空加密密钥。

支持版本：1.19.0 及以上。
使用限制：该函数仅当向 Zego RTC 服务器推流时调用有效。
注意事项：需要先更新拉流端解密密钥后才能更新推流端加密密钥。

takePublishStreamSnapshot

takePublishStreamSnapshot(channel: ZegoPublishChannel): Promise<Object>

对指定推流通道的推流画面截图。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

对推流画面进行截图。

调用时机：在调用 [startPublishingStream] 或 [startPreview] 后调用此函数。
相关回调：截图结果会通过 [ZegoPublisherTakeSnapshotCallback] 回调。
相关接口：[takePlayStreamSnapshot]。

支持版本：1.17.0 及以上。
使用限制：无。
注意事项：截图的分辨率为 [setVideoConfig] 里设置的编码分辨率，若需改为采集分辨率，请调用 [setCapturePipelineScaleMode] 将采集缩放时机模式改为 [Post]。

返回值

推流画面截图结果回调。

mutePublishStreamAudio

mutePublishStreamAudio(mute: boolean, channel: ZegoPublishChannel): void

停止或恢复发送指定推流通道的音频流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	是否停止发送音频流；true 表示不发送音频流；false 表示发送音频流；默认为 false。
channel	ZegoPublishChannel	推流通道。

详情

推流时可调用此函数实现不推音频数据流，本地仍会采集和处理音频，但向网络发送静音帧数据包。

业务场景：用户不希望推出任何音频数据时，可以调用该接口。该接口不影响 [onBeforeAudioPrepAudioData]。
调用时机：在创建引擎 [createEngine] 后调用生效。
相关回调：如果在本地设置了停止发送音频流，拉本地流的远端用户可以通过监听 [onRemoteMicStateUpdate] 回调收到 Mute 的状态变更通知。
相关接口：[mutePublishStreamVideo]。

支持版本：1.1.0 及以上。
使用限制：无。

mutePublishStreamVideo

mutePublishStreamVideo(mute: boolean, channel: ZegoPublishChannel): void

停止或恢复发送指定推流通道的视频流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	是否停止发送视频流；true 表示只发送音频流不发送视频流；false 表示同时发送音频和视频流；默认为 false。
channel	ZegoPublishChannel	推流通道。

详情

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

调用时机：在创建引擎 [createEngine] 后调用生效。
相关回调：如果在本地设置了停止发送视频流，拉本地流的远端用户可以通过监听 [onRemoteCameraStateUpdate] 回调收到 Mute 的状态变更通知。
相关接口：[mutePublishStreamAudio]。

支持版本：1.1.0 及以上。
使用限制：无。

setStreamAlignmentProperty

setStreamAlignmentProperty(alignment: number, channel: ZegoPublishChannel): void

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

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
alignment	number	是否开启精准对齐功能，1 表示开启，0 表示关闭。
channel	ZegoPublishChannel	推流通道。

详情

调用本接口开启或关闭流对齐功能。

业务场景：常用于 KTV 等需要流对齐的场景。
默认值：若未调该接口，默认为不对齐
调用时机：在创建引擎 [createEngine] 后。
相关接口：[startMixerTask]、[startAutoMixerTask]。

支持版本：2.11.0 及以上。
注意事项：如果在拉多路流或者混流时需要通过网络时间对各流进行对齐，推流需调用 [startPublishingStream] 且 [ZegoPublisherConfig] 中的 [forceSynchronousNetworkTime] 为1,开启网络时间同步。

enableTrafficControl

enableTrafficControl(enable: boolean, property: number, channel: ZegoPublishChannel): void

开始或停止指定推流通道的流量控制。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否使用流量控制；true 表示开启流控；false 表示关闭流控；默认为 true。
property	number	流量控制的属性，位掩码格式。具体可设置为 [ZegoTrafficControlProperty] 的属性的一个或多个枚举组合。默认为 AdaptiveFPS。
channel	ZegoPublishChannel	推流通道。

详情

开启流量控制可以使 SDK 根据当前上行网络环境状况，或者在1 对1 互动场景下根据对方下行网络环境状况，调节音视频推流码率大小，以保障效果流畅。同时，可进一步指定流量控制的属性来调整相应的控制策略。

默认值：默认开启。
调用时机：在创建引擎 [createEngine] 后，在推流 [startPublishingStream] 之前调用生效。

支持版本：1.5.0 及以上。
使用限制：仅支持 RTC 推流。

setMinVideoBitrateForTrafficControl

setMinVideoBitrateForTrafficControl(bitrate: number, mode: ZegoTrafficControlMinVideoBitrateMode): void

设置流量控制的最低视频码率阈值。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
bitrate	number	流量控制的最低视频码率阈值，单位为 kbps。
mode	ZegoTrafficControlMinVideoBitrateMode	低于最低码率时的视频发送模式。

详情

设置流量控制时视频码率达到最低阈值时的控制策略。当码率低于最低阈值时，可以选择不发送视频数据或者以极低帧率发送。

默认值：无视频码率最低阈值的控制效果。
调用时机：在创建引擎 [createEngine] 后，在推流 [startPublishingStream] 前调用生效。
相关接口：[enableTrafficControl]。

支持版本：1.1.0 及以上。
使用限制：必须开启流量控制 [enableTrafficControl]。
注意事项：作用于主推流通道 ZegoPublishChannel.Main。

setMinVideoFpsForTrafficControl

setMinVideoFpsForTrafficControl(fps: number, channel: ZegoPublishChannel): void

设置流量控制的最低视频帧率阈值。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
fps	number	流量控制的最低视频帧率阈值，单位为 fps。
channel	ZegoPublishChannel	推流通道。

详情

开启流量控制 [enableTrafficControl]，并且它的参数 [property] 包含属性 AdaptiveFPS 后，视频的最低帧率不会低于 [setMinVideoFpsForTrafficControl] 接口设置的值， 0 值表示不限制。

默认值：无视频帧率最低阈值的控制效果。
调用时机：在创建引擎 [createEngine] 后调用生效。
相关接口：[enableTrafficControl]。

支持版本：2.17.0 及以上。
使用限制：必须开启流量控制 [enableTrafficControl]，并且它的参数 [property] 必须包含属性 AdaptiveFPS，具体可以参考 [ZegoTrafficControlProperty]。
注意事项：如果需要取消该设置值的限制可以设置为 0。

setMinVideoResolutionForTrafficControl

setMinVideoResolutionForTrafficControl(width: number, height: number, channel: ZegoPublishChannel): void

设置流量控制的最低视频分辨率阈值。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
width	number	流量控制的最低视频分辨率的宽。
height	number	流量控制的最低视频分辨率的高。
channel	ZegoPublishChannel	推流通道。

详情

开启流量控制 [enableTrafficControl]，并且它的参数 [property] 包含属性 AdaptiveResolution 时，视频的最低分辨率不会低于 [setMinVideoResolutionForTrafficControl] 接口设置的值。 0 值表示不限制。

默认值：无视频分辨率最低阈值的控制效果。
调用时机：在创建引擎 [createEngine] 后调用生效。
相关接口：[enableTrafficControl]。

支持版本：2.17.0 及以上。
使用限制：必须开启流量控制 [enableTrafficControl]，并且它的参数 [property] 必须包含属性 AdaptiveResolution，具体可以参考 [ZegoTrafficControlProperty]。
注意事项：如果需要取消该设置值的限制可以设置分辨率宽高值为 0。

setTrafficControlFocusOn

setTrafficControlFocusOn(mode: ZegoTrafficControlFocusOnMode, channel: ZegoPublishChannel): void

设置指定推流通道的触发流量控制的关注因素。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoTrafficControlFocusOnMode	选择 LOCAL_ONLY 时，只关注本地网络状况。选择 REMOTE 时，不仅关注本地网络，同时也兼顾远端网络。
channel	ZegoPublishChannel	推流通道。

详情

通过该接口控制是否因为远端网络状况差而启动流量控制。

默认值：默认关闭。
调用时机：在创建引擎 [createEngine] 后，在推流 [startPublishingStream] 前调用生效。
相关接口：[enableTrafficControl]。

支持版本：2.4.0 及以上。
使用限制：必须开启流量控制 [enableTrafficControl]。

setCaptureVolume

setCaptureVolume(volume: number): void

设置推流端采集音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
volume	number	音量增益百分比，范围为 0 ~ 200，默认值为 100，表示为设备原始采集音量的 100%.

详情

此函数用于在设备采集音量的基础上做增益处理，本端用户可控制往远端发送音频流的声音大小。

默认值：默认为 100。
调用时机：在创建引擎 [createEngine] 后。
相关接口：设置拉流音量 [setPlayVolume]。

支持版本：1.13.0 及以上。
使用限制：在推流途中可以动态设置采集音量。

setAudioCaptureStereoMode

setAudioCaptureStereoMode(mode: ZegoAudioCaptureStereoMode): void

设置音频采集双声道模式。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoAudioCaptureStereoMode	双声道采集模式。

详情

此函数用于设置音频的采集声道模式，当开发者开启双声道采集后，使用专门的双声道采集设备，可以采集到双声道的音频数据并进行推流。

业务场景：在一些比较专业的场景里，用户对声音的效果尤为敏感，比如语音电台、乐器演奏，此时就需要对双声道和高音质的支持。
默认值：默认 None，即单声道采集。
调用时机：需要在 [createEngine] 之后，在 [startPublishingStream]、 [startPlayingStream]、 [startPreview]、 [createMediaPlayer]、 [createAudioEffectPlayer] 和 [createRealTimeSequentialDataManager] 之前调用才有效。
相关接口：当推流时需要同时通过 [setAudioConfig] 函数开启双声道音频编码功能。

支持版本：1.15.0 及以上 (iOS/Android/Windows/OHOS)；自 2.16.0 开始支持 macOS。
使用限制：如果需要开启双声道采集，还需要满足如下条件：对于 iOS/Android 来说，需要外接支持双声道采集的音频设备并且处于媒体音量下。对于 macOS 来说需要处于媒体音量下。对于 Windows 来说需要外接支持双声道采集的音频设备。

addPublishCdnUrl

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

增加转推至 CDN 的 URL。

Declared in ZegoExpressEngine.js

参数

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

详情

将 ZEGO RTC 服务器的音视频流转推至自定义的 CDN 内容分发网络，延迟高但是支持高并发拉流。

业务场景：1. 常用于对延迟没有特别高要求的大规模直播场景。2. 由于 ZEGO RTC 服务器本身可配置支持 CDN 内容分发网络，此函数主要为自身拥有 CDN 内容分发服务的开发者使用。3. 此函数支持动态转推至多个 CDN 内容分发网络，因此开发者可以使用此函数来作为 CDN 内容分发服务的一个容灾方案。
调用时机：在调用 [createEngine] 函数创建引擎后。
相关接口：删除转推至 CDN 的 URL [removePublishCdnUrl]，结果回调函数 [onPublisherRelayCDNStateUpdate]。

支持版本：1.1.0 及以上。
使用限制：当调用 [enablePublishDirectToCDN] 函数设置为 true 将流直推到 CDN 时，再调用本函数将无效。
注意事项：删除转推至 CDN 的 URL 需要调用 [removePublishCdnUrl]，调用 [stopPublishingStream] 不会删除转推至 CDN 的 URL。

返回值

更新 CDN 转推结果通知。

removePublishCdnUrl

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

删除转推至 CDN 的 URL。

Declared in ZegoExpressEngine.js

参数

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

详情

当已经通过 [addPublishCdnUrl] 添加了某个 CDN 转推地址，需要将流停止转推时调用此函数。

调用时机：在调用 [createEngine] 函数创建引擎后，不需要继续转推至 CDN 时。
相关接口：增加转推至 CDN 的 URL [addPublishCdnUrl]，结果回调函数 [onPublisherRelayCDNStateUpdate]。

支持版本：1.1.0 及以上。
使用限制：当调用 [enablePublishDirectToCDN] 函数设置为 true 将流直推到 CDN 时，再调用本函数将无效。
注意事项：此函数并不会停止推往 ZEGO RTC 服务器的音视频流。

返回值

更新 CDN 转推结果通知。

enablePublishDirectToCDN

enablePublishDirectToCDN(enable: boolean, config: ?ZegoCDNConfig, channel: ZegoPublishChannel): void

是否直接推流到 CDN（不经过 ZEGO RTC 服务器）, 支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启直推 CDN；true 表示开启直推 CDN；false 表示不开启直推 CDN；默认为 false。
config	?ZegoCDNConfig	CDN 配置，若为 null 则使用 Zego 的后台配置。
channel	ZegoPublishChannel	推流通道。

详情

是否不经过 ZEGO RTC 服务器直接推流到 CDN。

业务场景：常用于对延迟没有特别高要求的大规模直播场景。
默认值：默认为 false，不开启直推。
调用时机：在创建引擎 [createEngine]后，开始推流[startPublishingStream] 前。
相关接口：动态转推至 CDN 函数 [addPublishCdnUrl]、[removePublishCdnUrl]。

支持版本：1.5.0 及以上。
注意事项：直推 CDN 功能在网络传输过程中不经过 ZEGO 实时音视频云，无法使用 ZEGO 的超低延迟音视频服务。

setPublishWatermark

setPublishWatermark(watermark: ?ZegoWatermark, isPreviewVisible: boolean, channel: ZegoPublishChannel): void

设置推流水印，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
watermark	?ZegoWatermark	水印布局左上角为坐标系原点，区域不能超过编码分辨率设置的大小。若为空表示取消水印。
isPreviewVisible	boolean	是否本地预览能看见水印。
channel	ZegoPublishChannel	推流通道。

详情

给推流画面设置水印。

业务场景：常用于标识推流来源的场景。
调用时机：在调用 [createEngine] 函数创建引擎后。

支持版本：1.1.0 及以上。
注意事项：水印的布局不能超出推流的视频编码分辨率。可在推流前或推流中途任意时刻设置。

setSEIConfig

setSEIConfig(config: ZegoSEIConfig): void

设置媒体增强补充信息类型。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	ZegoSEIConfig	SEI 类型配置。默认使用 ZEGO 定义的 SEI。

详情

SDK 默认使用 ZEGO 自行定义的 SEI 类型包装数据，且此类型是 SEI 标准未规定的类型。当开发者需要使用第三方解码器解码，会导致解不出正确的 SEI，需要调用 [setSEIConfig] 函数更换 SDK 发送 SEI 的类型为 UserUnregister 类型。

业务场景：当开发者使用第三方解码器解码 SEI 时需要执行该函数。
调用时机：在创建引擎 [createEngine]后，开始推流[startPublishingStream] 前。

支持版本：1.18.0 及以上。
使用限制：无。

sendSEI

sendSEI(data: ArrayBuffer, channel: ZegoPublishChannel): void

指定推流通道号，发送媒体增强补充信息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
data	ArrayBuffer	SEI 内容。
channel	ZegoPublishChannel	推流通道。

详情

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

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

支持版本：1.1.0 及以上。
使用限制：1 秒钟不要超过30次，SEI 数据长度限制为 4096 字节。
注意事项：1. 由于网络问题有可能丢帧，因此 SEI 信息也有可能丢，为解决这种情况，应该在限制频率内多发几次。2. 即使调用 [enableCamera] 接口关闭摄像头或通过 [mutePublishStreamVideo] 停止发送视频数据，SEI 仍可发送成功；只要拉流端不调用 [mutePlayStreamVideo] 的接口停止拉音频数据，仍可正常接收 SEI。3. 若 SDK 不支持视频模块，但支持 SEI 功能模块，SEI 信息仍可正常发送。

enableHardwareEncoder

enableHardwareEncoder(enable: boolean): void

开/关硬件编码。

Declared in ZegoExpressEngine.js

参数

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

详情

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

调用时机：在推流前设置才能生效，如果在推流后设置，停推后重新推流可以生效。

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

setCapturePipelineScaleMode

setCapturePipelineScaleMode(mode: ZegoCapturePipelineScaleMode): void

设置采集缩放时机，视频数据是采集的时候立即缩放还是编码时才进行缩放。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoCapturePipelineScaleMode	采集缩放时机。

调用时机：此函数需要在调用 [createEngine] 之后，调用预览 [startPreview] 或推流 [startPublishingStream] 前设置有效。

支持版本：1.1.0 及以上。
注意事项：主要影响是当采集分辨率与编码分辨率不同的时候，是否影响本地预览情况。

setDummyCaptureImagePath

setDummyCaptureImagePath(filePath: string, channel: ZegoPublishChannel): void

设置关闭摄像头时所推静态图片的路径

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
filePath	string	图片路径
channel	ZegoPublishChannel	推流通道。

详情

设置关闭摄像头时所推静态图片的路径。开始正常推流后，调用 enableCamera(false) 时会开始推静态图片，调用 enableCamera(true) 时会结束推静态图片。

业务场景：开发者希望关闭摄像头时，显示静态图片。例如，主播退后台的时候，会主动关闭摄像头，此时观众侧需要展示主播暂时离开的图片。
调用时机：初始化引擎之后，关闭摄像头前调用本 API 进行参数配置，在关闭摄像头后，即可推静态图片。
平台差异： 1. Windows：直接填写图片位置，如"D://dir//image.jpg"。 2. iOS/macOS：如果是完整路径则添加 "file:" 前缀，如：@"file:/var/image.png"。资产则添加 "asset:" 前缀，如：@"asset
"。 3. Android：如果是完整路径则添加 "file:" 前缀，如："file:/sdcard/image.png"。“assets” 目录下的图片则添加 "asset:" 前缀，如："asset
.png"。 4. Flutter：如果是绝对路径则添加 "file:" 前缀，如："file:/sdcard/image.png"。“assets” 资源中的图片则添加 "flutter-asset://" 前缀，如："flutter-asset://assets/watermark.png"。 5. UniApp：仅支持绝对路径，需要添加 "file:" 前缀，如："file:/sdcard/image.png"。

支持版本：2.9.0 及以上。
使用限制： 1. 图片支持类型为 JPEG/JPG、PNG、BMP、HEIF。 2. 该接口只对 SDK 视频采集有效，对自定义视频采集不生效。 3. 不支持图片路径是网络链接。
注意事项： 1. 本地预览无法看到该静态图片。 2. 外部滤镜、水印、镜像、截图都不会生效。 3. 如果图片宽高比与设定的编码宽高比不一致，会按照编码宽高比进行裁剪。 4. 推音频流一定要再次调用该接口并把图片路径设置为空，避免产生视频计费。

enableH265EncodeFallback

enableH265EncodeFallback(enable: boolean): void

是否开启 H.265 编码自动降级到 H.264 编码。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启 H.265 编码自动降级到 H.264 编码；true 表示开启；false 表示关闭；默认为 true

详情

使用 H.265 编码方式推流时，是否开启在异常情况下 H.265 编码自动降级到 H.264 编码的策略；开启自动降级后，当不支持 H.265 编码或编码 H.265 失败时，SDK 内部会尝试降级使用 H.264 编码进行推流；关闭自动降级后，当不支持 H.265 编码或编码 H.265 失败时，直接推流失败。

业务场景：在多人连麦直播、秀场直播场景下，使用 H265 编码推流，达到不降低画质的情况下节省 CDN 流量的目的。
默认值：没有调用该接口时，默认为是，即开启 H.265 编码自动降级到 H.264 编码。
调用时机：创建引擎后，调用 [startPublishingStream] 函数推流前。
相关回调：开启 H.265 编码自动降级到 H.264 编码策略后，编码方式变化时会触发 [onPublisherVideoEncoderChanged] 回调。

支持版本：2.12.0 及以上。
注意事项：当推流过程中发生从 H.265 降级到 H.264 编码时，如果正在进行本地视频录制或云录制，会导致产生多个录制文件，需要对此做处理。

isVideoEncoderSupported

isVideoEncoderSupported(codecID: ZegoVideoCodecID, codecBackend: ZegoVideoCodecBackend): number

是否支持指定的视频编码类型和实现方式。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
codecID	ZegoVideoCodecID	视频编码类型。是否必填：是。
codecBackend	ZegoVideoCodecBackend	编码器的后端实现。是否必填：是。

详情

是否支持指定视频编码，主要取决于以下几个方面：硬件型号是否支持硬编、硬件型号性能是否支持软编、SDK 是否带该编码模块。

调用时机：创建引擎后。

支持版本：3.0.0 及以上。
注意事项：建议用户在进行 H.265 编码推流前，先调用本接口获取 H.265 编码支持能力，如果不支持，可以采用其他编码进行推流，比如 H.264。在移动端，SDK 仅支持 H.265 硬件编码，且受机型和硬件能力影响。

返回值

是否支持指定视频编码格式；0 表示不支持，不可以使用该编码格式进行推流；1 表示支持，可以使用该编码格式进行推流；2 表示未确认，建议稍后再调用本接口。

setLowlightEnhancement

setLowlightEnhancement(mode: ZegoLowlightEnhancementMode, channel: ZegoPublishChannel): void

设置低照度增强。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoLowlightEnhancementMode	低照度增强模式。
channel	ZegoPublishChannel	推流通道。

详情

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

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

支持版本：2.21.0 及以上。

setVideoSource

setVideoSource(source: ZegoVideoSourceType, instanceID: number, channel: ZegoPublishChannel): number

设置视频采集源实例作为指定推流通道的视频采集源。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
source	ZegoVideoSourceType	视频采集源类型。
instanceID	number	视频采集源实例 ID。
channel	ZegoPublishChannel	推流通道。

详情

设置视频采集源，用于在不同的视频采集源之间进行切换。

业务场景：通常用于需要在不同的视频采集源之间切换的场景下。
调用时机：在创建引擎 [createEngine] 后调用生效。

支持版本：3.1.0 及以上。
使用限制：无。
注意事项：1. 主路推流通道 ZegoPublishChannel.Main 不支持设置 ZegoVideoSourceType.Player 和 ZegoVideoSourceType.MainPublishChannel 视频输入源类型。

辅路推流通道 ZegoPublishChannel.Aux 使用 ZegoVideoSourceType.Player 和 ZegoVideoSourceType.MainPublishChannel 视频输入源类型时，需要确保主推流通道 ZegoPublishChannel.Main 设备正常工作。
抢占型视频源不允许在多通道同时使用，例如 ZegoVideoSourceType.Camera、ZegoVideoSourceType.ScreenCapture。
只有主路使用内部采集，辅路才可复制，且最多支持一路复制。
设置 ZegoVideoSourceType.Player 视频输入源类型时，请确保 ZegoMediaPlayer 实例创建成功。

返回值

结果。

setAudioSource

setAudioSource(source: ZegoAudioSourceType, channel: ZegoPublishChannel): number

为指定推流通道设置音频采集源

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
source	ZegoAudioSourceType	音频采集源类型。
channel	ZegoPublishChannel	推流通道。

详情

设置音频采集源，用于在不同的音频采集源之间进行切换。

业务场景：通常用于需要在不同的音频采集源之间切换的教育场景下。
调用时机：在创建引擎 [createEngine] 后调用生效。

支持版本：3.1.0 及以上。
注意事项：1. 主路推流通道 ZegoPublishChannel.Main 不支持设置 ZegoAudioSourceType.MediaPlayer 和 ZegoAudioSourceType.MainPublishChannel 音频输入源类型。

辅路推流通道 ZegoPublishChannel.Aux 使用 ZegoAudioSourceType.MediaPlayer 和 ZegoAudioSourceType.MainPublishChannel 音频输入源类型时，需要确保主推流通道 ZegoPublishChannel.Main 设备正常工作。 3. 抢占型音源不允许在多通道同时使用，例如 ZegoAudioSourceType.Microphone。
设置 ZegoAudioSourceType.MediaPlayer 音频输入源类型时，请确保 ZegoMediaPlayer 实例创建成功。

返回值

错误码。

setAudioSourceWithConfig

setAudioSourceWithConfig(source: ZegoAudioSourceType, config: ZegoAudioSourceMixConfig): number

设置音频采集源及混音配置

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
source	ZegoAudioSourceType	音频采集源类型。
config	ZegoAudioSourceMixConfig	音频采集源混音配置。

详情

设置音频采集源，用于在不同的音频采集源之间进行切换。

业务场景：通常用于需要在不同的音频采集源之间切换的场景下。
调用时机：在创建引擎 [createEngine] 后调用生效。

支持版本：3.1.0 及以上。
使用限制：无。
注意事项：作用于主路推流通道 ZegoPublishChannel.Main。主路推流通道 ZegoPublishChannel.Main 不支持设置 ZegoAudioSourceType.MediaPlayer 和 ZegoAudioSourceType.MainPublishChannel 音频输入源类型。

返回值

错误码。

enableVideoObjectSegmentation

  enableVideoObjectSegmentation(enable: boolean, config: ZegoObjectSegmentationConfig, channel: ZegoPublishChannel): void

开启主体分割。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启主体分割，默认关闭。
config	ZegoObjectSegmentationConfig	主体分割配置。
channel	ZegoPublishChannel	推流通道。

详情

主体分割与传输即在推流端将矩形视频内的主体（多数情况下是人）通过 AI 算法分离出来，并在 RTC 网络中传输、在拉流端渲染的技术。

业务场景：需要将视频中的主体与背景分离的场景，例如混合现实、多人同场互动场景等。
调用时机：在创建引擎 [createEngine] 后调用生效。
相关回调：当开启或者关闭主体分割后，通过 [onVideoObjectSegmentationStateChanged] 可以收到主体分割状态的通知。
相关接口：使用 [enableAlphaChannelVideoEncoder] 支持对分割后的主体的透明背景编码，再进行推流，则可以在拉流端渲染主体带透明背景效果。

支持版本：3.6.0 及以上。
使用限制：开启主体分割为耗时操作，轻勿频繁开启关闭。
注意事项：该功能需要特殊编包，请联系 ZEGO 技术支持。

enableAlphaChannelVideoEncoder

enableAlphaChannelVideoEncoder(enable: boolean, alphaLayout: ZegoAlphaLayoutType, channel: ZegoPublishChannel): void

开启视频编码器透明通道支持。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启视频编码器透明通道支持，默认关闭。
alphaLayout	ZegoAlphaLayoutType	指定 Alpha 通道数据的布局位置。
channel	ZegoPublishChannel	推流通道。

详情

在推流端开启视频编码器透明通道支持，将分割后的视频主体进行编码，用于推流。

业务场景：需要将视频中的主体与背景分离的场景，例如混合现实、多人同场互动场景等。
调用时机：创建引擎后。

支持版本：3.4.0 及以上。

onPublisherStateUpdate

onPublisherStateUpdate(streamID: string, state: ZegoPublisherState, errorCode: number, extendedData: string): void

推流状态回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	推流的流 ID。
state	ZegoPublisherState	推流状态。
errorCode	number	推流状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	string	状态更新附带的扩展信息，包含CDN拉流地址。

详情

在调用推流接口 [startPublishingStream] 成功后，可以通过该回调函数获取推流状态变更的通知。开发者可根据 state 参数是否在 [正在请求推流状态] 来大体判断用户的推流网络情况。

相关回调：在调用拉流接口 [startPlayingStream] 成功后，可以通过回调函数 [onPlayerStateUpdate] 获取拉流状态变更的通知。开发者可根据 state 参数是否在 [正在请求拉流状态] 来大体判断用户的拉流网络情况。

支持版本：1.1.0 及以上。
注意事项：参数 [extendedData] 为状态更新附带的扩展信息。若使用 ZEGO 的 CDN 内容分发网络，在推流成功后，该参数的内容的键为 [flv_url_list]、[rtmp_url_list]、[hls_url_list]，分别对应 flv、rtmp、hls 协议的拉流 URL。

onPublisherQualityUpdate

onPublisherQualityUpdate(streamID: string, quality: ZegoPublishStreamQuality): void

推流质量回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	推流的流 ID。
quality	ZegoPublishStreamQuality	推流质量，包含了音视频帧率、码率、RTT 等值。

详情

在调用推流接口 [startPublishingStream] 成功后默认3秒(该时间如果需要变更，请联系 ZEGO 技术支持配置)会收到此回调，通过该回调可以获取推送的音视频流的采集帧率，码率，RTT，丢包率等质量数据。开发者可根据此函数的质量参数实时监控推送的音视频流的健康情况，以便在设备 UI 界面上实时展示上行网络状况。

相关回调：当调用拉流接口 [startPlayingStream] 成功后每3秒会收到回调 [onPlayerQualityUpdate]，开发者可根据拉取的音视频流的帧率，码率，RTT，丢包率等质量数据，实时监控拉取流的健康情况。

支持版本：1.1.0 及以上。
注意事项：若开发者不清楚该回调函数的各个参数应该如何使用，可以只关注其中的 [quality] 参数的 [level] 字段，这是 SDK 内部根据质量参数计算的一个描述上行网络的综合值。

onPublisherCapturedAudioFirstFrame

onPublisherCapturedAudioFirstFrame(): void

音频采集首帧回调接口。

Declared in ZegoExpressEngine.js

SDK 启动麦克风采集到第一帧音频数据时会收到此回调。若未收到该回调,说明音频采集设备被占用或异常。

通知时机：SDK内部的音视频模块的引擎启动时，SDK 会去采集本机设备的音频数据，此时会收到该回调。
相关回调：通过回调函数[onPublisherCapturedVideoFirstFrame] 判断 SDK 是否真正采集到了视频数据，通过回调[onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完了采集到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPublisherCapturedVideoFirstFrame

onPublisherCapturedVideoFirstFrame(channel: ZegoPublishChannel): void

视频采集首帧回调接口。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

SDK 启动摄像头采集到第一帧视频数据时会收到此回调。若未收到该回调，说明视频采集设备被占用或异常。

通知时机：SDK 内部的音视频模块的引擎启动时，SDK 会去采集本机设备的视频数据，此时会收到该回调。
相关回调：通过回调函数 [onPublisherCapturedAudioFirstFrame] 判断 SDK 是否真的采集到音频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPublisherSendAudioFirstFrame

onPublisherSendAudioFirstFrame(channel: ZegoPublishChannel): void

推流端音频发送首帧回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路音频流，可以不关注该参数。

详情

调用推流函数 [startPublishingStream] 成功后，SDK 发出第一帧音频数据时会收到此回调。开发者可根据该回调判断 SDK 是否真的发出音频数据，若未收到该回调，说明音频发送异常。

通知时机：在未调用推流函数 [startPublishingStream] 的情况下，首次推流 SDK 会收到该回调。
相关回调：调用推流函数 [startPublishingStream] 成功后, 通过回调函数 [onPublisherCapturedVideoFirstFrame] 判断 SDK 是否真的采集到视频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：3.5.0 及以上。

onPublisherSendVideoFirstFrame

onPublisherSendVideoFirstFrame(channel: ZegoPublishChannel): void

推流端视频发送首帧回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路视频流，可以不关注该参数。

详情

调用推流函数 [startPublishingStream] 成功后，SDK 发出第一帧视频数据时会收到此回调。开发者可根据该回调判断 SDK 是否真的发出视频数据，若未收到该回调，说明视频发送异常。

通知时机：在未调用推流函数 [startPublishingStream] 的情况下，首次推流 SDK 会收到该回调。
相关回调：调用推流函数 [startPublishingStream] 成功后, 通过回调函数 [onPublisherCapturedAudioFirstFrame] 判断 SDK 是否真的采集到音频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：3.5.0 及以上。

onPublisherVideoSizeChanged

onPublisherVideoSizeChanged(width: number, height: number, channel: ZegoPublishChannel): void

采集视频大小变更回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
width	number	视频采集分辨率宽。
height	number	视频采集分辨率高。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

当在未推流 [startPublishingStream] 或未预览 [startPreview] 的情况下，首次推流或首次预览，即 SDK 内部的音视频模块的引擎启动时，会去采集本机设备的视频数据，此时采集分辨率会改变。

通知时机：推流 [startPublishingStream] 成功后，在推流中途如果有改变视频采集分辨率发生变化将会收到此回调。
业务场景：开发者可以根据此回调来去除本地预览的 UI 的遮盖等类似操作。也可以根据该回调的分辨率来动态调整预览视图的比例等。

支持版本：1.1.0 及以上。
注意事项：外部采集时通知的是编码分辨率大小变化，会受到流控影响。

onPublisherRelayCDNStateUpdate

onPublisherRelayCDNStateUpdate(streamID: string, infoList: ZegoStreamRelayCDNInfo[]): void

添加/删除转推 CDN 地址状态回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	推流的流 ID。
infoList	ZegoStreamRelayCDNInfo[]	当前 CDN 正在转推的信息列表。

详情

开发者可根据该回调判断转推 CDN 的音视频流是否正常，若不正常根据异常原因进一步定位转推 CDN 的音视频流异常的原因，以及做对应的容灾策略。

通知时机：在 ZEGO RTC 服务器将音视频流转推到 CDN 后，如果 CDN 转推状态发生变化，例如出现转推停止或转推重试，将会收到此回调。

支持版本：1.1.0 及以上。
注意事项：若对异常的原因不了解，可联系 ZEGO 技术人员分析具体异常的原因。

onVideoObjectSegmentationStateChanged

  onVideoObjectSegmentationStateChanged(state: ZegoObjectSegmentationState, channel: ZegoPublishChannel, errorCode: number): void

视频主体分割状态变化。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
state	ZegoObjectSegmentationState	主体分割状态。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。
errorCode	number	主体分割状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

推流端视频主体分割状态变化。

通知时机：当 [enableVideoObjectSegmentation] 开启或关闭主体分割后，根据实际情况通知开发者是否开启主体分割。

支持版本：3.4.0 及以上。
注意事项：该回调依赖于开启预览或者推流。

startPlayingStream

startPlayingStream(streamID: string, view: ZegoView, config: ZegoPlayerConfig): void

开始拉流（从 ZEGO RTC 服务器或第三方 CDN），支持多房间模式。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID，长度不超过 256 字节的字符串。注意事项：仅支持数字，英文字符和 '-', '_'。
view	ZegoView	启动预览时用于显示画面的视图。
config	ZegoPlayerConfig	拉流进阶配置, [ZegoPlayerConfig] 中房间 [roomID] 为登录的房间ID。

详情

从 ZEGO RTC 服务器或第三方 CDN 拉取远端用户的音视频流进行互通。

业务场景：在实时连麦或直播场景下，开发者可通过监听 [onRoomStreamUpdate] 事件回调来获取所在房间内新增的流信息，并调用此接口传入 "streamID" 进行拉流操作。
调用时机：调用 [loginRoom] 加入房间后调用该函数。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：1. 开发者可通过再次调用此函数实现切换拉流 canvas 的操作（streamID 必须一样）。同一条流只能在唯一的视图中拉取展示，如果调用 [startPlayingStream] 传入相同的 "streamID" 和不同的视图，画面只会在新视图展现。2. 首次拉流时如果因网络原因拉流失败或拉流中断，SDK 会在 20min 内多次尝试重连并拉流。3. 在网络质量不佳的情况下，用户拉流可能出现中断，SDK 会尝试重连并拉流，可通过监听 [onPlayerStateUpdate] 事件来获知当前拉流状态以及错误信息。详情请参考 https://doc-zh.zego.im/faq/reconnect 4. 如果拉取不存在的 "streamID"，SDK 会持续尝试拉取，在该 streamID 对应的音视频流被成功推送后，该流可以真正被拉取到。

stopPlayingStream

stopPlayingStream(streamID: string): void

停止拉流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。

详情

停止从 ZEGO RTC 服务器拉取远端用户的音视频流。

业务场景：在实时连麦场景下，开发者可通过监听 [onRoomStreamUpdate] 事件回调来获取所在房间内删除的流信息，并调用此接口传入 "streamID" 进行停止拉流操作。
调用时机：调用 [loginRoom] 加入房间后调用该函数。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：1. 停止拉流后对此条流此前设置的属性如 [setPlayVolume]、[mutePlayStreamAudio]、[mutePlayStreamVideo] 等拉流相关的配置都会失效，需要在下次拉流之前重新设置。 2.停止拉流后，iOS平台的视图默认会清除最后一帧，保持为视图的背景色。Android 平台视图默认保持在最后一帧，如果需要清除最后一帧，请联系 ZEGO 技术支持。

setPlayStreamDecryptionKey

setPlayStreamDecryptionKey(streamID: string, key: string): void

设置拉流解密密钥。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
key	string	解密密钥，注意密钥长度仅支持 16/24/32 字节。

详情

拉流时会根据设置的密匙解密音视频数据。

业务场景：常用于对音视频通话安全性要求较高的场景。
调用时机：[createEngine]后，拉流后可随时变更。
相关接口：[setPublishStreamEncryptionKey] 设置推流加密密匙。

支持版本：1.19.0 及以上。
使用限制：该函数仅当从 ZEGO RTC 或 L3 服务器拉流时调用有效。
注意事项：推流端有设置加密才能调用此函数。调用 [stopPlayingStream] 或 [logoutRoom] 都将会清空解密密钥。

takePlayStreamSnapshot

takePlayStreamSnapshot(streamID: string): Promise<Object>

拉流画面截图。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	要截图的流 ID。

详情

对指定拉流ID画面截图。

调用时机：[startPlayingStream]后调用。
相关回调：[onPlayerTakeSnapshotResult] 截图数据回调。

支持版本：1.17.0 及以上。
使用限制：无。

返回值

拉流画面截图结果回调。

setPlayVolume

setPlayVolume(streamID: string, volume: number): void

设置拉流音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
volume	number	音量百分比，取值范围为 0 ~ 200，默认值为 100。

详情

设置拉流的声音大小，本端用户可控制音频流的播放音量。

调用时机：[startPlayingStream] 后调用。
相关接口：[setAllPlayStreamVolume] 设置所有拉流音量。

支持版本：1.16.0 及以上。
使用限制：无。
注意事项：停止拉流后，再次拉流需要重新设置。此函数与 [setAllPlayStreamVolume] 函数相互覆盖，最后一个调用生效。

setAllPlayStreamVolume

setAllPlayStreamVolume(volume: number): void

设置所有拉流音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
volume	number	音量百分比，取值范围为 0 ~ 200，默认值为 100。

详情

此函数用于设置所有拉流的声音大小，本端用户可控制所有音频流的播放音量。

调用时机：[startPlayingStream]后调用。
相关接口：可使用 [setPlayVolume] 设置指定音视频流的音量。

支持版本：2.3.0 及以上。
使用限制：无。
注意事项：与setPlayVolume函数相互覆盖,最后一个调用生效。

setPlayStreamVideoType

setPlayStreamVideoType(streamID: string, streamType: ZegoVideoStreamType): void

设置播放视频流类型。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
streamType	ZegoVideoStreamType	视频流类型。

详情

当推流方通过 [setVideoConfig] 设置了 codecID 为 SVC 时，拉流方可以动态设置选用不同的流类型（小分辨率为标准图层的二分之一）。

业务场景：一般情况下，在网络较弱或者渲染的 UI 窗体较小的情况下，可以选择使用拉取小分辨率的视频来达到节省带宽的目的。
调用时机：[createEngine] 后可调用。

支持版本：2.3.0 及以上。
使用限制：无。

setPlayStreamBufferIntervalRange

setPlayStreamBufferIntervalRange(streamID: string, minBufferInterval: number, maxBufferInterval: number): void

设置拉流播放缓存自适应调整的区间范围。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
minBufferInterval	number	缓存自适应区间下限，单位毫秒。默认值为 0ms。
maxBufferInterval	number	缓存自适应区间上限，单位毫秒。默认值为 4000ms。

详情

设置拉流时 SDK 内部缓存自适应调整的区间范围 0-4000ms。

业务场景：一般在网络环境较差的情况下，调整增大拉流的播放缓存，会显著减少音视频卡顿，但会增大延迟。
调用时机：[createEngine] 后，如果有设置过，则每次重新拉流时都需要重新设置。

支持版本：2.1.0 及以上。
使用限制：无。
注意事项：当开发者设置的缓存区间上限超过 4000ms 时，会取值 4000 ms。当开发者设置的缓存区间上限小于缓存区间下限时，会自动将上限取值为下限。

setPlayStreamFocusOn

setPlayStreamFocusOn(streamID: string): void

设置拉音视频流优先级的权重。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。

详情

设置拉音视频流优先级的权重。

业务场景：当开发者业务上，需要对某音视流优先保证质量时（纯音频流下请勿使用），可使用此接口。例如：上课场景，学生拉多路流,则可设置老师流高优先级。
调用时机：[startPlayingStream]之后。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：默认所有音视频流的权重相同。只能设置一路流是高优先级的，以最后设置的为准。流停止之后自动恢复初始状态，所有流的权重相同。在本地网络不好的时候，保证focus流的同时，可能造成其他的卡顿更多。

mutePlayStreamAudio

mutePlayStreamAudio(streamID: string, mute: boolean): void

拉流是否可接收指定音频数据。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
mute	boolean	拉流时是否可以接收指定远端用户的音频数据，“true” 表示禁止，“false” 表示接收，默认值为 “false”。

详情

在实时音视频互动过程中，本地用户可根据需要，通过此函数控制拉流时是否接收指定远端用户的音频数据,当开发者不接收音频收据时，可降低硬件和网络的开销。

业务场景：当开发者需要快速关闭、恢复远端音频时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：在调用 [createEngine] 后可调用此函数。
相关接口：可调用 [muteAllPlayStreamAudio] 函数控制是否接收所有音频数据。必须当 [muteAllPlayStreamAudio] 和 [mutePlayStreamAudio] 两个函数同时设置为 "false" 时，本地用户拉流时才能接收远端用户的音频数据：1. 当调用 [muteAllPlayStreamAudio(true)] 函数时，全局生效，即本地用户会禁止接收所有远端用户的音频数据，此时无论在 [muteAllPlayStreamAudio] 之前还是之后调用 [mutePlayStreamAudio] 函数都不生效。2. 当调用 [muteAllPlayStreamAudio(false)] 函数时，本地用户可以接收所有远端用户的音频数据，此时可再通过 [mutePlayStreamAudio] 函数控制是否接收单条音频数据。调用 [mutePlayStreamAudio(true, streamID)] 函数则本地用户可以接收该 "streamID" 之外的其他音频数据；调用 [mutePlayStreamAudio(false, streamID)] 函数则本地用户可以接收 "streamID" 的音频数据。

支持版本：1.1.0 及以上。
注意事项： 1. 与 [muteAllPlayAudioStreams] 一起使用时，可以互相覆盖配置。

与 [muteAllPlayStreamAudio] 一起使用时，只有当 [muteAllPlayStreamAudio] 函数设置为 “false”时，此函数才有效。
停止拉流后对此条流此前设置的属性如 [setPlayVolume]、[mutePlayStreamAudio]、[mutePlayStreamVideo] 等拉流相关的配置都会失效，需要在下次拉流之前重新设置。

mutePlayStreamVideo

mutePlayStreamVideo(streamID: string, mute: boolean): void

拉流是否可接收指定视频数据。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
mute	boolean	拉流时是否可以接收指定远端用户的视频数据，“true” 表示禁止，“false” 表示接收，默认值为 “false”。SDK 内部自动拉取的流默认值为 false。

详情

在实时音视频互动过程中，本地用户可根据需要，通过此函数控制拉流时是否接收指定远端用户的视频数据,当开发者不接收视频数据时，可降低硬件和网络的开销。

业务场景：当开发者需要快速关闭、恢复观看远端视频画面时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：在调用 [createEngine] 后可调用此函数。
相关接口：可调用 [muteAllPlayStreamVideo] 函数控制是否接收所有视频数据。必须当 [muteAllPlayStreamVideo] 和 [mutePlayStreamVideo] 两个函数同时设置为 "false" 时，本地用户拉流时才能接收远端用户的视频数据：1. 当调用 [muteAllPlayStreamVideo(true)] 函数时，全局生效，即本地用户会禁止接收所有远端用户的视频数据，此时无论在 [muteAllPlayStreamVideo] 之前还是之后调用 [mutePlayStreamVideo] 函数都不生效。2. 当调用 [muteAllPlayStreamVideo(false)] 函数时，本地用户可以接收所有远端用户的视频数据，此时可再通过 [mutePlayStreamVideo] 函数控制是否接收单条视频数据。调用 [mutePlayStreamVideo(true, streamID)] 函数则本地用户可以接收该 "streamID" 之外的其他视频数据；调用 [mutePlayStreamVideo(false, streamID)] 函数则本地用户可以接收 "streamID" 的视频数据。

支持版本：1.1.0 及以上。
注意事项： 1. 与 [muteAllPlayAudioStreams] 一起使用时，可以互相覆盖配置。

与 [muteAllPlayStreamVideo] 一起使用时，只有当 [muteAllPlayStreamVideo] 函数设置为 “false”时，此函数才有效。
当指定不接收视频流数据时，视图默认保持在最后一帧，如果需要清除最后一帧，请联系 ZEGO 技术支持。
停止拉流后对此条流此前设置的属性如 [setPlayVolume]、[mutePlayStreamAudio]、[mutePlayStreamVideo] 等拉流相关的配置都会失效，需要在下次拉流之前重新设置。

muteAllPlayStreamAudio

muteAllPlayStreamAudio(mute: boolean): void

拉流是否接收所有音频数据。（当设置为true时，调用[mutePlayStreamAudio]不会生效）

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	拉流时是否可以接收所有远端用户的音频数据，“true” 表示禁止，“false” 表示接收，默认值为 “false”。

详情

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

业务场景：当开发者需要快速关闭、恢复远端音频时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：在调用 [createEngine] 后可调用此函数。
相关接口：可调用 [mutePlayStreamAudio] 函数控制是否接收单条音频数据。必须当 [muteAllPlayStreamAudio] 和 [mutePlayStreamAudio] 两个函数同时设置为 "false" 时，本地用户拉流时才能接收远端用户的音频数据：1. 当调用 [muteAllPlayStreamAudio(true)] 函数时，全局生效，即本地用户会禁止接收所有远端用户的音频数据，此时无论在 [muteAllPlayStreamAudio] 之前还是之后调用 [mutePlayStreamAudio] 函数都不生效。 2. 当调用 [muteAllPlayStreamAudio(false)] 函数时，本地用户可以接收所有远端用户的音频数据，此时可再通过 [mutePlayStreamAudio] 函数控制是否接收单条音频数据。调用 [mutePlayStreamAudio(true, streamID)] 函数则本地用户可以接收该 "streamID" 之外的其他音频数据；调用 [mutePlayStreamAudio(false, streamID)] 函数则本地用户可以接收 "streamID" 的音频数据。

支持版本：2.4.0 及以上。
注意事项：此接口在 SDK 生命周期内不能和 [muteAllPlayAudioStreams] 混用。

muteAllPlayStreamVideo

muteAllPlayStreamVideo(mute: boolean): void

拉流是否可接收所有视频数据。（当设置为true时，调用[mutePlayStreamVideo]不会生效）

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	拉流时是否可以接收所有远端用户的视频数据，“true” 表示禁止，“false” 表示接收，默认值为 “false”。

详情

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

业务场景：当开发者需要快速关闭、恢复观看远端视频画面时，可调用此函数。相比重新拉流，能极大降低耗时，提升互动体验。
调用时机：在调用 [createEngine] 后可调用此函数。
相关接口：可调用 [mutePlayStreamVideo] 函数控制是否接收单条视频数据。必须当 [muteAllPlayStreamVideo] 和 [mutePlayStreamVideo] 两个函数同时设置为 "false" 时，本地用户拉流时才能接收远端用户的视频数据： 1. 当调用 [muteAllPlayStreamVideo(true)] 函数时，全局生效，即本地用户会禁止接收所有远端用户的视频数据，此时无论在 [muteAllPlayStreamVideo] 之前还是之后调用 [mutePlayStreamVideo] 函数都不生效。 2. 当调用 [muteAllPlayStreamVideo(false)] 函数时，本地用户可以接收所有远端用户的视频数据，此时可再通过 [mutePlayStreamVideo] 函数控制是否接收单条视频数据。调用 [mutePlayStreamVideo(true, streamID)] 函数则本地用户可以接收该 "streamID" 之外的其他视频数据；调用 [mutePlayStreamVideo(false, streamID)] 函数则本地用户可以接收 "streamID" 的视频数据。

支持版本：2.4.0 及以上。
注意事项： 1. 此接口在 SDK 生命周期内不能和 [muteAllPlayVideoStreams] 混用。

当指定不接收视频流数据时，视图默认保持在最后一帧，如果需要清除最后一帧，请联系 ZEGO 技术支持。

enableHardwareDecoder

enableHardwareDecoder(enable: boolean): void

开/关硬件解码。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启硬解开关，true 表示开启硬解，false 表示关闭硬解。

详情

拉流时是否使用硬件解码，开启硬件解码后 SDK 会使用 GPU 进行解码，降低 CPU 使用率。

业务场景：若开发者在某些机型测试时发现拉大分辨率音视频流时设备发热严重，可考虑调用此函数开启硬件解码的方式。
默认值：未调用此接口时，默认关闭硬解。
调用时机：此函数需要在 [createEngine] 创建实例后调用。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：在拉流前设置才能生效，如果在拉流后设置，停止拉流后重新拉流才生效，此配置生效后，在下次调用生效前一直有效。

enableCheckPoc

enableCheckPoc(enable: boolean): void

开/关帧顺序检测。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启帧顺序检测，true 表示开启帧顺序检测，false 表示关闭帧顺序检测。

详情

设置是否开启帧顺序检查。

业务场景：拉cdn的流时，开启帧顺序检测可防止花屏。
默认值：未调用此接口时，默认开启帧顺序检测。
调用时机：此函数需要在 [createEngine] 创建实例后调用。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：拉流过程中关闭顺序检测可能出现短暂花屏。

isVideoDecoderSupported

isVideoDecoderSupported(codecID: ZegoVideoCodecID, codecBackend: ZegoVideoCodecBackend): number

是否支持指定视频解码格式。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
codecID	ZegoVideoCodecID	视频解码类型。是否必填：是。
codecBackend	ZegoVideoCodecBackend	解码器的后端实现。是否必填：是。

详情

是否支持指定视频解码，主要取决于以下几个方面：硬件型号是否支持硬解、硬件型号性能是否支持软解、SDK 是否带该解码模块。

调用时机：创建引擎后。

支持版本：3.0.0 及以上。
注意事项：建议用户在拉 H.265 流前，先调用本接口获取 H.265 解码支持能力，如果不支持，可以拉其他编码格式的流，比如 H.264。

返回值

是否支持指定视频解码格式；0 表示不支持，不可以使用该解码格式进行拉流；1 表示支持，可以使用该解码格式进行拉流；2 表示未确认，建议稍后再调用本接口。

onPlayerStateUpdate

onPlayerStateUpdate(streamID: string, state: ZegoPlayerState, errorCode: number, extendedData: string): void

拉流状态变更回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	流 ID。
state	ZegoPlayerState	拉流状态。
errorCode	number	拉流状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	string	状态更新附带的扩展信息。备用，目前仅返回空 json 表。

详情

在调用拉流接口 [startPlayingStream] 成功后，可以通过该回调函数获取拉流状态变更的通知。开发者可根据 state 参数是否在 [正在请求拉流状态] 来大体判断用户的拉流网络情况。

通知时机：在调用拉流接口 [startPlayingStream] 成功后，拉流状态变更时。
相关回调：在调用推流接口 [startPublishingStream] 成功后，可以通过回调函数 [onPublisherStateUpdate] 获取推流状态变更的通知。开发者可根据 state 参数是否在 [正在请求推流状态] 来大体判断用户的推流网络情况。

支持版本：1.1.0 及以上。

onPlayerQualityUpdate

onPlayerQualityUpdate(streamID: string, quality: ZegoPlayStreamQuality): void

拉流质量回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
quality	ZegoPlayStreamQuality	拉流质量，包含了音视频帧率、码率、RTT 等值。

详情

在调用拉流接口 [startPlayingStream] 成功后每3秒(该时间如果需要变更，请联系 ZEGO 技术支持配置)会收到此回调，通过该回调可以获取拉取的音视频流的帧率，码率，RTT，丢包率等质量数据。

业务场景：开发者可根据此函数的质量参数实时监控拉取的音视频流的健康情况，以便在设备 UI 界面上实时展示下行网络状况。
相关回调：当调用推流接口 [startPublishingStream] 成功后每3秒会收到回调 [onPublisherQualityUpdate]，开发者可根据推送的音视频流的帧率，码率，RTT，丢包率等质量数据，实时监控推送流的健康情况。

支持版本：1.1.0 及以上。
注意事项：若开发者不清楚该回调函数的各个参数应该如何使用，可以只关注其中的 quality 参数的 level 字段，这是 SDK 内部根据质量参数计算的一个描述下行网络的综合值。

onPlayerMediaEvent

onPlayerMediaEvent(streamID: string, event: ZegoPlayerMediaEvent): void

拉流媒体事件回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
event	ZegoPlayerMediaEvent	拉流时收到的具体事件。

详情

该回调用于接收拉流媒体事件。

业务场景：开发者可以根据此回调对卡顿情况做统计或在 App 的 UI 界面做友好的展示。
通知时机：在调用拉流接口 [startPlayingStream]后，当拉流发生音视频卡顿以及恢复等事件发生时会触发此回调。

支持版本：1.1.0 及以上。

onPlayerRecvAudioFirstFrame

onPlayerRecvAudioFirstFrame(streamID: string): void

拉流端音频接收首帧回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧音频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 从网络接收到第一帧音频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到视频数据，通过回调 [onPlayerRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerRecvVideoFirstFrame

onPlayerRecvVideoFirstFrame(streamID: string): void

拉流端视频接收首帧回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧视频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 从网络接收到第一帧视频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerRenderVideoFirstFrame

onPlayerRenderVideoFirstFrame(streamID: string): void

拉流端渲染完视频首帧回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 拉流并渲染完第一帧视频数据后会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 拉流并渲染完第一帧视频数据后会收到此回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerVideoSizeChanged

onPlayerVideoSizeChanged(streamID: string, width: number, height: number): void

拉流分辨率变更通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
width	number	视频解码分辨率宽。
height	number	视频解码分辨率高。

详情

调用拉流函数 [startPlayingStream] 成功后，当收到视频首帧数据，或推流方通过 [setVideoConfig] 改变编码分辨率，或流控策略生效时，拉流分辨率会发生改变。

业务场景：开发者可根据流的最终分辨率来更新或切换真正播放流的 UI 组件。
通知时机：拉流 [startPlayingStream] 成功后，在拉流中途如果有视频分辨率发生变化将会收到此回调。

支持版本：1.1.0 及以上。
注意事项： 1. 若拉的是流只有音频数据，则不会收到该回调。

若用户开启 ZegoVideoBufferTypeEncodedData 类型的自定义视频渲染， SDK 不负责视频解码，则不会收到该回调。

onPlayerRecvSEI

deprecated

onPlayerRecvSEI(streamID: string, data: UInt8Array): void

收到远端流的 SEI 内容。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
data	UInt8Array	SEI 内容。

详情

调用拉流函数 [startPlayingStream] 成功后，当远端流发送 SEI 后（如直接调用 [sendSEI] 、混音中带 SEI 数据、自定义视频采集发送码流数据时附带 SEI 等等），本端会收到此回调。

通知时机：拉流 [startPlayingStream] 成功后，当远端流发送 SEI 后，本端会收到此回调。

支持版本：1.1.0 及以上。
注意事项： 1. 客户可在此回调函数中直接操作 UI 控件。

由于视频编码器自身会产生 payload type 为 5 的 SEI，或者使用视频文件推流时，视频文件中也可能存在这样的 SEI，因此若开发者需要过滤掉这类型的 SEI 时，可在 [createEngine] 之前调用 [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]。其中 unregister_sei_filter 为 key，XXXXX 为需要设置的uuid过滤字符串。 3.调用 [mutePlayStreamVideo] 或 [muteAllPlayStreamVideo] 设置只拉音频流时，将无法接收媒体次要信息。

已废弃

此函数将在 3.4.0 版本及以上已废弃，请使用 [onPlayerSyncRecvSEI] 函数代替。

onPlayerSyncRecvSEI

onPlayerSyncRecvSEI(streamID: string, data: UInt8Array): void

同步接收远端流的 SEI 内容。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
data	UInt8Array	SEI 内容。

详情

调用拉流函数 [startPlayingStream] 成功后，当远端流发送 SEI 后（例如直接调用 [sendSEI] 、混音中带 SEI 数据、自定义视频采集发送码流数据时附带 SEI 等等），本端会收到此回调。

通知时机：拉流 [startPlayingStream] 成功且远端流发送 SEI 后，本端会收到此回调。

支持版本：3.4.0 及以上。
注意事项： 1. 由于视频编码器自身会产生 payload type 为 5 的 SEI，或者使用视频文件推流时，视频文件中也可能存在这样的 SEI，因此若开发者需要过滤掉这类型的 SEI 时，可在 [createEngine] 之前调用 [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]，其中 unregister_sei_filter 为 key，XXXXX 为需要设置的 uuid 过滤字符串。 2.执行 [mutePlayStreamVideo] 或 [muteAllPlayStreamVideo] 设置只拉音频流时，将无法接收媒体次要信息。

startMixerTask

startMixerTask(task: ZegoMixerTask): Promise<number, string>

开始混流任务。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
task	ZegoMixerTask	混流任务对象。是否必填：是。

详情

向 ZEGO RTC 服务器发起混流请求，服务器会寻找当前正在推的流，并根据 SDK 请求的混流任务的参数进行图层混合。当需要更新混流任务时，即输入流增加或减少时需要更新输入流列表，此时可以更新 [ZegoMixerTask] 对象 inputList 的字段并再次调用本函数传入相同的 [ZegoMixerTask] 对象更新混流任务。

业务场景：常用于需要多个视频画面合成一个视频时使用混流，比如教育类，直播老师和学生的画面。
调用时机：调用 [loginRoom] 登录房间后。
相关回调：可通过 [onMixerRelayCDNStateUpdate] 获取混流转推 CDN 状态更新通知，可通过 [onMixerSoundLevelUpdate] 获取混流中的每条单流的声浪更新通知。
相关接口：可通过 [stopMixerTask] 函数停止混流。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：由于客户端设备的性能考虑，SDK 的混流是在 ZEGO RTC 服务器开启混流任务进行混流。若请求开启混流任务发生异常，例如最常见的混流的输入流不存在，将会从 callback 回调的错误码给出。具体错误码请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html 若中途某条输入流不存在了，混流任务会自动重试拉这条输入流 90 秒，90 秒之后不再重试。若所有输入流均不存在了，90秒之后服务器会自动停止混流任务。

返回值

开始混流任务结果

stopMixerTask

stopMixerTask(task: ZegoMixerTask): Promise<number>

停止混流任务。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
task	ZegoMixerTask	混流任务对象。是否必填：是。

详情

向 ZEGO RTC 服务器发起结束混流请求。

业务场景：常用于需要多个视频画面合成一个视频时使用混流，比如教育类，直播老师和学生的画面。
调用时机：调用 [startMixerTask] 开始混流后。
相关接口：可通过 [startMixerTask] 函数开始混流。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：若开发者在未停止上一个混流任务的情况下启动下一个混流任务，上一个混流任务不会自动停止，直到上一个混流任务的输入流持续 90 秒都不存在之后。在启动下一个混流任务前，应当先停止上一个混流任务，以免当一个主播已经开启下一个混流任务与其他主播混流时，观众依然在拉上一个混流任务的输出流。

返回值

停止混流任务结果

muteMicrophone

muteMicrophone(mute: boolean): void

设置是否静音（关闭麦克风）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	是否静音（关闭麦克风）；"true" 表示静音（关闭麦克风）；"false" 表示开启麦克风。

详情

此函数用于控制是否使用采集到的音频数据，静音（关闭麦克风）将会使用静音数据替换设备采集到的音频数据进行推流，此时仍然会占用麦克风设备。

业务场景：用户仅关闭麦克风采集的人声，不关闭媒体播放器的音乐声音，可以调用该接口。该接口影响 [onBeforeAudioPrepAudioData]。
默认值：默认为 "false"，即不静音。
调用时机：在创建引擎 [createEngine] 后。
相关接口：若想要真正让 SDK 放弃占用麦克风，例如实现 App 退到后台后释放麦克风占用等功能，可调用 [enableAudioCaptureDevice] 函数开关音频采集设备。可使用 [isMicrophoneMuted] 来检查麦克风是否静音。

支持版本：1.1.0 及以上。
使用限制：无。

isMicrophoneMuted

isMicrophoneMuted(): boolean

检查麦克风是否设置为静音。

Declared in ZegoExpressEngine.js

用于判断麦克风是否被设置为静音。

调用时机：在创建引擎 [createEngine] 后。
相关接口：[muteMicrophone]。

支持版本：1.1.0 及以上。
使用限制：无。

麦克风是否静音；"true" 表示麦克风静音；"false" 表示麦克风开启中（没有被静音）。

muteSpeaker

muteSpeaker(mute: boolean): void

设置是否静音（关闭音频输出）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mute	boolean	是否静音(关闭音频输出)；"true" 表示静音(关闭音频输出)；"false" 表示开启音频输出。

详情

设置静音后，SDK 所有声音都不会播放，包括拉流、媒体播放器等。

默认值：默认为 "false"，即不静音。
调用时机：在创建引擎 [createEngine] 后。

支持版本：1.1.0 及以上。
使用限制：无。

isSpeakerMuted

isSpeakerMuted(): boolean

检查音频输出是否静音。

Declared in ZegoExpressEngine.js

用于判断音频输出是否静音。

调用时机：在创建引擎 [createEngine] 后。
相关接口：[muteSpeaker]。

支持版本：1.1.0 及以上。
使用限制：无。

音频输出是否静音；"true" 表示音频输出静音；"false" 表示音频输出开启中（没有被静音）。

getAudioDeviceList

getAudioDeviceList(deviceType: ZegoAudioDeviceType): ZegoDeviceInfo[]

获取音频设备列表

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型

详情

只适用于 Windows / macOS / Linux

返回值

音频设备列表

getDefaultAudioDeviceID

getDefaultAudioDeviceID(deviceType: ZegoAudioDeviceType): string

获取默认音频设备 ID

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型

详情

只适用于 Windows / macOS / Linux

返回值

默认音频设备 ID

useAudioDevice

useAudioDevice(deviceID: string, deviceType: ZegoAudioDeviceType): void

选择使用某个音频设备

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID
deviceType	ZegoAudioDeviceType	音频设备类型

详情

选择使用某个音频设备。

调用时机：在创建引擎 [createEngine] 之后。

支持版本：1.1.0 及以上。
使用限制：仅支持 Windows / macOS / Linux

getAudioDeviceVolume

getAudioDeviceVolume(deviceType: ZegoAudioDeviceType, deviceID: string): number

获取音频设备音量

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID

详情

获取音频设备音量，只适用于 Windows / macOS / Linux

返回值

设备音量

setAudioDeviceVolume

setAudioDeviceVolume(deviceType: ZegoAudioDeviceType, deviceID: string, volume: number): void

设置音频设备音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID
volume	number	设备音量

详情

可能因为系统限制导致直接操作系统设备失败，请优先使用 [setCaptureVolume] 和 [setPlayVolume] 来调节推拉流音量。只适用于 Windows / macOS / Linux

setSpeakerVolumeInAPP

setSpeakerVolumeInAPP(deviceID: string, volume: number): void

设置 App 中扬声器的音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID。
volume	number	设备音量。

详情

设置 App 中扬声器的音量。使用场景：需要只调整app的播放音量，并且不要调整系统的播放音量。

调用时机：在创建引擎 [createEngine] 之后。

支持版本：3.3.0 及以上。
使用限制：只适用于 Windows。
注意事项：可能因为系统限制导致直接操作系统设备失败，请优先使用 [setCaptureVolume] 和 [setPlayVolume] 来调节推拉流音量。

getSpeakerVolumeInAPP

getSpeakerVolumeInAPP(deviceID: string): number

获取 App 中扬声器的音量，只支持 Windows。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID。

详情

获取 App 中扬声器的音量，只支持 Windows。

调用时机：在创建引擎 [createEngine] 之后。
相关接口：设置 App 中扬声器的音量 [setSpeakerVolumeInAPP]。

支持版本：3.3.0 及以上。
使用限制：只适用于 Windows。

返回值

设备音量。

startAudioDeviceVolumeMonitor

startAudioDeviceVolumeMonitor(deviceType: ZegoAudioDeviceType, deviceID: string): void

开启音频设备音量监控。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID

详情

启动音频设备音量监控器。当该设备音量发生变更时，会通过 [onAudioDeviceVolumeChanged] 回调变更后的音量。

调用时机：在创建引擎 [createEngine] 之后。
平台差异：仅支持 Windows 和 macOS。
相关接口：当不再需要监控设备音量时，请调用 [stopAudioDeviceVolumeMonitor] 停止监控。

支持版本：1.1.0 及以上。
注意事项：目前仅支持同时监控一个音频输出设备和一个音频输入设备，多次调用此接口且传入相同的设备类型时将会覆盖上一次调用时此接口设置的设备 ID。

stopAudioDeviceVolumeMonitor

stopAudioDeviceVolumeMonitor(deviceType: ZegoAudioDeviceType, deviceID: string): void

停止音频设备音量监控。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID

详情

停止音频设备音量监控器。

调用时机：在创建引擎 [createEngine] 之后，当不再需要监控设备音量时。
平台差异：仅支持 Windows 和 macOS。

支持版本：1.1.0 及以上。

muteAudioDevice

muteAudioDevice(deviceType: ZegoAudioDeviceType, deviceID: string, mute: boolean): void

静音或取消静音音频设备。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	通过 [getAudioDeviceList] 获取的某个设备的 ID
mute	boolean	是否静音音频设备；"true" 表示静音音频设备；"false" 表示取消静音音频设备。

详情

只适用于 Windows / macOS / Linux

enableAudioCaptureDevice

enableAudioCaptureDevice(enable: boolean): void

开/关音频采集设备。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启音频采集设备；"true" 表示打开音频采集设备；"false" 表示关闭音频采集设备。

详情

此函数用于控制是否使用音频采集设备。如果关闭音频采集设备，则 SDK 不会再占用音频设备，当然如果此时正在推流，默认情况下会使用静音数据做为音频数据进行推流。注意 Linux 平台不支持该功能使用场景：当用户从不需要用到音频的时候，可以调用此函数关闭音频采集。

默认值：默认为 "true"。
调用时机：在创建引擎 [createEngine] 后。
相关接口：硬件上关闭或打开麦克风是耗时操作，用户频繁操作时有一定的性能开销，一般推荐使用 [muteMicrophone]。

支持版本：1.1.0 及以上。
使用限制：无。

enableCamera

enableCamera(enable: boolean, channel: ZegoPublishChannel): void

开/关摄像头，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否打开摄像头；"true" 表示打开摄像头；"false" 表示关闭摄像头。
channel	ZegoPublishChannel	推流通道

详情

此函数用于控制是否启动摄像头的采集，关闭摄像头后，将不会进行视频采集，此时本地预览和推流都将没有视频数据。

默认值：默认为 "true"，即打开摄像头。
调用时机：在创建引擎 [createEngine] 后。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：在使用自定义视频采集功能 [enableCustomVideoCapture] 的情况下，由于开发者接管了视频数据的采集，SDK 不再负责视频数据的采集，但此函数依然会影响是否进行编码的行为。因此开发者使用自定义视频采集时，请确保此函数的值为 "true"。

useVideoDevice

useVideoDevice(deviceID: string, channel: ZegoPublishChannel): void

选择使用某个视频设备，支持设置指定推流通道

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceID	string	通过 [getVideoDeviceList] 获取的某个设备的 ID
channel	ZegoPublishChannel	推流通道

详情

只适用于 Windows / macOS / Linux

getVideoDeviceList

getVideoDeviceList(): ZegoDeviceInfo[]

获取视频设备列表

Declared in ZegoExpressEngine.js

只适用于 Windows / macOS / Linux

视频设备列表

getDefaultVideoDeviceID

getDefaultVideoDeviceID(): string

获取默认视频设备 ID

Declared in ZegoExpressEngine.js

只适用于 Windows / macOS / Linux

默认视频设备 ID

startSoundLevelMonitor

startSoundLevelMonitor(millisecond: number): void

启动声浪监控，支持设置监听间隔。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
millisecond	number	声浪的监控时间周期，单位为毫秒，取值范围 [100, 3000]。默认 100 ms。

详情

启动监控后可通过 [onCapturedSoundLevelUpdate] 回调接收本地采集音频声浪，以及 [onRemoteSoundLevelUpdate] 回调接收远端拉流音频声浪。开发者可在进入房间之前，调用 [startPreview] 与此函数，并与 [onCapturedSoundLevelUpdate] 结合来判断音频设备是否正常工作。

业务场景：在推拉流过程中，判断麦上的用户谁在说话，并做 UI 展示。
调用时机：在创建引擎 [createEngine] 后。

支持版本：1.15.0 及以上。
注意事项： 1. [onCapturedSoundLevelUpdate] 与 [onRemoteSoundLevelUpdate] 回调通知周期为参数设置的值，若需要使用声浪进阶功能，请使用同名重载函数（参数类型为 ZegoSoundLevelConfig）代替。 2. 启动声浪监控后，即使未启动本地音频采集，onCapturedSoundLevelUpdate也会有回调，声浪值为0。

startSoundLevelMonitorWithConfig

startSoundLevelMonitorWithConfig(config: ZegoSoundLevelConfig): void

启动声浪监控，支持开启进阶功能。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	ZegoSoundLevelConfig	启动声浪监控的配置。

详情

业务场景：在推拉流过程中，判断麦上的用户谁在说话，并做 UI 展示。
调用时机：在创建引擎 [createEngine] 后。

支持版本：2.10.0 及以上。
注意事项： 1. [onCapturedSoundLevelUpdate] 与 [onRemoteSoundLevelUpdate] 回调通知周期为参数设置的值。 2. 启动声浪监控后，即使未启动本地音频采集，onCapturedSoundLevelUpdate也会有回调，声浪值为0。

stopSoundLevelMonitor

stopSoundLevelMonitor(): void

停止声浪监控。

Declared in ZegoExpressEngine.js

停止监控后将停止回调本地采集以及远端拉流的音频声浪回调。

调用时机：在创建引擎 [createEngine] 后。
相关接口：可通过 [startSoundLevelMonitor] 启动声浪监控。

支持版本：1.1.0 及以上。

startAudioSpectrumMonitor

startAudioSpectrumMonitor(millisecond: number): void

启动音频频谱监控，支持设置监听间隔。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
millisecond	number	音频频谱的监控时间周期，单位为毫秒，最小值为 10。默认 500 ms。

详情

启动监控后可通过 [onCapturedAudioSpectrumUpdate] 回调接收本地采集音频频谱，以及 [onRemoteAudioSpectrumUpdate] 回调接收远端音频声浪。

业务场景：在主播 K 歌场景中，已经推流或拉流的前提下，让主播或观众看到音调与音量变化的动画。
调用时机：在创建引擎 [createEngine] 后。

支持版本：1.15.0 及以上。
注意事项：[onCapturedAudioSpectrumUpdate] 与 [onRemoteAudioSpectrumUpdate] 回调通知周期为参数设置的值。

stopAudioSpectrumMonitor

stopAudioSpectrumMonitor(): void

停止音频频谱监控。

Declared in ZegoExpressEngine.js

停止监控后将停止回调本地采集以及远端拉流的音频频谱回调。

调用时机：在创建引擎 [createEngine] 后。
相关接口：可通过 [startAudioSpectrumMonitor] 启动音频频谱监控。

支持版本：1.1.0 及以上。

enableHeadphoneMonitor

enableHeadphoneMonitor(enable: boolean): void

开启/关闭耳返。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	true: 开启耳返， false: 关闭耳返。

详情

开启耳返，用户使用麦克风采集声音时会听到自己的声音。

调用时机：在创建引擎 [createEngine] 后。
默认值：关闭。

支持版本：1.9.0 及以上。
注意事项： 1. 同时连接耳机和麦克风时该设置才实际生效。 2. 耳返默认是在采集之后、前处理之前返回，如果需要在前处理之后返回请咨询 ZEGO 技术支持。

setHeadphoneMonitorVolume

setHeadphoneMonitorVolume(volume: number): void

设置耳返音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
volume	number	采集耳返音量大小，取值 [0, 200]，默认 60。

详情

设置耳返音量。

调用时机：在创建引擎 [createEngine] 后。
相关接口：可通过 [enableHeadphoneMonitor] 开关耳返。

支持版本：1.9.0 及以上。
注意事项：同时连接耳机和麦克风时该设置才实际生效。

enableMixSystemPlayout

enableMixSystemPlayout(enable: boolean): void

开启/关闭系统声卡采集。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	true: 开启声卡采集， false: 关闭声卡采集

详情

开启声卡采集，将系统播放的声音混入推流中，如浏览器播放的声音、第三方播放器软件播放的声音等。

默认值：默认关闭。
调用时机：调用 [startPublishingStream] 或 [startPreview] 后调用此函数。
相关接口：[setMixSystemPlayoutVolume] 设置系统声卡采集的音量。
平台差异：仅支持 Windows、macOS。

支持版本：1.9.0 及以上。
使用限制：无。
注意事项：系统声卡声音不包含拉流声音、媒体播放器声音和音效播放器声音。

setMixSystemPlayoutVolume

setMixSystemPlayoutVolume(volume: number): void

设置系统声卡采集的音量。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
volume	number	声卡采集音量。有效范围 [0, 200]，默认为 100。

详情

设置系统声卡采集的音量。

业务场景：用户需要调整系统声卡采集的音量大小。
调用时机：调用 [startPublishingStream] 或 [startPreview] 后调用此函数。
相关接口：[enableMixSystemPlayout] 开启或关闭声卡采集。
平台差异：仅支持 Windows、macOS。

支持版本：2.4.0 及以上。
使用限制：无。

enableMixEnginePlayout

enableMixEnginePlayout(enable: boolean): void

是否将 SDK 播放的声音混到推流中。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	true: 开启， false: 关闭

详情

开启后将 SDK 播放的声音混入推流中。

业务场景：用户需要将 SDK 播放的声音混入推流中，例如直播上课场景时，老师与学生连麦，老师可以将拉流声音混入推流中。
默认值：默认关闭。
调用时机：调用 [startPublishingStream] 或 [startPreview] 后调用此函数。

支持版本：1.1.0 及以上。
使用限制：无。

startAudioVADStableStateMonitor

startAudioVADStableStateMonitor(type: ZegoAudioVADStableStateMonitorType, millisecond: number): void

开始语音的稳态检测，可设置检测周期。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
type	ZegoAudioVADStableStateMonitorType	语音检测器类型。
millisecond	number	检测周期默认值 3000，有效值 [200, 10000]

详情

启动监控后可通过 [onAudioVADStateUpdate] 回调接收指定类型的音频语音检测回调。

业务场景：例如指定采集后类型而且使用麦克风采集时，就可以通过这个接口检测主播是否有持续稳定的语音输入。
调用时机：开发者可在推流之前，调用 [startPreview] 与此函数，并与 [onAudioVADStateUpdate] 结合来判断音频设备是否正常工作。
相关接口：[stopAudioVADStableStateMonitor]

支持版本：2.17.0 及以上。
使用限制：无。

stopAudioVADStableStateMonitor

stopAudioVADStableStateMonitor(type: ZegoAudioVADStableStateMonitorType): void

停止语音的稳态检测。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
type	ZegoAudioVADStableStateMonitorType	语音检测器类型。

详情

调用该接口后不再能接收到指定类型的 [onAudioVADStateUpdate] 回调。

调用时机：无。
相关接口：[startAudioVADStableStateMonitor]

支持版本：2.14.0 及以上。
使用限制：无。

onAudioDeviceStateChanged

  onAudioDeviceStateChanged(updateType: ZegoUpdateType, deviceType: ZegoAudioDeviceType, deviceInfo: ZegoDeviceInfo): void

音频设备状态改变

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
updateType	ZegoUpdateType	更新类型（添加/删除）
deviceType	ZegoAudioDeviceType	音频设备类型
deviceInfo	ZegoDeviceInfo	音频设备信息

详情

通过监听此回调，用户可在必要的时候更新使用特定设备进行声音采集或输出。

通知时机：监测到系统中有音频设备添加或移除时，会触发此回调。
平台差异：仅支持 Windows、macOS。

支持版本：1.1.0 及以上。
使用限制：无。

onAudioDeviceVolumeChanged

onAudioDeviceVolumeChanged(deviceType: ZegoAudioDeviceType, deviceID: string, volume: number): void

音频设备音量变更。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	string	音频设备ID
volume	number	音频设备音量

详情

音频设备音量变更事件回调。

通知时机：调用 [startAudioDeviceVolumeMonitor] 函数启动设备音量监控器后，且监控的音频设备音量发生变更时。
平台差异：仅支持 Windows 和 macOS。

支持版本：1.1.0 及以上。

onVideoDeviceStateChanged

onVideoDeviceStateChanged(updateType: ZegoUpdateType, deviceInfo: ZegoDeviceInfo): void

视频设备状态改变。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
updateType	ZegoUpdateType	更新类型（添加/删除）
deviceInfo	ZegoDeviceInfo	视频设备信息

详情

通过监听此回调，用户可在必要的时候更新使用特定设备进行视频采集。

通知时机：监测到系统中有视频设备添加或移除时，会触发此回调。
平台差异：仅支持 Windows、macOS。

支持版本：1.1.0 及以上。
使用限制：无。

onCapturedSoundLevelUpdate

onCapturedSoundLevelUpdate(soundLevel: number): void

本地采集音频声浪回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
soundLevel	number	本地采集的声浪值，取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

本地采集音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onRemoteSoundLevelUpdate] 监控远端拉流音频声浪。

支持版本：1.1.0 及以上。
注意事项： 1. 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值，当处于未推流 [startPublishingStream] 且未预览 [startPreview] 状态时，回调数值为默认值 0。 2. 该回调为高频回调，建议不要在回调内部做复杂逻辑处理。

onCapturedSoundLevelInfoUpdate

onCapturedSoundLevelInfoUpdate(soundLevelInfo: ZegoSoundLevelInfo *): void

本地采集音频声浪回调，支持人声检测。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
soundLevelInfo	ZegoSoundLevelInfo *	本地采集的声浪值，取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

本地采集音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onRemoteSoundLevelUpdate] 或 [onRemoteSoundLevelInfoUpdate] 监控远端拉流音频声浪。

支持版本：2.10.0 及以上。
注意事项： 1. 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。 2. 该回调为高频回调，建议不要在回调内部做复杂逻辑处理。

onRemoteSoundLevelUpdate

onRemoteSoundLevelUpdate(soundLevels: Object): void

远端拉流音频声浪回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
soundLevels	Object	远端的声浪键值对，key 为流 ID，value 为对应的流的声浪值，value 取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

远端拉流音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onCapturedSoundLevelUpdate] 或 [onCapturedSoundLevelInfoUpdate] 监控本地拉流音频声浪。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。

onLocalCaptureVideoData

onLocalCaptureVideoData(videoParam: ZegoVideoFrameObject): void

本地采集视频数据回调。

Declared in ZegoExpressEngine.js

名称	类型	描述
videoParam	ZegoVideoFrameObject	视频帧参数。

onRemotePlayVideoData

onRemotePlayVideoData(videoParam: ZegoVideoFrameObject): void

拉流视频数据回调。

Declared in ZegoExpressEngine.js

名称	类型	描述
videoParam	ZegoVideoFrameObject	视频帧参数。

onRemoteSoundLevelInfoUpdate

onRemoteSoundLevelInfoUpdate(soundLevelInfos: Map<String, ZegoSoundLevelInfo>): void

远端拉流音频声浪回调，支持人声检测。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
soundLevelInfos	Map<String, ZegoSoundLevelInfo>	远端的声浪键值对，key 为流 ID，value 为对应的流的声浪值，value 取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

远端拉流音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onCapturedSoundLevelUpdate] 或 [onCapturedSoundLevelInfoUpdate] 监控本地拉流音频声浪。

支持版本：2.10.0 及以上。
注意事项：回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。

onCapturedAudioSpectrumUpdate

onCapturedAudioSpectrumUpdate(audioSpectrum: number[]): void

本地采集音频频谱回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
audioSpectrum	number[]	本地采集的音频频谱值数组，频谱值范围为 [0-2^30]。

详情

本地采集音频频谱回调。

通知时机：调用 [startAudioSpectrumMonitor] 函数启动声浪监控器后。
相关接口：通过 [startAudioSpectrumMonitor] 启动声浪监控，通过回调 [onRemoteAudioSpectrumUpdate] 监控远端拉流音频频谱。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startAudioSpectrumMonitor] 时设置的参数值，当处于未推流 [startPublishingStream] 且未预览 [startPreview] 状态时，回调数值为默认值 0。

onRemoteAudioSpectrumUpdate

onRemoteAudioSpectrumUpdate(audioSpectrums: object): void

远端拉流音频频谱回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
audioSpectrums	object	远端音频频谱键值对，key 是流 ID，value 为对应的流的音频频谱值数组，频谱值范围为 [0-2^30]

详情

远端拉流音频频谱回调。

通知时机：调用 [startAudioSpectrumMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startAudioSpectrumMonitor] 启动音频频谱监控，通过回调 [onCapturedAudioSpectrumUpdate] 监控本地采集音频频谱。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startAudioSpectrumMonitor] 时设置的参数值。

onLocalDeviceExceptionOccurred

  onLocalDeviceExceptionOccurred(exceptionType: ZegoDeviceExceptionType, deviceType: ZegoDeviceType, deviceID: string): void

本地设备异常通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
exceptionType	ZegoDeviceExceptionType	设备异常类型。
deviceType	ZegoDeviceType	发生异常的设备类型。
deviceID	string	设备 ID。目前仅支持桌面端设备，用于标识具体的设备；对于移动端设备，此参数将返回空字符串。

详情

本地设备异常。

通知时机：当本地音频或视频设备功能出现异常时会触发此回调。

支持版本：2.15.0 及以上。

onRemoteCameraStateUpdate

onRemoteCameraStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

远端摄像头设备状态通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
state	ZegoRemoteDeviceState	远端摄像头状态。

详情

远端摄像头设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的摄像头设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端摄像头设备状态发生变更时，例如开关摄像头等，通过监听此回调，能够获取远端摄像头相关的事件，可以用于提示用户可能导致视频异常的情况。

支持版本：1.1.0 及以上。
注意事项：当从 CDN 拉流时，或对端使用了自定义视频采集时，不会触发此回调。

onRemoteMicStateUpdate

onRemoteMicStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

远端麦克风设备状态通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
state	ZegoRemoteDeviceState	远端麦克风状态。

详情

远端麦克风设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的麦克风设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端麦克风设备状态发生变更时，例如开关麦克风等，通过监听此回调，能够获取远端麦克风相关的事件，可以用于提示用户可能导致音频异常的情况。

支持版本：1.1.0 及以上。
注意事项：当从 CDN 拉流时，或对端使用了自定义音频采集时（且不是推流到 ZEGO RTC服务器），不会触发此回调。

onRemoteSpeakerStateUpdate

onRemoteSpeakerStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

远端扬声器设备状态通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
streamID	string	拉流的流 ID。
state	ZegoRemoteDeviceState	远端扬声器状态。

详情

远端扬声器设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的扬声器设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端扬声器设备状态发生变更时，例如开关扬声器等，通过监听此回调，能够获取远端扬声器相关的事件。

支持版本：1.1.0 及以上。
注意事项：此回调当从 CDN 拉流时不会回调。

onAudioVADStateUpdate

onAudioVADStateUpdate(type: ZegoAudioVADStableStateMonitorType, state: ZegoAudioVADType): void

检测音频数据的稳态语音状态的回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
type	ZegoAudioVADStableStateMonitorType	语音检测器类型
state	ZegoAudioVADType	语音检测结果

详情

检测音频数据的稳态语音状态的回调。触发时机：调用 [startAudioVADStableStateMonitor] 启动语音状态检测，且处于正在推流的状态或预览预览状态。

相关接口：[startAudioVADStableStateMonitor]， [stopAudioVADStableStateMonitor]。

支持版本：2.14.0 及以上。
使用限制：回调通知周期为 3 秒。

getCurrentAudioDevice

getCurrentAudioDevice(deviceType: ZegoAudioDeviceType): ZegoDeviceInfo

获取当前使用的音频设备信息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
deviceType	ZegoAudioDeviceType	音频设备类型。是否必填：是。

详情

获取当前使用的音频设备信息。

业务场景：用于需要手动在多个音频设备间切换的场景。
调用时机：调用 [startPublishingStream] 或 [startPreview] 后调用此函数。
相关接口：可通过 [getDefaultAudioDeviceID] 获取默认音频设备 ID。

支持版本：2.12.0 及以上。
使用限制：仅支持 Windows 和 macOS。

返回值

音频设备信息。

enableAEC

enableAEC(enable: boolean): void

是否开启回声消除。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启回声消除；true 表示开启；false 表示关闭

详情

打开回声消除， SDK 会对采集到的音频数据进行过滤以降低音频中的回音成分。

业务场景：当需要降低回声以提高通话质量和用户体验时，可以开启此功能。
调用时机：需要在 [createEngine] 之后调用。
相关接口：开发者可通过 [enableHeadphoneAEC] 以设置当使用耳机时是否也开启回声消除；可通过 [setAECMode] 设置回声消除的模式。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：回声消除功能仅支持处理经过 SDK 播放的声音，例如拉流、媒体播放器、音效播放器等功能播放的声音。未调用此函数前，SDK 内部会自动判断是否需要使用 AEC，一旦调用了此函数则不再自动判断。

setAECMode

setAECMode(mode: ZegoAECMode): void

设置回声消除模式

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoAECMode	回声消除模式

详情

当使用 [enableAEC] 开启了回声消除后，可通过此函数切换不同的回声消除模式以控制消除回声数据的程度。

业务场景：当默认的回声消除效果不符合预期时，可通过此函数调整回声消除模式。
默认值：未调用此函数时，默认的回声消除模式为 [Aggressive] 激进模式。
调用时机：需要在 [createEngine] 之后调用。

支持版本：1.1.0 及以上。
使用限制：仅在开启了回声消除功能后此函数设置的值才有效。

enableAGC

enableAGC(enable: boolean): void

开/关自动增益控制

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启自动增益控制；true 表示开启；false 表示关闭

详情

开启该功能后，SDK 能够自动调节麦克风音量，适应远近拾音，保持音量稳定。

业务场景：当需要保障音量稳定性以提高通话质量和用户体验时，可以开启此功能。
调用时机：需要在 [createEngine] 之后调用。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：未调用此函数前，SDK 内部会自动判断是否需要使用 AGC，一旦调用了此函数则不再自动判断。

enableANS

enableANS(enable: boolean): void

开/关噪声抑制

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启噪声抑制；true 表示开启噪声抑制；false 表示关闭噪声抑制

详情

开启该功能后，可以使人声更加清晰。

业务场景：当需要抑制噪声以提高通话质量和用户体验时，可以开启此功能。
调用时机：需要在 [createEngine] 之后调用。
相关接口：此功能对持续性的噪声（例如下雨声等白噪音）抑制效果较好，如果需要抑制瞬态噪声，请使用 [enableTransientANS]；可通过 [setANSMode] 设置噪声抑制的模式。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：未调用此函数前，SDK 内部会自动判断是否需要使用 ANS，一旦调用了此函数则不再自动判断。

enableTransientANS

enableTransientANS(enable: boolean): void

开/关瞬态噪声抑制

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启瞬态噪声抑制；true 表示开启；false 表示关闭

详情

用于抑制敲击键盘、桌子等瞬态噪声。

业务场景：当需要抑制瞬态噪声以提高通话质量和用户体验时，可以开启此功能。
默认值：未调用此函数时，默认不开启瞬态噪声抑制。
调用时机：需要在 [createEngine] 之后调用。
相关接口：此函数开启后不会抑制常规噪声，如果需要开启常规噪声抑制，请使用 [enableANS]

支持版本：1.17.0 及以上。
使用限制：无。

setANSMode

setANSMode(mode: ZegoANSMode): void

设置音频噪声抑制模式

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoANSMode	噪声抑制模式

详情

当使用 [enableANS] 开启了噪声抑制后，可通过此函数切换不同的噪声抑制模式以控制抑制噪声数据的程度。

业务场景：当默认的噪声抑制效果不符合预期时，可通过此函数调整噪声抑制模式。
默认值：未调用此函数时，默认的噪声抑制模式为 [Medium] 中等模式。
调用时机：需要在 [createEngine] 之后调用。

支持版本：1.1.0 及以上。
使用限制：仅在开启了噪声抑制功能后此函数设置的值才有效。

setAudioEqualizerGain

setAudioEqualizerGain(bandIndex: number, bandGain: number): void

设置音效均衡器（EQ）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
bandIndex	number	频谱子带索引，取值范围 [0, 9]，分别对应 10 个频带，中心频率分别是 [31, 62, 125, 250, 500, 1K, 2K, 4K, 8K, 16K] Hz。
bandGain	number	指定频带的增益值，取值范围 [-15, 15]，默认值为 0，如果所有频带的增益值全部为 0，即关闭 EQ 功能。

详情

可通过调用本函数设置音效均衡器调整音色。

业务场景：通常用于语聊房、KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。

支持版本：1.12.0 及以上。
使用限制：无。

setVoiceChangerPreset

setVoiceChangerPreset(preset: ZegoVoiceChangerPreset): void

通过预设枚举设置变声。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
preset	ZegoVoiceChangerPreset	变声预设枚举。

详情

可通过调用本函数设置预设变声效果。

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。
相关接口：如需自定义变声效果，可使用 [setVoiceChangerParam]。本函数与 [setReverbPreset] 同时使用效果可能和预期有差异，如需同时使用，建议先开启变声，再开启混响。使用机器人或空灵预设变声效果时，会修改混响或混响回声参数。因此，在使用上述预设变声效果后调用 [setVoiceChangerParam], [setReverbAdvancedParam], [setReverbEchoParam] 等函数可能影响变声效果。如需自定义混响/回声/变声/电音效果可通过 [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam], [setElectronicEffects] 四个函数组合配置使用。

支持版本：1.17.0 及以上。

setVoiceChangerParam

setVoiceChangerParam(param: ZegoVoiceChangerParam): void

设置变声的具体参数。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
param	ZegoVoiceChangerParam	变声参数。

详情

可通过调用本函数设置自定义变声效果。

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。
相关接口：如需使用常见的变声效果，可使用 [setVoiceChangerPreset] 函数。如需自定义混响/回声/变声效果可通过 [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] 三个函数组合配置使用。

支持版本：1.10.0 及以上。

setReverbPreset

setReverbPreset(preset: ZegoReverbPreset): void

通过预设枚举设置混响。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
preset	ZegoReverbPreset	混响预设枚举。

详情

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

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。支持推流过程中调用本函数动态设置混响效果。
相关接口：如需自定义混响效果，请使用 [setReverbAdvancedParam]。本函数与 [setVoiceChangerPreset] 同时使用效果可能和预期有差异，如需同时使用，建议先开启变声，再开启混响。如需自定义混响/回声/变声效果可通过 [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] 三个函数组合配置使用。

支持版本：1.17.0 及以上。

setReverbAdvancedParam

setReverbAdvancedParam(param: ZegoReverbAdvancedParam): void

设置混响的具体参数。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
param	ZegoReverbAdvancedParam	混响高级参数。

详情

可通过调用本函数设置自定义混响效果。

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。
相关接口：如需使用常见的混响效果，可使用 [setReverbPreset] 函数。如需自定义混响/回声/变声效果可通过 [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] 三个函数组合配置使用。

支持版本：1.10.0 及以上。
注意事项：推流过程中动态设置不同的值都会生效，当全部参数都设置成 0 时，混响关闭。

setReverbEchoParam

setReverbEchoParam(param: ZegoReverbEchoParam): void

设置混响回声效果的具体参数。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
param	ZegoReverbEchoParam	混响回声效果参数。

详情

可通过调用本函数设置混响回声效果。可搭配变声、混响以实现自定义各式各样的声音效果。

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。
相关接口：如需自行配置混响/回声/变声效果请通过 [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] 三个函数组合使用。

支持版本：1.17.0 及以上。

enableVirtualStereo

enableVirtualStereo(enable: boolean, angle: number): void

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

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	true 代表开启虚拟立体声，false 代表关闭虚拟立体声。
angle	number	虚拟立体声中声源的角度，范围为 -1 ~ 360，90 为正前方，0 / 180 / 270 分别对应最右边 / 最左边 / 正后方；特别的，设置 -1 时为全方位虚拟立体声效果。

详情

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

业务场景：通常用于直播、语聊房和 KTV 等场景。
调用时机：需要在 [createEngine] 之后调用才有效。

支持版本：1.10.0 及以上；注意：从 2.15.0 版本开始，角度参数支持设置 -1 以呈现全方位虚拟立体声效果。
注意事项：需要调用 [setAudioConfig] 设置双声道后虚拟立体声才能生效。

sendBroadcastMessage

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

发送房间广播消息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，不得为空，最大长度小于 128 字节的字符串。注意事项： 1.房间 ID 由您自己定义。 2. 仅支持数字，英文字符和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。 3. 如果需要与 Web SDK 互通，请不要使用 '%'。
message	string	消息内容。是否必填：是。取值范围：长度不超过 1024 字节。

详情

向房间发送广播消息，已经登录相同房间的用户能收到消息，消息可靠。

业务场景：一般在直播房间内使用。
调用时机：调用 [loginRoom] 登录房间之后。
相关回调：可通过 [onIMRecvBroadcastMessage] 接收到房间广播消息。
相关接口：可通过 [sendBarrageMessage] 函数发送弹幕消息，可通过 [sendCustomCommand] 函数发送自定义信令。

支持版本：1.2.1 及以上。
使用限制：同一房间内的广播消息发送频率不能高于 10条/s。单个用户在客户端调用此接口的最大QPS为2，关于此函数的使用限制，请参考 https://doc-zh.zego.im/article/7581 或联系 ZEGO 技术支持。

返回值

发送广播消息结果通知。

sendBarrageMessage

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

发送房间弹幕消息。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，不得为空，最大长度小于 128 字节的字符串。注意事项： 1.房间 ID 由您自己定义。 2. 仅支持数字，英文字符和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。 3. 如果需要与 Web SDK 互通，请不要使用 '%'。
message	string	消息内容。是否必填：是。取值范围：长度不超过 1024 字节。

详情

向房间发送弹幕消息，已经登录相同房间的用户能收到消息，消息不可靠。

业务场景：一般用于房间内有大量消息收发，且不需要保证消息可靠性的场景，例如直播弹幕。
调用时机：调用 [loginRoom] 登录房间之后。
相关回调：可通过 [onIMRecvBarrageMessage] 接收到房间弹幕消息。
相关接口：可通过 [sendBroadcastMessage] 函数发送广播消息，可通过 [sendCustomCommand] 函数发送自定义信令。

支持版本：1.5.0 及以上。
使用限制：同一房间内的弹幕消息发送频率不能高于 20条/s。关于此函数的使用限制，请参考 https://doc-zh.zego.im/article/7581 或联系 ZEGO 技术支持。

返回值

发送弹幕消息结果通知。

sendCustomCommand

sendCustomCommand(roomID: string, command: string, toUserList: ZegoUser[]): Promise<Object>

发送自定义信令。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID，不得为空，最大长度小于 128 字节的字符串。注意事项： 1.房间 ID 由您自己定义。 2. 仅支持数字，英文字符和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''。 3. 如果需要与 Web SDK 互通，请不要使用 '%'。
command	string	自定义信令内容。是否必填：是。取值范围：最大长度为 1024 字节。注意事项：为保护隐私，请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。
toUserList	ZegoUser[]	信令的接收者列表。是否必填：是。取值范围：用户列表或者 [nullptr]。注意事项：为 [nullptr] 时 SDK 回向房间内所有用户发送自定义信令。

详情

向已经登录相同房间的其他用户发送点对点的信令，消息可靠。

业务场景：一般用于远程控制信令或用户与用户之间的消息发送。
调用时机：调用 [loginRoom] 登录房间之后。
相关回调：可通过 [onIMRecvCustomCommand] 接收到房间自定义信令。
相关接口：可通过 [sendBroadcastMessage] 函数发送广播消息，可通过 [sendBarrageMessage] 函数发送弹幕消息。
隐私保护声明：请勿在此接口填写用户敏感信息，包括但不限于手机号、身份证号、护照编号、真实姓名等。

支持版本：1.2.1 及以上。
使用限制：同一房间内向单个用户发送的自定义消息频率不能高于 200条/s，向多个用户发送的自定义消息不能高于 10条/s。关于此函数的使用限制，请参考 https://doc-zh.zego.im/article/7581 或联系 ZEGO 技术支持。

返回值

发送信令结果通知。

onIMRecvBroadcastMessage

onIMRecvBroadcastMessage(roomID: string, messageList: ZegoBroadcastMessageInfo[]): void

接收房间广播消息通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID。取值范围：最大长度为 128 字节。
messageList	ZegoBroadcastMessageInfo[]	收到的消息列表。取值范围：每次最多接收 50 条消息。

详情

该回调用于接收相同房间内其他用户发送的广播消息。

业务场景：一般在直播房间内使用。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有用户通过 [sendBroadcastMessage] 函数发送广播消息，则触发此回调。
相关回调：可通过[onIMRecvBarrageMessage]接收房间弹幕消息，可通过 [onIMRecvCustomCommand] 接收房间自定义信令。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：用户自己发送的广播消息不会通过此回调得到通知。

onIMRecvBarrageMessage

onIMRecvBarrageMessage(roomID: string, messageList: ZegoBarrageMessageInfo[]): void

接收房间弹幕消息通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID。取值范围：最大长度为 128 字节。
messageList	ZegoBarrageMessageInfo[]	收到的消息列表。取值范围：每次最多接收 50 条消息。

详情

该回调用于接收相同房间内其他用户发送的弹幕消息。

业务场景：一般用于房间内有大量消息收发，且不需要保证消息可靠性的场景，例如直播弹幕。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有用户通过 [sendBarrageMessage] 函数发送弹幕消息，则触发此回调。
相关回调：可通过[onIMRecvBroadcastMessage]接收房间广播消息，可通过 [onIMRecvCustomCommand] 接收房间自定义信令。

支持版本：1.5.0 及以上。
使用限制：无。
注意事项：用户自己发送的弹幕消息不会通过此回调得到通知。在房间内有大量弹幕消息时可能会延迟收到通知，且可能丢失部分弹幕消息。

onIMRecvCustomCommand

onIMRecvCustomCommand(roomID: string, fromUser: ZegoUser, command: string): void

接收自定义信令通知。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
roomID	string	房间 ID。取值范围：最大长度为 128 字节。
fromUser	ZegoUser	信令的发送人。
command	string	信令内容。取值范围：最大长度为 1024 字节。

详情

该回调用于接收相同房间内其他用户发送的自定义信令。

业务场景：一般在直播房间内使用。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有其他用户通过 [sendCustomCommand] 函数发送自定义信令给开发者，则触发此回调。
相关回调：可通过[onIMRecvBroadcastMessage]接收房间广播消息，可通过 [onIMRecvBarrageMessage] 接收房间弹幕消息。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：用户自己发送给自己的自定义信令不会通过此回调得到通知。

createMediaPlayer

createMediaPlayer(): ZegoMediaPlayer

创建媒体播放器实例对象。

Declared in ZegoExpressEngine.js

创建媒体播放器实例对象。

业务场景：常用于播放媒体资源场景，例如播放视频文件，结合自定义视频采集将媒体资源的视频数据推送出去，远端可拉流观看。
调用时机：在初始化 SDK [createEngine] 之后。
相关接口：用户可以调用 [destroyMediaPlayer] 销毁媒体播放器实例对象。

支持版本：2.1.0 及以上。
使用限制：目前最多支持创建 4 个实例，超过后将返回 null。
注意事项：媒体播放器的实例越多，对设备的性能开销越大。

媒体播放器实例，超过最大数量限制后将返回 null。

destroyMediaPlayer

destroyMediaPlayer(mediaPlayer: ZegoMediaPlayer): void

销毁媒体播放器实例对象。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer	媒体播放器实例对象。

详情

销毁媒体播放器实例对象。

相关接口：用户可以调用 [createMediaPlayer] 创建媒体播放器实例对象。

支持版本：2.1.0 及以上。

createAudioEffectPlayer

createAudioEffectPlayer(): ZegoAudioEffectPlayer

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

Declared in ZegoExpressEngine.js

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

业务场景：当需要播放简短的声音效果，比如鼓掌，欢呼声等时，可以使用音效播放器来实现。
调用时机：在 [createEngine] 之后可调用。
相关接口：[destroyAudioEffectPlayer]。

支持版本：1.16.0 及以上。
使用限制：目前最多支持创建 1 个实例，超过后将返回 null。

音效播放器实例，超过最大数量限制后将返回 null。

destroyAudioEffectPlayer

destroyAudioEffectPlayer(audioEffectPlayer: ZegoAudioEffectPlayer): void

销毁音效播放器实例对象。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
audioEffectPlayer	ZegoAudioEffectPlayer	音效播放器实例对象。

详情

销毁指定的音效播放器实例对象。

调用时机：在 [createAudioEffectPlayer] 之后可调用。
相关接口：[createAudioEffectPlayer]。

支持版本：1.16.0 及以上。
使用限制：无。

startRecordingCapturedData

startRecordingCapturedData(config: ZegoDataRecordConfig, channel: ZegoPublishChannel): void

开始本地录制，直接将音视频数据录制到本地文件。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	ZegoDataRecordConfig	录制配置对象。
channel	ZegoPublishChannel	推流通道。

详情

开始录制本端音频或音视频，直接将音视频数据录制到本地文件，录制的数据将与该通道推流的数据一致。

相关回调：开始录制后将会收到 [onCapturedDataRecordStateUpdate] 录制状态回调和 [onCapturedDataRecordProgressUpdate] 录制进度回调。

支持版本：1.10.0 及以上。
使用限制：无。
注意事项：录制过程中不可以停止预览 [stopPreview] 或停止推流 [stopPublishingStream]，否则 SDK 将主动结束当前录制任务。媒体播放器的数据需要混入到推流中才能录制。

stopRecordingCapturedData

stopRecordingCapturedData(channel: ZegoPublishChannel): void

结束录制本端音频或音视频。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

结束录制本端音频或音视频。

调用时机：在 [startRecordingCapturedData] 之后。

支持版本：1.10.0 及以上。
使用限制：无。

onCapturedDataRecordStateUpdate

  onCapturedDataRecordStateUpdate(state: ZegoDataRecordState, errorCode: number, config: ZegoDataRecordConfig, channel: ZegoPublishChannel): void

本地录制的状态更新回调，当录制过程状态变化时触发。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
state	ZegoDataRecordState	文件录制状态。
errorCode	number	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
config	ZegoDataRecordConfig	录制配置对象。
channel	ZegoPublishChannel	推流通道。

详情

本地录制的状态更新回调，当录制过程状态变化时触发。

业务场景：开发者应根据此回调来判断文件录制的状态或者进行 UI 的提示等。
通知时机：调用 [startRecordingCapturedData] 后，当录制过程状态变化时触发。

支持版本：1.10.0 及以上。
使用限制：无。

onCapturedDataRecordProgressUpdate

  onCapturedDataRecordProgressUpdate(progress: ZegoDataRecordProgress, config: ZegoDataRecordConfig, channel: ZegoPublishChannel): void

录制进度更新回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
progress	ZegoDataRecordProgress	文件录制过程进度，开发者可以此对用户界面进行 UI 的提示等。
config	ZegoDataRecordConfig	录制配置对象。
channel	ZegoPublishChannel	推流通道。

详情

本地录制的进度更新回调，录制过程中定时触发。

业务场景：开发者可以此对用户界面进行 UI 的提示等。
通知时机：调用 [startRecordingCapturedData] 后，如果配置了需要回调，录制过程中定时触发。

支持版本：1.10.0 及以上。
使用限制：无。

startNetworkSpeedTest

startNetworkSpeedTest(config: ZegoNetworkSpeedTestConfig, interval: number): void

启动网络测速，支持设置测速周期。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
config	ZegoNetworkSpeedTestConfig	网络测速度配置。
interval	number	网络测速周期。单位为毫秒，默认为 3000 ms。

详情

网络连通状态下的上行/下行网络测速。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
调用时机：需要在 [loginRoom] 后调用。若在测速中途开始推流/拉流，则测速会自动停止。
相关接口：可通过 [stopNetworkSpeedTest] 停止网络测速。

支持版本：1.20.0 及以上。
使用限制：单次网络测速默认最大允许测试时间为30秒。
注意事项：可监听 [onNetworkSpeedTestQualityUpdate] 回调来获取测速结果，每 3 秒回调一次结果。若测速过程中发生异常，将会触发 [onNetworkSpeedTestError] 回调。若重复多次调用本函数，将以最后一次调用的测速配置为准。

stopNetworkSpeedTest

stopNetworkSpeedTest(): void

停止网络测速。

Declared in ZegoExpressEngine.js

停止网络测速。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
调用时机：需要在 [createEngine] 之后调用。
相关接口：可通过 [startNetworkSpeedTest] 启动网络测速。

支持版本：1.20.0 及以上。
使用限制：无。
注意事项：停止网络测速后，将不再触发 [onNetworkSpeedTestQualityUpdate] 回调。

getNetworkTimeInfo

getNetworkTimeInfo(): ZegoNetworkTimeInfo

获取同步网络时间信息。

Declared in ZegoExpressEngine.js

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

业务场景：在进行多端行为同步时，需要获取同步网络时间对当前时间进行校准。
调用时机：需要在 [createEngine] 之后调用。

支持版本：2.9.0 及以上。
使用限制：无。

网络时间信息。

onNetworkModeChanged

onNetworkModeChanged(mode: ZegoNetworkMode): void

网络模式变更回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoNetworkMode	当前网络模式。

详情

网络模式变更回调。

通知时机：当设备的网络模式改变时，例如从 WiFi 切换到 5G，或断网等情况，将会触发本回调。

支持版本：1.20.0 及以上。
使用限制：无。

onNetworkSpeedTestError

onNetworkSpeedTestError(errorCode: number, type: ZegoNetworkSpeedTestType): void

网络测速异常回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
errorCode	number	网络测速错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
type	ZegoNetworkSpeedTestType	上行或下行网络。

详情

网络测速异常回调。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
通知时机：网络测试过程中发生异常时，例如：连接测速服务器失败等，将触发本回调。

支持版本：1.20.0 及以上。
使用限制：无。

onNetworkSpeedTestQualityUpdate

onNetworkSpeedTestQualityUpdate(quality: ZegoNetworkSpeedTestQuality, type: ZegoNetworkSpeedTestType): void

网络测速质量回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
quality	ZegoNetworkSpeedTestQuality	网速测速质量.
type	ZegoNetworkSpeedTestType	上行或下行网络。

详情

网络连通状态下的网络测速质量回调。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
通知时机：调用 [startNetworkSpeedTest] 启动网络测速后，将触发本回调。回调通知周期为调用 [startNetworkSpeedTest] 时设置的参数值，未设置该参数时，默认 3 秒回调一次。

支持版本：1.20.0 及以上。
使用限制：无。
注意事项：当测速发生异常或停止测速时，本回调将会不再触发。

onNetworkQuality

  onNetworkQuality(userID: string, upstreamQuality: ZegoStreamQualityLevel, downstreamQuality: ZegoStreamQualityLevel): void

房间内正在推流的用户的网络质量回调。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
userID	string	用户 ID，空表示本地用户
upstreamQuality	ZegoStreamQualityLevel	上行网络质量
downstreamQuality	ZegoStreamQualityLevel	下行网络质量

详情

本地和远端用户的上下行网络回调，默认每两秒回调一次本地和每个拉取的远端用户的网络状况。 2.10.0 至 2.13.1 版本： 1. 自身必须既推流又拉流，才会收到自身的网络质量回调。 2. 当拉一条流时，推流端有拉流且推流端在自己所在房间内，才会收到该用户的网络质量。 2.14.0 至 2.21.1 版本：

自身只要推流或拉流，就会收到自身的网络质量回调。 2. 当拉一条流时，推流端在自己所在房间内，就会收到该用户的网络质量。 2.22.0 及以上版本：
自身只要推流或拉流，就会收到自身的网络质量回调。 2. 当拉一条流时，推流端在自己所在房间内，就会收到该用户的网络质量。
预估远端推流用户的网络情况，如果远端推流用户心跳丢失 1 次，回调其网络质量为 unknown；如果远端推流用户心跳丢失达到 3 次，回调其网络质量为 die。

业务场景：当开发者希望分析链路上的网络情况，或想要了解本地和远端用户的网络状况。
通知时机：调用 [startPublishingStream] 推流或 [startPlayingStream] 拉流后触发。

支持版本：2.10.0 及以上。

enableCustomVideoCapture

enableCustomVideoCapture(enable: boolean, channel: ZegoPublishChannel): void

开始或停止自定义视频采集，支持设置其他通道的推流。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启
channel	ZegoPublishChannel	推流通道

详情

enable 为 "true" 时开启视频自定义采集，为 "false" 时关闭视频自定义采集。

业务场景：开发者开发的 App使用了第三方美颜厂商的美颜 SDK，直播非摄像头采集的数据等。
默认值：没有调用该函数时，默认关闭自定义视频采集。
调用时机：[createEngine] 之后，调用 [startPreview]、[startPublishingStream]、[createRealTimeSequentialDataManager] 之前。如果需要修改配置，请先调用 [logoutRoom] 登出房间。
相关回调：当开发者开启自定义采集时，通过调用 [setCustomVideoCaptureHandler] 可设置接收自定义采集启停事件通知。

支持版本：1.9.0 及以上。
注意事项：自定义视频渲染功能可以与自定义视频采集功能同时使用，但当两者同时开启时，自定义视频渲染的本地采集帧回调将不会再被触发，开发者应该直接在自定义视频采集源里直接获取采集视频帧。

enableExternalRender

enableExternalRender(enable: boolean): void

开启/关闭外部渲染，当开启外部渲染时，SDK 内部将不再进行数据渲染。

Declared in ZegoExpressEngine.js

名称	类型	描述
enable	boolean	true-开启/false-关闭

registerCustomVideoCapturePlugin

registerCustomVideoCapturePlugin(plugin: Number, channel: ZegoPublishChannel, config: Object): void

注册自定义视频采集插件

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	Number	视频采集插件
channel	ZegoPublishChannel	推流通道
config	Object	自定义配置. type-插件类型（1-合图/0-默认）is_render-是否渲染, 默认开启（true-开启/false-关闭）渲染。

unregisterCustomVideoCapturePlugin

unregisterCustomVideoCapturePlugin(plugin: Number): void

注销自定义视频采集插件。

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	Number	视频采集插件

enableCameraVideoDataCapturePlugin

enableCameraVideoDataCapturePlugin(enable: boolean, channel: ZegoPublishChannel): void

开启/关闭摄像头视频数据采集插件

Declared in ZegoExpressEngine.js

名称	类型	描述
enable	boolean	开启/关闭
channel	ZegoPublishChannel	推流通道

getCameraVideoDataCapturePlugin

getCameraVideoDataCapturePlugin(channel: ZegoPublishChannel): number

获取摄像头视频数据采集插件，需要先调用接口 [enableCameraVideoDataCapturePlugin] 开启才能使用。

Declared in ZegoExpressEngine.js

名称	类型	描述
channel	ZegoPublishChannel	推流通道

返回值

插件的 ID

setCustomVideoCaptureFillMode

setCustomVideoCaptureFillMode(mode: ZegoViewMode, channel: ZegoPublishChannel): void

设置自定义视频采集画面缩放填充模式，支持其他路推流

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
mode	ZegoViewMode	画面填充缩放模式
channel	ZegoPublishChannel	推流通道

详情

当开启自定义视频采集功能时，可使用此接口设置视频画面的缩放填充模式。

业务场景：如自定义采集分辨率、SDK编码分辨率不一致时，SDK将根据填充模式处理视频帧，调整为编码分辨率。
调用时机：调用 [sendCustomVideoCaptureRawData]、[sendCustomVideoCaptureTextureData]、[sendCustomVideoCapturePixelBuffer]、[sendCustomVideoCaptureEncodedData] 之前。

支持版本：1.10.0 及以上。

setCustomVideoCaptureRegionOfInterest

  setCustomVideoCaptureRegionOfInterest(rectList: Array<ZegoRoiRect>, rectCount: number, channel: ZegoPublishChannel): void

设置指定推流通道自定义视频采集编码器的感兴趣区域（ROI）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
rectList	Array<ZegoRoiRect>	ROI 矩形区域列表，当前最多支持 6 个区域。
rectCount	number	ROI 矩形区域列表长度（矩形的数量）。
channel	ZegoPublishChannel	推流通道

详情

可通过此函数设置编码器的感兴趣区域（ROI）。

调用时机：在收到 [onStart] 回调后调用。

支持版本：2.16.0 及以上。
使用限制：目前仅特定的视频编码器支持此功能，使用前请联系技术支持。
注意事项：此函数目前为实验性功能，使用前请联系技术支持。

enableCustomVideoProcessing

enableCustomVideoProcessing(enable: boolean, channel: ZegoPublishChannel): void

自定义视频前处理配置开关，支持指定推流通道号。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启。是否必填：是。
channel	ZegoPublishChannel	推流通道。是否必填：否。默认值：主推流通道。

详情

当开发者开启自定义前处理时，通过调用 [setCustomVideoProcessHandler] 可设置设置自定义视频前处理回调。

业务场景：开发者自行采集视频数据或获取到 SDK 采集的视频数据后，若 SDK 自带的基础美颜和水印功能无法满足开发者需求时（例如美颜效果无法达到预期），可以结合 ZegoEffects SDK 对视频进行一些特殊处理，例如美颜、添加挂件等，该过程即为自定义视频前处理。
默认值：默认关闭。
调用时机：必须在调用 [startPreview]、[startPublishingStream]、[createRealTimeSequentialDataManager] 之前设置。如果需要修改配置，请先调用 [logoutRoom] 登出房间，否则不会生效。
相关接口：调用 [setCustomVideoProcessHandler] 函数可设置设置自定义视频前处理回调。

支持版本：2.2.0 及以上（Android/iOS/macOS原生），2.4.0 及以上（Windows/macOS C++）。
使用限制：无。

registerCustomVideoProcessPlugin

registerCustomVideoProcessPlugin(plugin: number, channel: ZegoPublishChannel): void

注册自定义视频前处理插件

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	number	视频前处理插件
channel	ZegoPublishChannel	推流通道

setCustomVideoProcessCutRegion

  setCustomVideoProcessCutRegion(left: number, top: number, right: number, bottom: number, channel: ZegoPublishChannel): void

设置自定义视频前处理裁剪区域

Declared in ZegoExpressEngine.js

名称	类型	描述
left	number	矩形水平轴左边的值
top	number	矩形竖直轴顶部的值
right	number	矩形水平轴右边的值
bottom	number	矩形竖直轴底部的值
channel	ZegoPublishChannel	推流通道

enableCustomAudioCaptureProcessing

enableCustomAudioCaptureProcessing(enable: boolean, config: ZegoCustomAudioProcessConfig): void

开启本地采集自定义音频处理（耳返前）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启本地采集自定义音频处理。
config	ZegoCustomAudioProcessConfig	自定义音频处理配置。

详情

开启自定义音频处理（耳返前），开发者可以通过 [onProcessCapturedAudioData] 收到本地采集的音频帧，并且可以对音频数据进行修改。

业务场景：如果开发者想在采集音频数据后或拉取远端音频数据渲染前，通过自定义处理实现特殊功能（例如变声、美声等）时。
调用时机：需要在 [startPublishingStream]、 [startPlayingStream]、 [startPreview]、 [createMediaPlayer]、 [createAudioEffectPlayer] 和 [createRealTimeSequentialDataManager] 之前调用才有效。

支持版本：1.13.0 及以上。
使用限制：无。

registerCustomAudioProcessPlugin

registerCustomAudioProcessPlugin(plugin: Number, type: ZegoCustomAudioProcessConfigureType): void

注册自定义音频处理插件。

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	Number	自定义音频处理插件。
type	ZegoCustomAudioProcessConfigureType	自定义音频处理配置类型。

unregisterCustomAudioProcessPlugin

unregisterCustomAudioProcessPlugin(type: ZegoCustomAudioProcessConfigureType): void

注销自定义音频处理插件。

Declared in ZegoExpressEngine.js

名称	类型	描述
type	ZegoCustomAudioProcessConfigureType	自定义音频处理配置类型。

enableCustomAudioCaptureProcessingAfterHeadphoneMonitor

enableCustomAudioCaptureProcessingAfterHeadphoneMonitor(enable: boolean, config: ZegoCustomAudioProcessConfig): void

开启本地采集自定义音频处理（耳返后）。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启本地采集自定义音频处理。
config	ZegoCustomAudioProcessConfig	自定义音频处理配置。

详情

开启自定义音频处理（耳返后），开发者可以通过 [onProcessCapturedAudioDataAfterUsedHeadphoneMonitor] 收到本地采集的音频帧，并且可以对音频数据进行修改。

业务场景：如果开发者想在采集音频数据后或拉取远端音频数据渲染前，通过自定义处理实现特殊功能（例如变声、美声等）时。
调用时机：需要在 [startPublishingStream]、 [startPlayingStream]、 [startPreview]、 [createMediaPlayer]、 [createAudioEffectPlayer] 和 [createRealTimeSequentialDataManager] 之前调用才有效。

支持版本：1.13.0 及以上。
使用限制：无。

enableCustomAudioIO

enableCustomAudioIO(enable: boolean, config?: ZegoCustomAudioConfig, channel: ZegoPublishChannel): void

开启自定义音频 IO 功能，支持其他路推流，支持 PCM 、AAC 格式数据。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
enable	boolean	是否开启自定义音频 IO。
config	ZegoCustomAudioConfig	自定义音频 IO 的配置。
channel	ZegoPublishChannel	指定要开启自定义音频 IO 的推流通道。

详情

开启自定义音频 IO 功能，支持 PCM 、AAC 格式数据。

业务场景：如果开发者想在采集音频数据后或拉取远端音频数据渲染前，通过自定义处理实现特殊功能（例如变声、美声等）时。
调用时机：需要在 [startPublishingStream]、 [startPlayingStream]、 [startPreview]、 [createMediaPlayer]、 [createAudioEffectPlayer] 和 [createRealTimeSequentialDataManager] 之前调用才有效。

支持版本：1.10.0 及以上。
使用限制：无。

registerCustomAudioCapturePlugin

registerCustomAudioCapturePlugin(plugin: Number, channel: ZegoPublishChannel): void

注册自定义音频采集插件。

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	Number	音频采集插件
channel	ZegoPublishChannel	推流通道

unregisterCustomAudioCapturePlugin

unregisterCustomAudioCapturePlugin(plugin: Number): void

注销自定义音频采集插件。

Declared in ZegoExpressEngine.js

名称	类型	描述
plugin	Number	音频采集插件

createCopyrightedMusic

createCopyrightedMusic(): ZegoCopyrightedMusic

创建版权音乐实例对象。

Declared in ZegoExpressEngine.js

创建版权音乐实例对象。

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

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

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

destroyCopyrightedMusic

destroyCopyrightedMusic(copyrightedMusic: ZegoCopyrightedMusic): void

销毁版权音乐实例对象。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
copyrightedMusic	ZegoCopyrightedMusic	版权音乐实例对象。

详情

销毁版权音乐实例对象。

调用时机：在销毁引擎 [destroyEngine] 之前。

支持版本：2.13.0 及以上。

onDownloadProgressUpdate

onDownloadProgressUpdate(resourceID: string, progressRate: number): void

加载歌曲或伴奏进度回调。

Declared in ZegoExpressEngine.js

名称	类型	描述
resourceID	string	触发此次回调的歌曲或伴奏对应的资源 ID。
progressRate	number	加载进度。

onCurrentPitchValueUpdate

onCurrentPitchValueUpdate(resourceID: string, currentDuration: number, pitchValue: number): void

实时音高线回调。

Declared in ZegoExpressEngine.js

名称	类型	描述
resourceID	string	触发此次回调的歌曲或伴奏对应的资源 ID。
currentDuration	number	当前播放进度。
pitchValue	number	实时音高准确程度或值。

getScreenCaptureSources

  getScreenCaptureSources(thumbnailWidth: number, thumbnailHeight: number, iconWidth: number, iconHeight: number): promise<Array<ZegoScreenCaptureSourceInfo>>

获取屏幕列表或屏幕中的窗口列表。

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
thumbnailWidth	number	获取窗口所对应的缩略图宽度，缩略图可用于绘制在窗口选择界面上。（单位为像素）
thumbnailHeight	number	获取窗口所对应的缩略图高度，缩略图可用于绘制在窗口选择界面上。（单位为像素）
iconWidth	number	获取程序所对应的图标的宽度。（单位为像素）
iconHeight	number	获取程序所对应的图标的高度。（单位为像素）

详情

获取屏幕列表或屏幕中的窗口列表。

支持版本：3.1.0 及以上
使用限制：只适用于 Windows/macOS 系统

返回值

采集源对象信息列表。

createScreenCaptureSource

createScreenCaptureSource(sourceId: number, sourceType: ZegoScreenCaptureSourceType): ZegoScreenCaptureSource

创建屏幕采集源

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
sourceId	number	指定的屏幕 ID 或窗口 ID。
sourceType	ZegoScreenCaptureSourceType	指定的屏幕源类型。

详情

根据提供的源的 ID 和源的类型创建屏幕采集源对象。

业务场景：需要对屏幕或窗口有录制和分享等业务时使用。
调用时机：需要在 [createEngine] 之后调用。
平台差异：仅支持 Windows 和 macOS。

支持版本：3.1.0 及以上。

返回值

屏幕采集源对象，超过最大数量限制后将返回 null

destroyScreenCaptureSource

destroyScreenCaptureSource(source: ZegoScreenCaptureSource): void

销毁屏幕采集源对象

Declared in ZegoExpressEngine.js

参数

名称	类型	描述
source	ZegoScreenCaptureSource	需要销毁的屏幕采集源对象

详情

销毁 [ZegoScreenCaptureSource] 屏幕采集源对象。

业务场景：不再需要使用屏幕采集功能时，可通过此函数销毁 [createScreenCaptureSource] 函数创建出来的实例对象。
调用时机：当需要销毁屏幕采集源对象时。
平台差异：仅支持 Windows 和 macOS。

支持版本：3.1.0 及以上。
使用限制：销毁后，开发者需要自行释放持有的 [ZegoScreenCaptureSource] 实例对象，并且销毁后也不要再调用此实例对象的函数。

ZegoMediaPlayer

Declared in ZegoExpressMediaPlayer.js

方法

loadResource

loadResource(path: string): Promise<Object>

加载本地或者网络媒体资源。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
path	string	本地资源路径或网络资源的 URL，不能传入 null 或 ""。Android 可通过 Uri 方式进行传参。

详情

加载媒体资源。

业务场景：开发者可以将可传本地资源的绝对路径或者网络资源的 URL 传入进行加载。
调用时机：在已经初始化引擎 [createEngine] 且创建媒体播放器 [createMediaPlayer] 之后可以调用。
相关接口：也可通过 [loadResourceWithPosition] 或 [loadResourceFromMediaData] 函数加载资源。

支持版本：1.3.4 及以上。
注意事项：如果该媒体播放器已经加载资源或者正在播放，请先调用 [stop] 接口停止播放，然后再调用接口加载媒体资源，否则无法加载成功。

返回值

加载媒体资源结果回调。

loadResourceWithPosition

loadResourceWithPosition(path: string, startPosition: number): Promise<Object>

加载本地或者网络媒体资源，并指定开始位置。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
path	string	本地资源路径或网络资源的 URL，不能传入 null 或 ""。Android 可通过 Uri 方式进行传参。
startPosition	number	开始播放的进度。

详情

加载媒体资源，同时可指定开始播放的进度,单位毫秒。

业务场景：开发者可以将可传本地资源的绝对路径或者网络资源的 URL 传入进行加载。
调用时机：在已经初始化引擎 [createEngine] 且创建媒体播放器 [createMediaPlayer] 之后可以调用。
相关接口：也可通过 [loadResource] 或 [loadResourceFromMediaData] 函数加载资源。

支持版本：2.14.0 及以上。
注意事项：1.当 startPosition 超过播放总时长，将从头开始播放。 2.如果该媒体播放器已经加载资源或者正在播放，请先调用 [stop] 接口停止播放，然后再调用接口加载媒体资源，否则无法加载成功。

返回值

加载媒体资源结果回调。

loadCopyrightedMusicResourceWithPosition

loadCopyrightedMusicResourceWithPosition(resourceID: string, startPosition: number): Promise<Object>

加载版权音乐资源。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
resourceID	string	从版权音乐模块获取的资源ID。
startPosition	number	开始播放的进度。

详情

加载版权音乐资源，同时可指定开始播放的进度,单位毫秒。

业务场景：开发者可以将可传版权音乐的资源ID进行加载。
调用时机：在已经初始化引擎 [createEngine] 且创建媒体播放器 [createMediaPlayer] 之后可以调用。

支持版本：2.14.0 及以上。
注意事项：1.当 startPosition 超过播放总时长，将从头开始播放。 2.如果该媒体播放器已经加载资源或者正在播放，请先调用 [stop] 接口停止播放，然后再调用接口加载媒体资源，否则无法加载成功。

返回值

加载媒体资源结果回调。

start

start(): void

开始播放

Declared in ZegoExpressMediaPlayer.js

必须在加载资源完成后才能调用

stop

stop(): void

停止播放

Declared in ZegoExpressMediaPlayer.js

pause

pause(): void

暂停播放

Declared in ZegoExpressMediaPlayer.js

resume

resume(): void

恢复播放

Declared in ZegoExpressMediaPlayer.js

seekTo

seekTo(millisecond: number): Promise<Object>

设置指定的播放进度

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
millisecond	number	指定的播放进度的时间点

详情

单位为毫秒

返回值

设置指定的播放进度的结果通知

enableRepeat

enableRepeat(enable: boolean): void

是否重复播放

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
enable	boolean	重复播放标记，默认为 false

enableAux

enableAux(enable: boolean): void

是否将播放器的声音混入正在推的流中

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
enable	boolean	是否混音标记，默认为 false

详情

此接口仅会将媒体播放器声音混到主通道中

muteLocal

muteLocal(mute: boolean): void

是否静默本地播放

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
mute	boolean	本地静音标记，默认为 false。

详情

若开启了混音入流则推的流中仍然有声音，默认为 false。

setPlayerView

setPlayerView(view: ZegoView): void

设置播放器播放视频的视图

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
view	ZegoView	视频渲染的画布对象

setVolume

setVolume(volume: number): void

设置播放器音量，会同时设置本地播放音量和推流音量

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
volume	number	范围为 0 ~ 200，默认为 60。

setPlayVolume

setPlayVolume(volume: number): void

设置播放器本地播放音量

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
volume	number	范围为 0 ~ 200，默认为 60。

setPublishVolume

setPublishVolume(volume: number): void

设置播放器推流音量

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
volume	number	范围为 0 ~ 200，默认为 60。

setProgressInterval

setProgressInterval(millisecond: number): void

设置播放进度回调间隔

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
millisecond	number	播放进度回调间隔时间，单位为毫秒

详情

可通过此函数控制 [onMediaPlayerPlayingProgress] 的回调频率，当设置回调间隔为 0 时，停止回调。默认回调间隔为 1s 回调不会严格按照设定的回调间隔值返回，而是以处理音频帧或者视频帧的频率来判断是否需要回调

getPlayVolume

getPlayVolume(): number

获取当前媒体播放器本地播放的音量，范围为 0 ~ 200，默认值为 60

Declared in ZegoExpressMediaPlayer.js

当前音量

getPublishVolume

getPublishVolume(): number

获取当前媒体播放器推流的音量，范围为 0 ~ 200，默认值为 60

Declared in ZegoExpressMediaPlayer.js

当前音量

getTotalDuration

getTotalDuration(): number

获取媒体资源的总进度

Declared in ZegoExpressMediaPlayer.js

必须在加载资源完成后才能调用，否则返回值为 0

单位为毫秒

getCurrentProgress

getCurrentProgress(): number

获取当前播放进度

Declared in ZegoExpressMediaPlayer.js

必须在加载资源完成后才能调用，否则返回值为 0

当前播放进度

getCurrentRenderingProgress

getCurrentRenderingProgress(): number

获取当前渲染进度

Declared in ZegoExpressMediaPlayer.js

必须在加载资源完成后才能调用，否则返回值为 0

当前渲染进度

getAudioTrackCount

getAudioTrackCount(): number

获取播放文件的音轨个数

Declared in ZegoExpressMediaPlayer.js

音轨个数

setAudioTrackIndex

setAudioTrackIndex(index: number): void

设置播放文件的音轨

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
index	number	音轨序号，可以通过 [getAudioTrackCount] 获取音轨个数

getCurrentState

getCurrentState(): ZegoMediaPlayerState

获取当前播放状态

Declared in ZegoExpressMediaPlayer.js

当前播放器状态

getIndex

getIndex(): number

获取媒体播放器的序号

Declared in ZegoExpressMediaPlayer.js

获取媒体播放器索引。

调用时机：在 [createMediaPlayer] 之后可调用。

使用限制：无。

媒体播放器索引。

takeSnapshot

takeSnapshot(): Promise<Object>

对媒体播放器当前播放画面进行截图

Declared in ZegoExpressMediaPlayer.js

只有在调用 [setPlayerCanvas] 设置了显示控件，以及播放状态的情况下，才能正常截图

截图的结果（错误码）以及经过 base64 编码后的 JPG 图片的字符串

enableSoundLevelMonitor

enableSoundLevelMonitor(enable: boolean, millisecond: number): void

是否开启声浪监听。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
enable	boolean	是否开启监听，true 开启，false 关闭。
millisecond	number	声浪的监听时间周期，单位为毫秒，取值范围 [100, 3000]。

详情

开启或关闭声浪监听。

调用时机：初始化引擎 [createEngine] 并创建媒体播放器 [createMediaPlayer] 之后调用。
相关回调：开启后可以通过 [onMediaPlayerSoundLevelUpdate] 回调监听声浪更新。

支持版本：2.15.0 及以上。
使用限制：无。

enableFrequencySpectrumMonitor

enableFrequencySpectrumMonitor(enable: boolean, millisecond: number): void

是否开启频谱监听。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
enable	boolean	是否开启监听，true 开启，false 关闭。
millisecond	number	频谱的监听时间周期，单位为毫秒，取值范围 [10, 3000]。注意在 3.19.0 及更老版本上，取值范围为 [100, 3000]

详情

开启或关闭频谱监听。

调用时机：初始化引擎 [createEngine] 并创建媒体播放器 [createMediaPlayer] 之后调用。
相关回调：开启后可以通过 [onMediaPlayerFrequencySpectrumUpdate] 回调监听声浪更新。

支持版本：2.15.0 及以上。
使用限制：无。

getMediaInfo

getMediaInfo(): ZegoMediaPlayerMediaInfo

获取媒体文件视频分辨率等媒体信息。

Declared in ZegoExpressMediaPlayer.js

获取媒体文件视频分辨率等媒体信息。

调用时机：初始化引擎 [createEngine] 并创建媒体播放器 [createMediaPlayer] 之后调用。

支持版本：3.6.0 及以上。
使用限制：无。

媒体文件信息。

enablePublishVideo

enablePublishVideo(enable: boolean, channel: number): void

是否将播放器的视频混入正在推的流中

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
enable	boolean	是否推视频
channel	number	channel

getCustomVideoCapturePlugin

getCustomVideoCapturePlugin(): number

获取播放器的自定义视频采集插件

Declared in ZegoExpressMediaPlayer.js

插件的 ID

registerCustomAudioProcessPlugin

registerCustomAudioProcessPlugin(plugin: Number): void

注册自定义的媒体播放器音频数据处理插件。

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
plugin	Number	自定义的媒体播放器音频数据处理插件。

unregisterCustomAudioProcessPlugin

unregisterCustomAudioProcessPlugin(): void

注销自定义的媒体播放器音频数据处理插件。

Declared in ZegoExpressMediaPlayer.js

enableLiveAudioEffect

enableLiveAudioEffect(enable: boolean, mode: ZegoLiveAudioEffectMode): void

开启现场音效。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
enable	boolean	是否开启现场音效。
mode	ZegoLiveAudioEffectMode	现场音效模式。

详情

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

业务场景：一般用于语聊房、K 歌场景下，增强伴奏的现场音效。
调用时机：在已经初始化引擎 [createEngine] 且创建媒体播放器 [createMediaPlayer] 之后可以调用。

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

enableLocalCache

enableLocalCache(enable: boolean, cacheDir: string): void

开启本地缓存 http/https 网络资源。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
enable	boolean	是否开启本地缓存。
cacheDir	string	缓存目录。如果留空会使用 SDK 内部指定的目录。

详情

当播放 http/https 网络资源时，开启本地缓存后，会将网络资源保存到本地，并通过 [onMediaPlayerLocalCache] 将缓存信息回调出来。

调用时机：在已经初始化引擎 [createEngine] 且创建媒体播放器 [createMediaPlayer] 之后可以调用。在 [loadResource] 之后或者播放过程中调用，会在下一次播放生效。

支持版本：3.12.0 及以上。
注意事项：只支持 http/https 单文件类型网络资源，如果播放过程中有 [seekTo] 操作，缓存会失败。

onMediaPlayerStateUpdate

onMediaPlayerStateUpdate(state: ZegoMediaPlayerState, errorCode: number): void

媒体播放器播放状态回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
state	ZegoMediaPlayerState	播放器状态。
errorCode	number	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

媒体播放器播放状态回调。

通知时机：当媒体播放器的播放状态改变时会触发此回调。

支持版本：1.3.4 及以上。
使用限制：无。

onMediaPlayerNetworkEvent

onMediaPlayerNetworkEvent(networkEvent: ZegoMediaPlayerNetworkEvent): void

媒体播放器网络状态事件回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
networkEvent	ZegoMediaPlayerNetworkEvent	网络状态事件。

详情

媒体播放器网络状态事件回调。

通知时机：当媒体播放器在播放网络资源时，当缓存数据的状态改变时会触发此回调。
相关接口：[setNetWorkBufferThreshold]。

支持版本：1.3.4 及以上。
使用限制：只有在播放网络资源时才会触发该回调。

onMediaPlayerPlayingProgress

onMediaPlayerPlayingProgress(millisecond: number): void

播放器播放进度回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
millisecond	number	进度，单位为毫秒。

详情

媒体播放器播放进度回调。通过调用 [setProgressInterval] 可以设置回调间隔时间。当设置回调间隔为 0 时，停止回调。默认回调间隔为 1 秒。

通知时机：当媒体播放器开始播放资源后会触发此回调。
相关接口：[setProgressInterval]。

支持版本：1.3.4 及以上。
使用限制：无。

onMediaPlayerRenderingProgress

onMediaPlayerRenderingProgress(millisecond: number): void

播放器渲染进度回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
millisecond	number	进度，单位为毫秒。

详情

媒体播放器渲染进度回调。通过调用 [setProgressInterval] 可以设置回调间隔时间。当设置回调间隔为 0 时，停止回调。默认回调间隔为 1 秒。

通知时机：当媒体播放器开始播放资源后会触发此回调。
相关接口：[setProgressInterval]。

支持版本：3.8.0 及以上。
使用限制：无。

onMediaPlayerVideoSizeChanged

onMediaPlayerVideoSizeChanged(width: number, height: number): void

媒体播放器播放视频分辨率改变事件回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
width	number	宽。
height	number	高。

详情

媒体播放器播放视频分辨率改变事件回调。

通知时机：当媒体播放器在播放视频资源时，开始播放以及视频的分辨率变化时会触发此回调。

支持版本：3.11.0 及以上。

onMediaPlayerLoadResource

onMediaPlayerLoadResource(errorCode: number, seq: number): void

媒体播放器加载资源结果的通知。

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
errorCode	number	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
seq	number	调用接口的序列号。

onMediaPlayerVideoData

onMediaPlayerVideoData(videoParam: ZegoVideoFrameObject): void

媒体播放器视频数据回调。

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
videoParam	ZegoVideoFrameObject	视频帧参数。

onMediaPlayerRecvSEI

onMediaPlayerRecvSEI(data: ArrayBuffer): void

媒体次要信息回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
data	ArrayBuffer	SEI 内容。

详情

媒体次要信息回调。

通知时机：媒体播放器开始播放媒体文件时，如果解析到媒体文件中含有 SEI 时，将触发该回调。

支持版本：2.2.0 及以上。
使用限制：不适用于 WebGL。
注意事项：调用接口 [on] 注册该回调后该回调才生效。

onMediaPlayerSoundLevelUpdate

onMediaPlayerSoundLevelUpdate(soundLevel: number): void

声浪更新回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
soundLevel	number	声浪值，取值范围：[0.0, 100.0]（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

声浪更新回调。

通知时机：回调频率由 [EnableSoundLevelMonitor] 指定。
相关接口：监听此回调需要通过 [EnableSoundLevelMonitor] 开启。

支持版本：2.15.0 及以上。
注意事项：调用接口 [on] 注册后该回调才生效。

onMediaPlayerFrequencySpectrumUpdate

onMediaPlayerFrequencySpectrumUpdate(spectrumList: Array<number>): void

频谱更新回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
spectrumList	Array<number>	媒体播放器频谱值数组，频谱值范围为 [0-2^30]。

详情

频谱更新回调。

通知时机：回调频率由 [EnableFrequencySpectrumMonitor] 指定。
相关接口：监听此回调需要通过 [EnableFrequencySpectrumMonitor] 开启。

支持版本：2.15.0 及以上。
注意事项：调用接口 [on] 注册后该回调才生效。

onMediaPlayerFirstFrameEvent

onMediaPlayerFirstFrameEvent(event: ZegoMediaPlayerFirstFrameEvent): void

媒体播放器播放首帧回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
event	ZegoMediaPlayerFirstFrameEvent	首帧回调事件类型。

详情

开始播放首帧回调。

通知时机：媒体播放器开始播放时会产生此回调。
相关接口：需要调用 [setPlayerCanvas] 接口，给媒体播放器设置视图，才能收到视频首帧事件回调。

支持版本：3.5.0 及以上。
注意事项：调用 [on] 注册设置后该回调才生效。

onMediaPlayerLocalCache

onMediaPlayerLocalCache(errorCode: number, resource: string, cachedFile: string): void

媒体播放器本地缓存 http/https 网络资源后回调。

Declared in ZegoExpressMediaPlayer.js

参数

名称	类型	描述
errorCode	number	错误码。
resource	string	播放的资源
cachedFile	string	缓存的文件

详情

本地缓存 http/https 网络资源后回调。

通知时机：媒体播放器缓存 http/https 网络资源后会产生此回调。
相关接口：需要调用 [enableLocalCache] 接口。

支持版本：3.12.0 及以上。
注意事项：调用 [enableLocalCache] 接口设置后，且播放的是 http/https 网络资源时该回调才生效。

setVoiceChangerParam

deprecated

setVoiceChangerParam(audioChannel: ZegoMediaPlayerAudioChannel, param: ZegoVoiceChangerParam): void

【已废弃】设置变声的具体参数

Declared in ZegoExpressMediaPlayer.js

名称	类型	描述
audioChannel	ZegoMediaPlayerAudioChannel	要进行变声的声道
param	ZegoVoiceChangerParam	变声参数

已废弃

此函数在 3.15.0 版本及以上已废弃，请使用 [enableVoiceChanger] 函数代替。

ZegoScreenCaptureSource

Declared in ZegoExpressScreenCaptureSource.js

方法

updateCaptureSource

updateCaptureSource(sourceId: number, sourceType: ZegoScreenCaptureSourceType): void

更新屏幕采集源

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
sourceId	number	指定的屏幕 ID 或窗口 ID。
sourceType	ZegoScreenCaptureSourceType	指定的屏幕源类型。

详情

根据提供的源的 ID 和源的类型更新屏幕采集源对象。

业务场景：需要对屏幕或窗口有录制和分享等业务时使用。
调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS

startCapture

startCapture(): void

开始屏幕采集。

Declared in ZegoExpressScreenCaptureSource.js

开始屏幕采集。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。

stopCapture

stopCapture(): void

停止屏幕采集。

Declared in ZegoExpressScreenCaptureSource.js

停止屏幕采集。

支持版本：3.1.0 及以上。

getCaptureSourceRect

getCaptureSourceRect(): ZegoRect

获取屏幕采集源的矩形。

Declared in ZegoExpressScreenCaptureSource.js

获取屏幕采集源的矩形。

支持版本：3.6.0 及以上
使用限制：开始采集 [startScreenCapture] 之后调用，只适用于 Windows/macOS 系统。

采集资源的矩形信息

updateCaptureRegion

updateCaptureRegion(rect: ZegoRect): void

更新屏幕采集的区域。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
rect	ZegoRect	待采集区域相对于整个屏幕或窗口的位置。

详情

更新屏幕采集的区域。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS 系统

updatePublishRegion

updatePublishRegion(rect: ZegoRect): void

更新屏幕采集的推流区域。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
rect	ZegoRect	待推流区域相对于采集画面左上角的位置，实际采集画面尺寸可以通过 [onAvailableFrame] 获取

详情

更新屏幕采集的推流区域。

调用时机：更新屏幕采集源 [updateScreenCaptureSource] 之后。

支持版本：3.8.0 及以上。
使用限制：每次更新屏幕采集源 [updateScreenCaptureSource] 时会清空区域，需要重新设置，只适用于 Windows/macOS 系统。
注意事项：设置的区域不能超过 [onAvailableFrame] 返回的尺寸，否则会设置失败并推流原始画面。推流区域失效会通过 [onExceptionOccurred] 通知。

setExcludeWindowList

setExcludeWindowList(list: Array<number>): void

设置过滤的窗口列表。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
list	Array<number>	过滤窗口的 ID 列表。

详情

指定窗口列表，在采集屏幕时将这些窗口过滤，不在画面中显示。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS

enableWindowActivate

enableWindowActivate(active: boolean): void

是否激活窗口提升至前台显示。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
active	boolean	是否激活窗口。true 为激活窗口，false 不激活窗口，默认 true。

详情

在采集目标为窗口的情况下，初次采集时，设置是否激活窗口提升至前台显示。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS

enableCursorVisible

enableCursorVisible(visible: boolean): void

设置是否显示光标

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
visible	boolean	是否显示光标。true 为显示光标，false 不显示光标，默认 false。

详情

设置是否显示光标。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS

enableHightLight

enableHightLight(enable: boolean, config: ZegoLayerBorderConfig): void

设置是否高亮采集区域

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
enable	boolean	是否高亮采集区域。true 为高亮，false 不高亮，默认 false。
config	ZegoLayerBorderConfig	高亮采集区域边框配置。

详情

设置是否高亮采集区域。

调用时机：在创建屏幕采集实例 [createScreenCaptureSource] 之后。

支持版本：3.21.0 及以上。
使用限制：只适用于 Windows/macOS

enableAudioCapture

enableAudioCapture(enable: boolean, audioParam: ZegoAudioFrameParam): void

窗口采集时是否采集窗口进程的声音

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
enable	boolean	是否采集声音。true 为采集，false 不采集，默认 false。
audioParam	ZegoAudioFrameParam	音频采集参数。

详情

采窗口采集时是否采集窗口进程的声音。

调用时机：在启动采集 [startScreenCapture] 之前。[setAudioSource] 设置采集源为 ZegoAudioSourceTypeCustom，并且屏幕采集推流通道相同。

支持版本：3.13.0 及以上。
使用限制：只适用于 Windows 10 及以上版本

getIndex

getIndex(): number

获取屏幕采集源索引。

Declared in ZegoExpressScreenCaptureSource.js

屏幕采集源索引。

onExceptionOccurred

onExceptionOccurred(exceptionType: ZegoScreenCaptureSourceExceptionType): void

屏幕采集异常通知

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
exceptionType	ZegoScreenCaptureSourceExceptionType	采集源异常类型。

详情

屏幕采集错误通知。

通知时机：屏幕开始采集后产生异常会触发此回调。

支持版本：3.1.0 及以上。
使用限制：只适用于 Windows/macOS。
注意事项：调用接口 [on] 注册后该回调才生效。

onCaptureTypeExceptionOccurred

  onCaptureTypeExceptionOccurred(sourceType: ZegoScreenCaptureSourceType, exceptionType: ZegoScreenCaptureSourceExceptionType): void

屏幕采集采集源异常通知

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
sourceType	ZegoScreenCaptureSourceType	采集源类型。
exceptionType	ZegoScreenCaptureSourceExceptionType	采集源异常类型。

详情

屏幕采集采集源异常通知。

通知时机：屏幕开始采集后产生异常会触发此回调。

支持版本：3.21.0 及以上。
使用限制：只适用于 Windows/macOS。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

onWindowStateChanged

onWindowStateChanged(windowState: ZegoScreenCaptureWindowState, windowRect: ZegoRect): void

采集目标窗口状态发生改变。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
windowState	ZegoScreenCaptureWindowState	采集的窗口状态。
windowRect	ZegoRect	采集的窗口矩形。

支持版本：3.4.0 及以上。
使用限制：只适用于 Windows/macOS
注意事项：调用接口 [on] 注册后该回调才生效。

onRectChanged

onRectChanged(captureRect: ZegoRect): void

采集区域发生改变。

Declared in ZegoExpressScreenCaptureSource.js

参数

名称	类型	描述
captureRect	ZegoRect	采集的区域矩形。

支持版本：3.7.0 及以上。
使用限制：只适用于 Windows/macOS
注意事项：调用接口 [on] 注册后该回调才生效。