Class


ZegoApiCalledEventHandler	ZegoEventHandler
ZegoExpressEngine	ZegoMediaPlayer

ZegoApiCalledEventHandler

Declared in ZegoExpressEventHandler.ts

Methods

onApiCalledResult

onApiCalledResult(errorCode: number, funcName: string, info: string): void

Method execution result callback

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
errorCode	number	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 monitoring is turned on through [setApiCalledCallback], the results of the execution of all methods will be called back through this callback.

Trigger: When the developer calls the SDK method, the execution result of the method is called back.
Caution: It is recommended to monitor and process this callback in the development and testing phases, and turn off the monitoring of this callback after going online.

Available since: 2.3.0
Restrictions: None.

ZegoEventHandler

Declared in ZegoExpressEventHandler.ts

Methods

onDebugError

onDebugError(errorCode: number, funcName: string, info: string): void

The callback for obtaining debugging error information.

Declared in ZegoExpressEventHandler.ts

Parameters

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

onEngineStateUpdate(state: ZegoEngineState): void

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

Declared in ZegoExpressEventHandler.ts

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

onRecvExperimentalAPI(content: string): void

Experimental API callback

Declared in ZegoExpressEventHandler.ts

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

onRoomStateUpdate

onRoomStateUpdate(roomID: string, state: ZegoRoomState, errorCode: number, extendedData: string): void

Notification of the room connection state changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID, a string of up to 128 bytes in length.
state	ZegoRoomState	Changed room state.
errorCode	number	Error code, For details, please refer to Common Error Codes.
extendedData	string	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

onRoomStateChanged(roomID: string, reason: ZegoRoomStateChangedReason, errorCode: number, extendedData: string): void

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

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID, a string of up to 128 bytes in length.
reason	ZegoRoomStateChangedReason	Room state change reason.
errorCode	number	Error code, please refer to the error codes document https://doc-en.zego.im/en/5548.html for details.
extendedData	string	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

onRoomUserUpdate(roomID: string, updateType: ZegoUpdateType, userList: ZegoUser[]): void

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

Declared in ZegoExpressEventHandler.ts

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	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

onRoomOnlineUserCountUpdate(roomID: string, count: number): void

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

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID where the user is logged in, a string of up to 128 bytes in length.
count	number	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

onRoomStreamUpdate(roomID: string, updateType: ZegoUpdateType, streamList: ZegoStream[], extendedData: string): void

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

Declared in ZegoExpressEventHandler.ts

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	ZegoStream[]	Updated stream list.
extendedData	string	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

onRoomStreamExtraInfoUpdate(roomID: string, streamList: ZegoStream[]): void

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 ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID where the user is logged in, a string of up to 128 bytes in length.
streamList	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

onRoomExtraInfoUpdate(roomID: string, roomExtraInfoList: ZegoRoomExtraInfo[]): void

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

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID where the user is logged in, a string of up to 128 bytes in length.
roomExtraInfoList	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

onRoomTokenWillExpire(roomID: string, remainTimeInSecond: number): void

Callback notification that room Token authentication is about to expire.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
roomID	string	Room ID where the user is logged in, a string of up to 128 bytes in length.
remainTimeInSecond	number	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

onPublisherStateUpdate(streamID: string, state: ZegoPublisherState, errorCode: number, extendedData: string): void

The callback triggered when the state of stream publishing changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
state	ZegoPublisherState	State of publishing stream.
errorCode	number	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	string	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

onPublisherQualityUpdate(streamID: string, quality: ZegoPublishStreamQuality): void

Callback for current stream publishing quality.

Declared in ZegoExpressEventHandler.ts

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

onPublisherCapturedAudioFirstFrame(): void

The callback triggered when the first audio frame is captured.

Declared in ZegoExpressEventHandler.ts

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

onPublisherCapturedVideoFirstFrame(channel: ZegoPublishChannel): void

The callback triggered when the first video frame is captured.

Declared in ZegoExpressEventHandler.ts

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]. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onPublisherRenderVideoFirstFrame

onPublisherRenderVideoFirstFrame(channel: ZegoPublishChannel): void

The callback triggered when the first video frame is rendered.

Declared in ZegoExpressEventHandler.ts

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]. This function is only available in ZegoExpressVideo SDK!

Available since: 2.4.0

onPublisherVideoSizeChanged

onPublisherVideoSizeChanged(width: number, height: number, channel: ZegoPublishChannel): void

The callback triggered when the video capture resolution changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
width	number	Video capture resolution width.
height	number	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. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onPublisherRelayCDNStateUpdate

onPublisherRelayCDNStateUpdate(streamID: string, infoList: ZegoStreamRelayCDNInfo[]): void

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

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
infoList	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

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

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

Declared in ZegoExpressEventHandler.ts

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

onPublisherStreamEvent(eventID: ZegoStreamEvent, streamID: string, extraInfo: string): void

The callback triggered when publishing stream.

Declared in ZegoExpressEventHandler.ts

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

onPlayerStateUpdate

onPlayerStateUpdate(streamID: string, state: ZegoPlayerState, errorCode: number, extendedData: string): void

The callback triggered when the state of stream playing changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	stream ID.
state	ZegoPlayerState	State of playing stream.
errorCode	number	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	string	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

onPlayerQualityUpdate

onPlayerQualityUpdate(streamID: string, quality: ZegoPlayStreamQuality): void

Callback for current stream playing quality.

Declared in ZegoExpressEventHandler.ts

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

onPlayerMediaEvent(streamID: string, event: ZegoPlayerMediaEvent): void

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

Declared in ZegoExpressEventHandler.ts

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

onPlayerRecvAudioFirstFrame(streamID: string): void

The callback triggered when the first audio frame is received.

Declared in ZegoExpressEventHandler.ts

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

onPlayerRecvVideoFirstFrame

onPlayerRecvVideoFirstFrame(streamID: string): void

The callback triggered when the first video frame is received.

Declared in ZegoExpressEventHandler.ts

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. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onPlayerRenderVideoFirstFrame

onPlayerRenderVideoFirstFrame(streamID: string): void

The callback triggered when the first video frame is rendered.

Declared in ZegoExpressEventHandler.ts

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. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onPlayerRenderCameraVideoFirstFrame

onPlayerRenderCameraVideoFirstFrame(streamID: string): void

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

Declared in ZegoExpressEventHandler.ts

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. This function is only available in ZegoExpressVideo SDK!

Available since: 3.0.0

onPlayerVideoSizeChanged

onPlayerVideoSizeChanged(streamID: string, width: number, height: number): void

The callback triggered when the stream playback resolution changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
width	number	Video decoding resolution width.
height	number	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. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onPlayerRecvSEI

deprecated

onPlayerRecvSEI(streamID: string, data: Uint8Array): void

The callback triggered when Supplemental Enhancement Information is received.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
data	Uint8Array	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.

onPlayerRecvAudioSideInfo

onPlayerRecvAudioSideInfo(streamID: string, data: Uint8Array): void

Receive the audio side information content of the remote stream.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
data	Uint8Array	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

onPlayerLowFpsWarning(codecID: ZegoVideoCodecID, streamID: string): void

Playing stream low frame rate warning.

Declared in ZegoExpressEventHandler.ts

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

onPlayerStreamEvent(eventID: ZegoStreamEvent, streamID: string, extraInfo: string): void

The callback triggered when playing stream.

Declared in ZegoExpressEventHandler.ts

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

onPlayerVideoSuperResolutionUpdate(streamID: string, state: ZegoSuperResolutionState, errorCode: number): void

Playing stream video super resolution enabled state changes.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
state	ZegoSuperResolutionState	Video super resolution state.
errorCode	number	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

onAudioDeviceStateChanged

  onAudioDeviceStateChanged(updateType: ZegoUpdateType, deviceType: ZegoAudioDeviceType, deviceInfo: ZegoDeviceInfo): void

The callback triggered when there is a change to audio devices (i.e. new device added or existing device deleted).

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
updateType	ZegoUpdateType	Update type (add/delete)
deviceType	ZegoAudioDeviceType	Audio device type
deviceInfo	ZegoDeviceInfo	Audio device information

Details

By listening to this callback, users can update the sound collection or output using a specific device when necessary. When to trigger: This callback is triggered when an audio device is added or removed from the system.

Platform differences: Only supports Windows and macOS.

Available since: 1.1.0
Restrictions: None.

onAudioDeviceVolumeChanged

onAudioDeviceVolumeChanged(deviceType: ZegoAudioDeviceType, deviceID: string, volume: number): void

The callback triggered when there is a change of the volume for the audio devices.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	Audio device ID
volume	number	audio device volume

Details

Audio device volume change event callback. When to trigger: After calling the [startAudioDeviceVolumeMonitor] function to start the device volume monitor, and the volume of the monitored audio device changes.

Platform differences: Only supports Windows and macOS.

Available since: 1.1.0

onVideoDeviceStateChanged

onVideoDeviceStateChanged(updateType: ZegoUpdateType, deviceInfo: ZegoDeviceInfo): void

The callback triggered when there is a change to video devices (i.e. new device added or existing device deleted).

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
updateType	ZegoUpdateType	Update type (add/delete)
deviceInfo	ZegoDeviceInfo	Audio device information

Details

By listening to this callback, users can update the video capture using a specific device when necessary. When to trigger: This callback is triggered when a video device is added or removed from the system.

Platform differences: Only supports Windows and macOS. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None

onCapturedSoundLevelInfoUpdate

onCapturedSoundLevelInfoUpdate(soundLevelInfo: ZegoSoundLevelInfo *): void

The local captured audio sound level callback, supported vad.

Declared in ZegoExpressEventHandler.ts

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

onRemoteSoundLevelInfoUpdate

onRemoteSoundLevelInfoUpdate(soundLevelInfos: Map<string, zego.ZegoSoundLevelInfo>): void

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

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
soundLevelInfos	Map<string, zego.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

onCapturedAudioSpectrumUpdate(audioSpectrum: number[]): void

The local captured audio spectrum callback.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
audioSpectrum	number[]	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

onRemoteAudioSpectrumUpdate(audioSpectrums: Map<string, number[]>): void

The remote playing streams audio spectrum callback.

Declared in ZegoExpressEventHandler.ts

Parameters

Name	Type	Description
audioSpectrums	Map<string, number[]>	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

  onLocalDeviceExceptionOccurred(exceptionType: ZegoDeviceExceptionType, deviceType: ZegoDeviceType, deviceID: string): void

The callback triggered when a local device exception occurred.

Declared in ZegoExpressEventHandler.ts

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

onRemoteCameraStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

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

Declared in ZegoExpressEventHandler.ts

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. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

onRemoteMicStateUpdate

onRemoteMicStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

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

Declared in ZegoExpressEventHandler.ts

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

onRemoteSpeakerStateUpdate(streamID: string, state: ZegoRemoteDeviceState): void

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

Declared in ZegoExpressEventHandler.ts

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

onAudioRouteChange(audioRoute: ZegoAudioRoute): void

Callback for device's audio route changed.

Declared in ZegoExpressEventHandler.ts

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

onAudioVADStateUpdate(type: ZegoAudioVADStableStateMonitorType, state: ZegoAudioVADType): void

Callback for audio VAD stable state update.

Declared in ZegoExpressEventHandler.ts

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.

onIMRecvCustomCommand

onIMRecvCustomCommand(roomID: string, fromUser: ZegoUser, command: string): void

The callback triggered when a Custom Command is received.

Declared in ZegoExpressEventHandler.ts

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

onPerformanceStatusUpdate(status: ZegoPerformanceStatus): void

System performance monitoring callback.

Declared in ZegoExpressEventHandler.ts

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.

onNetworkSpeedTestError

onNetworkSpeedTestError(errorCode: number, type: ZegoNetworkSpeedTestType): void

Network speed test error callback.

Declared in ZegoExpressEventHandler.ts

Parameters

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

onNetworkSpeedTestQualityUpdate(quality: ZegoNetworkSpeedTestQuality, type: ZegoNetworkSpeedTestType): void

Network speed test quality callback.

Declared in ZegoExpressEventHandler.ts

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

  onNetworkQuality(userID: string, upstreamQuality: ZegoStreamQualityLevel, downstreamQuality: ZegoStreamQualityLevel): void

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

Declared in ZegoExpressEventHandler.ts

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

onScreenCaptureExceptionOccurred

onScreenCaptureExceptionOccurred(exceptionType: ZegoScreenCaptureExceptionType): void

The callback triggered when a screen capture source exception occurred.

Declared in ZegoExpressEventHandler.ts

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

onScreenCaptureStart(): void

The callback triggered when start screen capture.

Declared in ZegoExpressEventHandler.ts

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.

ZegoExpressEngine

Declared in ZegoExpressEngine.ts

Methods

createEngine

static

createEngine

createEngine(profile: ZegoEngineProfile, eventHandler?: ZegoEventHandler): ZegoExpressEngine

Create ZegoExpressEngine singleton object and initialize SDK.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
profile	ZegoEngineProfile	The basic configuration information is used to create the engine.
eventHandler	ZegoEventHandler	Event notification callback. [null] means not receiving any callback notifications.It can also be managed later via [setEventHandler]. If [createEngine] is called repeatedly and the [destroyEngine] function is not called to destroy the engine before the second call, the eventHandler will not be updated.

Details

Create ZegoExpressEngine singleton object and initialize SDK.

When to call: The engine needs to be created before calling other functions.
Caution: The SDK only supports the creation of one instance of ZegoExpressEngine. If you need call [createEngine] multiple times, you need call [destroyEngine] before you call the next [createEngine]. Otherwise it will return the instance which created by [createEngine] you called last time.

Available since: 2.14.0
Restrictions: None.

Return

engine singleton instance.

destroyEngine

static

destroyEngine

destroyEngine(callback?: ZegoDestroyCompletionCallback): void

Destroy the ZegoExpressEngine singleton object and deinitialize the SDK.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
callback	ZegoDestroyCompletionCallback	Notification callback for destroy engine completion. Developers can listen to this callback to ensure that device hardware resources are released. If the developer only uses SDK to implement audio and video functions, this parameter can be passed [null].

Details

Destroy the ZegoExpressEngine singleton object and deinitialize the SDK.

When to call: When the SDK is no longer used, the resources used by the SDK can be released through this interface
Caution: After using [createEngine] to create a singleton, if the singleton object has not been created or has been destroyed, you will not receive related callbacks when calling this function.

