IZegoEventHandler

Declared in callback/IZegoEventHandler.java

Methods

onDebugError

public void onDebugError(int errorCode, String funcName, String info)

The callback for obtaining debugging error information.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Error code, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.
funcName	String	Function name.
info	String	Detailed error information.

Details

When the SDK functions are not used correctly, the callback prompts for detailed error information.

Trigger: Notify the developer when an exception occurs in the SDK.
Caution: None.

Available since: 1.1.0
Restrictions: None.

onEngineStateUpdate

public void onEngineStateUpdate(ZegoEngineState state)

The callback triggered when the audio/video engine state changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
state	ZegoEngineState	The audio/video engine state.

Details

Callback notification of audio/video engine status update. When audio/video functions are enabled, such as preview, push streaming, local media player, audio data observering, etc., the audio/video engine will enter the start state. When you exit the room or disable all audio/video functions , The audio/video engine will enter the stop state.

Trigger: The developer called the relevant function to change the state of the audio and video engine. For example: 1. Called ZegoExpressEngine's [startPreview], [stopPreview], [startPublishingStream], [stopPublishingStream], [startPlayingStream], [stopPlayingStream], [startAudioDataObserver], [stopAudioDataObserver] and other functions. 2. The related functions of MediaPlayer are called. 3. The [LogoutRoom] function was called. 4. The related functions of RealTimeSequentialDataManager are called.
Caution: 1. When the developer calls [destroyEngine], this notification will not be triggered because the resources of the SDK are completely released. 2. If there is no special need, the developer does not need to pay attention to this callback.

Available since: 1.1.0
Restrictions: None.

onRecvExperimentalAPI

public void onRecvExperimentalAPI(String content)

Experimental API callback

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
content	String	Callback content in JSON string format.

Details

Receive experimental API callbacks in JSON string format.

Caution: Please use this feature with the help of ZEGO Technical Support.

Available since: 2.7.0

onFatalError

public void onFatalError(int errorCode)

The callback that triggered a fatal error, causing the SDK to malfunction and unable to function properly.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Error code.

Details

The callback that triggered a fatal error.

Trigger: The APP has enabled the restriction of access from foreign IP addresses, and the current client is outside of the domain.
Caution: None.

Available since: 3.6.0
Restrictions: None.

onVideoBackendTypeChanged

public void onVideoBackendTypeChanged(ZegoVideoBackendType type)

Callback notification for video backend changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
type	ZegoVideoBackendType	Video backend type.

Details

Callback notification for changes in the video backend used by the engine.

Caution: 1. When the developer calls [destroyEngine], this notification will not be triggered because the resources of the SDK are completely released. 2. If there is no special need, the developer does not need to pay attention to this callback.

Available since: 3.18.0

onRoomStateUpdate

public void onRoomStateUpdate(String roomID, ZegoRoomState state, int errorCode, JSONObject extendedData)

Notification of the room connection state changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID, a string of up to 128 bytes in length.
state	ZegoRoomState	Changed room state.
errorCode	int	Error code, For details, please refer to Common Error Codes.
extendedData	JSONObject	Extended Information with state updates. When the room login is successful, the key "room_session_id" can be used to obtain the unique RoomSessionID of each audio and video communication, which identifies the continuous communication from the first user in the room to the end of the audio and video communication. It can be used in scenarios such as call quality scoring and call problem diagnosis.

Details

This callback is triggered when the connection status of the room changes, and the reason for the change is notified.For versions 2.18.0 and above, it is recommended to use the onRoomStateChanged callback instead of the onRoomStateUpdate callback to monitor room state changes.

Use cases: Developers can use this callback to determine the status of the current user in the room. When to trigger:

The developer will receive this notification when calling the [loginRoom], [logoutRoom], [switchRoom] functions.
This notification may also be received when the network condition of the user's device changes (SDK will automatically log in to the room when disconnected, please refer to [Does ZEGO SDK support a fast reconnection for temporary disconnection] for details](https://docs.zegocloud.com/faq/reconnect?product=ExpressVideo&platform=all).

Caution: If the connection is being requested for a long time, the general probability is that the user's network is unstable.
Related APIs: [loginRoom]、[logoutRoom]、[switchRoom]

Available since: 1.1.0
Restrictions: None.

onRoomStateChanged

public  void onRoomStateChanged(String roomID, ZegoRoomStateChangedReason reason, int errorCode, JSONObject extendedData)

Notification of the room connection state changes, including specific reasons for state change.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID, a string of up to 128 bytes in length.
reason	ZegoRoomStateChangedReason	Room state change reason.
errorCode	int	Error code, please refer to the error codes document https://doc-en.zego.im/en/5548.html for details.
extendedData	JSONObject	Extended Information with state updates. When the room login is successful, the key "room_session_id" can be used to obtain the unique RoomSessionID of each audio and video communication, which identifies the continuous communication from the first user in the room to the end of the audio and video communication. It can be used in scenarios such as call quality scoring and call problem diagnosis.

Details

Use cases: Developers can use this callback to determine the status of the current user in the room. When to trigger: Users will receive this notification when they call room functions (refer to [Related APIs]). 2. This notification may also be received when the user device's network conditions change (SDK will automatically log in to the room again when the connection is disconnected, refer to https://doc-zh.zego.im/faq/reconnect ).
Caution: If the connection is being requested for a long time, the general probability is that the user's network is unstable.
Related APIs: [loginRoom], [logoutRoom], [switchRoom]

Available since: 2.18.0
Restrictions: None.

onRoomUserUpdate

public void onRoomUserUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoUser> userList)

The callback triggered when the number of other users in the room increases or decreases.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
updateType	ZegoUpdateType	Update type (add/delete).
userList	ArrayList<ZegoUser>	List of users changed in the current room.

Details

When other users in the room are online or offline, which causes the user list in the room to change, the developer will be notified through this callback.

Use cases: Developers can use this callback to update the user list display in the room in real time. When to trigger:
1. When the user logs in to the room for the first time, if there are other users in the room, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeAdd], and userList is the other users in the room at this time.
2. The user is already in the room. If another user logs in to the room through the [loginRoom] or [switchRoom] functions, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeAdd].
3. If other users log out of this room through the [logoutRoom] or [switchRoom] functions, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeDelete].
4. The user is already in the room. If another user is kicked out of the room from the server, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeDelete].
Related APIs: [loginRoom]、[logoutRoom]、[switchRoom]

Available since: 1.1.0
Restrictions: If developers need to use ZEGO room users notifications, please ensure that the [ZegoRoomConfig] sent by each user when logging in to the room has the [isUserStatusNotify] property set to true, otherwise the callback notification will not be received.

onRoomOnlineUserCountUpdate

public void onRoomOnlineUserCountUpdate(String roomID, int count)

The callback triggered every 30 seconds to report the current number of online users.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
count	int	Count of online users.

Details

This method will notify the user of the current number of online users in the room.

Use cases: Developers can use this callback to show the number of user online in the current room.
When to call /Trigger: After successfully logging in to the room.
Caution: 1. This function is called back every 30 seconds. 2. Because of this design, when the number of users in the room exceeds 500, there will be some errors in the statistics of the number of online people in the room.

Available since: 1.7.0
Restrictions: None.

onRoomStreamUpdate

public  void onRoomStreamUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoStream> streamList, JSONObject extendedData)

The callback triggered when the number of streams published by the other users in the same room increases or decreases.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
updateType	ZegoUpdateType	Update type (add/delete).
streamList	ArrayList<ZegoStream>	Updated stream list.
extendedData	JSONObject	Extended information with stream updates.When receiving a stream deletion notification, the developer can convert the string into a json object to get the stream_delete_reason field, which is an array of stream deletion reasons, and the stream_delete_reason[].code field may have the following values: 1 (the user actively stops publishing stream) ; 2 (user heartbeat timeout); 3 (user repeated login); 4 (user kicked out); 5 (user disconnected); 6 (removed by the server).

