skip to content

In Cloudflare Stream, how does a live input take a weekly class over RTMPS, SRT or WHIP, and what decides whether it is recorded?

level: middleimportance: should knowfreq 22%

answer

  1. one input, many broadcasts
  2. stream key as a credential
  3. recording mode defaults off
  4. WebRTC goes unrecorded
  5. input ID versus video ID

basics

~20 s

A Stream live input is a reusable ingest point the encoder pushes to over RTMPS, SRT or WHIP. With recording.mode set to automatic, each RTMPS or SRT broadcast plays over HLS and DASH and is recorded; WHIP broadcasts are not.

solid answer

~40 s

Create one live input for the class with `POST .../stream/live_inputs` and keep its ID. Its response gives an RTMPS URL with a `streamKey`, an SRT URL, and WebRTC URLs: `webRTC.url` to publish over WHIP and `webRTCPlayback.url` to play over WHEP. The stream key and WHIP URL are broadcast credentials, so only the instructor gets them. Set `recording.mode` to `automatic`; the API default is `off`, which leaves the input with no HLS or DASH playback and no recording. In automatic mode each RTMPS or SRT broadcast becomes a new video that plays live and is a replay within about 60 seconds of ending. WHIP is the exception: it plays only over WHEP and is not recorded. Embed the live input ID on the class page so it always shows the current broadcast.

code

bash · 4 lines
bash
curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{"meta": {"name": "Weekly class"}, "recording": {"mode": "automatic", "requireSignedURLs": true}, "deleteRecordingAfterDays": 365}' \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/stream/live_inputs"

go deeper

for a junior

Recall that a live input has an RTMPS URL and stream key for the encoder, and that viewers watch through the player or HLS manifest.

for a middle

Explain recording.mode, why off means no playback or replay, the new video per broadcast, and when to embed the input ID.

for a senior

Show operational control: rotate_keys and enabled for leaked credentials, live webhooks with error codes, and replay retention with deleteRecordingAfterDays.

for a principal

Weigh ingest choices for instructors: browser WHIP is easy and fast but leaves no replay, while RTMPS or SRT need an encoder but give recordings.

