Video Rendering

enableInstantMediaRendering

Enables instant rendering of audio and video frames.

public abstract int enableInstantMediaRendering();
Since
Available since v4.1.1.

After successfully calling this method, the SDK enables instant frame rendering mode, accelerating the rendering of the first frame after the user joins the channel.

Note: Both broadcasters and audience members need to call this method to experience instant rendering of audio and video frames. Once this method is successfully called, you can only disable instant rendering by calling the destroy [2/2] method to destroy the RtcEngine object.

Scenario

Agora recommends enabling this mode for audience in ultra-low latency live streaming scenarios.

Timing

This method must be called before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -7: This method is called before RtcEngine is initialized.

setLocalRenderMode [1/2]

Sets the display mode of the local video.

public abstract int setLocalRenderMode(int renderMode)
Deprecated
This method is deprecated and not recommended.

You can call this method to set the display mode of the local video. It can be called multiple times during a call to dynamically adjust the display mode.

Parameters

renderMode
Display mode of the local video:
  • RENDER_MODE_HIDDEN (1): Hidden mode. Scales the video proportionally until it fills the view boundaries, possibly cropping part of the video.
  • RENDER_MODE_FIT (2): Fit mode. Scales the video proportionally until one side fits the view. The remaining area is filled with black.
  • RENDER_MODE_ADAPTIVE (3): Adaptive mode. This enum value is deprecated and not recommended.

Return Values

  • 0: Success.
  • < 0: Failure.

setLocalRenderMode [2/2]

Updates the display mode of the local video view.

public abstract int setLocalRenderMode(int renderMode, int mirrorMode);

This method only affects what the local user sees and does not affect the publication of the local video.

Timing

Make sure to call setupLocalVideo to initialize the local video view before calling this method. During a call, you can call this method multiple times as needed to update the display mode of the local video view.

Parameters

renderMode
Display mode of the local video:
  • RENDER_MODE_HIDDEN (1): Hidden mode. Scales the video proportionally until it fills the view boundaries (may be cropped). One edge of the video may be cut off.
  • RENDER_MODE_FIT (2): Fit mode. Scales the video proportionally until one side fits the view. The remaining area due to aspect ratio mismatch is filled with black.
  • RENDER_MODE_ADAPTIVE (3): Adaptive mode (deprecated and not recommended).
mirrorMode
Note: If you use the front camera, the SDK enables mirror mode by default; if you use the rear camera, the SDK disables mirror mode by default.
Mirror mode of the local user's video:
  • VIDEO_MIRROR_MODE_AUTO (0): SDK automatically decides whether to enable mirror mode.
  • VIDEO_MIRROR_MODE_ENABLED (1): Enables mirror mode for the local view.
  • VIDEO_MIRROR_MODE_DISABLED (2): Disables mirror mode for the local view.

Return Values

  • 0: Success.
  • < 0: Failure.

setLocalRenderTargetFps

Sets the maximum frame rate for local video rendering.

public abstract int setLocalRenderTargetFps(Constants.VideoSourceType sourceType, int targetFps);

You can call this method in scenarios where high rendering frame rate is not required, such as screen sharing or online education. The SDK will attempt to keep the actual local rendering frame rate near the specified value to reduce CPU usage and improve system performance.

Scenario

In scenarios where video rendering frame rate is not critical (such as screen sharing or online education), you can call this method to set the maximum frame rate for local video rendering. The SDK will try to keep the actual local rendering frame rate near this value to reduce CPU usage and improve system performance.

Timing

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

Parameters

sourceType
Type of video source. See VideoSourceType.
targetFps
Frame rate (fps) for local video capture. Supported values: 1, 7, 10, 15, 24, 30, 60.
Note: This parameter must be set to a value lower than the actual video frame rate, otherwise it will not take effect.

Return Values

  • 0: Success.
  • < 0: Failure.

setLocalVideoMirrorMode

Sets the local video mirror mode.

public abstract int setLocalVideoMirrorMode(int mode)
Deprecated
This method is deprecated.

Parameters

mode
Local video mirror mode:
  • VIDEO_MIRROR_MODE_AUTO (0): The SDK decides whether to enable mirror mode. Mirror mode is enabled by default for the front camera and disabled for the rear camera.
  • VIDEO_MIRROR_MODE_ENABLED (1): Enable mirror mode for the local view.
  • VIDEO_MIRROR_MODE_DISABLED (2): Disable mirror mode for the local view.

Return Values

  • 0: Success.
  • < 0: Failure.

setRemoteRenderMode

Updates the display mode of the remote user's video view.

public abstract int setRemoteRenderMode(int uid, int renderMode)
Deprecated
This method is deprecated.

You can call this method to update the rendering and mirror modes of the remote user's video view. This method only affects what the local user sees.

