启动云端旁路转推

更新时间：2024-08-15

接口描述

本接口用于启动云端旁路转推任务。

获取转推资源ID后，可以在资源ID有效期内调用启动云端旁路转推接口，对房间中用户进行直播转推。调用该接口成功后，可以从响应体中获得一个转推任务ID，该转推任务ID是一次转推任务的唯一标识。

请求结构

POST /v1/livestreamingBypass/start HTTP/1.1

请求头域

除公共头域外，无其它特殊头域。

请求参数

参数名	类型	是否必需	描述
resourceId	String	是	转推资源ID
appId	String	是	应用ID
roomName	String	是	房间名
clientUserId	Long	否	单路转推时需要，表示要转推的客户端uid
pushUrl	String	是	直播推流地址，只支持RTMP协议
taskExpiredHour	Integer	否	转推任务接口可以调用的时效性，单位小时。从成功启动转推任务开始计算，超时后无法调用查询、更新和停止等接口，但是转推任务不会停止。参数的单位是小时，默认24小时，最大可设置72小时（3天），最小设置1小时。
bypassCfg	LiveStreamingBypassConfig	否	转推基础配置
+bypassMode	String	否	转推模式。 0表示单流转推，1表示混流转推，默认值为0。单路转推：将指定的clientUserId用户的音视频流直接转推到直播服务，不会进行转码。混流转推：将房间内多个用户的音视频混流转码后转推到转推服务，目前一个混流转推中最多添加6路用户流。
+streamMode	String	否	转推流模式。 0表示音频+视频，1表示纯音频，2表示纯视频，默认值为0。
+maxIdleSeconds	Integer	否	最大续播时长，单位：秒。默认值为 30 秒，该值需大于等于 5 秒、且小于等于 7200秒(2小时)。当超过最大续播时长，没有用户流参与转推，自动停止转推。注意：混流模式下，续播等待期内会补黑帧和静音帧继续转推，单路模式下则不会转推。在续播等待期内，单路和混流转推会按照音频时长收取转推/混流费用。
+targetOrExcludeStreamsCfg	TargetOrExcludeStreamsConfig	否	参与任务的音频流和视频流的黑白名单，仅在 bypassMode="1" 时有效，详细结构见下文。
mixTranscodingCfg	CloudMixTranscodingCfg	否	混流转码配置，用于配置输出音视频编码、布局和水印等。
+encodeCfg	EncodeConfig	否	编码配置，详细结构见下文。
+layoutCfg	LayoutConfig	否	布局配置，详细结构见下文。
+watermarkCfgs	WatermarkConfig数组	否	全局水印配置，最多支持10个全局水印，详细结构见下文。

TargetOrExcludeStreamsConfig 结构

对混流类型任务可以设置音频和视频的黑白名单，黑白名单的内容可以是具体的 userId，也可以是特定的匹配规则。音频白名单和音频黑名单不能同时设置，视频亦然。支持通过设置 ".*$" 通配符规则，来前缀匹配用户的 userId；支持通过设置 "#allstream#" 规则来匹配所有用户。

参数名	类型	是否必需	描述
targetAudioUserIds	String 数组	否	音频流白名单，指定哪些用户的音频流参与该任务，例如["1", "2", "3"], 代表 userId 1，2，3的音频流会参与任务；["1.*$"], 代表 userId 前缀为1的用户音频流参与任务；["#allstream#"] 代表所有用户的音频流都会参与任务。默认不填房间内所有的音频流都会参与任务，但实际参与任务的用户数不超过37。
excludeAudioUserIds	String 数组	否	音频流黑名单，指定哪些用户的音频流不参与该任务，例如["1", "2", "3"], 代表 userId 1，2，3的音频流不参与任务；["1.*$"], 代表 userId 前缀为1的用户音频不参与任务；["#allstream#"] 代表所有用户的音频流都不会参与任务。默认不填房间内所有的音频流都会参与任务，但实际参与任务的用户数不超过37。
targetVideoUserIds	String 数组	否	视频流白名单，指定哪些用户的视频流参与该任务，具体规则同音频白名单。默认不填房间内所有的视频流都会参与任务，但实际参与任务的用户数不超过37。
excludeVideoUserIds	String 数组	否	视频流黑名单，指定哪些用户的视频流不参与该任务，具体规则同音频黑名单。默认不填房间内所有的视频流都会参与任务，但实际参与任务的用户数不超过37。