Details

When other users in the room start publishing stream or stop publishing stream, the streaming list in the room changes, and the developer will be notified through this callback.

Use cases: This callback is used to monitor stream addition or stream deletion notifications of other users in the room. Developers can use this callback to determine whether other users in the same room start or stop publishing stream, so as to achieve active playing stream [startPlayingStream] or take the initiative to stop the playing stream [stopPlayingStream], and use it to change the UI controls at the same time. When to trigger:
1. When the user logs in to the room for the first time, if there are other users publishing streams in the room, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeAdd], and streamList is an existing stream list.
2. The user is already in the room. if another user adds a new push, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeAdd].
3. The user is already in the room. If other users stop streaming, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeDelete].
4. The user is already in the room. If other users leave the room, the SDK will trigger a callback notification with updateType being [ZegoUpdateTypeDelete].

Available since: 1.1.0
Restrictions: None.

onRoomStreamExtraInfoUpdate

public void onRoomStreamExtraInfoUpdate(String roomID, ArrayList<ZegoStream> streamList)

The callback triggered when there is an update on the extra information of the streams published by other users in the same room.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
streamList	ArrayList<ZegoStream>	List of streams that the extra info was updated.

Details

All users in the room will be notified by this callback when the extra information of the stream in the room is updated.

Use cases: Users can realize some business functions through the characteristics of stream extra information consistent with stream life cycle.
When to call /Trigger: When a user publishing the stream update the extra information of the stream in the same room, other users in the same room will receive the callback.
Caution: Unlike the stream ID, which cannot be modified during the publishing process, the stream extra information can be updated during the life cycle of the corresponding stream ID.
Related APIs: Users who publish stream can set extra stream information through [setStreamExtraInfo].

Available since: 1.1.0
Restrictions: None.

onRoomExtraInfoUpdate

public void onRoomExtraInfoUpdate(String roomID, ArrayList<ZegoRoomExtraInfo> roomExtraInfoList)

The callback triggered when there is an update on the extra information of the room.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
roomExtraInfoList	ArrayList<ZegoRoomExtraInfo>	List of the extra info updated.

Details

After the room extra information is updated, all users in the room will be notified except update the room extra information user.

Use cases: Extra information for the room.
When to call /Trigger: When a user update the room extra information, other users in the same room will receive the callback.
Related APIs: Users can update room extra information through [setRoomExtraInfo] function.

Available since: 1.1.0
Restrictions: None.

onRoomTokenWillExpire

public void onRoomTokenWillExpire(String roomID, int remainTimeInSecond)

Callback notification that room Token authentication is about to expire.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID where the user is logged in, a string of up to 128 bytes in length.
remainTimeInSecond	int	The remaining time before the token expires.

Details

The callback notification that the room Token authentication is about to expire, please use [renewToken] to update the room Token authentication.

Use cases: In order to prevent illegal entry into the room, it is necessary to perform authentication control on login room, push streaming, etc., to improve security.
When to call /Trigger: 30 seconds before the Token expires, the SDK will call [onRoomTokenWillExpire] to notify developer.
Caution: The token contains important information such as the user's room permissions, publish stream permissions, and effective time, please refer to https://docs.zegocloud.com/article/11649.
Related APIs: When the developer receives this callback, he can use [renewToken] to update the token authentication information.

Available since: 2.8.0
Restrictions: None.

onPublisherStateUpdate

public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData)

The callback triggered when the state of stream publishing changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
state	ZegoPublisherState	State of publishing stream.
errorCode	int	The error code corresponding to the status change of the publish stream, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.
extendedData	JSONObject	Extended information with state updates, include playing stream CDN address.

Details

After calling the [startPublishingStream] successfully, the notification of the publish stream state change can be obtained through the callback function. You can roughly judge the user's uplink network status based on whether the state parameter is in [PUBLISH_REQUESTING].

Caution: The parameter [extendedData] is extended information with state updates. If you use ZEGO's CDN content distribution network, after the stream is successfully published, the keys of the content of this parameter are [flv_url_list], [rtmp_url_list], [hls_url_list], these correspond to the publishing stream URLs of the flv, rtmp, and hls protocols.
Related callbacks: After calling the [startPlayingStream] successfully, the notification of the play stream state change can be obtained through the callback function [onPlayerStateUpdate]. You can roughly judge the user's downlink network status based on whether the state parameter is in [PLAY_REQUESTING].

Available since: 1.1.0

onPublisherQualityUpdate

public void onPublisherQualityUpdate(String streamID, ZegoPublishStreamQuality quality)

Callback for current stream publishing quality.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
quality	ZegoPublishStreamQuality	Publishing stream quality, including audio and video framerate, bitrate, RTT, etc.

Details

After calling the [startPublishingStream] successfully, the callback will be received every 3 seconds default(If you need to change the time, please contact the instant technical support to configure). Through the callback, the collection frame rate, bit rate, RTT, packet loss rate and other quality data of the published audio and video stream can be obtained, and the health of the publish stream can be monitored in real time.You can monitor the health of the published audio and video streams in real time according to the quality parameters of the callback function, in order to show the uplink network status in real time on the device UI.

Caution: If you does not know how to use the parameters of this callback function, you can only pay attention to the [level] field of the [quality] parameter, which is a comprehensive value describing the uplink network calculated by SDK based on the quality parameters.
Related callbacks: After calling the [startPlayingStream] successfully, the callback [onPlayerQualityUpdate] will be received every 3 seconds. You can monitor the health of play streams in real time based on quality data such as frame rate, code rate, RTT, packet loss rate, etc.

Available since: 1.1.0

onPublisherCapturedAudioFirstFrame

public void onPublisherCapturedAudioFirstFrame()

The callback triggered when the first audio frame is captured.

Declared in callback/IZegoEventHandler.java

This callback will be received when the SDK starts the microphone to capture the first frame of audio data. If this callback is not received, the audio capture device is occupied or abnormal.

Trigger: When the engine of the audio/video module inside the SDK starts, the SDK will go and collect the audio data from the local device and will receive the callback at that time.
Related callbacks: Determine if the SDK actually collected video data by the callback function [onPublisherCapturedVideoFirstFrame], determine if the SDK has rendered the first frame of video data collected by calling back [onPublisherRenderVideoFirstFrame].

Available since: 1.1.0

onPublisherCapturedVideoFirstFrame

public void onPublisherCapturedVideoFirstFrame(ZegoPublishChannel channel)

The callback triggered when the first video frame is captured.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

The SDK will receive this callback when the first frame of video data is captured. If this callback is not received, the video capture device is occupied or abnormal.

Trigger: When the SDK's internal audio/video module's engine starts, the SDK will collect video data from the local device and will receive this callback.
Related callbacks: Determine if the SDK actually collected audio data by the callback function [onPublisherCapturedAudioFirstFrame], determine if the SDK has rendered the first frame of video data collected by calling back [onPublisherRenderVideoFirstFrame].

Available since: 1.1.0

onPublisherSendAudioFirstFrame

public void onPublisherSendAudioFirstFrame(ZegoPublishChannel channel)

The callback triggered when the first audio frame is sent.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio stream, you can ignore this parameter.

Details

After the [startPublishingStream] function is called successfully, this callback will be called when SDK received the first frame of audio data. Developers can use this callback to determine whether SDK has actually collected audio data. If the callback is not received, the audio capture device is occupied or abnormal.

