创建云端播放器
更新时间不可用
创建一个云端播放器，用于将在线媒体流输入到声网频道。
https://api.sd-rtn.com/{region}/v1/projects/{appId}/cloud-player/playersCreate 方法用于在项目中创建一个云端播放器。
注意
为确保请求成功，请不要将必填字段设为空，例如 null 或 ""。
鉴权
regionstring云端播放器的区域。声网支持分区域创建云端播放器，目前支持以下区域：
-
cn：中国大陆。 -
ap：除中国大陆以外的亚洲区域。 -
na：北美。 -
eu：欧洲。
注意：请确保设置的 region 与你的媒体流源站在同一个区域，且 region 值为小写。
appIdstring声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。
streamIpstring媒体流源站 IP 地址。必须使用有效的 IPv4 地址。
该参数可以保障媒体流的传输质量。如果源媒体流只在 region 区域内的部分区域提供服务，请使用该参数。如果源媒体流可在 region 区域内的广泛的区域提供服务，请忽略该参数。
Content-Typestringapplication/json
X-Request-IDstringUUID（通用唯一识别码），标识本次请求。传入该字段后，声网服务器会在响应 Header 中返回该字段。声网推荐你对 X-Request-ID 赋值。如果不赋值，声网服务器会自动生成一个 UUID 传入。
channelNamestring声网频道名称。字符串长度必须在 64 字节以内，支持以下字符集（共 89 个字符）：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
uidnumber云端播放器在声网频道内的用户 UID。取值范围为 0 到（232-1）。取值 0 时，声网服务器自动为 player 分配一个 UID。
注意
uid和account字段二选一必填。如果不设置用户名（UID 或 Account），该云端播放器不能创建，声网服务器会返回400(Bad Request)的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同，否则影响播放质量。- 如果你需要在同一个频道内有多个云端播放器，请确保每个云端播放器的用户名（UID 或 Account）都是唯一的。
accountstring云端播放器在声网频道内的用户 Account。使用该字段前请先阅读如何使用 String 型用户名。该字段不能超过 255 字节，也不能为空字符串。支持的字符集范围（共 89 个字符）如下：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- 空格
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
注意
uid和account字段二选一必填。如果不设置用户名（UID 或 Account），该云端播放器不能创建，声网服务器会返回400(Bad Request)的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同，否则影响播放质量。- 如果你需要在同一个频道内有多个云端播放器，请确保每个云端播放器的用户名（UID 或 Account）都是唯一的。
namestring云端播放器的名字。长度必须在 64 个字符以内，支持的字符集范围为：
- 所有小写英文字母（a-z）
- 所有大写英文字母（A-Z）
- 数字 0-9
- "-", "_"
注意
- 不传值时，
name为空。同一时间，一个项目下可以有多个name为空的云端播放器。 - 同一时间，一个项目下不允许出现重名的云端播放器，用户尝试创建同名的云端播放器时会收到响应状态码
409(Conflict)。 - 如果你需要在同一个频道内仅有一个云端播放器，请你务必使用
name字段。
云端播放器的音频转码配置。
volumenumber云端播放器的的音量大小。取值范围 [0,200]。默认值为 100，表示原始音量。
profilenumber音频场景。用于设置音频采样率、码率、编码模式和声道数。
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。
云端播放器的视频转码配置。
widthnumber输出视频宽度 (pixel)。取值范围为 [66,1920]。默认值为源媒体流的视频宽度。
heightnumber输出视频高度 (pixel)。取值范围为 [66,1080]。默认值为源媒体流的高度宽度。
widthHeightAdaptionboolean是否开启横竖屏自适应模式：
true：开启横竖屏自适应模式。成功开启后，如果源媒体流为横屏模式，则输出视频宽度和高度为 1280 × 720；如果源媒体流为竖屏模式，则输出视频宽度和高度为 720 × 1280。false：（默认）不开启横竖屏自适应模式。
frameRatenumber输出视频的编码帧率 (fps)。详见输出视频参考表。
bitratenumber输出视频的编码码率 (Kbps)。详见输出视频参考表。默认值为标准码率，即声网依据当前频道场景、分辨率、帧率为你设置的最合适的码率。
gopnumberGOP (Group of Pictures) 为关键帧帧间隔时间，单位为秒。
codecstring输出视频的编码格式，目前仅支持标准 H.264 格式。默认值为 "H.264"。如果设置为其他值，则依然为 H.264。
fillModestring视频画面的显示方式：
"fit"：（默认）等比缩放视频，直到画面在视窗内完整显示。"fill"：等比缩放视频，直至充满视窗。
streamUrlstring在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/HLS 地址，且长度在 1024 个字符以内。
注意：如需发布图片到声网频道，则设置 streamUrl 为你需要发布的图片 URL，云端播放器会将图片转换为视频，并发布到声网频道。目前支持 JPEG 和 PNG 格式的图片。你可以通过 videoOptions 设置视频转码相关参数。
playTsnumber云端播放器开始播放在线媒体流时的 Unix 时间戳（秒）。假设云端播放器创建时的 Unix 时间戳是 T，那么 playTs 的取值范围为 [T - 86400,T + 300]。默认值为 0，代表云端播放器在创建成功时自动播放在线媒体流。假设 playTs 取值为 S：
- 当 S = T 或 0 时，云端播放器在创建成功时自动播放在线媒体流。
- 当 S > T 时，云端播放器会在 S 时刻开始播放在线媒体流。这种取值方式适用于定时播放。
- 当 S < T 时，如果在线媒体流是直播流，云端播放器在创建成功时直接播放直播流；如果在线媒体流是点播流，云端播放器会从 T - S 时刻（秒）的位置开始播放点播流。这种取值方式适用于应对云端播放器运行出错的场景。举例来说，如果云端播放器 A 在运行中出错，你可以重新创建一个云端播放器 B 并将
playTs字段设为云端播放器 A 开始播放在线媒体流时的 Unix 时间戳。
idleTimeoutnumber云端播放器处于空闲状态的最大时长（秒），即媒体流为非播放状态的最大时长。空闲状态超过设置的 idleTimeout 后，该播放器会自动销毁。取值范围为 5 到 600。默认值为 300。如果取值小于 5，声网服务器会自动调整为 5；如果取值大于 600，声网服务器会自动调整为 600。
encryptModestring内置加密模式，可设为如下值：
"aes-128-xts"：128 位 AES 加密，XTS 模式。"aes-256-xts"：256 位 AES 加密，XTS 模式。"aes-128-ecb"：128 位 AES 加密，ECB 模式。"sm4-128-ecb"：128 位 SM4 加密，ECB 模式。"aes-128-gcm"：128 位 AES 加密，GCM 模式。"aes-256-gcm"：256 位 AES 加密，GCM 模式。"aes-128-gcm2"：推荐设置。128 位 AES 加密，GCM 模式。 相比于aes-128-gcm加密模式，aes-128-gcm2加密模式安全性更高且需要设置盐（encryptKdfSalt）。"aes-256-gcm2"：推荐设置。256 位 AES 加密，GCM 模式。相比于aes-256-gcm加密模式，aes-256-gcm2加密模式安全性更高且需要设置盐（encryptKdfSalt）。
encryptKeystring内置加密密钥。字符串长度无限制。声网推荐使用 32 字节的密钥。
注意：如果该字段为空，则无法启用内置加密。
encryptKdfSaltstring盐，长度为 32 字节。声网推荐你在服务端使用 OpenSSL 随机生成 Base64 编码的盐，详见媒体流加密。
注意：该字段仅在 aes-128-gcm2 或 aes-256-gcm2 加密模式下生效。
repeatTimenumber播放媒体流次数。该参数仅适用于点播流。可设为如下值：
1：（默认）播放媒体流一次。-1：循环播放媒体流。n：自定义播放媒体流次数。整型，不可设置为 0。
seekPositionnumber指定点播文件的播放位置（秒）。默认值为 0，表示从点播文件起始位置播放。必须小于音视频时长。
数据流配置，用于展示当前 Cloud Player 对应的 UID 的点播流总时长，可以用来展示实时播放进度。
enableboolean设置是否通过 Data stream 展示点播流总时长：
true：展示。false：（默认）不展示。
如果通过 Data stream 展示点播流总时长，发出的 Data stream 需要使用 Protobuf 解析，而不能用 ASCII 码直接解析。
Protobuf（全称 Protocol Buffers）是由 Google 开发的一种高效的、跨语言的序列化数据格式。Protobuf 解析步骤如下：
-
将如下代码保存到一个 proto 文件中，例如
PlayerMessage.proto：syntax = "proto3"; message PositionData { int32 duration = 1; int32 position = 2; int32 uid = 3; } -
使用 protoc 生成源代码
-
对接收到的数据进行反序列化
temponumber播放倍速，支持如下取值：
- 0.5
- 0.75
- 1.0（默认）
- 1.25
- 1.5
- 1.75
- 2.0
响应
如果状态码为 2XX，请求成功。
响应 Header
响应 Body
uidnumber云端播放器在声网频道内的用户 UID。
idstring云端播放器的 ID。它是声网服务器生成的一个 UUID（通用唯一识别码），标识已创建的一个云端播放器。
createTsnumber云端播放器创建的 Unix 时间戳（秒）。
statusstring云端播放器的运行状态：
"idle"：播放未开始。"connecting"：声网服务器正在连接媒体流地址或正在探测音视频数据。"running"：正在播放。"failed"：声网服务器无法连接媒体流地址或该媒体流无法播放。
fieldsstringJSON 编码方式的字段掩码，详见谷歌 protobuf FieldMask 文档。用于指定返回 players 数组中每个 player 中的字段子集。在使用 uid 的示例中，fields 指定声网服务器返回 players 数组中每个 player 中的 name,streamUrl,channelName,uid,id,createTs 和 status 字段子集。
请求示例
curl --request POST \
--url "https://api.sd-rtn.com/:region/v1/projects/:appId/cloud-player/players" \
--header 'Authorization: Basic <credentials>' \
--header 'X-Request-ID: <string>' \
-H 'Content-Type: application/json' \
-d '{
"player": {
"audioOptions": {
"profile": 1
},
"videoOptions": {
"width": 1920,
"height": 1080,
"frameRate": 15,
"bitrate": 400,
"codec": "H.264",
"gop": 2,
"fillMode": "fill"
},
"streamUrl": "rtmp://example.agora.io/live/class32/101",
"channelName": "class32",
"token": "2a78446***",
"uid": 101,
"idleTimeout": 300,
"name": "test"
}
}'响应示例
{
"player": {
"uid": 101,
"id": "2a784467d647bb87b60b719f6fa56317",
"createTs": 1575508644,
"status": "running"
},
"fields": "player.uid,player.id,player.createTs,player.status"
}