Video Basic Features

disableVideo

Disables the video module.

public abstract int disableVideo();

Note: disableVideo affects the internal engine and can be called after leaving the channel. Calling this method resets the entire engine, which may slow down response time. Depending on your needs, you can use the following methods to control specific video module functions:

enableLocalVideo: Whether to enable the camera to create a local video stream.
muteLocalVideoStream: Whether to publish the local video stream.
muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Timing

You can call this method before or after joining a channel.

If called before joining, it enables voice-only mode.
If called after joining, it switches from video to voice mode. You can call enableVideo again to switch back to video mode.

Related Callbacks

After this method is successfully called, the remote client triggers the onUserEnableVideo(false) callback.

Return Values

0: Success.
< 0: Failure.

enableLocalVideo

Enables or disables local video capture.

public abstract int enableLocalVideo(boolean enabled);

This method disables or re-enables local video capture without affecting the reception of remote video streams. If you call enableLocalVideo(false) in the channel, it also stops publishing the video stream in the channel. To resume video capture, call enableLocalVideo(true), then call updateChannelMediaOptions to set the options parameter to publish the locally captured video stream in the channel. After successfully disabling or enabling local video capture, the remote side triggers the onRemoteVideoStateChanged callback.

Note:

You can call this method before or after joining a channel. If called before joining, the setting takes effect after joining the channel.
This method enables the internal engine and remains effective after leaving the channel.

Related Callbacks

After successfully disabling or re-enabling the local video capturer, the SDK triggers the onRemoteVideoStateChanged callback on the remote client.

Parameters

enabled

Whether to enable local video capture.

true: (default) Enables local video capture.
false: Disables local video capture. When disabled, remote users cannot receive the local user's video stream, but the local user can still receive remote users' video streams. No local camera is required when set to false.

Return Values

0: Success.
< 0: Failure.

enableVideo

Enables the video module.

public abstract int enableVideo();

By default, the video module is disabled. Call this method to enable the video module. To disable it later, call disableVideo.

Note: This method enables the internal engine and remains effective after leaving the channel. Calling this method resets the entire engine, which may slow down response time. Depending on your needs, you can use the following methods to control specific video module functions:

enableLocalVideo: Whether to enable the camera to create a local video stream.
muteLocalVideoStream: Whether to publish the local video stream.
muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Successfully calling this method resets the settings of enableLocalVideo, muteRemoteVideoStream, and muteAllRemoteVideoStreams, so use it with caution.

Timing

You can call this method before or after joining a channel:

If called before joining, it enables the video module.
If called during a voice call, the call automatically switches to a video call.

Related Callbacks

Successfully calling this method triggers the onRemoteVideoStateChanged callback on the remote client.

Return Values

0: Success.
< 0: Failure.

setVideoEncoderConfiguration

Sets the encoder configuration for the local video.

public abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config);

Note:

This method and getMirrorApplied both support setting mirror effects. Agora recommends using only one of them. Using both may cause mirror effect stacking, making the mirror setting ineffective.
The config specified in this method is the maximum value under ideal network conditions. If the video engine cannot render video using the specified config due to unstable network conditions, it will try lower parameters in the list until it finds a usable configuration.

Timing

You can call this method before or after joining a channel. If the user does not need to reset video encoding properties after joining, Agora recommends calling this method before enableVideo to reduce the time to render the first video frame.

Parameters

config: Video encoder configuration. See VideoEncoderConfiguration.

Return Values

0: Success.
< 0: Failure.

setVideoEncoderConfigurationEx

Sets the encoder configuration for the local video.

public abstract int setVideoEncoderConfigurationEx(VideoEncoderConfiguration config, RtcConnection connection);

setVideoEncoderConfigurationEx sets the encoder configuration for the local video. Each configuration corresponds to a set of video parameters, including resolution, frame rate, and bitrate.

Note: The config parameter represents the upper limits under ideal network conditions. If the video engine cannot render video using the specified config due to unstable network conditions, it will try lower configurations in the list until a suitable one is found.

Scenario

This method applies to multi-channel scenarios.

Parameters

config: Video encoder configuration. See VideoEncoderConfiguration.
connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

setVideoScenario

Sets the video application scenario.

public abstract int setVideoScenario(Constants.VideoScenario scenarioType);

After this method is successfully called, the SDK automatically enables best practice strategies and adjusts key performance indicators based on the specified video scenario to optimize the video experience.

Note: Call this method before joining a channel.

Parameters

scenarioType

Type of video application scenario. See VideoScenario.

