Custom Video Capture and Rendering

createCustomVideoTrack

Creates a custom video track.

public abstract int createCustomVideoTrack();

Call this method to create a video track and obtain the video track ID. This ID can be used to publish a custom video source. To publish a custom video source, follow these steps:

Call this method to create a video track and obtain the video track ID.
Call joinChannel to join a channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID to be published and set publishCustomVideoTrack to true.
Call pushExternalVideoFrameById and set videoTrackId to the video track ID specified in step 2 to publish the corresponding custom video source in the channel.

Return Values

If the method call succeeds, returns the unique identifier of the video track, i.e., the video track ID.
If the method call fails, returns 0xffffffff.

destroyCustomVideoTrack

Destroys the specified video track.

public abstract int destroyCustomVideoTrack(int video_track_id);

Parameters

video_track_id: The video track ID returned by createCustomVideoTrack.

Return Values

0: Success.
< 0: Failure.

isTextureEncodeSupported

Checks whether Texture encoding is supported for video.

public abstract boolean isTextureEncodeSupported();

Return Values

true: Texture encoding is supported.
false: Texture encoding is not supported.

pushExternalVideoFrameById [1/2]

Pushes external raw video frame to the SDK via video track.

public abstract int pushExternalVideoFrameById(VideoFrame frame, int videoTrackId);

To publish a custom video source, follow these steps:

Call createCustomVideoTrack to create a video track and get the video track ID.
Call joinChannel to join the channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID and set publishCustomVideoTrack to true.
Call pushExternalVideoFrameById and set videoTrackId to the ID from step 2 to publish the corresponding custom video source in the channel.

You can push video frames by calling pushExternalVideoFrameById or pushExternalVideoFrameById (with AgoraVideoFrame parameter). The difference is that this method supports video data in Texture format.

Note: If you only need to push one custom video source to the channel, you can directly call setExternalVideoSource, and the SDK will automatically create a video track with videoTrackId 0. Danger: After calling this method, even if you stop pushing external video frames to the SDK, the custom video stream will still be counted toward video duration and incur charges. Agora recommends taking appropriate actions based on your use case to avoid such charges:

If you no longer need to capture external video, call destroyCustomVideoTrack to destroy the custom video track.
If you only want to use external video for local preview and not publish it to the channel, call muteLocalVideoStream to stop sending the video stream, or call updateChannelMediaOptions and set publishCustomVideoTrack to false.

Parameters

frame: The video frame to be pushed.
videoTrackId: The video track ID returned by createCustomVideoTrack.
Note: If you only need to push one custom video source, set videoTrackId to 0.

Return Values

0: Success.
< 0: Failure.

pushExternalVideoFrame [1/2]

Pushes external raw video frame to the SDK.

public abstract boolean pushExternalVideoFrame(VideoFrame frame)

Deprecated: This method is deprecated.

Call setExternalVideoSource and set enabled to true, and encodedFrame to false to use this method to push external raw video frames to the SDK. You can call this method or pushExternalVideoFrame to push video frames. The difference is that this method supports video data in Texture format.

Parameters

frame: The video frame to be pushed.

Return Values

true: Success.
false: Failure.

pushExternalVideoFrameById [2/2]

Pushes external raw video frame to the SDK via video track.

public abstract int pushExternalVideoFrameById(AgoraVideoFrame frame, int videoTrackId);

To publish a custom video source, follow these steps:

Call createCustomVideoTrack to create a video track and get the video track ID.
Call joinChannel to join the channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID and set publishCustomVideoTrack to true.
Call pushExternalVideoFrameById and set videoTrackId to the ID from step 2 to publish the corresponding custom video source in the channel.

You can push video frames by calling pushExternalVideoFrameById or pushExternalVideoFrame. The difference is that pushExternalVideoFrameById does not support Texture format video data.

Note: If you only need to push one custom video source to the channel, you can directly call setExternalVideoSource, and the SDK will automatically create a video track with videoTrackId 0. Warning: After calling pushExternalVideoFrameById, even if you stop pushing external video frames to the SDK, the custom video stream will still be counted toward video duration and incur charges. Agora recommends taking appropriate actions based on your use case to avoid such charges:

If you no longer need to capture external video, call destroyCustomVideoTrack to destroy the custom video track.
If you only want to use external video for local preview and not publish it to the channel, call muteLocalVideoStream to stop sending the video stream, or call updateChannelMediaOptions and set publishCustomVideoTrack to false.

Parameters

frame: The external raw video frame to be pushed. See AgoraVideoFrame.
videoTrackId: The video track ID returned by createCustomVideoTrack.
Note: If you only need to push one custom video source, set videoTrackId to 0.

Return Values

0: Success.
< 0: Failure.

pushExternalVideoFrame [2/2]

Pushes external raw video frame to the SDK.

public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame)

Deprecated: Deprecated since v4.5.0.

Call setExternalVideoSource and set enabled to true and encodedFrame to false to use pushExternalVideoFrame to push external raw video frames to the SDK. You can also call pushExternalVideoFrame to push video frames. The difference is that this method does not support Texture format video data.

Parameters

frame: The external raw video frame to be pushed. See AgoraVideoFrame.

Return Values

true: Success.
false: Failure.

setExternalRemoteEglContext

Sets the EGL context used to render remote video streams.

public abstract int setExternalRemoteEglContext(Object eglContext);

This method replaces the SDK's default remote EGL context, allowing you to manage the EGL context yourself. The SDK automatically releases the context when the engine is destroyed.

Scenario

This method is applicable when using custom rendering (e.g., Texture format) to replace the SDK's default rendering of remote video frames.

Timing

Call this method before joining a channel.

Parameters

eglContext: The EGL context used to render remote video streams.

Return Values

0: Success.
< 0: Failure.

setExternalVideoSource

Configures external video source.

public abstract int setExternalVideoSource(boolean enable, boolean useTexture, Constants.ExternalVideoSourceType sourceType);

After calling this method, you can call pushExternalVideoFrameById to push external video data to the SDK.

Note: Dynamic switching of video sources is not supported in the channel. To switch from external to internal video source, you must leave the channel, disable the external video source with this method, and rejoin the channel.

Timing

Call this method before joining a channel.

Parameters

enable

Whether to use an external video source:

true: Use external video source. SDK prepares to receive external video frames.
false: (Default) Do not use external video source.

useTexture

Whether to use Texture format for external video frames:

true: Use Texture format.
false: (Default) Do not use Texture format.

sourceType

Whether the external video frame is encoded. See ExternalVideoSourceType.

Return Values

0: Success.
< 0: Failure.