Add watermark to recordings

This guide explains how to configure and apply watermarks when recording video with the On-Premise Recording SDK.

Understand the tech

Use watermarks to display logos, timestamps, or custom text for branding, copyright, or verification. The On-Premise Recording SDK supports three types of watermarks in both individual and composite recording modes:

Text watermark: Shows user-defined text with customizable font and size.
Timestamp watermark: Displays the current time from the recording server.
Image watermark: Renders a static image in PNG or JPG format.

Prerequisites

Before adding watermarks, integrate the On-Premise Recording SDK and complete the Quickstart guide to ensure basic recording works as expected.

Implementation

To add watermarks to your recordings, follow the platform-specific implementation instructions:

To add or update a watermark in composite recording mode, call enableAndUpdateVideoWatermarks and pass an array of watermark configuration objects. Each object defines one watermark, including its type, content, position, and appearance. To remove all watermarks, call disableVideoWatermarks.

To use watermarks in individual recording mode, call enableAndUpdateVideoWatermarksByUid and disableVideoWatermarksByUid instead.

Add a text watermark

To add a text watermark:

Call enableAndUpdateVideoWatermarks and pass the watermark_configs array.

Set the watermark type to LITERA:

watermarks[i].type = agora::rtc::LITERA;

Configure the text, font path, and font size:

watermarks[i].literaSource.wmLitera = "Agora watermark example";
watermarks[i].literaSource.fontFilePath = "path/to/font.ttf"; // Optional
watermarks[i].literaSource.fontSize = 24;

Add a timestamp watermark

To add a timestamp watermark:

Call enableAndUpdateVideoWatermarks and pass the watermark_configs array.

Set the watermark type to TIMESTAMPS:

watermarks[i].type = agora::rtc::TIMESTAMPS;

Configure the font path and size:

watermarks[i].timestampSource.fontFilePath = "path/to/font.ttf"; // Optional
watermarks[i].timestampSource.fontSize = 20;

Add an image watermark

To add an image watermark:

Call enableAndUpdateVideoWatermarks and pass the watermark_configs array.

Set the watermark type to PICTURE:

watermarks[i].type = agora::rtc::PICTURE;

Set the image path:

watermarks[i].imageUrl = "path/to/watermark.png";

Set the watermark position

You can set watermark positions using either absolute pixels or relative ratios. You can also define separate positions for portrait and landscape orientations.

Fixed position (pixels)

Portrait mode

// Use fixed-pixel positioning
watermarks[i].options.mode = agora::rtc::FIT_MODE_COVER_POSITION;
watermarks[i].options.zOrder = 1;

watermarks[i].options.positionInPortraitMode.x = 50;
watermarks[i].options.positionInPortraitMode.y = 50;
watermarks[i].options.positionInPortraitMode.width = 200;
watermarks[i].options.positionInPortraitMode.height = 100;

Landscape mode

// Use fixed-pixel positioning
watermarks[i].options.mode = agora::rtc::FIT_MODE_COVER_POSITION;
watermarks[i].options.zOrder = 1;

watermarks[i].options.positionInLandscapeMode.x = 50;
watermarks[i].options.positionInLandscapeMode.y = 50;
watermarks[i].options.positionInLandscapeMode.width = 200;
watermarks[i].options.positionInLandscapeMode.height = 100;

Relative position (ratio)

// Use ratio-based positioning
watermarks[i].options.mode = agora::rtc::FIT_MODE_USE_IMAGE_RATIO;
watermarks[i].options.zOrder = 1;

watermarks[i].options.watermarkRatio.xRatio = 0.5;
watermarks[i].options.watermarkRatio.yRatio = 0.5;
watermarks[i].options.watermarkRatio.widthRatio = 0.6;

Complete sample

Full example for adding watermarks

