Thumbnail hooks

Thumbnail preview is a feature that allows you to get a preview thumbnail image of your video stream. Thumbnails are delivered via a webhook POST request to your server so that you can save the image and distribute with your infrastructure.

If thumbnail functionality is enabled for the stream, it will extract an intra frame from the incoming feed to create a thumbnail. While the stream has an active publisher, a Thumbnail webhook is sent at most every 30 seconds.

The thumbnail webhook is a POST request that will be sent to the webhook URL with a body of a JPEG image and Content-Type of image/jpeg. You will need to host the image in you own infrastructure or CDN for your customers.

The following HTTP headers are on the request to identify stream details:

• X-Millicast-Timestamp: timestamp of the generated thumbnail.
• X-Millicast-Feed-Id: Dolby.io Real-time Streaming feed id.
• X-Millicast-Stream-Id: Dolby.io Real-time Streaming stream id.
• X-Millicast-Signature: SHA1 signature using the hook configured secret (The same signature mechanism used by the other webhooks).

Enabling thumbnail preview:

• Enable thumbnail preview for each API token in the dashboard publishing token settings.
• Use the Publish Token - Create token call

{
     "streams": [
          {
               "isRegex": false,
               "streamName": "thumbnails"
          }
     ],
     "subscribeRequiresAuth": false,
     "record": false,
     "multisource": false,
     "label": "thumbnails",
     "enableThumbnails": true
}

• Images are sent via webhook (currently the webhook must be enabled via the API for webhooks). See isThumbnailHooks.

{
    "url": "https://your-webhook-url.com",
    "isFeedHooks": false,
    "isRecordingHooks": false,
    "isThumbnailHooks": true
}

Limitations

• Currently only VP8, H264 and VP9 are supported. H265 and AV1 are not supported.
• Rescaling is not supported. The thumbnail will be the same resolution as the incoming stream.
• Thumbnails cannot be configured to send faster than every 30 seconds.
• Regular intra frames are required to generate the thumbnails.

Resources

We have some sample code to demonstrate receiving a thumbnail hook and saving it to disk: Webhook Code Example (download and save)