跳到主要内容

占位水印

在直播合流过程中,如果多视频画面的排版方案为自定义布局,那么在 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 对象:

名称类型说明
versionNumber标明 API 版本。您可直接传入当前建议的版本:2
sessionIdString(必传)需要配置的会话 ID。您可以通过融云服务端回调获取该 sessionId,请参见房间状态同步
placeholdStringObject 格式数据;可以设置布局相关参数,具体如下
placehold[i].actionNumber1:设置在连麦者关闭摄像头时,该人视图上需要显示的占位图。

2:清除关闭摄像头时显示的占位图。

3:设置在连麦者用户取消发布视频流后,该人视图上应显示的占位图。

4:清除取消发布视频流时的占位图。
placehold[i].streamIdString视频流 ID
placehold[i].text[i].contentString文字内容
placehold[i].text[i].fontSizeNumber文字大小,单位为像素(px)
placehold[i].text[i].colorString文字颜色(black, white)
placehold[i].text[i].alphaNumber文字透明度(0.0-1.0)
placehold[i].text[i].xNumber文字起始位置横坐标(0.0-1.0)
placehold[i].text[i].yNumber文字起始位置横坐标(0.0-1.0)
placehold[i].picture[i].uriString图片下载地址
placehold[i].picture[i].wNumber占位图的长度,相对于用户占用画布的区域。浮点数。
placehold[i].picture[i].hNumber占位图的宽度,相对于用户占用画布的区域。浮点数。。
placehold[i].picture[i].xNumber占位图起始位置 x 坐标,相对于连麦用户所占画布的区域。浮点数。
placehold[i].picture[i].yNumber占位图起始位置 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,设置了取消发布视频流后应显示的占位图,并最后清除了占位图设置。

  1. 使用直播合流 API,设置为自定义视频布局,并在 config.input.video 里面设置了 stream1, stream2,stream3 三个流,但 stream3 目前没有人发布视频流(这种情况 MCU 不会报错)。
  2. 调用占位水印 API,设置 stream3 的 placehold[i].action 为 3,并设置取消发布视频后需要显示的占位图。设置成功后,stream3 的位置上显示该占位图。
  3. 连麦用户发布了 stream3 视频流,此时不再显示占位图,而是正常显示连麦用户发布的视频。
  4. 连麦用户取消发布了 stream3,此时重新显示 stream3 上的占位图。
  5. 调用直播合流 API,但在 config.input.video 里面仅设置 stream1,stream2,不设置 stream3,即 stream3 不再参与合流。此时不再显示 stream3 的占位图,同时服务端会清除与 stream3 对应的占位图设置。
  6. 调用直播合流 API,在 config.input.video 里面设置 stream1,stream2,stream3。此时连麦用户未发布视频流,但因与 stream3 相关的占位图设置已被清除,此时 stream3 位置上无占位图。
  7. 调用占位水印 API,再次设置 stream3 的 placehold[i].action 为 3,并设置 stream3 的取消发布视频占位图。设置成功后,stream3 的位置上显示新设置的占位图。
  8. 调用占位水印 API,设置 stream3 的 placehold[i].action 为 4,即清除了取消发布视频流后应显示的占位图。设置成功后,stream3 位置上不再显示占位图。

流程示例 2

在该流程示例中,steam3 对应的连麦用户多次开启、关闭摄像头。我们使用直播合流 API 从合流视频列表中移除了该用户,并重新加回该用户。使用调用占位水印 API,设置了关闭摄像头后应显示的占位图,并最后清除了占位图设置。

  1. 使用直播合流 API,设置为自定义视频布局,在 config.input.video 里面设置 stream1,stream2,stream3 三个流,并且用户发布了这三个流。
  2. 调用占位水印 API,设置 stream3 的 placehold[i].action 为 1,设置关闭摄像头后需要显示的占位图。
  3. stream3 对应的连麦用户关闭了摄像头,此时 stream3 的位置上显示上一步中设置的占位图。
  4. stream3 对应的连麦用户开启了摄像头,此时 stream3 的位置上不再显示 stream3 的占位图,而是显示连麦用户视频。
  5. 调用直播合流 API,但在 config.input.video 里面仅设置 stream1,stream2,不设置 stream3,即 stream3 不再参与合流。此时不再显示 stream3 的占位图,同时服务端会清除与 stream3 对应的占位图设置。
  6. 调用直播合流 API,在 config.input.video 里面设置 stream1,stream2,stream3。但注意,此时与 stream3 相关的占位图设置已被清除,且未重新设置。
  7. stream3 对应的连麦用户关闭摄像头,此时 stream3 位置上显示为黑屏,不显示占位图。
  8. 调用占位水印 API,设置 stream3 的 placehold[i].action 为 1,重新设置关闭摄像头后需要显示的占位图。设置成功后,stream3 位置上显示占位图。
  9. 调用占位水印 API,设置 stream3 的 placehold[i].action 为 2,即清除关闭摄像头时应显示的占位图。设置成功后,stream3 位置上不显示占位图。