黑白名单示例

预期效果	推荐设置
所有用户音频流和视频流都需要参与任务	无需设置黑白名单相关参数
所有用户音频流都需要参与，只有 123 用户和 4 开头用户的视频流需要参与	targetVideoUserIds: ["123", "4.*$"]
所有用户音频流都需要参与，只有 123 用户和 4 开头用户的视频流需要排除	excludeVideoUserIds: ["123", "4.*$"]
用户 123 的音频流需要排除，只有用户 456 的视频流需要参与	excludeAudioUserIds: ["123"] targetVideoUserIds: ["456"]
所有用户音频流都需要参与，所有用户视频流都需要排除	excludeVideoUserIds: ["#allstream#"] 如果不需要使用水印等视频模式特有的功能，将 streamMode 设置为 "1" 也可达到同样的效果。

EncodeConfig 结构

参数名	类型	是否必需	描述
width	Integer	否	混流输出画布的宽，默认值为1280，取值范围[0,1920]，单位为像素值。需要在streamMode包含视频时才有效。
height	Integer	否	混流输出画布的高，默认值为720，取值范围[0,1920]，单位为像素值。需要在streamMode包含视频时才有效。
videoBitrate	Integer	否	视频码率，单位 kb/s，默认值1200。需要在streamMode包含视频时才有效。

LayoutConfig结构

streamMode包含视频时，layoutCfg才有效。

参数名	类型	是否必需	描述
layout	String	是	布局模板，默认值为 side_by_side_primary。可取值 side_by_side_primary（主次平铺），side_by_side_equal（相等平铺），picture_in_picture_bottom（画中画），custom（自定义布局）。
mainUserId	Long	否	混流后主画面窗口对应的userId。只在 side_by_side_primary 和 picture_in_picture_bottom 布局生效。如果未设置，会自动按照先后顺序选择主画面。
renderMode	String	否	用户窗口绘制模式，在主次平铺、相等平铺和画中画布局中有效，可取值0和1，0表示缩放后裁剪，1表示缩放并显示黑底，默认值为1。
defaultPlaceholderImageUrl	String	否	窗口默认占位图 URL 地址。 - 当用户视频流未发布、暂停采集时，窗口会使用占位图来填充； - 支持 jpg 和 png 格式； - 当占位图和窗口尺寸不一致时，会依据 `renderMode` 配置在窗口中绘制占位图。
generalWindowCfgs	GeneralWindowConfig 数组	否	通用布局配置，在任意布局模板下都生效，详细结构见下文。可用于对每个小窗口设置属性，比如流级别水印。
customWindowCfgs	CustomWindowConfig 数组	否	窗口自定义布局设置，在 layout=custom 时生效，详细结构见下文。

GeneralWindowConfig结构

参数名	类型	是否必需	描述
userId	Long	是	窗口对应的客户端 userId
watermarkCfgs	WatermarkConfig数组	否	流级别水印设置，置于用户的小窗口内。每个用户最多支持10个流级别水印。详细结构见下文。流级别水印建议使用相对坐标。另外出于效果考虑，不建议使用流级别图片类型水印。

CustomWindowConfig 结构

如果某个混流源的 userId 在 customWindowCfgs 结构中不存在，那么会将该用户窗口平铺到整个画布上。

