View a markdown version of this page

MediaTailor server-guided ad insertion configuration for live streams - AWS Elemental MediaTailor
Requirements for live SGAILive playback configurationSGAI live manifest requestsManifest-based prefetch for live SGAITesting SGAI live configuration

MediaTailor server-guided ad insertion configuration for live streams

AWS Elemental MediaTailor server-guided ad insertion for live content provides significant performance benefits through cacheable manifests. Configuring SGAI for live content uses the same core parameters as VOD, with specific considerations for live stream characteristics and real-time processing.

Requirements for live SGAI

Before you enable SGAI for live content, ensure that you have the following:

  • Your live stream includes properly formatted DATERANGE markers

  • Ad break durations are consistent and predictable

  • Your CDN is configured to cache SGAI manifests appropriately

  • Players support server-guided ad insertion workflows

  • Your ad decision server can handle real-time requests for live content

Player requirements

Players must be configured to handle SGAI live manifests properly:

  • Support for server-guided ad insertion workflows

  • Ability to process ad insertion guidance from manifests

  • Proper handling of live stream timing and synchronization

  • For HLS content: Support for HLS version 8 and EXT-X-DATERANGE with CLASS attribute. Version 11 for server-side beaconing.

  • For HLS content: EXT-X-DEFINE variable substitution support

Live playback configuration

To enable SGAI for live content, create a playback configuration that has the following settings:

Example SGAI live playback configuration

{
  "Name": "LiveSGAIConfig",
  "VideoContentSourceUrl": "https://your-live-origin.com/live/stream.m3u8",
  "AdDecisionServerUrl": "https://your-ads.com/ads",
  "PersonalizationThresholdSeconds": 1,
  "InsertionMode": "PLAYER_SELECT"
}

The following are key considerations for live SGAI configuration:

VideoContentSourceUrl

Must point to a live HLS stream with properly formatted SCTE-35 DATERANGE markers. The stream should maintain consistent segment durations and bitrate variants.

SGAI live manifest requests

SGAI live manifests use the same URL pattern as traditional ad insertion:


https://your-config.mediatailor.region.amazonaws.com/v1/master/config-name/manifest.m3u8?aws.insertionMode=GUIDED

Manifest-based prefetch for live SGAI

For live SGAI workflows, you can enable manifest-based prefetch heartbeating to reduce ad fill latency. Add aws.guidedPrefetchMode=MANIFEST to the manifest request:

https://your-config.mediatailor.region.amazonaws.com/v1/master/config-name/manifest.m3u8?aws.insertionMode=GUIDED&aws.guidedPrefetchMode=MANIFEST

When enabled, MediaTailor appends a session identifier (?aws.sessionId=<id>) as a query parameter to each interstitial media manifest (/v1/i-media) URL in the multivariant playlist. Each time the player refreshes an i-media manifest, the request reaches MediaTailor with the session ID, which MediaTailor uses to identify the session and enqueue prefetch requests for upcoming ad breaks.

Important

Do not cache i-media manifests in your CDN when using guided prefetch. The prefetch heartbeating mechanism depends on the player's manifest refresh requests reaching MediaTailor directly. If your CDN caches and serves /v1/i-media responses, MediaTailor does not receive the heartbeat requests and cannot trigger prefetching. Configure your CDN to pass through /v1/i-media/* requests to MediaTailor when aws.guidedPrefetchMode=MANIFEST is in use.

Guided prefetch is independent of the reporting mode. Whether you use server-side (default) or client-side (aws.reportingMode=CLIENT) tracking, beacons fire at playback time, not when ads are prefetched. For general information about how ad prefetching works in MediaTailor, see Prefetching ads.

Testing SGAI live configuration

Verify your SGAI live setup with these validation steps:

  1. Test manifest generation

    Request the SGAI live manifest URL and verify it returns cacheable content with proper ad insertion guidance.

  2. Verify CDN caching

    Check that your CDN is caching SGAI manifests according to the configured TTL values.

  3. Test ad insertion

    Confirm that players can successfully insert ads using the guidance provided in SGAI manifests.

  4. Monitor performance

    Use CloudWatch metrics to verify reduced origin load and improved cache hit rates.