Note:
  • Make sure to call setupRemoteVideo to initialize the remote video view before calling this method.
  • During a call, you can call this method multiple times to update the display mode of the remote user's video view.

Parameters

uid
Remote user ID.
renderMode
Display mode of the remote user's video view:
  • RENDER_MODE_HIDDEN(1): Scales the video proportionally until it fills the view boundaries (may be cropped). Some content may be cut off.
  • RENDER_MODE_FIT(2): Scales the video proportionally until one dimension fits the view. The remaining area due to aspect ratio mismatch is filled with black.

Return Values

  • 0: Success.
  • < 0: Failure.

setRemoteRenderModeEx

Sets the video display mode of a specified remote user.

public abstract int setRemoteRenderModeEx(int uid, int renderMode, int mirrorMode, RtcConnection connection);

Call this method after initializing the remote view using the setupRemoteVideo method. During a call, you can call this method multiple times to update the display mode of the remote user's video view.

Scenario

This method applies to multi-channel scenarios.

Parameters

uid
Remote user ID.
renderMode
Remote user's video display mode:
  • RENDER_MODE_HIDDEN (1): Hidden mode. Scales the video to fill the view while maintaining the aspect ratio. Some parts of the video might be cropped.
  • RENDER_MODE_FIT (2): Fit mode. Scales the video to fit one dimension of the view while maintaining the aspect ratio. Black bars appear in the remaining areas.
  • RENDER_MODE_ADAPTIVE (3): Adaptive mode (deprecated, not recommended).
mirrorMode
Mirror mode of the remote user view:
  • VIDEO_MIRROR_MODE_AUTO (0): The SDK automatically decides whether to enable mirror mode. Mirror mode is enabled by default when using the front camera and disabled when using the rear camera.
  • VIDEO_MIRROR_MODE_ENABLED (1): Enables mirror mode for the local view.
  • VIDEO_MIRROR_MODE_DISABLED (2): Disables mirror mode for the local view.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

setRemoteRenderTargetFps

Sets the maximum frame rate for rendering remote video.

public abstract int setRemoteRenderTargetFps(int targetFps);

In scenarios where high frame rate rendering is not required (e.g., screen sharing, online education), or when the remote user uses a low- or mid-end device, you can call this method to set the maximum rendering frame rate for the remote client. The SDK tries to keep the actual rendering frame rate close to this value to reduce CPU usage and improve system performance.

Scenario

In scenarios where video rendering frame rate is not critical (e.g., screen sharing, online education) or when the remote user is using a low- or mid-end device, you can call this method to set the maximum frame rate for remote client video rendering. The SDK will try to keep the actual rendering frame rate near this value to reduce CPU usage and improve system performance.

Timing

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

Parameters

targetFps
Target rendering frame rate (fps). Supported values: 1, 7, 10, 15, 24, 30, 60.
Note: Set this parameter to a value lower than the actual video frame rate, otherwise the setting will not take effect.

Return Values

  • 0: Success.
  • < 0: Failure.

setVideoRenderMode

Sets the rendering mode of the media player.

int setRenderMode(int mode);

Parameters

mode
Sets the rendering mode of the view:
  • RENDER_MODE_HIDDEN (1): Hidden mode. Scales the video proportionally until it fills the view bounds, which may crop part of the video.
  • RENDER_MODE_FIT (2): Fit mode. Scales the video proportionally until one side fits the view bounds. Black bars are used to fill the remaining area due to aspect ratio differences.
  • RENDER_MODE_ADAPTIVE (3): Adaptive mode. This enum value is deprecated and not recommended.

Return Values

  • 0: The method call succeeds.
  • < 0: The method call fails.

setupLocalVideo

Initializes the local video view.

public abstract int setupLocalVideo(VideoCanvas local);

You can call this method to bind the local video stream to a video view (view) and set the rendering and mirror modes. The binding remains valid after leaving the channel. To stop rendering or unbind the local video from the view, set view to null. In real-time interaction scenarios, if you need to display multiple preview views simultaneously in the local video preview, with each view at a different observation position in the video pipeline, you can call this method multiple times with different view instances and set different observation positions for each. For example, after setting the video source to the camera, configure two views with position set to VIDEO_MODULE_POSITION_POST_CAPTURER_ORIGIN and VIDEO_MODULE_POSITION_POST_CAPTURER, respectively, to simultaneously preview the raw unprocessed video frame and the video frame after applying beautification, virtual background, watermark, etc.

Note: To update only the rendering or mirror mode of the local video view during a call, call setLocalRenderMode.

Scenario

After initialization, call this method to set up local video before joining a channel. In real-time interaction scenarios, if you want to preview multiple views from different perspectives locally, you can call this method multiple times with different view and positions.

Timing

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

Parameters

local
Local video view and related settings. See VideoCanvas.

Return Values

  • 0: Success.
  • < 0: Failure.

setupRemoteVideo

