Class

2026-05-26


ZIMAudio	ZIMAudioEventHandler

ZIMAudio

详情

ZIMAudio SDK 主类。

Declared in ZIMAudio.java

方法

getVersion

static

getVersion

String getVersion()

获取 SDK 版本号。

Declared in ZIMAudio.java

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

调用时机：任意时刻。

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

SDK 版本号。

setAdvancedConfig

static

setAdvancedConfig

void setAdvancedConfig(String key, String value)

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

Declared in ZIMAudio.java

参数

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

详情

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

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

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

getInstance

static

getInstance

ZIMAudio getInstance()

获取 SDK 单例对象。

Declared in ZIMAudio.java

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

调用时机：任意时刻。

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

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

init

void init(Application application, String license)

初始化 ZIMAudio SDK

Declared in ZIMAudio.java

参数

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

详情

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

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

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

uninit

void uninit()

反初始化 ZIMAudio SDK

Declared in ZIMAudio.java

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

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

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

setEventHandler

void setEventHandler(ZIMAudioEventHandler eventHandler)

设置事件通知回调。

Declared in ZIMAudio.java

参数

名称	类型	描述
eventHandler	ZIMAudioEventHandler	事件通知回调。传 [null] 则清空已设置的回调。开发者应根据自身业务场景，监听相应的回调。SDK 主要的回调函数都在这里。

详情

设置事件通知回调，用于监听如录制器、播放器的生命周期事件等回调。

调用时机：在 [init] 后。

支持版本：1.0.0 及以上。
使用限制：无。
注意事项：当多次调用该 API 传入不同的 eventHandler 对象时，最后一次的对象会覆盖前面设置过的对象；当该 API 传入的 eventHandler 对象为空时，则取消事件回调通知。

enableANS

void enableANS(boolean enable)

开/关噪声抑制

Declared in ZIMAudio.java

参数

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

详情

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

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

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

enableAGC

void enableAGC(boolean enable)

开/关自动增益控制

Declared in ZIMAudio.java

参数

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

详情

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

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

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

setANSParam

void setANSParam(ZIMAudioANSParam param)

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

Declared in ZIMAudio.java

参数

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

详情

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

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

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

startRecord

void startRecord(ZIMAudioRecordConfig config)

开始录制音频文件

Declared in ZIMAudio.java

参数

名称	类型	描述
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

void completeRecord()

完成录制音频文件

Declared in ZIMAudio.java

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

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

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

cancelRecord

void cancelRecord()

停止录制音频文件

Declared in ZIMAudio.java

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

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

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

isRecording

boolean isRecording()

获取是否正在录制

Declared in ZIMAudio.java

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

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

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

是否正在录制

setAudioRouteType

void setAudioRouteType(ZIMAudioRouteType routeType)

设置音频路由类型

Declared in ZIMAudio.java

参数

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

详情

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

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

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

startPlay

void startPlay(ZIMAudioPlayConfig config)

开始播放音频文件

Declared in ZIMAudio.java

参数

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

详情

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

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

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

stopPlay

void stopPlay()

停止播放音频文件

Declared in ZIMAudio.java

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

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

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

isPlaying

boolean isPlaying()

获取是否正在播放

Declared in ZIMAudio.java

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

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

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

是否正在播放

ZIMAudioEventHandler

详情

ZIMAudio SDK 事件处理类。

Declared in callback/ZIMAudioEventHandler.java

方法

onError

void onError(ZIMAudioError errorInfo)

SDK 异常出错通知

Declared in callback/ZIMAudioEventHandler.java

参数

名称	类型	描述
errorInfo	ZIMAudioError

详情

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

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

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

onRecorderStarted

void onRecorderStarted()

录制开始通知

Declared in callback/ZIMAudioEventHandler.java

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

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

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

onRecorderCompleted

void onRecorderCompleted(int totalDuration)

录制完成通知

Declared in callback/ZIMAudioEventHandler.java

参数

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

详情

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

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

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

onRecorderCancelled

void onRecorderCancelled()

录制取消通知

Declared in callback/ZIMAudioEventHandler.java

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

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

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

onRecorderProgress

void onRecorderProgress(int currentDuration)

录制进度通知

Declared in callback/ZIMAudioEventHandler.java

参数

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

详情

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

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

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

onRecorderFailed

void onRecorderFailed(ZIMAudioErrorCode errorCode)

录制失败通知

Declared in callback/ZIMAudioEventHandler.java

参数

名称	类型	描述
errorCode	ZIMAudioErrorCode	错误码

详情

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

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

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

onPlayerStarted

void onPlayerStarted(int totalDuration)

播放开始通知

Declared in callback/ZIMAudioEventHandler.java

参数

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

详情

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

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

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

onPlayerEnded

void onPlayerEnded()

播放结束通知

Declared in callback/ZIMAudioEventHandler.java

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

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

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

onPlayerStopped

void onPlayerStopped()

播放停止通知

Declared in callback/ZIMAudioEventHandler.java

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

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

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

onPlayerProgress

void onPlayerProgress(int currentDuration)

播放进度回调

Declared in callback/ZIMAudioEventHandler.java

参数

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

详情

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

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

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

onPlayerInterrupted

void onPlayerInterrupted()

播放被中断通知

Declared in callback/ZIMAudioEventHandler.java

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

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

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

onPlayerFailed

void onPlayerFailed(ZIMAudioErrorCode errorCode)

播放失败通知

Declared in callback/ZIMAudioEventHandler.java

参数

名称	类型	描述
errorCode	ZIMAudioErrorCode	错误码

详情

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

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

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