Trigger: In the case of no startPublishingStream audio stream, the first startPublishingStream audio stream, it will receive this callback.
Related callbacks: After the [startPublishingStream] function is called successfully, determine if the SDK actually collected video data by the callback function [onPublisherCapturedVideoFirstFrame], determine if the SDK has rendered the first frame of video data collected by calling back [onPublisherRenderVideoFirstFrame].

Available since: 3.5.0

onPublisherSendVideoFirstFrame

public void onPublisherSendVideoFirstFrame(ZegoPublishChannel channel)

The callback triggered when the first video frame is sent.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one video stream, you can ignore this parameter.

Details

After the [startPublishingStream] function is called successfully, this callback will be called when SDK received the first frame of video data. Developers can use this callback to determine whether SDK has actually collected video data. If the callback is not received, the video capture device is occupied or abnormal.

Trigger: In the case of no startPublishingStream video stream, the first startPublishingStream video stream, it will receive this callback.
Related callbacks: After the [startPublishingStream] function is called successfully, determine if the SDK actually collected audio data by the callback function [onPublisherCapturedAudioFirstFrame], determine if the SDK has rendered the first frame of video data collected by calling back [onPublisherRenderVideoFirstFrame].

Available since: 3.5.0

onPublisherRenderVideoFirstFrame

public void onPublisherRenderVideoFirstFrame(ZegoPublishChannel channel)

The callback triggered when the first video frame is rendered.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

this callback will be called after SDK rendered the first frame of video data captured. This interface is for preview rendering. The first frame callback is only available for external collection and internal preview. If it is not for SDK rendering, there is no such callback.

Related callbacks: After the [startPublishingStream] function is called successfully, determine if the SDK actually collected audio data by the callback function [onPublisherCapturedAudioFirstFrame], determine if the SDK actually collected video data by the callback function [onPublisherCapturedVideoFirstFrame].

Available since: 2.4.0

onPublisherVideoSizeChanged

public void onPublisherVideoSizeChanged(int width, int height, ZegoPublishChannel channel)

The callback triggered when the video capture resolution changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
width	int	Video capture resolution width.
height	int	Video capture resolution height.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

When the audio and video stream is not published [startPublishingStream] or previewed [startPreview] for the first time, the publishing stream or preview first time, that is, the engine of the audio and video module inside the SDK is started, the video data of the local device will be collected, and the collection resolution will change at this time.

Trigger: After the successful publish [startPublishingStream], the callback will be received if there is a change in the video capture resolution in the process of publishing the stream.
Use cases: You can use this callback to remove the cover of the local preview UI and similar operations.You can also dynamically adjust the scale of the preview view based on the resolution of the callback.
Caution: What is notified during external collection is the change in encoding resolution, which will be affected by flow control.

Available since: 1.1.0

onPublisherRelayCDNStateUpdate

public void onPublisherRelayCDNStateUpdate(String streamID, ArrayList<ZegoStreamRelayCDNInfo> infoList)

The callback triggered when the state of relayed streaming to CDN changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
infoList	ArrayList<ZegoStreamRelayCDNInfo>	List of information that the current CDN is relaying.

Details

Developers can use this callback to determine whether the audio and video streams of the relay CDN are normal. If they are abnormal, further locate the cause of the abnormal audio and video streams of the relay CDN and make corresponding disaster recovery strategies.

Trigger: After the ZEGO RTC server relays the audio and video streams to the CDN, this callback will be received if the CDN relay status changes, such as a stop or a retry.
Caution: If you do not understand the cause of the abnormality, you can contact ZEGO technicians to analyze the specific cause of the abnormality.

Available since: 1.1.0

onPublisherVideoEncoderChanged

public  void onPublisherVideoEncoderChanged(ZegoVideoCodecID fromCodecID, ZegoVideoCodecID toCodecID, ZegoPublishChannel channel)

The callback triggered when the video encoder changes in publishing stream.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
fromCodecID	ZegoVideoCodecID	Video codec ID before the change.
toCodecID	ZegoVideoCodecID	Video codec ID after the change.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

After the H.265 automatic downgrade policy is enabled, if H.265 encoding is not supported or the encoding fails during the streaming process with H.265 encoding, the SDK will actively downgrade to the specified encoding (H.264), and this callback will be triggered at this time. When to trigger: In the process of streaming with H.265 encoding, if H.265 encoding is not supported or encoding fails, the SDK will actively downgrade to the specified encoding (H.264), and this callback will be triggered at this time.

Caution: When this callback is triggered, if local video recording or cloud recording is in progress, multiple recording files will be generated. Developers need to collect all the recording files for processing after the recording ends. When this callback is triggered, because the streaming code has changed, the developer can evaluate whether to notify the streaming end, so that the streaming end can deal with it accordingly.

Available since: 2.12.0

onPublisherStreamEvent

public void onPublisherStreamEvent(ZegoStreamEvent eventID, String streamID, String extraInfo)

The callback triggered when publishing stream.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
eventID	ZegoStreamEvent	Publish stream event ID
streamID	String	Stream ID.
extraInfo	String	extra info. it is in JSON format. Included information includes "url" for address, "streamProtocol" for stream protocol, including rtmp, flv, avertp, hls, webrtc, etc. "netProtocol" for network protocol, including tcp, udp, quic, "resourceType" for resource type , including cdn, rtc, l3.

Details

After start publishing stream, this callback will return the current stream address, resource type and protocol-related information. When to trigger: Publish and retry publish events.

Caution: None.

Available since: 2.18.0

onVideoObjectSegmentationStateChanged

public  void onVideoObjectSegmentationStateChanged(ZegoObjectSegmentationState state, ZegoPublishChannel channel, int errorCode)

The video object segmentation state changed.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
state	ZegoObjectSegmentationState	Object segmentation state.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.
errorCode	int	The error code corresponding to the status change of the object segmentation, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.

Details

The object segmentation state of the stream publishing end changes. When to trigger: When [enableVideoObjectSegmentation] enables or disables object segmentation, notify the developer whether to enable object segmentation according to the actual state.

Caution: This callback depends on enabling preview or stream publishing.

Available since: 3.4.0

onPublisherLowFpsWarning

public void onPublisherLowFpsWarning(ZegoVideoCodecID codecID, ZegoPublishChannel channel)

Video encoding low frame rate warning.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
codecID	ZegoVideoCodecID	Video codec ID.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

Video encoding low frame rate warning. When to trigger: This callback triggered by low frame rate in video encoding.

Caution: This callback is disabled by default, if necessary, please contact ZEGO technical support.

Available since: 3.8.0

onPublisherDummyCaptureImagePathError

public void onPublisherDummyCaptureImagePathError(int errorCode, String path, ZegoPublishChannel channel)

The notification for setting the path of the static image displayed when the camera is turned off is incorrect.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	error code.
path	String	Image path.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

The notification for setting the path of the static image displayed when the camera is turned off is incorrect. When to trigger: If the path for the image is set using [setDummyCaptureImagePath], but the image cannot be obtained during streaming, this callback will be triggered.

Caution: Please make sure that the image path is correct and has read permission before setting it.

Available since: 3.9.0

onPublisherFaceDetectInfo

public void onPublisherFaceDetectInfo(ZegoFaceDetectionInfo info, ZegoPublishChannel channel)

Face detection information update notification.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
info	ZegoFaceDetectionInfo	Face detection information.
channel	ZegoPublishChannel	Publishing stream channel.If you only publish one audio and video stream, you can ignore this parameter.

Details

The notification for face detection. When to trigger: Turn on face detection through the [enableFaceDetection] interface, and this callback will be triggered when the camera is started or the number of faces changes.

Caution: The callback is low-frequency and cannot be used with the custom video pre-processing function.

Available since: 3.20.0

onPlayerStateUpdate

public void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData)

