Media Pull（输入在线媒体流）
cloud player 拉流、播放状态推导、region 路径、更新与销毁、配额与回调。
Media Pull 把外部媒体流拉进频道（「输入在线媒体流」）：给它一个 URL（RTMP/FLV/HLS/RTSP），它作为频道里的一个「播放器用户」出现，其他参与者像订阅普通用户一样订阅它。
概念
| 概念 | 含义 |
|---|---|
| player | 一个拉流实例：一路流 → 频道里的一个 uid |
| uid / account | player 在频道里的身份（数字 uid 与可选账号名） |
| playbackUrl | 拉流成功后可直接播放的地址（由我们生成，便于调试） |
| idleTimeout | 无人观看时的回收秒数 |
| repeatTime | 循环播放次数（0 表示一直播） |
| seekPosition | 起播位置（秒），用于「从第 N 秒开始播」 |
创建 player
curl -s -X POST "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/cloud-player/players?streamIp=$STREAM_IP" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{
"player": {
"streamUrl": "https://example.com/media/weekly-intro.m3u8",
"channelName": "weekly-sync",
"uid": 30001,
"name": "intro-video",
"idleTimeout": 120
}
}'player（必填）字段：
| 字段 | 类型 | 说明 | |
|---|---|---|---|
streamUrl | string | 源地址；支持协议见下方「支持的源」 | |
channelName | string | 目标频道 | |
uid | integer | 播放在频道里的 uid（不要与真实用户重复） | |
account | string \ | null | 可选账号名 |
name | string \ | null | 业务名 |
audioOptions / videoOptions | object | 音量、画面等比/裁剪等 | |
idleTimeout | integer | 空闲回收秒数 | |
playTs / seekPosition | integer | 起播时间戳 / 起播位置 | |
repeatTime | integer | 循环次数 |
生命周期
| 操作 | 端点 |
|---|---|
| 创建 | POST /{region}/v1/projects/{appId}/cloud-player/players |
| 查询单个 | GET /{region}/v1/projects/{appId}/cloud-player/players/{id} |
| 列表 | GET /v1/projects/{appId}/cloud-player/players（pageSize/pageToken/filter） |
| 更新 | PATCH /{region}/v1/projects/{appId}/cloud-player/players/{id}（可 isPause、seekPosition） |
| 销毁 | DELETE /{region}/v1/projects/{appId}/cloud-player/players/{id} |
状态（status）由播放器参与者是否真实存在推导：running / paused / stopped / failed。 这不是一个「看起来像在播」的内存字段——reconcile 会把与媒体面不一致的记录纠正过来。
支持的源
| 协议 | 说明 |
|---|---|
| RTMP / RTMPS | 直播源；延迟最低 |
| HTTP-FLV | 常见的低延迟直播分发格式 |
| HLS（m3u8） | 点播/直播均可；点播支持 seekPosition |
| RTSP | 摄像头/安防设备；不支持鉴权的源需自行转换 |
streamUrl 必须是服务端可访问的地址：内网地址、localhost、需要交互登录的地址都拉不到。 需要一个测试源时，可先在文档示例目录运行 14-streaming-lifecycle.mjs 造一条推流，再把它的播放地址喂给 player。
控制播放
# 暂停 / 恢复
curl -s -X PATCH "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/cloud-player/players/$PLAYER_ID?sequence=1" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"player":{"isPause":true}}'
# 跳转到第 60 秒
curl -s -X PATCH "$NIMEET_API_BASE/cn-shanghai/v1/projects/$APP_ID/cloud-player/players/$PLAYER_ID" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"player":{"seekPosition":60}}'sequence 是乐观并发控制：并发更新时旧序号会得到 409，重新 GET 后再提交。
与频道里其他参与者的关系
- player 是一个只发布、不订阅的参与者；
- 真实用户可以正常订阅它（
user-published事件照常触发，mediaType是audio/video）； - 录制（composite）会把它当作普通画面合进布局——这正好实现「片头视频 + 真人」的合流；
- 销毁 player 相当于该用户离开频道，会触发
user-left。
配额与错误
| 场景 | 返回 |
|---|---|
| 服务未开通 | 403 service_not_enabled |
| 并发 player 超限（500） | 429 streaming_quota_exceeded |
| 源地址不可达 | 创建成功但 status 会在查询里变为失败态，error 字段说明原因 |
| uid 与已有 player 重复 | 不拒绝（实测允许同名 uid 并存）。但两个参与者同 uid 会让订阅端无法区分，请自行保证 uid 唯一 |
端到端示例
node 文档站 class="tok-flag">-all.mjs --only=1919-media-pull-lifecycle.mjs：创建 → 查询 → 暂停 → 恢复 → 销毁（写操作，需要 --all）。