跳到主要内容

直播合流

直播合流是指将房间内多路音视频流进行按需混合,控制输出的合流视频参数。

利用直播合流服务端 API,您可以进行以下配置:

  • 选择主播视频流进行合流,即控制观众可以在合流后视频中看到或者听到的哪些主播
  • 配置直播的布局,即观众端多视频画面的排版方案
  • 管理直播合流输出的分辨率
  • 管理(文字、图片)水印的效果和位置

请求方法

POSThttp(s)://api.rong-api.com/rtc/mcu/config.json

签名规则: 所有请求融云服务端 API 接口的请求均需要进行规则校验,详见 API 请求签名

正文参数

HTTP 请求正文中包含具有以下结构的 JSON 对象:

请求参数类型说明
sessionIdString(必传)需要配置合流的会话 ID,可通过服务端回调获取。详见房间状态同步
configObjectJSON 格式数据,包含所有布局相关参数。
config.modeNumber合流布局模式,用于控制即多视频画面的排版方式。可选模式如下:
  • 1:自定义布局,您可以设置合流视频整体尺寸,以及各个连麦者视图位置及大小。

    注意:各个子视图位置及大小数据需要在 config.video.input 中分别传入。

  • 2:悬浮布局(默认)
  • 3:自适应布局
详见了解合流布局
config.versionNumber配置版本号,默认为 1。
config.host_user_idString主视频流发布者的用户 ID。使用自定义布局时(config.mode1)应留空,填 “”。
  • 使用悬浮布局时(config.mode 为 2),该 ID 将被放置在悬浮布局的背景上。
  • 使用自适应布局时(config.mode 为 3),该 ID 将放置在自适应布局的左上角。
config.host_stream_idString主视频流 ID。使用自定义布局时(config.mode1)应留空,填 “”。
  • 使用悬浮布局时(config.mode 为 2),该 ID 将被放置在悬浮布局的背景上。
  • 使用自适应布局时(config.mode 为 3),该 ID 将放置在自适应布局的左上角图像上。
您可以使用房间状态同步获取流 ID。
config.outputObject指定合流之后的媒体输出参数,内部包含 JSON 格式的视频合流输出配置(video)和音频合流输出配置(audio)。详见下方 config.output 对象说明
config.customModeBool(已废弃)请使用 inputFilterMode 字段。
config.inputFilterModeNumber控制 MCU 合流服务所使用的资源。
  • 0:使用当前会话中所有主播发布的音视频流进行合流。
  • 4:使用 config.input.videoconfig.input.audio 中提供的音频流、视频流 stream_id 进行合流。