## What a live input is In Cloudflare Stream, a **live input** is a long-lived ingest point that a broadcaster streams to, again and again. For a weekly class you create one input, keep its ID, and every Tuesday the instructor's encoder connects to it. Stream encodes each broadcast at several quality levels and serves it worldwide. You create one in the dashboard's **Live inputs** page or with `POST .../stream/live_inputs`; the response's `uid` is the **live input ID**, which never changes. ## Three ways in | Ingest | What the instructor gets | Live playback | Recording | |---|---|---|---| | **RTMPS** | `rtmps.url` (`rtmps://live.cloudflare.com:443/live/`) and `rtmps.streamKey` | HLS and DASH, Stream player | Yes, with recording mode `automatic` | | **SRT** | An SRT URL; Stream supports SRT **caller** mode, so the encoder dials Stream | HLS and DASH, Stream player | Yes, with recording mode `automatic` | | **WHIP** (WebRTC) | `webRTC.url`, a publish URL with a secret in it | Only over **WHEP** at `webRTCPlayback.url`, under a second of latency | **No**: WebRTC broadcasts are not recorded | RTMPS is the common choice for desktop encoders. SRT is the other encoder protocol, and the docs note it makes captions and multiple audio tracks easier. WHIP lets an instructor go live from a browser with no encoder, at the cost of no HLS playback and no replay; the docs still mark it beta, with delivery billing from 15 October 2026. The stream key and the WHIP publish URL are **broadcast credentials**: anyone holding them can go live as the class. Only the instructor should have them; viewers never need them. ## Recording mode and the replay The setting that decides playback and recording is `recording.mode`: - `off` is the API default. The input then neither offers HLS or DASH playback nor records. - `automatic` creates a **new video** each time a broadcast starts, plays it live over HLS and DASH, and keeps it as a replay. Other recording settings live in the same object: `recording.requireSignedURLs`, `recording.allowedOrigins` and `recording.hideLiveViewerCount`. Practical facts about replays: 1. A recording is ready within about **60 seconds** of the broadcast ending; until then the video may report `not-found` or `not-started`. 2. `GET .../live_inputs/{input_id}/videos` lists one video per broadcast: the active one in `live-inprogress`, finished ones in `ready`. 3. `deleteRecordingAfterDays` (30 to 1,096) schedules deletion of each recording, not the input. 4. A broadcast longer than seven days is recorded only for its first seven days. 5. Recordings count as stored minutes; a broadcast nobody watches still costs storage. ## Input ID or video ID on the page Both work in `customer-<CODE>.cloudflarestream.com/<ID>/iframe` and `/manifest/video.m3u8`. Use the **live input ID** on the class page: it always shows the current broadcast, or a "Stream has not started" message when idle. Use a **video ID** on a page for one session's replay, since each broadcast gets a new one. The input's `lifecycle` endpoint (`customer-<CODE>.cloudflarestream.com/<INPUT_ID>/lifecycle`) returns `isInput`, `live` and the active `videoUID`, which a custom player needs to show its own idle state; the Stream player does this check itself. Setting `recording.hideLiveViewerCount` removes the viewer count from the player when a small class should not see how few people joined. ## Keeping the broadcast credential safe - `enabled: false` on the input (a `PUT` to `.../live_inputs/{input_id}`) rejects RTMPS and SRT connections, which ends a broadcast or blocks the slot between classes. - `POST .../live_inputs/{input_id}/rotate_keys` revokes the old credentials, disconnects any broadcast using them and returns new ones, keeping the input ID and embeds. `keysRotatedAt` records when. ## Watching it from the backend Live events do not use the on-demand video webhook. They are set up as a **Notifications** destination, and each call carries an `event_type` of `live_input.connected`, `live_input.disconnected` or `live_input.errored`. An error includes a code such as `ERR_GOP_OUT_OF_RANGE`, `ERR_UNSUPPORTED_VIDEO_CODEC` or `ERR_STORAGE_QUOTA_EXHAUSTED`, which tells you whether the encoder or the account is at fault. The storage one matters for a class: when prepaid storage runs out, Stream refuses to start new live streams as well as new uploads (Enterprise contracts may allow uploads past the quota), so a forgotten replay backlog can stop next week's class from going live. `deleteRecordingAfterDays` is the guard against that. How live segments, latency and bitrate ladders work in general is covered with media streaming design; WebRTC calls between participants belong to Cloudflare Realtime.

  • When should a Stream page embed the live input ID rather than a video ID?
    Use the live input ID for a page tied to a recurring program: it shows whatever broadcast is live, or a not-started message when idle. Use a video ID for one session or its replay, because each broadcast gets a new video ID when it starts.
  • The instructor's Stream key appeared in a screen share. What now?
    Call `POST .../live_inputs/{input_id}/rotate_keys`. It revokes the old credentials, disconnects any broadcast using them and returns new ones, while the input ID and every embed stay the same. Setting `enabled` to `false` is the stopgap if you need to block broadcasts first.
  • How does the backend learn that the class went live or that the encoder is misconfigured?
    Subscribe a webhook through Notifications for Stream Live. Calls carry `event_type` values `live_input.connected`, `live_input.disconnected` or `live_input.errored`, and errors include a code such as `ERR_GOP_OUT_OF_RANGE`, so you can alert the instructor about encoder settings.

  • A live input created through the API records broadcasts by default.
  • A WHIP broadcast gets an HLS replay just like an RTMPS one.
  • Every broadcast on a live input reuses the same video ID.
  • A leaked stream key means deleting the input and re-embedding a new ID.
  • Viewers need the stream key to watch the class.

Assumes Stream as of 2026-10-10: WebRTC live (WHIP and WHEP) is still marked beta with delivery billing from 15 October 2026, and the enabled flag and rotate_keys arrived during 2026.