Watermark

addVideoWatermark [1/3]

Adds a watermark image to the local video.

public abstract int addVideoWatermark(AgoraImage watermark)

Deprecated: Deprecated since v2.9.1. Use addVideoWatermark [3/3] instead.

This method adds a PNG watermark image to the local video stream in a live broadcast scenario. All users in the channel (including CDN viewers) and video capture devices can see and capture the watermark image. If you only want to add a watermark to the CDN stream, use the startRtmpStreamWithTranscoding method.

Note:

The meaning of the URL differs between local video and CDN streaming: in the local video stream, the URL refers to the absolute path of the watermark image file; in CDN streaming, the URL refers to the address of the watermark image in the CDN stream.
The source file of the watermark image must be in PNG format. If the width and height of the PNG file do not match the settings in this method, the SDK will crop the PNG file to fit the settings.
The SDK only supports adding one watermark image to either the local video or the CDN stream. A newly added watermark image will replace the previous one.

Parameters

watermark: The watermark image to be added to the local live stream. See AgoraImage.

Return Values

0: Success.
< 0: Failure.

addVideoWatermark [2/3]

Adds a watermark image to the local video.

public abstract int addVideoWatermark(String watermarkUrl, WatermarkOptions options)

Deprecated: Deprecated since v4.6.0. Use addVideoWatermark [3/3] instead.

This method adds a PNG watermark image to the local video in a live broadcast. After adding the watermark, all viewers in the channel (including CDN viewers) and capture devices can see and capture the watermark image. The Agora SDK supports only one watermark image per live video stream. A newly added watermark replaces the previous one. The watermark image position depends on the settings in the setVideoEncoderConfiguration method:

If the orientation mode (ORIENTATION_MODE) of the encoded video is fixed landscape or adaptive landscape, the watermark uses landscape orientation.
If the orientation mode is fixed portrait or adaptive portrait, the watermark uses portrait orientation.
When setting the watermark position, the region must be smaller than the dimensions set in setVideoEncoderConfiguration, otherwise the watermark image will be cropped.

