Watermark (Beta)

The Watermark extension works with Web SDK v4.24.0 or later to add image watermarks to video streams. The extension supports customizable watermark properties such as position, size, and transparency, and can be applied to both local and remote video tracks.

Understand the tech

The Watermark extension integrates into the Web SDK's video processing pipeline to overlay images onto video streams in real-time. When enabled, the extension processes each video frame by compositing the watermark image at the specified position with the configured transparency level.

Prerequisites

To use the Watermark extension, ensure that:

You are using the latest version of Chrome (recommended), Edge, or Firefox desktop browser.
You have implemented the SDK quickstart in your project using the Web SDK version 4.24.0 or later.

Implementation

Follow these steps to integrate the Watermark extension and add watermarks to your video streams.

Integrate the extension

Use npm to integrate the agora-extension-video-watermark package into your project.

Install the Watermark extension:

_1npm install agora-extension-video-watermark
Import the watermark module in your .js file:

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

Register the extension

Call AgoraRTC.registerExtensions and pass the created VideoWatermarkExtension instance to register the Watermark extension.

Note

Agora recommends creating only one VideoWatermarkExtension instance.

import AgoraRTC from "agora-rtc-sdk-ng";
import { VideoWatermarkExtension } from "agora-extension-video-watermark";
// Create VideoWatermarkExtension instance
const extension = new VideoWatermarkExtension();
// Register the extension
AgoraRTC.registerExtensions([extension]);

Enable the extension

Follow these steps to enable the Watermark extension:

Call createProcessor to create an IVWProcessor instance:

_2// Create IVWProcessor instance _2const processor = extension.createProcessor();
Call the SDK's pipe method and specify the processorDestination property to inject the extension into the video processing pipeline:

_4// Create a video track (local or remote) _4const videoTrack = await AgoraRTC.createCameraVideoTrack(); _4// Inject the extension into the video processing pipeline _4videoTrack.pipe(processor).pipe(videoTrack.processorDestination);

Add watermarks

The Watermark extension supports two methods for creating watermark images:

Use an existing HTMLImageElement

If you already have an image element in the DOM (for example, from an <img> tag), you can use it directly:

_12 const image = document.getElementById('watermark-image') as HTMLImageElement; _12 const watermark = new AgoraWatermarkImage( _12 image, _12 10, // x coordinate _12 10, // y coordinate _12 100, // width _12 50, // height _12 0.8 // opacity (0.0-1.0) _12 ); _12 _12 // Add watermark to processor _12 processor.addVideoWatermark(watermark);
Use an image URL (asynchronous)

You can also create a watermark from an image URL. This method loads the image asynchronously, so you must wait for the .ready Promise to complete before use:

_14 const watermark = new AgoraWatermarkImage( _14 'https://example.com/watermark.png', _14 10, // x coordinate _14 10, // y coordinate _14 100, // width (-1 uses original image width) _14 50, // height (-1 uses original image height) _14 0.8 // opacity (0.0-1.0) _14 ); _14 _14 // Wait for image to load _14 await watermark.ready; _14 _14 // Add watermark to processor _14 processor.addVideoWatermark(watermark);
Note
- When loading images from URLs, the operation may fail due to Cross-Origin Resource Policy (CORP) restrictions. If image loading fails, the ready Promise is rejected with an error.
- To use the original image dimensions, set both width and height to -1.

Enable the processor

After adding watermarks, call enable to activate the processor:

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

Manage watermarks

You can dynamically enable or disable the watermark as follows:

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

Release resources

When you no longer need the Watermark extension, properly release resources:

const release = async () => {
  // Unpipe connections
  processor.unpipe();
  videoTrack.unpipe();
  
  // Reconnect to original destination
  videoTrack.pipe(videoTrack.processorDestination);
  
  // Release processor resources
  await processor.release();
};
await release();

Complete sample code

The following example demonstrates complete usage of the Watermark extension:

Sample code

import AgoraRTC from "agora-rtc-sdk-ng";
import { VideoWatermarkExtension, AgoraWatermarkImage } from "agora-extension-video-watermark";
import type { IVWProcessor } from "agora-extension-video-watermark";
// Create and register Watermark extension
const extension = new VideoWatermarkExtension();
AgoraRTC.registerExtensions([extension]);
// Create processor
const processor = extension.createProcessor();
async function setupWatermark() {
  try {
    // Create video track
    const videoTrack = await AgoraRTC.createCameraVideoTrack();
    
    // Inject extension into video processing pipeline
    videoTrack.pipe(processor).pipe(videoTrack.processorDestination);
    
    // Create watermark (using URL method)
    const watermark = new AgoraWatermarkImage(
      'https://example.com/logo.png',
      20,   // x coordinate
      20,   // y coordinate
      120,  // width
      60,   // height
      0.7   // opacity
    );
    
    // Wait for watermark image to load
    await watermark.ready;
    
    // Add watermark to processor
    processor.addVideoWatermark(watermark);
    
    // Enable processor
    await processor.enable();
    
    console.log("Watermark extension successfully enabled");
    
    // Play video track
    videoTrack.play("video-container");
    
  } catch (error) {
    console.error("Error setting up watermark:", error);
  }
}
// Cleanup function
async function cleanup() {
  try {
    await processor.disable();
    processor.unpipe();
    videoTrack.unpipe();
    videoTrack.pipe(videoTrack.processorDestination);
    await processor.release();
    console.log("Resources cleaned up");
  } catch (error) {
    console.error("Error cleaning up resources:", error);
  }
}
// Call setup function
setupWatermark();

addVideoWatermark(watermark: AgoraWatermarkImage): number;

Parameters

watermark: An AgoraWatermarkImage instance.

Returns

The watermark ID for subsequent watermark management. Returns -1 if the operation fails.

clearVideoWatermarks

Removes all added video watermarks.

clearVideoWatermarks(): boolean;

Returns

true: Successfully removed all watermarks.
false: Failed to remove watermarks.

removeVideoWatermark

Removes a specific video watermark by ID.

removeVideoWatermark(id: number): boolean;

Parameters

id: The ID of the watermark to remove.

Returns

true: Successfully removed the specified watermark.
false: Failed to remove the watermark.

release

Releases the IVWProcessor resources.

release(): Promise<void>;

AgoraWatermarkImage

Creates a watermark image instance.

export class AgoraWatermarkImage {
  public image: HTMLImageElement | null;
  public x: number;
  public y: number;
  public width: number;
  public height: number;
  public alpha: number;
  public ready: Promise<void>;
  public imageReady: boolean = false;
}

Parameters

image: The HTMLImageElement to use as the watermark. If null, no image is used.
url: The image URL to use as the watermark. If null or an empty string, no image is used.
x: The x-coordinate (in pixels) of the image on the video, relative to the top-left corner. Default is 0.
y: The y-coordinate (in pixels) of the image 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 uses the original width after the image loads.
height: The desired height (in pixels) of the watermark image. Default is -1, which uses the original height after the image loads.
alpha: The image opacity, from 0.0 (completely transparent) to 1.0 (completely opaque). Default is 1.0.

Watermark (Beta)

Understand the tech

Prerequisites

Implementation

Integrate the extension

Register the extension

Enable the extension

Add watermarks

Enable the processor

Manage watermarks

Release resources

Complete sample code

Reference

API reference

addVideoWatermark

clearVideoWatermarks

removeVideoWatermark

release

AgoraWatermarkImage