Skip to main content

Stream Data Model

The core objects you work with — program, call, broadcast, player, participant, and the media stream controller — and how they fit together.

You interact with Native Frame through two surfaces: the Cloud API, a REST API you call from your backend to manage streams, and the client SDK, the libraries you use in a browser or app to broadcast and play. Each surface exposes its own objects. This page defines them and shows how they connect, so the terms in the guides — especially program — have a precise meaning.

note

Two object models, one platform. The Cloud API is organized around programs and streams. The SDK is organized around calls, broadcasts, and players. A broadcast is the object that appears in both, and it is what ties the two models together.

Program​

A program is a Cloud API object and the top-level container for related streams. It carries identifying fields — a programName, a programSlug, and the projectID of the project it belongs to — and reports how many streams it holds (streamCount) and how many are live (liveStreamCount).

A program contains streams. A stream is a single audio and video channel; a program groups the streams that belong together. For example, a source stream and its overlay stream live under the same program (see Overlay streaming).

You manage programs through the Cloud API — create, fetch, and update them. When a guide tells you to "create a program," this is the object it means.

Broadcast​

A broadcast is a stream being published live. It appears in both models, which is what makes it the bridge between them:

  • On the Cloud API, you start and end a broadcast on a stream, and a broadcast carries the programId of its containing program.
  • In the SDK, BroadcastAPI represents an active broadcast inside a call, identified by its stream name, with controls to mute audio, hide video, pause and resume, and swap the media source.

When a broadcast starts, the platform makes a manifest available for it — the file players use to discover and switch between renditions.

Call​

A call is an SDK object: a real-time session that people join to send and receive audio and video. CallAPI exposes the call's participants, its broadcasts, and the moderation actions a host needs.

A call has:

  • Participants — the connected people (see below).
  • Broadcasts — one or more active broadcasts, keyed by stream name.
  • An owner — the participant who can moderate the call.

You create a call with createCall and join an existing one with joinCall; each call has an id you can share so others can join. Group calls and private calls are both calls — see the Video Calls guides.

Participant​

A participant is a person connected to a call. The SDK models each connected participant as a peer — CallAPI.peers is the set of participants in the call.

Participants have roles. A call's owner can moderate the others — promoting, demoting, or removing them. Roles are also expressed as token scopes: conference-owner and conference-participant for group calls, and broadcaster or viewer (and their private- variants) for one-to-many streams. See Tokens and scopes for what each scope group grants; the scope reference covers the streaming scopes in more detail.

note

"Participant" is a role and a way of describing the people in a call. The object the SDK actually exposes is the peer.

Player​

A player is an SDK object that plays a stream into a video element. PlayerAPI supports live playback, DVR and VOD seeking, quality selection, and switching delivery drivers — for example, WebRTC for low latency or HLS for scale (see Streaming protocols).

A player is constructed by the VideoClient — the SDK entry point that also creates calls. You request one with a manifest URL, so what a player consumes is the manifest a broadcast produces, not the call directly.

Media stream controller​

A media stream controller is the SDK object that owns access to the camera and microphone. It sits between the browser's device APIs and the stream a broadcast sends, and it:

  • selects which capture devices are used,
  • toggles the camera and microphone on and off,
  • switches between multiple devices, and
  • provides the media stream a broadcast publishes.

It is the only object here on the capture side. Program, broadcast, call and player all describe a stream that already exists; the media stream controller is what produces one in the first place, which is why a broadcaster constructs it before opening a broadcast.

How the objects relate​

The two models are separate views of the same platform, joined by the broadcast:

  • Cloud API (server side): a project holds programs; a program contains streams; a broadcast is a stream being published, and it carries its program's id.
  • SDK (client side): a VideoClient creates calls and players; a media stream controller supplies the camera and microphone a broadcast publishes; a call has participants and broadcasts; a player plays the manifest a broadcast produces.

The broadcast is the shared object: it belongs to a program on the server and lives inside a call in the SDK. That is the connection point between managing streams from your backend and broadcasting or playing them from a client.

See also​