直播合流
直播合流是指将房间内多路音视频流进行按需混合,控制输出的合流视频参数。
利用直播合流服务端 API,您可以进行以下配置:
- 选择主播视频流进行合流,即控制观众可以在合流后视频中看到或者听到的哪些主播
- 配置直播的布局,即观众端多视频画面的排版方案
- 管理直播合流输出的分辨率
- 管理(文字、图片)水印的效果和位置
请求方法
POST:http(s)://api.rong-api.com/rtc/mcu/config.json
签名规则: 所有请求融云服务端 API 接口的请求均需要进行规则校验,详见 API 请求签名。
正文参数
HTTP 请求正文中包含具有以下结构的 JSON 对象:
请求参数 | 类型 | 说明 |
---|---|---|
sessionId | String | (必传)需要配置合流的会话 ID,可通过服务端回调获取。详见房间状态同步。 |
config | Object | JSON 格式数据,包含所有布局相关参数。 |
config.mode | Number | 合流布局模式,用于控制即多视频画面的排版方式。可选模式如下:
|
config.version | Number | 配置版本号,默认为 1。 |
config.host_user_id | String | 主视频流发布者的用户 ID。使用自定义布局时(config.mode 为 1 )应留空,填 “”。
|
config.host_stream_id | String | 主视频流 ID。使用自定义布局时(config.mode 为 1 )应留空,填 “”。
|
config.output | Object | 指定合流之后的媒体输出参数,内部包含 JSON 格式的视频合流输出配置(video )和音频合流输出配置(audio )。详见下方 config.output 对象说明 |
config.customMode | Bool | (已废弃)请使用 inputFilterMode 字段。 |
config.inputFilterMode | Number | 控制 MCU 合流服务所使用的资源。
|
config.input | Object | 指定需要进行合流的子用户流输入配置,内部包含子视频流的数组(video )和子音频流数组(audio )。详见下方 config.input 对象说明 |
config.waterMark | Object | 指定视频水印配置,支持在合流后整个画布上添加水印;以及各个子视频流上添加水印。可添加图片、文字、时间戳水印。详见下方 config.waterMark 对象说明。 |
-
config.output 对象说明:该对象描述了合流的视频、音频输出参数。
参数 类型 说明 video Object 指定合流输出视频的配置,内部包含常规视频流(大流)配置对象( normal
)、小流配置对象(tiny
)、裁剪方式配置、背景颜色配置和背景图配置。video.normal Object 指定合流之后媒体服务输出的常规视频流(大流)的配置。 video.normal.width Number 合流之后媒体服务输出的常规尺寸视频的宽度。 video.normal.height Number 合 流之后媒体服务输出的常规尺寸视频的高度。 video.normal.fps Number 合流之后媒体服务输出的常规尺寸视频的帧率。 video.normal.bitrate Number 合流之后媒体服务输出的常规尺寸视频的码率。如果您无法确定合适的码率,可参考以下分辨率/码率对应关系进行配置: - 640X360:800
- 480X480:800
- 640X480:900
- 1280X720:2500
- 1920X1080:4000
video.tiny Object (可选)指定合流之后媒体服务输出的小流视频的配置。如不配置,小流使用默认分辨率("width": 180, "height": 320) video.tiny.width Number 合流之后媒体服务输出的小流视频的宽度。 video.tiny.height Number 合流之后媒体服务输出的小流视频的高度。 video.tiny.fps Number 合流之后媒体服务输出的小流视频的帧率。 video.tiny.bitrate Number 合流之后媒体服务输出的小流视频的码率(kbps)。 video.exparams Object 指定合流服务输出视频的其他配置,内部包含视频裁剪方式配置( renderMode
)。video.exparams.renderMode Number 1
:裁剪;2
:不裁剪。video.backgroundColor String 指定背景颜色,无此项则保持上次设置。例如 "0xf1a2c3"。 video.backgroundPicture Object 指定合流背景图的配置。详见下方 video.backgroundPicture 对象说明。 audio Object 指定合流输出音频的配置,内部包含音频比特率配置( bitrate
)。audio.bitrate Number 音频比特率配置,单位为 kbps。 -
video.backgroundPicture 对象说明:该对象描述了合流的视频的背景图配置。
参数 类型 说明 enable String 是否需要设置背景图。 off
表示关闭。on
或者不传表示开启。fillMode String 背景图片填充模式。 1
:按比例裁剪。2
:不裁剪,按比例压缩。picture Array of Objects 背景图配置数组。 picture[i].uri String 图片下载地址。要求图片是png格式的, 不能是 jpg 格式的,也不能是 jpg 格式的图片的后缀名改成 png 的图片。 picture[i].x Number 图片显示位置横坐标 (0.0-1.0) picture[i].y Number 图片显示位置纵坐标 (0.0-1.0) picture[i].w Number 图片显示区域宽度 (0.0-1.0), 对应整体画布宽度为 1 picture[i].h Number 图片显示区域高度 (0.0-1.0), 对应整体画布高度为 1。其中图片宽高的显示会根据原始比例做缩放。例如从网络地址获取的 png 图片原始宽高为500x500,picture[i].w=0.5,picture[i].h=0.2,画布尺寸为 640*480,则设置的图片显示区域为(320x96),最终显示的图片水印大小为(96x96)。
-
config.input 对象说明:该对象描述了进行合流的子视频流、子音频流输入参数,以及自定义布局下子视图的具体坐标和宽高。
参数 类型 说明 video Array of objects 指定需要进行合流的用户视频流数组,内部包含各个视频流的基础信息。在合流布局方式为自定义布局时( config.mode
= 1),内部还需要包含各个子视频流对应视图的坐标和宽高配置。video[i].user_id String (必填)子视图视频发布者 ID。需要保证有效性。 video[i].stream_id String (必填)子视图视频发布者的流 ID,需要保证有效性。
可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下mediaType
为 1 时的msid
。video[i].x Number 子视图左上角相对画布原点的偏移坐标,x 轴参数(像素)不能超出画布整体。
仅在合流布局方式为自定义布局时(config.mode
= 1)需要设置。video[i].y Number 子视图左上角相对画布原点的偏移坐标,y 轴参数(像素)不能超出画布整体。
仅在合流布局方式为自定义布局时(config.mode
= 1)需要设置。video[i].width Number 子视图视频的宽度(像素值), x + width 不能大于视频宽度像素值。
仅在合流布局方式为自定义布局时(config.mode
= 1)需要设置。video[i].height Number 子视图视频的高度(像素值), y + height 不能大于视频高度像素值。
仅在合流布局方式为自定义布局时(config.mode
= 1)需要设置。audio Array of objects 指定需要进行合流的用户音频流数组,内部包含各个音频流的基础信息。 audio[i].user_id String 音频流发布者的用户 ID。 audio[i].stream_id String 音频流 ID。
可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下mediaType
为 0 时的msid
。 -
config.waterMark 对象说明:该对象描述了合流前、合流后的水印配置。
参数 类型 说明 waterMark.enable Bool 水印开关。 waterMark.mixScreen Object 配置合流后整个画布的水印。 waterMark.mixScreen.timestamp Object 配置合流后整个画布的水印。详见下方时间戳水印说明。 waterMark.mixScreen.text Array of Objects 配置合流后整个画布的水印。详见下方文字水印说明。 waterMark.mixScreen.picture Array of Objects 配置合流后整个画布的水印。详见下方图片水印说明。 waterMark.singleScreen Array of Objects 根据流 ID 配置单个视频流的水印。数组内部可指定各个子视频流的水印配置。 waterMark.singleScreen[i].steamId String 子视频流的 ID。
可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下mediaType
为 1 时的msid
。waterMark.singleScreen[i].timestamp Object 配置单个视频流的时间戳水印。详见下方时间戳水印说明。 waterMark.singleScreen[i].text Array of Objects 配置单个视频流的文字水印。详见下方文字水印说明。 waterMark.singleScreen[i].picture Array of Objects 配置单个视频流的图片水印。详见下方图片水印说明。 -
时间戳水印说明:
timestamp
对象描述了时间戳的水印配置参数。参数 类型 说明 timestamp Object 配置时间戳水印。 timestamp.timezone Number 时间戳水印时区。 timestamp.fontSize Number 时间戳水印字体像素大小。 timestamp.color String 时间戳水印字体颜色。可选值: black
(黑)、white
(白)。timestamp.alpha Number 时间戳水印字体透明度(0.0-1.0)。 timestamp.x Number 时间戳水印起始位置横坐标, 浮点值(0.0-1.0),对应画布宽度为 1。 timestamp.y Number 时间戳水印起始位置纵坐标, 浮点值(0.0-1.0),对应画布高度为 1。 -
文字水印说明:
text
数组描述了文字水印配置参数。参数 类型 说明 text Array of Objects 配置文字水印。 text[i].content String 文字水印的文字内容。 text[i].fontSize Number 文字水印的字体大小(像素)。 text[i].color String 文字水印字体颜色。可选值: black
(黑)、white
(白)。text[i].alpha Number 文字水印的文字透明度 (0.0-1.0) text[i].x Number 文字水印的文字起始位置横坐标 (0.0-1.0)。 text[i].y Number 文字水印的文字起始位置纵坐标 (0.0-1.0)。 -
图片水印说明:
picture
数组描述了图片水印配置参数。参数 类型 说明 picture Array of Objects 配置图片水印。 picture[i].uri String 图片下载地址。要求图片是png格式的,不能是 jpg 格式的,也不能是 jpg 格式的图片的后缀名改成 png 的图片。 picture[i].x Number 图片显示位置横坐标 (0.0-1.0) picture[i].y Number 图片显示位置纵坐标 (0.0-1.0) picture[i].w Number 图片显示区域宽度 (0.0-1.0), 对应整体画布宽度为 1 picture[i].h Number 图片显示区域高度 (0.0-1.0), 对应整体画布高度为 1。其中图片宽高的显示会根据原始比例做缩放。例如从网络地址获取的 png 图片原始宽高为500x500,picture[i].w=0.5,picture[i].h=0.2,画布尺寸为 640*480,则设置的图片显示区域为(320x96),最终显示的图片水印大小为(96x96)。
-