Skip to main content

Snapshots

Snapshots are short MP4 clips captured automatically from a stream while it is live, saved under a snapshots/ prefix in the project's snapshot storage. Use them for live highlights, periodic thumbnails/previews, or moderation samples — without running your own capture pipeline.

You configure a snapshot rule per stream (cadence, clip length, look-back), and Native Frame captures clips while the stream is live. Clips can be listed and downloaded from the dashboard or the API.

Storage prerequisite

Snapshots need a storage profile on the snapshots surface — managed (default) or BYO. See the Storage Profiles guide. A project with no snapshots profile gets 422 project_missing_s3_config when you save a rule.

Dashboard access

The dashboard for all brands is at platform.nativeframe.com.

Configure a snapshot rule (dashboard)​

1. Open the stream's Snapshots tab​

From Streams → (your stream) → Snapshots. Before a rule exists you'll see the empty state — click + Configure Snapshots.

2. Fill in the rule​

Field (dashboard)API fieldWhat it does
Clip length (seconds)maxDurSecEach clip captures up to this many seconds. Required.
Capture every (seconds)intervalSecHow often a clip is captured while live. Leave empty for the platform default (60s).
Capture a single clip (one-shot)oneShotOn = capture one clip, then the rule self-expires. Off = repeat on a cadence.
Look-back (seconds)backfillSecSeconds before the trigger to include (the lead-up). Bounded by the deployment's buffer.
Keep partial clipsminDurSecShortest clip worth keeping if the stream ends early. Omit to discard partials.
(advanced)formatsRendition (bitrate) selector, e.g. ["2300"] — picks which encoding to clip. Output is always MP4.

Click Save Rule.

3. Rule is active​

The rule shows as Active with its settings and Edit / Remove actions. Changes take effect within a few seconds.

4. View & download captured clips​

Clips are produced only while the stream is live; the first appears within roughly the capture interval (~60s by default). Each clip is an MP4 stored at:

snapshots/{streamID}/{captureTime}_{streamID}.mp4

For managed storage, the dashboard lists the captured clips with a per-clip Download backed by a short-lived presigned URL — no storage credentials needed. For BYO storage, read the clips from your own bucket. See Managed vs BYO.

The snapshot rule API​

Backed by the Program Service HTTP API (base path /program/api/v2; Bearer JWT with a service-account audience/role, project taken from the token):

Only maxDurSec is required; everything else is optional.

Examples​

Each example is the JSON body for POST /program/api/v2/streams/{id}/snapshot-rule.

A 30-second clip every minute (the common case — omit intervalSec to use the 60s default):

{ "maxDurSec": 30 }

A 10-second clip every 30 seconds (frequent short previews):

{ "maxDurSec": 10, "intervalSec": 30 }

Exactly one 15-second clip, then stop (one-shot — e.g. grab a single highlight on demand):

{ "maxDurSec": 15, "oneShot": true }
warning

oneShot and intervalSec are mutually exclusive — sending both returns 400 invalid_interval. In one-shot mode the server sets the interval itself.

Capture the 10 seconds leading up to each trigger (backfillSec clips the last N seconds from the live buffer — useful so the clip includes the moment that prompted it, not just what comes after):

{ "maxDurSec": 30, "intervalSec": 120, "backfillSec": 10 }

Keep short clips when a stream ends early (minDurSec < maxDurSec saves partial clips down to that floor; omit it and a stream that ends mid-clip discards the partial):

{ "maxDurSec": 60, "intervalSec": 300, "minDurSec": 15 }

Pin the rendition to clip (formats selects which encoding/bitrate to capture by its selector, e.g. the 2300 kbps rendition; defaults to the project's archiving formats):

{ "maxDurSec": 30, "formats": ["2300"] }

How the parameters interact​

  • maxDurSec vs intervalSec — read as "a maxDurSec-second clip every intervalSec seconds." Keep maxDurSec ≤ intervalSec so clips don't overlap; e.g. maxDurSec: 30, intervalSec: 30 captures back-to-back, maxDurSec: 30, intervalSec: 300 captures a 30s clip every 5 minutes.
  • backfillSec — accuracy is keyframe-bound and capped by the source buffer, so the actual lead-up may be shorter than requested (most reliable on transcoded streams). 0/omitted captures forward from the trigger.
  • minDurSec — defaults to maxDurSec (partials discarded). Set it lower to keep clips cut short by the stream ending.
  • oneShot — the rule expires server-side after one maxDurSec clip; pair it with backfillSec to grab a single moment-of-interest including its lead-up.

Editing / removing a rule​

  • Edit — change clip length, cadence, look-back, etc.; effective within a few seconds.
  • Remove (DELETE …/snapshot-rule) — stops further capture. Already-captured clips remain in storage.
  • Storage Profiles — where snapshots are stored (managed vs BYO) and the snapshot gallery + download keys.
  • Snapshot captures also emit snapshot-* lifecycle events — see Webhooks.