Agora Video Watermark

This package provides video watermark feature for Agora Web SDK.

Requirements

• Agora Web SDK (v4.24.0 or later)

Usage

Install packages agora-rtc-sdk-ng and agora-extension-video-watermark, then import these packages in your code:

import AgoraRTC from "agora-rtc-sdk-ng";
import { VideoWatermarkExtension, AgoraWatermarkImage } from "agora-extension-video-watermark";
import type { IVWProcessor } from "agora-extension-video-watermark";

Process video track(s) with VideoWatermarkProcessor:

Create an extension instance and register it:

const extension = new VideoWatermarkExtension();
AgoraRTC.registerExtensions([extension]);

Once you have a video track (ILocalVideoTrack or IRemoteVideoTrack), create a processor and pipe it to track:

const processor = extension.createProcessor();
track.pipe(processor).pipe(track.processorDestination);

Add watermark to the processor by creating an AgoraWatermarkImage instance:

const image = document.getElementById('image');
const watermark = new AgoraWatermarkImage(image);
processor.addVideoWatermark(watermark);

Enable or disable the processor:

const enable = async () => {
  const enabled = processor.enabled;
  if (!enabled) {
    await processor.enable();
  }
};
const disable = async () => {
  const enabled = processor.enabled;
  if (enabled) {
    await processor.disable();
  }
};

Unpipe and release the processor when it is not longer in use:

const release = async () => {
  processor.unpipe();
  track.unpipe();
  track.pipe(track.processorDestination);
  await processor.release();
}

Creating AgoraWatermarkImage instance(s):

Option 1: Using an existing HTMLImageElement

If you already have an image element in your DOM (e.g., from an <img> tag), you can directly use it:

const image = document.getElementById('image');
const watermark = new AgoraWatermarkImage(image);

constructor(
  image: HTMLImageElement | null,
  x?: number,
  y?: number,
  width?: number,
  height?: number,
  alpha?: number
)

Option 2: Using an image URL (asynchronous)

You can also create a watermark from an image URL. This approach loads the image asynchronously, so you must await the .ready promise before using it:

const watermark = new AgoraWatermarkImage('https://example.com/image.png');
await watermark.ready;
processor.addVideoWatermark(watermark);

constructor(
  url: string | null,
  x?: number,
  y?: number,
  width?: number,
  height?: number,
  alpha?: number
)

Constructor Parameters:
image: The HTMLImageElement to be used as the watermark. If null, no image will be used.
url: URL of the image to be used as a watermark. If null or an empty string, no image will be used.

x: The x-coordinate (in pixels) for the image position on the video, relative to the top-left corner. Default is 0.
y: The y-coordinate (in pixels) for the image position on the video, relative to the top-left corner. Default is 0.
width: The desired width (in pixels) of the watermark image. Default is -1, which means the image's own width will be used after it loads.
height: The desired height (in pixels) of the watermark image. Default is -1, which means the image's own height will be used after it loads.
alpha: Image opacity, from 0.0 (fully transparent) to 1.0 (fully opaque). Default is 1.0.

Attributes:
ready:: A Promise that resolves when the watermark image is loaded (if url is used).
imageReady:: A boolean indicating whether the watermark is ready to be used.

Notes:

• If url is used, image will be loaded asynchronously. You must await the .ready promise before using the watermark. If width and height are set to -1, they will be set to the image's own width and height after it loads.
• Loading from url may fail due to Cross-Origin Resource Policy (CORP) restrictions. In the case where image failed to load from url, the ready Promise will be rejected with an error.

Refer to Agora Docs for further details.

© Copyright Agora, Inc.