Local Video Transcoding

startLocalVideoTranscoder

Starts local video composition.

public abstract int startLocalVideoTranscoder(LocalTranscoderConfiguration config);
After calling this method, you can locally merge multiple video streams into one, such as camera capture, screen sharing, media player, remote video, video files, images, etc., and then publish the mixed video stream to the channel. Below is a typical use case for implementing portrait picture-in-picture:
  1. Call enableVirtualBackground and set the custom background image to BACKGROUND_NONE to separate the portrait from the background in the camera-captured video.
  2. Call startScreenCapture to start capturing the screen sharing video stream.
  3. Call startLocalVideoTranscoder and set the captured portrait video source as one of the sources for local video composition to achieve portrait picture-in-picture effect in the video.
Note:
  • Local video composition requires more CPU resources. Agora recommends enabling this feature on high-performance devices.
  • To mix locally captured video streams, the SDK supports the following combinations:
    • On Android, supports up to 2 camera-captured video streams (the device must support dual cameras or external cameras) + 1 screen sharing stream.
  • When configuring local video composition, ensure the layer number of the portrait video stream is greater than that of the screen sharing stream. Otherwise, the portrait will be blocked by the screen sharing and will not appear in the final mixed video.
  • The maximum resolution for each video stream participating in local video composition is 4096 × 2160. If this limit is exceeded, the video composition will not take effect.
  • The maximum resolution of the mixed video stream is 4096 × 2160.

Scenario

Applicable to scenarios such as remote meetings, live streaming, and online education. It helps users view and manage multiple video streams and supports features like portrait picture-in-picture.

Timing

Related Callbacks

If this method call fails, the SDK triggers the onLocalVideoTranscoderError callback to report the failure reason.

Parameters

config
Configuration for local video composition. See LocalTranscoderConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

updateLocalTranscoderConfiguration

Updates local composition configuration.

public abstract int updateLocalTranscoderConfiguration(LocalTranscoderConfiguration config);

After calling startLocalVideoTranscoder, if you need to update the local composition configuration, you can call this method.

Note: If you want to update the video source type used for local composition, such as adding a second camera or screen for video capture, call this method after calling startCameraCapture or startScreenCapture.

Parameters

config
Local composition configuration. See LocalTranscoderConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.

onLocalVideoTranscoderError

Callback for errors during local video mixing.

public void onLocalVideoTranscoderError(LocalTranscoderConfiguration.TranscodingVideoStream stream, int error)

When startLocalVideoTranscoder or updateLocalTranscoderConfiguration fails, the SDK triggers this callback to report the reason for the failure.

Trigger Timing

This callback is triggered when calling startLocalVideoTranscoder or updateLocalTranscoderConfiguration fails.

Parameters

stream
Video stream that cannot be mixed during video mixing. See TranscodingVideoStream.
error
Reason for the local video mixing error:
  • 1: The specified video source has not started video capture. You need to create a video track and start capture.
  • 2: Invalid video source type. You need to specify a supported video source type.
  • 3: Invalid image path. You need to specify the correct image path.
  • 4: Invalid image format. Make sure the image format is PNG, JPEG, or GIF.
  • 5: Invalid resolution after mixing.
  • 20: Internal error.