# 获取指定 Converter 的推流状态 (/zh-CN/api-reference/api-ref/media-push/get) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 获取指定 Converter 的推流状态。 - OpenAPI: /openapi/media-push/media-push.zh-CN.yaml - Operation ID: get-region-v1-projects-appId-rtmp-converters-converterId - Method: GET - Path: /{region}/v1/projects/{appId}/rtmp-converters/{converterId} - Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/rtmp-converters/{converterId} ## Servers - https://api.sd-rtn.com ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, required, string) - `application/json` - `X-Request-ID` (header, optional, string) - UUID(通用唯一识别码),标识本次请求。推荐你赋值,赋值后,声网服务器会在响应 Header 中返回一个对应的 `X-Custom-Request-ID` 字段,你可以用此进行问题排查。如果你不赋值,那么声网服务器会自动生成一个 UUID 并在响应 Header 中返回一个对应的 `X-Request-ID` 字段。 - `region` (path, required, string) - Converter 所在的区域,必须与创建 Converter 时设置的 `region` 一致。 - `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 - `converterId` (path, required, string) - Converter 的 ID。 ## Request body No request body. ## Responses ### 2XX 如果状态码为 2XX,请求成功。 `Get` 请求可获取**转码**推流和**不转码**推流的 Converter。 - `converter` (object) - **转码**推流时返回如下字段。 - `converter.name` (string) - Converter 的名称。 - `converter.transcodeOptions` (object) - **转码**推流的配置。 - `converter.transcodeOptions.rtcChannel` (string) - 声网频道名称,即 Converter 处理的流所属频道的名称。 - `converter.transcodeOptions.audioOptions` (object) - Converter 的音频转码配置。 - `converter.transcodeOptions.audioOptions.rtcStreamUids` (array) - 指定参与混音的用户 UID。 **注意**: - 如果 `audioOptions` 中无该字段,声网将频道内所有用户音频进行混音。 - 如果 `audioOptions` 中存在该字段且值为空,则代表不混合任何用户的音频流。 - `converter.transcodeOptions.audioOptions.rtcStreamUids.items` (number) - `converter.transcodeOptions.audioOptions.codecProfile` (string) - Converter 输出的音频编解码规格。支持如下值: - `"LC-AAC"`: MPEG-4 AAC LC。 - `"HE-AAC"`: High-Efficiency AAC。 - Default: `LC-AAC` - `converter.transcodeOptions.audioOptions.sampleRate` (number) - Converter 输出的音频编码采样率 (Hz),支持取值如下: - `32000` - `44100` - `48000` - Default: `48000` - `converter.transcodeOptions.audioOptions.bitrate` (number) - Converter 输出的音频编码码率 (Kbps)。 - `converter.transcodeOptions.audioOptions.audioChannels` (number) - Converter 输出的音频声道数,支持取值如下: - `1`:单声道。 - `2`:双声道。 - Default: `1` - `converter.transcodeOptions.audioOptions.volumes` (array) - 参与混音的用户音量。 - `converter.transcodeOptions.audioOptions.volumes.items` (object) - `converter.transcodeOptions.audioOptions.volumes.items.rtcStreamUid` (number) - 待设置音量的混音用户 UID。 - `converter.transcodeOptions.audioOptions.volumes.items.volume` (number) - 指定的混音用户的音量。 - `converter.transcodeOptions.videoOptions` (object) - Converter 的视频转码配置。 - `converter.transcodeOptions.videoOptions.canvas` (object) - 视频画布的配置。 - `converter.transcodeOptions.videoOptions.canvas.width` (number) - 画布的宽度 (pixel)。 - `converter.transcodeOptions.videoOptions.canvas.height` (number) - 画布的高度 (pixel)。 - `converter.transcodeOptions.videoOptions.canvas.color` (number) - 画布的背景色。RGB 颜色值,以十进制数表示。如 255 代表蓝色。 - `converter.transcodeOptions.videoOptions.layoutType` (number) - 输出视频的画面布局类型: - `0` 或空:自定义布局,即通过 `layout` 自定义布局。 - `1`:垂直布局,即通过 `vertical` 指定一个用户在屏幕左侧显示大视窗画面,其他用户以小视窗画面在屏幕右侧垂直排列,详见[设置垂直布局](/zh-CN/realtime-media/media-push/build/configure-media-stream/vertical-streaming)。垂直布局时,通过 `Update` 请求只能更新 `rtmpUrl`。 - Default: `0` - `converter.transcodeOptions.videoOptions.layout` (array) - 画布上各用户的视频画面的配置。 **注意**:仅在 `layoutType` 为自定义布局时返回 `layout` 字段。 - `converter.transcodeOptions.videoOptions.layout.items` (object) - `converter.transcodeOptions.videoOptions.layout.items.rtcStreamUid` (number, required) - 用户 UID。 - `converter.transcodeOptions.videoOptions.layout.items.region` (object, required) - 用户视频画面在画布上的显示区域。超出画布的视频画面会被裁剪。 - `converter.transcodeOptions.videoOptions.layout.items.region.xPos` (number, required) - 画面在画布上的 x 坐标 (pixel)。以画布左上角为原点,x 坐标为画面左上角相对于原点的横向位移。 - `converter.transcodeOptions.videoOptions.layout.items.region.yPos` (number, required) - 画面在画布上的 y 坐标 (pixel)。以画布左上角为原点,y 坐标为画面左上角相对于原点的纵向位移。 - `converter.transcodeOptions.videoOptions.layout.items.region.zIndex` (number, required) - 画面的图层编号。取值范围为 [0,100]。`0` 代表最下层的图层。`100` 代表最上层的图层。 - `converter.transcodeOptions.videoOptions.layout.items.region.width` (number, required) - 画面的宽度 (pixel)。 - `converter.transcodeOptions.videoOptions.layout.items.region.height` (number, required) - 画面的高度 (pixel)。 - `converter.transcodeOptions.videoOptions.layout.items.fillMode` (string) - 用户视频画面的显示模式: - `"fill"`:在保持宽高比的前提下,缩放画面,并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989)。 - `"fit"`:在保持宽高比的前提下,缩放画面,使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782)。 - Default: `fill` - `converter.transcodeOptions.videoOptions.layout.items.placeholderImageUrl` (string) - 用户画面的背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流,如果设置了该字段,用户的视频画面将切换为该背景图,否则会显示为画布背景色。 - `converter.transcodeOptions.videoOptions.layout.items.alpha` (number) - 透明度。`0.0` 代表完全透明,`1.0` 代表完全不透明。 - Default: `1` - Format: `float` - Range: `[0, 1]` - `converter.transcodeOptions.videoOptions.vertical` (object) - 垂直布局的画面配置。 **注意**:仅在 `layoutType` 为垂直布局时返回 `vertical` 字段。 - `converter.transcodeOptions.videoOptions.vertical.maxResolutionUid` (number) - 显示大视窗画面的用户 UID。 **注意**:如果未设置,则每次布局画面刷新时将音量最大的用户显示为大视窗画面。为维持大视窗画面稳定,建议你设置该字段。 - `converter.transcodeOptions.videoOptions.vertical.fillMode` (string) - 用户视频画面的显示模式: - `"fill"`:在保持宽高比的前提下,缩放画面,并居中剪裁。详见[示意图](https://web-cdn.agora.io/docs-files/1628837665989)。 - `"fit"`:在保持宽高比的前提下,缩放画面,使其完整显示。详见[示意图](https://web-cdn.agora.io/docs-files/1628837708782)。 - Default: `fill` - `converter.transcodeOptions.videoOptions.vertical.refreshIntervalSec` (number) - 布局画面刷新的时间间隔,单位为秒。 - Default: `3` - Range: `[1, 30]` - `converter.transcodeOptions.videoOptions.defaultPlaceholderImageUrl` (string) - 默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时,背景图的行为如下: - 如果设置了该字段,用户的视频画面将切换为该背景图。 - 如果未设置该字段,用户的视频画面先显示为该用户视频最后一帧,布局刷新后显示为画布背景色。 - `converter.transcodeOptions.videoOptions.bitrate` (number) - 输出视频的编码码率 (Kbps)。 - `converter.transcodeOptions.videoOptions.frameRate` (number) - 输出视频的编码帧率 (fps)。 - `converter.transcodeOptions.videoOptions.gop` (number) - 输出视频的 GOP。默认值为 `framerate` 的 2 倍。 - `converter.transcodeOptions.videoOptions.codec` (string) - 输出视频的编解码规格。不可设置为空。支持如下值: - `"H.264"` - `"H.265"` - Default: `H.264` - `converter.transcodeOptions.videoOptions.codecProfile` (string) - 输出视频的编码规格。支持如下值: - `"high"`: High 级别的视频编码规格,一般用于广播及视频碟片存储,高清电视。 - `"baseline"`: Baseline 级别的视频编码规格,一般用于低阶或需要额外容错的应用,比如视频通话、手机视频等。 - `"main"`: Main 级别的视频编码规格,一般用于主流消费类电子产品,如 mp4、便携的视频播放器、PSP 和 iPad 等。 **注意**:如果 `codec` 为 H.265,那么该字段默认值且唯一支持取值为 `"main"`。如果 `codec` 为 H.264,那么该字段默认值为 `"high"`。 - `converter.transcodeOptions.videoOptions.seiOptions` (object) - 携带的用户 SEI(Supplemental Enhancement Information)信息。 - `converter.transcodeOptions.videoOptions.seiOptions.source` (object) - SEI 信息的数据来源。 - `converter.transcodeOptions.videoOptions.seiOptions.source.metadata` (boolean) - 是否传入 Metadata 类型的 SEI 信息。 - `true`:传入。 - `false`:不传入。 - Default: `false` - `converter.transcodeOptions.videoOptions.seiOptions.source.datastream` (boolean) - 是否传入 Datastream 类型的 SEI 信息。 - `true`:传入。 - `false`:不传入。 - Default: `false` - `converter.transcodeOptions.videoOptions.seiOptions.source.customized` (object) - 自定义 SEI 信息,会被转换为[声网 SEI 规范](/zh-CN/reference/faq/quality/sei)的 SEI 信息。 - `converter.transcodeOptions.videoOptions.seiOptions.source.customized.prefixForAgoraSei` (string) - 自定义 SEI 信息的 payload 前缀。长度必须在 32 个字符以内。默认为空。 - `converter.transcodeOptions.videoOptions.seiOptions.source.customized.payload` (string) - 自定义 SEI 信息的 payload。长度必须在 4096 个字符以内。默认为空。 自定义 SEI 信息会被转换为[声网 SEI 规范](/zh-CN/reference/faq/quality/sei)的 SEI 信息。此处设置的 payload 会被转换至声网 SEI 规范中定义的 `app_data` 中。 - `converter.transcodeOptions.videoOptions.seiOptions.sink` (object) - 输出的 SEI 信息。 - `converter.transcodeOptions.videoOptions.seiOptions.sink.type` (number) - 输出 SEI 信息的 payload 的 `type`。 - Default: `100` - `converter.rtmpUrl` (string) - CDN 推流地址。 - `converter.idleTimeout` (string) - Converter 处于空闲状态的最大时长(秒)。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 `idleTimeout`,Converter 自动销毁,推流停止。 - `converter.jitterBufferSizeMs` (number) - 音频接收端到网络抖动缓冲端的网络延迟 (ms)。旁路推流服务会根据你设置的值,以 100 为单位向上取整。 ### 非 2XX 如果状态码不为 2XX,请求失败。 - `reason` (string) - 描述请求失败的具体原因。 ## Response examples ### 2XX ```json { "converter": { "name": "Converter 的名称。", "transcodeOptions": { "rtcChannel": "声网频道名称,即 Converter 处理的流所属频道的名称。", "audioOptions": { "rtcStreamUids": [ 0 ], "codecProfile": "LC-AAC", "sampleRate": 48000, "bitrate": 0, "audioChannels": 1, "volumes": [ { "rtcStreamUid": 0, "volume": 0 } ] }, "videoOptions": { "canvas": { "width": 0, "height": 0, "color": 0 }, "layoutType": 0, "layout": [ { "rtcStreamUid": 0, "region": { "xPos": 0, "yPos": 0, "zIndex": 0, "width": 0, "height": 0 }, "fillMode": "fill", "placeholderImageUrl": "用户画面的背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流,如果设置了该字段,用户的视频画面将切换为该背景图,否则会显示为画布背景色。", "alpha": 1 } ], "vertical": { "maxResolutionUid": 0, "fillMode": "fill", "refreshIntervalSec": 3 }, "defaultPlaceholderImageUrl": "默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时,背景图的行为如下:\n- 如果设置了该字段,用户的视频画面将切换为该背景图。\n- 如果未设置该字段,用户的视频画面先显示为该用户视频最后一帧,布局刷新后显示为画布背景色。", "bitrate": 0, "frameRate": 0, "gop": 0, "codec": "H.264", "codecProfile": "输出视频的编码规格。支持如下值:\n- `\"high\"`: High 级别的视频编码规格,一般用于广播及视频碟片存储,高清电视。\n- `\"baseline\"`: Baseline 级别的视频编码规格,一般用于低阶或需要额外容错的应用,比如视频通话、手机视频等。\n- `\"main\"`: Main 级别的视频编码规格,一般用于主流消费类电子产品,如 mp4、便携的视频播放器、PSP 和 iPad 等。\n**注意**:如果 `codec` 为 H.265,那么该字段默认值且唯一支持取值为 `\"main\"`。如果 `codec` 为 H.264,那么该字段默认值为 `\"high\"`。", "seiOptions": { "source": { "metadata": false, "datastream": false, "customized": { "prefixForAgoraSei": "自定义 SEI 信息的 payload 前缀。长度必须在 32 个字符以内。默认为空。", "payload": "自定义 SEI 信息的 payload。长度必须在 4096 个字符以内。默认为空。
\n自定义 SEI 信息会被转换为[声网 SEI 规范](/zh-CN/reference/faq/quality/sei)的 SEI 信息。此处设置的 payload 会被转换至声网 SEI 规范中定义的 `app_data` 中。" } }, "sink": { "type": 100 } } } }, "rtmpUrl": "CDN 推流地址。", "idleTimeout": "Converter 处于空闲状态的最大时长(秒)。空闲指 Converter 处理的音视频流所对应的所有用户均已离开频道。当 Converter 处于空闲状态时长大于 `idleTimeout`,Converter 自动销毁,推流停止。", "jitterBufferSizeMs": 0 } } ``` ### 非 2XX ```json { "reason": "描述请求失败的具体原因。" } ```