UpdatePlayer

POST

https://cloud-player-api.zego.im/

调用本接口更新指定云端播放器的播放进度、音频转码参数、视频转码参数等信息。

说明

调用频率限制：20 次/秒

Request

Query Parameters

Action string必填

可选值: [UpdatePlayer]

接口原型参数

https://cloud-player-api.zego.im?Action=UpdatePlayer

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

application/json

Body

required

PlayerId string必填

云端播放器唯一标识 ID，通过 CreatePlayer 返回。 调用本接口时，请确保 PlayerId 是已存在的，否则可能会出错。

Sequence number必填

请求的序列号，用于保证时序，同个播放器任务的参数修改需要保证序列号的递增。例如："Sequence"：1。ZEGO 服务器将按照最新的配置来更新云端播放器。

StreamUrl string

可选值: <= 1024 characters

媒体资源的地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。

注意

此处需要根据创建云端播放器时，创建的是单播放器还是列表播放器来选择。

创建单播放器时 StreamUrl 参数可选填，StreamUrlList 不可选；

创建列表播放器时 StreamUrlList 参数可选填，StreamUrl 不可选。

如果此处选填了 StreamUrl 或者 StreamUrlList ，其他的参数会被忽略。

StreamUrlList string[]

媒体资源列表地址。更新列表将重置媒体资源列表，并立即从新列表的首个资源开始播放。

注意

此处需要根据创建云端播放器时，创建的是单播放器还是列表播放器来选择。

创建单播放器时 StreamUrl 参数可选填，StreamUrlList 不可选；

创建列表播放器时 StreamUrlList 参数可选填，StreamUrl 不可选。

如果此处选填了 StreamUrl 或者 StreamUrlList ，其他的参数会被忽略。

BackupStreamUrl string

可选值: <= 1024 characters

媒体资源的备用地址，必须是有效的 HTTP/HTTPS 地址，且长度在 1024 字节以内。当 StreamUrl 参数中的地址访问失败时，云端播放器会尝试访问备用地址。

VideoOptions object

视频转码参数配置。请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

Width number

可选值: >= 1 and <= 3000

视频宽度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px。 请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流；该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

Height number

可选值: >= 1 and <= 3000

视频高度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px。 请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流；该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

VideoBitrate number

可选值: >= 1 and <= 50000

视频码率，取值范围为 [1, 50000]，单位为 kbps。 请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

AudioOptions object

音频转码参数配置。请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

AudioBitrate number

可选值: >= 1 and <= 192

音频码率，范围为 [1, 192]，单位为 kbps。 请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

Volume number

可选值: >= 0 and <= 200

音量值，范围为 [0, 200]。 请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

SeekTo number

指定播放进度（秒）。 请注意，该参数不填写时，默认使用上一次调用本接口、或创建云端播放器时的配置。

IsPause number

可选值: [0, 1]

是否暂停播放。

0：正常播放源文件。
1：暂停播放源文件。

注意

设置暂停播放时不能传入 StreamUrl 参数，否则会忽略其他的参数配置导致暂停播放失败。

RepeatTimes number

播放次数。

1：播放媒体流 1 次。
-1：自动循环播放。
n：自定义播放媒体流次数，必须大于 0。

请注意，该参数不填写或值为 0 时，默认使用上一次调用本接口、或创建云端播放器时的配置。

Responses

application/json

数据结构
按数据结构生成的示例

Schema

Code number

错误码。

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
0	成功。	-
100000004	签名过期。	请重新生成签名。
100000005	签名错误。	请确认生成签名的参数是否正确。
350006001	接口请求频率超过上限。	请确认对应接口的 QPS 限制，降低请求频率。
350006002	网关校验失败。	请联系 ZEGO 技术支持处理。
350006003	无效的输入参数。	请根据 Message 提示，调整对应参数的取值。
350006006	服务未开通。	请联系 ZEGO 技术支持，开通服务权限。
350010000	系统错误。	请联系 ZEGO 技术支持处理。

Message string

错误描述。

RequestId string

请求 ID。

{
  "Code": 0,
  "Message": "succeed",
  "RequestId": "abcd123"
}

{
  "Code": 0,
  "Message": "succeed",
  "RequestId": "abcd123"
}