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(): void

获取 SDK 单例对象。

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

调用时机：任意时刻。

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

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

init

init(license: string): void

初始化 ZIMAudio SDK

参数

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

详情

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

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

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

uninit

uninit(): void

反初始化 ZIMAudio SDK

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

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

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

enableANS

enableANS(enable: boolean): void

开/关噪声抑制

参数

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

详情

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

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

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

enableAGC

enableAGC(enable: boolean): void

开/关自动增益控制

参数

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

详情

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

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

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

setANSParam

setANSParam(param: ZIMAudioANSParam): void

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

参数

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

详情

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

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

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

startRecord

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

completeRecord(): void

完成录制音频文件

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

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

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

cancelRecord

cancelRecord(): void

停止录制音频文件

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

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

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

isRecording

isRecording(): Promise<boolean>

获取是否正在录制

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

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

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

是否正在录制

setAudioRouteType

setAudioRouteType(routeType: ZIMAudioRouteType): void

设置音频路由类型

参数

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

详情

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

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

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

startPlay

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

stopPlay(): void

停止播放音频文件

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

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

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

isPlaying

isPlaying(): Promise<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 及以上。
注意事项：无。