APPLICATION_SCENARIO_MEETING (1): Suitable for meeting scenarios. The SDK automatically enables the following strategies:
- When the low-quality video stream requires a higher bitrate, the SDK automatically enables various network congestion handling techniques to enhance the performance of the low-quality stream and ensure smooth reception on the subscriber side.
- The SDK monitors the number of subscribers to the high-quality video stream in real time and dynamically adjusts its configuration:
  - If no one subscribes to the high-quality stream, the SDK automatically reduces its bitrate and frame rate to save upstream bandwidth.
  - If someone subscribes to the high-quality stream, the SDK resets it to the configuration set by the most recent call to setVideoEncoderConfiguration; if no configuration was set, the following defaults are used:
    - Resolution: 960 × 540.
    - Frame rate: 15 fps.
    - Bitrate: 1000 Kbps.
- The SDK monitors the number of subscribers to the low-quality stream in real time and dynamically enables or disables the stream:
  - If you called setDualStreamMode and set it to never send the low-quality stream (DISABLE_SIMULCAST_STREAM), then dynamic adjustment of the low-quality stream in meeting scenarios will not take effect.
  - If no one subscribes to the low-quality stream, the SDK disables it to save upstream bandwidth.
  - If someone subscribes to the low-quality stream, the SDK enables it and resets it to the configuration set by the most recent call to setDualStreamMode; if no configuration was set, the following defaults are used:
    - Resolution: 480 × 272.
    - Frame rate: 15 fps.
    - Bitrate: 500 Kbps.
APPLICATION_SCENARIO_1V1 (2): Suitable for one-on-one live streaming scenarios. To meet the needs of low latency and high quality, the SDK optimizes strategies to improve video quality, first frame rendering speed, latency performance on mid- and low-end devices, and smoothness under poor network conditions.
- Note: This enum value is only applicable to broadcaster-to-broadcaster scenarios.
APPLICATION_SCENARIO_LIVESHOW (3): Suitable for live show scenarios. In this scenario, fast video rendering and high quality are critical. The SDK performs various performance optimizations, including:
- Automatically enabling audio and video frame accelerated rendering to minimize first-frame delay (no need to call enableInstantMediaRendering).
- Enabling B-frame encoding to improve image quality and bandwidth efficiency.
- Providing enhanced video quality and smooth playback even under poor network conditions or on low-end devices.

Return Values

0: Success.
< 0: Failure.
- -1: A general error occurred (no specific reason).
- -4: Video scenario not supported. Possible reason: using the voice SDK instead of the video SDK.
- -7: The RtcEngine object has not been initialized. Please initialize the RtcEngine object before calling this method.

startPreview [1/2]

Enables local video preview.

public abstract int startPreview();

Note:

Mirror mode is enabled by default for local preview.
After leaving the channel, the local preview remains active. You need to call stopPreview to stop the local preview.

Timing

This method must be called after calling enableVideo and setupLocalVideo.

Return Values

0: Success.
< 0: Failure.

startPreview [2/2]

Enables local video preview and specifies the video source for preview.

public abstract int startPreview(Constants.VideoSourceType sourceType);

Note:

Mirror mode is enabled by default for local preview.
After leaving the channel, the local preview remains active. You need to call stopPreview to stop the local preview.

Timing

This method must be called after calling enableVideo and setupLocalVideo.

Parameters

sourceType: The type of video source. See VideoSourceType.

Return Values

0: Success.
< 0: Failure.

stopPreview [1/2]

Stops local video preview.

public abstract int stopPreview();

After calling startPreview to enable preview, you can call this method to stop the local video preview.

Timing

Call this method before joining or after leaving a channel.

Return Values

0: Success.
< 0: Failure.

stopPreview [2/2]

Stops local video preview.

public abstract int stopPreview(Constants.VideoSourceType sourceType);

After calling startPreview, if you need to stop the local video preview, call stopPreview.

Timing

Call this method before joining or after leaving a channel.

Parameters

sourceType: The type of video source. See VideoSourceType.

Return Values

0: Success.
< 0: Failure.

onFirstLocalVideoFrame

Callback triggered when the first local video frame is displayed in the local view.

public void onFirstLocalVideoFrame(Constants.VideoSourceType source, int width, int height, int elapsed)

Parameters

source: Video source type. See VideoSourceType.
width: Width of the first local video frame in pixels.
height: Height of the first local video frame in pixels.
elapsed: Time elapsed (in milliseconds) from the local user calling joinChannel to the triggering of this callback. If startPreview was called before joining the channel, this parameter indicates the time from calling startPreview to the event trigger.

onFirstLocalVideoFramePublished

Callback for the first local video frame published.

public void onFirstLocalVideoFramePublished(Constants.VideoSourceType source, int elapsed)

