创建 Converter
更新时间不可用
在项目中创建一个 Converter，用于处理音视频流并推流到 CDN。
https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtmp-converters鉴权
regionstring创建 Converter 的区域。声网支持分区域创建 Converter。请保证设置的 region 与你的 CDN 源站在同一个区域且传入 region 的值为小写。目前支持以下区域：
cn：中国大陆ap：除中国以外的亚洲区域na：北美eu：欧洲
appIdstring声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
regionHintIpstringCDN 源站 IP 地址，必须为有效的 IPv4 地址。该参数可以保障 RTMP 流的稳定性。
Content-Typestringapplication/json
X-Request-IDstringUUID（通用唯一识别码），标识本次请求。推荐你赋值，赋值后，声网服务器会在响应 Header 中返回一个对应的 X-Custom-Request-ID 字段，你可以用此进行问题排查。如果你不赋值，那么声网服务器会自动生成一个 UUID 并在响应 Header 中返回一个对应的 X-Request-ID 字段。
Create 请求可创建转码推流和不转码推流的 Converter。
转码推流时需设置如下字段。
namestringConverter 的名字。长度必须在 64 个字符以内，支持的字符集范围如下：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- "-", "_"
注意
- 不传值时该字段为空。
- 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码
409(Conflict)。 - 为避免重复创建多个 Converter 重复推流，请使用
name字段管理指定项目下的 Converter。声网推荐你以“频道名（rtcChannel）”和 “Converter 特性”组合来给name赋值。如show68_horizontal和show68_vertical，分别代表在频道show68中创建的用户画面为水平布局和和垂直布局的 Converter。
转码推流的配置。
rtcChannelstring声网频道名称，即 Converter 处理的流所属频道的名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Converter 的音频转码配置。
注意：
- 该字段仅需在有音频的场景下设置。如果有音频但是无需自定义音频配置，那么将该字段设为空，即
"audioOptions": {}。 - 暂时只支持不超过 3 名用户进行混音，如果参与混音的用户人数大于 3，请联系技术支持。
rtcStreamUidsarray<number>指定参与混音的用户 UID。
注意：
- 如果
audioOptions中无该字段，声网将频道内所有用户音频进行混音。 - 如果
audioOptions中存在该字段且值为空，则代表不混合任何用户的音频流。
codecProfilestringConverter 输出的音频编解码规格。支持如下值：
"LC-AAC": MPEG-4 AAC LC。"HE-AAC": High-Efficiency AAC。
sampleRatenumberConverter 输出的音频编码采样率 (Hz)，支持取值如下：
320004410048000
bitratenumberConverter 输出的音频编码码率 (Kbps)。取值范围为 [32,128]。推荐取值如下：
- 如果音频编解码器为 LC-AAC，推荐取值范围为 [32,112]。
- 如果音频编解码器为 HE-AAC，推荐取值范围为 [40,96]。
audioChannelsnumberConverter 输出的音频声道数，支持取值如下：
1：单声道。2：双声道。
参与混音的用户音量。
注意：发起 Update 请求更新指定用户音量时，每次请求成功都会将其他用户（非指定用户）的音量恢复成默认音量 100。
rtcStreamUidnumber待设置音量的混音用户 UID。
注意：填入的 UID 需要存在于 rtcStreamUids（参与混音的用户 UID 数组）中，否则请求失败。
volumenumber指定的混音用户的音量。取值范围为 [0,200]。
Converter 的视频转码配置。
注意：该字段仅需在有视频的场景下设置。并且在音视频场景下，该字段不能为空。
视频画布的配置。
widthnumber画布的宽度 (pixel)。取值范围为 [66,1920]。
heightnumber画布的高度 (pixel)。取值范围为 [66,1920]。
colornumber画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。取值范围为 [0,16777215]。默认值为 0，即黑色。
layoutTypenumber输出视频的画面布局类型：
0或空：自定义布局，即通过layout自定义布局。1：垂直布局，即通过vertical指定一个用户在屏幕左侧显示大视窗画面，其他用户以小视窗画面在屏幕右侧垂直排列，详见设置垂直布局。垂直布局时，通过Update请求只能更新rtmpUrl。
画布上各用户的视频画面的配置。
注意
仅需在 layoutType 为自定义布局时设置 layout 字段。
rtcStreamUidnumber用户 UID。
用户视频画面在画布上的显示区域。超出画布的视频画面会被裁剪。
xPosnumber画面在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。
yPosnumber画面在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。
zIndexnumber画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
widthnumber画面的宽度 (pixel)。
heightnumber画面的高度 (pixel)。
placeholderImageUrlstring用户画面的背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流，如果设置了该字段，用户的视频画面将切换为该背景图，否则会显示为画布背景色。
alphanumber透明度。0.0 代表完全透明，1.0 代表完全不透明。
画布上视频图片的配置。画布上视频图片可充当水印。
注意
仅需在 layoutType 为自定义布局时设置 layout 字段。
imageUrlstring图片的 URL，以 http 或 https 开头。支持 JPG 和 PNG 格式的图片。
图片在画布上的显示区域。超出画布的图片会被裁剪。
xPosnumber图片在画布上的 x 坐标 (pixel)。以画布左上角为原点，x 坐标为图片左上角相对于原点的横向位移。
yPosnumber图片在画布上的 y 坐标 (pixel)。以画布左上角为原点，y 坐标为图片左上角相对于原点的纵向位移。
zIndexnumber图片的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。
widthnumber图片的宽度 (pixel)。
heightnumber图片的高度 (pixel)。
alphanumber透明度。0.0 代表完全透明，1.0 代表完全不透明。
垂直布局的画面配置。
注意
仅需在 layoutType 为垂直布局时设置 vertical 字段。
maxResolutionUidnumber显示大视窗画面的用户 UID。
注意：如果未设置，则每次布局画面刷新时将音量最大的用户显示为大视窗画面。为维持大视窗画面稳定，建议你设置该字段。
refreshIntervalSecnumber布局画面刷新的时间间隔，单位为秒。
defaultPlaceholderImageUrlstring默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时，背景图的行为如下：
- 如果设置了该字段，用户的视频画面将切换为该背景图。
- 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
bitratenumber输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。推荐取值详见常用视频属性。
frameRatenumber输出视频的编码帧率 (fps)。取值范围为 [1,30]。推荐取值详见常用视频属性。
gopnumber输出视频的 GOP。默认值为 framerate 的 2 倍。
codecstring输出视频的编解码规格。不可设置为空。支持如下值：
"H.264""H.265"
codecProfilestring输出视频的编码规格。支持如下值：
"high": High 级别的视频编码规格，一般用于广播及视频碟片存储，高清电视。"baseline": Baseline 级别的视频编码规格，一般用于低阶或需要额外容错的应用，比如视频通话、手机视频等。"main": Main 级别的视频编码规格，一般用于主流消费类电子产品，如 mp4、便携的视频播放器、PSP 和 iPad 等。 注意：如果codec为 H.265，那么该字段默认值且唯一支持取值为"main"。如果codec为 H.264，那么该字段默认值为"high"。
设置携带的用户 SEI（Supplemental Enhancement Information）信息。默认为空。不设置则不携带用户 SEI 信息。
设置 SEI 信息的数据来源。默认为空。
metadataboolean是否传入 Metadata 类型的 SEI 信息。
true：传入。false：不传入。
datastreamboolean是否传入 Datastream 类型的 SEI 信息。
true：传入。false：不传入。
设置输出的 SEI 信息。默认为空。
typenumber输出 SEI 信息的 payload 的 type。
rtmpUrlstringCDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 {server}/{stream_key} 的规则来拼接 RTMP URL。
idleTimeoutnumberConverter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。
jitterBufferSizeMsnumber音频接收端到网络抖动缓冲端的网络延迟 (ms)。取值范围 [0,1000]。旁路推流服务会根据你设置的值，以 100 为单位向上取整。
注意：声网建议你不要设为 0。设为 0 表示不使用抖动缓冲延迟，弱网情况下可能导致音画质量问题，
不转码推流时需设置如下字段。
namestringConverter 的名字。长度必须在 64 个字符以内，支持的字符集范围如下：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- "-", "_"
注意
- 不传值时该字段为空。
- 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码
409(Conflict)。 - 为避免重复创建多个 Converter 重复推流，请使用
name字段管理指定项目下的 Converter。声网推荐你以“频道名（rtcChannel）”和 “Converter 特性”组合来给name赋值。如show68_horizontal和show68_vertical，分别代表在频道show68中创建的用户画面为水平布局和和垂直布局的 Converter。
不转码推流配置。
rtcChannelstring声网频道名称，即 Converter 处理的流所属频道的名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
rtcStreamUidnumber音视频流所属用户的 UID。
rtmpUrlstringCDN 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 {server}/{stream_key} 的规则来拼接 RTMP URL。
idleTimeoutnumberConverter 处于空闲状态的最大时长（秒）。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 idleTimeout，Converter 自动销毁，推流停止。取值范围为 [5,86400]。如果设置值小于 5，则默认为 5；如果设置值大于 86400，则默认为 86400。
jitterBufferSizeMsnumber音频接收端到网络抖动缓冲端的网络延迟 (ms)。取值范围 [0,1000]。旁路推流服务会根据你设置的值，以 100 为单位向上取整。
注意：声网建议你不要设为 0。设为 0 表示不使用抖动缓冲延迟，弱网情况下可能导致音画质量问题，
响应
如果状态码为 2XX，请求成功。
响应 Header
响应 Body
idstringConverter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
createTsstring创建 Converter 时的 Unix 时间戳（秒）。
updateTsstring最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
statestringConverter 的运行状态：
"connecting": 正在连接声网推流服务器和 CDN 服务器。"running": 正在进行推流。"failed": 推流失败。
fieldsstringJSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于描述返回的 converter object 中包含的字段集合。
示例：
{
"converter": {
"id": "4c014467d647bb87b60b719f6fa57686",
"createTs": 1591786766,
"updateTs": 1591788746,
"state": "running"
},
"fields": "id,createTs,updateTs,state"
}
在本示例中，fields 描述返回的 converter object 中包含 id、createTs、updateTs、state 字段。
请求示例
curl --request POST \
--url "https://api.sd-rtn.com/:region/v1/projects/:appId/rtmp-converters" \
--header 'Authorization: Basic <credentials>' \
--header 'X-Request-ID: <string>' \
-H 'Content-Type: application/json' \
-d '{
"converter": {
"name": "show68_vertical",
"transcodeOptions": {
"rtcChannel": "show68",
"audioOptions": {
"codecProfile": "HE-AAC",
"sampleRate": 48000,
"bitrate": 128,
"audioChannels": 1,
"rtcStreamUids": [
201,
202
],
"volumes": [
{
"volume": 50,
"rtcStreamUid": 201
},
{
"volume": 150,
"rtcStreamUid": 202
}
]
},
"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/live/show68",
"idleTimeout": 300
}
}'响应示例
{
"converter": {
"id": "Converter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。",
"createTs": "创建 Converter 时的 Unix 时间戳（秒）。",
"updateTs": "最近一次更新 Converter 配置时的 Unix 时间戳（秒）。",
"state": "Converter 的运行状态：\n- `\"connecting\"`: 正在连接声网推流服务器和 CDN 服务器。\n- `\"running\"`: 正在进行推流。\n- `\"failed\"`: 推流失败。"
},
"fields": "JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述返回的 `converter` object 中包含的字段集合。<p>\n示例：\n```json\n{\n \"converter\": {\n \"id\": \"4c014467d647bb87b60b719f6fa57686\",\n \"createTs\": 1591786766,\n \"updateTs\": 1591788746,\n \"state\": \"running\"\n },\n \"fields\": \"id,createTs,updateTs,state\"\n}\n```\n在本示例中，`fields` 描述返回的 `converter` object 中包含 `id`、`createTs`、`updateTs`、`state` 字段。"
}