The callback triggered when the state of stream playing changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	stream ID.
state	ZegoPlayerState	State of playing stream.
errorCode	int	The error code corresponding to the status change of the playing stream, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.
extendedData	JSONObject	Extended Information with state updates. As the standby, only an empty json table is currently returned.

Details

After calling the [startPlayingStream] successfully, the notification of the playing stream state change can be obtained through the callback function. You can roughly judge the user's downlink network status based on whether the state parameter is in [PLAY_REQUESTING]. When to trigger: After calling the [startPublishingStream], this callback is triggered when a playing stream's state changed.

Related callbacks: After calling the [startPublishingStream] successfully, the notification of the publish stream state change can be obtained through the callback function [onPublisherStateUpdate]. You can roughly judge the user's uplink network status based on whether the state parameter is in [PUBLISH_REQUESTING].

Available since: 1.1.0

onPlayerSwitched

public void onPlayerSwitched(String streamID, int errorCode)

Switch playing stream callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	The stream ID currently playing.
errorCode	int	The error code corresponding to the result of the switch stream, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.

Details

After calling the [switchPlayingStream] successfully, the result of switching streams can be obtained through this callback function. When to trigger: After calling the [switchPlayingStream], this callback is triggered when a switch stream request ultimately succeeds or fails.

Related callbacks: After the stream switching is successful or failed, you can obtain the current streaming status through the callback function [onPlayerStateUpdate].

Available since: 3.16.0

onPlayerQualityUpdate

public void onPlayerQualityUpdate(String streamID, ZegoPlayStreamQuality quality)

Callback for current stream playing quality.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
quality	ZegoPlayStreamQuality	Playing stream quality, including audio and video framerate, bitrate, RTT, etc.

Details

After calling the [startPlayingStream] successfully, the callback will be received every 3 seconds default(If you need to change the time, please contact the instant technical support to configure). Through the callback, the collection frame rate, bit rate, RTT, packet loss rate and other quality data can be obtained, and the health of the played audio and video streams can be monitored in real time.

Use cases: You can monitor the health of the played audio and video streams in real time according to the quality parameters of the callback function, in order to show the downlink network status on the device UI in real time.
Caution: If you does not know how to use the various parameters of the callback function, you can only focus on the level field of the quality parameter, which is a comprehensive value describing the downlink network calculated by SDK based on the quality parameters.
Related callbacks: After calling the [startPublishingStream] successfully, a callback [onPublisherQualityUpdate] will be received every 3 seconds. You can monitor the health of publish streams in real time based on quality data such as frame rate, code rate, RTT, packet loss rate, etc.

Available since: 1.1.0

onPlayerMediaEvent

public void onPlayerMediaEvent(String streamID, ZegoPlayerMediaEvent event)

The callback triggered when a media event occurs during streaming playing.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
event	ZegoPlayerMediaEvent	Specific events received when playing the stream.

Details

This callback is used to receive pull streaming events.

Use cases: You can use this callback to make statistics on stutters or to make friendly displays in the UI of the app. When to trigger: After calling the [startPublishingStream], this callback is triggered when an event such as audio and video jamming and recovery occurs in the playing stream.

Available since: 1.1.0

onPlayerRecvAudioFirstFrame

public void onPlayerRecvAudioFirstFrame(String streamID)

The callback triggered when the first audio frame is received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK received the first frame of audio data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: This callback is triggered when SDK receives the first frame of audio data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerRecvVideoFirstFrame] determines whether the SDK has received the video data, and the callback [onPlayerRenderVideoFirstFrame] determines whether the SDK has rendered the first frame of the received video data.

Available since: 1.1.0

onPlayerSyncRecvAudioFirstFrame

public void onPlayerSyncRecvAudioFirstFrame(String streamID)

The callback triggered when the first audio frame is received. Please do not call the SDK interface in the callback thread.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK received the first frame of audio data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: This callback is triggered when SDK receives the first frame of audio data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerSyncRecvVideoFirstFrame] determines whether the SDK has received the video data, and the callback [onPlayerSyncRecvRenderVideoFirstFrame] determines whether the SDK has rendered the first frame of the received video data.

Available since: 3.22.0

onPlayerRecvVideoFirstFrame

public void onPlayerRecvVideoFirstFrame(String streamID)

The callback triggered when the first video frame is received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK received the first frame of video data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: This callback is triggered when SDK receives the first frame of video data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerRecvAudioFirstFrame] determines whether the SDK has received the audio data, and the callback [onPlayerRenderVideoFirstFrame] determines whether the SDK has rendered the first frame of the received video data.

Available since: 1.1.0

onPlayerSyncRecvVideoFirstFrame

public void onPlayerSyncRecvVideoFirstFrame(String streamID)

The callback triggered when the first video frame is received. Please do not call the SDK interface in the callback thread.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK received the first frame of video data.

Use cases: Developer can use this callback to count time consuming that take the first frame time.
Trigger: This callback is triggered when SDK receives the first frame of video data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerSyncRecvAudioFirstFrame] determines whether the SDK has received the audio data, and the callback [onPlayerSyncRecvRenderVideoFirstFrame] determines whether the SDK has rendered the first frame of the received video data.

Available since: 3.8.0

onPlayerRenderVideoFirstFrame

public void onPlayerRenderVideoFirstFrame(String streamID)

The callback triggered when the first video frame is rendered.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK rendered the first frame of video data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: This callback is triggered when SDK rendered the first frame of video data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerRecvAudioFirstFrame] determines whether the SDK has received the audio data, and the callback [onPlayerRecvVideoFirstFrame] determines whether the SDK has received the video data.

Available since: 1.1.0

onPlayerSyncRecvRenderVideoFirstFrame

public void onPlayerSyncRecvRenderVideoFirstFrame(String streamID)

The callback triggered when the first video frame is rendered. Please do not call the SDK interface in the callback thread.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After the [startPlayingStream] function is called successfully, this callback will be called when SDK rendered the first frame of video data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: This callback is triggered when SDK rendered the first frame of video data from the network.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerSyncRecvAudioFirstFrame] determines whether the SDK has received the audio data, and the callback [onPlayerSyncRecvVideoFirstFrame] determines whether the SDK has received the video data.

Available since: 3.22.0

onPlayerRenderCameraVideoFirstFrame

public void onPlayerRenderCameraVideoFirstFrame(String streamID)

Calls back when the stream playing end renders the first frame of the video from the remote camera.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.

Details

After calling the [startPlayingStream] function to pull the stream successfully, the SDK will receive this callback after pulling the stream and rendering the first frame of remote camera video data.

Use cases: Developer can use this callback to count time consuming that take the first frame time or update the UI for playing stream.
Trigger: After the remote [enableCamera] enables the camera, or after [mutePublishStreamVideo] is true and starts to send video data, the SDK will receive this callback after playing the stream and rendering the first frame of the remote camera video data.
Caution: It is only applicable when the remote end uses the camera to push the stream. Only applicable to RTC publishing and playing streaming scenarios.
Related callbacks: After a successful call to [startPlayingStream], the callback [onPlayerRecvVideoFirstFrame] determines whether the SDK has received the video data.

Available since: 3.0.0

onPlayerRenderMultiViewFirstFrame

public void onPlayerRenderMultiViewFirstFrame(String streamID, String viewContext)

When multiple playing canvas are set, the callback will be triggered after one view renders the first frame of the video.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
viewContext	String	Context of view.

Details

Call [startPlayingStream] to play stream and call [setPlayingCanvas] to add multiple views, this callback will be called when SDK rendered the first frame of video data.

