# 更新指定 Converter (/zh-CN/api-reference/api-ref/media-push/update)

> 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: patch-region-v1-projects-appId-rtmp-converters-converterId
- Method: PATCH
- 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

`Update` 请求的 Body 字段设置较为复杂，请阅读如下文档后再进一步了解本文的字段说明：

- [更新不转码推流](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-no-transcode)
- [更新转码推流](/zh-CN/realtime-media/media-push/build/configure-media-stream/update-transcode)
- [更新混音音量](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-volume)
- [更新 SEI 信息](/zh-CN/realtime-media/media-push/build/configure-media-stream/set-sei)


## 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` 字段。
- `sequence` (query, optional, number) - `Update` 请求的序列号。取值需要大于或等于 0。请确保后一次 `Update` 请求的序列号大于前一次 `Update` 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新 Converter。

**推荐用法**：声网推荐你在第一次调用 `Update` 时，将 `sequence` 填 `0`。在第二次调用 `Update` 时，将 `sequence` 填 `1`。在第三次调用 `Update` 时，将 `sequence` 填 `2`。依次类推。声网服务器会按照最新 `Update` 请求（即最大的序列号）更新 Converter。
- `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

`Update` 请求可更新**转码**推流和**不转码**推流的 Converter。

> [!CAUTION]
> `Update` 不支持更新 Converter 的如下配置：
> - `name`
> - `idleTimeOut`
> - `transcodeOptions.rtcChannel`
> - `transcodeOptions.audioOptions.codecProfile`
> - `transcodeOptions.audioOptions.sampleRate`
> - `transcodeOptions.audioOptions.bitrate`
> - `transcodeOptions.audioOptions.audioChannels`
> - `transcodeOptions.videoOptions.codec`
> - `transcodeOptions.videoOptions.codecProfile`

- `converter` (object)
  - `converter.transcodeOptions` (object) - **转码**推流的配置。
    - `converter.transcodeOptions.audioOptions` (object) - Converter 的音频转码配置。
      - `converter.transcodeOptions.audioOptions.rtcStreamUids` (array) - 指定参与混音的用户 UID。

**注意**：
- 如果 `audioOptions` 中无该字段，声网将频道内所有用户音频进行混音。
- 如果 `audioOptions` 中存在该字段且值为空，则代表不混合任何用户的音频流。
        - `converter.transcodeOptions.audioOptions.rtcStreamUids.items` (number)
      - `converter.transcodeOptions.audioOptions.volumes` (array) - 参与混音的用户音量。

**注意**：发起 `Update` 请求更新指定用户音量时，每次请求成功都会将其他用户（非指定用户）的音量恢复成默认音量 `100`。
        - `converter.transcodeOptions.audioOptions.volumes.items` (object)
          - `converter.transcodeOptions.audioOptions.volumes.items.rtcStreamUid` (number, required) - 待设置音量的混音用户 UID。

**注意**：填入的 UID 需要存在于 `rtcStreamUids`（参与混音的用户 UID 数组）中，否则请求失败。
          - `converter.transcodeOptions.audioOptions.volumes.items.volume` (number) - 指定的混音用户的音量。取值范围为 [0,200]。
            - Default: `100`
    - `converter.transcodeOptions.videoOptions` (object) - Converter 的视频转码配置。
      - `converter.transcodeOptions.videoOptions.canvas` (object) - 视频画布的配置。
        - `converter.transcodeOptions.videoOptions.canvas.width` (number) - 画布的宽度 (pixel)。取值范围为 [66,1920]。
        - `converter.transcodeOptions.videoOptions.canvas.height` (number) - 画布的高度 (pixel)。取值范围为 [66,1920]。
        - `converter.transcodeOptions.videoOptions.canvas.color` (number) - 画布的背景色。RGB 颜色值，以十进制数表示。如 255 代表蓝色。取值范围为 [0,16777215]。默认值为 0，即黑色。
          - Default: `0`
      - `converter.transcodeOptions.videoOptions.layout` (array) - 画布上各用户的视频画面的配置。

> [!CAUTION]
> 仅需在 `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.defaultPlaceholderImageUrl` (string) - 默认的用户画面背景图 URL 地址。支持 JPG、PNG 和 GIF 格式的图片。当频道内用户停止发布视频流时，背景图的行为如下：
- 如果设置了该字段，用户的视频画面将切换为该背景图。
- 如果未设置该字段，用户的视频画面先显示为该用户视频最后一帧，布局刷新后显示为画布背景色。
      - `converter.transcodeOptions.videoOptions.bitrate` (number) - 输出视频的编码码率 (Kbps)。取值范围为 [1,10000]。推荐取值详见[常用视频属性](/zh-CN/api-reference/media-push/restful/api/video-profile)。
      - `converter.transcodeOptions.videoOptions.frameRate` (number) - 输出视频的编码帧率 (fps)。取值范围为 [1,30]。推荐取值详见[常用视频属性](/zh-CN/api-reference/media-push/restful/api/video-profile)。
        - Default: `15`
      - `converter.transcodeOptions.videoOptions.gop` (number) - 输出视频的 GOP。默认值为 `framerate` 的 2 倍。
      - `converter.transcodeOptions.videoOptions.seiOptions` (object) - 设置携带的用户 SEI（Supplemental Enhancement Information）信息。默认为空。不设置则不携带用户 SEI 信息。
        - `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)
            - `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 推流地址。必须为有效的 RTMP 地址，且长度在 1024 个字符以内。如果你从 OBS 推流更换为旁路推流，需要按照 `{server}/{stream_key}` 的规则来拼接 RTMP URL。
  - `converter.jitterBufferSizeMs` (number) - 音频接收端到网络抖动缓冲端的网络延迟 (ms)。取值范围 [0,1000]。旁路推流服务会根据你设置的值，以 100 为单位向上取整。

**注意**：声网建议你不要设为 `0`。设为 `0` 表示不使用抖动缓冲延迟，弱网情况下可能导致音画质量问题，
    - Default: `1000`
- `fields` (string, required) - JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述更新的 `converter` object 中包含的字段集合。

示例：
```json
{
    "converter": {
        "rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
    },
    "fields": "rtmpUrl"
}
```
在本示例中，`fields` 描述 `converter` object 中更新 `rtmpUrl` 字段。

**注意**：更新多个字段时，`fields` 中填写的各字段必须用英文逗号分隔，且逗号后无空格。例如，`"fields": "a,b"`。

### Request body example

```json
{
  "converter": {
    "rtmpUrl": "rtmp://example.agora.io/live/show68_backup"
  },
  "fields": "rtmpUrl"
}
```

## Responses

### 2XX

如果状态码为 2XX，请求成功。

- `converter` (object)
  - `converter.id` (string) - Converter 的 ID，是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 Converter。
  - `converter.createTs` (string) - 创建 Converter 时的 Unix 时间戳（秒）。
  - `converter.updateTs` (string) - 最近一次更新 Converter 配置时的 Unix 时间戳（秒）。
  - `converter.state` (string) - Converter 的运行状态：
- `"connecting"`: 正在连接声网推流服务器和 CDN 服务器。
- `"running"`: 正在进行推流。
- `"failed"`: 推流失败。
- `fields` (string) - JSON 编码方式的字段掩码，详见[谷歌 protobuf FieldMask 文档](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask)。用于描述返回的 `converter` object 中包含的字段集合。

示例：
```json
{
    "converter": {
      "id": "4c014467d647bb87b60b719f6fa57686",
      "createTs": 1591786766,
      "updateTs": 1591788746,
      "state": "running"
    },
    "fields": "id,createTs,updateTs,state"
}
```
在本示例中，`fields` 描述返回的 `converter` object 中包含 `id`、`createTs`、`updateTs`、`state` 字段。
### 非 2XX

如果状态码不为 2XX，请求失败。

- `message` (string) - 描述请求失败的具体原因。

## Response examples

### 2XX

```json
{
  "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` 字段。"
}
```
### 非 2XX

```json
{
  "message": "描述请求失败的具体原因。"
}
```