The Live Heartbeat is a Global Notification that can be configured to be deployed to all live encoders in an organization. Once enabled as a global variable, the live heartbeat service will be deployed on all instances used for live encodings from that point forward.

The service provides a push notification as a webhook to a defined endpoint, each Live Encoder is therefore responsible for providing the notification to that endpoint and in this way it can be considered the single source of truth about a live encoders health and reported status. Deploying the heartbeat directly to the live encoder infrastructure also allows this service to scale, without the risk of their being a bottleneck in the Bitmovin multitenant platform.

Enabling the Live Heartbeat

The live heartbeat is a global setting - therefore once configured all live encodings will start posting updates.

📘

It is possible to configure multiple Heartbeats, to multiple endpoints.

However the payload of will always been the same and can not be modified.

Via the Dashboard

To enable the notification navigate to Notifications in the Configurations settings under Live Encoding

Form here it is possible to configure triggered event notifications via Webhook & Email, and Heartbeat.

Pressing Create+ will open a pop-up window where the Heartbeat can be configured and saved.

Interval can be set in seconds, by default it will be 20 seconds, at minimum it can be 1 second.

Once created the Live Heartbeat can be reviewed and deleted.

Via the API

The new “Live Encoding Heartbeat” webhook can be configured via the
/notifications/webhooks/encoding/encodings API.

To list current heartbeats, use List 'Live Encoding Heartbeat' Webhooks

To create, use Add 'Live Encoding Heartbeat' Webhook

To get details, use 'Live Encoding Heartbeat' Webhook Details

To delete, use Delete 'Live Encoding Heartbeat' Webhook

Once configured all Live Encodings started afterward will send the webhook in a fixed interval.

Payload

Below is an example payload.

{
  "encoding": {
    "cloudRegion": "AWS_EU_WEST_1",
    "id": "232610f5-ff80-4146-a21b-54dd123fb5fd",
    "name": "Test Live Heartbeat",
    "encoderVersion": "BETA",
    "type": "LIVE"
  },
  "webhookId": "1c03498b-0454-42d4-8f05-48ecb45fe7ee",
  "orgId": "1f4cf17c-c6a6-4e9a-8f6f-6776ebe571da",
  "resourceId": "cf9e71b5-e136-40ad-a47b-788568a4edc5",
  "resourceType": "ENCODING",
  "triggeredAt": "2024-06-14T12:15:41.489249069Z",
  "value": {
    "ingest": {
      "healthy": true,
      "status": "CONNECTED",
      "streamInfos": [
        {
          "bitrate": 1303552,
          "codec": "h264",
          "healthy": true,
          "incomingBitrate": 211394.43333333332,
          "lastArrivalTime": "2024-06-14T12:15:41:455Z",
          "lastTimestamp": 107858,
          "mediaType": "video",
          "rate": 23,
          "samplesReadPerSecondAvg": 23.96666666666667,
          "streamId": "0",
          "lastTimestampTimescale": 1000,
          "height": 1080,
          "width": 1920
        },
        {
          "bitrate": 128000,
          "codec": "aac",
          "healthy": true,
          "incomingBitrate": 16609.149999999998,
          "lastArrivalTime": "2024-0-14T12:15:41:476Z",
          "lastTimestamp": 107899,
          "mediaType": "audio",
          "rate": 44100,
          "samplesReadPerSecondAvg": 44100.26666666666,
          "streamId": "1",
          "lastTimestampTimescale": 1000,
          "height": null,
          "width": null
        }
      ]
    }
  },
  "id": "85f0fdde-4f26-42df-bc1a-4807cc586906",
  "eventType": "LIVE_ENCODING_HEARTBEAT",
  "customData": {}
}

Payload Explanation

• encoding : Contains information about the live encoding configuration
  • cloudRegion: Cloud region where the encoding is running
  • id: Unique identifier for the encoding
  • name: Name of the encoding
  • encoderVersion: Version of the encoder being used
  • type: Indicates the encoding type (that it is a live encoding)
• webhookId: Unique identifier for the webhook
• orgId: Organization ID that owns this encoding
• resourceId: ID of the resource (if the resourceType is ENCODING it would refer to the encoding ID)
• resourceType: Type of the resource for which the webhook was fired. (e.g.: ENCODING)
• triggeredAt: Timestamp (ISO 8601-Format) corresponding to a given heartbeat notification trigger time
• value: Contains the actual heartbeat data
  • ingest: Information about the input stream
    • healthy: Current health status of the ingest
    • status: Current status of the input stream (CONNECTED, WAITING_FOR_FIRST_CONNECT, DISCONNECTED, ERROR, UNKNOWN)
    • streamInfos: Array of information about each stream (video/audio)
      Each stream in streamInfos contains:
      • bitrate: The bitrate of the input data in bits per second (0 if input is not healthy)
      • codec: Codec being used (eg. h264 for video, aac for audio)
      • healthy: Health status of this specific stream
      • incomingBitrate: Average actual incoming bitrate (not to confuse with bitrate field) in bytes per second during the last minute
      • lastArrivalTime: Timestamp (ISO 8601-Format) of the last received input stream packet
      • lastTimestamp: Presentation timestamp (PTS) (the time at which the decompressed packet will be presented to the user) of the last received input stream packet
      • mediaType: Type of media (video/audio)
      • rate: Input stream frame rate for video or input sample rate for audio
      • samplesReadPerSecondAvg: Average frames/samples processed per second during the last minute
      • streamId: Unique identifier for this stream (0, 1, ..)
      • lastTimestampTimescale: Timescale for lastTimestamp
      • height: Video height in pixels (null for audio)
      • width: Video width in pixels (null for audio)
• id: Unique identifier for this heartbeat event
• eventType: Type of event being reported (eg. LIVE_ENCODING_HEARTBEAT)
• customData: Additional custom data