if (!recorderConfig.waterMark.empty()) {
  std::vector<WatermarkConfig> watermarks(recorderConfig.waterMark.size());

  for (size_t i = 0; i < watermarks.size(); ++i) {
    const WatermarkInfo& info = recorderConfig.waterMark[i];
    watermarks[i].index = static_cast<int>(i + 1);
    watermarks[i].type = convertToWatermarkSourceType(info.type);

    if (watermarks[i].type == agora::rtc::LITERA) {
      watermarks[i].literaSource.wmLitera = info.litera;
      watermarks[i].literaSource.fontFilePath = info.fontFilePath;
      watermarks[i].literaSource.fontSize = info.fontSize;

    } else if (watermarks[i].type == agora::rtc::TIMESTAMPS) {
      watermarks[i].timestampSource.fontFilePath = info.fontFilePath;
      watermarks[i].timestampSource.fontSize = info.fontSize;

    } else if (watermarks[i].type == agora::rtc::PICTURE) {
      watermarks[i].imageUrl = info.imgUrl;
    }

    watermarks[i].options.mode = agora::rtc::FIT_MODE_COVER_POSITION;
    watermarks[i].options.zOrder = info.zOrder;

    watermarks[i].options.positionInPortraitMode = {
      info.x, info.y, info.width, info.height
    };

    watermarks[i].options.positionInLandscapeMode = {
      info.x, info.y, info.width, info.height
    };
  }

  recorder->enableAndUpdateVideoWatermarks(watermarks.data(), watermarks.size());
}

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

API references

This guide explains how to configure and apply watermarks when recording video with the On-Premise Recording SDK.

Understand the tech

Text watermark: Shows user-defined text with customizable font and size.
Timestamp watermark: Displays the current time from the recording server.
Image watermark: Renders a static image in PNG or JPG format.

Prerequisites

Before adding watermarks, integrate the On-Premise Recording SDK and complete the Quickstart guide to ensure basic recording works as expected.

Implementation

To add watermarks to your recordings, follow the platform-specific implementation instructions:

To apply or update a watermark in composite recording mode, call enableAndUpdateVideoWatermarks and pass an array of watermark configuration objects. Each object defines one watermark, including its type, content, position, and appearance. To remove all watermarks, call disableVideoWatermarks.

To apply watermarks in individual recording mode, use enableAndUpdateVideoWatermarksByUid and disableVideoWatermarksByUid instead.

Add a text watermark

To add a text watermark:

Call enableAndUpdateVideoWatermarks() and pass the watermarkConfigs array.

Set the watermark type to LITERA:

watermarks[i].setType(Constants.WatermarkSourceType.LITERA);

Configure the text content, font path, and font size:

WatermarkLitera textWatermark = new WatermarkLitera();
textWatermark.setWmLitera("Agora Watermark Example");
textWatermark.setFontFilePath("path/to/font.ttf"); // Optional
textWatermark.setFontSize(24);

watermarks[i].setLiteraSource(textWatermark);

Add a timestamp watermark

To add a timestamp watermark:

Call enableAndUpdateVideoWatermarks() and pass the watermarkConfigs array.

Set the watermark type to TIMESTAMPS:

watermarks[i].setType(Constants.WatermarkSourceType.TIMESTAMPS);

Configure the font and size:

WatermarkTimestamp timestamp = new WatermarkTimestamp();
timestamp.setFontFilePath("path/to/font.ttf"); // Optional
timestamp.setFontSize(20);

watermarks[i].setTimestampSource(timestamp);

Add an image watermark

To add an image watermark:

Call enableAndUpdateVideoWatermarks() and pass the watermarkConfigs array.

Set the watermark type to PICTURE:

watermarks[i].setType(Constants.WatermarkSourceType.PICTURE);

Set the image path:

watermarks[i].setImageUrl("path/to/watermark.png");

Set the watermark position

You can set watermark positions using either absolute pixels or relative ratios. You can also define separate positions for portrait and landscape orientations.

Fixed position (pixels)

Portrait mode

