Protocol

2026-07-06


ZIMAudio	ZIMAudioEventHandler

ZIMAudio

Details

ZIMAudio SDK main class.

Declared in ZIMAudio.h

Methods

getVersion

static

getVersion

+ (NSString *)getVersion;

Gets the SDK's version number.

Declared in ZIMAudio.h

If you encounter an abnormality during the running of the SDK, you can submit the problem, log and other information to the ZEGO technical staff to locate and troubleshoot. Developers can also collect current SDK version information through this API, which is convenient for App operation statistics and related issues.

When to call：Any time.
Caution：None.

Available since：1.0.0
Restrictions：None.

SDK version.

setAdvancedConfigWithKey

static

setAdvancedConfigWithKey

+ (void)setAdvancedConfig:(NSString *) key :(NSString *) value;

Set up SDK advanced configuration, please contact ZEGO technical support before use.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
key	NSString *	Key for advanced configuration
value	NSString *	Value for advanced configuration

Details

When the default behavior of the SDK cannot meet the developer's usage scenario, this API can be called to implement developer-defined advanced configuration.

When to call：Must be called before [init], otherwise it will only take effect after the next [init].
Caution：Please contact ZEGO technical support before use.

Available since：1.0.0
Restrictions：None.

sharedInstance

static

sharedInstance

+ (ZIMAudio *)getInstance;

Get SDK singleton object.

Declared in ZIMAudio.h

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

When to call：Any time.
Caution：None.

Available since：1.0.0
Restrictions：None.

SDK singleton object for subsequent API calls

initWithLicense:

- (void)init:(NSString *) license;

Init ZIMAudio SDK

Declared in ZIMAudio.h

Parameters

Name	Type	Description
license	NSString *	License info. If developers do not obtain it through the server API, they can pass in an empty string, but subsequent use of some functions that require authentication will be restricted.

Details

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

When to call：Call before calling other APIs.
Caution：None.

Available since：1.0.0
Restrictions：When no authentication information is passed in or the authentication information is incorrect, the initialization of the SDK can proceed normally, but subsequent use of some functions that require authentication will be restricted.

uninit

- (void)uninit;

Uninit ZIMAudio SDK

Declared in ZIMAudio.h

When you no longer need to use ZIMAudio SDK, you can call this API to deinitialize and release memory resources.

When to call：Any time.
Caution：None.

Available since：1.0.0
Restrictions：None.

setEventHandler

- (void)setEventHandler:(id<ZIMAudioEventHandler>) eventHandler;

Sets up the event notification callbacks that need to be handled.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
eventHandler	id<ZIMAudioEventHandler>	Event notification callback. If the eventHandler is set to [null], all the callbacks set previously will be cleared. Developers should monitor the corresponding callbacks according to their own business scenarios. The main callback functions of the SDK are here.

Details

Set event notification callbacks to monitor callbacks such as recorder and player life cycle events.

When to call：After [init].
Caution：When the API is called multiple times and different eventHandler objects are passed in, the last object will overwrite the previously set object; when the eventHandler object passed in by the API is empty, the event callback notification is cancelled.

Available since：1.0.0
Restrictions：None.

enableANS

- (void)enableANS:(BOOL) enable;

Enables or disables active noise suppression (ANS, aka ANC).

Declared in ZIMAudio.h

Parameters

Name	Type	Description
enable	BOOL	Whether to enable noise suppression, true: enable, false: disable

Details

After turning on this function, the human voice can be made clearer. This function is better at suppressing continuous noise (such as the sound of rain and other white noise).

Use case：This feature can be turned on when noise suppression is needed to improve the vocal quality and user experience of recorded audio.
When to call：Called at any time after [init].
Caution：This API can only be called normally after the authentication is within the legal usage period, or the use is allowed in the authentication information; otherwise, an error message will be reported that the authentication has expired or this feature is not supported.

Available since：1.0.0
Restrictions：None.

enableAGC

- (void)enableAGC:(BOOL) enable;

Enables or disables automatic gain control (AGC).

Declared in ZIMAudio.h

Parameters

Name	Type	Description
enable	BOOL	Whether to enable automatic gain control, true: enable, false: disable

Details

