旁路推流 RESTful API 概览

更新时间 2023/03/13 03:12:41

你可以使用推流 RESTful API 订阅声网频道内的音视频流，将音视频流转码后（或选择不转码），通过标准协议（如 RTMP）推送到 CDN（Content Delivery Network）。这个过程相当于声网通过一个 Converter 将音视频流处理后输出并推到 CDN。

开通服务

第一次使用旁路推流，需要开通服务，步骤如下：

登录控制台，在项目管理页面，选择需要开通输入旁路推流服务的项目，点击配置。
在项目配置页面选择服务配置，在旁路推流模块点击启用。
启用服务端 RESTful。启用后不能关闭。
仔细阅读弹窗提示，点击保存。成功开启旁路推流服务后，启用按钮会切换为配置按钮，用于配置旁路推流。

开通成功后你可以在用量页面看到旁路推流的使用情况。

通过 Basic HTTP 认证

声网 RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入 Authorization 字段。关于如何生成该字段的值，请参考 RESTful API 认证。

工作原理

你可以通过如下方法控制 Converter：

Create：为指定的项目创建一个 Converter，设置转码（或不转码）和推流的相关参数。频道内用户音视频流会按照指定的配置经过 Converter 处理后输出推到 CDN。
Delete：销毁指定的 Converter。销毁该 Converter 后，此频道内用户音视频流将不再经过 Converter 处理并输出推到 CDN。
Update：更新指定的 Converter 配置。
Get: 获取指定 Converter 的推流状态。

在推流 RESTful API 中，Converter 通过 converter 字段设置。

转码并推流
多主播场景下，旁路推流服务将多路音视频流合成一路音视频流，并旁路推流。
字段结构如下图：

字段含义详见下表：

