Watermark

addVideoWatermark [1/3]

Adds a PNG format watermark image to the local video stream.

virtual int addVideoWatermark(const RtcImage& watermark) __deprecated = 0;

Deprecated: This method is deprecated.

After adding a watermark image, all users in the channel (including CDN viewers) and video capture devices can see and capture the image. If you only want to add a watermark in CDN streaming, refer to startRtmpStreamWithTranscoding.

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 the local video stream; in CDN streaming, the URL refers to the URL 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 file to fit the settings.
The Agora SDK only supports adding one watermark image in either the local video or the CDN stream. A newly added watermark image will replace the previous one.

Parameters

watermark: Watermark image. See RtcImage for details.

Return Values

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

addVideoWatermark [2/3]

Adds a PNG watermark image to the local video.

virtual int addVideoWatermark(const char* watermarkUrl, const WatermarkOptions& options) = 0;

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

In live streaming, this method adds a PNG watermark image to the local video. 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 supports adding only one watermark image at a time. Adding a new image replaces the previous one. The coordinates of the watermark image depend 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 image is in landscape mode.
If the orientation mode is fixed portrait or adaptive portrait, the watermark image is in portrait mode.
When setting the watermark position, the region must be smaller than the video dimensions set in setVideoEncoderConfiguration, otherwise the watermark image will be cropped.

You can control whether the watermark is visible in the preview by setting the visibleInPreview parameter. However, its final visibility also depends on the video frame position (position) set in setupLocalVideo:

Observation position VIDEO_MODULE_POSITION_POST_CAPTURER (default): if visiblePreview is true, the watermark is visible; if false, it is not.
Observation position VIDEO_MODULE_POSITION_PRE_ENCODER: if visiblePreview is true, the watermark is visible; if false, it 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 PNG format watermark images. 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 mirroring for the local video, the watermark in the local video will also be mirrored. To avoid mirroring the watermark, Agora recommends not using both local video mirroring and watermark features simultaneously. You can implement the watermark at the application layer.

Parameters

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

Return Values

0: Success.
< 0: Failure.

addVideoWatermark [3/3]

Adds a watermark image to the local video stream.

virtual int addVideoWatermark(const WatermarkConfig& configs) = 0;

Since: Available since v4.6.0.

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

Parameters

configs: The watermark configuration. See WatermarkConfig.

Return Values

0: Success.
< 0: Failure.

addVideoWatermarkEx [1/2]

Adds a watermark image to the local video.

virtual int addVideoWatermarkEx(const char* watermarkUrl, const WatermarkOptions& options, const RtcConnection& connection) = 0;

Deprecated: Deprecated since v4.6.0. Use addVideoWatermarkEx(const WatermarkConfig& config, const RtcConnection& connection) instead.

This method adds a PNG format watermark image to the local video during a live broadcast. Once added, all viewers in the channel (including CDN viewers) and capture devices can see and capture the image. The Agora SDK supports only one watermark image per live video stream. A newly added image replaces the previous one. The position of the watermark image depends 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 is displayed in landscape mode.
If the orientation mode is fixed portrait or adaptive portrait, the watermark is displayed in portrait mode.
When setting the watermark position, the area must be smaller than the video dimensions set in setVideoEncoderConfigurationEx, otherwise the watermark image will be cropped.

Note:

Make sure to call enableVideo 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 PNG image size does not match the settings of this method, the image will be cropped or scaled to fit.
If you have enabled local video preview using startPreview, you can set whether the watermark is visible in the preview via the visibleInPreview member.
If mirror mode is enabled for the local video, the watermark will also be mirrored. To avoid the watermark being mirrored, Agora recommends not using mirror mode and watermarking simultaneously. You can also 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 both absolute and 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.

virtual int addVideoWatermarkEx(const WatermarkConfig& config, const RtcConnection& connection) = 0;

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 the watermark image from the video stream.

virtual int clearVideoWatermarkEx(const RtcConnection& connection) = 0;

Parameters

connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

clearVideoWatermarks

Removes watermark images from the video stream.

virtual int clearVideoWatermarks() = 0;

Return Values

0: Success.
< 0: Failure.

removeVideoWatermark

Removes a watermark image from the local video.

virtual int removeVideoWatermark(const char* id) = 0;

Since: Available since v4.6.0.

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

Parameters

id: The ID of the watermark to remove. This value must match the ID used when the watermark was added.

Return Values

0: Success.
< 0: Failure.

removeVideoWatermarkEx

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

virtual int removeVideoWatermarkEx(const char* id, const RtcConnection& connection) = 0;

Since: Available since v4.6.0.

Scenario

This method applies to multi-channel scenarios.

Parameters

id: Watermark ID.
connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.