# 直播水印 (/zh-CN/api-reference/rtc/android/4.6.0/video/pre-and-post-processing/watermark)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## addVideoWatermark [1/3] [#addvideowatermark-13]
向本地视频添加水印图像。
```java
public abstract int addVideoWatermark(AgoraImage watermark)
```
#### `废弃` [#废弃]
自 v2.9.1 版本废弃,请改用 [addVideoWatermark [3/3]](/zh-CN/api-reference/rtc/android/video/pre-and-post-processing/watermark#api_irtcengine_addvideowatermark3)。
该方法在直播场景中向本地视频流添加 PNG 格式的水印图像。频道内的所有用户(包括 CDN 观众)以及视频采集设备都可以看到并采集该水印图像。如果你只想向 CDN 推流添加水印,请使用 [startRtmpStreamWithTranscoding](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengine_startrtmpstreamwithtranscoding) 方法。
注:
- 本地视频和 CDN 推流中 URL 的含义不同:在本地视频流中,URL 指的是添加的水印图像文件在本地视频流中的绝对路径;在 CDN 推流中,URL 指的是添加的水印图像在 CDN 推流中的 URL 地址。
- 水印图像的源文件必须为 PNG 格式。如果 PNG 文件的宽高与该方法中的设置不一致,SDK 会对 PNG 文件进行裁剪以符合设置。
- SDK 仅支持在本地视频或 CDN 推流中添加一张水印图像。新添加的水印图像会替换之前的图像。
### 参数 [#参数]
#### `watermark` [#watermark]
要添加到本地直播中的水印图像。详见 [AgoraImage](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcimage)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## addVideoWatermark [2/3] [#addvideowatermark-23]
向本地视频添加水印图像。
```java
public abstract int addVideoWatermark(String watermarkUrl, WatermarkOptions options)
```
#### `废弃` [#废弃-1]
自 v4.6.0 版本废弃,请改用 [addVideoWatermark [3/3]](/zh-CN/api-reference/rtc/android/video/pre-and-post-processing/watermark#api_irtcengine_addvideowatermark3) 方法。
该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印后,频道中的所有观众(包括 CDN 观众)以及采集设备都可以看到并采集到该水印图像。声网 SDK 每个直播视频流仅支持添加一张水印图像,新添加的水印会替换之前的图像。 水印图像的位置依赖于 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法中的设置:
- 如果编码视频的方向模式(ORIENTATION_MODE )为固定横屏模式或自适应横屏模式,则水印使用横屏方向。
- 如果编码视频的方向模式为固定竖屏模式或自适应竖屏模式,则水印使用竖屏方向。
- 设置水印位置时,区域必须小于 setVideoEncoderConfiguration 方法中设置的尺寸,否则水印图像会被裁剪。
你可以通过设置 `visibleInPreview` 参数控制预览时水印的可见性。但其最终是否生效还取决于调用 [setupLocalVideo](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setuplocalvideo) 时设置的 `position` 参数(视频帧在视频链路中的位置):
- 观察位置 VIDEO_MODULE_POSITION_POST_CAPTURER (默认): visiblePreview 为 true,则水印可见; visiblePreview 为 false,则水印不可见。
- 观察位置 VIDEO_MODULE_POSITION_PRE_ENCODER: visiblePreview 为 true,则水印可见; visiblePreview 为 false,则水印仍可见。
注:
- 请确保在调用该方法前已调用 enableVideo。
- 如果你只想为媒体推流添加水印,可以调用该方法或 startRtmpStreamWithTranscoding 方法。
- 该方法仅支持添加 PNG 文件格式的水印图像。支持的 PNG 图像像素格式包括 RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果 PNG 图像的尺寸与该方法中的设置不一致,图像将被裁剪或缩放以符合设置。
- 如果你为本地视频启用了镜像模式,则本地视频中的水印也会被镜像。为避免水印被镜像,声网建议不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。
### 参数 [#参数-1]
#### `watermarkUrl` [#watermarkurl]
要添加的水印图像的本地文件路径。支持使用本地绝对路径或相对路径。
#### `options` [#options]
水印图像的相关设置。详见 [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## addVideoWatermark [3/3] [#addvideowatermark-33]
向本地视频流添加水印图像。
```java
public abstract int addVideoWatermark(WatermarkConfig config);
```
#### `自从` [#自从]
自 v4.6.0 版本新增。
你可以使用该方法通过 [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig) 配置,在本地视频流中叠加水印图像,包括设置水印在预览中的位置、大小和可见性。
### 参数 [#参数-2]
#### `config` [#config]
水印配置。详见 [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## addVideoWatermarkEx [1/2] [#addvideowatermarkex-12]
向本地视频添加水印图像。
```java
public abstract int addVideoWatermarkEx(String watermarkUrl, WatermarkOptions options, RtcConnection connection)
```
#### `废弃` [#废弃-2]
自 v4.6.0 版本废弃,请改用 [addVideoWatermarkEx [2/2]](/zh-CN/api-reference/rtc/android/video/pre-and-post-processing/watermark#api_irtcengineex_addvideowatermarkex1) 方法。
该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印图像后,频道中的所有观众(包括 CDN 观众)以及采集设备都可以看到并采集该图像。声网 SDK 仅支持在一个直播视频流中添加一张水印图像,新添加的水印图像会替换之前的图像。 水印图像的坐标依赖于 [setVideoEncoderConfigurationEx](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 方法中的设置:
- 如果编码视频的方向模式(ORIENTATION_MODE )为固定横屏模式或自适应横屏模式,则水印使用横屏方向。
- 如果编码视频的方向模式为固定竖屏模式或自适应竖屏模式,则水印使用竖屏方向。
- 设置水印位置时,区域必须小于 setVideoEncoderConfigurationEx 方法中设置的尺寸,否则水印图像会被裁剪。
注:
- 请确保在调用该方法前已调用 enableVideo 方法。
- 该方法仅支持添加 PNG 文件格式的水印图像。支持的 PNG 图像像素格式包括 RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果 PNG 图像的尺寸与该方法中的设置不一致,图像将被裁剪或缩放以符合设置。
- 如果你已通过调用 startPreview 方法启用了本地视频预览,可以使用 visibleInPreview 成员设置水印在预览中是否可见。
- 如果你为本地视频启用了镜像模式,则本地视频中的水印也会被镜像。为避免水印被镜像,声网建议不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。
### 适用场景 [#适用场景]
该方法适用于多频道场景。
### 参数 [#参数-3]
#### `watermarkUrl` [#watermarkurl-1]
要添加的水印图像的本地文件路径。支持使用本地绝对路径或相对路径。
#### `options` [#options-1]
水印图像的相关设置。详见 [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)。
#### `connection` [#connection]
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex)
## addVideoWatermarkEx [2/2] [#addvideowatermarkex-22]
向本地视频添加水印图像。
```java
public abstract int addVideoWatermarkEx(WatermarkConfig config, RtcConnection connection);
```
#### `自从` [#自从-1]
自 v4.6.0 版本新增。
### 适用场景 [#适用场景-1]
该方法适用于多频道场景。
### 参数 [#参数-4]
#### `config` [#config-1]
水印配置。详见 [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig)。
#### `connection` [#connection-1]
[RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection) 对象。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex)
## clearVideoWatermarkEx [#clearvideowatermarkex]
从视频流中移除水印图像。
```java
public abstract int clearVideoWatermarkEx(RtcConnection connection);
```
### 适用场景 [#适用场景-2]
该方法适用于多频道场景。
### 参数 [#参数-5]
#### `connection` [#connection-2]
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex)
## clearVideoWatermarks [#clearvideowatermarks]
从视频流中移除水印图像。
```java
public abstract int clearVideoWatermarks();
```
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## getBuffer [#getbuffer]
获取水印图像的数据缓冲区。
```java
public ByteBuffer getBuffer()
```
#### `自从` [#自从-2]
自 v4.6.0 版本新增。
### 返回值 [#返回值-7]
方法调用成功时,返回包含水印图像数据的 `ByteBuffer` 对象。
### 所属接口类 [#所属接口类-7]
- [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer)
## getFormat [#getformat]
获取水印图像的格式。
```java
public int getFormat()
```
#### `自从` [#自从-3]
自 v4.6.0 版本新增。
### 返回值 [#返回值-8]
方法调用成功,返回水印图像缓冲区的格式。
### 所属接口类 [#所属接口类-8]
- [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer)
## getHeight [#getheight]
获取水印图像的高度。
```java
public int getHeight()
```
#### `自从` [#自从-4]
自 v4.6.0 版本新增。
### 返回值 [#返回值-9]
方法调用成功,返回水印图像的高度,单位为像素。
### 所属接口类 [#所属接口类-9]
- [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer)
## getId [#getid]
获取水印的唯一标识符。
```java
public String getId()
```
#### `自从` [#自从-5]
自 v4.6.0 版本新增。
用于从 [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer) 或 [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig) 实例中获取水印的唯一标识符。
### 返回值 [#返回值-10]
- 方法调用成功时,返回水印的唯一标识符。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-10]
- [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer)
## getImageUrl [#getimageurl]
获取水印图像的 URL。
```java
public String getImageUrl()
```
#### `自从` [#自从-6]
自 v4.6.0 版本新增。
### 返回值 [#返回值-11]
- 方法调用成功时,返回水印图像的 URL。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-11]
- [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig)
## getPositionInLandscapeMode [#getpositioninlandscapemode]
获取横屏模式下水印的位置。
```java
public int[] getPositionInLandscapeMode()
```
#### `自从` [#自从-7]
自 v4.6.0 版本新增。
### 返回值 [#返回值-12]
方法调用成功,返回一个包含四个元素的整数数组,依次表示水印矩形的 x、y、宽度和高度。
### 所属接口类 [#所属接口类-12]
- [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)
## getPositionInPortraitMode [#getpositioninportraitmode]
获取竖屏模式下水印的位置。
```java
public int[] getPositionInPortraitMode()
```
#### `自从` [#自从-8]
自 v4.6.0 版本新增。
### 返回值 [#返回值-13]
方法调用成功,返回一个包含四个元素的整数数组,分别表示水印矩形的 x、y、宽度和高度。
### 所属接口类 [#所属接口类-13]
- [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)
## getType [#gettype]
获取当前水印配置中的水印类型信息。
```java
public int getType()
```
#### `自从` [#自从-9]
自 v4.6.0 版本新增。
### 返回值 [#返回值-14]
方法调用成功,返回水印类型:
- WATERMARK_TYPE_IMAGE:图片水印。
- WATERMARK_TYPE_BUFFER:Buffer 水印。
### 所属接口类 [#所属接口类-14]
- [WatermarkConfig](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkconfig)
## getWidth [#getwidth]
获取水印图像的宽度。
```java
public int getWidth()
```
#### `自从` [#自从-10]
自 v4.6.0 版本新增。
### 返回值 [#返回值-15]
方法调用成功,返回水印图像的宽度,单位为像素。
### 所属接口类 [#所属接口类-15]
- [WatermarkBuffer](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkbuffer)
## getzOrder [#getzorder]
获取水印图像的 Z-order 索引。
```java
public int getzOrder()
```
#### `自从` [#自从-11]
自 v4.6.0 版本新增。
### 返回值 [#返回值-16]
方法调用成功,返回水印图像的 Z-order 索引。
### 所属接口类 [#所属接口类-16]
- [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)
## isVisibleInPreview [#isvisibleinpreview]
检查水印在本地视频预览中是否可见。
```java
public boolean isVisibleInPreview()
```
#### `自从` [#自从-12]
自 v4.6.0 版本新增。
### 返回值 [#返回值-17]
- true:水印在本地视频预览中可见。
- false:水印在本地视频预览中不可见。
### 所属接口类 [#所属接口类-17]
- [WatermarkOptions](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-watermarkoptions)
## removeVideoWatermark [#removevideowatermark]
从本地视频中移除水印图像。
```java
public abstract int removeVideoWatermark(String id);
```
#### `自从` [#自从-13]
自 v4.6.0 版本新增。
该方法使用指定的唯一 ID,从本地视频流中移除之前添加的水印图像。
### 参数 [#参数-6]
#### `id` [#id]
要移除的水印图像的 ID。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## removeVideoWatermarkEx [#removevideowatermarkex]
从本地或远端视频流中移除指定的水印图像。
```java
public abstract int removeVideoWatermarkEx(String id, RtcConnection connection);
```
#### `自从` [#自从-14]
自 v4.6.0 版本新增。
### 适用场景 [#适用场景-3]
该方法适用于多频道场景。
### 参数 [#参数-7]
#### `id` [#id-1]
要移除的水印图像的 ID。
#### `connection` [#connection-3]
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-rtcconnection)。
### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [RtcEngineEx](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineex)