Class

2026-06-24


ZIMAudio	ZIMAudioEventHandler

ZIMAudio

Details

The main class of the ZIMAudio SDK.

Declared in ZIMAudio.java

Methods

getVersion

static

getVersion

String getVersion()

Gets the SDK version number.

Declared in ZIMAudio.java

If the SDK encounters exceptions during runtime, issues and logs can be submitted to ZEGOCLOUD Technical Support for troubleshooting. Developers can also use this API to collect the current SDK version information for app operation statistics and issue correlation.

Call timing: Anytime.

Supported versions: 1.0.0 and later.
Usage limitations: None.
Notes: None.

SDK version number.

setAdvancedConfig

static

setAdvancedConfig

void setAdvancedConfig(String key, String value)

Sets advanced SDK configuration. Please contact ZEGOCLOUD Technical Support before use.

Declared in ZIMAudio.java

Parameters

Name	Type	Description
key	String	Key of the advanced configuration
value	String	Value of the advanced configuration

Details

When the default behavior of the SDK cannot meet the developer's use case, this API can be called to implement custom advanced configuration.

Call timing: Must be called before [init], otherwise it will only take effect after the next [init].

Supported versions: 1.0.0 and later.
Usage limitations: None.
Notes: Please contact ZEGOCLOUD Technical Support before use.

getInstance

static

getInstance

ZIMAudio getInstance()

Gets the SDK singleton object.

Declared in ZIMAudio.java

When using the ZIMAudio SDK, developers should call this API directly to obtain the internal singleton object, without creating and maintaining objects themselves.

Call timing: Anytime.

Supported versions: 1.0.0 and later.
Usage limitations: None.
Notes: None.

SDK singleton object for subsequent API calls.

init

void init(Application application, String license)

Initializes the ZIMAudio SDK

Declared in ZIMAudio.java

Parameters

Name	Type	Description
application	Application	Application context information
license	String	License information. If the developer has not obtained it through the server-side API, an empty string can be passed in, but subsequent use of features requiring a license will be restricted.

Details

Before using other functional interfaces of the ZIMAudio SDK, this API must be called first for initialization.

Call timing: Called before other APIs.

Supported versions: 1.0.0 and later.
Usage limitations: When no license information is passed in or the license information is incorrect, the SDK initialization can proceed normally, but subsequent use of features requiring a license will be restricted.
Notes: None.

uninit

void uninit()

Deinitializes the ZIMAudio SDK

Declared in ZIMAudio.java

When the ZIMAudio SDK is no longer needed, this API can be called to deinitialize and release memory resources.

Call timing: Anytime.If recording or playback is not stopped before deinitializing the SDK, they will all be stopped.

Supported versions: 1.0.0 and later.
Usage limitations: None.
Notes: None.

setEventHandler

void setEventHandler(ZIMAudioEventHandler eventHandler)

Sets the event notification callback.

Declared in ZIMAudio.java

Parameters

Name	Type	Description
eventHandler	ZIMAudioEventHandler	Event notification callback. Pass [null] to clear the previously set callback. Developers should listen to the corresponding callbacks based on their business scenarios. The main SDK callback functions are all here.

Details

Sets the event notification callback for listening to lifecycle events of the recorder and player.

Call timing: After [init].

Supported versions: 1.0.0 and later.
Usage limitations: None.
Notes: When this API is called multiple times with different eventHandler objects, the last object will override the previously set objects; when the eventHandler object passed to this API is empty, the event callback notification will be canceled.

enableANS

void enableANS(boolean enable)

Enables or disables noise suppression

Declared in ZIMAudio.java

Parameters

Name	Type	Description
enable	boolean	Whether to enable noise suppression; true to enable, false to disable

Details

After enabling this feature, the human voice can be clearer. This feature has better suppression effects on continuous noise (such as white noise like rain).

Business scenario: When you need to suppress noise to improve the voice quality and user experience of recorded audio, you can enable this feature.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: This API can only be called normally when the license is within its valid usage period, or when the license information allows the use of this feature; otherwise, an error indicating that the license has expired or the feature is not supported will be reported.
Usage limitations: None.

enableAGC

void enableAGC(boolean enable)

Enables or disables automatic gain control

Declared in ZIMAudio.java

Parameters

Name	Type	Description
enable	boolean	Whether to enable automatic gain control; true to enable, false to disable