Available since: 1.1.0
Restrictions: None.

setEngineConfig

static

setEngineConfig

setEngineConfig(config: ZegoEngineConfig): void

Set advanced engine configuration.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoEngineConfig	Advanced engine configuration

Details

Used to enable advanced functions.

When to call: Different configurations have different call timing requirements. For details, please consult ZEGO technical support.

Available since: 1.1.0
Restrictions: None.

setLogConfig

static

setLogConfig

setLogConfig(config: ZegoLogConfig): void

Set log configuration.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoLogConfig	log configuration.

Details

If you need to customize the log file size and path, please call this function to complete the configuration.

When to call: It must be set before calling [createEngine] to take effect. If it is set after [createEngine], it will take effect at the next [createEngine] after [destroyEngine].
Caution: Once this interface is called, the method of setting log size and path via [setEngineConfig] will be invalid.Therefore, it is not recommended to use [setEngineConfig] to set the log size and path.

Available since: 2.3.0
Restrictions: None.

setRoomMode

static

setRoomMode

setRoomMode(mode: ZegoRoomMode): void

Set room mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoRoomMode	Room mode. Description: Used to set the room mode. Use cases: If you need to enter multiple rooms at the same time for publish-play stream, please turn on the multi-room mode through this interface. Required: True. Default value: ZEGO_ROOM_MODE_SINGLE_ROOM.

Details

If you need to use the multi-room feature, please call this function to complete the configuration.

When to call: Must be set before calling [createEngine] to take effect, otherwise it will fail.
Caution: None.

Available since: 2.9.0
Restrictions: If you need to use the multi-room feature, please contact the instant technical support to configure the server support.

getVersion

static

getVersion

getVersion(): string

Gets the SDK's version number.

Declared in ZegoExpressEngine.ts

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.1.0
Restrictions: None.

SDK version.

setApiCalledCallback

static

setApiCalledCallback

setApiCalledCallback(callback: ZegoApiCalledEventHandler): void

Set method execution result callback.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
callback	ZegoApiCalledEventHandler	Method execution result callback.

Details

Set the setting of the execution result of the calling method. After setting, you can get the detailed information of the result of each execution of the ZEGO SDK method.

When to call: Any time.
Caution: It is recommended that developers call this interface only when they need to obtain the call results of each interface. For example, when troubleshooting and tracing problems. Developers generally do not need to pay attention to this interface.

Available since: 2.3.0
Restrictions: None.

isFeatureSupported

static

isFeatureSupported

isFeatureSupported(featureType: ZegoFeatureType): boolean

Query whether the current SDK supports the specified feature.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
featureType	ZegoFeatureType	Type of feature to query.

Details

Since the SDK supports feature trimming, some features may be trimmed; you can use this function to quickly determine whether the current SDK supports the specified features, such as querying whether the media player feature is supported.

When to call: Any time.

Available since: 2.22.0

Return

Whether the specified feature is supported. true: supported; false: not supported.

setEventHandler

setEventHandler(eventHandler?: ZegoEventHandler): void

Sets up the event notification callbacks that need to be handled. If the eventHandler is set to [null], all the callbacks set previously will be cleared.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
eventHandler	ZegoEventHandler	Event notification callback. If the eventHandler is set to [nullptr], 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 up event notification callbacks, used to monitor callbacks such as engine status changes, room status changes, etc.

When to call: After [createEngine].
Caution: After calling this function or [createEngine] setting a callback, unless this function is called to clear the callback, setting a callback again will not take effect. After calling [destroyEngine], the event handler that has been set will be invalid and need to be reset after next calling of [createEngine].

Available since: 1.1.0
Restrictions: None.

setRoomScenario

setRoomScenario(scenario: ZegoScenario): void

Set room scenario.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
scenario	ZegoScenario	Room scenario.

Details

You can set the scenario of the room, and the SDK will adopt different optimization strategies for different scenarios in order to obtain better effects; this function does exactly the same thing as the [scenario] parameter in the [profile] configuration of [createEngine].

Use cases: This function is suitable for apps in various audio and video business scenarios, such as 1v1 video call (or voice call) scenario and live show scenario; this function can be used to switch scenarios without destroying the engine through [destroyEngine].
When to call: Must be set before calling [loginRoom] AND after calling [createEngine].
Caution: 1. Users in the same room are recommended to use the same room scenario for best results. 2. Setting the scenario will affect the audio and video bit rate, frame rate, resolution, codec id, audio device mode, audio route type, traffic control, 3A, ear return and other audio and video configurations. If you have special needs, you can call various other APIs to set the above configuration after calling this API. 3. Calling this function will override the scenario specified on [createEngine] or the scenario set by the last call to this function. 4. Calling this function will overwrite the audio and video related configuration you set through APIs such as [setVideoConfig], [setAudioConfig], so it is recommended to set the scenario first and then adjust the audio and video configuration through other APIs.

Available since: 3.0.0
Restrictions: Once you log in to the room, you are no longer allowed to modify the room scenario. If you need to modify the scenario, you need to log out of the room first. If you log in to multiple rooms, you need to log out of all rooms before you can modify it.

uploadLog

uploadLog(callback?: ZegoUploadLogResultCallback): void

Uploads logs to the ZEGO server, with callback.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
callback	ZegoUploadLogResultCallback	Log upload result callback.

Details

By default, SDK creates and prints log files in the App's default directory. Each log file defaults to a maximum of 5MB. Three log files are written over and over in a circular fashion. When calling this function, SDK will auto package and upload the log files to the ZEGO server.

Use cases: Developers can provide a business “feedback” channel in the App. When users feedback problems, they can call this function to upload the local log information of SDK to help locate user problems.
When to call: After [createEngine].
Caution: 1.After calling this interface to upload logs, if you call [destroyEngine] or exit the App too quickly, there may be a failure.It is recommended to wait a few seconds, and then call [destroyEngine] or exit the App after receiving the upload success callback. 2.If you want to call before [createEngine], use the [submitLog] interface.

Available since: 2.4.0
Restrictions: The frequency limit is once per minute.

enableDebugAssistant

enableDebugAssistant(enable: boolean): void

Enable the debug assistant. Note, do not enable this feature in the online version! Use only during development phase!

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable the debug assistant.

Details

After enabled, the SDK will print logs to the console, and will pop-up an alert (toast) UI message when there is a problem with calling other SDK functions.

Default value: This function is disabled by default.
When to call: This function can be called right after [createEngine].
Platform differences: The pop-up alert function only supports Android / iOS / macOS / Windows, and the console log function supports all platforms.
Caution: Be sure to confirm that this feature is turned off before the app is released to avoid pop-up UI alert when an error occurs in your release version's app. It is recommended to associate the [enable] parameter of this function with the DEBUG variable of the app, that is, only enable the debug assistant in the DEBUG environment.

Available since: 2.17.0
Restrictions: None.

callExperimentalAPI

callExperimentalAPI(params: string): string

Call the experimental API.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
params	string	Parameters in the format of a JSON string, please consult ZEGO technical support for details.

Details

ZEGO provides some technical previews or special customization functions in RTC business through this API. If you need to get the use of the function or the details, please consult ZEGO technical support.

When to call: After [createEngine].

Available since: 2.7.0

Return

Returns an argument in the format of a JSON string, please consult ZEGO technical support for details.

loginRoom

loginRoom(roomID: string, user: ZegoUser, config?: ZegoRoomConfig, callback?: ZegoRoomLoginCallback): void

Log in to the room by configuring advanced properties, and return the login result through the callback parameter. You must log in to the room before pushing or pulling the stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
roomID	string	Room ID, a string of less 128 bytes in length. Caution: 1. room ID is defined by yourself. 2. Only support numbers, English characters and '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''. 3. If you need to communicate with the Web SDK, please do not use '%'.
user	ZegoUser	User object instance, configure userID, userName. Note that the userID needs to be globally unique with the same appID, otherwise the user who logs in later will kick out the user who logged in first.
config	ZegoRoomConfig	Advanced room configuration.
callback	ZegoRoomLoginCallback	The callback of this login result, if you need detailed room status, please pay attention to the [onRoomStateChanged] callback. Required: No. Default value: null.Caution: If the connection is retried multiple times due to network problems, the retry status will not be thrown by this callback.

Details

If the room does not exist, [loginRoom] creates and logs in the room. SDK uses the 'room' to organize users. After users log in to a room, they can use interface such as push stream [startPublishingStream], pull stream [startPlayingStream], send and receive broadcast messages [sendBroadcastMessage], etc. To prevent the app from being impersonated by a malicious user, you can add authentication before logging in to the room, that is, the [token] parameter in the ZegoRoomConfig object passed in by the [config] parameter.

