# 更新云端播放器 (/zh-CN/api-reference/api-ref/media-pull/update)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

更新指定云端播放器的可变配置。

- OpenAPI: /openapi/media-pull/media-pull.zh-CN.yaml
- Operation ID: patch-region-v1-projects-appId-cloud-player-players-playerid
- Method: PATCH
- Path: /{region}/v1/projects/{appId}/cloud-player/players/{playerid}
- Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/cloud-player/players/{playerid}

## Servers

- https://api.sd-rtn.com

`Update` 方法用于更新指定的云端播放器。

声网目前仅支持更新如下字段：

- `audioOptions`：更新音频转码配置。请求 Body 中需要传入音量和音频场景字段。
- `audioOptions.volume`：仅更新音量，不更新音频场景。请求 Body 中不需要传入音频场景字段。
- `isPause`：控制播放的暂停和恢复。
- `streamUrl`：更新在线媒体流地址。
- `seekPosition`：更新点播文件的播放位置。
- `tempo`：播放倍速。


## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `X-Request-ID` (header, optional, string) - UUID（通用唯一识别码），标识本次请求。传入该字段后，声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值，声网服务器会自动生成一个 UUID 传入。
- `sequence` (query, required, number) - Update 请求的序列号。取值需要大于或等于 0。请确保后一次 Update 请求的序列号大于前一次 Update 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新云端播放器。

**推荐用法**：声网推荐你在第一次调用 Update 时，将 `sequence` 填 `0`。在第二次调用 Update 时，将 `sequence` 填 `1`。在第三次调用 Update 时，将 `sequence` 填 `2`。依次类推。声网服务器会按照最新 Update 请求（即最大的序列号）更新云端播放器。
- `region` (path, required, string) - 云端播放器所在的区域，必须与创建云端播放器设置的 `region` 一致。
- `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
- `playerid` (path, required) - 云端播放器的 ID。

## Request body

- `player` (object)
  - `player.audioOptions` (object) - 云端播放器的音频转码配置。
    - `player.audioOptions.volume` (number) - 云端播放器的的音量大小。取值范围 [0,200]。默认值为 100，表示原始音量。
      - Default: `100`
      - Range: `[0, 200]`
    - `player.audioOptions.profile` (number) - 音频场景。用于设置音频采样率、码率、编码模式和声道数。
- `0`：默认设置：
  - 通信场景下，该选项代表指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  - 直播场景下，该选项代表指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
- `1`：SPEECH_STANDARD。指定 32 kHz 采样率，语音编码, 单声道，编码码率最大值为 18 Kbps。
- `2`：MUSIC_STANDARD。指定 48 kHz 采样率，音乐编码, 单声道，编码码率最大值为 64 Kbps。
- `4`：MUSIC_HIGH_QUALITY。指定 48 kHz 采样率，音乐编码, 单声道，编码码率最大值为 96 Kbps。
      - Default: `0`
  - `player.isPause` (boolean) - 是否暂停播放媒体流源文件：
- `true`：暂停播放媒体流源文件。
- `false`：（默认）播放媒体流源文件。
> [!CAUTION]
> 在暂停状态下，不会触发 `idelTimeout` 倒计时销毁播放器，因此暂停时也会正常计费。如果不再需要输入在线媒体流，可直接调用[销毁云端播放器](/zh-CN/api-reference/api-ref/media-pull/delete)结束播放任务，不要停留在暂停状态，否则会一直产生费用。
    - Default: `false`
  - `player.streamUrl` (string) - 在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/HLS 地址，且长度在 1024 个字符以内。

**注意**：如需发布图片到声网频道，则设置 `streamUrl` 为你需要发布的图片 URL，云端播放器会将图片转换为视频，并发布到声网频道。目前支持 JPEG 和 PNG 格式的图片。你可以通过 `videoOptions` 设置视频转码相关参数。
    - Max length: `1024`
  - `player.seekPosition` (number) - 指定点播文件的播放位置（秒）。默认值为 0，表示从点播文件起始位置播放。必须小于音视频时长。
    - Default: `0`
  - `player.tempo` (number) - 播放倍速，支持如下取值：
- 0.5
- 0.75
- 1.0（默认）
- 1.25
- 1.5
- 1.75
- 2.0
    - Default: `1`
    - Format: `float`

### Request body example

```json
{
  "player": {
    "audioOptions": {
      "volume": 10
    },
    "isPause": false,
    "streamUrl": "http://example",
    "seekPosition": 40
  }
}
```

## Responses

### 200

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

No schema.
### 非 2XX

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

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

## Response examples

### 非 2XX

```json
{
  "reason": "Resource is not found and destroyed."
}
```