Getting Started

The SGAI-Proxy is a simple HTTP proxy server that inserts ads into a video stream. It is designed to be used together with a video player (e.g., AVPlayer) that supports Server Guided Ad Insertion (SGAI). The proxy server intercepts the video stream from the origin server and inserts ads into the media playlist as interstitials at specified time points.

Prerequisites

• If you have not already done so, sign up for an OSC account.

Step 1: (Optional) Create the origin stream

You can use any HLS (VoD or Live) stream as the origin stream. For testing with a VoD stream, consider using the OSC demo reel as input. Alternatively, you can use your own HLS stream, such as a live stream hosted on your server, as the origin stream.

Another option is to create a test stream using the Test Source HLS VoD service. To do this, click the "Create testsource" button in the web interface and provide a name for the test source stream (e.g., sgai).

Then the stream will be available at https://${TENANT_ID}-${SOURCE_NAME}.eyevinn-docker-testsrc-hls-live.auto.prod.osaas.io/loop/master.m3u8

For example, https://eyevinnlab-sgai.eyevinn-docker-testsrc-hls-live.auto.prod.osaas.io/loop/master.m3u8

Step 2: (Optional) Preview the origin stream in Safari

Open the stream URL in Safari to preview the content. This step is optional but can help you verify that the stream is working correctly before proceeding with ad insertion.

Step 3: Create a Test Ad Server instance

Click on the "Create test-adserver" button and name it (e.g., sgai).

Then the VAST endpoint will be https://${TENANT_ID}-${AD_SERVER_NAME}.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/vast

For example, https://eyevinnlab-sgai.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/vast

To request ad breaks, one could use URL: https://eyevinnlab-sgai.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]

Here the dur and ps specify the duration and ad number of the break while uid stands for the user ID. Query parameter values like [template.*] will be handled by the proxy server later.

Step 4: (Optional) Create an Ad Normalizer instance

Optionally, you can use the [Ad Normalizer service] (https://github.com/EyevinnOSC/community/wiki/Service:-Ad-Normalizer) to proxy the test ad server. This service acts as middleware between an ad server and our SGAI proxy which needs processed assets for stitching or playback. The ad normalizer accepts VAST requests and returns a list containing the relevant creatives that are immediately available to stream. Creatives that have not been processed are sent to SVT Encore for transcoding.

Step 5: Create a SGAI proxy instance

Click on the "Create proxy" button.

1. Fill in a name (e.g., demo)
2. Parse Test Ad Server VAST endpoint from Step 3: https://eyevinnlab-sgai.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]
3. (Optional) Or Ad normalizer VAST endpoint from Step 4: https://eyevinnlab-sgai.eyevinn-ad-normalizer.auto.prod.osaas.io/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]
4. And Origin URL from Step 1: https://eyevinnlab-sgai.eyevinn-docker-testsrc-hls-live.auto.prod.osaas.io/loop/master.m3u8
5. Choose insertion mode: dynamic
6. Skip the rest and create it

Then the proxied stream will be available at https://${TENANT_ID}-${PROXY_NAME}.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/loop/master.m3u8

For example, https://eyevinnlab-demo.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/loop/master.m3u8

Alternatively, if the origin stream is VoD e.g., https://lab.cdn.eyevinn.technology/osc/osc-reel/a4e1156e-f872-455f-9f1f-be73b5effba8/index.m3u8, the proxied stream will be available at https://eyevinnlab-demo.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/osc/osc-reel/a4e1156e-f872-455f-9f1f-be73b5effba8/index.m3u8

Step 6: View the stream in QuickTime Player

Open the stream URL in QuickTime Player to view the proxied stream.

Step 7: Insert ad breaks with the curl command

via /command endpoint

For example, curl https://eyevinnlab-demo.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/command?in=0&dur=10&pod=2

This command will insert an ad break at 0 seconds to the live edge with a duration of 10 seconds and a pod number of 2.

Step 8: (Optional) Static ad insertion for VoD streams

If you want to insert ads into a VoD stream, you MUST choose static ad insertion mode instead. This is essential for VoD streams, as they do not support real-time ad insertion.

This option will create a fixed set of ad breaks in advance and have them inserted into the stream without the need for dynamic ad requests. It is useful for testing purposes or when you want to have a predictable ad experience. However, it may not be suitable for all use cases, as it does not allow for real-time ad decisioning or targeting.