WatermarkOptions options = new WatermarkOptions();
options.setMode(Constants.WatermarkFitMode.FIT_MODE_COVER_POSITION);
options.setZOrder(1);

Rectangle portrait = new Rectangle();
portrait.setX(50);
portrait.setY(50);
portrait.setWidth(200);
portrait.setHeight(100);

options.setPositionInPortraitMode(portrait);
watermarks[i].setOptions(options);

Landscape mode

Rectangle landscape = new Rectangle();
landscape.setX(50);
landscape.setY(50);
landscape.setWidth(200);
landscape.setHeight(100);

options.setPositionInLandscapeMode(landscape);
watermarks[i].setOptions(options);

Relative position (ratios)

WatermarkOptions options = new WatermarkOptions();
options.setMode(Constants.WatermarkFitMode.FIT_MODE_USE_IMAGE_RATIO);
options.setZOrder(1);

WatermarkRatio ratio = new WatermarkRatio();
ratio.setXRatio(0.5);
ratio.setYRatio(0.5);
ratio.setWidthRatio(0.6);

options.setWatermarkRatio(ratio);
watermarks[i].setOptions(options);

Complete sample

Full example for adding watermarks

if (recorderConfig.getWaterMark() != null && !recorderConfig.getWaterMark().isEmpty()) {
  WatermarkConfig[] watermarks = new WatermarkConfig[recorderConfig.getWaterMark().size()];

  for (int i = 0; i < watermarks.length; i++) {
    WatermarkInfo info = recorderConfig.getWaterMark().get(i);
    watermarks[i] = new WatermarkConfig();
    watermarks[i].setIndex(i + 1);

    WatermarkSourceType type = Utils.convertToWatermarkSourceType(info.getType());
    watermarks[i].setType(type);

    if (type == WatermarkSourceType.LITERA) {
      WatermarkLitera litera = new WatermarkLitera();
      litera.setWmLitera(info.getLitera());
      litera.setFontFilePath(info.getFontFilePath());
      litera.setFontSize(info.getFontSize());
      watermarks[i].setLiteraSource(litera);

    } else if (type == WatermarkSourceType.TIMESTAMPS) {
      WatermarkTimestamp timestamp = new WatermarkTimestamp();
      timestamp.setFontFilePath(info.getFontFilePath());
      timestamp.setFontSize(info.getFontSize());
      watermarks[i].setTimestampSource(timestamp);

    } else if (type == WatermarkSourceType.PICTURE) {
      watermarks[i].setImageUrl(info.getImgUrl());
    }

    WatermarkOptions options = new WatermarkOptions();
    options.setMode(Constants.WatermarkFitMode.FIT_MODE_COVER_POSITION);
    options.setZOrder(info.getZorder());

    Rectangle portrait = new Rectangle();
    portrait.setX(info.getX());
    portrait.setY(info.getY());
    portrait.setWidth(info.getWidth());
    portrait.setHeight(info.getHeight());

    Rectangle landscape = new Rectangle();
    landscape.setX(info.getX());
    landscape.setY(info.getY());
    landscape.setWidth(info.getWidth());
    landscape.setHeight(info.getHeight());

    options.setPositionInPortraitMode(portrait);
    options.setPositionInLandscapeMode(landscape);
    watermarks[i].setOptions(options);
  }

  agoraMediaRtcRecorder.enableAndUpdateVideoWatermarks(watermarks);
}

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Add watermark to recordings

Understand the tech

Prerequisites

Implementation

Add a text watermark

Add a timestamp watermark

Add an image watermark

Set the watermark position

Fixed position (pixels)

Relative position (ratio)

Complete sample

Reference

API references

Understand the tech

Prerequisites

Implementation

Add a text watermark

Add a timestamp watermark

Add an image watermark

Set the watermark position

Fixed position (pixels)

Relative position (ratios)

Complete sample

Reference

API references

Contact Us

Contact Us