# 创建云端播放器 (/zh-CN/api-reference/api-ref/media-pull/create) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 创建一个云端播放器,用于将在线媒体流输入到声网频道。 - OpenAPI: /openapi/media-pull/media-pull.zh-CN.yaml - Operation ID: get-region-v1-projects-appId-cloud-player-players - Method: POST - Path: /{region}/v1/projects/{appId}/cloud-player/players - Endpoint: https://api.sd-rtn.com/{region}/v1/projects/{appId}/cloud-player/players ## Servers - https://api.sd-rtn.com `Create` 方法用于在项目中创建一个云端播放器。 :::warning[注意] 为确保请求成功,请不要将必填字段设为空,例如 `null` 或 `""`。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` ## Parameters - `Content-Type` (header, required, string) - `application/json` - `X-Request-ID` (header, optional, string) - UUID(通用唯一识别码),标识本次请求。传入该字段后,声网服务器会在响应 Header 中返回该字段。声网推荐你对 `X-Request-ID` 赋值。如果不赋值,声网服务器会自动生成一个 UUID 传入。 - `streamIp` (query, optional, string) - 媒体流源站 IP 地址。必须使用有效的 IPv4 地址。 该参数可以保障媒体流的传输质量。如果源媒体流只在 `region` 区域内的部分区域提供服务,请使用该参数。如果源媒体流可在 `region` 区域内的广泛的区域提供服务,请忽略该参数。 - `region` (path, required, string) - 云端播放器的区域。声网支持分区域创建云端播放器,目前支持以下区域: - `cn`:中国大陆。 - `ap`:除中国大陆以外的亚洲区域。 - `na`:北美。 - `eu`:欧洲。 **注意**:请确保设置的 `region` 与你的媒体流源站在同一个区域,且 `region` 值为小写。 - `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 ## Request body - `player` (object) - `player.channelName` (string, required) - 声网频道名称。字符串长度必须在 64 字节以内,支持以下字符集(共 89 个字符): - 所有小写英文字母(a-z) - 所有大写英文字母(A-Z) - 数字 0-9 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", "," - `player.uid` (number) - 云端播放器在声网频道内的用户 UID。取值范围为 0 到(232-1)。取值 0 时,声网服务器自动为 player 分配一个 UID。 > [!CAUTION] > - `uid` 和 `account` 字段二选一必填。如果不设置用户名(UID 或 Account),该云端播放器不能创建,声网服务器会返回 `400(Bad Request)` 的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同,否则影响播放质量。 > - 如果你需要在同一个频道内有多个云端播放器,请确保每个云端播放器的用户名(UID 或 Account)都是唯一的。 - `player.account` (string) - 云端播放器在声网频道内的用户 Account。使用该字段前请先阅读[如何使用 String 型用户名](/zh-CN/reference/faq/integration/string_uid)。该字段不能超过 255 字节,也不能为空字符串。支持的字符集范围(共 89 个字符)如下: - 所有小写英文字母(a-z) - 所有大写英文字母(A-Z) - 数字 0-9 - 空格 - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "\|", "~", "," > [!CAUTION] > - `uid` 和 `account` 字段二选一必填。如果不设置用户名(UID 或 Account),该云端播放器不能创建,声网服务器会返回 `400(Bad Request)` 的状态码。请确保该值与频道内其他用户、云端播放器的 UID 都不同,否则影响播放质量。 > - 如果你需要在同一个频道内有多个云端播放器,请确保每个云端播放器的用户名(UID 或 Account)都是唯一的。 - `player.token` (string) - 云端播放器在声网频道内使用的动态密钥。如在声网控制台未启用 App 证书,则不需要向 `token` 传值;如在声网控制台已启用 App 证书,则必须传入 `token`: - 安全性要求一般时,可使用声网控制台生成的[临时 Token](/zh-CN/introduction/quickstart#获取开发参数)。 - 安全性要求高时,使用用户服务器生成的[正式 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 **注意**:生成正式 Token 时,使用的 `uid` 或 `account` 必须和云端播放器的 `uid` 或 `account` 取值一致。 - `player.name` (string) - 云端播放器的名字。长度必须在 64 个字符以内,支持的字符集范围为: - 所有小写英文字母(a-z) - 所有大写英文字母(A-Z) - 数字 0-9 - "-", "_" > [!CAUTION] > - 不传值时,`name` 为空。同一时间,一个项目下可以有多个 `name` 为空的云端播放器。 > - 同一时间,一个项目下不允许出现重名的云端播放器,用户尝试创建同名的云端播放器时会收到响应状态码 `409(Conflict)`。 > - 如果你需要在同一个频道内仅有一个云端播放器,请你务必使用 `name` 字段。 - Max length: `64` - `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.videoOptions` (object) - 云端播放器的视频转码配置。 - `player.videoOptions.width` (number) - 输出视频宽度 (pixel)。取值范围为 [66,1920]。默认值为源媒体流的视频宽度。 - Default: `源文件视频宽度` - Range: `[66, 1920]` - `player.videoOptions.height` (number) - 输出视频高度 (pixel)。取值范围为 [66,1080]。默认值为源媒体流的高度宽度。 - Default: `源文件视频高度` - Range: `[66, 1080]` - `player.videoOptions.widthHeightAdaption` (boolean) - 是否开启横竖屏自适应模式: - `true`:开启横竖屏自适应模式。成功开启后,如果源媒体流为横屏模式,则输出视频宽度和高度为 1280 × 720;如果源媒体流为竖屏模式,则输出视频宽度和高度为 720 × 1280。 - `false`:(默认)不开启横竖屏自适应模式。 - Default: `false` - `player.videoOptions.frameRate` (number) - 输出视频的编码帧率 (fps)。详见[输出视频参考表](/zh-CN/api-reference/media-pull/restful/api/video-profile)。 - Default: `15` - Range: `[5, 30]` - `player.videoOptions.bitrate` (number) - 输出视频的编码码率 (Kbps)。详见[输出视频参考表](/zh-CN/api-reference/media-pull/restful/api/video-profile)。默认值为标准码率,即声网依据当前频道场景、分辨率、帧率为你设置的最合适的码率。 - Default: `标准码率` - Range: `[1, 10000]` - `player.videoOptions.gop` (number) - GOP (Group of Pictures) 为关键帧帧间隔时间,单位为秒。 - Default: `2` - Range: `[1, 10]` - `player.videoOptions.codec` (string) - 输出视频的编码格式,目前仅支持标准 H.264 格式。默认值为 `"H.264"`。如果设置为其他值,则依然为 H.264。 - Default: `H.264` - `player.videoOptions.fillMode` (string) - 视频画面的显示方式: - `"fit"`:(默认)等比缩放视频,直到画面在视窗内完整显示。 - `"fill"`:等比缩放视频,直至充满视窗。 - Default: `fit` - `player.streamUrl` (string, required) - 在线媒体流 URL 地址。必须为有效的 HTTP/HTTPS/RTMP/HLS 地址,且长度在 1024 个字符以内。 **注意**:如需发布图片到声网频道,则设置 `streamUrl` 为你需要发布的图片 URL,云端播放器会将图片转换为视频,并发布到声网频道。目前支持 JPEG 和 PNG 格式的图片。你可以通过 `videoOptions` 设置视频转码相关参数。 - Max length: `1024` - `player.playTs` (number) - 云端播放器开始播放在线媒体流时的 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 时间戳。 - `player.idleTimeout` (number) - 云端播放器处于空闲状态的最大时长(秒),即媒体流为非播放状态的最大时长。空闲状态超过设置的 `idleTimeout` 后,该播放器会自动销毁。取值范围为 5 到 600。默认值为 300。如果取值小于 5,声网服务器会自动调整为 5;如果取值大于 600,声网服务器会自动调整为 600。 - Default: `300` - Range: `[5, 600]` - `player.encryptMode` (string) - 内置加密模式,可设为如下值: - `"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`)。 - `player.encryptKey` (string) - 内置加密密钥。字符串长度无限制。声网推荐使用 32 字节的密钥。 **注意**:如果该字段为空,则无法启用内置加密。 - `player.encryptKdfSalt` (string) - 盐,长度为 32 字节。声网推荐你在服务端使用 OpenSSL 随机生成 Base64 编码的盐,详见[媒体流加密](/zh-CN/realtime-media/rtc/build/advanced-channel/channel-encryption)。 **注意**:该字段仅在 `aes-128-gcm2` 或 `aes-256-gcm2` 加密模式下生效。 - `player.repeatTime` (number) - 播放媒体流次数。该参数仅适用于点播流。可设为如下值: - `1`:(默认)播放媒体流一次。 - `-1`:循环播放媒体流。 - `n`:自定义播放媒体流次数。整型,不可设置为 0。 - `player.seekPosition` (number) - 指定点播文件的播放位置(秒)。默认值为 0,表示从点播文件起始位置播放。必须小于音视频时长。 - Default: `0` - `player.dataStreamOptions` (object) - 数据流配置,用于展示当前 Cloud Player 对应的 UID 的点播流总时长,可以用来展示实时播放进度。 - `player.dataStreamOptions.enable` (boolean) - 设置是否通过 Data stream 展示点播流总时长: - `true`:展示。 - `false`:(默认)不展示。 如果通过 Data stream 展示点播流总时长,发出的 Data stream 需要使用 Protobuf 解析,而不能用 ASCII 码直接解析。 Protobuf(全称 [Protocol Buffers](https://protobuf.dev/))是由 Google 开发的一种高效的、跨语言的序列化数据格式。Protobuf 解析步骤如下: 1. 将如下代码保存到一个 proto 文件中,例如 `PlayerMessage.proto`: ```proto syntax = "proto3"; message PositionData { int32 duration = 1; int32 position = 2; int32 uid = 3; } ``` 2. 使用 protoc 生成源代码 3. 对接收到的数据进行反序列化 - Default: `false` - `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": { "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" } } ``` ## Responses ### 200 如果状态码为 2XX,请求成功。 - `player` (object) - `player.uid` (number) - 云端播放器在声网频道内的用户 UID。 - `player.id` (string) - 云端播放器的 ID。它是声网服务器生成的一个 UUID(通用唯一识别码),标识已创建的一个云端播放器。 - `player.createTs` (number) - 云端播放器创建的 Unix 时间戳(秒)。 - `player.status` (string) - 云端播放器的运行状态: - `"idle"`:播放未开始。 - `"connecting"`:声网服务器正在连接媒体流地址或正在探测音视频数据。 - `"running"`:正在播放。 - `"failed"`:声网服务器无法连接媒体流地址或该媒体流无法播放。 - `fields` (string) - JSON 编码方式的字段掩码,详见[谷歌 protobuf FieldMask 文档](https://googleapis.dev/nodejs/pubsub/latest/google.protobuf.html#.FieldMask)。用于指定返回 `players` 数组中每个 player 中的字段子集。在使用 `uid` 的示例中,`fields` 指定声网服务器返回 `players` 数组中每个 player 中的 `name`,`streamUrl`,`channelName`,`uid`,`id`,`createTs` 和 `status` 字段子集。 ### 非 2XX 如果状态码不为 2XX,请求失败。 - `message` (string) - 描述请求失败的具体原因。 ## Response examples ### 200 ```json { "player": { "uid": 101, "id": "2a784467d647bb87b60b719f6fa56317", "createTs": 1575508644, "status": "running" }, "fields": "player.uid,player.id,player.createTs,player.status" } ``` ### 非 2XX ```json { "message": "Invalid authentication credentials." } ```