The SDK triggers this callback when any of the following conditions are met:

The local client enables the video module and successfully joins the channel by calling joinChannel.
The local client calls muteLocalVideoStream(true) followed by muteLocalVideoStream(false).
The local client calls disableVideo followed by enableVideo.
The local client successfully pushes video frames to the SDK using pushExternalVideoFrameById.

Trigger Timing

This callback is triggered when the first local video frame is published.

Parameters

source: Video source type. See VideoSourceType.
elapsed: Time (in milliseconds) from the local user successfully calling joinChannel to the triggering of this callback.

onFirstRemoteVideoDecoded

Callback when the first remote video frame is received and decoded.

public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed)

Deprecated: This method is deprecated. Use REMOTE_VIDEO_STATE_STARTING(1) or REMOTE_VIDEO_STATE_DECODING(2) in the onRemoteVideoStateChanged callback instead.

The SDK triggers this callback in any of the following scenarios:

A remote user joins the channel and sends a video stream.
A remote user stops sending video and resumes after 15 seconds. Possible causes include:
- The remote user leaves the channel.
- The remote user goes offline.
- The remote user calls disableVideo to disable video.

Trigger Timing

This callback is triggered when the first remote video frame is received and decoded.

Parameters

uid: Remote user ID.
width: Width of the video stream (in pixels).
height: Height of the video stream (in pixels).
elapsed: Time (in milliseconds) from the local user calling joinChannel to the triggering of this callback.

onFirstRemoteVideoFrame

Callback for the first remote video frame displayed.

public void onFirstRemoteVideoFrame(int uid, int width, int height, int elapsed)

Note: The onFirstRemoteVideoFrame callback is only triggered when the video frame is rendered by the SDK. If you use custom video rendering, this callback is not triggered. You need to implement this functionality outside of the SDK.

Trigger Timing

This callback is triggered when the renderer receives the first frame of remote video.

Parameters

uid: Remote user ID who sent the video stream.
width: Width of the video stream (pixels).
height: Height of the video stream (pixels).
elapsed: Time (in milliseconds) from the local user calling joinChannel to the SDK triggering this callback.

onLocalVideoEvent

onLocalVideoEvent callback.

public void onLocalVideoEvent(Constants.VideoSourceType source, int event)

You can use this callback to get the reason why a local video event occurred.

Parameters

source

Video source type. See VideoSourceType.

event

Local video event type:

LOCAL_VIDEO_EVENT_TYPE_SCREEN_CAPTURE_WINDOW_HIDDEN (1): The screen capture window is hidden.
LOCAL_VIDEO_EVENT_TYPE_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN (2): The screen capture window recovers from hidden.
LOCAL_VIDEO_EVENT_TYPE_SCREEN_CAPTURE_STOPPED_BY_USER (3): The screen capture is stopped by the user.
LOCAL_VIDEO_EVENT_TYPE_SCREEN_CAPTURE_SYSTEM_INTERNAL_ERROR (4): A system internal error occurs during screen capture.

onLocalVideoStateChanged

Callback for changes in local video stream state.

public void onLocalVideoStateChanged(Constants.VideoSourceType source, int state, int reason)

You can use this callback to monitor changes in the local video stream state and take appropriate actions based on the reason to better manage and troubleshoot video stream issues.

Note: Note that duplicate frame detection only applies to video frames with resolution greater than 200 × 200, frame rate ≥ 10 fps, and bitrate < 20 Kbps. In general, if a video capture error occurs, you can troubleshoot using the reason parameter in this callback. However, on some devices, Android does not throw any error callback when capture issues occur (e.g., stuttering), so the SDK cannot report the reason for local video state changes. In this case, you can determine whether video frames are not captured by checking if this callback reports LOCAL_VIDEO_STREAM_STATE_CAPTURING or LOCAL_VIDEO_STREAM_STATE_ENCODING, and captureFrameRate in the onLocalVideoStats callback is 0.

Trigger Timing

This callback is triggered in the following situations, with state as LOCAL_VIDEO_STREAM_STATE_FAILED and reason as LOCAL_VIDEO_STREAM_REASON_CAPTURE_FAILURE:

On Android 9 and above, the system may reclaim camera permissions after the app runs in the background for some time.
On Android 6 and above, if the camera is occupied by a third-party app and then released, the SDK triggers this callback with state as LOCAL_VIDEO_STREAM_STATE_CAPTURING and reason as LOCAL_VIDEO_STREAM_REASON_OK.
The camera starts normally but does not output video frames for four consecutive seconds.
If the camera outputs video frames, and the SDK detects 15 consecutive duplicate frames, this callback is triggered with state as LOCAL_VIDEO_STREAM_STATE_CAPTURING and reason as LOCAL_VIDEO_STREAM_REASON_CAPTURE_FAILURE.