Use cases: Developer can use this callback to update the UI for playing stream.
Trigger: The user playing the mixed stream, adds multiple views through [setPlayingCanvas], and sets the correct viewContext parameters, which will trigger this callback after the corresponding view has rendered the first frame of video data.
Related callbacks: After a successful call to [startPlayingStream], the callback function [onPlayerRecvAudioFirstFrame] determines whether the SDK has received the audio data, and the callback [onPlayerRecvVideoFirstFrame] determines whether the SDK has received the video data.

Available since: 3.21.0

onPlayerVideoSizeChanged

public void onPlayerVideoSizeChanged(String streamID, int width, int height)

The callback triggered when the stream playback resolution changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
width	int	Video decoding resolution width.
height	int	Video decoding resolution height.

Details

After the [startPlayingStream] function is called successfully, the play resolution will change when the first frame of video data is received, or when the publisher changes the encoding resolution by calling [setVideoConfig], or when the network traffic control strategies work.

Use cases: Developers can update or switch the UI components that actually play the stream based on the final resolution of the stream.
Trigger: After the [startPlayingStream] function is called successfully, this callback is triggered when the video resolution changes while playing the stream.
Caution:

If the stream is only audio data, the callback will not be triggered.
If the user enables custom video rendering of the ZegoVideoBufferTypeEncodedData type, the SDK is not responsible for video decoding and will not trigger this callback.

Available since: 1.1.0

onPlayerRecvSEI

deprecated

public void onPlayerRecvSEI(String streamID, byte[] data)

The callback triggered when Supplemental Enhancement Information is received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
data	byte[]	SEI content.

Details

After the [startPlayingStream] function is called successfully, when the remote stream sends SEI (such as directly calling [sendSEI], audio mixing with SEI data, and sending custom video capture encoded data with SEI, etc.), the local end will receive this callback.

Trigger: After the [startPlayingStream] function is called successfully, when the remote stream sends SEI, the local end will receive this callback.
Caution: 1.The customer can directly operate the UI control in this callback function.

Since the video encoder itself generates an SEI with a payload type of 5, or when a video file is used for publishing, such SEI may also exist in the video file. Therefore, if the developer needs to filter out this type of SEI, it can be before [createEngine] Call [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]. Among them, unregister_sei_filter is the key, and XXXXX is the uuid filter string to be set.
When [mutePlayStreamVideo] or [muteAllPlayStreamVideo] is called to set only the audio stream to be pulled, the SEI will not be received.

Available since: 1.1.0

Deprecated

It will be deprecated in version 3.4.0 and above. Please use the [onPlayerSyncRecvSEI] function instead.

onPlayerSyncRecvSEI

public void onPlayerSyncRecvSEI(String streamID, byte[] data)

The callback triggered when Supplemental Enhancement Information is received synchronously.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
data	byte[]	SEI content.

Details

Trigger: After the [startPlayingStream] function is called successfully, when the remote stream sends SEI, the local end will receive this callback.
Caution:

Since the video encoder itself generates an SEI with a payload type of 5, or when a video file is used for publishing, such SEI may also exist in the video file. Therefore, if the developer needs to filter out this type of SEI, it can be before [createEngine] Call [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]. Among them, unregister_sei_filter is the key, and XXXXX is the uuid filter string to be set.
When [mutePlayStreamVideo] or [muteAllPlayStreamVideo] is called to set only the audio stream to be pulled, the SEI will not be received.

Available since: 3.4.0

onPlayerRecvMediaSideInfo

public void onPlayerRecvMediaSideInfo(ZegoMediaSideInfo info)

The callback triggered when Supplemental Enhancement Information is received synchronously.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
info	ZegoMediaSideInfo	SEI Callback info.

Details

Trigger: After the [startPlayingStream] function is called successfully, when the remote stream sends SEI, the local end will receive this callback.
Caution: 1. Since the video encoder itself generates an SEI with a payload type of 5, or when a video file is used for publishing, such SEI may also exist in the video file. Therefore, if the developer needs to filter out this type of SEI, it can be before [createEngine] Call [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]. Among them, unregister_sei_filter is the key, and XXXXX is the uuid filter string to be set. 2. When [mutePlayStreamVideo] or [muteAllPlayStreamVideo] is called to set only the audio stream to be pulled, the SEI will not be received.

Available since: 3.9.0

onPlayerRecvAudioSideInfo

public void onPlayerRecvAudioSideInfo(String streamID, byte[] data)

Receive the audio side information content of the remote stream.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
data	byte[]	Audio side information content.

Details

After the [startPlayingStream] function is called successfully, when the remote stream sends audio side information, the local end will receive this callback.

Trigger: After the [startPlayingStream] function is called successfully, when the remote stream sends audio side information, the local end will receive this callback.
Caution: 1. When [mutePlayStreamAudio] or [muteAllPlayStreamAudio] is called to set only the video stream to be pulled, the audio side information not be received. 2. Due to factors such as the network, the received data may be missing, but the order is guaranteed.
Related APIs: Send audio side information by the [sendAudioSideInfo] function.

Available since: 2.19.0

onPlayerLowFpsWarning

public void onPlayerLowFpsWarning(ZegoVideoCodecID codecID, String streamID)

Playing stream low frame rate warning.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
codecID	ZegoVideoCodecID	Video codec ID.
streamID	String	Stream ID.

Details

This callback triggered by low frame rate when playing stream. When to trigger: This callback triggered by low frame rate when playing stream.

Caution: If the callback is triggered when the user playing the h.265 stream, you can stop playing the h.265 stream and switch to play the H.264 stream.

Available since: 2.14.0

onPlayerStreamEvent

public void onPlayerStreamEvent(ZegoStreamEvent eventID, String streamID, String extraInfo)

The callback triggered when playing stream.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
eventID	ZegoStreamEvent	Play stream event ID
streamID	String	Stream ID.
extraInfo	String	extra info. it is in JSON format. Included information includes "url" for address, "streamProtocol" for stream protocol, including rtmp, flv, avertp, hls, webrtc, etc. "netProtocol" for network protocol, including tcp, udp, quic, "resourceType" for resource type , including cdn, rtc, l3.

Details

After start playing stream, this callback will return the current stream address, resource type and protocol-related information. When to trigger: Play and retry play events.

Caution: None.

Available since: 2.18.0

onPlayerVideoSuperResolutionUpdate

public void onPlayerVideoSuperResolutionUpdate(String streamID, ZegoSuperResolutionState state, int errorCode)

Playing stream video super resolution enabled state changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
state	ZegoSuperResolutionState	Video super resolution state.
errorCode	int	Error code, please refer to the error codes document https://docs.zegocloud.com/en/5548.html for details.

Details

Playing stream video super resolution enabled state changes. When to trigger: When [enableVideoSuperResolution] enables or disables video super resolution, the developer will be notified whether to enable video super resolution according to the actual situation when playing stream video rendering.

Caution: None.

Available since: 3.0.0

onMixerRelayCDNStateUpdate

public void onMixerRelayCDNStateUpdate(String taskID, ArrayList<ZegoStreamRelayCDNInfo> infoList)

