Show live stream health stats to your streamer

In this guide you will learn how to use the Live Stream Health StatsBeta API in order to embed the live stream health stats for a particular live stream ID into your applications. A common use case is when you want to show the live stream stats to your streamer during a live event, so that the streamer can monitor the status and take actions when issues occur.

You will use JSON Web Tokens to authenticate to this API.

1. Understand Live Stream Stats

The Live Stream Stats API returns Stream Drift Session Average, Stream Drift Deviation From Rolling Average, and Status. Before we dive into each of them, understanding a couple of terms here might be helpful:

• Wallclock time: Also called the real-world time.
• Stream drift: The difference between elapsed media time and elapsed wallclock time. For example, if your encoder has been connected for 10 seconds and it has sent 5 seconds of media during that time, then your current stream drift would be 5s.

Now keep reading below for the metrics the API returns and their definitions.

Stream Drift Session Average

Stream Drift Session Average is the running average of stream drift for the lifetime of an ingest connection. It applies a smoothing function to the potentially jagged, fluctuating raw metric. Use this metric as an indication of the average offset between the elapsed wallclock time and media time throughout the whole session.

The value we return from the API is measured in miliseconds and is continuously updated with each measurement taken. It is reset whenever the encoder disconnects.

Stream Drift Deviation From Rolling Average

To get an indication of whether the current drift is consistent (good) or growing (bad), use Deviation From Rolling Average. It is the difference between current stream drift and current stream drift rolling average. The rolling average only takes the last ~30s of data into account, so it represents the recent drift, rather than measurements taken potentially long time ago. Disparities between current drift and the rolling average can be a good indicator because session average moves slower and may not reflect the latest status.

Use this metric to understand whether the stream is experiencing issues at the moment. When it is, the Deviation From Rolling Average will likely be high.

Status

The status returned from the Live Stream Health API could be any of the following values: excellent, good, poor, or unknown.

• excellent: The Stream Drift Deviation From Rolling Average is less than or equal to 500ms
• good: The Stream Drift Deviation From Rolling Average is less than or equal to 1s but greater than 500ms
• poor: The Stream Drift Deviation From Rolling Average is greater than 1s
• unknown: We are unable to calculate the stream drift. This is usually because the live stream is inactive and/or we have not received any data about it for a few minutes.

Use status as an indicator of the latest health status of the live stream ingest. A common use case is to render color coded UI for your streamer's ease-of-use based on the status information, such as green, yellow, or red. You can also check out our pre-built UI to monitor the status by going to the Mux Dashboard for the specific live stream.

2. Create a Signing Key

Signing keys can be managed (created, deleted, listed) from the Signing Keys settings of the Mux dashboard or via the Mux System API.

When creating a new signing key, the API will generate a 2048-bit RSA key pair and return the private key and a generated key ID; the public key will be stored at Mux to validate signed tokens. Store the private key in a secure manner.

You probably only need one signing key active at a time and can use the same signing key when requesting live stream stats for multiple live streams. However, you can create multiple signing keys to enable key rotation, creating a new key and deleting the old only after any existing signed URLs have expired.

Example request

curl -X POST \
-H "Content-Type: application/json" \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET} \
'https://api.mux.com/system/v1/signing-keys'

Example response

// POST https://api.mux.com/system/v1/signing-keys
{
  "data": {
    "private_key": "(base64-encoded PEM file with private key)",
    "id": "(unique signing-key identifier)",
    "created_at": "(UNIX Epoch seconds)”
  }
}

This can also be done manually via the UI. If you choose to create and download your signing key as a PEM file from UI, you will need to base64 encode it before using it with (most) libraries.

❯ cat /path/to/file/my_signing_key.pem | base64
LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktL...

3. Generate a JSON Web Token

The following JWT claims are required:

Expiration time

Expiration time should be at least the duration of the live stream. When the signed URL expires, you will no longer be able to receive live stream stats data from the API.

4. Signing the JWT

The steps can be summarized as:

1. Load the private key used for signing
2. Assemble the claims (sub, aud, exp, kid etc) in a map
3. Encode and sign the JWT using the claims map and private key and the RS256 algorithm.

There are dozens of software libraries for creating and reading JWTs. Whether you’re writing in Go, Elixir, Ruby, or a dozen other languages, don’t fret, there’s probably a JWT library that you can rely on. For a list of open source libraries to use, check out jwt.io.

package main

import (
    "encoding/base64"
    "fmt"
    "log"
    "time"
    "github.com/golang-jwt/jwt/v4"
)

func main() {

    myId := ""       // Enter the id for which you would like to get counts here
    myIdType := ""   // Enter the type of ID provided in my_id; one of video_id | asset_id | playback_id | live_stream_id
    keyId := ""      // Enter your signing key id here
    key := ""        // Enter your base64 encoded private key here

    decodedKey, err := base64.StdEncoding.DecodeString(key)
    if err != nil {
        log.Fatalf("Could not base64 decode private key: %v", err)
    }

    signKey, err := jwt.ParseRSAPrivateKeyFromPEM(decodedKey)
    if err != nil {
        log.Fatalf("Could not parse RSA private key: %v", err)
    }

    token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
        "sub": myId,
        "aud": myIdType,
        "exp": time.Now().Add(time.Minute * 15).Unix(),
        "kid": keyId,
    })

    tokenString, err := token.SignedString(signKey)
    if err != nil {
        log.Fatalf("Could not generate token: %v", err)
    }

    fmt.Println(tokenString)
}

5. Making a Request

Supply the JWT in the resource URL using the token query parameter. The API will inspect and validate the JWT to make sure the request is allowed.

Example:

curl 'https://stats.mux.com/live-stream-health?token={JWT}'

Response:

{
  "data": [
    {
      "ingest_health": {
        "updated_at": "2022-11-14T17:32:23",
        "stream_drift_session_avg": 384,
        "stream_drift_deviation_from_rolling_avg": 12,
        "status": "excellent",
        },
    },
  ],
}

• stream_drift_session_avg is the session average of stream drift. Use this to represent the overall health of the stream.
• stream_drift_deviation_from_rolling_avg is the delta between the current stream drift and the rolling average. Use this to represent the latest stream health.