直播水印

addVideoWatermark [1/3]

向本地视频添加水印图像。

Java

public abstract int addVideoWatermark(AgoraImage watermark)

废弃

自 v2.9.1 版本废弃，请改用 addVideoWatermark [3/3]。

该方法在直播场景中向本地视频流添加 PNG 格式的水印图像。频道内的所有用户（包括 CDN 观众）以及视频采集设备都可以看到并采集该水印图像。如果你只想向 CDN 推流添加水印，请使用 startRtmpStreamWithTranscoding 方法。

信息

• 本地视频和 CDN 推流中 URL 的含义不同：在本地视频流中，URL 指的是添加的水印图像文件在本地视频流中的绝对路径；在 CDN 推流中，URL 指的是添加的水印图像在 CDN 推流中的 URL 地址。
• 水印图像的源文件必须为 PNG 格式。如果 PNG 文件的宽高与该方法中的设置不一致，SDK 会对 PNG 文件进行裁剪以符合设置。
• SDK 仅支持在本地视频或 CDN 推流中添加一张水印图像。新添加的水印图像会替换之前的图像。

参数

watermark

要添加到本地直播中的水印图像。详见 AgoraImage。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

addVideoWatermark [2/3]

向本地视频添加水印图像。

Java

public abstract int addVideoWatermark(String watermarkUrl, WatermarkOptions options)

废弃

自 v4.6.0 版本废弃，请改用 addVideoWatermark [3/3] 方法。

该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印后，频道中的所有观众（包括 CDN 观众）以及采集设备都可以看到并采集到该水印图像。声网 SDK 每个直播视频流仅支持添加一张水印图像，新添加的水印会替换之前的图像。 水印图像的位置依赖于 setVideoEncoderConfiguration 方法中的设置：

• 如果编码视频的方向模式（ORIENTATION_MODE）为固定横屏模式或自适应横屏模式，则水印使用横屏方向。
• 如果编码视频的方向模式为固定竖屏模式或自适应竖屏模式，则水印使用竖屏方向。
• 设置水印位置时，区域必须小于 setVideoEncoderConfiguration 方法中设置的尺寸，否则水印图像会被裁剪。

你可以通过设置 visibleInPreview 参数控制预览时水印的可见性。但其最终是否生效还取决于调用 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 图像的尺寸与该方法中的设置不一致，图像将被裁剪或缩放以符合设置。
• 如果你为本地视频启用了镜像模式，则本地视频中的水印也会被镜像。为避免水印被镜像，声网建议不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。

参数

watermarkUrl

要添加的水印图像的本地文件路径。支持使用本地绝对路径或相对路径。

options

水印图像的相关设置。详见 WatermarkOptions。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

addVideoWatermark [3/3]

向本地视频流添加水印图像。

Java

public abstract int addVideoWatermark(WatermarkConfig config);

自从

自 v4.6.0 版本新增。

你可以使用该方法通过 WatermarkConfig 配置，在本地视频流中叠加水印图像，包括设置水印在预览中的位置、大小和可见性。

参数

config

水印配置。详见 WatermarkConfig。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

addVideoWatermarkEx [1/2]

向本地视频添加水印图像。

Java

public abstract int addVideoWatermarkEx(String watermarkUrl, WatermarkOptions options, RtcConnection connection)

废弃

自 v4.6.0 版本废弃，请改用 addVideoWatermarkEx [2/2] 方法。

该方法在直播中向本地视频添加 PNG 格式的水印图像。添加水印图像后，频道中的所有观众（包括 CDN 观众）以及采集设备都可以看到并采集该图像。声网 SDK 仅支持在一个直播视频流中添加一张水印图像，新添加的水印图像会替换之前的图像。 水印图像的坐标依赖于 setVideoEncoderConfigurationEx 方法中的设置：

• 如果编码视频的方向模式（ORIENTATION_MODE）为固定横屏模式或自适应横屏模式，则水印使用横屏方向。
• 如果编码视频的方向模式为固定竖屏模式或自适应竖屏模式，则水印使用竖屏方向。
• 设置水印位置时，区域必须小于 setVideoEncoderConfigurationEx 方法中设置的尺寸，否则水印图像会被裁剪。

信息

