# 直播水印 (/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## addVideoWatermark: [#addvideowatermark]
向本地视频添加水印图像。
```objc
- (int)addVideoWatermark:(AgoraImage * _Nonnull)watermark NS_SWIFT_NAME(addVideoWatermark(_:)) __deprecated_msg("use addVideoWatermarkWithConfig:config instead.");
```
:::error[废弃]
自 v4.5.0 版本废弃,请改用 [addVideoWatermarkWithConfig:](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3)。
:::
该方法在直播场景中向本地视频流添加 PNG 格式的水印图像。添加水印图像后,频道内的所有用户(包括 CDN 观众)以及视频采集设备都可以看到并采集该图像。如果你只想向 CDN 推流添加水印,请参见 `startRtmpStreamWithTranscoding:` 方法。
:::note
注:
- 本地视频和 CDN 推流中 URL 的含义不同:在本地视频流中,URL 指的是添加的水印图像文件在本地视频流中的绝对路径;在 CDN 推流中,URL 指的是添加的水印图像在 CDN 推流中的 URL 地址。
- 水印图像的源文件必须为 PNG 格式。如果 PNG 文件的宽高与该方法中的设置不一致,SDK 会裁剪该文件以符合设置。
- SDK 仅支持在本地视频或 CDN 推流中添加一个水印图像。新添加的水印图像会替换之前的图像。
:::
### 参数 [#参数]
要添加到本地直播中的水印图像。详见 [AgoraImage](/zh-CN/api-reference/rtc/ios/class-rtcimage)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## addVideoWatermark\:options: [#addvideowatermarkoptions]
向本地视频添加水印图像。
```objc
- (int)addVideoWatermark:(NSURL* _Nonnull)url options:(WatermarkOptions* _Nonnull)options NS_SWIFT_NAME(addVideoWatermark(_:options:)) __deprecated_msg("use addVideoWatermarkWithConfig:config instead.");
```
:::error[废弃]
自 v4.5.0 版本废弃,请改用 `addVideoWatermarkWithConfig:config`。
:::
该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印图像后,频道中的所有观众(包括 CDN 观众)以及采集设备都可以看到并采集该图像。声网 SDK 仅支持在一个直播视频流中添加一张水印图像,新添加的水印图像会替换之前的图像。
水印图像的坐标依赖于 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法中的设置:
- 如果编码视频的方向模式([AgoraVideoOutputOrientationMode](/zh-CN/api-reference/rtc/ios/enum-orientationmode))为固定横屏或自适应横屏模式,水印图像将使用横屏方向。
- 如果编码视频的方向模式为固定竖屏或自适应竖屏模式,水印图像将使用竖屏方向。
- 设置水印位置时,区域必须小于 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法中设置的尺寸,否则水印图像将被裁剪。
你可以通过调用该方法时设置 `visibleInPreview` 参数来控制水印在预览中的可见性。但其最终是否生效还取决于调用 [setupLocalVideo:](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setuplocalvideo) 时设置的 `position` 参数。:
- 观察位置 `AgoraVideoModulePositionPostCapture`(默认):`visiblePreview` 为 YES,则水印可见;`visiblePreview` 为 NO,则水印不可见。
- 观察位置 `AgoraVideoModulePositionPreEncoder`:`visiblePreview` 为 YES,则水印可见;`visiblePreview` 为 NO,则水印仍可见。
:::note
注:
- 请确保在调用该方法前已调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo)。
- 如果你只想为媒体推流添加水印,可以调用该方法或 [startRtmpStreamWithTranscoding\:transcoding:](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengine_startrtmpstreamwithtranscoding) 方法。
- 该方法仅支持添加 PNG 文件格式的水印图像。支持的 PNG 图像像素格式包括 RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果 PNG 图像的尺寸与该方法中的设置不一致,图像将被裁剪或缩放以符合设置。
- 如果你为本地视频启用了镜像模式,本地视频中的水印也会被镜像。为避免水印被镜像,声网建议你不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。
:::
### 参数 [#参数-1]
要添加的水印图像的本地文件路径。该方法支持使用本地的绝对路径或相对路径添加水印图像。
水印图像的相关选项。详见 [WatermarkOptions](/zh-CN/api-reference/rtc/ios/class-watermarkoptions)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## addVideoWatermarkWithConfig: [#addvideowatermarkwithconfig]
向本地视频添加水印图像。
```objc
- (int)addVideoWatermarkWithConfig:(WatermarkConfig* _Nonnull)config NS_SWIFT_NAME(addVideoWatermark(_:));
```
:::info[自从]
自 v4.6.0 版本新增。
:::
你可以使用此方法在本地视频流上叠加水印图像,并通过 [WatermarkConfig](/zh-CN/api-reference/rtc/ios/class-watermarkconfig) 配置水印的位置、大小以及在预览中的可见性。
### 参数 [#参数-2]
水印图像的配置。详见 [WatermarkConfig](/zh-CN/api-reference/rtc/ios/class-watermarkconfig)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## addVideoWatermarkEx\:options\:connection: [#addvideowatermarkexoptionsconnection]
向本地视频添加水印图像。
```objc
- (int)addVideoWatermarkEx:(NSURL* _Nonnull)url options:(WatermarkOptions* _Nonnull)options connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(addVideoWatermarkEx(_:options:connection:)) __deprecated_msg("use addVideoWatermark:config connection instead.");
```
:::error[废弃]
自 v4.5.0 版本废弃,请改用 `addVideoWatermark:config connection`。
:::
该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印图像后,频道中的所有观众(包括 CDN 观众)以及采集设备都可以看到并采集该图像。声网 SDK 仅支持在一个直播视频流中添加一张水印图像,新添加的水印图像会替换之前的图像。
水印图像的坐标依赖于 `setVideoEncoderConfigurationEx` 方法中的设置:
- 如果编码视频的方向模式([AgoraVideoOutputOrientationMode](/zh-CN/api-reference/rtc/ios/enum-orientationmode))为固定横屏或自适应横屏模式,水印图像将采用横屏方向。
- 如果编码视频的方向模式为固定竖屏或自适应竖屏模式,水印图像将采用竖屏方向。
- 设置水印位置时,区域必须小于 `setVideoEncoderConfigurationEx` 方法中设置的尺寸,否则水印图像将被裁剪。
:::note
注:
- 请确保你在调用该方法前已调用 [enableVideo](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_enablevideo)。
- 该方法仅支持添加 PNG 文件格式的水印图像。支持的 PNG 图像像素格式包括 RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果 PNG 图像的尺寸与该方法中的设置不一致,图像将被裁剪或缩放以符合设置。
- 如果你已通过调用 [startPreview](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview) 方法启用本地视频预览,可使用 `visibleInPreview` 成员设置水印是否在预览中可见。
- 如果你已为本地视频启用镜像模式,本地视频中的水印也会被镜像。为避免水印被镜像,声网建议你不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。
:::
### 适用场景 [#适用场景]
该方法适用于多频道场景。
### 参数 [#参数-3]
要添加的水印图像的本地文件路径。该方法支持从本地绝对路径或相对路径添加水印图像。
水印图像的选项。详见 [WatermarkOptions](/zh-CN/api-reference/rtc/ios/class-watermarkoptions)。
连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/ios/class-rtcconnection)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex)
## addVideoWatermarkEx\:connection: [#addvideowatermarkexconnection]
向本地视频添加水印图像。
```objc
- (int)addVideoWatermarkEx:(WatermarkConfig* _Nonnull)configs connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(addVideoWatermarkEx(_:connection:));
```
:::info[自从]
自 v4.6.0 版本新增。
:::
### 适用场景 [#适用场景-1]
该方法适用于多频道场景。
### 参数 [#参数-4]
水印配置。详见 [WatermarkConfig](/zh-CN/api-reference/rtc/ios/class-watermarkconfig)。
[AgoraRtcConnection](/zh-CN/api-reference/rtc/ios/class-rtcconnection) 对象。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/ios/class-rtcconnection)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex)
## clearVideoWatermarkEx: [#clearvideowatermarkex]
从视频流中移除水印图像。
```objc
- (int)clearVideoWatermarkEx:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(clearVideoWatermarkEx(_:));
```
### 适用场景 [#适用场景-2]
该方法适用于多频道场景。
### 参数 [#参数-5]
连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/ios/class-rtcconnection)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex)
## clearVideoWatermarks [#clearvideowatermarks]
从视频流中移除水印图像。
```objc
- (int)clearVideoWatermarks NS_SWIFT_NAME(clearVideoWatermarks());
```
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## removeVideoWatermark: [#removevideowatermark]
从本地视频中移除水印图像。
```objc
- (int)removeVideoWatermark:(NSString* _Nonnull)id NS_SWIFT_NAME(removeVideoWatermark(_:));
```
:::info[自从]
自 v4.6.0 版本新增。
:::
该方法使用你指定的唯一标识符,从本地视频流中移除之前添加的水印图像。
### 参数 [#参数-6]
要移除的水印的标识符。
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## removeVideoWatermarkEx\:connection: [#removevideowatermarkexconnection]
从本地或远端视频流中移除指定的水印图像。
```objc
- (int)removeVideoWatermarkEx:(NSString* _Nonnull)id connection:(AgoraRtcConnection * _Nonnull)connection NS_SWIFT_NAME(removeVideoWatermarkEx(_:connection:));
```
:::info[自从]
自 v4.6.0 版本新增。
:::
### 适用场景 [#适用场景-3]
该方法适用于多频道场景。
### 参数 [#参数-7]
要移除的水印的标识符。
连接信息。详见 [AgoraRtcConnection](/zh-CN/api-reference/rtc/ios/class-rtcconnection)。
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcEngineKit(Ex)](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex)