Class

2026-05-26


ZIMAudio	ZIMAudioEventHandler

ZIMAudio

详情

ZIMAudio SDK 主类。

方法

getVersion

static

getVersion

static getVersion(): string

获取 SDK 版本号。

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

调用时机：任意时刻。

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

SDK 版本号。

setAdvancedConfig

static

setAdvancedConfig

static setAdvancedConfig(key: string, value: string): void

设置 SDK 进阶配置，使用前请先联系 ZEGO 技术支持。

参数

名称	类型	描述
key	string	进阶配置的 Key
value	string	进阶配置的 Value

详情

当 SDK 的默认行为不能满足开发者使用场景时，可以调用该 API 用于实现开发者自定义的进阶配置。

调用时机：必须在 [init] 之前调用，否则只能在下一次 [init] 之后才会生效。

支持版本：1.0.0 及以上。
使用限制：无。
注意事项：使用前请先联系 ZEGO 技术支持。

getInstance

static

getInstance

static getInstance(): ZIMAudio

获取 SDK 单例对象。

使用 ZIMAudio SDK 时，开发者应直接调用该 API 获取内部单例对象，而无需自行创建并且维护对象。

调用时机：任意时刻。

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

SDK 单例对象，用于后续的 API 调用。

init

abstract init(license: string): void

初始化 ZIMAudio SDK

参数

名称	类型	描述
license	string	鉴权信息。开发者如果没有通过服务端 API 获取到的情况下，可以传入空字符串，但后续使用部分需要鉴权的功能时会受限。

详情

使用 ZIMAudio SDK 的其他功能性接口时，必须先调用此 API 进行初始化。

调用时机：调用其他 API 之前调用。

支持版本：1.0.0 及以上。
使用限制：当不传入鉴权信息或者鉴权信息有误时，SDK 的初始化能够正常进行，但后续使用部分需要鉴权的功能时会受限。
注意事项：无。

uninit

abstract uninit(): void

反初始化 ZIMAudio SDK

在不需要再使用 ZIMAudio SDK 时，可以调用此 API 进行反初始化以释放内存资源。

调用时机：任意时机。若反初始化 SDK 之前录制或播放功能没有停止，则此时会全部停止。

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

on

abstract on<K extends keyof ZIMAudioEventHandler>(type: K, listener: ZIMAudioEventHandler[K]): void

参数

名称	类型	描述
type	K	事件类型。
listener	ZIMAudioEventHandler[K]	事件产生后的自定义回调方法。

支持版本：1.0.0 及以上。

off

abstract off<K extends keyof ZIMAudioEventHandler>(type: K): void

取消注册 Audio 事件通知回调

参数

名称	类型	描述
type	K	事件类型。

支持版本：1.0.0 及以上。

enableANS

abstract enableANS(enable: boolean): void

开/关噪声抑制

参数

名称	类型	描述
enable	boolean	是否开启噪声抑制；true 表示开启噪声抑制；false 表示关闭噪声抑制

详情

开启该功能后，可以使人声更加清晰。此功能对持续性的噪声（例如下雨声等白噪音）抑制效果较好。

业务场景：当需要抑制噪声以提高录制音频的人声质量和用户体验时，可以开启此功能。
调用时机：在 [init] 之后的任意时机调用。

支持版本：1.0.0 及以上。
注意事项：此 API 只有在鉴权在合法的使用期限内，或者鉴权信息里允许使用了之后才能够正常调用；否则将会报错鉴权已过期或不支持该特性。
使用限制：无。

enableAGC

abstract enableAGC(enable: boolean): void

开/关自动增益控制

参数

名称	类型	描述
enable	boolean	是否开启自动增益控制；true 表示开启；false 表示关闭

详情

开启该功能后，SDK 能够自动调节麦克风音量，适应远近拾音，保持音量稳定。

业务场景：当需要保障音量稳定性以提高录制音频的人声质量和用户体验时，可以开启此功能。
调用时机：在 [init] 之后的任意时机调用。

支持版本：1.0.0 及以上。
注意事项：此 API 只有在鉴权在合法的使用期限内，或者鉴权信息里允许使用了之后才能够正常调用；否则将会报错鉴权已过期或不支持该特性。
使用限制：无。

setANSParam

abstract setANSParam(param: ZIMAudioANSParam): void

设置噪声抑制参数，当前仅包含噪声抑制模式

参数

名称	类型	描述
param	ZIMAudioANSParam	ANS 参数，包含 ANS 模式

详情

当使用 [enableANS] 开启了噪声抑制后，可通过此函数切换不同的噪声抑制模式以控制抑制噪声数据的程度。

业务场景：当默认的噪声抑制效果不符合预期时，可通过此函数调整噪声抑制模式。
默认值：未调用此函数时，默认的噪声抑制模式为 [Medium] 中等模式。
调用时机：在 [init] 之后的任意时机调用。

支持版本：1.0.0 及以上。
注意事项：此 API 只有在鉴权在合法的使用期限内，或者鉴权信息里允许使用了之后才能够正常调用；否则将会报错鉴权已过期或不支持该特性。
使用限制：仅在开启了噪声抑制功能后此函数设置的值才有效。

startRecord

abstract startRecord(config: ZIMAudioRecordConfig): void

开始录制音频文件

参数

名称	类型	描述
config	ZIMAudioRecordConfig	录制配置

详情

开始录制音频文件，SDK 将会向系统申请使用麦克风设备进行音频采集并写入到本地文件中。

业务场景：在用户需要发送语音消息之前，可以调用该 API 采集并生成发送所需要的语音文件，录制文件最终会保存到本地所设置的路径中。
调用时机：在 [init] 后。
相关接口：当调用此 API 开始录制后，SDK 会抛出 [onRecorderStarted] 通知。收到此回调通知之后开发者才能认为正式开始录制并更新 UI 的展示；在此之后，SDK 将会通过 [onRecorderProgress] 回调录制进度；异常情况下，SDK 也会可能抛出 [onRecorderFailed] 通知，请开发者酌情监听并做好当异常出现时对用户的提醒。

支持版本：1.0.0 及以上。
注意事项：请开发者使用此 API 之前确保已经获得了 App 的音频采集权限；当 SDK 开始进行录制时，会独占音频设备的使用权，因此此时会打断其他第三方 App 的播放等行为。
使用限制：录制相关的 API 不能与播放相关的 API 同时使用，同一时刻 SDK 内部只能进行录制或者进行播放。因此在需要开启录制之前，请开发者先主动停掉播放功能，否则在 SDK 开始录制之前也会停止播放相关的功能。

completeRecord

abstract completeRecord(): void

完成录制音频文件

完成录制音频文件。调用此 API 之后录制文件会生成到 [startRecord] 时传入的文件路径中并保存。

业务场景：在完成录制之后，开发者就可以将录制文件进行 IM 消息的发送。如传到 ZIM 的 AudioMessage 中进行语音消息的发送。
调用时机：[startRecord] 录制生效过程中。
相关接口：当调用此 API 并成功完成录制时，SDK 会抛出 [onRecorderCompleted] 通知。开发者必须收到此回调通知之后才能进行语音消息的发送。

支持版本：1.0.0 及以上。
注意事项：当开发者在 [startRecord] 录制生效的过程中一直没有调用该 API 来进行录制结束的情况下，那么当到了 [startRecord] 的最大录制时长后依然会完成录制并保存文件。完成录制后，SDK 将会释放对音频设备的占用。
使用限制：录制相关的 API 不能与播放相关的 API 同时使用，同一时刻 SDK 内部只能进行录制或者进行播放。

cancelRecord

abstract cancelRecord(): void

停止录制音频文件

中断录制音频文件。调用此 API 之后录制将会被停止，且 SDK 内部会把该本地文件同时删除。

业务场景：当录制过程中需要提前停止录制且不需要发送语音消息时，可以调用该 API 取消录制。
调用时机：[startRecord] 录制生效过程中。
相关接口：当调用此 API 取消录制后，SDK 会抛出 [onRecorderCancelled] 通知。开发者可以基于此回调通知进行相关资源清理和更新 UI 的展示。

