Class

2026-06-24


ZIMAudio	ZIMAudioEventHandler

ZIMAudio

Details

The main class of the ZIMAudio SDK.

Methods

getVersion

static

getVersion

static getVersion(): string

Gets the SDK version number.

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

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

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

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

static getInstance(): ZIMAudio

Gets the SDK singleton object.

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

abstract init(license: string): void

Initializes the ZIMAudio SDK

Parameters

Name	Type	Description
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

abstract uninit(): void

Deinitializes the ZIMAudio SDK

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.

on

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

Registers Audio event notification callback

Parameters

Name	Type	Description
type	K	Event type.
listener	ZIMAudioEventHandler[K]	Custom callback method after an event occurs.

Supported versions: 1.0.0 and later.

off

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

Unregisters Audio event notification callback

Parameters

Name	Type	Description
type	K	Event type.

Supported versions: 1.0.0 and later.

enableANS

abstract enableANS(enable: boolean): void

Enables or disables noise suppression

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

abstract enableAGC(enable: boolean): void

Enables or disables automatic gain control

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

abstract setANSParam(param: ZIMAudioANSParam): void

Sets noise suppression parameters, currently only includes noise suppression mode

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

abstract startRecord(config: ZIMAudioRecordConfig): void

Starts recording an audio file

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

abstract completeRecord(): void

Completes recording an audio file

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

abstract cancelRecord(): void

Stops recording an audio file

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

abstract isRecording(): Promise<boolean>

Gets whether recording is in progress

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

abstract setAudioRouteType(routeType: ZIMAudioRouteType): void

Sets the audio route type

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

abstract startPlay(config: ZIMAudioPlayConfig): void

Starts playing an audio file

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

abstract stopPlay(): void

Stops playing an audio file

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

abstract isPlaying(): Promise<boolean>

Gets whether playback is in progress

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.

Methods

error

onError(errorInfo: ZIMAudioError): void

SDK error notification

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.

recorderStarted

onRecorderStarted(): void

Recording started notification

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

onRecorderCompleted(totalDuration: number): void

Recording completed notification

Parameters

Name	Type	Description
totalDuration	number	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

onRecorderCancelled(): void

Recording cancelled notification

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

onRecorderProgress(currentDuration: number): void

Recording progress notification

Parameters

Name	Type	Description
currentDuration	number	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

onRecorderFailed(errorCode: ZIMAudioErrorCode): void

Recording failed notification

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

onPlayerStarted(totalDuration: number): void

Playback started notification

Parameters

Name	Type	Description
totalDuration	number	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

onPlayerEnded(): void

Playback ended notification

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

onPlayerStopped(): void

Playback stopped notification

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

onPlayerProgress(currentDuration: number): void

Playback progress callback

Parameters

Name	Type	Description
currentDuration	number	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

onPlayerInterrupted(): void

Playback interrupted notification

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

onPlayerFailed(errorCode: ZIMAudioErrorCode): void

Playback failed notification

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.