Parameters

source

The type of video source. See VideoSourceType.

state

LOCAL_VIDEO_STREAM_STATE_STOPPED (0): The local video is in the initial state.
LOCAL_VIDEO_STREAM_STATE_CAPTURING (1): The local video capturing device is started successfully.
LOCAL_VIDEO_STREAM_STATE_ENCODING (2): The first frame of video is encoded successfully.
LOCAL_VIDEO_STREAM_STATE_FAILED (3): Failed to start the local video.

reason

LOCAL_VIDEO_STREAM_REASON_OK (0): The local video state is normal.
LOCAL_VIDEO_STREAM_REASON_FAILURE (1): The local video failed for an unspecified reason.
LOCAL_VIDEO_STREAM_REASON_DEVICE_BUSY (3): The local video capturing device is occupied. Prompt the user to check if the camera is used by another app or try rejoining the channel.
LOCAL_VIDEO_STREAM_REASON_CAPTURE_FAILURE (4): Failed to capture local video. Prompt the user to check if the video capturing device is working properly, if the camera is used by another app, or try rejoining the channel.
LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT (5): Failed to encode local video.
LOCAL_VIDEO_STREAM_REASON_DEVICE_NOT_FOUND (8): No local video capturing device found. Prompt the user to check if the camera is properly connected or working, then rejoin the channel.
LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT (14): Video capture interrupted. Possible reasons include:
- The camera is used by another app. Prompt the user to check if the camera is in use.
- The device is locked, or the app is sent to the background. You can use a foreground service notification to ensure video capture continues in the background.
LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR (15): The video capturing device encountered a fatal error. Prompt the user to close and restart the camera. If the issue persists, check for hardware failure.
LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_FAILURE (21): The current captured window has no data.

onLocalVideoStats

Callback for local video stream statistics.

public void onLocalVideoStats(Constants.VideoSourceType source, LocalVideoStats stats) {}

This callback is triggered every two seconds.

Trigger Timing

This callback is triggered every two seconds.

Parameters

source: Video source type. See VideoSourceType.
stats: Statistics of the local video stream. See LocalVideoStats.

onRemoteVideoStateChanged

Callback when the remote video state changes.

public void onRemoteVideoStateChanged(int uid, int state, int reason, int elapsed)

Note: This callback may not work properly when the number of users (in a communication channel) or hosts (in a live broadcasting channel) exceeds 32.

Trigger Timing

This callback is triggered when the state of the remote video changes.

Parameters

uid

The user ID of the remote user whose video state has changed.

state

The state of the remote video:

REMOTE_VIDEO_STATE_STOPPED (0): The remote video is in the initial state. This state is reported under REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3), REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5), or REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7).
REMOTE_VIDEO_STATE_STARTING (1): The first frame of the remote video packet is received.
REMOTE_VIDEO_STATE_DECODING (2): The remote video stream is decoded and playing normally. This state is reported under REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (2), REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED (4), REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6), or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY (9).
REMOTE_VIDEO_STATE_FROZEN (3): The remote video is frozen. This state is reported under REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION (1) or REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK (8).
REMOTE_VIDEO_STATE_FAILED (4): The remote video fails to start. This state is reported by the SDK under REMOTE_VIDEO_STATE_REASON_INTERNAL (0).

reason

The reason for the remote video state change:

REMOTE_VIDEO_STATE_REASON_INTERNAL (0): Internal reason.
REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION (1): Network congestion.
REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY (2): Network recovery.
REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED (3): The local user stops receiving the remote video stream or disables the video module.
REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED (4): The local user resumes receiving the remote video stream or enables the video module.
REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED (5): The remote user stops sending the video stream or disables the video module.
REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED (6): The remote user resumes sending the video stream or enables the video module.
REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE (7): The remote user leaves the channel.
REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK (8): The remote media stream switches to audio-only due to poor network conditions.
REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY (9): The remote media stream switches back to video after the network condition improves.
REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT (13): The local video decoder does not support decoding the remote video stream.

elapsed

Time (ms) from the local user calling joinChannel to the SDK triggering this callback.

onRemoteVideoStats

Callback that reports statistics of the video stream sent by each remote user.

public void onRemoteVideoStats(RemoteVideoStats stats) {}

The SDK triggers this callback every two seconds for each remote user. If there are multiple users or hosts sending video streams in the channel, the SDK triggers this callback multiple times accordingly.

Trigger Timing

