# 更新指定 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 中包含的字段集合。
\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": "描述请求失败的具体原因。" } ```