占位水印
在直 播合流过程中，如果多视频画面的排版方案为自定义布局，那么在 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 位置上不显示占位图。