Details

After enabling this feature, the SDK can automatically adjust the microphone volume, adapt to near and far audio pickup, and keep the volume stable.

Business scenario: When you need to ensure volume stability to improve the voice quality and user experience of recorded audio, you can enable this feature.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: This API can only be called normally when the license is within its valid usage period, or when the license information allows the use of this feature; otherwise, an error indicating that the license has expired or the feature is not supported will be reported.
Usage limitations: None.

setANSParam

void setANSParam(ZIMAudioANSParam param)

Sets noise suppression parameters, currently only includes noise suppression mode

Declared in ZIMAudio.java

Parameters

Name	Type	Description
param	ZIMAudioANSParam	ANS parameters, including ANS mode

Details

After noise suppression is enabled via [enableANS], this function can be used to switch between different noise suppression modes to control the degree of noise suppression.

Business scenario: When the default noise suppression effect does not meet expectations, you can adjust the noise suppression mode through this function.
Default value: When this function is not called, the default noise suppression mode is Medium.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: This API can only be called normally when the license is within its valid usage period, or when the license information allows the use of this feature; otherwise, an error indicating that the license has expired or the feature is not supported will be reported.
Usage limitations: The value set by this function only takes effect after noise suppression is enabled.

startRecord

void startRecord(ZIMAudioRecordConfig config)

Starts recording an audio file

Declared in ZIMAudio.java

Parameters

Name	Type	Description
config	ZIMAudioRecordConfig	Recording configuration

Details

Starts recording an audio file. The SDK will request the system to use the microphone device for audio capture and write it to a local file.

Business scenario: Before the user needs to send a voice message, this API can be called to capture and generate the voice file needed for sending. The recorded file will be saved to the locally configured path.
Call timing: After [init].
Related APIs: After calling this API to start recording, the SDK will emit [onRecorderStarted] notification. Developers should only consider recording as formally started and update the UI display after receiving this callback; after this, the SDK will report recording progress via [onRecorderProgress] ; in case of exceptions, the SDK may also emit [onRecorderFailed] notification. Developers should listen to these as appropriate and provide user prompts when exceptions occur.

Supported versions: 1.0.0 and later.
Notes: Please ensure the app has audio recording permission before using this API. When the SDK starts recording, it will exclusively occupy the audio device, which will interrupt playback and other behaviors of third-party apps.
Usage limitations: Recording-related APIs cannot be used simultaneously with playback-related APIs. The SDK can only perform recording or playback at any given time. Before starting recording, please stop the playback function first; otherwise, playback will be stopped before the SDK starts recording.

completeRecord

void completeRecord()

Completes recording an audio file

Declared in ZIMAudio.java

Completes recording an audio file. After calling this API, the recorded file will be generated at the file path passed in [startRecord] and saved.

Business scenario: After completing recording, developers can send the recorded file as an IM message. For example, passing it to ZIM's AudioMessage for voice message sending.
Call timing: During active recording via [startRecord].
Related APIs: After calling this API and successfully completing the recording, the SDK will emit [onRecorderCompleted] notification. Developers must receive this callback before sending voice messages.ive this callback before sending voice messages.

Supported versions: 1.0.0 and later.
Notes: When the developer does not call this API to end recording during [startRecord] If the developer does not call this API to end the recording during the effective recording period of [startRecord] , the recording will still be completed and the file saved when the maximum recording duration is reached. After completing recording, the SDK will release the audio device.
Usage limitations: Recording-related APIs cannot be used simultaneously with playback-related APIs. The SDK can only perform recording or playback at any given time.

cancelRecord

void cancelRecord()

Stops recording an audio file

Declared in ZIMAudio.java

Interrupts recording an audio file. After calling this API, recording will be stopped and the SDK will also delete the local file.

Business scenario: When you need to stop recording early and do not need to send a voice message, you can call this API to cancel the recording.
Call timing: During active recording via [startRecord].
Related APIs: After calling this API to cancel the recording, the SDK will emit [onRecorderCancelled] notification. Developers can perform related resource cleanup and update the UI display based on this callback.

Supported versions: 1.0.0 and later.
Notes: After canceling the recording, the SDK will release the audio device.
Usage limitations: Recording-related APIs cannot be used simultaneously with playback-related APIs. The SDK can only perform recording or playback at any given time.

isRecording

boolean isRecording()