参数名	类型	是否必需	描述
userId	Long	是	窗口对应的客户端 userId
renderMode	String	否	窗口绘制模式，可取值0和1，0表示缩放后裁剪，1表示缩放并显示黑底，默认值为1。
xpos	int	否	该窗口在输出时矩形左上角的X坐标，单位为像素值，默认值为0。
ypos	int	否	该窗口在输出时矩形左上角的Y坐标，单位为像素值，默认值为0。
zorder	int	否	窗口在输出时的层级，不填默认为0。zorder越大，处于画面越上方，取值为0时窗口位于最底层。
width	int	否	窗口在输出时的宽度，单位为像素值，默认值为0。
height	int	否	窗口在输出时的高度，单位为像素值，默认值为0。
placeholderImageUrl	String	否	窗口占位图 URL 地址。 - 自定义布局中，可以对不同窗口设置不同的占位图，会覆盖窗口默认占位图设置。 - 支持 jpg 和 png 格式； - 当占位图和窗口尺寸不一致时，会依据自定义布局的 `renderMode` 配置在窗口中绘制占位图。

WatermarkConfig结构

bypassMode="0"时，不会进行转码，全局水印和流级别水印均无效。

参数名	类型	是否必需	描述
type	String	是	水印类型，可取值image，text，clock。image 表示图片水印，text 表示文字水印，clock 表示时间戳水印。
posMode	Integer	否	水印坐标类型，支持取值0或1，默认值为0。当 posMode=0 时，xpos、ypos 为绝对值坐标，单位是像素值；当 posMode=1时，xpos、ypos 表示坐标占全局窗口/用户窗口width、height的百分比，取值范围[0,1]，最多精确到小数点后3位。流级别水印建议使用 posMode=1。
xpos	Float	是	该水印在输出时矩形左上角的X坐标，默认值为0。详见 posMode 描述。
ypos	Float	否	该水印在输出时矩形左上角的Y坐标，默认值为0。详见 posMode 描述。
imageUrl	String	否	type=image 时必须携带，图片水印 http url，水印图片只支持缩放。
width	Integer	否	type=image 时生效，该水印在输出时的宽度，单位为像素值，不填默认为图片宽度。
height	Integer	否	type=image 时生效，该水印图片在输出时的高度，单位为像素值，不填默认为图片高度。
color	String	否	水印颜色，type=clock 或 type=text 时生效，采用big-endian ARGB的方式，并使用16进制表示。背景颜色取值共10位，前2位固定为0x，接下来2位表示透明度，后6位表示颜色值，例如0xFF000000。
size	Integer	否	字体大小，type=clock 或 type=text 时生效。
font	string	否	字体类型，type=clock 或 type=text 时生效，暂时只支持取值Normal。
text	String	否	文字水印内容，type=text 时表示文字水印内容，type=clock 时在时间戳前面添加该文字。
textTransfer	Boolean	否	表示 text 字段是否进行转义，默认值为false。如果 textTransfer=true，那么 text 中 %D 会被转义成客户端用户的 display （昵称）属性。例如 text="用户_%D"，display="Bob"，textTransfer=true，text 内容会被转义成 "用户_Bob"。
timeFormat	String	否	时间戳格式，默认 %Y-%m-%d %H:%M:%S，时间戳格式参考：https://man7.org/linux/man-pages/man3/strftime.3.html

响应头域

除公共头域外，无其它特殊头域。

响应参数

字段名	类型	描述
taskId	String	转推任务ID

请求示例

单路转推示例

POST /v1/livestreamingBypass/start HTTP/1.1
host: rtc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "resourceId":"testResourceId",
    "appId":"testApp",
    "roomName":"65432112341",
    "clientUserId": 123456,
    "pushUrl": "rtmp://***/***/***",
    "taskExpiredHour":24,
    "bypassCfg":{
        "bypassMode":"0",
        "streamMode":"0",
        "maxIdleSeconds":60
    }
}

混流转推示例

POST /v1/livestreamingBypass/start HTTP/1.1
host: rtc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "resourceId":"testResourceId",
    "appId":"testApp",
    "roomName":"65432112341",
    "pushUrl": "rtmp://***/***/***",
    "taskExpiredHour":24,
    "bypassCfg":{
        "bypassMode":"1",
        "streamMode":"0",
        "maxIdleSeconds":60
    },
    "mixTranscodingCfg":{
    	"layoutCfg": {
    		"layout": "side_by_side_primary",
    		"mainUserId": 123456
    	}
    }
}

自定义布局混流转推示例

POST /v1/livestreamingBypass/start HTTP/1.1
host: rtc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "resourceId":"testResourceId",
    "appId":"testApp",
    "roomName":"65432112341",
    "pushUrl": "rtmp://***/***/***",
    "taskExpiredHour":24,
    "bypassCfg":{
        "bypassMode":"1",
        "streamMode":"0",
        "maxIdleSeconds":60
    },
    "mixTranscodingCfg":{
    	 "layoutCfg":{
            "layout":"custom",
            "customWindowCfgs":[
                {
                    "userId":"123",
                    "renderMode":"0",
                    "xpos":300,
                    "ypos":0,
                    "zorder":1,
                    "width":300,
                    "height":300
                },
                {
                    "userId":"456",
                    "renderMode":"1",
                    "xpos":300,
                    "ypos":400,
                    "zorder":1,
                    "width":300,
                    "height":300
                }
            ]
        }
    }
}

包含全局水印和流级别水印配置示例

POST /v1/livestreamingBypass/start HTTP/1.1
host: rtc.baidubce.com
content-type: application/json
authorization: {bce-authorization-string}
x-bce-request-id: {bce-request-id}
{
    "resourceId":"testResourceId",
    "appId":"testApp",
    "roomName":"65432112341",
    "pushUrl": "rtmp://***/***/***",
    "taskExpiredHour":24,
    "bypassCfg":{
        "bypassMode":"1",
        "streamMode":"0",
        "maxIdleSeconds":60
    },
    "mixTranscodingCfg":{
    	"encodeCfg":{
            "width":1280,
            "height":720,
            "videoBitrate":1200
        },
        "layoutCfg":{
            "layout":"side_by_side_primary",
            "mainUserId": 123123,
            "generalWindowCfgs": [
                {
                    "userId": 123456,
                    "watermarkCfgs": [
                         {  
                            "type":"text",
                            "posMode": 1,
                            "text":"用户_%D",
                            "textTransfer": true,
                            "xpos":0.1,
                            "ypos":0.1,
                            "font":"Normal",
                            "size":22,
                            "color":"0xFFFFFFFF"
                        },
                        {
                            "type":"clock",
                            "posMode": 1,
                            "xpos":0.1,
                            "ypos":0.5,
                            "timeFormat":"%Y-%m-%d %H:%M:%S",
                            "text":"北京时间：",
                            "font":"Normal",
                            "size":22,
                            "color":"0xFFFFFFFF"
                        }
                    ]
                }
            ]
        },
        "watermarkCfgs":[
            {
                "type":"image",
                "imageUrl":"https://brtc-tools.cdn.bcebos.com/shuiyin.jpeg",
                "xpos":0,
                "ypos":0,
                "width":200,
                "height":200
            },
            {
                "type":"text",
                "text":"Hello world!",
                "xpos":0,
                "ypos":100,
                "font":"Normal",
                "size":22,
                "color":"0xFF000000"
            },
            {
                "type":"clock",
                "timeFormat":"%Y-%m-%d %H:%M:%S",
                "text":"北京时间：",
                "xpos":0,
                "ypos":200,
                "font":"Normal",
                "size":22,
                "color":"0xFF000000"
            }
        ]
    }
}

响应示例

HTTP/1.1 200 OK
x-bce-request-id: b06a9214-04d6-4a08-9f5d-966b04604cfb
date: Mon, 05 Sep 2022 03:25:43 GMT
transfer-encoding: chunked
content-type: application/json;charset=UTF-8
cache-control: no-cache
{
    "taskId": "testTaskId"
}

获取云端旁路转推资源

查询云端旁路转推

百度智能云

实时音视频 RTC