• 请确保在调用该方法前已调用 enableVideo 方法。
• 该方法仅支持添加 PNG 文件格式的水印图像。支持的 PNG 图像像素格式包括 RGBA、RGB、Palette、Gray 和 Alpha_gray。
• 如果 PNG 图像的尺寸与该方法中的设置不一致，图像将被裁剪或缩放以符合设置。
• 如果你已通过调用 startPreview 方法启用了本地视频预览，可以使用 visibleInPreview 成员设置水印在预览中是否可见。
• 如果你为本地视频启用了镜像模式，则本地视频中的水印也会被镜像。为避免水印被镜像，声网建议不要同时使用本地视频的镜像和水印功能。你可以在应用层实现水印功能。

适用场景

该方法适用于多频道场景。

参数

watermarkUrl

要添加的水印图像的本地文件路径。支持使用本地绝对路径或相对路径。

options

水印图像的相关设置。详见 WatermarkOptions。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

addVideoWatermarkEx [2/2]

向本地视频添加水印图像。

Java

public abstract int addVideoWatermarkEx(WatermarkConfig config, RtcConnection connection);

自从

自 v4.6.0 版本新增。

适用场景

该方法适用于多频道场景。

参数

config

水印配置。详见 WatermarkConfig。

connection

RtcConnection 对象。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

clearVideoWatermarkEx

从视频流中移除水印图像。

Java

public abstract int clearVideoWatermarkEx(RtcConnection connection);

适用场景

该方法适用于多频道场景。

参数

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

clearVideoWatermarks

从视频流中移除水印图像。

Java

public abstract int clearVideoWatermarks();

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

getBuffer

获取水印图像的数据缓冲区。

Java

public ByteBuffer getBuffer()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功时，返回包含水印图像数据的 ByteBuffer 对象。

所属接口类

• WatermarkBuffer

getFormat

获取水印图像的格式。

Java

public int getFormat()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回水印图像缓冲区的格式。

所属接口类

• WatermarkBuffer

getHeight

获取水印图像的高度。

Java

public int getHeight()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回水印图像的高度，单位为像素。

所属接口类

• WatermarkBuffer

getId

获取水印的唯一标识符。

Java

public String getId()

自从

自 v4.6.0 版本新增。

用于从 WatermarkBuffer 或 WatermarkConfig 实例中获取水印的唯一标识符。

返回值

• 方法调用成功时，返回水印的唯一标识符。
• 方法调用失败，返回空字符串。

所属接口类

• WatermarkBuffer

getImageUrl

获取水印图像的 URL。

Java

public String getImageUrl()

自从

自 v4.6.0 版本新增。

返回值

• 方法调用成功时，返回水印图像的 URL。
• 方法调用失败，返回空字符串。

所属接口类

• WatermarkConfig

getPositionInLandscapeMode

获取横屏模式下水印的位置。

Java

public int[] getPositionInLandscapeMode()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回一个包含四个元素的整数数组，依次表示水印矩形的 x、y、宽度和高度。

所属接口类

• WatermarkOptions

getPositionInPortraitMode

获取竖屏模式下水印的位置。

Java

public int[] getPositionInPortraitMode()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回一个包含四个元素的整数数组，分别表示水印矩形的 x、y、宽度和高度。

所属接口类

• WatermarkOptions

getType

获取当前水印配置中的水印类型信息。

Java

public int getType()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回水印类型：

• WATERMARK_TYPE_IMAGE：图片水印。
• WATERMARK_TYPE_BUFFER：Buffer 水印。

所属接口类

• WatermarkConfig

getWidth

获取水印图像的宽度。

Java

public int getWidth()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回水印图像的宽度，单位为像素。

所属接口类

• WatermarkBuffer

getzOrder

获取水印图像的 Z-order 索引。

Java

public int getzOrder()

自从

自 v4.6.0 版本新增。

返回值

方法调用成功，返回水印图像的 Z-order 索引。

所属接口类

• WatermarkOptions

isVisibleInPreview

检查水印在本地视频预览中是否可见。

Java

public boolean isVisibleInPreview()

自从

自 v4.6.0 版本新增。

返回值

• true：水印在本地视频预览中可见。
• false：水印在本地视频预览中不可见。

所属接口类

• WatermarkOptions

removeVideoWatermark

从本地视频中移除水印图像。

Java

public abstract int removeVideoWatermark(String id);

自从

自 v4.6.0 版本新增。

该方法使用指定的唯一 ID，从本地视频流中移除之前添加的水印图像。

参数

id

要移除的水印图像的 ID。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

removeVideoWatermarkEx

从本地或远端视频流中移除指定的水印图像。

Java

public abstract int removeVideoWatermarkEx(String id, RtcConnection connection);

自从

自 v4.6.0 版本新增。

适用场景

该方法适用于多频道场景。

参数

id

要移除的水印图像的 ID。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx