Service: HLS VOD Stitcher - EyevinnOSC/community GitHub Wiki

HLS VOD Stitcher

HLS VOD Stitcher (serviceId eyevinn-lambda-stitch, license MIT) is a proxy that stitches another HLS VOD (for example ads) into an HLS VOD on the fly, either by manipulating the manifest or by using HLS interstitials. It is built on the @eyevinn/hls-splice library. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.

What it can do

  • Splice ad VODs into a source HLS VOD at given positions (pre-roll with pos: 0, or mid-roll).
  • Return HLS interstitial tags (DATERANGE with an asset list pointing back to the stitcher) instead of splicing server-side.
  • Use an asset list URL of your own (for example from an ad server) for each break.

Creating an instance

The stitcher has no dependencies on other OSC services. Call create-service-instance with serviceId: "eyevinn-lambda-stitch":

{ "name": "guide" }

Then wait-for-service-ready (or get-instance-status) and describe-service-instance to get the instance URL, which has the form https://<tenant>-<name>.eyevinn-lambda-stitch.auto.prod-se.osaas.io.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
AssetListBaseUrl No string The catalog gives no description for this option and the upstream README does not document it. Presumably a base URL used when building asset list URLs for interstitials; not verified.

Using the instance

Step 1: Generate a payload

POST a JSON body to /stitch/ on the instance. This example inserts an ad at the beginning (pre-roll). Replace the host with your instance URL:

curl -v -X POST -H "Content-Type: application/json" -d '{
  "uri": "https://maitv-vod.lab.eyevinn.technology/VINN.mp4/master.m3u8",
  "breaks": [
    { "pos": 0, "duration": 15000, "url": "https://maitv-vod.lab.eyevinn.technology/ads/apotea-15s.mp4/master.m3u8" }
  ]
}' https://eyevinn-guide.eyevinn-lambda-stitch.auto.prod-se.osaas.io/stitch/

The response is a JSON object with a uri such as /stitch/master.m3u8?payload=<base64>; the payload is the base64 encoding of the JSON you posted.

Step 2: Play the stitched stream

Append the returned path to the instance URL and give it to a video player:

https://eyevinn-guide.eyevinn-lambda-stitch.auto.prod-se.osaas.io/stitch/master.m3u8?payload=<base64>

HLS interstitials

  • i=1 on the master playlist URL returns an HLS with a DATERANGE interstitial whose X-ASSET-LIST points back to the stitcher (/stitch/assetlist/...), instead of splicing the ad segments.
  • c=1 both inserts the interstitial tags and splices in the ad segments.
  • A break can use your own asset list by giving assetListUrl instead of url, and optionally sn and re (for example "sn": "IN", "re": "SKIP,JUMP"):
{
  "uri": "https://lab.cdn.eyevinn.technology/VINN-OpbZjryxa3.mp4/manifest.m3u8",
  "breaks": [
    { "pos": 0, "duration": 15000, "assetListUrl": "https://urlto.your.adserving/service/hls/15-seconds-of-ads/assets" },
    { "pos": 75000, "duration": 45000, "assetListUrl": "https://urlto.your.adserving/service/hls/45-seconds-of-ads/assets", "sn": "IN", "re": "SKIP,JUMP" }
  ]
}

Each assetListUrl must return a JSON list: [ { "URI": "https://ad.content.origin/ad1/master.m3u8", "DURATION": 30 }, ... ]. Use i=1 together with the payload for this mode.

Resources

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