config.inputObject指定需要进行合流的子用户流输入配置,内部包含子视频流的数组(video)和子音频流数组(audio)。详见下方 config.input 对象说明
config.waterMarkObject指定视频水印配置,支持在合流后整个画布上添加水印;以及各个子视频流上添加水印。可添加图片、文字、时间戳水印。详见下方 config.waterMark 对象说明
  • config.output 对象说明:该对象描述了合流的视频、音频输出参数。

    参数类型说明
    videoObject指定合流输出视频的配置,内部包含常规视频流(大流)配置对象(normal)、小流配置对象(tiny)、裁剪方式配置、背景颜色配置和背景图配置。
    video.normalObject指定合流之后媒体服务输出的常规视频流(大流)的配置。
    video.normal.widthNumber合流之后媒体服务输出的常规尺寸视频的宽度。
    video.normal.heightNumber合流之后媒体服务输出的常规尺寸视频的高度。
    video.normal.fpsNumber合流之后媒体服务输出的常规尺寸视频的帧率。
    video.normal.bitrateNumber合流之后媒体服务输出的常规尺寸视频的码率。如果您无法确定合适的码率,可参考以下分辨率/码率对应关系进行配置:
    • 640X360:800
    • 480X480:800
    • 640X480:900
    • 1280X720:2500
    • 1920X1080:4000
    video.tinyObject(可选)指定合流之后媒体服务输出的小流视频的配置。如不配置,小流使用默认分辨率("width": 180, "height": 320)
    video.tiny.widthNumber合流之后媒体服务输出的小流视频的宽度。
    video.tiny.heightNumber合流之后媒体服务输出的小流视频的高度。
    video.tiny.fpsNumber合流之后媒体服务输出的小流视频的帧率。
    video.tiny.bitrateNumber合流之后媒体服务输出的小流视频的码率(kbps)。
    video.exparamsObject指定合流服务输出视频的其他配置,内部包含视频裁剪方式配置(renderMode)。
    video.exparams.renderModeNumber1:裁剪;2:不裁剪。
    video.backgroundColorString指定背景颜色,无此项则保持上次设置。例如 "0xf1a2c3"。
    video.backgroundPictureObject指定合流背景图的配置。详见下方 video.backgroundPicture 对象说明
    audioObject指定合流输出音频的配置,内部包含音频比特率配置(bitrate)。
    audio.bitrateNumber音频比特率配置,单位为 kbps。
    • video.backgroundPicture 对象说明:该对象描述了合流的视频的背景图配置。

      参数类型说明
      enableString是否需要设置背景图。off 表示关闭。on 或者不传表示开启。
      fillModeString背景图片填充模式。1:按比例裁剪。2:不裁剪,按比例压缩。
      pictureArray of Objects背景图配置数组。
      picture[i].uriString图片下载地址。要求图片是png格式的,不能是 jpg 格式的,也不能是 jpg 格式的图片的后缀名改成 png 的图片。
      picture[i].xNumber图片显示位置横坐标 (0.0-1.0)
      picture[i].yNumber图片显示位置纵坐标 (0.0-1.0)
      picture[i].wNumber图片显示区域宽度 (0.0-1.0), 对应整体画布宽度为 1
      picture[i].hNumber图片显示区域高度 (0.0-1.0), 对应整体画布高度为 1。其中图片宽高的显示会根据原始比例做缩放。例如从网络地址获取的 png 图片原始宽高为500x500,picture[i].w=0.5,picture[i].h=0.2,画布尺寸为 640*480,则设置的图片显示区域为(320x96),最终显示的图片水印大小为(96x96)。
  • config.input 对象说明:该对象描述了进行合流的子视频流、子音频流输入参数,以及自定义布局下子视图的具体坐标和宽高。

    参数类型说明
    videoArray of objects指定需要进行合流的用户视频流数组,内部包含各个视频流的基础信息。在合流布局方式为自定义布局时(config.mode = 1),内部还需要包含各个子视频流对应视图的坐标和宽高配置。
    video[i].user_idString(必填)子视图视频发布者 ID。需要保证有效性。
    video[i].stream_idString(必填)子视图视频发布者的流 ID,需要保证有效性。

    可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下 mediaType 为 1 时的 msid
    video[i].xNumber子视图左上角相对画布原点的偏移坐标,x 轴参数(像素)不能超出画布整体。

    仅在合流布局方式为自定义布局时(config.mode = 1)需要设置。
    video[i].yNumber子视图左上角相对画布原点的偏移坐标,y 轴参数(像素)不能超出画布整体。

    仅在合流布局方式为自定义布局时(config.mode = 1)需要设置。
    video[i].widthNumber子视图视频的宽度(像素值), x + width 不能大于视频宽度像素值。

    仅在合流布局方式为自定义布局时(config.mode = 1)需要设置。
    video[i].heightNumber子视图视频的高度(像素值), y + height 不能大于视频高度像素值。

    仅在合流布局方式为自定义布局时(config.mode = 1)需要设置。
    audioArray of objects指定需要进行合流的用户音频流数组,内部包含各个音频流的基础信息。
    audio[i].user_idString音频流发布者的用户 ID。
    audio[i].stream_idString音频流 ID。

    可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下 mediaType 为 0 时的 msid
  • config.waterMark 对象说明:该对象描述了合流前、合流后的水印配置。

    参数类型说明
    waterMark.enableBool水印开关。
    waterMark.mixScreenObject配置合流后整个画布的水印。
    waterMark.mixScreen.timestampObject配置合流后整个画布的水印。详见下方时间戳水印说明
    waterMark.mixScreen.textArray of Objects配置合流后整个画布的水印。详见下方文字水印说明
    waterMark.mixScreen.pictureArray of Objects配置合流后整个画布的水印。详见下方图片水印说明
    waterMark.singleScreenArray of Objects根据流 ID 配置单个视频流的水印。数组内部可指定各个子视频流的水印配置。
    waterMark.singleScreen[i].steamIdString子视频流的 ID。

    可通过服务端回调获取。详见房间状态同步。对应字段为用户资源信息下 mediaType 为 1 时的 msid
    waterMark.singleScreen[i].timestampObject配置单个视频流的时间戳水印。详见下方时间戳水印说明
    waterMark.singleScreen[i].textArray of Objects配置单个视频流的文字水印。详见下方文字水印说明
    waterMark.singleScreen[i].pictureArray of Objects配置单个视频流的图片水印。详见下方图片水印说明
    • 时间戳水印说明timestamp 对象描述了时间戳的水印配置参数。

      参数类型说明
      timestampObject配置时间戳水印。
      timestamp.timezoneNumber时间戳水印时区。
      timestamp.fontSizeNumber时间戳水印字体像素大小。
      timestamp.colorString时间戳水印字体颜色。可选值: black(黑)、white(白)。
      timestamp.alphaNumber时间戳水印字体透明度(0.0-1.0)。
      timestamp.xNumber时间戳水印起始位置横坐标, 浮点值(0.0-1.0),对应画布宽度为 1。
      timestamp.yNumber时间戳水印起始位置纵坐标, 浮点值(0.0-1.0),对应画布高度为 1。
    • 文字水印说明text 数组描述了文字水印配置参数。

      参数类型说明
      textArray of Objects配置文字水印。
      text[i].contentString文字水印的文字内容。
      text[i].fontSizeNumber文字水印的字体大小(像素)。
      text[i].colorString文字水印字体颜色。可选值: black(黑)、white(白)。
      text[i].alphaNumber文字水印的文字透明度 (0.0-1.0)
      text[i].xNumber文字水印的文字起始位置横坐标 (0.0-1.0)。
      text[i].yNumber文字水印的文字起始位置纵坐标 (0.0-1.0)。
    • 图片水印说明picture 数组描述了图片水印配置参数。

      参数类型说明
      pictureArray of Objects配置图片水印。
      picture[i].uriString图片下载地址。要求图片是png格式的,不能是 jpg 格式的,也不能是 jpg 格式的图片的后缀名改成 png 的图片。
      picture[i].xNumber图片显示位置横坐标 (0.0-1.0)
      picture[i].yNumber图片显示位置纵坐标 (0.0-1.0)
      picture[i].wNumber图片显示区域宽度 (0.0-1.0), 对应整体画布宽度为 1
      picture[i].hNumber图片显示区域高度 (0.0-1.0), 对应整体画布高度为 1。其中图片宽高的显示会根据原始比例做缩放。例如从网络地址获取的 png 图片原始宽高为500x500,picture[i].w=0.5,picture[i].h=0.2,画布尺寸为 640*480,则设置的图片显示区域为(320x96),最终显示的图片水印大小为(96x96)。