After turning on this function, the SDK can automatically adjust the microphone volume to adapt to far and near pickup and keep the volume stable.

Use case：This feature can be turned on when volume stability needs to be ensured to improve the vocal quality and user experience of recorded audio.
When to call：Called at any time after [init].
Caution：This API can only be called normally after the authentication is within the legal usage period, or the use is allowed in the authentication information; otherwise, an error message will be reported that the authentication has expired or this feature is not supported.

Available since：1.0.0
Restrictions：None.

setANSParam

- (void)setANSParam:(ZIMAudioANSParam) param;

Set noise suppression parameters, currently only includes noise suppression mode.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
param	ZIMAudioANSParam	ANS parameters, including ANS mode

Details

When noise suppression is turned on using [enableANS], you can use this function to switch between different noise suppression modes to control the degree of noise suppression.

Use case：When the default noise suppression effect does not meet expectations, you can use this function to adjust the noise suppression mode.
Default value：When this function is not called, the default noise suppression mode is [Medium].
When to call：Called at any time after [init].
Caution：This API can only be called normally after the authentication is within the legal usage period, or the use is allowed in the authentication information; otherwise, an error message will be reported that the authentication has expired or this feature is not supported.

Available since：1.0.0
Restrictions：None.

startRecordWithConfig

- (void)startRecord:(ZIMAudioRecordConfig) config;

Start record audio file.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
config	ZIMAudioRecordConfig	Record config

Details

Start recording audio files. The SDK will apply to the system to use the microphone device to collect audio and write it to a local file.

Use case：Before the user need to send voice messages, they can call this API to collect and generate the voice files required for sending. The recording files will eventually be saved to the path set locally.
When to call：After [init].
Related APIs：When this API is called to start recording, the SDK will throw the [onRecorderStarted] notification. Only after receiving this callback notification can the developer consider that recording has officially started and updated the UI display; after that, the SDK will call back the recording progress through [onRecorderProgress]; under abnormal circumstances, the SDK may also throw an [onRecorderFailed] notification, please Developers may monitor and alert users when exceptions occur as appropriate.
Caution：Developers are requested to ensure that they have obtained the audio collection permission of the app before using this API; when the SDK starts recording, it will exclusively have the right to use the audio device, so it will interrupt the playback and other behaviors of other third-party apps.

Available since：1.0.0
Restrictions：Recording-related APIs cannot be used at the same time as playback-related APIs. At the same time, only recording or playback can be performed inside the SDK. Therefore, before you need to start recording, developers are required to actively stop the playback function, otherwise the playback-related functions will also be stopped before the SDK starts recording.

completeRecord

- (void)completeRecord;

Complete record audio file.

Declared in ZIMAudio.h

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

Use case：After completing the recording, the developer can send the recording file as an IM message. For example, it is passed to ZIM's AudioMessage to send voice messages.
When to call：[startRecord] Recording is taking effect.
Related APIs：When this API is called and recording is successfully completed, the SDK throws the [onRecorderCompleted] notification. Developers must receive this callback notification before sending voice messages.
Caution：If the developer does not call this API to end the recording while [startRecord] is in effect, the recording will still be completed and the file will be saved when the maximum recording duration of [startRecord] is reached. After completing the recording, the SDK will release the occupation of the audio device.

Available since：1.0.0
Restrictions：Recording-related APIs cannot be used at the same time as playback-related APIs. At the same time, only recording or playback can be performed inside the SDK.

cancelRecord

- (void)cancelRecord;

Cancel record audio file.

Declared in ZIMAudio.h

Interrupt recording audio file. After calling this API, recording will be stopped, and the local file will be deleted internally by the SDK.

Use case：When you need to stop recording early during the recording process and do not need to send a voice message, you can call this API to cancel the recording.
When to call：[startRecord] Recording is taking effect.
Related APIs：When this API is called to cancel recording, the SDK will throw the [onRecorderCancelled] notification. Developers can clean up related resources and update UI display based on this notification.
Caution：After canceling the recording, the SDK will release the occupation of the audio device.

Available since：1.0.0
Restrictions：Recording-related APIs cannot be used at the same time as playback-related APIs. At the same time, only recording or playback can be performed inside the SDK.

isRecording