This callback is triggered when the SDK collects video stream statistics from remote users every two seconds.

Parameters

stats: Statistics of the remote video stream. See RemoteVideoStats.

onRemoteVideoTransportStats

Callback for transport-layer statistics of remote video stream.

public void onRemoteVideoTransportStats(int uid, int delay, int lost, int rxKBitRate)

Deprecated: This method is deprecated. Use onRemoteVideoStats instead.

This callback reports transport-layer statistics such as packet loss rate and network delay. It is triggered every 2 seconds during the call when the local user receives video packets from a remote user or host.

Trigger Timing

This callback is triggered every 2 seconds during the call when the local user receives video packets from a remote user or host.

Parameters

uid: Remote user ID.
delay: Network delay from sender to receiver (ms).
lost: Packet loss rate (%) of video packets sent from the remote user.
rxKBitRate: Received video bitrate (Kbps).

onUserEnableLocalVideo

Callback triggered when a specified remote user enables or disables local video capture.

public void onUserEnableLocalVideo(int uid, boolean enabled)

Deprecated

This callback is deprecated. Use the onRemoteVideoStateChanged callback instead, with the following parameters:

REMOTE_VIDEO_STATE_STOPPED(0) and REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5).
REMOTE_VIDEO_STATE_DECODING(2) and REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6).

Trigger Timing

This callback is triggered when a remote user calls enableLocalVideo to enable or disable local video capture.

Parameters

uid

Remote user ID.

enabled

Whether the specified remote user enables local video capture:

true: Enables the video module. Other users in the channel can see the remote user's video.
false: Disables the video module. Other users in the channel cannot receive the remote user's video stream, but the remote user can still receive video streams from others.

onUserEnableVideo

Callback when a remote user enables or disables the video module.

public void onUserEnableVideo(int uid, boolean enabled)

This callback is triggered when a remote user calls enableVideo or disableVideo. After disabling the video module, the user can only make voice calls and cannot send or receive any video.

Trigger Timing

This callback is triggered when a remote user enables or disables the video module.

Parameters

uid

Remote user ID.

enabled

Whether the video module is enabled:

true: Video module is enabled.
false: Video module is disabled.

onUserMuteVideo

Callback when the remote video state changes.

public void onUserMuteVideo(int uid, boolean muted)

When a remote user calls muteLocalVideoStream, the SDK triggers this callback to report the remote user's video stream state to the local user.

Note: When the number of users in a communication scenario or hosts in an ultra-low latency live streaming scenario exceeds 32, this callback may be inaccurate.

Trigger Timing

This callback is triggered when a remote user calls muteLocalVideoStream to stop or resume publishing video streams.

Parameters

uid

Remote user ID.

muted

Whether the remote user stops publishing video streams:

true: The remote user stops publishing video streams.
false: The remote user resumes publishing video streams.

onVideoPublishStateChanged

Callback for video publish state change.

public void onVideoPublishStateChanged(Constants.VideoSourceType source, String channel, int oldState, int newState, int elapseSinceLastState)

Parameters

source

Type of video source. See VideoSourceType.

channel

Channel name.

oldState

Previous video publish state:

PUB_STATE_IDLE (0): Initial publish state after joining the channel.
PUB_STATE_NO_PUBLISHED (1): Failed to publish the local stream.
PUB_STATE_PUBLISHING (2): Publishing the local stream.
PUB_STATE_PUBLISHED (3): Successfully published the local stream.

newState

Current video publish state:

PUB_STATE_IDLE (0): Initial publish state after joining the channel.
PUB_STATE_NO_PUBLISHED (1): Failed to publish the local stream.
PUB_STATE_PUBLISHING (2): Publishing the local stream.
PUB_STATE_PUBLISHED (3): Successfully published the local stream.

elapseSinceLastState

Time elapsed (ms) from the previous state to the current state.

onVideoSizeChanged

Callback when the video size or rotation information of a specified user changes.

public void onVideoSizeChanged(Constants.VideoSourceType source, int uid, int width, int height, int rotation)

Trigger Timing

This callback is triggered when the video size or rotation angle of a specified user changes.

Parameters

source: Video source type. See VideoSourceType.
uid: User ID whose video size or rotation changed. For the local user, uid is 0, indicating the local video preview.
width: Width of the video stream (in pixels).
height: Height of the video stream (in pixels).
rotation: Video rotation angle, range [0, 360).

onVideoStopped

Callback triggered when the video stops playing.

public void onVideoStopped() {}

Deprecated: This method is deprecated. Use onLocalVideoStateChanged instead.

You can change the view configuration in this callback, such as displaying another image in the view.

Trigger Timing

This callback is triggered when the video stops playing.