# 使用水印插件 (Beta) (/zh-CN/realtime-media/rtc/build/extensions/web/watermark) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 使用水印插件(Beta 版) [#使用水印插件beta-版] 水印插件可以与 Web SDK (v4.24.0 或以上) 搭配使用,用于在视频流中添加图像水印。 该插件支持自定义水印的位置、大小、透明度等属性,可以应用于本地视频轨道和远端视频轨道。 ## 实现原理 [#实现原理] 声网 Web SDK 的媒体传输管道包含采集、前处理、编码、传输、解码、后处理和播放等环节。在前处理阶段,插件可以对管道中的音视频数据进行处理,从而实现虚拟背景、降噪、美颜、语音活动检测等功能。 ## 前提条件 [#前提条件] 使用水印插件需要满足以下前提条件: - 使用最新版本的桌面端 Chrome(87 及以上)、Edge、Firefox 浏览器。 - 已集成 v4.24.0 或以上版本的 Web SDK,实现基础的实时音视频互动功能,具体参考[快速开始](../../../get-started/quick-start?platform=web)文档。 ## 实现步骤 [#实现步骤] 按照以下步骤集成水印插件并实现视频水印功能。 ### 1. 集成插件 [#1-集成插件] 通过 npm 将水印插件 [agora-extension-video-watermark](https://www.npmjs.com/package/agora-extension-video-watermark) 集成到你的项目中。 1. 运行以下命令安装水印插件: ```shell npm install agora-extension-video-watermark ``` 2. 在你的 TypeScript 文件中加入以下代码导入水印模块: ```typescript import AgoraRTC from "agora-rtc-sdk-ng"; import { VideoWatermarkExtension, AgoraWatermarkImage } from "agora-extension-video-watermark"; import type { IVWProcessor } from "agora-extension-video-watermark"; ``` ### 2. 注册插件 [#2-注册插件] 调用 `AgoraRTC.registerExtensions` 方法并传入创建的 `VideoWatermarkExtension` 实例注册水印插件。 :::warning[注意] 声网推荐你只创建一个 `VideoWatermarkExtension` 实例。 ::: ```typescript import AgoraRTC from "agora-rtc-sdk-ng"; import { VideoWatermarkExtension } from "agora-extension-video-watermark"; // 创建 VideoWatermarkExtension 实例 const extension = new VideoWatermarkExtension(); // 注册插件 AgoraRTC.registerExtensions([extension]); ``` ### 3. 开启插件 [#3-开启插件] 按照以下步骤开启水印插件: 1. 调用 `createProcessor` 方法创建一个 `IVWProcessor` 实例。 ```typescript // 创建 IVWProcessor 实例 const processor = extension.createProcessor(); ``` 2. 调用 SDK 的 `pipe` 方法并指定 `processorDestination` 属性,将插件注入视频处理管道。 ```typescript // 创建视频轨道(本地或远端) const videoTrack = await AgoraRTC.createCameraVideoTrack(); // 将插件注入视频处理管道 videoTrack.pipe(processor).pipe(videoTrack.processorDestination); ``` ### 4. 添加水印 [#4-添加水印] 水印插件支持两种方式创建水印图像: #### 方式一:使用现有的 HTMLImageElement [#方式一使用现有的-htmlimageelement] 如果你已经在 DOM 中有一个图像元素(例如来自 `` 标签),可以直接使用: ```typescript const image = document.getElementById('watermark-image') as HTMLImageElement; const watermark = new AgoraWatermarkImage( image, 10, // x 坐标 10, // y 坐标 100, // 宽度 50, // 高度 0.8 // 透明度 (0.0-1.0) ); // 添加水印到处理器 processor.addVideoWatermark(watermark); ``` #### 方式二:使用图像 URL(异步) [#方式二使用图像-url异步] 你也可以通过图像 URL 创建水印。这种方式会异步加载图像,因此必须等待 `.ready` Promise 完成后才能使用: ```typescript const watermark = new AgoraWatermarkImage( 'https://example.com/watermark.png', 10, // x 坐标 10, // y 坐标 100, // 宽度(-1 表示使用图像原始宽度) 50, // 高度(-1 表示使用图像原始高度) 0.8 // 透明度 (0.0-1.0) ); // 等待图像加载完成 await watermark.ready; // 添加水印到处理器 processor.addVideoWatermark(watermark); ``` :::warning[注意] - 使用 URL 加载图像时,可能会因为 [跨域资源策略 (CORP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cross-Origin_Resource_Policy) 限制而失败。如果图像加载失败,`ready` Promise 将被拒绝并返回错误。 - 如果 `width` 和 `height` 设置为 -1,它们将在图像加载后设置为图像的原始宽度和高度。 ::: ### 5. 启用处理器 [#5-启用处理器] 添加水印后,调用 `enable` 方法启用处理器: ```typescript const enable = async () => { const enabled = processor.enabled; if (!enabled) { await processor.enable(); } }; await enable(); ``` ### 6. 管理水印 [#6-管理水印] 你可以动态地启用或禁用水印处理器: ```typescript // 启用水印 const enable = async () => { const enabled = processor.enabled; if (!enabled) { await processor.enable(); } }; // 禁用水印 const disable = async () => { const enabled = processor.enabled; if (enabled) { await processor.disable(); } }; ``` ### 7. 释放资源 [#7-释放资源] 当不再需要使用水印插件时,需要正确释放资源: ```typescript const release = async () => { // 取消管道连接 processor.unpipe(); videoTrack.unpipe(); // 重新连接到原始目标 videoTrack.pipe(videoTrack.processorDestination); // 释放处理器资源 await processor.release(); }; await release(); ``` ## 完整示例 [#完整示例] 以下是一个完整的水印插件使用示例: ```typescript import AgoraRTC from "agora-rtc-sdk-ng"; import { VideoWatermarkExtension, AgoraWatermarkImage } from "agora-extension-video-watermark"; import type { IVWProcessor } from "agora-extension-video-watermark"; // 创建并注册水印插件 const extension = new VideoWatermarkExtension(); AgoraRTC.registerExtensions([extension]); // 创建处理器 const processor = extension.createProcessor(); async function setupWatermark() { try { // 创建视频轨道 const videoTrack = await AgoraRTC.createCameraVideoTrack(); // 将插件注入视频处理管道 videoTrack.pipe(processor).pipe(videoTrack.processorDestination); // 创建水印(使用 URL 方式) const watermark = new AgoraWatermarkImage( 'https://example.com/logo.png', 20, // x 坐标 20, // y 坐标 120, // 宽度 60, // 高度 0.7 // 透明度 ); // 等待水印图像加载完成 await watermark.ready; // 添加水印到处理器 processor.addVideoWatermark(watermark); // 启用处理器 await processor.enable(); console.log("水印插件已成功启用"); // 播放视频轨道 videoTrack.play("video-container"); } catch (error) { console.error("设置水印时出错:", error); } } // 清理资源的函数 async function cleanup() { try { await processor.disable(); processor.unpipe(); videoTrack.unpipe(); videoTrack.pipe(videoTrack.processorDestination); await processor.release(); console.log("资源已清理"); } catch (error) { console.error("清理资源时出错:", error); } } // 调用设置函数 setupWatermark(); ``` ## API 参考 [#api-参考] 本节提供水印插件的核心 API 参考。 ### addVideoWatermark [#addvideowatermark] ```typescript addVideoWatermark(watermark: AgoraWatermarkImage): number; ``` 向视频流添加水印图像。 **参数:** - `watermark`:`AgoraWatermarkImage` 实例。 **返回值:** 返回水印的 ID 表示标识,用于后续水印管理。如果返回 -1,则表示添加失败。 ### clearVideoWatermarks [#clearvideowatermarks] ```typescript clearVideoWatermarks(): boolean; ``` 删除所有已添加的视频水印。 **返回值:** - `true`:成功删除所有水印。 - `false`:删除失败。 ### removeVideoWatermark [#removevideowatermark] ```typescript removeVideoWatermark(id: number): boolean; ``` 根据水印的 ID 删除指定的视频水印。 **参数:** - `id`:要删除的水印 ID。 **返回值:** - `true`:成功删除指定水印。 - `false`:删除失败。 ### release [#release] ```typescript release(): Promise; ``` 释放 `IVWProcessor` 资源。 ### AgoraWatermarkImage [#agorawatermarkimage] ```typescript 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; public imageReady: boolean = false; } ``` **参数:** - `image`:用作水印的 HTMLImageElement。如果为 `null`,则不使用图像。 - `url`:用作水印的图像 URL。如果为 `null` 或空字符串,则不使用图像。 - `x`:图像在视频上的 x 坐标(像素),相对于左上角。默认为 0。 - `y`:图像在视频上的 y 坐标(像素),相对于左上角。默认为 0。 - `width`:水印图像的期望宽度(像素)。默认为 -1,表示使用图像加载后的原始宽度。 - `height`:水印图像的期望高度(像素)。默认为 -1,表示使用图像加载后的原始高度。 - `alpha`:图像不透明度,从 0.0(完全透明)到 1.0(完全不透明)。默认为 1.0。