Media Pull (Input Online Media Stream)

Cloud player lifecycle, playback state derivation, region paths, update/destroy, quota and callbacks.

Version v1.1.0 · Updated 2026-10-26 · revision 1

Media Pull pulls external media streams into a channel ("input online media stream"): you give it a URL (RTMP/FLV/HLS/RTSP) and it appears in the channel as a "player user", which other participants subscribe to exactly like a normal user.

Concepts#

Creating a 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 (required) fields:

Lifecycle#

The status is derived from whether the player participant actually exists: running / paused / stopped / failed. It is not an in-memory field that merely "looks like it is playing" — reconcile corrects records that disagree with the media plane.

Supported sources#

streamUrl must be an address the server can reach: internal addresses, loopback addresses, and addresses that require an interactive login cannot be pulled. If you need a test source, create a push stream with the 14-streaming-lifecycle.mjs example first, then feed its playback address to the player.

Controlling playback#

# pause / resume
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}}'

# seek to second 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 is optimistic concurrency control: on a concurrent update the stale sequence gets 409; GET the resource again and resubmit.

Relationship with other participants in the channel#

• A player is a participant that only publishes and never subscribes;
• Real users can subscribe to it normally (the user-published event fires as usual, with mediaType being audio/video);
• Recording (composite) mixes it into the layout like any other video — which is exactly how you get "intro video + real people" in one stream;
• Destroying a player is equivalent to that user leaving the channel, and triggers user-left.

Quotas and errors#

End-to-end example#

node run-all.mjs --only=19

19-media-pull-lifecycle.mjs: create → query → pause → resume → destroy (writes, so it needs --all).