支持版本：1.0.0 及以上。
注意事项：取消录制后，SDK 将会释放对音频设备的占用。
使用限制：录制相关的 API 不能与播放相关的 API 同时使用，同一时刻 SDK 内部只能进行录制或者进行播放。

isRecording

abstract isRecording(): boolean

获取是否正在录制

获取当前时刻 SDK 是否正在录制。

业务场景：当开发者在某一时刻有需要对录制状态进行获取和检测时，可以调用该 API 获取录制状态。
调用时机：在 [init] 之后的任意时机调用。

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

是否正在录制

setAudioRouteType

abstract setAudioRouteType(routeType: ZIMAudioRouteType): void

设置音频路由类型

参数

名称	类型	描述
routeType	ZIMAudioRouteType	音频路由类型，默认为声音从扬声器播出。

详情

设置音频路由类型以选择是否使用扬声器或者听筒播放音频。

业务场景：当开发者需要有选项让用户选择播放时的声音是从何处播出时，可以调用该 API 更改当前播放的音频路由类型。
调用时机：在 [init] 之后的任意时机调用。

支持版本：1.0.0 及以上。
注意事项：当用户当前使用了耳机进行音频播放的情况下，此 API 的设置将不生效。
使用限制：无。

startPlay

abstract startPlay(config: ZIMAudioPlayConfig): void

开始播放音频文件

参数

名称	类型	描述
config	ZIMAudioPlayConfig	播放参数

详情

开始播放音频文件。SDK 将会读取指定路径下的文件音频播放。

业务场景：在用户接收到了语音消息之后，可以调用该 API 对已经下载完成并已经保存到了本地的音频文件进行播放。
调用时机：在 [init] 后。
相关接口：当调用此 API 开始播放时，SDK 会抛出 [onPlayerStarted] 通知。收到此回调通知之后开发者才能认为正式开始播放并更新 UI 的展示；在此之后，SDK 将会通过 [onPlayerProgress] 回调播放进度；异常情况下，SDK 也会可能抛出 [onPlayerFailed] 通知，请开发者酌情监听并做好当异常出现时对用户的提醒。

支持版本：1.0.0 及以上。
注意事项：当 SDK 开始进行播放时，会独占音频设备的使用权，因此此时会打断其他第三方 App 的播放等行为，并不会与其他 App 的音频输出进行混音。
使用限制：播放相关的 API 不能与录制相关的 API 同时使用，同一时刻 SDK 内部只能进行录制或者进行播放。因此在需要开启播放之前，请开发者先确保此时没有正在使用录制功能，否则将会播放失败。

stopPlay

abstract stopPlay(): void

停止播放音频文件

停止 SDK 当前正在播放的音频。

业务场景：当播放过程中需要提前停止音频的播放时，可以调用该 API 进行停止播放。如用户需要立即播放下一段音频前，需要先停止上一段音频的播放；或者将要离开播放页面时也应该先停止当前的播放。
调用时机：[startPlay] 播放过程中。
相关接口：当调用此 API 停止播放后，SDK 会抛出 [onPlayerStopped] 通知。开发者可以基于此回调通知进行 UI 展示的更新。

支持版本：1.0.0 及以上。
注意事项：停止播放或者播放完成后，SDK 将会释放对音频设备的占用。
使用限制：播放相关的 API 不能与录制相关的 API 同时使用，同一时刻 SDK 内部只能进行录制或者进行播放。因此在需要开启播放之前，请开发者先确保此时没有正在使用录制功能，否则将会播放失败。

isPlaying

abstract isPlaying(): boolean

获取是否正在播放

获取当前时刻 SDK 是否正在播放。

业务场景：当开发者在某一时刻有需要对播放状态进行获取和检测时，可以调用该 API 获取播放状态。
调用时机：在 [init] 之后的任意时机调用。

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

是否正在播放

ZIMAudioEventHandler

详情

ZIMAudio SDK 事件处理类。

方法

onError

onError(errorInfo: ZIMAudioError): void

SDK 异常出错通知

参数

名称	类型	描述
errorInfo	ZIMAudioError

详情

当 SDK 内部检测到有异常出现时，会通过该回调抛出通知。

