Overview

In Composite Recording mode, you can add watermarks to the video, such as a logo, timestamp, or text, for copyright protection, promotion, or recording.

The On-premise Recording SDK supports three types of watermarks:

  • Text watermarks: Use text as the watermark. You can specify the font and font size.
  • Timestamp watermarks: Use a dynamic timestamp that shows the current time of the recording server (such as "2019:06:18 14:30:35") as the watermark. You can specify the font size of the timestamp.
  • Image watermarks: Use a PNG image as the watermark. The image is displayed at a fixed position on the video.

The On-premise Recording SDK v3.0 and later support watermarks.

Configure watermarks

Set the wm_num parameter to specify the total number of watermarks. You can add up to 15 watermarks (one timestamp watermark, four image watermarks, and ten text watermarks).

Set the wm_configs parameter to configure the watermarks. You can specify multiple WatermarkConfig objects in the wm_configs parameter. The number of WatermarkConfig objects must be the same as the value of the wm_num parameter.

In WatermarkConfig, you can set the type parameter to specify the watermark type and set the configparameter to define the detailed configuration of each watermark.

Text watermarks

Set the following parameters to add a text watermark:

  • Set the type parameter as WATERMARK_TYPE_LITERA.
  • Set the wm_litera parameter in config to add the text in the string format.
  • Set the font_size parameter in config to specify the font size. The default value is 10 (10 x 15 points at 144 dpi).
  • Set the font_file_path parameter in config to specify the path of the font file. Supported font file formats: TTF and OTF. If not specified, the default font, NotoSansMonoCJKsc-Regular, is used.
  • Set the offset_x, offset_y, wm_width, and wm_height parameters in config to specify the size and position of the watermark rectangle.
  • Supports up to 10 text watermarks.
  • Supports only UTF-8 encoding.
  • The supported characters depend on the font. The default font is NotoSansMonoCJKsc-Regular. See the font introduction.
  • There is no limit on the string length. How the text is displayed on the watermark rectangle depends on the font size and the size of the watermark rectangle. The part of the text that exceeds the area of the rectangle will not be displayed.
  • Supports word wrap and line breaks.
  • The font color is either black or white and automatically changes according to the video background: If the background is dark, the font color is white; and if the background is bright, the font color is black.

Timestamp watermarks

Set the following parameters to add a timestamp watermark:

  • Set the type parameter as WATERMARK_TYPE_TIMESTAMP.
  • Set the font_size parameter in config to specify the font size of the timestamp. The default value is 10 (10 x 15 points at 144 dpi).
  • Set the offset_x, offset_y, wm_width, and wm_height parameters in config to specify the size and position of the watermark rectangle.
  • Supports only one timestamp watermark.
  • The dynamic timestamp shows the current time of the recording server, such as "2019:06:18 14:30:35".
  • The timestamp color is either black or white and automatically changes according to the video background: If the background is dark, the color is white; and if the background is bright, the color is black.

Image watermarks

Set the following parameters to add an image watermark:

  • Set the type parameter as WATERMARK_TYPE_LITERA.
  • Set the image_path parameter in config to specify the path of the image.
  • Set the offset_x, offset_y, wm_width, and wm_height parameters in config to specify the size and position of the watermark rectangle.
  • Supports up to four image watermarks.
  • Supports only local PNG images.
  • The resolution of the image should not exceed 480p.
  • If the image is smaller than the watermark rectangle, the SDK centers the image; if the image is larger than the watermark rectangle, the SDK resizes and centers the image in the watermark rectangle.

Specify the size and position of a watermark rectangle

No matter what type of watermark you want to add, you must set the offset_x, offset_y, wm_width, and wm_height parameters in config to specify the horizontal position, vertical position, width, and height of the watermark rectangle.

As shown in the figure above, we set the upper-left corner of the video canvas as the origin. The offset_x and offset_y parameters define the position of the watermark rectangle on the canvas, representing the horizontal and vertical distances between the upper-left corner of the rectangle and the origin respectively. The wm_width and wm_height parameters define the width and height of the rectangle. The offset_x, offset_y, wm_width, and wm_height parameters are absolute values in pixels. The default value is 0.

Add watermarks

You can add watermarks to the recorded video in the following ways:

  • Set the wm_num and wm_configs parameters when calling the setVideoMixingLayout method.
  • Set the wm_num and config parameters when calling the updateWatermarkConfigs method.

Update and delete watermarks

You can call the setVideoMixingLayout or updateWatermarkConfigs method to update the configuration of the watermarks and also to delete them.

For example, if you have added an image watermark and a text watermark and you want to delete the text watermark, you can change the wm_num parameter from 2 to 1, delete the configuration of the original text watermark, pass in the configuration of the original image watermark, and then call the updateWatermarkConfigs method.

Note that if you want to delete all the watermarks that you have added, you must call the updateWatermarkConfigs method, and set the wm_num and config parameters as 0 and NULL respectively. If you call the setVideoMixingLayoutmethod and do not set the wm_num and config parameters, the On-premise Recording SDK will not change the watermarks.

Code snippets

The following C++ code snippets show how to add an image watermark, a timestamp watermark, and a text watermark by calling the setVideoMixingLayout method.

agora::linuxsdk::VideoMixingLayout layout;

//TO DO: Set other video layout configuration in composite recording mode here.

//Watermark configuration.
agora::linuxsdk::WatermarkConfig config[3];
config[0].type = agora::linuxsdk::WATERMARK_TYPE_IMAGE;
config[0].config.image.image_path = "path-to-test.png";
config[0].config.image.offset_x = 20;
config[0].config.image.offset_y = 20;
config[0].config.image.wm_width = 200;
config[0].config.image.wm_height = 300;

config[1].type = agora::linuxsdk::WATERMARK_TYPE_TIMESTAMP;
config[1].config.timestamp.font_size = 10;
config[1].config.timestamp.offset_x = 20;
config[1].config.timestamp.offset_y = 400;
config[1].config.timestamp.wm_width = 200;
config[1].config.timestamp.wm_height = 20;

config[2].type = agora::linuxsdk::WATERMARK_TYPE_LITERA;
config[2].config.litera.font_size = 10;
config[2].config.litera.wm_litera = "test watermark";
config[2].config.litera.offset_x = 20;
config[2].config.litera.offset_y = 500;
config[2].config.litera.wm_width = 200;
config[2].config.litera.wm_height = 20;

layout.wm_num = 3;
layout.wm_configs = config;

int res = m_enigne->setVideoMixingLayout(layout);

API Reference