Open Source Ad Normalizer for SGAI available as a service

5 min readJan 30, 2025

In a previous blog we outlined how you can get started with testing and evaluating Server-Guided Ad-Insertion (SGAI) without having to modify your current streaming setup. In this blog we will extend this setup by adding a new open source component that will transcode the ad creatives to align with the content for a seamless experience for the end users.

Server-Guided Ad-Insertion (SGAI) is an ad-insertion technology where the server signals the ad-breaks and the video player handles the ad-insertion. The server provides the players with a common streaming manifest that contains instructions to the player on when and how to reach an ad-server. When the player reaches an ad-insertion opportunity it reaches out to the ad-server and receives an XML with the ads to insert.

The media files for the ad creatives in the ad-server response are in most cases not from a video file perspective aligned with the main content and this can cause some challenges to provide a smooth transition for the viewer. To align these media files with the main content we have developed and open sourced a component we call an “Ad Normalizer”. This component acts as a proxy for the ad-server and parses the XML response from the ad-server. It will check all media files in the response and removes all ads in the XML that does not have a normalized media file before it is returned to the client. The media files for the removed ads are normalized using an SVT Encore based transcoder and packaging pipeline in Eyevinn Open Source Cloud.

Launch your setup in Eyevinn Open Source Cloud

We will setup and launch this setup using the open web services available in Eyevinn Open Source Cloud, however as they are all open source they can be launched in your own premises or cloud infrastructure.

A prerequisite is that you have an account in Eyevinn Open Source Cloud and your account is on the Business subscription plan. If you don’t have an account already you can signup here.

Step 1: Setup a Test Adserver

In this setup we will use a “mock” ad-server and we will use the Test Adserver available in Eyevinn Open Source Cloud. Navigate to the service in the web console.

Click on the Create test-adserver button and give this instance a name.

Step 2: Setup transcoding and packaging pipeline

Now we will setup the transcoding and packaging pipeline that is used to “normalize” the ad creative media files. Follow the instructions to setup a transcoding and packaging pipeline and when creating the packager instance you need to set the OutputSubfolderTemplate to $EXTERNALID$/$JOBID$

Step 3: Create Ad Normalizer instance

Navigate to the Ad Normalizer service in the Eyevinn Open Source Cloud web console and press button “Create normalizer”.

Give your instance a name (for example “blog”).
Insert the URLs of the encore instance running in your pipeline, e.g. https://eyevinnlab-demo.encore.prod.osaas.io
Insert the URL to the callback listener instance endpoint, e.g https://eyevinnlab-demo.eyevinn-encore-callback-listener.auto.prod.osaas.io/encoreCallback
Insert the url of your ad server endpoint, e.g. https://eyevinnlab-blog.eyevinn-test-adserver.auto.prod.osaas.io/api/v1/vast
For OutputBucketUrl, insert an S3 URL (other formats may be supported later), for ex. s3://demoassets assuming that the bucket you created in step 2 is called demoassets .
Fill in the AccessKey and SecretKey to access the storage instance
Insert the endpoint used to reach your s3 compatible storage instance
Insert your Open Source Cloud personal access token (PAT). You obtain this token by going to Settings in the left navigation bar and then select the tab API.

Once your deployment is up and running, you can verify that it works as intended by making a request to the endpoint /api/v1/vast.

For example:

% curl -v -H 'accept: application/json' \
  "https://eyevinnlab-demo.eyevinn-ad-normalizer.auto.prod.osaas.io/api/v1/vast?dur=30"

If the instance is brand new, and your redis instance is unpopulated, you should get the following response:

{"ASSETS": []}

When the ad creative media files have been normalized the response will instead give:

% curl -v -H 'accept: application/json' \
  "https://eyevinnlab-demo.eyevinn-ad-normalizer.auto.prod.osaas.io/api/v1/vast?dur=30"
{"ASSETS":[{"URI":"https:/eyevinnlab-adnormalizer.minio-minio.auto.prod.osaas.io/adassets/AAA2FBBBB1232F1/7c0bd98e-20ff-43ff-bc5a-e1cd0491d94c/index.m3u8","DURATION":10},{"URI":"https:/eyevinnlab-adnormalizer.minio-minio.auto.prod.osaas.io/adassets/AAA2FDDDD1232F2/221dfa61-4351-43cb-bf24-f5d0c4b19510/index.m3u8","DURATION":15}]}

Step 4: Create SGAI proxy

Launch the SGAI proxy and test source as we described in previous blog post but skip the step to setup the Test Adserver as this has already been done. The VAST endpoint to use will now be the Ad Normalizer endpoint instead of the ad server.

Fill in a name (e.g., demo)
Parse Test Ad Server VAST endpoint from Step 3: https://eyevinnlab-demo.eyevinn-ad-normalizer.auto.prod.osaas.io/api/v1/vast?dur=[template.duration]&uid=[template.sessionId]&ps=[template.pod]
And Origin URL to the test source: https://eyevinnlab-sgai.eyevinn-docker-testsrc-hls-live.auto.prod.osaas.io/loop/master.m3u8
Choose insertion mode: dynamic
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-blog.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/loop/master.m3u8

Insert that in your AVPlayer and you will see the test source as you did before. Now it is time to actually insert an ad-insertion opportunity. Use an HTTP client (curl or Postman) of your choice and send this command to the proxy:

% curl "https://eyevinn-blog.eyevinn-sgai-ad-proxy.auto.prod.osaas.io/command?in=5&dur=10&pod=2"

Conclusion

With the Ad Normalizer we can provide a smooth and seamless transition between content and ad break and in general an improved viewing experience for the viewer. All components mentioned in this blog are available as open source and by making them available in Eyevinn Open Source Cloud you can get started without having to do any modifications to your current deployment.