业务场景：用于方便开发者收集 SDK 问题并进行排查解决，建议对该回调进行监听并做合适的日志打印或者事件上报。

支持版本：1.0.0 及以上。
注意事项：不建议开发者监听到该回调之后做逻辑，只建议用于收集和排查问题。

onRecorderStarted

onRecorderStarted(): void

录制开始通知

当开发者调用 [startRecord] 之后，SDK 内部已经准备好音频设备即将开始录制时，会回调该通知。

业务场景：用于开发者更新 UI 使用。
相关接口：[startRecord] 调用之后会回调该通知。

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

onRecorderCompleted

onRecorderCompleted(totalDuration: number): void

录制完成通知

参数

名称	类型	描述
totalDuration	number	录制总时长，单位为毫秒

详情

当开发者调用 [completeRecord] 之后，SDK 完成录制并保存好录制文件时，会回调该通知。

业务场景：用于开发者更新 UI 并进行后续的语音消息发送。
相关接口：[completeRecord] 调用之后会回调该通知。

支持版本：1.0.0 及以上。
注意事项：开发者必须收到此回调通知之后才能进行语音消息的发送。

onRecorderCancelled

onRecorderCancelled(): void

录制取消通知

当开发者调用 [cancelRecord] 之后，SDK 停止录制并删除录制文件后，会回调该通知。

业务场景：用于开发者更新 UI 使用。
相关接口：[cancelRecord] 调用之后会回调该通知。

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

onRecorderProgress

onRecorderProgress(currentDuration: number): void

录制进度通知

参数

名称	类型	描述
currentDuration	number	当前录制时长，单位为毫秒

详情

当录制已经开始时，SDK 会按照每 500ms 一次的频率回调进度通知。

业务场景：用于开发者更新 UI 使用。

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

onRecorderFailed

onRecorderFailed(errorCode: ZIMAudioErrorCode): void

录制失败通知

参数

名称	类型	描述
errorCode	ZIMAudioErrorCode	错误码

详情

当录制开始或者录制中途发生异常而导致当次录制失败时，会通过此回调通知。

业务场景：用于开发者更新 UI 使用。建议开发者监听此回调并对用户进行必要的提示。

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

onPlayerStarted

onPlayerStarted(totalDuration: number): void

播放开始通知

参数

名称	类型	描述
totalDuration	number	播放总时长，单位为毫秒

详情

当开发者调用 [startPlay] 之后，SDK 内部已经准备好音频设备即将开始播放时，会回调该通知。

业务场景：用于开发者更新 UI 使用。
相关接口：[startPlay] 调用之后会回调该通知。

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

onPlayerEnded

onPlayerEnded(): void

播放结束通知

当用户已经完整播放完成了音频文件后，会回调该通知。

业务场景：用于开发者更新 UI 使用。

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

onPlayerStopped

onPlayerStopped(): void

播放停止通知

当开发者调用 [stopPlay] 之后，SDK 会马上停止当前正在播放的音频并回调此通知。

业务场景：用于开发者更新 UI 使用。
相关接口：[stopPlay] 调用之后会回调该通知。

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

onPlayerProgress

onPlayerProgress(currentDuration: number): void

播放进度回调

参数

名称	类型	描述
currentDuration	number	当前播放时长，单位为毫秒

详情

当播放已经开始时，SDK 会按照每 500ms 一次的频率回调进度通知。

业务场景：用于开发者更新 UI 使用。

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

onPlayerInterrupted

onPlayerInterrupted(): void

播放被中断通知

当播放过程中被其他行为打断时，SDK 会回调该通知。如播放过程中执行了开始录制、播放过程中收到系统的来电事件、播放过程中被其他 App 抢占了音频设备等。

业务场景：用于开发者更新 UI 使用。

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

onPlayerFailed

onPlayerFailed(errorCode: ZIMAudioErrorCode): void

播放失败通知

参数

名称	类型	描述
errorCode	ZIMAudioErrorCode	错误码

详情

当播放开始或者播放中途发生异常而导致当次播放失败时，会通过此回调通知。

业务场景：用于开发者更新 UI 使用。建议开发者监听此回调并对用户进行必要的提示。

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