字段	类型	描述
id	String	Converter 的 ID。它是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
name	String，可选	Converter 的名字。
transcodeOptions	JSON Object	Converter 的转码配置。
transcodeOptions.rtcChannel	String	声网频道名称。
transcodeOptions.audioOptions	JSON Object	Converter 的音频转码配置。
transcodeOptions.audioOptions.codecProfile	String	Converter 输出的音频编解码器。
transcodeOptions.audioOptions.sampleRate	Number	Converter 输出的音频编码采样率 (Hz)。
transcodeOptions.audioOptions.bitrate	Number	Converter 输出的音频编码码率 (Kbps)。
transcodeOptions.audioOptions.audioChannels	Number	Converter 输出的音频声道数。
transcodeOptions.audioOptions.rtcStreamUids	JSON Array	参与混音的用户 UID。
transcodeOptions.videoOptions	JSON Object	Converter 的视频转码配置。
transcodeOptions.videoOptions.canvas	JSON Object	视频画布。
transcodeOptions.videoOptions.canvas.width	Number	画布的宽度 (pixel)。
transcodeOptions.videoOptions.canvas.height	Number	画布的高度 (pixel)。
transcodeOptions.videoOptions.canvas.color	Number	画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。
transcodeOptions.videoOptions.layout	JSON Array	画布上视频画面的内容描述。支持 RtcStreamView 和 ImageView 两种元素。
transcodeOptions.videoOptions. layout.RtcStreamView 元素	无	画布上各用户的视频画面。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.rtcStreamUid	Number	视频流所属用户的 UID。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region	JSON Object	用户视频画面在画布上的显示区域。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region.xPos	Number	画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region.yPos	Number	画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region.zIndex	Number	画面的图层编号。取值范围为 [0,100]。`0` 代表最下层的图层。`100` 代表最上层的图层。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region.width	Number	画面的宽度 (pixel)。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.region.height	Number	画面的高度 (pixel)。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.fillMode	String	画面的显示方式。 `fill`：在保持长宽比的前提下，缩放画面，使画面充满容器。 `fit`：在保持长宽比的前提下，缩放画面，使得画面在容器内完整显示出来。
transcodeOptions.videoOptions. layout.RtcStreamView 元素.placeholderImageUrl	String	用户画面的背景图 URL 地址。支持 JPG 和 PNG 格式的图片。当频道内用户停止发布视频流：如果设置了该字段，用户的视频画面将切换为该背景图如果未设置该字段，则显示为画布背景色。
transcodeOptions.videoOptions. layout.ImageView 元素	无	画布上的视频图片，可当水印。
transcodeOptions.videoOptions. layout.ImageView 元素.imageUrl	String	图片的 HTTP(S) URL。
transcodeOptions.videoOptions. layout.ImageView 元素.region	JSON Object	图片在画布上的显示区域。
transcodeOptions.videoOptions. layout.ImageView 元素.region.xPos	Number	图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
transcodeOptions.videoOptions. layout.ImageView 元素.region.yPos	Number	图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
transcodeOptions.videoOptions. layout.ImageView 元素.region.zIndex	Number	图片的图层编号。取值范围为 [0,100]。`0` 代表最下层的图层。`100` 代表最上层的图层。
transcodeOptions.videoOptions. layout.ImageView 元素.region.width	Number	图片的宽度 (pixel)。
transcodeOptions.videoOptions. layout.ImageView 元素.region.height	Number	图片的高度 (pixel)。
transcodeOptions.videoOptions. layout.ImageView 元素.fillMode	String	图片的显示方式。 `fill`：在保持长宽比的前提下，缩放图片，使图片充满容器。 `fit`：在保持长宽比的前提下，缩放图片，使得图片在容器内完整显示出来。
transcodeOptions.videoOptions.layoutType	Number	输出视频的画面布局类型： `0` 或（默认）空：自定义布局，即通过 `transcodeOptions.videoOptions.layout` 设置布局信息。 `1`：垂直布局。指定一个用户在屏幕左侧显示大视窗画面，其他用户以小视窗画面在屏幕右侧垂直排列，详见垂直布局显示。
transcodeOptions.videoOptions.vertical	JSON Object	垂直布局的画面设置信息。当 `layoutType` 为 `1` 时必须设置该参数。
transcodeOptions.videoOptions. vertical.maxResolutionUid	Number	显示大视窗画面的用户 UID。如果未设置 `maxResolutionUid`，则布局刷新时音量最大的用户显示为大视窗画面。 Converter 会 3 秒刷新一次画面布局，如需调整刷新时间间隔，请联系技术支持。未设置 `maxResolutionUid` 可能会导致画面布局每隔 3 秒变化一次，如果需要布局稳定不变，请设置该参数。
transcodeOptions.videoOptions. vertical.fillMode	String	用户画面的显示方式。 `fill`：在保持长宽比的前提下，缩放画面，使画面充满容器。 `fit`：在保持长宽比的前提下，缩放画面，使得画面在容器内完整显示出来。
transcodeOptions.videoOptions. defaultPlaceholderImageUrl	String	默认的用户画面背景图 URL 地址。支持 JPG 和 PNG 格式的图片。当频道内用户停止发布视频流：如果设置了该字段，用户的视频画面将切换为该背景图。如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
transcodeOptions.videoOptions.bitrate	Number	输出视频的编码码率 (Kbps)。
transcodeOptions.videoOptions.frameRate	Number	输出视频的编码帧率 (fps)。
transcodeOptions.videoOptions.gop	Number	输出视频的 GOP。
transcodeOptions.videoOptions. codec	String（可选）	输出视频的编解码规格。不可设置为空。支持如下值： `H.264`（默认值） `H.265`
transcodeOptions.videoOptions. codecProfile	String（可选）	输出视频的编码规格。支持如下值： `high`（默认值）: High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。 `baseline`: Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。 `main`: Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。如果 `codec` 设置为 `H.265`，则 `codecProfile` 默认且必须为 `main`。
transcodeOptions.videoOptions.seiOptions	JSON Object	设置输出视频中携带的用户 SEI 信息。默认为空。不设置则表示不输出 SEI 信息。
transcodeOptions.videoOptions. seiOptions.source	JSON Object	设置 SEI 信息的数据来源。默认为空。
transcodeOptions.videoOptions. seiOptions.source.metadata	Bool	设置是否传入 metadata 类型的 SEI 信息。 true：传入 metadata 类型的 SEI 信息。（默认）false：不传入 metadata 类型的 SEI 信息。
transcodeOptions.videoOptions. seiOptions.source.datastream	Bool	设置是否传入声网 DataStream 类型的 SEI 信息。 true：传入声网 DataStream 类型的 SEI 信息。（默认）false：不传入声网 DataStream 类型的 SEI 信息。
transcodeOptions.videoOptions. seiOptions.source.customized	JSON Object	自定义 SEI 信息。该 SEI 信息会被转换为声网 SEI 规范的 SEI 信息。默认为空。
transcodeOptions.videoOptions. seiOptions.source.customized.prefixForAgoraSei	String	设置 SEI 信息的 payload 前缀。长度必须在 32 个字符以内，默认为空。
transcodeOptions.videoOptions. seiOptions.source.customized.payload	String	设置 SEI 信息的 payload。默认为空。SEI 信息被转换为声网 SEI 规范的 SEI 信息时，该 payload 会被传入到 SEI 的 app_data 中。
transcodeOptions.videoOptions. seiOptions.sink	JSON Object	设置输出 SEI 信息的属性。默认为空。
transcodeOptions.videoOptions. seiOptions.sink.type	Int	设置输出 SEI 信息的 payload type。默认为 100。
rtmpUrl	String	CDN 推流地址。
idleTimeout	Number	Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 `idleTimeout`，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。默认值为 300。
createTs	Number	创建 Converter 时的 Unix 时间戳（秒）。
updateTs	Number	最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
state	String	Converter 的运行状态： `idle`: 推流未开始或已结束。 `connecting`: 正在连接声网推流服务器和 CDN 服务器。 `running`: 正在进行推流。 `failed`: 推流失败。