Use cases: In the same room, users can conduct live broadcast, audio and video calls, etc.
When to call /Trigger: This interface is called after [createEngine] initializes the SDK.
Caution: 1. Apps that use different appIDs cannot intercommunication with each other. 2. SDK supports startPlayingStream audio and video streams from different rooms under the same appID, that is, startPlayingStream audio and video streams across rooms. Since ZegoExpressEngine's room related callback notifications are based on the same room, when developers want to startPlayingStream streams across rooms, developers need to maintain related messages and signaling notifications by themselves. 3. It is strongly recommended that userID corresponds to the user ID of the business APP, that is, a userID and a real user are fixed and unique, and should not be passed to the SDK in a random userID. Because the unique and fixed userID allows ZEGO technicians to quickly locate online problems. 4. After the first login failure due to network reasons or the room is disconnected, the default time of SDK reconnection is 20min.
Privacy reminder: Please do not fill in sensitive user information in this interface, including but not limited to mobile phone number, ID number, passport number, real name, etc.
Related callbacks: 1. When the user starts to log in to the room, the room is successfully logged in, or the room fails to log in, the [onRoomStateChanged] (Not supported before 2.18.0, please use [onRoomStateUpdate]) callback will be triggered to notify the developer of the status of the current user connected to the room. 2. Different users who log in to the same room can get room related notifications in the same room (eg [onRoomUserUpdate], [onRoomStreamUpdate], etc.), and users in one room cannot receive room signaling notifications in another room. 3. If the network is temporarily interrupted due to network quality reasons, the SDK will automatically reconnect internally. You can get the current connection status of the local room by listening to the [onRoomStateChanged] (Not supported before 2.18.0, please use [onRoomStateUpdate]) callback method, and other users in the same room will receive [onRoomUserUpdate] callback notification. 4. Messages sent in one room (e.g. [setStreamExtraInfo], [sendBroadcastMessage], [sendBarrageMessage], [sendCustomCommand], etc.) cannot be received callback ((eg [onRoomStreamExtraInfoUpdate], [onIMRecvBroadcastMessage], [onIMRecvBarrageMessage], [onIMRecvCustomCommand], etc) in other rooms. Currently, SDK does not provide the ability to send messages across rooms. Developers can integrate the SDK of third-party IM to achieve.
Related APIs: 1. Users can call [logoutRoom] to log out. In the case that a user has successfully logged in and has not logged out, if the login interface is called again, the console will report an error and print the error code 1002001. 2. SDK supports multi-room login, please call [setRoomMode] function to select multi-room mode before engine initialization, and then call [loginRoom] to log in to multi-room. 3. Calling [destroyEngine] will also automatically log out.

Available since: 2.18.0
Restrictions: For restrictions on the use of this function, please refer to https://docs.zegocloud.com/article/7611 or contact ZEGO technical support.

logoutRoom

logoutRoom(roomID?: string, callback?: ZegoRoomLogoutCallback): void

Exit the room of the specified room ID with callback.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
roomID	string	Room ID, a string of up to 128 bytes in length. Caution: 1. Only support numbers, English characters and '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''. 2. If you need to communicate with the Web SDK, please do not use '%'.
callback	ZegoRoomLogoutCallback	The callback of this logout room result, if you need detailed room status, please pay attention to the [onRoomStateChanged] callback. Required: No. Default value: null.

Details

This API will log out the room named roomID.

Use cases: In the same room, users can conduct live broadcast, audio and video calls, etc.
When to call /Trigger: After successfully logging in to the room, if the room is no longer used, the user can call the function [logoutRoom].
Caution: 1. Exiting the room will stop all publishing and playing streams for user, and inner audio and video engine will stop, and then SDK will auto stop local preview UI. If you want to keep the preview ability when switching rooms, please use the [switchRoom] method. 2. If the user logs out to the room, but the incoming 'roomID' is different from the logged-in room name, SDK will return failure.
Related callbacks: After calling this function, you will receive [onRoomStateChanged] (Not supported before 2.18.0, please use [onRoomStateUpdate]) callback notification successfully exits the room, while other users in the same room will receive the [onRoomUserUpdate] callback notification(On the premise of enabling isUserStatusNotify configuration).
Related APIs: Users can use [loginRoom], [switchRoom] functions to log in or switch rooms.

Available since: 1.1.0
Restrictions: None.

switchRoom

switchRoom(fromRoomID: string, toRoomID: string, config?: ZegoRoomConfig): void

Switch the room with advanced room configurations.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
fromRoomID	string	Current roomID.
toRoomID	string	The next roomID.
config	ZegoRoomConfig	Advanced room configuration.

Details

Using this interface allows users to quickly switch from one room to another room.

Use cases: if you need to quickly switch to the next room, you can call this function.
When to call /Trigger: After successfully login room.
Caution: 1. When this function is called, all streams currently publishing or playing will stop (but the local preview will not stop). 2. To prevent the app from being impersonated by a malicious user, you can add authentication before logging in to the room, that is, the [token] parameter in the ZegoRoomConfig object passed in by the [config] parameter. This parameter configuration affects the room to be switched over. 3. Multi-room mode is supported in version 3.5.0 (use the function [setRoomMode] to set ZegoRoomMode to ZEGO_ROOM_MODE_MULTI_ROOM). 4. If a Token is passed in for login when logging into the room [loginRoom], the [switchroom] interface must be used with the config parameter and the corresponding Token value passed in when switching rooms.
Privacy reminder: Please do not fill in sensitive user information in this interface, including but not limited to mobile phone number, ID number, passport number, real name, etc.
Related callbacks: When the user call the [switchRoom] function, the [onRoomStateChanged] (Not supported before 2.18.0, please use [onRoomStateUpdate]) callback will be triggered to notify the developer of the status of the current user connected to the room.
Related APIs: Users can use the [logoutRoom] function to log out of the room.

Available since: 1.15.0
Restrictions: None.

renewToken

renewToken(roomID: string, token: string): void

Renew token.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
roomID	string	Room ID.
token	string	The token that needs to be renew.

Details

After the developer receives [onRoomTokenWillExpire], they can use this API to update the token to ensure that the subsequent RTC functions are normal.

Use cases: Used when the token is about to expire.
When to call /Trigger: After the developer receives [onRoomTokenWillExpire].
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 callbacks: None.
Related APIs: None.

Available since: 2.8.0
Restrictions: None.

setRoomExtraInfo

setRoomExtraInfo(roomID: string, key: string, value: string, callback?: ZegoRoomSetRoomExtraInfoCallback): void

Set room extra information.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
roomID	string	Room ID.
key	string	key of the extra info.
value	string	value if the extra info.
callback	ZegoRoomSetRoomExtraInfoCallback	Callback for setting room extra information.

Details

The user can call this function to set the extra info of the room.

Use cases: You can set some room-related business attributes, such as whether someone is Co-hosting.
When to call /Trigger: After logging in the room successful.
Caution: For key and value restrictions, please refer to Restrictions. Newly set values will overwrite old ones.
Related callbacks: Other users in the same room will be notified through the [onRoomExtraInfoUpdate] callback function.
Related APIs: None.

Available since: 1.13.0
Restrictions: For restrictions on the use of this function, please refer to https://docs.zegocloud.com/article/7611 or contact ZEGO technical support.

startPublishingStream

startPublishingStream(streamID: string, config?: ZegoPublisherConfig, channel?: ZegoPublishChannel): void

Starts publishing a stream. Support multi-room mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID, a string of up to 256 characters. Caution: 1. Stream ID is defined by you. 2. needs to be globally unique within the entire AppID. If in the same AppID, different users publish each stream and the stream ID is the same, which will cause the user to publish the stream failure. You cannot include URL keywords, otherwise publishing stream and playing stream will fails. 3. Only support numbers, English characters and '-', '_'.
config	ZegoPublisherConfig	Advanced publish configuration.
channel	ZegoPublishChannel	Publish stream channel.

Details

Users push their local audio and video streams to the ZEGO RTC server or CDN, and other users in the same room can pull the audio and video streams to watch through the streamID or CDN pull stream address.

Use cases: It can be used to publish streams in real-time connecting wheat, live broadcast and other scenarios.
When to call: After [loginRoom].
Caution: 1. Before start to publish the stream, the user can choose to call [setVideoConfig] to set the relevant video parameters, and call [startPreview] to preview the video. 2. Other users in the same room can get the streamID by monitoring the [onRoomStreamUpdate] event callback after the local user publishing stream successfully. 3. In the case of poor network quality, user publish may be interrupted, and the SDK will attempt to reconnect. You can learn about the current state and error information of the stream published by monitoring the [onPublisherStateUpdate] event. 4. To call [SetRoomMode] function to select multiple rooms, the room ID must be specified explicitly.

Available since: 1.1.0
Restrictions: None.

stopPublishingStream

stopPublishingStream(channel?: ZegoPublishChannel): void

Stops publishing a stream (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publish stream channel.

Details

The user stops sending local audio and video streams, and other users in the room will receive a stream deletion notification.

Use cases: It can be used to stop publish streams in real-time connecting wheat, live broadcast and other scenarios.
When to call: After [startPublishingStream].
Caution: 1. After stopping the streaming, other users in the same room can receive the delete notification of the stream by listening to the [onRoomStreamUpdate] callback. 2. If the user has initiated publish flow, this function must be called to stop the publish of the current stream before publishing the new stream (new streamID), otherwise the new stream publish will return a failure. 3. After stopping streaming, the developer should stop the local preview based on whether the business situation requires it.

Available since: 1.1.0
Restrictions: None.

setStreamExtraInfo

  setStreamExtraInfo(extraInfo: string, channel?: ZegoPublishChannel, callback?: ZegoPublisherSetStreamExtraInfoCallback): void

Sets the extra information of the stream being published for the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
extraInfo	string	Stream extra information, a string of up to 1024 characters.
channel	ZegoPublishChannel	Publish stream channel.
callback	ZegoPublisherSetStreamExtraInfoCallback	Set stream extra information execution result notification.

Details

Use this function to set the extra info of the stream. The stream extra information is an extra information identifier of the stream ID. Unlike the stream ID, which cannot be modified during the publishing process, the stream extra information can be modified midway through the stream corresponding to the stream ID. Developers can synchronize variable content related to stream IDs based on stream additional information.

When to call: After the engine is created [createEngine], Called before and after [startPublishingStream] can both take effect.
Related callbacks: Users can obtain the execution result of the function through [ZegoPublisherSetStreamExtraInfoCallback] callback.

Available since: 1.1.0
Restrictions: None.

startPreview

startPreview(canvas?: ZegoCanvas, channel?: ZegoPublishChannel): void

Starts/Updates the local video preview (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
canvas	ZegoCanvas	The view used to display the preview image. If the view is set to null, no preview will be made.
channel	ZegoPublishChannel	Publish stream channel

Details

The user can see his own local image by calling this function.

Use cases: It can be used for local preview in real-time connecting wheat, live broadcast and other scenarios.
When to call: After [createEngine].
Caution: 1. The preview function does not require you to log in to the room or publish the stream first. But after exiting the room, SDK internally actively stops previewing by default. 2. Local view and preview modes can be updated by calling this function again. The user can only preview on one view. If you call [startPreview] again to pass in a new view, the preview screen will only be displayed in the new view. 3. You can set the mirror mode of the preview by calling the [setVideoMirrorMode] function. The default preview setting is image mirrored. 4. When this function is called, the audio and video engine module inside SDK will start really, and it will start to try to collect audio and video. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

stopPreview

stopPreview(channel?: ZegoPublishChannel): void

Stops the local preview (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publish stream channel

Details

This function can be called to stop the preview when the preview is not needed locally.

Caution: Stopping the preview will not affect the publish stream and playing stream functions. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

setVideoConfig

setVideoConfig(config: ZegoVideoConfig, channel?: ZegoPublishChannel): void

Sets up the video configurations (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoVideoConfig	Video configuration, the SDK provides a common setting combination of resolution, frame rate and bit rate, they also can be customized.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set the video frame rate, bit rate, video capture resolution, and video encoding output resolution.

Default value: The default video capture resolution is 360p, the video encoding output resolution is 360p, the bit rate is 600 kbps, and the frame rate is 15 fps.
When to call: After [createEngine].
Caution: Developers should note that the wide and high resolution of the mobile end is opposite to the wide and high resolution of the PC. For example, in the case of 360p, the resolution of the mobile end is 360x640, and the resolution of the PC end is 640x360. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: It is necessary to set the relevant video configuration before [startPreview], and only support the modification of the encoding resolution, the bit rate and the frame rate after [startPreview].

getVideoConfig

getVideoConfig(channel?: ZegoPublishChannel): ZegoVideoConfig

Gets the current video configurations (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publish stream channel

Details

This function can be used to get the specified publish channel's current video frame rate, bit rate, video capture resolution, and video encoding output resolution. This function is only available in ZegoExpressVideo SDK!

Return

Video configuration object

setVideoMirrorMode

setVideoMirrorMode(mirrorMode: ZegoVideoMirrorMode, channel?: ZegoPublishChannel): void

Sets the video mirroring mode (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mirrorMode	ZegoVideoMirrorMode	Mirror mode for previewing or publishing the stream.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set whether the local preview video and the published video have mirror mode enabled. For specific mirroring mode.

When to call: After [createEngine].

Available since: 1.1.0
Restrictions: This setting only works if the SDK is responsible for rendering. This function is only available in ZegoExpressVideo SDK!

setAppOrientation

setAppOrientation(orientation: ZegoOrientation, channel?: ZegoPublishChannel): void

Sets the video orientation (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
orientation	ZegoOrientation	Video orientation.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set the video orientation.

Use cases: When users use mobile devices to conduct live broadcasts or video calls, they can set different video directions according to the scene.
When to call: After [createEngine].

Available since: 1.1.0
Restrictions: Currently only supports iOS and Android platforms. This function is only available in ZegoExpressVideo SDK!

setAudioConfig

setAudioConfig(config: ZegoAudioConfig, channel?: ZegoPublishChannel): void

Sets up the audio configurations for the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoAudioConfig	Audio config.
channel	ZegoPublishChannel	Publish stream channel.

Details

You can set the combined value of the audio codec, bit rate, and audio channel through this function. If the preset value cannot meet the developer's scenario, the developer can set the parameters according to the business requirements.

Default value: The default audio config refers to the default value of [ZegoAudioConfig].
When to call: After the engine is created [createEngine], and before publishing [startPublishingStream].
Related APIs: [getAudioConfig].

Available since: 1.3.4
Restrictions: None.

getAudioConfig

getAudioConfig(channel?: ZegoPublishChannel): ZegoAudioConfig

Gets the current audio configurations from the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publish stream channel.

Details

You can get the current audio codec, bit rate, and audio channel through this function.

When to call: After the engine is created [createEngine].
Related APIs: [setAudioConfig].

Available since: 1.8.0
Restrictions: None.

Return

Audio config.

setPublishStreamEncryptionKey

setPublishStreamEncryptionKey(key: string, channel?: ZegoPublishChannel): void

Set encryption key for the publishing stream for the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
key	string	The encryption key, note that the key length only supports 16/24/32 bytes.
channel	ZegoPublishChannel	Publish stream channel.

Details

Support calling this function to update the encryption key while publishing stream.

When to call: After the engine is created [createEngine], Called before and after [startPublishingStream] can both take effect.
Caution: that developers need to update the player's decryption key before updating the publisher's encryption key.
Related APIs: Calling [stopPublishingStream] or [logoutRoom] will clear the encryption key.

Available since: 1.19.0
Restrictions: This function is only valid when publishing stream to the Zego RTC server.

mutePublishStreamAudio

mutePublishStreamAudio(mute: boolean, channel?: ZegoPublishChannel): void

Stops or resumes sending the audio part of a stream for the specified channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether to stop sending audio streams, true means not to send audio stream, and false means sending audio stream. The default is false.
channel	ZegoPublishChannel	Publish stream channel.

Details

This function can be called when publishing the stream to realize not publishing the audio data stream. The SDK still collects and processes the audio, but send muted audio frame packets to the network. Use case: Users can call this interface when they do not want to publish any audio data. This interface does not affect [onBeforeAudioPrepAudioData].

When to call: Called after the engine is created [createEngine] can take effect.
Related callbacks: If you stop sending audio streams, the remote user that play stream of local user publishing stream can receive Mute status change notification by monitoring [onRemoteMicStateUpdate] callbacks.
Related APIs: [mutePublishStreamVideo].

Available since: 1.1.0
Restrictions: None.

mutePublishStreamVideo

mutePublishStreamVideo(mute: boolean, channel?: ZegoPublishChannel): void

Stops or resumes sending the video part of a stream for the specified channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether to stop sending video streams, true means not to send video stream, and false means sending video stream. The default is false.
channel	ZegoPublishChannel	Publish stream channel.

Details

This function can be called when publishing the stream to realize not publishing the video stream. The local camera can still work normally, can capture, preview and process video images normally, but does not send the video data to the network.

When to call: Called after the engine is created [createEngine] can take effect.
Related callbacks: If you stop sending video streams locally, the remote user that play stream of local user publishing stream can receive Mute status change notification by monitoring [onRemoteCameraStateUpdate] callbacks.
Related APIs: [mutePublishStreamAudio]. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

enableTrafficControl

enableTrafficControl(enable: boolean, property: number, channel?: ZegoPublishChannel): void

Enables or disables the traffic control for the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable traffic control. The default is ture.
property	number	Adjustable property of traffic control, bitmask format. Should be one or the combinations of [ZegoTrafficControlProperty] enumeration. [AdaptiveFPS] as default.
channel	ZegoPublishChannel	Publish stream channel.

Details

Enabling traffic control allows the SDK to adjust the audio and video streaming bitrate according to the current upstream network environment conditions, or according to the counterpart's downstream network environment conditions in a one-to-one interactive scenario, to ensure smooth results. At the same time, you can further specify the attributes of traffic control to adjust the corresponding control strategy.

Default value: Enable.
When to call: After the engine is created [createEngine], Called before [startPublishingStream] can take effect.

Available since: 1.5.0
Restrictions: Only support RTC publish.

setMinVideoBitrateForTrafficControl

  setMinVideoBitrateForTrafficControl(bitrate: number, mode: ZegoTrafficControlMinVideoBitrateMode, channel?: ZegoPublishChannel): void

Sets the minimum video bitrate for traffic control for the specified publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
bitrate	number	Minimum video bitrate (kbps).
mode	ZegoTrafficControlMinVideoBitrateMode	Video sending mode below the minimum bitrate.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set the control strategy when the video bitrate reaches the lowest threshold during flow control. When the bitrate is lower than the minimum threshold, you can choose not to send video data or send it at a very low frame bitrate.

Default value: There is no control effect of the lowest threshold of video bitrate.
When to call: After the engine is created [createEngine], Called before [startPublishingStream] can take effect.
Related APIs: [enableTrafficControl]. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: The traffic control must be turned on [enableTrafficControl].

setMinVideoFpsForTrafficControl

setMinVideoFpsForTrafficControl(fps: number, channel?: ZegoPublishChannel): void

Sets the minimum video frame rate threshold for traffic control.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
fps	number	The minimum video frame rate threshold for traffic control(fps).
channel	ZegoPublishChannel	Publish stream channel.

Details

When enabling traffic control [enableTrafficControl], and its parameter [property] includes the attribute AdaptiveFPS, the minimum frame rate of the video will not be lower than the value set by the [setMinVideoFpsForTrafficControl] interface. A value of 0 indicates no limit.

Default value: There is no control effect of the lowest threshold of video frame rate.
When to call: The call takes effect after the engine [createEngine] is created.
Related APIs: [enableTrafficControl].
Caution: If you need to cancel the limit of the setting value, you can set it to 0. This function is only available in ZegoExpressVideo SDK!

Available since: 2.17.0
Restrictions: The traffic control must be turned on [enableTrafficControl]. And its parameter [property] must contain AdaptiveFPS, Please refer to [ZegoTrafficControlProperty] for details.

setMinVideoResolutionForTrafficControl

setMinVideoResolutionForTrafficControl(width: number, height: number, channel?: ZegoPublishChannel): void

Sets the minimum video resolution threshold for traffic control.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
width	number	The flow controls the width of the lowest video resolution.
height	number	The flow controls the height of the lowest video resolution.
channel	ZegoPublishChannel	Publish stream channel.

Details

When enabling traffic control [enableTrafficControl], and its parameter [property] includes the attribute AdaptiveResolution, the minimum resolution of the video will not be lower than the value set by the [setMinVideoResolutionForTrafficControl] interface. A value of 0 indicates no limit.

Default value: There is no control effect of the lowest threshold of video resolution.
When to call: The call takes effect after the engine [createEngine] is created.
Related APIs: [enableTrafficControl].
Caution: If you need to cancel the limit of the setting value, you can set width and height to 0. This function is only available in ZegoExpressVideo SDK!

Available since: 2.17.0
Restrictions: The traffic control must be turned on [enableTrafficControl]. And its parameter [property] must contain AdaptiveResolution, Please refer to [ZegoTrafficControlProperty] for details.

setCaptureVolume

setCaptureVolume(volume: number): void

Sets the audio recording volume for stream publishing.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
volume	number	The volume gain percentage, the range is 0 ~ 200, and the default value is 100, which means 100% of the original collection volume of the device.

Details

This function is used to perform gain processing based on the device's collected volume. The local user can control the sound level of the audio stream sent to the remote end.

Default value: Default is 100.
When to call: After creating the engine [createEngine].
Related APIs: Set the playing stream volume [setPlayVolume].

Available since: 1.13.0
Restrictions: The capture volume can be dynamically set during publishing.

enableHardwareEncoder

enableHardwareEncoder(enable: boolean): void

Enables or disables hardware encoding.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable hardware encoding, true: enable hardware encoding, false: disable hardware encoding.

Details

Whether to use the hardware encoding function when publishing the stream, the GPU is used to encode the stream and to reduce the CPU usage.

When to call: The setting can take effect before the stream published. If it is set after the stream published, the stream should be stopped first before it takes effect.
Caution: Because hard-coded support is not particularly good for a few models, SDK uses software encoding by default. If the developer finds that the device is hot when publishing a high-resolution audio and video stream during testing of some models, you can consider calling this function to enable hard coding.

Available since: 1.1.0

setCapturePipelineScaleMode

setCapturePipelineScaleMode(mode: ZegoCapturePipelineScaleMode): void

Sets the timing of video scaling in the video capture workflow. You can choose to do video scaling right after video capture (the default value) or before encoding.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoCapturePipelineScaleMode	The capture scale timing mode.

When to call: This function needs to be set before call [startPreview] or [startPublishingStream].
Caution: The main effect is Whether the local preview is affected when the acquisition resolution is different from the encoding resolution. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

isVideoEncoderSupported

isVideoEncoderSupported(codecID: ZegoVideoCodecID): boolean

Whether the specified video encoding type is supported.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
codecID	ZegoVideoCodecID	Video codec id. Required: Yes.

Details

Whether the specified video encoding is supported depends on the following aspects, whether the hardware model supports hard encoding, whether the performance of the hardware model supports soft encoding, and whether the SDK has the encoding module.

When to call: After creating the engine.
Caution: It is recommended that users call this interface to obtain H.265 encoding support capability before publish stream with H.265 encoding, if not supported, you can use other encodings for publish, such as H.264.On the mobile platform, the SDK only supports H.265 hardware encoding, and it is affected by the model and hardware capabilities.

Available since: 2.12.0 and above

Return

Whether the specified video encoding is supported.Value range: true means support, you can use this encoding format for publish; false means the is not supported, and the encoding format cannot be used for publish.

setAppOrientationMode

setAppOrientationMode(mode: ZegoOrientationMode): void

Set the orientation mode of the video.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoOrientationMode	Orientation mode of the video.

Details

In order to simplify the complexity of processing video screen rotation for mobile developers, the SDK supports setting multiple video orientation modes, and developers can choose different modes according to the needs of the scene.

Use cases: Scenarios for live streaming or video calls using mobile devices.
Default value: Custom mode.
When to call: This function needs to be valid after calling [createEngine] and before calling preview [startPreview] or push stream [startPublishingStream].
Caution:
1. It is valid for all channels.
2. The adaptive mode takes effect in preview, streaming, and mixed streaming scenarios. It does not support external video capture, media player, cloud recording, local recording, or publishing/playing stream through CDN.
Related APIs: You can call the [setAppOrientation] function to set the orientation of the App in custom mode.

Available since: 2.23.0

setVideoSource

setVideoSource(source: ZegoVideoSourceType, instanceID?: number, channel?: ZegoPublishChannel): number

Set a video capture instance as video capture source for the specified channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
source	ZegoVideoSourceType	Video capture source.
instanceID	number	Video capture source instance id.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set video capture source for switching between different video capture sources.

Use cases: Typically used in educational scenarios that require switching between different video capture sources.
When to call: After the engine is created [createEngine].
Caution: 1. Main push channel ZegoPublishChannel.Main does not support using ZegoVideoSourceType.Player and ZegoVideoSourceType.MainPublishChannel video source type.

When using ZegoVideoSourceType.Player and ZegoVideoSourceType.MainPublishChannel video source type in aux publish channel ZegoPublishChannel.Aux, must ensure that physical device works on main publish channel ZegoPublishChannel.Main.
Preemptive video sources are not allowed to be used on multiple channels at the same time, such as ZegoVideoSourceType.Camera and ZegoVideoSourceType.ScreenCapture.
The other publish channel can copy the main publish channel only when the main publish channel uses internal video capture. A maximum of one copy is supported.
When using ZegoVideoSourceType.Player video source type, please ensure that the ZegoMediaPlayer instance is created successfully. This function is only available in ZegoExpressVideo SDK!

Available since: 3.1.0
Restrictions: None.

setAudioSource

setAudioSource(source: ZegoAudioSourceType, channel?: ZegoPublishChannel): number

Set audio capture source for the specified channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
source	ZegoAudioSourceType	Audio capture source.
channel	ZegoPublishChannel	Publish stream channel.

Details

Set audio capture source for switching between different audio capture sources.

Use cases: Typically used in educational scenarios that require switching between different audio capture sources.
When to call: After the engine is created [createEngine].
Caution: 1. Main push channel ZegoPublishChannel.Main does not support using ZegoAudioSourceType.MediaPlayer and ZegoAudioSourceType.MainPublishChannel audio source type.

When using ZegoAudioSourceType.MediaPlayer and ZegoAudioSourceType.MainPublishChannel audio source type in aux publish channel ZegoPublishChannel.Aux, must ensure that physical device works on main publish channel ZegoPublishChannel.Main.
Preemptive audio sources are not allowed to be used on multiple channels at the same time, such as ZegoAudioSourceType.Microphone.
When using ZegoAudioSourceType.MediaPlayer audio source type, please ensure that the ZegoMediaPlayer instance is created successfully.

Available since: 3.1.0

startPlayingStream

startPlayingStream(streamID: string, canvas?: ZegoCanvas, config?: ZegoPlayerConfig): void

Starts playing a stream from ZEGO RTC server or from third-party CDN. Support multi-room mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID, a string of up to 256 characters. Caution: Only support numbers, English characters and '-', '_'.
canvas	ZegoCanvas	The view used to display the play audio and video stream's image. When the view is set to [null], no video is displayed, only audio is played.
config	ZegoPlayerConfig	Advanced player configuration Room [roomID] in [ZegoPlayerConfig] is the login roomID.

Details

Play audio and video streams from the ZEGO RTC server or CDN.

Use cases: In real-time or live broadcast scenarios, developers can listen to the [onRoomStreamUpdate] event callback to obtain the new stream information in the room where they are located, and call this interface to pass in streamID for play streams.
When to call: After [loginRoom].
Caution: 1. The developer can update the player canvas by calling this function again (the streamID must be the same). 2. After the first play stream failure due to network reasons or the play stream is interrupted, the default time for SDK reconnection is 20min. 3. In the case of poor network quality, user play may be interrupted, the SDK will try to reconnect, and the current play status and error information can be obtained by listening to the [onPlayerStateUpdate] event. please refer to https://docs.zegocloud.com/faq/reconnect. 4. Playing the stream ID that does not exist, the SDK continues to try to play after calling this function. After the stream ID is successfully published, the audio and video stream can be actually played. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

stopPlayingStream

stopPlayingStream(streamID: string): void

Stops playing a stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.

Details

Play audio and video streams from the ZEGO RTC server.

Use cases: In the real-time scenario, developers can listen to the [onRoomStreamUpdate] event callback to obtain the delete stream information in the room where they are located, and call this interface to pass in streamID for stop play streams.
When to call: After [loginRoom].
Caution: 1. When stopped, the attributes set for this stream previously, such as [setPlayVolume], [mutePlayStreamAudio], [mutePlayStreamVideo], etc., will be invalid and need to be reset when playing the the stream next time.

After stopping pulling, the iOS platform view will clear the last frame by default and keep the background color of the view. The Android platform view remains at the last frame by default. If you need to clear the last frame, please contact ZEGO technical support.

Available since: 1.1.0
Restrictions: None.

setPlayStreamDecryptionKey

setPlayStreamDecryptionKey(streamID: string, key: string): void

Set decryption key for the playing stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
key	string	The decryption key, note that the key length only supports 16/24/32 bytes.

Details

When streaming, the audio and video data will be decrypted according to the set key.

Use cases: Usually used in scenarios that require high security for audio and video calls.
When to call: after [createEngine], after the play stream can be changed at any time.
Related APIs: [setPublishStreamEncryptionKey]Set the publish stream encryption key.
Caution: This interface can only be called if encryption is set on the publish. Calling [stopPlayingStream] or [logoutRoom] will clear the decryption key.

Available since: 1.19.0
Restrictions: This function is only valid when calling from Zego RTC or L3 server.

setPlayVolume

setPlayVolume(streamID: string, volume: number): void

Sets the stream playback volume.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
volume	number	Volume percentage. The value ranges from 0 to 200, and the default value is 100.

Details

Set the sound size of the stream, the local user can control the playback volume of the audio stream.

When to call: after called [startPlayingStream].
Related APIs: [setAllPlayStreamVolume] Set all stream volume.
Caution: You need to reset after [stopPlayingStream] and [startPlayingStream]. This function and the [setAllPlayStreamVolume] function overwrite each other, and the last call takes effect.

Available since: 1.16.0
Restrictions: None.

setAllPlayStreamVolume

setAllPlayStreamVolume(volume: number): void

Sets the all stream playback volume.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
volume	number	Volume percentage. The value ranges from 0 to 200, and the default value is 100.

Details

Set the sound size of the stream, the local user can control the playback volume of the audio stream.

When to call: after called [startPlayingStream].
Related APIs: [setPlayVolume] Set the specified streaming volume.
Caution: Set the specified streaming volume and [setAllPlayStreamVolume] interface to override each other, and the last call takes effect.

Available since: 2.3.0
Restrictions: None.

setPlayStreamVideoType

setPlayStreamVideoType(streamID: string, streamType: ZegoVideoStreamType): void

Set play video stream type.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
streamType	ZegoVideoStreamType	Video stream type.

Details

When the publish stream sets the codecID to SVC through [setVideoConfig], the puller can dynamically set and select different stream types (small resolution is one-half of the standard layer).

Use cases: In general, when the network is weak or the rendered UI window is small, you can choose to pull videos with small resolutions to save bandwidth.
When to call: before or after called [startPlayingStream].

Available since: 2.3.0
Restrictions: None. This function is only available in ZegoExpressVideo SDK!

setPlayStreamBufferIntervalRange

setPlayStreamBufferIntervalRange(streamID: string, minBufferInterval: number, maxBufferInterval: number): void

Set the adaptive adjustment interval range of the buffer for playing stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
minBufferInterval	number	The lower limit of the buffer adaptation interval, in milliseconds. The default value is 0ms.
maxBufferInterval	number	The upper limit of the buffer adaptation interval, in milliseconds. The default value is 4000ms.

Details

Set the range of adaptive adjustment of the internal buffer of the sdk when streaming is 0-4000ms.

Use cases: Generally, in the case of a poor network environment, adjusting and increasing the playback buffer of the pull stream will significantly reduce the audio and video freezes, but will increase the delay.
When to call: after called [createEngine], if it has been set, you need to reset it every time you play the stream again.
Caution: When the upper limit of the cache interval set by the developer exceeds 4000ms, the value will be 4000ms. When the upper limit of the cache interval set by the developer is less than the lower limit of the cache interval, the upper limit will be automatically set as the lower limit.

Available since: 2.1.0
Restrictions: None.

setPlayStreamFocusOn

setPlayStreamFocusOn(streamID: string): void

Set the weight of the pull stream priority.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.

Details

Set the weight of the streaming priority.

Use cases: This interface can be used when developers need to prioritize the quality of a audio and video stream in business（do not use in pure audio case）. For example: in class scene, if students pull multiple streams, you can set high priority for teacher stream.
When to call: after called [startPlayingStream].
Caution: By default, all streams have the same weight. Only one stream can be set with high priority, whichever is set last. After the flow is stopped, the initial state is automatically restored, and all flows have the same weight.When the local network is not good, while ensuring the focus flow, other stalls may be caused more.

Available since: 1.1.0
Restrictions: None.

mutePlayStreamAudio

mutePlayStreamAudio(streamID: string, mute: boolean): void

Whether the pull stream can receive the specified audio data.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
mute	boolean	Whether it can receive the audio data of the specified remote user when streaming, "true" means prohibition, "false" means receiving, the default value is "false".

Details

In the process of real-time audio and video interaction, local users can use this function to control whether to receive audio data from designated remote users when pulling streams as needed. When the developer does not receive the audio receipt, the hardware and network overhead can be reduced.

Use cases: Call this function when developers need to quickly close and restore remote audio. Compared to re-flow, it can greatly reduce the time and improve the interactive experience.
When to call: This function can be called after calling [createEngine].
Caution:

When used together with [muteAllPlayAudioStreams], they can override each other's configurations.
When used together with [muteAllPlayStreamAudio], this function only works when the [muteAllPlayStreamAudio] function is set to false.
After stopping streaming, any properties previously set for this stream such as [setPlayVolume], [mutePlayStreamAudio], [mutePlayStreamVideo] and other streaming-related configurations will become invalid and need to be reset before the next stream is pulled.

Related APIs: You can call the [muteAllPlayStreamAudio] function to control whether to receive all audio data. When the two functions [muteAllPlayStreamAudio] and [mutePlayStreamAudio] are set to false at the same time, the local user can receive the audio data of the remote user when the stream is pulled: 1. When the [muteAllPlayStreamAudio(true)] function is called, it is globally effective, that is, local users will be prohibited from receiving all remote users' audio data. At this time, the [mutePlayStreamAudio] function will not take effect whether it is called before or after [muteAllPlayStreamAudio].2. When the [muteAllPlayStreamAudio(false)] function is called, the local user can receive the audio data of all remote users. At this time, the [mutePlayStreamAudio] function can be used to control whether to receive a single audio data. Calling the [mutePlayStreamAudio(true, streamID)] function allows the local user to receive audio data other than the streamID; calling the [mutePlayStreamAudio(false, streamID)] function allows the local user to receive all audio data.

Available since: 1.1.0

mutePlayStreamVideo

mutePlayStreamVideo(streamID: string, mute: boolean): void

Whether the pull stream can receive the specified video data.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
streamID	string	Stream ID.
mute	boolean	Whether it is possible to receive the video data of the specified remote user when streaming, "true" means prohibition, "false" means receiving, the default value is "false". The default value for automatically played streams within the SDK is false.

Details

In the process of real-time video and video interaction, local users can use this function to control whether to receive video data from designated remote users when pulling streams as needed. When the developer does not receive the video data, the hardware and network overhead can be reduced.

Use cases: This function can be called when developers need to quickly close and resume watching remote video. Compared to re-flow, it can greatly reduce the time and improve the interactive experience.
When to call: This function can be called after calling [createEngine].
Caution:

When used together with [muteAllPlayVideoStreams], they can override each other's configurations.
When used together with [muteAllPlayStreamAudio], this function only works when the [muteAllPlayStreamVideo] function is set to false.
When you mute the video stream, the view remains at the last frame by default, if you need to clear the last frame, please contact ZEGO technical support.
After stopping streaming, any properties previously set for this stream such as [setPlayVolume], [mutePlayStreamAudio], [mutePlayStreamVideo] and other streaming-related configurations will become invalid and need to be reset before the next stream is pulled.

Related APIs: You can call the [muteAllPlayStreamVideo] function to control whether to receive all video data. When the two functions [muteAllPlayStreamVideo] and [mutePlayStreamVideo] are set to false at the same time, the local user can receive the video data of the remote user when the stream is pulled: 1. When the [muteAllPlayStreamVideo(true)] function is called, it will take effect globally, that is, local users will be prohibited from receiving all remote users' video data. At this time, the [mutePlayStreamVideo] function will not take effect whether it is called before or after [muteAllPlayStreamVideo]. 2. When the [muteAllPlayStreamVideo(false)] function is called, the local user can receive the video data of all remote users. At this time, the [mutePlayStreamVideo] function can be used to control whether to receive a single video data. Call the [mutePlayStreamVideo(true, streamID)] function, the local user can receive other video data other than the streamID; call the [mutePlayStreamVideo(false, streamID)] function, the local user can receive all the video data. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0

muteAllPlayStreamAudio

muteAllPlayStreamAudio(mute: boolean): void

Can the pull stream receive all audio data. (When set to true, calling [mutePlayStreamAudio] will not take effect)

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether it is possible to receive audio data from all remote users when streaming, "true" means prohibition, "false" means receiving, and the default value is "false".

Details

In the process of real-time audio and video interaction, local users can use this function to control whether to receive audio data from all remote users when pulling streams (including the audio streams pushed by users who have newly joined the room after calling this function). By default, users can receive audio data pushed by all remote users after joining the room. When the developer does not receive the audio receipt, the hardware and network overhead can be reduced.

Use cases: Call this function when developers need to quickly close and restore remote audio. Compared to re-flow, it can greatly reduce the time and improve the interactive experience.
When to call: This function can be called after calling [createEngine].
Caution: This function cannot be used together with [muteAllPlayAudioStreams] throughout the SDK lifecycle.
Related APIs: You can call the [mutePlayStreamAudio] function to control whether to receive a single piece of audio data. When the two functions [muteAllPlayStreamAudio] and [mutePlayStreamAudio] are set to false at the same time, the local user can receive the audio data of the remote user when the stream is pulled: 1. When the [muteAllPlayStreamAudio(true)] function is called, it takes effect globally, that is, local users will be prohibited from receiving audio data from all remote users. At this time, the [mutePlayStreamAudio] function will not take effect no matter if the [mutePlayStreamAudio] function is called before or after [muteAllPlayStreamAudio]. 2. When the [muteAllPlayStreamAudio(false)] function is called, the local user can receive the audio data of all remote users. At this time, the [mutePlayStreamAudio] function can be used to control whether to receive a single audio data. Calling the [mutePlayStreamAudio(true, streamID)] function allows the local user to receive audio data other than the streamID; calling the [mutePlayStreamAudio(false, streamID)] function allows the local user to receive all audio data.

Available since: 2.4.0

muteAllPlayStreamVideo

muteAllPlayStreamVideo(mute: boolean): void

Can the pull stream receive all video data. (When set to true, calling [mutePlayStreamVideo] will not take effect)

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether it is possible to receive all remote users' video data when streaming, "true" means prohibition, "false" means receiving, and the default value is "false".

Details

In the process of real-time video and video interaction, local users can use this function to control whether to receive all remote users' video data when pulling the stream (including the video stream pushed by the new user who joins the room after calling this function). By default, users can receive video data pushed by all remote users after joining the room. When the developer does not receive the video data, the hardware and network overhead can be reduced.

Use cases: This function can be called when developers need to quickly close and resume watching remote video. Compared to re-flow, it can greatly reduce the time and improve the interactive experience.
When to call: This function can be called after calling [createEngine].
Caution:

This function cannot be used together with [muteAllPlayVideoStreams] throughout the SDK lifecycle.
When you mute the video stream, the view remains at the last frame by default, if you need to clear the last frame, please contact ZEGO technical support.

Related APIs: You can call the [mutePlayStreamVideo] function to control whether to receive a single piece of video data. When the two functions [muteAllPlayStreamVideo] and [mutePlayStreamVideo] are set to false at the same time, the local user can receive the video data of the remote user when the stream is pulled: 1. When the [muteAllPlayStreamVideo(true)] function is called, it will take effect globally, that is, the local user will be prohibited from receiving all remote users' video data. At this time, the [mutePlayStreamVideo] function will not take effect whether it is called before or after [muteAllPlayStreamVideo]. 2. When the [muteAllPlayStreamVideo(false)] function is called, the local user can receive the video data of all remote users. At this time, the [mutePlayStreamVideo] function can be used to control whether to receive a single video data. Call the [mutePlayStreamVideo(true, streamID)] function, the local user can receive other video data other than the streamID; call the [mutePlayStreamVideo(false, streamID)] function, the local user can receive all the video data. This function is only available in ZegoExpressVideo SDK!

Available since: 2.4.0

enableHardwareDecoder

enableHardwareDecoder(enable: boolean): void

Enables or disables hardware decoding.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to turn on hardware decoding switch, true: enable hardware decoding, false: disable hardware decoding.

Details

Control whether hardware decoding is used when playing streams, with hardware decoding enabled the SDK will use the GPU for decoding, reducing CPU usage.

Use cases: If developers find that the device heats up badly when playing large resolution audio and video streams during testing on some models, consider calling this function to enable hardware decoding.
Default value: Hardware decoding is disabled by default when this interface is not called.
When to call: This function needs to be called after [createEngine] creates an instance.
Caution: Need to be called before calling [startPlayingStream], if called after playing the stream, it will only take effect after stopping the stream and re-playing it. Once this configuration has taken effect, it will remain in force until the next call takes effect.

Available since: 1.1.0
Restrictions: None.

enableCheckPoc

enableCheckPoc(enable: boolean): void

Enables or disables frame order detection.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to turn on frame order detection, true: enable check poc, false: disable check poc.

Details

Control whether to turn on frame order detection.

Use cases: Turning on frame order detection when pulling cdn's stream will prevent splash screens.
Default value: Turn on frame order detection by default when this interface is not called.
When to call: This function needs to be called after [createEngine] creates an instance.
Caution: Turn off frame order detection during playing stream may result in a brief splash screen. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

isVideoDecoderSupported

isVideoDecoderSupported(codecID: ZegoVideoCodecID): boolean

Whether the specified video decoding format is supported.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
codecID	ZegoVideoCodecID	Video codec id.Required: Yes.

Details

Whether the specified video decoding is supported depends on the following aspects: whether the hardware model supports hard decoding, whether the performance of the hardware model supports soft decoding, and whether the SDK includes the decoding module.

When to call: After creating the engine.
Caution: It is recommended that users call this interface to obtain the H.265 decoding support capability before pulling the H.265 stream. If it is not supported, the user can pull the stream of other encoding formats, such as H.264.

Available since: 2.12.0

Return

Whether the specified video decoding format is supported; true means supported, you can use this decoding format for playing stream; false means not supported, the SDK does not recommend users to play streams of this encoding format. If users force the play, low frame rates may occur.

muteMicrophone

muteMicrophone(mute: boolean): void

Mutes or unmutes the microphone.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether to mute (disable) the microphone, `true`: mute (disable) microphone, `false`: enable microphone.

Details

This function is used to control whether to use the collected audio data. Mute (turn off the microphone) will use the muted data to replace the audio data collected by the device for streaming. At this time, the microphone device will still be occupied. Use case: Users can call this interface by only turning off the human voice collected by the microphone and not turning off the music sound of the media player. This interface affects [onBeforeAudioPrepAudioData].

Default value: The default is false, which means no muting.
When to call: After creating the engine [createEngine].
Related APIs: Developers who want to control whether to use microphone on the UI should use this function to avoid unnecessary performance overhead by using the [enableAudioCaptureDevice]. You can use [isMicrophoneMuted] to check if the microphone is muted.

Available since: 1.1.0
Restrictions: None.

isMicrophoneMuted

isMicrophoneMuted(): boolean

Checks whether the microphone is muted.

Declared in ZegoExpressEngine.ts

Used to determine whether the microphone is set to mute.

When to call: After creating the engine [createEngine].
Related APIs: [muteMicrophone].

Available since: 1.1.0
Restrictions: None.

Whether the microphone is muted; true: the microphone is muted; false: the microphone is enable (not muted).

muteSpeaker

muteSpeaker(mute: boolean): void

Mutes or unmutes the audio output speaker.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mute	boolean	Whether to mute (disable) speaker audio output, `true`: mute (disable) speaker audio output, `false`: enable speaker audio output.

Details

After mute speaker, all the SDK sounds will not play, including playing stream, mediaplayer, etc.

Default value: The default is false, which means no muting.
When to call: After creating the engine [createEngine].

Available since: 1.1.0
Restrictions: None.

isSpeakerMuted

isSpeakerMuted(): boolean

Checks whether the audio output speaker is muted.

Declared in ZegoExpressEngine.ts

Used to determine whether the audio output is muted.

When to call: After creating the engine [createEngine].
Related APIs: [muteSpeaker].

Available since: 1.1.0
Restrictions: None.

Whether the speaker is muted; true: the speaker is muted; false: the speaker is enable (not muted).

getAudioDeviceList

getAudioDeviceList(deviceType: ZegoAudioDeviceType): ZegoDeviceInfo[]

Gets a list of audio devices.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type

Details

Only for Windows / macOS / Linux

Return

Audo device List

getDefaultAudioDeviceID

getDefaultAudioDeviceID(deviceType: ZegoAudioDeviceType): string

Get the device ID of the default audio device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type

Details

Only for Windows / macOS / Linux

Return

Default Audio device ID

useAudioDevice

useAudioDevice(deviceType: ZegoAudioDeviceType, deviceID: string): void

Chooses to use the specified audio device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]

Details

Chooses to use the specified audio device.

When to call: After creating the engine [createEngine].

Available since: 1.1.0
Restrictions: Only supports Windows / macOS / Linux

getAudioDeviceVolume

getAudioDeviceVolume(deviceType: ZegoAudioDeviceType, deviceID: string): number

Get volume for the specified audio device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]

Details

Get volume for the specified audio device. Only for Windows / macOS / Linux

Return

Device volume

setAudioDeviceVolume

setAudioDeviceVolume(deviceType: ZegoAudioDeviceType, deviceID: string, volume: number): void

Set volume for the specified audio device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]
volume	number	Device volume

Details

The direct operating system device may fail due to system restrictions. Please use [setCaptureVolume] and [setPlayVolume] first to adjust the volume of publish and play streams. Only for Windows / macOS / Linux

startAudioDeviceVolumeMonitor

startAudioDeviceVolumeMonitor(deviceType: ZegoAudioDeviceType, deviceID: string): void

Turn on audio device volume monitoring.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]

Details

Starts the audio device volume monitor. When the volume of the device changes, the changed volume will be called back via [onAudioDeviceVolumeChanged].

Caution: Currently, only one audio output device and one audio input device are supported to be monitored at the same time. When this API is called multiple times and the same device type is set, the device ID set to this API during the last call will be overwritten.
When to call: After creating the engine via [createEngine].
Platform differences: Only supports Windows and macOS.
Related APIs: When you no longer need to monitor the device volume, please call [stopAudioDeviceVolumeMonitor] to stop monitoring.

Available since: 1.1.0

stopAudioDeviceVolumeMonitor

stopAudioDeviceVolumeMonitor(deviceType: ZegoAudioDeviceType, deviceID: string): void

Turn off audio device volume monitoring. Only for Windows/macOS.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]

Details

Stops the audio device volume monitor.

When to call: After creating the engine via [createEngine], and when you no longer need to monitor the device volume.
Platform differences: Only supports Windows and macOS.

Available since: 1.1.0

muteAudioDevice

muteAudioDevice(deviceType: ZegoAudioDeviceType, deviceID: string, mute: boolean): void

Mutes or unmutes the audio device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]
mute	boolean	Whether to mute the audio device; `true` means to mute the audio device; `false` means to unmute the audio device.

Details

Only for Windows / macOS / Linux

setAudioDeviceMode

setAudioDeviceMode(deviceMode: ZegoAudioDeviceMode): void

Set the audio device mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceMode	ZegoAudioDeviceMode	Audio device mode

Details

Select audio equipment mode according to the need of the scene (only supported by Android and iOS).

Use cases: In the case of KTV, the General mode must be used, but in the language room, the Communication2 or Communication3 mode is required in order to avoid the sound of third-party music being collected. For details on how to set the audio device mode, see https://doc-zh.zego.im/faq/AudioDeviceMod?product=ExpressVideo&platform=macos
When to call: After creating the engine [createEngine].
Caution: This interface triggers startup switchover of the device. You are advised not to invoke this interface frequently to avoid unnecessary overhead and hardware problems. This interface may cause the volume mode to switch between call and media. If the media volume is inconsistent with the call volume, the volume may change.

Available since: 2.22.0

isAudioDeviceMuted

isAudioDeviceMuted(deviceType: ZegoAudioDeviceType, deviceID: string): boolean

Check if the audio device is muted.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type
deviceID	string	ID of a device obtained by [getAudioDeviceList]

Details

Only for Windows / macOS / Linux

Return

Whether the audio device is muted; true means the audio device is muted; false means the audio device is not muted.

enableAudioCaptureDevice

enableAudioCaptureDevice(enable: boolean): void

Enables or disables the audio capture device.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable the audio capture device, `true`: enable audio capture device, `false`: disable audio capture device.

Details

This function is used to control whether to use the audio collection device. When the audio collection device is turned off, the SDK will no longer occupy the audio device. Of course, if the stream is being published at this time, by default, mute data will be used as audio data for streaming. not support Linux.

Use cases: When the user never needs to use the audio, you can call this function to close the audio collection.
Default value: The default is true.
When to call: After creating the engine [createEngine].
Related APIs: Turning off or turning on the microphone on the hardware is a time-consuming operation, and there is a certain performance overhead when the user performs frequent operations. [muteMicrophone] is generally recommended.

Available since: 1.1.0
Restrictions: None.

getAudioRouteType

getAudioRouteType(): ZegoAudioRoute

get current audio route type.

Declared in ZegoExpressEngine.ts

Audio routing refers to the audio output device that an app uses to play audio, and common audio routes are: speakers, handsets, headphones, Bluetooth devices, and so on.

When to call: After creating the engine [createEngine].
Related APIs: Set audio route to speaker [setAudioRouteToSpeaker].

Available since: 1.1.0
Restrictions: Not supported under win or mac platforms.

setAudioRouteToSpeaker

setAudioRouteToSpeaker(defaultToSpeaker: boolean): void

Whether to use the built-in speaker to play audio.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
defaultToSpeaker	boolean	Whether to use the built-in speaker to play sound, `true`: use the built-in speaker to play sound, `false`: use the highest priority audio output device scheduled by the current system to play sound

Details

Whether to use the speaker to play audio, when you choose not to use the built-in speaker to play the sound, the SDK will select the audio output device with the highest current priority to play the sound according to the system schedule, and common audio routes are: handsets, headphones, Bluetooth devices, and so on.

When to call: After creating the engine [createEngine].
Related APIs: Get the current audio route [getAudioRouteType].

Available since: 1.1.0
Restrictions: Only switching between the earpiece and the speaker is supported. If it is a Bluetooth headset or a wired headset, it does not support routing to the speaker through this interface.

enableCamera

enableCamera(enable: boolean, channel?: ZegoPublishChannel): void

Turns on/off the camera (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to turn on the camera, `true`: turn on camera, `false`: turn off camera
channel	ZegoPublishChannel	Publishing stream channel

Details

This function is used to control whether to start the capture of the camera. After the camera is turned off, the video capture will not be performed. At this time, there will be no video data for local preview and push streaming.

Default value: The default is true which means the camera is turned on.
When to call: After creating the engine [createEngine].
Caution: In the case of using the custom video capture function [enableCustomVideoCapture], since the developer has taken over the video data capture, the SDK is no longer responsible for the video data capture, but this function still affects whether to encode or not. Therefore, when developers use custom video capture, please ensure that the value of this function is true. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

useFrontCamera

useFrontCamera(enable: boolean, channel?: ZegoPublishChannel): void

Switches to the front or the rear camera (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	[ZegoVideoSourceTypeCamera] if or not use front camera, `true`: use the front camera, `false`: use the the rear camera.
channel	ZegoPublishChannel	Publishing stream channel.

Details

This function controls whether [ZegoVideoSourceTypeCamera] uses the front camera or the rear camera (only supported by Android and iOS).

Default value: The default is true which means the front camera is used.
When to call: After creating the engine [createEngine].
Caution: When the custom video capture function [enableCustomVideoCapture] is turned on, since the developer has taken over the video data capture, the SDK is no longer responsible for the video data capture, and this function is no longer valid. This function is only available in ZegoExpressVideo SDK!

Available since: 1.1.0
Restrictions: None.

isCameraFocusSupported

isCameraFocusSupported(channel?: ZegoPublishChannel): boolean

Whether the camera supports focusing.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel

Details

Whether the camera supports focusing.

Trigger: Called after turn on preview [startPreview].
Caution: Need to start the camera successfully. This function is only available in ZegoExpressVideo SDK!

Available since: 2.14.0

Return

Whether to support focus, support is true, not support is false.

setCameraFocusMode

setCameraFocusMode(mode: ZegoCameraFocusMode, channel?: ZegoPublishChannel): void

Set the camera focus mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoCameraFocusMode	focus mode.
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the camera focus mode.

Trigger: Called after turn on preview [startPreview].

Available since: 2.14.0
Restrictions: Currently only supports iOS and Android platforms. This function is only available in ZegoExpressVideo SDK!

setCameraFocusPointInPreview

setCameraFocusPointInPreview(x: number, y: number, channel?: ZegoPublishChannel): void

Set the focus point in the preview view.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
x	number	Normalized X axis coordinate value, effective value [0,1].
y	number	Normalized Y axis coordinate value, effective value [0,1].
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the focus point in the preview view. (x, y) are the normalized coordinates in the preview view, that is, the ratio of the position of the focus point relative to the preview view and the width and height of the preview view. The upper left corner is (0, 0).

Trigger: Called after turn on preview [startPreview].
Caution: Every time the camera restarts the acquisition, the settings will become invalid and need to be reset. This function is only available in ZegoExpressVideo SDK!

Available since: 2.14.0
Restrictions: Currently only supports iOS and Android platforms.

setCameraExposureMode

setCameraExposureMode(mode: ZegoCameraExposureMode, channel?: ZegoPublishChannel): void

Set the camera exposure mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoCameraExposureMode	Exposure mode.
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the camera exposure mode.

Trigger: Called after turn on preview [startPreview].

Available since: 2.14.0
Restrictions: Currently only supports iOS and Android platforms. This function is only available in ZegoExpressVideo SDK!

setCameraExposurePointInPreview

setCameraExposurePointInPreview(x: number, y: number, channel?: ZegoPublishChannel): void

Set the exposure point in the preview view.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
x	number	Normalized X axis coordinate value, effective value [0,1].
y	number	Normalized Y axis coordinate value, effective value [0,1].
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the exposure point in the preview view. (x, y) are the normalized coordinates in the preview view, that is, the ratio of the position of the exposure point relative to the preview view and the width and height of the preview view. The upper left corner is (0, 0).

Trigger: Called after turn on preview [startPreview].
Caution: Every time the camera restarts the acquisition, the settings will become invalid and need to be reset. This function is only available in ZegoExpressVideo SDK!

Available since: 2.14.0
Restrictions: Currently only supports iOS and Android platforms.

setCameraExposureCompensation

setCameraExposureCompensation(value: number, channel?: ZegoPublishChannel): void

Set the camera exposure compensation value and support spedifying the publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
value	number	Camera exposure, the value range is [-1,1], the default 0, -1 tends to darken, 1 tends to brighten.
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the camera exposure compensation value.

Use cases: User can call this function to set the camera exposure compensation value.
When to call /Trigger: Called this function after calling [startPublishingStream] or [startPreview].
Caution: The setting will be invalid when the camera is restarted.
Platform differences: Only supports iOS and Android. This function is only available in ZegoExpressVideo SDK!

Available since: 2.10.0
Restrictions: None.

setCameraZoomFactor

setCameraZoomFactor(factor: number, channel?: ZegoPublishChannel): void

Set the zoom factor of the camera and support specifying the publish channel. Every time the camera is restarted, the camera zoom factor will return to the initial value (1.0).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
factor	number	The zoom factor of the camera, the minimum value is 1.0, and the maximum value is the return value of [getCameraMaxZoomFactor].
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the camera zoom factor. Every time the camera is restarted, the camera zoom factor will be restored to its initial value.

When to call: After creating the engine [createEngine].

Available since: 1.20.0
Restrictions: The settings will not take effect until the camera is started. This function is only available in ZegoExpressVideo SDK!

getCameraMaxZoomFactor

getCameraMaxZoomFactor(channel?: ZegoPublishChannel): number

Get the maximum zoom factor of the camera and support specifying the publish channel.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
channel	ZegoPublishChannel	Publishing stream channel

Details

Set the camera zoom factor. Every time the camera is restarted, the camera zoom factor will be restored to its initial value.

When to call: This is only available after the camera has been successfully started, and can generally be called when the captured first frame is received [onPublisherCapturedVideoFirstFrame] callback.

Available since: 1.20.0
Restrictions: None. This function is only available in ZegoExpressVideo SDK!

Return

The maximum zoom factor of the camera.

enableCameraAdaptiveFPS

enableCameraAdaptiveFPS(enable: boolean, minFPS: number, maxFPS: number, channel?: ZegoPublishChannel): void

Enable camera adaptive frame rate.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable camera adaptive frame rate. true means on, false means off.Off by default.
minFPS	number	Desired minimum frame rate, 15 recommended. Unit: fps.
maxFPS	number	Desired minimum frame rate, 25 recommended. Unit: fps.
channel	ZegoPublishChannel	Publishing stream channel.

Details

After enabling, the SDK matches the capture frame rate range supported by the camera according to the set frame rate range, and dynamically adjusts the capture frame rate of the camera according to the ambient brightness within this range to improve the screen brightness when the set frame rate is too high.

Use cases: The frame rate set by the user on the streaming end is too high, and the ambient lighting is low, so the subject cannot be displayed or recognized normally. For example, live broadcast scenes with high exposure requirements.
When to call: After creating the engine [createEngine], before the camera starts.
Caution: Takes When calling [setVideoConfig] to set the frame rate lower than the expected minimum frame rate, the frame rate value set by [setVideoConfig] will be used. Due to the different hardware and algorithm strategies of different mobile phone manufacturers, the effect of this interface is different on different models or on the front and rear cameras of the same model.
Related APIs: Through [setVideoConfig], you can set the camera capture frame rate and the encoder encoding frame rate.

Available since: 2.20.0

useVideoDevice

useVideoDevice(deviceID: string, channel?: ZegoPublishChannel): void

Chooses to use the specified video device (for the specified channel).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceID	string	ID of a device obtained by [getVideoDeviceList]
channel	ZegoPublishChannel	Publishing stream channel

Details

Only for Windows / macOS / Linux This function is only available in ZegoExpressVideo SDK!

getVideoDeviceList

getVideoDeviceList(): ZegoDeviceInfo[]

Gets a list of video devices.

Declared in ZegoExpressEngine.ts

Only for Windows / macOS / Linux This function is only available in ZegoExpressVideo SDK!

Video device List

getDefaultVideoDeviceID

getDefaultVideoDeviceID(): string

Get the device ID of the default video device.

Declared in ZegoExpressEngine.ts

Only for Windows / macOS / Linux This function is only available in ZegoExpressVideo SDK!

Default video device ID

startSoundLevelMonitor

startSoundLevelMonitor(config?: ZegoSoundLevelConfig): void

Starts sound level monitoring. Support enable some advanced feature.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoSoundLevelConfig	Configuration for starts the sound level monitor.

Details

After starting monitoring, you can receive local audio sound level via [onCapturedSoundLevelUpdate] callback, and receive remote audio sound level via [onRemoteSoundLevelUpdate] callback. Before entering the room, you can call [startPreview] with this function and combine it with [onCapturedSoundLevelUpdate] callback to determine whether the audio device is working properly.

Use cases: During the publishing and playing process, determine who is talking on the wheat and do a UI presentation.
When to call: After the engine is created [createEngine].
Caution: 1. [onCapturedSoundLevelUpdate] and [onRemoteSoundLevelUpdate] callback notification period is the value set by the parameter. 2. After the sound monitoring is started, even if the local audio capture is not started, [onCapturedSoundLevelUpdate] will have a callback, and the sound level is 0.

Available since: 2.10.0

stopSoundLevelMonitor

stopSoundLevelMonitor(): void

Stops sound level monitoring.

Declared in ZegoExpressEngine.ts

After the monitoring is stopped, the callback of the local/remote audio sound level will be stopped.

When to call: After the engine is created [createEngine].
Related APIs: Soundwave monitoring can be initiated via [startSoundLevelMonitor].

Available since: 1.1.0

startAudioSpectrumMonitor

startAudioSpectrumMonitor(millisecond?: number): void

Starts audio spectrum monitoring. Support setting the listening interval.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
millisecond	number	Monitoring time period of the audio spectrum, in milliseconds, the minimum value is 10. Default is 500 ms.

Details

After starting monitoring, you can receive local audio spectrum via [onCapturedAudioSpectrumUpdate] callback, and receive remote audio spectrum via [onRemoteAudioSpectrumUpdate] callback.

Use cases: In the host K song scene, has been published or played under the premise that the host or audience to see the tone and volume change animation.
When to call: After the engine is created [createEngine].
Caution: [onCapturedAudioSpectrumUpdate] and [onRemoteAudioSpectrumUpdate] callback notification period is the value set by the parameter.

Available since: 1.15.0

stopAudioSpectrumMonitor

stopAudioSpectrumMonitor(): void

Stops audio spectrum monitoring.

Declared in ZegoExpressEngine.ts

After the monitoring is stopped, the callback of the local/remote audio spectrum will be stopped.

When to call: After the engine is created [createEngine].
Related APIs: Audio spectrum monitoring can be initiated via [startAudioSpectrumMonitor].

Available since: 1.1.0

enableHeadphoneMonitor

enableHeadphoneMonitor(enable: boolean): void

Enables or disables headphone monitoring.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to use headphone monitor, true: enable, false: disable

Details

Enable/Disable headphone monitor, and users hear their own voices as they use the microphone to capture sounds.

When to call: After the engine is created [createEngine].
Default value: Disable.
Caution: 1. This setting does not actually take effect until both the headset and microphone are connected. 2. The default is to return after acquisition and before pre-processing. If you need to return after pre-processing, please contact ZEGO technical support.

Available since: 1.9.0

setHeadphoneMonitorVolume

setHeadphoneMonitorVolume(volume: number): void

Sets the headphone monitor volume.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
volume	number	headphone monitor volume, range from 0 to 200, 60 as default.

Details

set headphone monitor volume.

When to call: After the engine is created [createEngine].
Caution: This setting does not actually take effect until both the headset and microphone are connected.
Related APIs: Enables or disables headphone monitoring via [enableHeadphoneMonitor].

Available since: 1.9.0

enableMixSystemPlayout

enableMixSystemPlayout(enable: boolean): void

Enable or disable system audio capture.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to mix system playout.

Details

Enable sound card capture to mix sounds played by the system into the publishing stream, such as sounds played by the browser, sounds played by the third-party player, etc.

Default value: Default is disable.
When to call: Called this function after calling [startPublishingStream] or [startPreview].
Caution: The system sound card sound does not include streaming sound, media player sound and sound effect player sound.
Related APIs: [setMixSystemPlayoutVolume] function can set system audio capture volume.
Platform differences: Only supports Windows and macOS.

Available since: 1.9.0
Restrictions: None.

setMixSystemPlayoutVolume

setMixSystemPlayoutVolume(volume: number): void

set system audio capture volume.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
volume	number	the volume. Valid range [0, 200], default is 100.

Details

set system audio capture volume.

Use cases: User needs to adjust the volume which system playout mix to stream publishing.
When to call /Trigger: Called this function after calling [startPublishingStream] or [startPreview].
Related APIs: [enableMixSystemPlayout] enable or disable mix system playout.
Platform differences: Only supports Windows and macOS.

Available since: 2.4.0
Restrictions: None.

enableMixEnginePlayout

enableMixEnginePlayout(enable: boolean): void

Enable or disable mix SDK playout to stream publishing.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to mix engine playout

Details

Enable mix SDK playout sounds into the stream publishing.

Use cases: Users need to mix the sound of SDK playout into stream publishing. For example, when the class scene, the teacher and student Co-hosting, and the teacher can mix the play streaming sound into the publish streaming.
Default value: Default is disable.
When to call /Trigger: Called this function after calling [startPublishingStream] or [startPreview].

Available since: 1.1.0
Restrictions: None.

startAudioVADStableStateMonitor

startAudioVADStableStateMonitor(type: ZegoAudioVADStableStateMonitorType, millisecond: number): void

Start audio VAD stable state monitoring, and the monitoring period can be set.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
type	ZegoAudioVADStableStateMonitorType	audio VAD monitor type.
millisecond	number	monitoring period default 3000. value of [200, 10000]

Details

After monitoring is started, you can use the [onAudioVADStateUpdate] callback to receive the specified type of audio VAD callback.

Use cases: For example, when you specify the type of collection and use the microphone to collect, you can check whether the host has continuous and stable voice input through this interface.
When to call: Before publish stream, you can call [startPreview] with this function and combine it with [onAudioVADStateUpdate] callback to determine whether the audio device is working properly.
Related APIs: [stopAudioVADStableStateMonitor].

Restrictions: None.

stopAudioVADStableStateMonitor

stopAudioVADStableStateMonitor(type: ZegoAudioVADStableStateMonitorType): void

Stop audio VAD stable state monitoring.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
type	ZegoAudioVADStableStateMonitorType	audio VAD monitor type.

Details

After calling this interface, the specified type of [onAudioVADStateUpdate] callback can no longer be received.

When to call: None.
Related APIs: [startAudioVADStableStateMonitor].

Available since: 2.14.0
Restrictions: None.

getCurrentAudioDevice

getCurrentAudioDevice(deviceType: ZegoAudioDeviceType): ZegoDeviceInfo

Get the audio device information currently in use.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
deviceType	ZegoAudioDeviceType	Audio device type.Required .

Details

Get the audio device information currently in use.

Use cases: Used for scenes that need to manually switch between multiple audio devices.
When to call: Called this function after calling [startPublishingStream] or [startPreview].
Related APIs: The default audio device ID can be obtained through [getDefaultAudioDeviceID].

Available since: 2.12.0
Restrictions: Only supports Windows and macOS.

Return

Audio device information.

enableAEC

enableAEC(enable: boolean): void

Whether to enable acoustic echo cancellation (AEC).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable echo cancellation, true: enable, false: disable

Details

Turning on echo cancellation, the SDK filters the collected audio data to reduce the echo component in the audio. Use case: When you need to reduce the echo to improve the call quality and user experience, you can turn on this feature.

When to call: It needs to be called after [createEngine].
Caution: The AEC function only supports the processing of sounds playbacked through the SDK, such as sounds played by the playing stream, media player, audio effect player, etc. Before this function is called, the SDK automatically determines whether to use AEC. Once this function is called, the SDK does not automatically determine whether to use AEC.
Related APIs: Developers can use [enableHeadphoneAEC] to set whether to enable AEC when using headphones, and use [setAECMode] to set the echo cancellation mode.

Available since: 1.1.0
Restrictions: None.

enableHeadphoneAEC

enableHeadphoneAEC(enable: boolean): void

Whether to turn on acoustic echo cancellation (AEC) when using the headphone.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable, true: enable, false: disable

Details

When [enableAEC] is used to turn on echo cancellation, it is only turned on when the speaker is used for mobile terminal equipment. Call this function if you need to turn echo cancellation on or off when using the headset. Use case: It is common when the mobile device is connected to a external sound card as the audio output source. In order to eliminate the echo in this case, you need to call this function to turn on the echo cancellation.

Default value: Android is off by default and iOS is on by default.
When to call: It needs to be called after [createEngine], before [startPublishingStream], [startPlayingStream], [startPreview], [createMediaPlayer], [createAudioEffectPlayer] and [createRealTimeSequentialDataManager].
Caution: Turning on echo cancellation will increase the ear return delay. On the iOS platform, the SDK cannot distinguish between the headset and the external sound card. If you use this function to turn off the system echo cancellation when using the headset, the sound played by the external sound card will be collected when the user accesses the external sound card.
Related APIs: When the headset is not used, you can set whether the SDK turns on echo cancellation through [enableAEC].
Platform differences: Only supports iOS and Android.

Available since: 1.1.0
Restrictions: None.

setAECMode

setAECMode(mode: ZegoAECMode): void

Sets the acoustic echo cancellation (AEC) mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoAECMode	Echo cancellation mode

Details

When [enableAEC] is used to enable echo cancellation, this function can be used to switch between different echo cancellation modes to control the degree of echo cancellation. Use case: When the default echo cancellation effect does not meet expectations, this function can be used to adjust the echo cancellation mode.

Default value: When this function is not called, the default echo cancellation mode is [Aggressive].
When to call: It needs to be called after [createEngine].

Available since: 1.1.0
Restrictions: The value set by this function is valid only after the echo cancellation function is turned on.

enableAGC

enableAGC(enable: boolean): void

Enables or disables automatic gain control (AGC).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	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 near and far sound pickups and keep the volume stable. Use case: When you need to ensure volume stability to improve call quality and user experience, you can turn on this feature.

When to call: It needs to be called after [createEngine].
Caution: Before this function is called, the SDK automatically determines whether to use AGC. Once this function is called, the SDK does not automatically determine whether to use AGC.

Available since: 1.1.0
Restrictions: None.

enableANS

enableANS(enable: boolean): void

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

Declared in ZegoExpressEngine.ts

Parameters

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

Details

Enable the noise suppression can reduce the noise in the audio data and make the human voice clearer. Use case: When you need to suppress noise to improve call quality and user experience, you can turn on this feature.

When to call: It needs to be called after [createEngine].
Related APIs: This function has a better suppression effect on continuous noise (such as the sound of rain, white noise). If you need to turn on transient noise suppression, please use [enableTransientANS]. And the noise suppression mode can be set by [setANSMode].
Caution: Before this function is called, the SDK automatically determines whether to use ANS. Once this function is called, the SDK does not automatically determine whether to use ANS.

Available since: 1.1.0
Restrictions: None.

enableTransientANS

enableTransientANS(enable: boolean): void

Enables or disables transient noise suppression.

Declared in ZegoExpressEngine.ts

Parameters

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

Details

Enable the transient noise suppression can suppress the noises such as keyboard and desk knocks. Use case: When you need to suppress transient noise to improve call quality and user experience, you can turn on this feature.

Default value: When this function is not called, this is disabled by default.
When to call: It needs to be called after [createEngine].
Related APIs: This function will not suppress normal noise after it is turned on. If you need to turn on normal noise suppression, please use [enableANS].

Available since: 1.17.0
Restrictions: None.

setANSMode

setANSMode(mode: ZegoANSMode): void

Sets the automatic noise suppression (ANS) mode.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mode	ZegoANSMode	Audio Noise Suppression mode

Details

When [enableANS] is used to enable noise suppression, this function can be used 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, this function can be used to adjust the noise suppression mode.

Default value: When this function is not called, the default automatic noise suppression (ANS) mode is [Medium].
When to call: It needs to be called after [createEngine].

Available since: 1.1.0
Restrictions: The value set by this function is valid only after the noise suppression function is turned on.

startEffectsEnv

startEffectsEnv(): void

Enable the Effects beauty environment.

Declared in ZegoExpressEngine.ts

Enable the Effects beauty environment. The SDK uses the specified video frame data type for transmission. The Windows platform only supports video frame raw data, the Apple platform only supports CVPixelBuffer, and the Android platform only supports texture2d.

Use cases: It is often used in scenes such as video calls and live broadcasts.
Default value: When this function is not called, the beauty environment is not activated by default.
When to call: Must be called before calling [startPreview], [startPublishingStream]. If you need to modify the configuration, please call [logoutRoom] to log out of the room first, otherwise it will not take effect.
Related APIs: [enableEffectsBeauty] switch beauty, [setEffectsBeautyParam] set beauty parameters.
Caution: This beauty function is the basic function. If it does not meet the expectations of the developer, you can use the custom video pre-processing function [enableCustomVideoProcessing] or the custom video capture function [enableCustomVideoCapture] docking and constructing the AI Effects SDK [ZegoEffects] /ai-effects-android-java/overview/overview for best results.

Available since: 2.16.0
Restrictions: This function only supports Android system 5.0 and above, Android SDK version 21 and above. This function is only available in ZegoExpressVideo SDK!

stopEffectsEnv

stopEffectsEnv(): void

Disable the Effects beauty environment.

Declared in ZegoExpressEngine.ts

Disable the Effects beauty environment.

Use cases: It is often used in scenes such as video calls and live broadcasts.
When to call: Must be called before calling [startPreview], [startPublishingStream]. If you need to modify the configuration, please call [logoutRoom] to log out of the room first, otherwise it will not take effect.
Related APIs: [enableEffectsBeauty] switch beauty, [setEffectsBeautyParam] set beauty parameters.
Caution: This beauty function is the basic function. If it does not meet the expectations of the developer, you can use the custom video pre-processing function [enableCustomVideoProcessing] or the custom video capture function [enableCustomVideoCapture] docking and constructing the AI Effects SDK [ZegoEffects] for best results.

Available since: 2.16.0
Restrictions: This function only supports Android system 5.0 and above, Android SDK version 21 and above. This function is only available in ZegoExpressVideo SDK!

enableEffectsBeauty

enableEffectsBeauty(enable: boolean): void

Enables or disables the beauty effect.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	Whether to enable the beauty effect, true is enabled; false is disabled, and the default is false.

Details

Support basic beauty functions, including whiten, rosy, smooth, and sharpen.

Use cases: It is often used in scenes such as video calls and live broadcasts.
When to call: You must call [startEffectsEnv] to enable the beauty environment before calling this function.
Default value: When this function is not called, the beauty effect is not enabled by default.
Related APIs: You can call the [setBeautifyOption] function to adjust the beauty parameters.
Caution: This beauty function is the basic function. If it does not meet the expectations of the developer, you can use the custom video pre-processing function [enableCustomVideoProcessing] or the custom video capture function [enableCustomVideoCapture] docking and constructing the AI Effects SDK [ZegoEffects] for best results.

Available since: 2.16.0
Restrictions: If this function is used on the Android platform, it only supports 5.0 and above, SDK version 21 and above. This function is only available in ZegoExpressVideo SDK!

setEffectsBeautyParam

setEffectsBeautyParam(param: ZegoEffectsBeautyParam): void

Set beautify param.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
param	ZegoEffectsBeautyParam	Beauty option param.

Details

Set the beauty parameters, including whiten, rosy, smooth, and sharpen.

Use cases: It is often used in scenes such as video calls and live broadcasts.
When to call: You must call [startEffectsEnv] to enable the beauty environment before calling this function.
Related APIs: You can call [enableEffectsBeauty] to turn on or off the beauty function.

Available since: 2.16.0
Restrictions: This function only supports Android system 5.0 and above, Android SDK version 21 and above. This function is only available in ZegoExpressVideo SDK!

setAudioEqualizerGain

setAudioEqualizerGain(bandIndex: number, bandGain: number): void

Set the sound equalizer (EQ).

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
bandIndex	number	Band frequency index, the value range is [0, 9], corresponding to 10 frequency bands, and the center frequencies are [31, 62, 125, 250, 500, 1K, 2K, 4K, 8K, 16K] Hz.
bandGain	number	Band gain for the index, the value range is [-15, 15]. Default value is 0, if all gain values in all frequency bands are 0, EQ function will be disabled.

Details

Call this function to set the sound equalizer adjust the tone.

Use cases: Often used in voice chatroom, KTV.
When to call: It should be called after the engine has started.

Available since: 1.12.0
Restrictions: None.

setVoiceChangerPreset

setVoiceChangerPreset(preset: ZegoVoiceChangerPreset): void

Setting up the voice changer via preset enumeration.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
preset	ZegoVoiceChangerPreset	The voice changer preset enumeration.

Details

Call this function to use preset voice changer effect.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Related APIs: If you need advanced voice changer effect, please use [setVoiceChangerParam]. The effect of using this function together with [setReverbPreset] may be different from what is expected. If you need to use it at the same time, it is recommended to enable the voice changer first, and then enable the reverb. Using ANDROID/ETHEREAL preset voice changer effect will modify reverberation or reverberation echo parameters. Calling [setVoiceChangerParam], [setReverbAdvancedParam], [setReverbEchoParam] may affect the voice changer effect after use these preset voice changer effect. If you need advanced reverb/echo/electronic effects/voice changer effect, please use [setReverbAdvancedParam], [setReverbEchoParam], [setElectronicEffects], [setVoiceChangerParam] together.

Available since: 1.17.0

setVoiceChangerParam

setVoiceChangerParam(param: ZegoVoiceChangerParam): void

Setting up the specific voice changer parameters.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
param	ZegoVoiceChangerParam	Voice changer parameters.

Details

Call this function to set custom voice changer effect.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Related APIs: [setVoiceChangerPreset] provide a set of preset voice changer effects. If you need advanced reverb/echo/voice changer effect, please use [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] together.

Available since: 1.10.0

setReverbPreset

setReverbPreset(preset: ZegoReverbPreset): void

Setting up the reverberation via preset enumeration.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
preset	ZegoReverbPreset	The reverberation preset enumeration.

Details

Call this function to set preset reverb effect.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine]. Support call this function to change preset reverb effect during publishing stream.
Related APIs: If you need advanced reverb effect, please use [setReverbAdvancedParam]. The effect of using this function together with [setVoiceChangerPreset] may be different from what is expected. If you need to use it at the same time, it is recommended to enable the voice changer first, and then enable the reverb. If you need advanced reverb/echo/voice changer effect, please use [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] together.

Available since: 1.17.0

setReverbAdvancedParam

setReverbAdvancedParam(param: ZegoReverbAdvancedParam): void

Setting up the specific reverberation parameters.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
param	ZegoReverbAdvancedParam	Reverb advanced parameter.

Details

Call this function to set preset reverb effect.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Caution: Different values dynamically set during publishing stream will take effect. When all parameters are set to 0, the reverberation is turned off.
Related APIs: [setReverbPreset] provide a set of preset reverb effects. If you need advanced reverb/echo/voice changer effect, please use [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] together.

Available since: 1.10.0

setReverbEchoParam

setReverbEchoParam(param: ZegoReverbEchoParam): void

Setting up the specific reverberation echo parameters.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
param	ZegoReverbEchoParam	The reverberation echo parameter.

Details

Call this function to set reverb echo effect. This function can be used with voice changer and reverb to achieve a variety of custom sound effects.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Related APIs: If you need advanced reverb/echo/voice changer effect, please use [setReverbAdvancedParam], [setReverbEchoParam], [setVoiceChangerParam] together.

Available since: 1.17.0

enableVirtualStereo

enableVirtualStereo(enable: boolean, angle: number): void

Enable or disable the virtual stereo effect when publishing stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	true to turn on the virtual stereo, false to turn off the virtual stereo.
angle	number	The angle of the sound source in virtual stereo in the range of -1 ~ 360, with 90 being directly in front, 0 / 180 / 270 corresponding to the rightmost and leftmost respectively. In particular, when set to -1, it is all round virtual stereo effects.

Details

Call this function to enable / disable the virtual stereo effect when publishing stream.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Caution: You need to set up a dual channel with [setAudioConfig] for the virtual stereo to take effect.

Available since: 1.10.0; Starting from 2.15.0, the angle parameter supports setting -1 to present a all round virtual stereo effect.

enablePlayStreamVirtualStereo

enablePlayStreamVirtualStereo(enable: boolean, angle: number, streamID: string): void

Enable or disable the virtual stereo effect when playing stream.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	true to turn on the virtual stereo, false to turn off the virtual stereo.
angle	number	The angle of the sound source in virtual stereo in the range of 0 ~ 360, with 90 being directly in front, 0 / 180 / 270 corresponding to the rightmost and leftmost respectively.
streamID	string	Stream ID.

Details

Call this function to enable/disable the virtual stereo effect when playing stream.

Use cases: Often used in live broadcasting, voice chatroom and KTV.
When to call: It needs to be called after [createEngine].
Caution: It can dynamically switch and set angle parameters before and after playing stream. After stopping playing stream, it will automatically reset and disable.

Available since: 2.8.0

setElectronicEffects

setElectronicEffects(enable: boolean, mode: ZegoElectronicEffectsMode, tonal: number): void

Turn on or off the electronic sound effect.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
enable	boolean	true to turn on the electronic sound effect, false to turn off the electronic sound effect.
mode	ZegoElectronicEffectsMode	Mode of Electronic Effects reference.
tonal	number	The starting pitch of an electric tone in a given mode, representing 12 semitones in one octave of the sound, in the range [0, 11].

Details

Call this function to turn on or off the electronic sound effect.

Use cases: Often used in live broadcasting, voice chatroom and sung unaccompanied scenes.
Default value: When this function is not called, the electronic sound effect is not enabled by default.
When to call: It needs to be called after [createEngine].
Caution: When the mode parameter is Harmonic Minor, the tonal parameter does not take effect.
Related APIs: Common electronic sound effect configurations can be set via [setVoiceChangerPreset].

Available since: 2.13.0
Restrictions: None.

sendCustomCommand

  sendCustomCommand(roomID: string, command: string, toUserList: ZegoUser[], callback?: ZegoIMSendCustomCommandCallback): void

Sends a Custom Command to the specified users in the same room.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
roomID	string	Room ID, a string of less 128 bytes in length. Caution: 1. room ID is defined by yourself. 2. Only support numbers, English characters and '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''. 3. If you need to communicate with the Web SDK, please do not use '%'.
command	string	Custom command content. Required: Yes. Value range: The maximum length is 1024 bytes. Caution: To protect privacy, please do not fill in sensitive user information in this interface, including but not limited to mobile phone number, ID number, passport number, real name, etc.
toUserList	ZegoUser[]	List of recipients of signaling. Required: Yes. Value range: user list or [null]. Caution: When it is [null], the SDK will send custom signaling back to all users in the room
callback	ZegoIMSendCustomCommandCallback	Send a notification of the signaling result. Required: No. Caution: Passing [null] means not receiving callback notifications.

Details

Send point-to-point signaling to other users who have logged into the same room, and the message is reliable.

Use cases: Generally used for remote control signaling or message sending between users.
When to call: After calling [loginRoom] to log in to the room.
Related callbacks: The room custom command can be received through [onIMRecvCustomCommand].
Related APIs: Broadcast messages can be sent through the [sendBroadcastMessage] function, and barrage messages can be sent through the [sendBarrageMessage] function.
Privacy reminder: Please do not fill in sensitive user information in this interface, including but not limited to mobile phone number, ID number, passport number, real name, etc.

Available since: 1.2.1
Restrictions: The frequency of sending barrage messages in the same room cannot be higher than 20 messages/s. For restrictions on the use of this function, please contact ZEGO technical support.

createMediaPlayer

createMediaPlayer(): ZegoMediaPlayer|null

Creates a media player instance.

Declared in ZegoExpressEngine.ts

Creates a media player instance. Use case: It is often used to play media resource scenes, For example, play video files, push the video of media resources in combination with custom video acquisition, and the remote end can pull the stream for viewing.

When to call: It can be called after the SDK by [createEngine] has been initialized.
Caution: The more instances of a media player, the greater the performance overhead on the device.
Related APIs: User can call [destroyMediaPlayer] function to destroy a media player instance.

Available since: 2.1.0
Restrictions: Currently, a maximum of 10 instances can be created, after which it will return null.

Media player instance, null will be returned when the maximum number is exceeded.

destroyMediaPlayer

destroyMediaPlayer(mediaPlayer: ZegoMediaPlayer): void

Destroys a media player instance.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
mediaPlayer	ZegoMediaPlayer	The media player instance object to be destroyed.

Details

Destroys a media player instance.

Related APIs: User can call [createMediaPlayer] function to create a media player instance.

Available since: 2.1.0

startPerformanceMonitor

startPerformanceMonitor(millisecond?: number): void

Start system performance monitoring.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
millisecond	number	Monitoring time period(in milliseconds), the value range is [1000, 10000]. Default value is 2000 ms.

Details

Start system performance monitoring, monitor system or App's CPU usage and memory usage. Support set the monitoring interval.

Use cases: Monitor system performance can help user quickly locate and solve performance problems and improve user experience.
When to call: It needs to be called after [createEngine].
Related callbacks: After starting monitoring, you can receive system performance status via [onPerformanceStatusUpdate] callback. [onPerformanceStatusUpdate] callback notification period is the value set by millisecond parameter.
Related APIs: Call [stopPerformanceMonitor] to stop system performance monitoring.

Available since: 1.19.0
Restrictions: None.

stopPerformanceMonitor

stopPerformanceMonitor(): void

Stop system performance monitoring.

Declared in ZegoExpressEngine.ts

Stop system performance monitoring. After the monitoring is stopped, the [onPerformanceStatusUpdate] callback will not triggered.

Use cases: Monitor system performance can help user quickly locate and solve performance problems and improve user experience.
When to call: It needs to be called after [createEngine].
Related APIs: Call [startPerformanceMonitor] to start system performance monitoring.

Available since: 1.19.0
Restrictions: None.

startNetworkSpeedTest

startNetworkSpeedTest(config: ZegoNetworkSpeedTestConfig, interval?: number): void

Start network speed test. Support set speed test interval。

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoNetworkSpeedTestConfig	Network speed test configuration.
interval	number	Interval of network speed test. In milliseconds, default is 3000 ms.

Details

This function supports uplink/downlink network speed test 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 call: It needs to be called after [loginRoom]. If you call [startPublishingStream]/[startPlayingStream] while speed testing, the speed test will automatically stop.
Caution: Developers can register [onNetworkSpeedTestQualityUpdate] callback to get the speed test result, which will be triggered every 3 seconds. If an error occurs during the speed test process, [onNetworkSpeedTestError] callback will be triggered. If this function is repeatedly called multiple times, the last functioh call's configuration will be used.
Related APIs: Call [stopNetworkSpeedTest] to stop network speed test.

Available since: 1.20.0
Restrictions: The default maximum allowable test time for a single network speed test is 30 seconds.

stopNetworkSpeedTest

stopNetworkSpeedTest(): void

Stop network speed test.

Declared in ZegoExpressEngine.ts

Stop network speed test.

Use cases: This function can be used to detect whether the network environment is suitable for pushing/pulling streams with specified bitrates.
When to call: It needs to be called after [createEngine].
Caution: After the network speed test stopped, [onNetworkSpeedTestQualityUpdate] callback will not be triggered.
Related APIs: Call [startNetworkSpeedTest] to start network speed test.

Available since: 1.20.0
Restrictions: None.

setAppGroupID

setAppGroupID(groupID: string): void

Set the App Group configuration item.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
groupID	string	The host app and the extension app should belong to the same App Group, and the AppGroupID needs to be passed in here.

Use cases: You need to use the iOS cross-process screen sharing function, and you need to start the App Group, which can provide better performance and stability. Must be used with [setupWithAppGroupID:] in the ZegoReplayKit extension class.
When to call: Called after [createEngine], before calling [startScreenCapture].

Available since: 3.3.0
Restrictions: Only available on iOS platform.

startScreenCaptureInApp

startScreenCaptureInApp(config: ZegoScreenCaptureConfig): void

Start screen capture, in-app capture only.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoScreenCaptureConfig	Screen capture parameter configuration.

Details

Start screen capture.

When to call: After calling the [setVideoSource]、[setAudioSource] function to set the capture source to ScreenCapture.

Available since: 3.1.0
Restrictions: Only valid for iOS system

startScreenCapture

startScreenCapture(config: ZegoScreenCaptureConfig): void

Start screen capture.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoScreenCaptureConfig	Screen capture parameter configuration.

Details

Start screen capture.

When to call: After calling the [setVideoSource]、[setAudioSource] function to set the capture source to ScreenCapture.

Available since: 3.1.0

stopScreenCapture

stopScreenCapture(): void

Stop screen capture.

Declared in ZegoExpressEngine.ts

Stop screen capture.

Available since: 3.1.0

updateScreenCaptureConfig

updateScreenCaptureConfig(config: ZegoScreenCaptureConfig): void

Update screen capture parameter configuration.

Declared in ZegoExpressEngine.ts

Parameters

Name	Type	Description
config	ZegoScreenCaptureConfig	Screen capture parameter configuration.

Details

Update screen capture parameter configuration.

When to call: After calling [startScreenCapture] to start capturing.

Available since: 3.1.0
Restrictions: Only valid for iOS system. Only available on iOS 12.0 or newer

ZegoMediaPlayer

Declared in ZegoExpressDefines.ts

Methods

loadResourceWithConfig

loadResourceWithConfig(resource: ZegoMediaPlayerResource, callback?: ZegoMediaPlayerLoadResourceCallback): void

Load local or network media resource with config.

Declared in ZegoExpressDefines.ts

Parameters

Name	Type	Description
resource	ZegoMediaPlayerResource	Multimedia resources that need to be loaded.
callback	ZegoMediaPlayerLoadResourceCallback	Notification of resource loading results

Details

Load media resources. Use case: Developers can load the absolute path to the local resource or the URL of the network resource incoming.

When to call: Called after the engine [createEngine] has been initialized and the media player [createMediaPlayer] has been created.
Related APIs: Support for loading resources through the [loadResourceWithPosition] or [loadResourceFromMediaData] interface.
Caution: If the mediaplayer has already loaded resources or is in the process of playing, please first call the [stop] interface to halt the playback, and then proceed to call the interface to load the media resources; failure to do so will result in an unsuccessful load.

Return

Callback result of loading media resource.

start

start(): void

Start playing.

Declared in ZegoExpressDefines.ts

You need to load resources before playing

stop

stop(): void

Stop playing.

Declared in ZegoExpressDefines.ts