# 获取指定 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 个字符以内。默认为空。<p>\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": "描述请求失败的具体原因。"
}
```