1.接口说明
1.1创建任务
请求地址: POST /v4/apps/{appid}/rooms/{roomid}/jobs
输入参数: Job对象，请参考2.1
返回值:
当HTTP返回码为200时，表明请求成功，同时会返回任务ID：
{"status":"OK","id":"basic-ulwelrjl12"}
当HTTP码非200时，表明请求失败：
{"error":"invalid input"}
使用样例:
如下参数创建输出分辨率为720p只有一个用户的视频，同时设置背景及水印
{
"type": "basic",
"inputs": [
{
"userId": "user-a",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 1080,
"h": 720
}
},
{
"kind": "image",
"url": "http://qiniu.com/background.png",
"position": {
"z": 0,
"x": 0,
"y": 0,
"w": 1080,
"h": 720
}
},
{
"kind": "image",
"url": "http://qiniu.com/watermark.png",
"position": {
"z": 65535,
"x": 0,
"y": 0,
"w": 100,
"h": 72
}
}
],
"config": {
"height": 720,
"width": 1080,
"fps": 25,
"kbps": 2000
},
"outputs": [
{
"type": "rtmp",
"url": "rtmp://qiniu.com/stream"
}
]
}
如下参数转推创建一个用户的视频
{
"type": "simple",
"inputs": [
{
"userId": "testuser"
}
],
"outputs": [
{
"type": "rtmp",
"url": "rtmp://qiniu.com/stream"
}
]
}
1.2更新任务
请求地址: POST /v4/apps/{appid}/rooms/{roomid}/jobs/update
输入参数: Job对象，请参考2.1
返回值:
当HTTP返回码为200时，表明请求成功，同时会返回任务ID：
{"status":"OK","id":"basic-ulwelrjl12"}
当HTTP码非200时，表明请求失败：
{"error":"invalid input"}
使用样例:
以下参数将上面任务更新为两个用户并列显示的视频
{
"id": "basic-ulwelrjl12", // 更新需要传递之前返回的任务ID
"type": "basic",
"inputs": [
{
"userId": "user-a",
"position": {
"x": 0,
"y": 0,
"w": 540,
"h": 720,
"z": 0
}
},
{
"userId": "user-b",
"position": {
"x": 540,
"y": 0,
"w": 540,
"h": 720,
"z": 0
}
}
],
"config": {
"height": 720,
"width": 1080,
"fps": 25,
"kbps": 2000
},
"outputs": [
{
"type": "rtmp",
"url": "rtmp://qiniu.com/stream"
}
]
}
1.3 删除任务
请求地址: POST /v4/apps/{appid}/rooms/{roomid}/jobs/stop
输入参数:
{"id":"basic-ulwelrjl12"}
返回值:
当HTTP返回码为200时，表明请求成功，同时会返回任务ID：
{"status":"OK","id":"basic-ulwelrjl12"}
当HTTP码非200时，表明请求失败：
{"error":"invalid input"}
2.参数说明
2.1 Job对象
| 名称 | 类型 | 是否可选 | 描述 | 备注 |
|---|---|---|---|---|
| type | String | 必填 | 固定填写: basic/simple | basic为合流任务，simple为转推任务 |
| inputs | Input数组 | 必填 | 数组，用于指明输入媒体信息 | 请参考2.1.1 input对象 |
| outputs | Output数组 | 必填 | 用于指明输出信息，目前只支持单个RTMP类型输出，更多输出功能开发中。 | 请参考2.1.2 output对象 |
| config | Config对象 | 可选 simple下不需要 | 配置项 | 请参考2.1.3 config对象 |
2.1.1 input对象
Job为simple的时候，只支持一个input对象，且input对象只支持设置userId参数
| 名称 | 类型 | 是否可选 | 可用type | 描述 |
|---|---|---|---|---|
| kind | String | 可选 | basic | 默认为media类型，可选值为image/media，当为media时userId必填，当为image时imageUrl必填 |
| userId | String | 根据kind决定是否必填 | basic/simple | 用户加入房间适用用户名 |
| tag | String | 可选 | basic | 当用户同时发布多路音视频是用于区分不同的输入,请详细参考3.3 Input和Tag说明 |
| url | String | 根据kind决定是否必填 | basic | 图片地址 |
| position | Position对象 | 可选 | basic | 当任务类型为basic，并且需要对多路视频进行合并操作时必填，指明视频位置 |
| stretchMode | String | 必填 | basic |
2.1.2 output对象
| 名称 | 类型 | 是否可选 | 描述 | 备注 |
|---|---|---|---|---|
| type | String | 必填 | 请填写：rtmp | 支持类型，为rtmp、file, file类型不会直播而是直接存储进七牛云存储，请参考直接录制API |
| url | String | 必填 | 指明输出地址 |
2.1.3 Config对象
| 名称 | 类型 | 是否可选 | 描述 | 备注 |
|---|---|---|---|---|
| audioOnly | bool | 可选 | 是否仅做音频合流，当audioOnly为true时，fps，height，width，kbps参数均无意义，可不填。 | |
| fps | int | 如果audioOnly不为true则必填 | 指定输出帧率 | |
| kbps | int | 如果audioOnly不为true则必填 | 指定输出码率 | |
| height | int | 如果audioOnly不为true则必填 | 指定输出高度 | 必须为2的倍数 |
| width | int | 如果audioOnly不为true则必填 | 指定输出宽度 | 必须为2的倍数 |
| stretchMode | string | 可选 | 整个任务的stretchMode默认值 | |
| fps | bool | 可选 | 是否保留用户最后一帧，默认为false |
2.1.4 Position对象
| 名称 | 类型 | 是否可选 | 描述 | 备注 |
|---|---|---|---|---|
| x | int | 必填 | ||
| y | int | 必填 | ||
| z | int | 可选 | 0~65535 | |
| w | int | 必填 | 必须为2的倍数 | |
| h | int | 必填 | 必须为2的倍数 |
3.补充说明
3.1 Basic和Simple区别
- Basic为合流，支持将多路音视频合成一路。
- Simple为转推，只支持输入一个用户的一路音频+视频，并且不支持更新。
3.2 StretchMode拉伸模式
取值范围如下:
- aspectFill: 默认值, 视频通过保持长宽比来填充视图的大小。视频的某些部分可能被剪切。
- aspectFit: 通过保持宽高比(可能显示黑色边框)，视频被缩放以适应视图的大小。
- scaleToFit: 视频被缩放以填充视图的大小，而不需要保持长宽比
当config中传递其他部分不传时，均使用config中的stretchMode作为拉伸模式。
3.3 原水印背景图功能
- 背景图：在inputs内指定kind为image，position中z指定为0即可。
- 水印：在inputs内指定kind为image，position中z指定为65535即可。
3.4 Input及tag说明
七牛实时音视频服务在发布track时支持设置自定义Tag,参考:https://developer.qiniu.com/rtc/11434/UniappQNScreenVideoTrackConfig。Tag的主要功能是用于区分一个用户发布的多路音视频，建议使用方式如下：
- 如果每个用户只会发布一路音视频，建议不要设置tag，这样在输入input时tag留空即可。
- 如果每个用户会发布一路视频，多路音频，也建议不要设置tag，这样在输入input时留空即可。
- 如果存在每个用户发布多个音视频的情况，需要涉及tag，请务必在合流时设置相同tag才可以正确识别。
每个Input可以代表N路音频+最多1路视频，详细举例：
3.4.1 用户只发布一路音视频，并且没有设置tag：
[{
"userId": "user-a",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 1080,
"h": 720
}
}] // 只需要一个input对象。
3.4.2 用户发布一路音视频，分别设置tag为video和audio：
[{
"userId": "user-a",
"tag":"video",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 1080,
"h": 720
}
},
{
"userId": "user-a",
"tag":"audio"
}] // 需要为不同的tag独立指定input对象，音频不需要设置position信息
3.4.3 用户发布两个视频，设置tag为空和screen，同时发布一个音频tag为空。
[{
"userId": "user-a",
"tag":"screen",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 540,
"h": 720
}
}, // 代表tag为screen的视频输入。
{
"userId": "user-a",
"position": {
"z": 1,
"x": 540,
"y": 0,
"w": 540,
"h": 720
}
} // 代表tag为空的视频和音频
]
3.4.4 用户发布两个视频，设置tag为camera和screen，同时发布一个音频tag为camera
[{
"userId": "user-a",
"tag":"screen",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 540,
"h": 720
}
}, // 代表tag为screen的视频输入。
{
"userId": "user-a",
"tag":"camera",
"position": {
"z": 1,
"x": 540,
"y": 0,
"w": 540,
"h": 720
}
} // 代表tag为camera的视频和音频
]
同时需要注意不可预期行为
3.4.5 用户发布两个视频，均未设置tag或者设置为相同tag。
[{
"userId": "user-a",
"position": {
"z": 1,
"x": 0,
"y": 0,
"w": 540,
"h": 720
}
} // 具体哪个视频会参与合流不可预期，但是只会有一个参与。
]
文档反馈
(如有产品使用问题，请 提交工单)
售前 
售后 