Format Availability (Format Begin / Format End)

Native Frame notifies you when a transcode variant (an encoding — e.g. a 540p HLS rendition) becomes available (Format Begin) or unavailable (Format End) on a live stream. Use it to surface a quality option, kick off downstream processing, or track which renditions are live.

These are notifications — informational only. You don't return a verdict, and they can't stop a stream.

How you receive format events

There are two delivery methods — both carry the same payload (below). The broadcast is identified by its streamID.

Method	How it works
Program-states webhook (recommended)	Format events arrive on your registered program-states webhook as format-started / format-ended token events — nothing extra to implement.
Legacy callbacks	Native Frame calls HTTP endpoints you host — PUT for Format Begin, DELETE for Format End.

Program-states webhook

On the producing stream's token, event is format-started (Format Begin) or format-ended (Format End), and payload carries the format detail. streamID, streamName, and programID come from the surrounding context. (Delivered via the events service, you receive the payload only — your registered endpoint identifies the project.)

{
  "event": "program-states-v2",
  "payload": {
    "programs": {
      "<programID>": {
        "streams": {
          "<streamID>": {
            "producing": [
              {
                "streamName": "default",
                "token": {
                  "type": "token",
                  "value": "<authKey>",
                  "event": "format-started",
                  "payload": {
                    "videoCodec": "h264",
                    "audioCodec": "aac",
                    "manifest": "https://cdn.example.com/manifest.m3u8",
                    "location": "https://cdn.example.com/",
                    "clientEncoder": "obs",
                    "encodings": [
                      {
                        "isOriginal": true,
                        "videoWidth": 1280, "videoHeight": 720,
                        "videoKbps": 2500, "audioKbps": 128,
                        "videoPts": 12478, "audioPts": 12478,
                        "collected": 1718040000000,
                        "location": "https://cdn.example.com/720p/"
                      }
                    ]
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

See the Webhooks API reference for the full program-states contract and event catalog.

Legacy callbacks

Native Frame calls endpoints you host, identified by streamID and the format/encoding name.

Format Begin — an encoding becomes available:

PUT {host}/integration/v1/broadcast/{streamID}/encoding/{format}

The request body is the format payload. Respond 200:

{ "status": "OK", "message": "Broadcast can continue" }

Format End — an encoding becomes unavailable:

DELETE {host}/integration/v1/broadcast/{streamID}/encoding/{format}

No request body. Respond 200:

{ "status": "OK", "message": "Encoding removed" }

Format payload

Both methods deliver the same Format Begin payload:

Field	Type	Notes
videoCodec	string	e.g. h264
audioCodec	string	e.g. aac
manifest	string	Viewer playback manifest URL
location	string	Base media location (direct playback / pull)
clientEncoder	string	Broadcast encoder in use, e.g. obs, FMLE
encodings[]	array	One entry per variant — see below

Each encodings[] entry:

Field	Type	Notes
isOriginal	boolean	true if this is the origin stream (not a transcoded variant)
videoWidth, videoHeight	integer	Resolution
videoKbps, audioKbps	integer	Streaming rates (kbps)
videoPts, audioPts	integer	Current presentation timestamps
collected	integer	Sample time in unix millis (0 if no sample available)
location	string	Direct playback / pull URL for this variant

Format End carries only the streamID — the encoding is identified by the callback path ({format}), or by the surrounding token context on the webhook.

Behaviour

• Notifications, not gates — your response (or HTTP status) doesn't stop anything, unlike control events such as starting/polling.
• Format End mid-stream — it usually precedes broadcast end, but can fire mid-stream if a variant is lost while the stream is still live.
• A stream that publishes multiple renditions reports them in encodings[]; the origin entry has isOriginal: true.

Migrating from the legacy encoding callback

If you previously integrated the lgbx PUT /nativeframe/:private_key/encoding/:encoding callback, the contract is the same — but the broadcast is now identified by streamID (not the legacy private/stream key). You can keep the callback model (paths above) or move to the program-states webhook; both deliver the same payload.

For the complete webhook contract and event catalog, see the Webhooks API reference.