Initializes the remote video view.

public abstract int setupRemoteVideo(VideoCanvas remote);

This method initializes the view for the remote video stream on the local device and only affects what the local user sees. You can call this method to bind the remote video stream to a video view and set the rendering and mirror modes for that view. You must specify the remote user's ID in this method. If the app has not yet obtained the remote user ID, set it after receiving the onUserJoined callback. To unbind the remote user from the view, set the view parameter to null. Once the remote user leaves the channel, the SDK automatically unbinds the user. In scenarios where you customize the video mixing layout on mobile, you can call this method and assign a separate view for each sub-stream in the mixed stream for rendering.

Note:
  • To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderMode method.
  • When using the recording service, the app does not need to bind a view because the recording service does not send video streams. If your app cannot identify the recording service, bind the remote user to a view when the SDK triggers the onFirstRemoteVideoDecoded callback.

Parameters

remote
Remote video view and related settings. See VideoCanvas.

Return Values

  • 0: Success.
  • < 0: Failure.

setupRemoteVideoEx

Initializes the video view of a remote user.

public abstract int setupRemoteVideoEx(VideoCanvas remote, RtcConnection connection);

You can call this method to bind a remote video stream to a video view and set the rendering and mirror modes of the video view. This method only affects the video view seen by the local user. The app must specify the remote user ID using VideoCanvas before the remote user joins the channel. If the app has not yet obtained the remote user ID, you can set it after receiving the onUserJoined callback. If video recording is enabled, the recording service will join the channel as a virtual client, and other clients will also receive the onUserJoined callback. Do not bind the virtual client to a view in the app, as it does not send any video stream. To unbind a remote user from the view, set the view parameter to null. After the remote user leaves the channel, the SDK automatically unbinds it.

Note: To update the rendering or mirror mode of the remote video view during a call, use the setRemoteRenderModeEx method.

Scenario

This method applies to multi-channel scenarios.

Parameters

remote
Settings of the remote video view. See VideoCanvas.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

startMediaRenderingTracing

Enables tracing of the video frame rendering process.

public abstract int startMediaRenderingTracing();
Since
Available since v4.1.1.

Once this method is successfully called, the SDK starts tracing the rendering status of video frames in the channel and reports related event information via the onVideoRenderingTracingResult callback.

Note:
  • If you do not call this method, the SDK starts tracing video frame rendering events from the moment joinChannel is called.
  • After the local user leaves the current channel, the SDK will automatically begin tracing video rendering events again upon rejoining the channel.

Scenario

You can call this method in conjunction with UI settings in your app (such as buttons or sliders) to enhance user experience. For example, call this method when the user clicks the "Join Channel" button, then use the onVideoRenderingTracingResult callback to get the rendering time of video frames to optimize related metrics.

Related Callbacks

This method triggers the onVideoRenderingTracingResult callback.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -7: This method is called before RtcEngine is initialized.

startMediaRenderingTracingEx

Enables tracing of the video frame rendering process.

public abstract int startMediaRenderingTracingEx(RtcConnection connection);
Since
Available since v4.1.1.

After successfully calling this method, the SDK traces the rendering status of video frames in the channel and reports related event information through the onVideoRenderingTracingResult callback.

Note:
  • If you do not call this method, the SDK starts tracing video frame rendering events from the time joinChannel is called.
  • You can call this method at the appropriate time based on your application scenario to set the starting point for tracing video rendering events.
  • After the local user leaves the current channel, the SDK automatically resumes tracing from the next time the user joins a channel.

Scenario

This method is applicable in multi-channel scenarios.

Related Callbacks

This method triggers the onVideoRenderingTracingResult callback.

Parameters

connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

onTranscodedStreamLayoutInfo

Callback for receiving a mixed video stream with layout information.

public void onTranscodedStreamLayoutInfo(int uid, VideoLayoutInfo info) {}

When the local user receives a mixed video stream sent by the video mixing server for the first time, or when the layout information of the stream changes, the SDK triggers this callback to report the layout information of each sub-video stream in the mixed stream.

Trigger Timing

This callback is triggered when the local user receives a mixed video stream for the first time, or when the layout information of the stream changes.

Parameters

uid
User ID that published the mixed video stream.
info
Layout information of sub-video streams. See VideoLayoutInfo.

onVideoRenderingTracingResult

Callback for video frame rendering events.

public void onVideoRenderingTracingResult(int uid, Constants.MEDIA_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo)

After calling the startMediaRenderingTracing method or joining the channel, the SDK triggers this callback to report video frame rendering events and various metrics during rendering. You can optimize these metrics to improve the efficiency of the first frame rendering.

Parameters

uid
User ID.
currentEvent
Current video frame rendering event. See MEDIA_TRACE_EVENT.
tracingInfo
Various metrics during video frame rendering. See VideoRenderingTracingInfo.