- (BOOL)isRecording;

Get whether recording is taking place.

Declared in ZIMAudio.h

Get whether the SDK is recording at the current moment.

Use case：When developers need to obtain and detect the recording status at a certain moment, they can call this API to obtain the recording status.
When to call：Called at any time after [init].
Caution：None.

Available since：1.0.0
Restrictions：None.

The return value whether is recording

setAudioRouteType

- (void)setAudioRouteType:(ZIMAudioRouteType) routeType;

Set audio routing type.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
routeType	ZIMAudioRouteType	Audio routing type, the default is that the sound is played from the speaker.

Details

Set the audio routing type to choose whether to use speakers or earpieces to play audio.

Use case：When developers need to have the option for users to choose where the sound is played from, they can call this API to change the audio routing type currently being played.
When to call：Called at any time after [init].
Caution：When the user is currently using headphones for audio playback, the settings of this API will not take effect.

Available since：1.0.0
Restrictions：None.

startPlayWithConfig

- (void)startPlay:(ZIMAudioPlayConfig) config;

Start playing audio file.

Declared in ZIMAudio.h

Parameters

Name	Type	Description
config	ZIMAudioPlayConfig	Play config

Details

Start playing the audio file. The SDK will read the audio file in the specified path and play it.

Use case：After the user receives the voice message, the API can be called to play the audio file that has been downloaded and saved locally.
When to call：After [init].
Related APIs：When this API is called to start playback, the SDK will throw the [onPlayerStarted] notification. Only after receiving this callback notification can the developer consider that playback has officially started and update the UI display; after that, the SDK will call back the playback progress through [onPlayerProgress]; under abnormal circumstances, the SDK may also throw an [onPlayerFailed] notification, please Developers may monitor and alert users when exceptions occur as appropriate.
Caution：When the SDK starts playing, it will exclusively use the audio device, so it will interrupt the playback of other third-party apps and will not mix with the audio output of other apps.

Available since：1.0.0
Restrictions：Playback-related APIs cannot be used at the same time as recording-related APIs. At the same time, only recording or playback can be performed inside the SDK. Therefore, before you need to enable playback, developers must first ensure that the recording function is not being used at this time, otherwise playback will fail.

stopPlay

- (void)stopPlay;

Stop playing audio file.

Declared in ZIMAudio.h

Stops the audio currently being played by the SDK.

Use case：When you need to stop audio playback in advance during playback, you can call this API to stop playback. If the user needs to immediately play the next piece of audio, he needs to stop the playback of the previous piece of audio; or when he is about to leave the playback page, he should also stop the current playback.
When to call：[startPlay] During playback.
Related APIs：When this API is called to stop playback, the SDK will throw the [onPlayerStopped] notification. Developers can update the UI display based on this callback notification.
Caution：After stopping playback or completing playback, the SDK will release the occupation of the audio device.

Available since：1.0.0
Restrictions：Playback-related APIs cannot be used at the same time as recording-related APIs. At the same time, only recording or playback can be performed inside the SDK. Therefore, before you need to enable playback, developers must first ensure that the recording function is not being used at this time, otherwise playback will fail.

isPlaying

- (BOOL)isPlaying;

Get whether it is playing.

Declared in ZIMAudio.h

Get whether the SDK is playing at the current moment.

Use case：When developers need to obtain and detect the playback status at a certain moment, they can call this API to obtain the playback status.
When to call：Called at any time after [init]. Related APIs:
Caution：None.

Available since：1.0.0
Restrictions：None.

The return value whether is playing

ZIMAudioEventHandler

Details

ZIMAudio SDK event handler class.

Declared in ZIMAudioEventHandler.h

Methods

onError

- (void)onError:(ZIMAudioError) errorInfo;

SDK exception error notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
errorInfo	ZIMAudioError

Details

When an exception is detected internally in the SDK, a notification will be thrown through this callback.

Use case：It is used to facilitate developers to collect SDK problems and troubleshoot them. It is recommended to monitor the callback and do appropriate log printing or event reporting.
Caution：It is not recommended that developers perform logic after listening to this callback. It is only recommended for collecting and troubleshooting problems.

Available since：1.0.0

onRecorderStarted

- (void)onRecorderStarted;

