Service: SGAI Proxy - EyevinnOSC/community GitHub Wiki

SGAI Proxy

SGAI Proxy (serviceId eyevinn-sgai-ad-proxy, catalog page) is an HTTP proxy that inserts ads into an HLS stream using Server Guided Ad Insertion (SGAI). It intercepts the stream from the origin server and adds ads to the media playlist as interstitials at specified time points. It is a long-running service instance. License: Apache-2.0.

What it can do

  • Proxy an HLS origin (live or VoD) and insert ad interstitials, for players that support SGAI such as QuickTime Player, AVPlayer or HLS.js 1.6.0+.
  • Fetch ads from any VAST 4.0/4.1 XML compatible endpoint, such as the OSC Test Ad Server or Ad Normalizer.
  • Insert ad breaks on demand (dynamic mode, live content only) or at fixed intervals (static mode, also for VoD).
  • Personalize ads through query parameters in the ad server URL and in the playlist URL.

Creating an instance

Create and confirm running first:

  • An origin HLS stream: any HLS (VoD or live) URL, or an OSC Test Source HLS Live instance (eyevinn-docker-testsrc-hls-live, stream at https://<tenant>-<name>.eyevinn-docker-testsrc-hls-live.auto.prod-se.osaas.io/loop/master.m3u8).
  • A VAST ad server: a Test Ad Server instance (eyevinn-test-adserver, VAST endpoint https://<tenant>-<name>.eyevinn-test-adserver.auto.prod-se.osaas.io/api/v1/vast) or an Ad Normalizer instance (eyevinn-ad-normalizer). The Ad Normalizer proxies an ad server and returns creatives that are ready to stream; unprocessed creatives are sent to SVT Encore for transcoding.

Then call create-service-instance with serviceId: "eyevinn-sgai-ad-proxy":

{
  "name": "demo",
  "VastEndpoint": "https://<tenant>-<name>.eyevinn-test-adserver.auto.prod-se.osaas.io/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]",
  "OriginHost": "<tenant>-<name>.eyevinn-docker-testsrc-hls-live.auto.prod-se.osaas.io",
  "OriginUrl": "https://<tenant>-<name>.eyevinn-docker-testsrc-hls-live.auto.prod-se.osaas.io/loop/master.m3u8",
  "InsertionMode": "dynamic"
}

Verify with wait-for-service-ready or get-instance-status, then describe-service-instance for the URL. The [template.*] placeholders in VastEndpoint are replaced by the proxy before it calls the ad server.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
VastEndpoint Yes string VAST 4.0/4.1 XML compatible ad server endpoint URL. May include [template.duration], [template.sessionId] and [template.pod] placeholders, e.g. ...?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]; other query parameters are passed as is.
OriginHost Yes string Hostname or IP address of the origin HLS streaming server. Catalog marks it required; the upstream README only documents the full master playlist URL.
OriginUrl No string Complete URL to the master playlist of the origin HLS stream.
InsertionMode Yes string static or dynamic (upstream default static). static adds an interstitial every 30 seconds (1000 in total) and must be used for VoD. dynamic inserts a break when requested via /command and works for live content only.
DefaultAdDuration No string Default ad break duration in seconds (upstream default 13).
DefaultRepeatingCycle No string Repeat the ad break every n seconds in static mode (upstream default 30).
DefaultAdNumber No string Default number of ad slots to generate in static mode (upstream default 1000).
TestAssetUrl No string Replaces raw MP4 ad assets with this asset, which must be a fragmented MP4 VoD media playlist. Use when the player only accepts fMP4 and the ad server returns raw MP4.

Using the instance

The proxied stream is served at the instance URL with the origin's path, for example origin .../loop/master.m3u8 becomes https://<tenant>-<name>.eyevinn-sgai-ad-proxy.auto.prod-se.osaas.io/loop/master.m3u8. For a VoD origin such as https://lab.cdn.eyevinn.technology/osc/osc-reel/<id>/index.m3u8, the path /osc/osc-reel/<id>/index.m3u8 is used on the proxy URL. Open it in a player that supports SGAI.

In dynamic mode, insert an ad break at the live edge with a request to /command:

curl "https://<instance-url>/command?in=0&dur=10&pod=2"

in is the time in seconds, dur the break duration in seconds and pod the number of creatives. GET /status returns the proxy status. A player can add query parameters to the master playlist URL, and they are forwarded to the ad server request.

Example with the OSC CLI:

npx -y @osaas/cli create eyevinn-sgai-ad-proxy demo \
  -o VastEndpoint="https://<ad-server>/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]" \
  -o OriginUrl="https://<origin>/loop/master.m3u8" \
  -o InsertionMode=dynamic

Limitations

  • Each proxy instance handles one HLS stream at a time; restart is needed to switch streams (upstream README).
  • VoD origins require InsertionMode static; dynamic insertion is for live only.
  • Static mode creates a fixed set of breaks in advance and gives no real-time ad decisioning or targeting.

Resources

⚠️ **GitHub.com Fallback** ⚠️