JSON 示例

{
"sessionId":"aaa",
"config":{
"version": 2,
"mode": 1/2/3, // 1 自定义,需要用户设置input 2 悬浮(默认) 3 自适应
"host_user_id": "001", //
"host_stream_id":"111_RongCloudRTC",//此流会渲染到布局的主位置上
"output": {
"video": {
"normal": {
"width": 360,
"height": 640,
"fps": 25,
"bitrate": 800, //kbps
},
"exparams": {
"renderMode":1 //1 裁剪 2 不裁剪,根据该用户分辨率进行渲染
},
"backgroundColor":"0xf1a2c3", //背景颜色, 无此项则保持上次设置
"backgroundPicture" : { //背景图片, 无此项则保持上次设置
"enable":"on", //enable off-关闭, on或者没有, 开启
"fillMode" : 1, //背景图片填充模式, 1-按比例裁剪, 2-不裁剪, 按比例压缩
"picture" : [
{
"uri" : "http://aaa.png", //png图片下载地址
"x" : 0.0, //相对于整体画布的起始位置x坐标
"y" : 0.0, //相对于整体画布的起始位置x坐标
"w" : 1.0, //相对于整体画布的宽
"h" : 1.0 //相对于整体画布的高
},
{
"uri" : "http://bbb.png",
"x" : 0.5,
"y" : 0.5,
"w" : 0.5,
"h" : 0.5
}
]
}
},
"audio": {
"bitrate": 200, //kbps
}
},
"inputFilterMode":4,
"input": {
"video": [
{
"user_id": "111",
"stream_id":"111_RongCloudRTC", //用来区分普通视频和第三方视频,无此项或者值为RongCloudRTC时为普通摄像头视频
//"tiny": false,
"x":0,
"y":0,
"width":180,
"height":320
},
{
"user_id": "2222",
"stream_id":"2222_screenshare",
//"tiny": false,
"x":180,
"y":320,
"width":180,
"height":320
}
],
"audio":[
{
"user_id":"111",
"stream_id":"111_RongCloudRTC"
},
{
"user_id":"2222",
"stream_id":"2222_RongCloudRTC"
}
]
},
"waterMark": {
"enable":"on", // off 关闭, on或者没有enable, 开启
"mixScreen": {
"timestamp": {
"fontSize": 30,
"timezone": 8,
"x": 0.1,
"y": 0.1,
"alpha": 0.8,
"color": "black"
},
"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
}
]
},
"singleScreen": [{
"streamId": "stream1_RongCloudRTC",
"timestamp": {
"alpha": 0.8,
"color": "black",
"fontSize": 30,
"timezone": 8,
"x": 0.1,
"y": 0.1
}
},
{
"streamId": "stream2_RongCloudRTC",
"picture": [{
"uri": "https://ccc",
"w": 0.1,
"h": 0.1,
"x": 0.2,
"y": 0.3
}]
}
]
}
}
}

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

  • code:HTTP 响应正文中的业务码,200 为处理成功。
 {
"code":404,
"errorMessage": "Not a valid API"
}