human: 如何处理七牛云的实时音视频合流转推API

gpt: [实时音视频](https://developer.qiniu.com/rtc) > API 文档 >
[服务端API](https://developer.qiniu.com/rtc/api/12000/the-service-api) > 合流转推API

#  合流转推API

最近更新时间: 2023-07-10 18:10:28

# 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 __](https://developer.qiniu.com/rtc/12205/rtc-recorded-directly)  
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
            }
        } // 具体哪个视频会参与合流不可预期，但是只会有一个参与。
    ]
    
    

以上内容是否对您有帮助？