You can control the watermark visibility during preview by setting the visibleInPreview parameter. However, its final effect also depends on the position parameter set in setupLocalVideo (the video frame's position in the video pipeline):

Observation position VIDEO_MODULE_POSITION_POST_CAPTURER (default): visiblePreview is true, watermark is visible; visiblePreview is false, watermark is not visible.
Observation position VIDEO_MODULE_POSITION_PRE_ENCODER: visiblePreview is true, watermark is visible; visiblePreview is false, watermark is still visible.

Note:

Make sure to call enableVideo before calling this method.
If you only want to add a watermark for media streaming, you can call this method or startRtmpStreamWithTranscoding.
This method only supports watermark images in PNG format. Supported PNG pixel formats include RGBA, RGB, Palette, Gray, and Alpha_gray.
If the PNG image size does not match the settings in this method, the image will be cropped or scaled to fit.
If you enable mirror mode for the local video, the watermark in the local video will also be mirrored. To avoid this, Agora recommends not using both local video mirroring and watermark features simultaneously. You can implement watermarking at the application level.

Parameters

watermarkUrl: The local file path of the watermark image to be added. Supports both absolute and relative local paths.
options: Settings for the watermark image. See WatermarkOptions.

Return Values

0: Success.
< 0: Failure.

addVideoWatermark [3/3]

Adds a watermark image to the local video stream.

public abstract int addVideoWatermark(WatermarkConfig config);

Since: Available since v4.6.0.

You can use this method to overlay a watermark image on the local video stream using the WatermarkConfig, including setting the position, size, and visibility of the watermark in the preview.

Parameters

config: Watermark configuration. See WatermarkConfig.

Return Values

0: Success.
< 0: Failure.

addVideoWatermarkEx [1/2]

Adds a watermark image to the local video.

public abstract int addVideoWatermarkEx(String watermarkUrl, WatermarkOptions options, RtcConnection connection)

Deprecated: Deprecated since v4.6.0. Use addVideoWatermarkEx [2/2] instead.

This method adds a PNG watermark image to the local video during a live broadcast. After the watermark is added, all audience members in the channel (including CDN viewers) and capture devices can see and capture the image. The Agora SDK only supports adding one watermark image to a live video stream. A new image replaces the previous one. The coordinates of the watermark image depend on the settings in the setVideoEncoderConfigurationEx method:

If the orientation mode (ORIENTATION_MODE) of the encoded video is fixed landscape or adaptive landscape, the watermark uses landscape orientation.
If the orientation mode is fixed portrait or adaptive portrait, the watermark uses portrait orientation.
When setting the watermark position, the region must be smaller than the dimensions set in the setVideoEncoderConfigurationEx method, otherwise the image will be cropped.

Note:

Make sure to call the enableVideo method before calling this method.
This method only supports PNG format watermark images. Supported PNG pixel formats include RGBA, RGB, Palette, Gray, and Alpha_gray.
If the size of the PNG image does not match the settings in this method, the image will be cropped or scaled to fit.
If you have enabled local video preview using the startPreview method, you can use the visibleInPreview member to set whether the watermark is visible in the preview.
If local video mirroring is enabled, the watermark will also be mirrored. To avoid mirroring the watermark, Agora recommends not using mirroring and watermark features simultaneously. You can implement the watermark feature at the application level.

Scenario

This method applies to multi-channel scenarios.

Parameters

watermarkUrl: The local file path of the watermark image to be added. Supports absolute or relative local paths.
options: Settings for the watermark image. See WatermarkOptions.
connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

addVideoWatermarkEx [2/2]

Adds a watermark image to the local video.

public abstract int addVideoWatermarkEx(WatermarkConfig config, RtcConnection connection);

Since: Available since v4.6.0.

Scenario

This method applies to multi-channel scenarios.

Parameters

config: Watermark configuration. See WatermarkConfig.
connection: RtcConnection object. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

clearVideoWatermarkEx

Removes watermark images from the video stream.

public abstract int clearVideoWatermarkEx(RtcConnection connection);

Parameters

connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

clearVideoWatermarks

Removes watermark images from the video stream.

public abstract int clearVideoWatermarks();

Return Values

0: Success.
< 0: Failure.

getBuffer

Gets the data buffer of the watermark image.

public ByteBuffer getBuffer()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns a ByteBuffer object containing the watermark image data.

getFormat

Gets the format of the watermark image.

public int getFormat()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns the format of the watermark image buffer.

getHeight

Gets the height of the watermark image.

public int getHeight()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns the height of the watermark image in pixels.

getId

Retrieves the unique identifier of the watermark.

public String getId()

Since: Available since v4.6.0.

Used to retrieve the unique identifier of the watermark from a WatermarkBuffer or WatermarkConfig instance.

Return Values

The unique identifier of the watermark, if the method call succeeds.
An empty string, if the method call fails.

getImageUrl

Retrieves the URL of the watermark image.

public String getImageUrl()

Since: Available since v4.6.0.

Return Values

The URL of the watermark image, if the method call succeeds.
An empty string, if the method call fails.

getPositionInLandscapeMode

Gets the watermark position in landscape mode.

public int[] getPositionInLandscapeMode()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns an integer array with four elements representing the x, y, width, and height of the watermark rectangle.

getPositionInPortraitMode

Gets the watermark position in portrait mode.

public int[] getPositionInPortraitMode()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns an integer array with four elements representing the x, y, width, and height of the watermark rectangle.

getType

Retrieves the watermark type information in the current watermark configuration.

public int getType()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns the watermark type:

WATERMARK_TYPE_IMAGE: Image watermark.
WATERMARK_TYPE_BUFFER: Buffer watermark.

getWidth

Gets the width of the watermark image.

public int getWidth()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns the width of the watermark image in pixels.

getzOrder

Gets the Z-order index of the watermark image.

public int getzOrder()

Since: Available since v4.6.0.

Return Values

If the method call succeeds, returns the Z-order index of the watermark image.

isVisibleInPreview

Checks whether the watermark is visible in the local video preview.

public boolean isVisibleInPreview()

Since: Available since v4.6.0.

Return Values

true: The watermark is visible in the local video preview.
false: The watermark is not visible in the local video preview.

removeVideoWatermark

Removes a watermark image from the local video.

public abstract int removeVideoWatermark(String id);

Since: Available since v4.6.0.

This method removes a previously added watermark image from the local video stream using the specified unique ID.

Parameters

id: The ID of the watermark image to remove.

Return Values

0: Success.
< 0: Failure.

removeVideoWatermarkEx

Removes the specified watermark image from the local or remote video stream.

public abstract int removeVideoWatermarkEx(String id, RtcConnection connection);

Since: Available since v4.6.0.

Scenario

This method applies to multi-channel scenarios.

Parameters

id: The ID of the watermark image to be removed.
connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.