Gets whether recording is in progress

Declared in ZIMAudio.java

Gets whether the SDK is currently recording.

Business scenario: When developers need to check the recording status at a certain point in time, they can call this API to get the recording status.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: None.
Usage limitations: None.

Whether recording is in progress

setAudioRouteType

void setAudioRouteType(ZIMAudioRouteType routeType)

Sets the audio route type

Declared in ZIMAudio.java

Parameters

Name	Type	Description
routeType	ZIMAudioRouteType	Audio route type. Default is playing sound from the speaker.

Details

Sets the audio route type to select whether to use the Speaker or Earpiece for audio playback.

Business scenario: When developers need to provide an option for users to choose the audio output source during playback, they can call this API to change the current audio route type.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: When the user is currently using earphones for audio playback, the settings of this API will not take effect.
Usage limitations: None.

startPlay

void startPlay(ZIMAudioPlayConfig config)

Starts playing an audio file

Declared in ZIMAudio.java

Parameters

Name	Type	Description
config	ZIMAudioPlayConfig	Playback parameters

Details

Starts playing an audio file. The SDK will read the audio file at the specified path and play it.

Business scenario: After the user receives a voice message, this API can be called to play the audio file that has been downloaded and saved locally.
Call timing: After [init].
Related APIs: fter receiving this callback; after this, the SDK will report playback progress via [onPlayerProgress]; in case of exceptions, the SDK may also emit [onPlayerFailed] notification. Developers should listen to these as appropriate and provide user prompts when exceptions occur.fter receiving this callback; after this, the SDK will report playback progress via [onPlayerProgress]; in case of exceptions, the SDK may also emit [onPlayerFailed] notification. Developers should listen to these as appropriate and provide user prompts when exceptions occur.fter receiving this callback; after this, the SDK will report playback progress via [onPlayerProgress]; in case of exceptions, the SDK may also emit [onPlayerFailed] notification. Developers should listen to these as appropriate and provide user prompts when exceptions occur.fter receiving this callback; after this, the SDK will report playback progress via [onPlayerProgress] ; after this, the SDK will report playback progress via [onPlayerProgress]; in case of exceptions, the SDK may also emit [onPlayerFailed] notification. Developers should listen to these as appropriate and provide user prompts when exceptions occur.

Supported versions: 1.0.0 and later.
Notes: When the SDK starts playing, it will exclusively occupy the audio device, which will interrupt playback and other behaviors of third-party apps, and will not mix with the audio output of other apps.
Usage limitations: Playback-related APIs cannot be used simultaneously with recording-related APIs. The SDK can only perform recording or playback at any given time. Before starting playback, please ensure no recording function is in use, otherwise playback will fail.

stopPlay

void stopPlay()

Stops playing an audio file

Declared in ZIMAudio.java

Stops the audio currently being played by the SDK.

Business scenario: When you need to stop audio playback early, you can call this API to stop it. For example, before the user needs to immediately play the next audio, the previous audio playback should be stopped first; or when about to leave the playback page, the current playback should also be stopped first.
Call timing: During active playback via [startPlay].
Related APIs: After calling this API to stop playback, the SDK will emit [onPlayerStopped] notification. Developers can update the UI display based on this callback.

Supported versions: 1.0.0 and later.
Notes: After stopping playback or when playback is complete, the SDK will release the audio device.
Usage limitations: Playback-related APIs cannot be used simultaneously with recording-related APIs. The SDK can only perform recording or playback at any given time. Before starting playback, please ensure no recording function is in use, otherwise playback will fail.

isPlaying

boolean isPlaying()

Gets whether playback is in progress

Declared in ZIMAudio.java

Gets whether the SDK is currently playing.

Business scenario: When developers need to check the playback status at a certain point in time, they can call this API to get the playback status.
Call timing: Called at any time after [init].

Supported versions: 1.0.0 and later.
Notes: None.
Usage limitations: None.

Whether playback is in progress

ZIMAudioEventHandler

Details

The event handler class of the ZIMAudio SDK.

Declared in callback/ZIMAudioEventHandler.java

Methods

onError

void onError(ZIMAudioError errorInfo)

SDK error notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
errorInfo	ZIMAudioError

Details

When the SDK internally detects an exception, it will emit a notification through this callback.

