跳到主要内容

开始录制

开始录制,同时设置录制服务的各项参数。

开通服务

云端录制为付费增值服务。在使用云端录制 API 之前,请确认已在控制台开通云端录制服务,并已完成相关配置。详见配置云端录制服务

请注意,录制触发方式需要配置为手动才能使用 API 控制录制服务。

请求方法

POST: http(s)://api.rong-api.com/rtc/record/start.json

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

正文参数

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

参数类型必传说明
sessionIdString当前通话的会话 ID。您可以通过融云服务端回调获取该 sessionId,请参见房间状态同步
extraString扩展字段,可以作为您业务方面的标记。录制回调服务会带上此字段给到您的应用 Server。
configObject指定云端录制配置,支持录制分流,或者录制 mcu 合流。
config.recordTypeNumber指定录制类型(默认值 1)。录制模式按录制流的区别分为以下两种类型:
  • 1录制分流:支持每个用户的流分别录制;支持将房间内所有用户的流合并录制,可指定录制文件的合流布局
  • 2录制 mcu 合流:直接录制服务端合流后的直播流。录制结果与观众观看的合流一致,合流布局已经在执行合流操作时指定。仅在开通音视频直播服务后可用。
config.modeNumber指定录制分流的模式,仅在录制类型为录制分流config.recordType 值为 1)时有效:
  • 0:Single 模式 -- 全录;
  • 1:Single 模式 -- 仅录视频;
  • 2:Single 模式 -- 仅录音频;
  • 3:Mix 模式 -- 全录;
  • 4:Mix 模式 -- 仅录视频;
  • 5:Mix 模式 -- 仅录音频;
  • 6:单人 Mix 模式 -- 视频;
Single 模式下均只生成纯音频、纯视频文件的录制结果。Mix 模式下会生成多道分流合并录制的文件。单人 Mix 模式会以用户为单位生成包含音视频的文件。详见知识库文档配置云端录制服务中的录制模式详解
config.videoResolutionString指定录制分流的分辨率,仅在录制类型为录制分流config.recordType 值为 1)时有效。共 12 个可选项:
  • 256x144 / 144x256
  • 320x240 / 240x320
  • 480x320 / 320x480
  • 640x480 / 480x640
  • 1280x720 / 720x1280
  • 1920x1080 / 1080x1920
默认值
  • 在所有 single 录制模式下(config.mode 取值 0/1/2),默认值为客户端第一次发流的分辨率。
  • 在所有 mix 录制模式下(config.mode 取值 3/4/5/6),默认值为 640x480
config.videoFormatString指定录制的视频输出格式,可选项:mkvmp4flvhls

注意:部分视频/音频格式组合可能与播放器软件存在兼容性问题。如果出现播放问题(例如,视频无声),建议更换当前平台使用的播放器进行排查,再根据排查结果确定合适的音频/视频格式组合。
config.audioFormatString指定录制的音频输出格式,可选项:aacmp3

注意:部分视频/音频格式组合可能与播放器软件存在兼容性问题。如果出现播放问题(例如,视频无声),建议更换当前平台使用的播放器进行排查,再根据排查结果确定合适的音频/视频格式组合。
config.mixLayoutNumber指定录制分流时的子视频流布局方式,仅在录制类型为录制分流config.recordType 值为 1)时有效,且仅在 mix 录制模式下(config.mode 取值 3/4/5/6)有效。可选项:
  • 1:自定义布局
  • 2:悬浮布局
  • 3:自适应布局
config.sliceMinNumber指定录制切片文件时长(单位为分钟)。可选值:306090120
config.renderModeNumber指定视频的填充方式,可选项:
  • 1:等比放大填充(相对视频源会有裁剪)
  • 2:等比缩放(可能会有黑边)
config.hostUserIdString指定主画面的用户 ID,仅在录制类型为录制分流config.recordType 值为 1)时有效。
  • 使用自定义布局时(config.mixLayout1),不需要传此字段;但必须通过 config.input 字段传入自定义布局的相关参数。
  • 必填)使用悬浮布局时(config.mixLayout2),该 ID 将被放置在悬浮布局的背景上;
  • 必填)使用自适应布局时(config.mixLayout3),该 ID 将放置在自适应布局的左上角图像上;