Recording start notification.

Declared in ZIMAudioEventHandler.h

When the developer calls [startRecord] and the SDK has internally prepared the audio device and is about to start recording, the notification will be called back.

Use case：Used by developers to update the UI.
Related APIs：The notification will be called back after [startRecord] is called.
Caution：None.

Available since：1.0.0

onRecorderCompleted

- (void)onRecorderCompleted:(int) totalDuration;

Recording completion notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
totalDuration	int	Total recording duration in milliseconds

Details

When the developer calls [completeRecord] and the SDK completes the recording and saves the recording file, the notification will be called back.

Use case：Used by developers to update the UI and send subsequent voice messages.
Related APIs：The notification will be called back after [completeRecord] is called.
Caution：Developers must receive this callback notification before sending voice messages.

Available since：1.0.0

onRecorderCancelled

- (void)onRecorderCancelled;

Recording cancellation notification.

Declared in ZIMAudioEventHandler.h

When the developer calls [cancelRecord] and the SDK stops recording and deletes the recording file, this notification will be called back.

Use case：Used by developers to update the UI.
Related APIs：The notification will be called back after [cancelRecord] is called.
Caution：None.

Available since：1.0.0

onRecorderProgress

- (void)onRecorderProgress:(int) currentDuration;

Recording progress notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
currentDuration	int	Current recording duration in milliseconds

Details

When recording has started, the SDK will call back progress notifications every 500ms.

Use case：Used by developers to update the UI.
Caution：None.

Available since：1.0.0

onRecorderFailed

- (void)onRecorderFailed:(ZIMAudioErrorCode) errorCode;

Recording failure notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
errorCode	ZIMAudioErrorCode	Error code

Details

When recording starts or an exception occurs during recording and the recording fails, this callback will be used to notify you.

Use case：Used by developers to update the UI. It is recommended that developers listen to this callback and provide necessary prompts to users.
Caution：None.

Available since：1.0.0

onPlayerStarted

- (void)onPlayerStarted:(int) totalDuration;

Play start notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
totalDuration	int	Total playing duration in milliseconds

Details

When the developer calls [startPlay] and the SDK has internally prepared the audio device and is about to start playing, the notification will be called back.

Use case：Used by developers to update the UI.
Related APIs：The notification will be called back after [startPlay] is called.
Caution：None.

Available since：1.0.0

onPlayerEnded

- (void)onPlayerEnded;

Playback end notification.

Declared in ZIMAudioEventHandler.h

When the user has finished playing the audio file, the notification will be called back.

Use case：Used by developers to update the UI.
Caution：None.

Available since：1.0.0

onPlayerStopped

- (void)onPlayerStopped;

Play stop notification.

Declared in ZIMAudioEventHandler.h

When the developer calls [stopPlay], the SDK will immediately stop the currently playing audio and call back this notification.

Use case：Used by developers to update the UI.
Related APIs：The notification will be called back after [stopPlay] is called.
Caution：None.

Available since：1.0.0

onPlayerProgress

- (void)onPlayerProgress:(int) currentDuration;

Playback progress callback.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
currentDuration	int	Current playing duration in milliseconds

Details

When playback has started, the SDK will call back progress notifications every 500ms.

Use case：Used by developers to update the UI.
Caution：None.

Available since：1.0.0

onPlayerInterrupted

- (void)onPlayerInterrupted;

Notification that playback has been interrupted.

Declared in ZIMAudioEventHandler.h

When playback is interrupted by other actions, the SDK will call back this notification. For example, recording is started during playback, an incoming call event from the system is received during playback, the audio device is preempted by other apps during playback, etc.

Use case：Used by developers to update the UI.
Caution：None.

Available since：1.0.0

onPlayerFailed

- (void)onPlayerFailed:(ZIMAudioErrorCode) errorCode;

Playback failure notification.

Declared in ZIMAudioEventHandler.h

Parameters

Name	Type	Description
errorCode	ZIMAudioErrorCode	Error code

Details

When playback starts or an exception occurs during playback and the playback fails, this callback will be used to notify you.

Use case：Used by developers to update the UI. It is recommended that developers listen to this callback and provide necessary prompts to users.
Caution：None.

Available since：1.0.0