The callback triggered when the state of relayed streaming of the mixed stream to CDN changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
taskID	String	The mixing task ID. Value range: the length does not exceed 256. Caution: This parameter is in string format and cannot contain URL keywords, such as 'http' and '?' etc., otherwise the push and pull flow will fail. Only supports numbers, English characters and'~','!','@','$','%','^','&','*','(',')','_' ,'+','=','-','`',';',''',',','.','<','>',''.
infoList	ArrayList<ZegoStreamRelayCDNInfo>	List of information that the current CDN is being mixed.

Details

The general situation of the mixing task on the ZEGO RTC server will push the output stream to the CDN using the RTMP protocol, and the state change during the push process will be notified from the callback function.

Use cases: It is often used when multiple video images are required to synthesize a video using mixed streaming, such as education, live teacher and student images. When to trigger: After the developer calls the [startMixerTask] function to start mixing, when the ZEGO RTC server pushes the output stream to the CDN, there is a state change.
Related callbacks: Develop can get the sound update notification of each single stream in the mixed stream through [OnMixerSoundLevelUpdate].
Related APIs: Develop can start a mixed flow task through [startMixerTask].

Available since: 1.2.1
Restrictions: None.

onMixerSoundLevelUpdate

public void onMixerSoundLevelUpdate(HashMap<Integer, Float> soundLevels)

The callback triggered when the sound level of any input stream changes in the stream mixing process.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevels	HashMap<Integer, Float>	The sound key-value pair of each single stream in the mixed stream, the key is the soundLevelID of each single stream, and the value is the sound value of the corresponding single stream. Value range: The value range of value is 0.0 ~ 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.).

Details

Developers can use this callback to display the effect of which stream’s anchor is talking on the UI interface of the mixed stream of the audience.

Use cases: It is often used when multiple video images are required to synthesize a video using mixed streaming, such as education, live teacher and student images. When to trigger: After the developer calls the [startPlayingStream] function to start playing the mixed stream. Callback notification period is 100 ms.
Related callbacks: [OnMixerRelayCDNStateUpdate] can be used to get update notification of mixing stream repost CDN status.
Related APIs: Develop can start a mixed flow task through [startMixerTask].

Available since: 1.2.1
Restrictions: The callback is triggered every 100 ms, and the trigger frequency cannot be set.Due to the high frequency of this callback, please do not perform time-consuming tasks or UI operations in this callback to avoid stalling.

onAutoMixerSoundLevelUpdate

public void onAutoMixerSoundLevelUpdate(HashMap<String, Float> soundLevels)

The callback triggered when the sound level of any input stream changes in the auto stream mixing process.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevels	HashMap<String, Float>	Sound level hash map, key is the streamID of every single stream in this mixer stream, value is the sound level value of that single stream, value ranging from 0.0 to 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.).

Details

According to this callback, user can obtain the sound level information of each stream pulled during auto stream mixing.

Use cases: Often used in voice chat room scenarios.Users can use this callback to show which streamer is speaking when an audience pulls a mixed stream.
Trigger: Call [startPlayingStream] function to pull the stream.
Related APIs: Users can call [startAutoMixerTask] function to start an auto stream mixing task.Users can call [stopAutoMixerTask] function to stop an auto stream mixing task.

Available since: 2.10.0

onCapturedSoundLevelUpdate

public void onCapturedSoundLevelUpdate(float soundLevel)

The local captured audio sound level callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevel	float	Locally captured sound level value, ranging from 0.0 to 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.) .

Details

The local captured audio sound level callback.

Trigger: After you start the sound level monitor by calling [startSoundLevelMonitor].
Caution: 1. The callback notification period is the parameter value set when the [startSoundLevelMonitor] is called. The callback value is the default value of 0 When you have not called the interface [startPublishingStream] and [startPreview]. 2. This callback is a high-frequency callback, and it is recommended not to do complex logic processing inside the callback.
Related APIs: Start sound level monitoring via [startSoundLevelMonitor]. Monitoring remote played audio sound level by callback [onRemoteSoundLevelUpdate]

Available since: 1.1.0

onCapturedSoundLevelInfoUpdate

public void onCapturedSoundLevelInfoUpdate(ZegoSoundLevelInfo soundLevelInfo)

The local captured audio sound level callback, supported vad.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevelInfo	ZegoSoundLevelInfo	Locally captured sound level value, ranging from 0.0 to 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.).

Details

The local captured audio sound level callback.

Trigger: After you start the sound level monitor by calling [startSoundLevelMonitor].
Caution: 1. The callback notification period is the parameter value set when the [startSoundLevelMonitor] is called. 2. This callback is a high-frequency callback, and it is recommended not to do complex logic processing inside the callback.
Related APIs: Start sound level monitoring via [startSoundLevelMonitor]. Monitoring remote played audio sound level by callback [onRemoteSoundLevelUpdate] or [onRemoteSoundLevelInfoUpdate].

Available since: 2.10.0

onRemoteSoundLevelUpdate

public void onRemoteSoundLevelUpdate(HashMap<String, Float> soundLevels)

The remote playing streams audio sound level callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevels	HashMap<String, Float>	Remote sound level hash map, key is the streamID, value is the sound level value of the corresponding streamID, value ranging from 0.0 to 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.).

Details

The remote playing streams audio sound level callback.

Trigger: After you start the sound level monitor by calling [startSoundLevelMonitor], you are in the state of playing the stream [startPlayingStream].
Caution: The callback notification period is the parameter value set when the [startSoundLevelMonitor] is called.
Related APIs: Start sound level monitoring via [startSoundLevelMonitor]. Monitoring local captured audio sound by callback [onCapturedSoundLevelUpdate] or [onCapturedSoundLevelInfoUpdate].

Available since: 1.1.0

onRemoteSoundLevelInfoUpdate

public void onRemoteSoundLevelInfoUpdate(HashMap<String, ZegoSoundLevelInfo> soundLevelInfos)

The remote playing streams audio sound level callback, supported vad.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
soundLevelInfos	HashMap<String, ZegoSoundLevelInfo>	Remote sound level hash map, key is the streamID, value is the sound level value of the corresponding streamID, value ranging from 0.0 to 100.0 (This value only represents the range of the sound level value returned by the callback, not the precision.).

Details

The remote playing streams audio sound level callback.

Trigger: After you start the sound level monitor by calling [startSoundLevelMonitor], you are in the state of playing the stream [startPlayingStream].
Caution: The callback notification period is the parameter value set when the [startSoundLevelMonitor] is called.
Related APIs: Start sound level monitoring via [startSoundLevelMonitor]. Monitoring local captured audio sound by callback [onCapturedSoundLevelUpdate] or [onCapturedSoundLevelInfoUpdate].

Available since: 2.10.0

onCapturedAudioSpectrumUpdate

public void onCapturedAudioSpectrumUpdate(float[] audioSpectrum)

The local captured audio spectrum callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
audioSpectrum	float[]	Locally captured audio spectrum value list. Spectrum value range is [0-2^30].

Details

The local captured audio spectrum callback.

Trigger: After you start the audio spectrum monitor by calling [startAudioSpectrumMonitor].
Caution: The callback notification period is the parameter value set when the [startAudioSpectrumMonitor] is called. The callback value is the default value of 0 When you have not called the interface [startPublishingStream] and [startPreview].
Related APIs: Start audio spectrum monitoring via [startAudioSpectrumMonitor]. Monitoring remote played audio spectrum by callback [onRemoteAudioSpectrumUpdate]

Available since: 1.1.0

onRemoteAudioSpectrumUpdate

public void onRemoteAudioSpectrumUpdate(HashMap<String, float[]> audioSpectrums)

The remote playing streams audio spectrum callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
audioSpectrums	HashMap<String, float[]>	Remote audio spectrum hash map, key is the streamID, value is the audio spectrum list of the corresponding streamID. Spectrum value range is [0-2^30]

Details

The remote playing streams audio spectrum callback.

Trigger: After you start the audio spectrum monitor by calling [startAudioSpectrumMonitor], you are in the state of playing the stream [startPlayingStream].
Caution: The callback notification period is the parameter value set when the [startAudioSpectrumMonitor] is called.
Related APIs: Start audio spectrum monitoring via [startAudioSpectrumMonitor]. Monitoring local played audio spectrum by callback [onCapturedAudioSpectrumUpdate].

Available since: 1.1.0

onLocalDeviceExceptionOccurred

public  void onLocalDeviceExceptionOccurred(ZegoDeviceExceptionType exceptionType, ZegoDeviceType deviceType, String deviceID)

The callback triggered when a local device exception occurred.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
exceptionType	ZegoDeviceExceptionType	The type of the device exception.
deviceType	ZegoDeviceType	The type of device where the exception occurred.
deviceID	String	Device ID. Currently, only desktop devices are supported to distinguish different devices; for mobile devices, this parameter will return an empty string.

Details

The callback triggered when a local device exception occurs.

Trigger: This callback is triggered when the function of the local audio or video device is abnormal.

Available since: 2.15.0

onRemoteCameraStateUpdate

public void onRemoteCameraStateUpdate(String streamID, ZegoRemoteDeviceState state)

The callback triggered when the state of the remote camera changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
state	ZegoRemoteDeviceState	Remote camera status.

Details

The callback triggered when the state of the remote camera changes.

Use cases: Developers of 1v1 education scenarios or education small class scenarios and similar scenarios can use this callback notification to determine whether the camera device of the remote publishing stream device is working normally, and preliminary understand the cause of the device problem according to the corresponding state.
Trigger: When the state of the remote camera device changes, such as switching the camera, by monitoring this callback, it is possible to obtain an event related to the far-end camera, which can be used to prompt the user that the video may be abnormal.
Caution: This callback will not be called back when the remote stream is play from the CDN, or when custom video acquisition is used at the peer.

Available since: 1.1.0

onRemoteMicStateUpdate

public void onRemoteMicStateUpdate(String streamID, ZegoRemoteDeviceState state)

The callback triggered when the state of the remote microphone changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
state	ZegoRemoteDeviceState	Remote microphone status.

Details

The callback triggered when the state of the remote microphone changes.

Use cases: Developers of 1v1 education scenarios or education small class scenarios and similar scenarios can use this callback notification to determine whether the microphone device of the remote publishing stream device is working normally, and preliminary understand the cause of the device problem according to the corresponding state.
Trigger: When the state of the remote microphone device is changed, such as switching a microphone, etc., by listening to the callback, it is possible to obtain an event related to the remote microphone, which can be used to prompt the user that the audio may be abnormal.
Caution: This callback will not be called back when the remote stream is play from the CDN, or when custom audio acquisition is used at the peer (But the stream is not published to the ZEGO RTC server.).

Available since: 1.1.0

onRemoteSpeakerStateUpdate

public void onRemoteSpeakerStateUpdate(String streamID, ZegoRemoteDeviceState state)

The callback triggered when the state of the remote speaker changes.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
streamID	String	Stream ID.
state	ZegoRemoteDeviceState	Remote speaker status.

Details

The callback triggered when the state of the remote microphone changes.

Use cases: Developers of 1v1 education scenarios or education small class scenarios and similar scenarios can use this callback notification to determine whether the speaker device of the remote publishing stream device is working normally, and preliminary understand the cause of the device problem according to the corresponding state.
Trigger: When the state of the remote speaker device changes, such as switching the speaker, by monitoring this callback, you can get events related to the remote speaker.
Caution: This callback will not be called back when the remote stream is play from the CDN.

Available since: 1.1.0

onAudioRouteChange

public void onAudioRouteChange(ZegoAudioRoute audioRoute)

Callback for device's audio route changed.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
audioRoute	ZegoAudioRoute	Current audio route.

Details

Callback for device's audio route changed.

Trigger: This callback will be called when there are changes in audio routing such as earphone plugging, speaker and receiver switching, etc.
Platform differences: Only supports iOS and Android.

Available since: 1.20.0

onAudioVADStateUpdate

public void onAudioVADStateUpdate(ZegoAudioVADStableStateMonitorType type, ZegoAudioVADType state)

Callback for audio VAD stable state update.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
type	ZegoAudioVADStableStateMonitorType	audio VAD monitor type
state	ZegoAudioVADType	VAD result

Details

Callback for audio VAD stable state update. When to trigger: the [startAudioVADStableStateMonitor] function must be called to start the audio VAD monitor and you must be in a state where it is publishing the audio and video stream or be in [startPreview] state.

Related APIs: [startAudioVADStableStateMonitor], [stopAudioVADStableStateMonitor].

Available since: 2.14.0
Restrictions: The callback notification period is 3 seconds.

onRecvRoomTransparentMessage

public void onRecvRoomTransparentMessage(String roomID, ZegoRoomRecvTransparentMessage message)

The callback triggered when Barrage Messages are received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID. Value range: The maximum length is 128 bytes.
message	ZegoRoomRecvTransparentMessage	recv message.

Details

This callback is used to receive room passthrough messages sent by other users in the same room. When to trigger: After calling [loginRoom] to login to the room, this callback is triggered if there is a user in the room who sends a message received by the specified client through the [sendTransparentMessage] function.

Caution: Barrage messages sent by users themselves will not be notified through this callback. When there are a large number of barrage messages in the room, the notification may be delayed, and some barrage messages may be lost.
Related callbacks: A bullet-screen message sent by the user himself is not notified by this callback. [sendTransparentMessage] specifies that only a server callback is used. This callback is not triggered.

Available since: 1.5.0
Restrictions: None

onIMRecvBroadcastMessage

public void onIMRecvBroadcastMessage(String roomID, ArrayList<ZegoBroadcastMessageInfo> messageList)

The callback triggered when Broadcast Messages are received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID. Value range: The maximum length is 128 bytes.
messageList	ArrayList<ZegoBroadcastMessageInfo>	List of received messages. Value range: Up to 50 messages can be received each time.

Details

This callback is used to receive broadcast messages sent by other users in the same room.

Use cases: Generally used in the live room. When to trigger: After calling [loginRoom] to log in to the room, if a user in the room sends a broadcast message via [sendBroadcastMessage] function, this callback will be triggered.
Caution: The broadcast message sent by the user will not be notified through this callback.
Related callbacks: You can receive room barrage messages through [onIMRecvBarrageMessage], and you can receive room custom signaling through [onIMRecvCustomCommand].

Available since: 1.2.1
Restrictions: None

onIMRecvBarrageMessage

public void onIMRecvBarrageMessage(String roomID, ArrayList<ZegoBarrageMessageInfo> messageList)

The callback triggered when Barrage Messages are received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID. Value range: The maximum length is 128 bytes.
messageList	ArrayList<ZegoBarrageMessageInfo>	List of received messages. Value range: Up to 50 messages can be received each time.

Details

This callback is used to receive barrage messages sent by other users in the same room.

Use cases: Generally used in scenarios where there is a large number of messages sent and received in the room and the reliability of the messages is not required, such as live barrage. When to trigger: After calling [loginRoom] to log in to the room, if a user in the room sends a barrage message through the [sendBarrageMessage] function, this callback will be triggered.
Caution: Barrage messages sent by users themselves will not be notified through this callback. When there are a large number of barrage messages in the room, the notification may be delayed, and some barrage messages may be lost.
Related callbacks: Develop can receive room broadcast messages through [onIMRecvBroadcastMessage], and can receive room custom signaling through [onIMRecvCustomCommand].

Available since: 1.5.0
Restrictions: None

onIMRecvCustomCommand

public void onIMRecvCustomCommand(String roomID, ZegoUser fromUser, String command)

The callback triggered when a Custom Command is received.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
roomID	String	Room ID. Value range: The maximum length is 128 bytes.
fromUser	ZegoUser	Sender of the command.
command	String	Command content received.Value range: The maximum length is 1024 bytes.

Details

This callback is used to receive custom command sent by other users in the same room.

Use cases: Generally used in the live room. When to trigger: After calling [loginRoom] to log in to the room, if other users in the room send custom signaling to the developer through the [sendCustomCommand] function, this callback will be triggered.
Caution: The custom command sent by the user himself will not be notified through this callback.
Related callbacks: You can receive room broadcast messages through [onIMRecvBroadcastMessage], and you can receive room barrage message through [onIMRecvBarrageMessage].

Available since: 1.2.1
Restrictions: None

onPerformanceStatusUpdate

public void onPerformanceStatusUpdate(ZegoPerformanceStatus status)

The system performance status callback. (Note: Due to Android system limitations, CPU usage cannot be obtained)

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
status	ZegoPerformanceStatus	System performance monitoring status.

Details

System performance monitoring callback. The callback notification period is the value of millisecond parameter set by call [startPerformanceMonitor].

Use cases: Monitor system performance can help user quickly locate and solve performance problems and improve user experience. When to trigger: It will triggered after [createEngine], and call [startPerformanceMonitor] to start system performance monitoring.

Available since: 1.19.0
Restrictions: None.

onNetworkModeChanged

public void onNetworkModeChanged(ZegoNetworkMode mode)

Network mode changed callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
mode	ZegoNetworkMode	Current network mode.

Details

Network mode changed callback. When to trigger: This callback will be triggered when the device's network mode changed, such as switched from WiFi to 5G, or when network is disconnected.

Available since: 1.20.0
Restrictions: None.

onNetworkSpeedTestError

public void onNetworkSpeedTestError(int errorCode, ZegoNetworkSpeedTestType type)

Network speed test error callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Network speed test error code. Please refer to error codes document https://docs.zegocloud.com/en/5548.html for details.
type	ZegoNetworkSpeedTestType	Uplink or downlink.

Details

Network speed test error callback.

Use cases: This function can be used to detect whether the network environment is suitable for pushing/pulling streams with specified bitrates. When to
Trigger: If an error occurs during the speed test, such as: can not connect to speed test server, this callback will be triggered.

Available since: 1.20.0
Restrictions: None.

onNetworkSpeedTestQualityUpdate

public void onNetworkSpeedTestQualityUpdate(ZegoNetworkSpeedTestQuality quality, ZegoNetworkSpeedTestType type)

Network speed test quality callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
quality	ZegoNetworkSpeedTestQuality	Network speed test quality.
type	ZegoNetworkSpeedTestType	Uplink or downlink.

Details

Network speed test quality callback when the network can be connected.

Use cases: This function can be used to detect whether the network environment is suitable for pushing/pulling streams with specified bitrates. When to
Trigger: After call [startNetworkSpeedTest] start network speed test, this callback will be triggered. The trigger period is determined by the parameter value specified by call [startNetworkSpeedTest], default value is 3 seconds
Caution: When error occurred during network speed test or [stopNetworkSpeedTest] called, this callback will not be triggered.

Available since: 1.20.0
Restrictions: None.

onNetworkQuality

public  void onNetworkQuality(String userID, ZegoStreamQualityLevel upstreamQuality, ZegoStreamQualityLevel downstreamQuality)

The network quality callback of users who are publishing in the room.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
userID	String	User ID, empty means local user
upstreamQuality	ZegoStreamQualityLevel	Upstream network quality
downstreamQuality	ZegoStreamQualityLevel	Downstream network quality

Details

The uplink and downlink network callbacks of the local and remote users, that would be called by default every two seconds for the local and each playing remote user's network quality. Versions 2.10.0 to 2.13.1:

Developer must both publish and play streams before you receive your own network quality callback.
When playing a stream, the publish end has a play stream and the publish end is in the room where it is located, then the user's network quality will be received. Versions 2.14.0 to 2.21.1:
As long as you publish or play a stream, you will receive your own network quality callback.
When you play a stream, the publish end is in the room where you are, and you will receive the user's network quality. Version 2.22.0 and above:
As long as you publish or play a stream, you will receive your own network quality callback.
When you play a stream, the publish end is in the room where you are, and you will receive the user's network quality.
Estimate the network conditions of the remote stream publishing user. If the remote stream publishing user loses one heartbeat, the network quality will be called back as unknown; if the remote stream publishing user's heartbeat loss reaches 3 Second, call back its network quality to die. Use case: When the developer wants to analyze the network condition on the link, or wants to know the network condition of local and remote users. When to

Trigger: After publishing a stream by called [startPublishingStream] or playing a stream by called [startPlayingStream].

Available since: 2.10.0

onRtcStats

public void onRtcStats(ZegoRtcStatsInfo info)

RTC network statistics callback.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
info	ZegoRtcStatsInfo	statistical information.

Details

RTC network statistics callback.

Use cases: When a developer wants to analyze the local network situation. When to
Trigger: After calling [startPublishingStream] to start pushing the RTC stream, it will call back the upstream statistics. After calling [startPlayingStream] to start playing the RTC or L3 stream, it will call back the downlink statistics. The default callback period is 3 seconds.
Caution: None.

Available since: 3.20.0
Restrictions: None.

onNetworkTimeSynchronized

public void onNetworkTimeSynchronized()

Successful callback of network time synchronization.

Declared in callback/IZegoEventHandler.java

Available since: 2.12.0 This callback is triggered when internal network time synchronization completes after a developer calls [createEngine].

onRequestDumpData

public void onRequestDumpData()

Request to dump data.

Declared in callback/IZegoEventHandler.java

Trigger: When the customer reports back the problem, ZEGO expects the user to dump the data to analyze the audio / video processing problem, which will trigger this callback.

Available since: 3.10.0 When to

onRequestUploadDumpData

public void onRequestUploadDumpData(String dumpDir, boolean takePhoto)

Request to dump data.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
dumpDir	String	Dump data dir.
takePhoto	boolean	Need to take photo when uploading dump data

Trigger: When the customer reports back the problem, ZEGO expects the user to dump the data to analyze the audio / video processing problem, which will trigger this callback.

Available since: 3.11.0 When to

onStartDumpData

public void onStartDumpData(int errorCode)

Callback when starting to dump data.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Error code.

Trigger: This callback is triggered when [startDumpData] is called.

Available since: 3.10.0 When to

onStopDumpData

public void onStopDumpData(int errorCode, String dumpDir)

Callback when stopping to dump data.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Error code.
dumpDir	String	Dump data dir.

Trigger: This callback is triggered when [stopDumpData] is called.

Available since: 3.10.0 When to

onUploadDumpData

public void onUploadDumpData(int errorCode)

Callback after uploading the dump data.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
errorCode	int	Error code.

Trigger: When [uploadDumpData] is called, this callback will be triggered after SDK executes the upload task.

Available since: 3.10.0 When to

onScreenCaptureExceptionOccurred

public void onScreenCaptureExceptionOccurred(ZegoScreenCaptureExceptionType exceptionType)

The callback triggered when a screen capture source exception occurred.

Declared in callback/IZegoEventHandler.java

Parameters

Name	Type	Description
exceptionType	ZegoScreenCaptureExceptionType	Screen capture exception type.

Details

The callback triggered when the mobile screen capture source exception occurred.

Trigger: This callback is triggered when an exception occurs after the mobile screen capture started.
Caution: The callback does not actually take effect until call [setEventHandler] to set.

Available since: 3.6.0
Restrictions: Only available on Android and iOS.

onScreenCaptureStart

public void onScreenCaptureStart()

The callback triggered when start screen capture.

Declared in callback/IZegoEventHandler.java

The callback triggered when calling the start mobile screen capture.

Trigger: After calling [startScreenCapture], this callback will be triggered when starting screen capture successfully, and [onScreenCaptureExceptionOccurred] will be triggered when failing.
Caution: The callback does not actually take effect until call [setEventHandler] to set.

Available since: 3.16.0
Restrictions: Only available on Android and iOS.