录制类型为录制 mcu 分流config.recordType 值为 2)时请勿传入该字段,否则有可能导致错误。
config.hostStreamIdString指定主画面的视频流 ID,仅在录制类型为录制分流config.recordType 值为 1)时有效。
  • 使用自定义布局时(config.mixLayout1),不需要传此字段;但必须通过 config.input 字段传入自定义布局的相关参数。
  • 必填)使用悬浮布局时(config.mixLayout2),使用该用户的视频渲染主背景;
  • 必填)使用自适应布局时(config.mixLayout3),使用该用户的视频渲染左上角的画面;
录制类型为录制 mcu 分流config.recordType 值为 2)时请勿传入该字段,否则有可能导致错误。
config.inputObject指定合并录制多道分流时的自定义布局参数,内部包含子视频流的数组(video),仅在录制类型为录制分流config.recordType 值为 1)时有效。

注意:使用自定义布局时(config.mixLayout1),必须通过此字段指定合并录制结果中的子视图的视频流、坐标、宽高等参数。

详见下方 config.input 对象说明
config.mcuConfigObject指定录制 mcu 合流的配置,内部包含 mcu 录制模式选项,以及录制合流时使用的分辨率选项。
config.mcuConfig.modeNumber指定录制 mcu 合流的模式,仅在录制类型为录制 mcu 合流config.recordType 值为 2)时有效。可选项:
  • 1:MCU 合流仅录视频模式
  • 2:MCU 合流仅录音频模式
  • 6:MCU 合流全录模式
config.mcuConfig.videoResolutionString指定录制 mcu 合流的分辨率,仅在录制类型为录制 mcu 合流config.recordType 值为 2)时有效。共 12 个可选项:
  • 256x144 / 144x256
  • 320x240 / 240x320
  • 480x320 / 320x480
  • 640x480 / 480x640
  • 1280x720 / 720x1280
  • 1920x1080 / 1080x1920
  • config.input 对象说明:该对象描述了在合并录制多道分流时,自定义布局子视频流的相关参数:

    参数类型必传说明
    videoArray用于设置合流布局每个用户视频子窗口的位置和大小。
    video[i].userIdString子窗口的用户 ID
    video[i].streamIdString子窗口的视频流 ID
    video[i].xNumber浮点数。子窗口的起始点 x 轴相对坐标。即距离左边框的像素点 / videoResolution 的宽度
    video[i].yNumber浮点数。子窗口的起始点 y 轴相对坐标。即距离上边框的像素点 / videoResolution 的高度
    video[i].widthNumber浮点数。子窗口的相对宽度。即子窗口的宽度除以 videoResolution 的宽度
    video[i].heightNumber浮点数。子窗口的相对高度。即子窗口的高度除以 videoResolution 的高度

请求示例

POST /rtc/record/start.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Timestamp: 1585127132438
Nonce: 14314
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Room-Id: room1
Content-Type: application/json

{
"sessionId":"aaa",
"config":{
"recordType": 1,
"mode":3,
"videoResolution":"640x480",
"videoFormat":"mkv",
"audioFormat":"aac",
"mixLayout":1,
"sliceMin":60,
"renderMode":1,
"hostUserId":"abc",
"hostStreamId":"111_RongCloudRTC",
"input":{
"video":[
{
"userId":"111",
"streamId":"111_RongCloudRTC",
"x":0,
"y":0,
"width":0.5,
"height":0.5
},
{
"userId":"2222",
"streamId":"2222_RongCloudRTC",
"x":0.5,
"y":0.5,
"width":0.5,
"height":0.5
}
]
},
"mcuConfig":{
"mode": 6
"videoResolution":"640x480"

}
}
}

返回结果

返回值返回类型说明
codeNumber返回码,200 为正常。
errorMessageString错误信息。
recordIdString录制 ID,每次录制任务的唯一标识。可以用于录制回调或文件切片关联。

返回结果示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"code":200,
"errorMessage":"Success",
"recordId":"b8bed381888091ff4e6a42d6f3b8782a"
}