占位水印
在直播合流过程中,如果多视频画面的排版方案为自定义布局,那么在 MCU 服务收不到某个连麦者的视频数据时,会将该连麦者的视频视图将显示为黑屏。MCU 收不到视频数据的情况一般有以下两种:
- 连麦者关闭摄像头
- 连麦者取消发布视频流
设置了视频占位图之后,MCU 在收不到用户的视频数据时,会使用设置的占位图来填充画面。占位图使用水印方式实现(下 文也称为「占位水印」),支持文字水印和图片水印。文字水印叠加显示在图片水印上层。
在直播合流自定义布局模式下,您可以使用占位水印 API 接口进行以下设置:
- 设置(或取消)在连麦者关闭摄像头时,该用户视图上显示的占位图。
- 设置(或取消)在连麦者取消发布视频流时,该人视图上显示的占位图。
注意事项
-
占位水印仅在多视频画面的排版方案为自定义布局时生效。在悬浮模式和自适应模式下不生效。
在悬浮模式与自适应模式下,如果连麦者关闭摄像头或取消发布视频流,则不显示该连麦者视图。
-
占位图在画面中显示的位置与自定义模式连麦用户的位置保持一致。例如,如果使用直播合流 API 设置自定义布局,那么显示占位图时将使用最后一次调用接口时设置的
input.video
项中的子视图坐标。 -
显示占位图时,会按比例铺满连麦用户所占位置。如果比例不一致,则裁剪图片。
-
每一个占位图最多支持 10 行文字和 5 个图片水印。
-
每一个占位的图片/文字根据x、y、w、h有个覆盖关系,后面的覆盖前面的。
-
每一个占位的图片和文字覆盖关系是,根据x、y文字覆盖图片, 图片不会覆盖文字。
请求方法
POST:http(s)://api.rong-api.com/v2/rtc/mcu/placehold
签名规则: 所有请求融云服务端 API 接口的请求均需要进行规则校验,详见 API 请求签名。
正文参数
HTTP 请求正文中包含具有以下结构的 JSON 对象:
名称 | 类型 | 说明 |
---|---|---|
version | Number | 标明 API 版本。您可直接传入当前建议的版本:2 |
sessionId | String | (必传)需要配置的会话 ID。您可以通过融云服务端回调获取该 sessionId ,请参见房间状态同步。 |
placehold | String | Object 格式数据;可以设置布局相关参数,具体如下 |
placehold[i].action | Number | 1 :设置在连麦者关闭摄像头时,该人视图上需要显示的占位图。2 :清除关闭摄像头时显示的占位图。3 :设置在连麦者用户取消发布视频流后,该人视图上应显示的占位图。4 :清除取消发布视频流时的占位图。 |
placehold[i].streamId | String | 视频流 ID |
placehold[i].text[i].content | String | 文字内容 |
placehold[i].text[i].fontSize | Number | 文字大小,单位为像素(px) |
placehold[i].text[i].color | String | 文字颜色(black, white) |
placehold[i].text[i].alpha | Number | 文字透明度(0.0-1.0) |
placehold[i].text[i].x | Number | 文字起始位置横坐标(0.0-1.0) |
placehold[i].text[i].y | Number | 文字起始位置横坐标(0.0-1.0) |
placehold[i].picture[i].uri | String | 图片下载地址 |
placehold[i].picture[i].w | Number | 占位图的长度,相对于用户占用画布的区域。浮点数。 |
placehold[i].picture[i].h | Number | 占位图的宽度,相对于用户占用画布的区域。浮点数。。 |
placehold[i].picture[i].x | Number | 占位图起始位置 x 坐标,相对于连麦用户所占画布的区域。浮点数。 |
placehold[i].picture[i].y | Number | 占位图起始位置 y 坐标,相对于连麦用户所占画布的区域。浮点数。 |
JSON 示例
{
"version": 2,
"sessionId": "aaa",
"placehold": [{
"action": 2,
"streamId": "stream1_RongCloudRTC",
"text": [{
"alpha": 1,
"color": "white",
"x": 0.1,
"y": 0.2,
"content": "abcde",
"fontSize": 30
},
{
"alpha": 0.2,
"color": "black",
"x": 0.3,
"y": 0.5,
"content": "hello, world",
"fontSize": 20
}
],
"picture": [{
"uri": "https://aaa",
"w": 0.1,
"h": 0.1,
"x": 0.1,
"y": 0.2
},
{
"uri": "https://ccc",
"w": 0.6,
"h": 0.6,
"x": 0.2,
"y": 0.2
}
]
},
{
"action": 3,
"streamId": "stream2_RongCloudRTC",
"text": [{
"alpha": 1,
"color": "white",
"x": 0.1,
"y": 0.2,
"content": "abcde",
"fontSize": 30
},
{
"alpha": 0.2,
"color": "black",
"x": 0.3,
"y": 0.5,
"content": "hello, world",
"fontSize": 20
}
],
"picture": [{
"uri": "https://aaa",
"w": 0.1,
"h": 0.1,
"x": 0.1,
"y": 0.2
},
{
"uri": "https://ccc",
"w": 0.6,
"h": 0.6,
"x": 0.2,
"y": 0.2
}
]
}
]
}
移除占位图
占位水印 API 接口中定义了两个 action
,用于清除与某个视频流 ID(streamId)对应的占位图设置。具体如下:
- 设置
placehold[i].action
为 2,清除关闭摄像头时显示的占位图。 - 设置
placehold[i].action
为 4,清除取消发布视频流后显示的占位图。
请注意,如果在直播合流的视频流列表中移除某视频流,则会同时清除与该视频流 ID 相关的所有占位图设置。例如,如果使用直播合流 API ,最近一次调用时 input.video
里去除了某个连麦用户的 streamId
,则与该用户相关的占位图设置均会被清除。
流程示例
如果您想更好地理解占位图的具体行为,可以参考下面两个流程示例。
流程示例 1
在该流程示例中,steam3 对应的连麦用户发布了视频流,随后取消发布视频流。我们使用直播合流 API 从合流视频列表中移除了该用户,并重新加回该用户。使用调用占位水印 API,设置了取消发布视频流后应显示的占位图,并最后清除了占位图设置。
- 使用直播合流 API,设置为自定义视频布局,并在 config.input.video 里面设置了 stream1, stream2,stream3 三个流,但 stream3 目前没有人发布视频流(这种情况 MCU 不会报错)。
- 调用占位水印 API,设置 stream3 的
placehold[i].action
为 3,并设置取消发布视频后需要显示的占位图。设置成功后,stream3 的位置上显示该占位图。 - 连麦用户发布了 stream3 视频流,此时不再显示占位图,而是正常显示连麦用户发布的视频。
- 连麦用户取消发布了 stream3,此时重新显示 stream3 上的占位图。
- 调用直播合流 API,但在 config.input.video 里面仅设置 stream1,stream2,不设置 stream3,即 stream3 不再参与合流。此时不再显示 stream3 的占位图,同时服务端会清除与 stream3 对应的占位图设置。
- 调用直播合流 API,在 config.input.video 里面设置 stream1,stream2,stream3。此时连麦用户未发布视频流,但因与 stream3 相关的占位图设置已被清除,此时 stream3 位置上无占位图。
- 调用占位水印 API,再次设置 stream3 的
placehold[i].action
为 3,并设置 stream3 的取消发布视频占位图。设置成功后,stream3 的位置上显示新设置的占位图。 - 调用占位水印 API,设置 stream3 的
placehold[i].action
为 4,即清除了取消发布视频流后应显示的占位图。设置成功后,stream3 位置 上不再显示占位图。
流程示例 2
在该流程示例中,steam3 对应的连麦用户多次开启、关闭摄像头。我们使用直播合流 API 从合流视频列表中移除了该用户,并重新加回该用户。使用调用占位水印 API,设置了关闭摄像头后应显示的占位图,并最后清除了占位图设置。
- 使用直播合流 API,设置为自定义视频布局,在 config.input.video 里面设置 stream1,stream2,stream3 三个流,并且用户发布了这三个流。
- 调用占位水印 API,设置 stream3 的
placehold[i].action
为 1,设置关闭摄像头后需要显示的占位图。 - stream3 对应的连麦用户关闭了摄像头,此时 stream3 的位置上显示上一步中设置的占位图。
- stream3 对应的连麦用户开启了摄像头,此时 stream3 的位置上不再显示 stream3 的占位图,而是显示连麦用户视频。
- 调用直播合流 API,但在 config.input.video 里面仅设置 stream1,stream2,不设置 stream3,即 stream3 不再参与合流。此时不再显示 stream3 的占位图,同时服务端会清除与 stream3 对应的占位图设置。
- 调用直播合流 API,在 config.input.video 里面设置 stream1,stream2,stream3。但注意,此时与 stream3 相关的占位图设置已被清除,且未重新设置。
- stream3 对应的连麦用户关闭摄像头,此时 stream3 位置上显示为黑屏,不显示占位图。
- 调用占位水印 API,设置 stream3 的
placehold[i].action
为 1,重新设置关闭摄像头后需要显示的占位图。设置成功后,stream3 位置上显示占位图。 - 调用占位水印 API,设置 stream3 的
placehold[i].action
为 2,即 清除关闭摄像头时应显示的占位图。设置成功后,stream3 位置上不显示占位图。