完整的 Converter 示例如下：

转码推流且自定义布局

{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "name": "show68_vertical",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "codecProfile": "HE-AAC",
                "sampleRate": 48000,
                "bitrate": 128,
                "audioChannels": 1,
                "rtcStreamUids": [
                    201
                ]
            },
            "videoOptions": {
                "canvas": {
                    "width": 360,
                    "height": 640,
                    "color": 0
                },
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        },
                        "fillMode": "fill",
                        "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
                    },
                    {
                        "rtcStreamUid": 202,
                        "region": {
                            "xPos": 0,
                            "yPos": 320,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        }
                    },
                    {
                        "imageUrl": "http://example.agora.io/watchmark.jpg",
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 2,
                            "width": 36,
                            "height": 64
                        },
                        "fillMode": "fit"
                    }
                ],
                "codec": "H.264",
                "codecProfile": "high",
                "frameRate": 15,
                "gop": 30,
                "bitrate": 400,
                "seiOptions": {
                    "source": {
                        "metadata": true,
                        "datastream": true,
                        "customized": {
                            "payload": "example"
                        }
                    },
                    "sink": {
                        "type": 100
                    }
                }
            }
        },
        "rtmpUrl": "rtmp://example.agora.io/live/show68",
        "idleTimeout": 300,
        "createTs": 1591786766,
        "updateTs": 1591786835,
        "state": "connecting"
    }
}

转码推流且垂直布局

{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "name": "show68_vertical",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "codecProfile": "HE-AAC",
                "sampleRate": 48000,
                "bitrate": 128,
                "audioChannels": 1,
                "rtcStreamUids": [
                    201
                ]
            },
            "videoOptions": {
                "canvas": {
                    "width": 360,
                    "height": 640,
                    "color": 0
                },
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 640
                        },
                        "fillMode": "fill",
                        "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
                    }
                ],
                "codec": "H.264",
                "codecProfile": "high",
                "frameRate": 15,
                "gop": 30,
                "bitrate": 400,
                "layoutType": 1,
                "vertical": {
                    "maxResolutionUid": 201,
                    "fillMode": "fill",
                    "refreshIntervalSec": 4
                },
                "defaultPlaceholderImageUrl": "http://example.agora.io/host_placeholder.jpg",
                "seiOptions": {
                    "source": {
                        "metadata": true,
                        "datastream": true,
                        "customized": {
                            "payload": "example"
                        }
                    },
                    "sink": {
                        "type": 100
                    }
                }
            }
        },
        "rtmpUrl": "rtmp://example.agora.io/live/show68",
        "idleTimeout": 300
    }
}

不转码推流
单主播场景下，你可以选择不转码推流。
字段结构如下图：

字段含义详见下表：

字段	类型	描述
id	String	Converter 的 ID。它是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
name	String，可选	Converter 的名字。
rawOptions	JSON Object	Converter 不转码的相关配置。
rawOptions.rtcChannel	String	声网频道名称。
rawOptions.rtcStreamUid	Number	要推送的音视频流所属用户的 UID。
rtmpUrl	String	CDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。
idleTimeout	Number（可选）	Converter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 `idleTimeout`，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。默认值为 300。

一个完整的不转码推流 Converter 示例如下：

{
    "converter": {
      "name": "show68_vertical",
      "rawOptions": {
        "rtcChannel": "show68",
        "rtcStreamUid": 201
      },
      "rtmpUrl": "rtmp://vid-218.push.chinanetcenter.broadcastapp.agora.io/live/global",
      "idleTimeout": 120
    }
}

这篇文章对你有帮助吗？

是

否