创建云端播放器

StreamUrl

String

是

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

BackupStreamUrl

String

否

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

当 StreamUrl 参数中的地址访问失败时，云端播放器会尝试访问备用地址。

RoomId

String

是

推流到指定房间 ID，长度在 128 字节以内。

调用本接口时，如果 RoomId 不存在，会自动创建房间。

StreamId

String

否

云端播放器推流到指定房间的流 ID，长度在 256 字节以内，仅支持数字，英文字符 和 '-'，'_'。

请注意，同一个 AppID 下，StreamId 必须是唯一的。该参数不填写时，由 ZEGO 服务器随机分配一个 ID。

PlayerName

String

否

云端播放器的名称，长度在 64 字节以内，默认为空。

• 同一个 AppId 下可以存在多个 PlayerName 为空的云端播放器，但不允许出现多个正在运行中、且 PlayerName 重复的云端播放器。
• 已销毁的播放器名称 PlayerName 可以再次创建使用，但是建议开发者避免创建相同 PlayerName 的播放器。

VideoOptions

Object

否

视频转码参数配置。

请注意，该参数不填写时，其中所包含的字段均使用默认值。

Width

Number

否

视频宽度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的宽度。

请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。

Height

Number

否

视频高度，取值范围为 [1, 3000]，且必须是 2 的整倍数，单位为 px，默认值为原始媒体资源的高度。

请注意，Width 和 Height 任意参数设置为 1 时，都表示纯音频推流。

VideoBitrate

Number

否

视频码率，取值范围为 [1, 50000]，单位为 kbps，默认值为 ZEGO 根据分辨率和帧率给出的推荐码率，详情请参考 常用视频配置 中的“预设值组合”。

例如，输入分辨率为 360*640 时，输出流的 VideoBitrate 设置为 600 kbps。

VideoCodec

Number

否

视频编码格式。

• 0：H264，默认值。
• 2：VP8。
• 3：H265。

Fps

Number

否

视频帧率，取值范围为 [1, 30]，单位为 fps，默认值为 15。

RenderMode

Number

否

视频填充模式。

• 0：填充模式，视频等比例缩放，直到画面在视窗内完整显示，可能会有黑边，默认值。
• 1：裁剪模式，视频等比例缩放，直到充满整个视窗，可能有部分会被裁减。

AudioOptions

Object

否

音频转码参数配置。

请注意，该参数不填写时，其中所包含的字段均使用默认值。

AudioCodec

Number

否

音频编码及采样率。

• 0：AAC-LC，采样率：44100 kHz，默认值。
• 1：HE-AAC，采样率：44100 kHz。
• 6：OPUS，采样率：48000 kHz。

AudioBitrate

Number

否

音频码率，取值范围为 [1, 192]，单位为 kbps，默认值为 48 kbps。

SoundChannel

Number

否

音频声道数。

• 1：单声道，默认值。
• 2：双声道。

Volume

Number

否

音量值，范围为 [0, 200]，默认值为 100，表示音频的原始音量。

PlayTime

Number

否

开始播放在线媒体流时的 Unix 时间戳（秒），取值范围为 [CreateTime - 86400, CreateTime + 1800]（CreateTime 是云端播放器的创建时间，调用本接口成功后会返回。如需提高上限，请联系 ZEGO 技术支持），默认值为 0，表示云端播放器创建成功时，自动开始播放在线媒体流。

• 当 PlayTime = CreateTime 时，云端播放器在创建成功时，自动开始播放。
• 当 PlayTime > CreateTime 时，云端播放器在创建成功后，提前加载媒体资源，等到设置的 PlayTime 时刻，再开始播放，实现定时播放的效果。
• 当 PlayTime < CreateTime 时，云端播放器在创建成功后，会从 CreateTime - PlayTime 时刻对应的位置，开始播放。例如，当云端播放器 A 运行中出现异常时，您可以创建一个新的云端播放器 B，将 B 的 PlayTime 设置为 A 开始播放的 Unix 时间戳，当 B 创建成功后，即可直接从 A 的当前进度开始播放。

例如，CreateTime 为晚上 20:00，当 PlayTime 为 20:00 时，云端播放器创建成功后，直接开始播放；当 PlayTime 为 20:10（CreateTime + 600）时，云端播放器创建成功后，开始加载资源，等到 20:10 开始播放；当 PlayTime 为 19:55（CreateTime - 300）时，云端播放器创建成功后，将直接从媒体流的第 6 分钟开始播放。

RepeatTimes

Number

否

播放次数。

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

SeekTo

Number

否

指定播放进度（秒），默认值为 0，表示从起始位置开始播放。

MaxIdleTime

Number

否

云端播放器处于空闲状态（指 Status 为 2、6，具体请参考 查询云端播放器任务列表 的返回参数）的最大时长，即媒体流为非播放状态的最大时长。取值范围为 [5, 600]，单位为秒，默认值为 300 秒。

• 空闲状态超过设置的 MaxIdleTime 后，该播放器会被自动销毁。
• MaxIdleTime 如果取值小于 5，ZEGO 服务器会自动调整为 5；如果取值大于 600，ZEGO 服务器会自动调整为 600。

StreamData

Object

否

实时媒体流携带的数据配置（例如播放进度信息等）。该数据将随视频帧作为 SEI 信息，传输给拉流方，拉流方可通过监听客户端的 onPlayerSyncRecvSEI 等回调获取该数据。

该参数传输的 SEI 信息默认为 JSON 类型的数据格式，开发者可按 JSON 格式进行解析。例如 SEI 内容为 null，其中 CloudPlayerPlayingProgress 表示视频帧当前的播放进度，1000 表示当前的播放进度为 1000ms。

Enable

Number

否

是否开启 StreamData 配置。

• 0：不开启，默认值。
• 1：开启。

Interval

Number

否

设置用于传输 StreamData 数据的 SEI 信息发送频率（毫秒），默认值为 1000，表示每隔 1 秒发送 1 个携带 StreamData 数据的 SEI 信息。

ExtensionParams

Array of Object

否

扩展参数，以 Key-Value 的方式进行设置。

该参数一般用于非常规的特殊参数或部分技术预览，请根据实际情况填写，常规的云端播放器任务可忽略。

Key

String

否

key 值。

Value

String

否

value 值。

RoomUserUpdate

Number

否

当您在创建云端播放器时因 RoomId 不存在而自动创建房间时，用户进出房间是否会触发房内其他用户的客户端 onRoomUserUpdate 回调通知：

• 0：不会（默认）。
• 1：会。

Code

Number

错误码。

Message

String

错误描述。

RequestId

String

请求 ID。

Data

Object

返回的具体信息。

PlayerId

String

播放器唯一标识 ID。

RoomId

String

房间 ID。

StreamId

String

流 ID。

CreateTime

Number

播放器创建时间，Unix 时间戳，单位：秒。