Business scenario: Used to help developers collect SDK issues for troubleshooting. It is recommended to listen to this callback and perform appropriate log printing or event reporting.

Supported versions: 1.0.0 and later.
Notes: It is not recommended for developers to perform logic upon receiving this callback; it is only recommended for collecting and troubleshooting issues.

onRecorderStarted

void onRecorderStarted()

Recording started notification

Declared in callback/ZIMAudioEventHandler.java

After the developer calls [startRecord], when the SDK has prepared the audio device and is about to start recording, this notification will be triggered.

Business scenario: Used for developers to update the UI.
Related APIs: [startRecord] will trigger this callback after being called.

Supported versions: 1.0.0 and later.
Notes: None.

onRecorderCompleted

void onRecorderCompleted(int totalDuration)

Recording completed notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
totalDuration	int	Total recording duration in milliseconds

Details

After the developer calls [completeRecord], when the SDK completes recording and saves the recorded file, this notification will be triggered.

Business scenario: Used for developers to update the UI and send subsequent voice messages.
Related APIs: [completeRecord] will trigger this callback after being called.

Supported versions: 1.0.0 and later.
Notes: Developers must receive this callback before sending voice messages.

onRecorderCancelled

void onRecorderCancelled()

Recording cancelled notification

Declared in callback/ZIMAudioEventHandler.java

After the developer calls [cancelRecord], when the SDK stops recording and deletes the recorded file, this notification will be triggered.

Business scenario: Used for developers to update the UI.
Related APIs: [cancelRecord] will trigger this callback after being called.

Supported versions: 1.0.0 and later.
Notes: None.

onRecorderProgress

void onRecorderProgress(int currentDuration)

Recording progress notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
currentDuration	int	Current recording duration in milliseconds

Details

When recording has started, the SDK will report progress notifications at a frequency of once every 500ms.

Business scenario: Used for developers to update the UI.

Supported versions: 1.0.0 and later.
Notes: None.

onRecorderFailed

void onRecorderFailed(ZIMAudioErrorCode errorCode)

Recording failed notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
errorCode	ZIMAudioErrorCode	Error code

Details

When an exception occurs at the start or during recording that causes the recording to fail, this callback will be triggered.

Business scenario: Used for developers to update the UI. It is recommended that developers listen to this callback and provide necessary prompts to users.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerStarted

void onPlayerStarted(int totalDuration)

Playback started notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
totalDuration	int	Total playback duration in milliseconds

Details

After the developer calls [startPlay], when the SDK has prepared the audio device and is about to start playing, this notification will be triggered.

Business scenario: Used for developers to update the UI.
Related APIs: [startPlay] will trigger this callback after being called.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerEnded

void onPlayerEnded()

Playback ended notification

Declared in callback/ZIMAudioEventHandler.java

When the user has fully played the audio file, this notification will be triggered.

Business scenario: Used for developers to update the UI.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerStopped

void onPlayerStopped()

Playback stopped notification

Declared in callback/ZIMAudioEventHandler.java

After the developer calls [stopPlay], the SDK will immediately stop the currently playing audio and trigger this callback.

Business scenario: Used for developers to update the UI.
Related APIs: [stopPlay] will trigger this callback after being called.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerProgress

void onPlayerProgress(int currentDuration)

Playback progress callback

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
currentDuration	int	Current playback duration in milliseconds

Details

When playback has started, the SDK will report progress notifications at a frequency of once every 500ms.

Business scenario: Used for developers to update the UI.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerInterrupted

void onPlayerInterrupted()

Playback interrupted notification

Declared in callback/ZIMAudioEventHandler.java

When playback is interrupted by other actions, the SDK will trigger this notification. Such as starting recording during playback, receiving a system incoming call during playback, or the audio device being preempted by another app during playback.

Business scenario: Used for developers to update the UI.

Supported versions: 1.0.0 and later.
Notes: None.

onPlayerFailed

void onPlayerFailed(ZIMAudioErrorCode errorCode)

Playback failed notification

Declared in callback/ZIMAudioEventHandler.java

Parameters

Name	Type	Description
errorCode	ZIMAudioErrorCode	Error code

Details

When an exception occurs at the start or during playback that causes the playback to fail, this callback will be triggered.

Business scenario: Used for developers to update the UI. It is recommended that developers listen to this callback and provide necessary prompts to users.

Supported versions: 1.0.0 and later.
Notes: None.