Playlist manipulation

Stitcher is a playlist manipulator that can insert HLS interstitials on-the-fly.

Use cases

• Insert linear ads at given cue points, derived from a VMAP.
• Add a bumper playlist at the start of a playlist, like Netflix' intro. You wouldn't want to re-transcode an asset if a bumper changes.
• Filter a media playlist to exclude qualities, eg; free users can stream up to 720p.

Create a session

Providing input for the stitcher happens in the form of a uri. The support uri schemas are:

• asset://{assetId}

  We want to greatly simplify how you stitch playlists together. If you use the asset scheme, Superstreamer will know that you mean a package result from within the platform.

• http(s)://{url}/master.m3u8

  In case you want to use HLS playlists hosted elsewhere, you can use the http(s) scheme.

$ curl -X POST https://stitcher-superstreamer.domain.com/session
  -H "Content-Type: application/json"
  -d "{body}"

{
  "uri": "asset://2d6e6c0e-07d9-48b1-8192-318f32a3b909",
  // OR
  // If you provide a UUID without scheme, we'll assume it's an assetId:
  "uri": "2d6e6c0e-07d9-48b1-8192-318f32a3b909",
  // OR
  // An external playlist:
  "uri": "https://my-awesome-external-service/assets/123/master.m3u8"
}

The response includes the new playlist URL, and you can pass this on directly to the player. The UUID in the playlist URL is the sessionId. Superstreamer will keep a session in memory with information about the session.

{
  "url": "{PUBLIC_STITCHER_ENDPOINT}/session/625f68c2-6c09-44d4-a50f-81873cb7839b/master.m3u8"
}

That's nice and all, but all we did was play an asset through the stitcher. That's not very interesting. You're right, but what is interesting is the fact that we can manipulate the playlist for each session individually.

Filters

You can apply filters, such as limit the different resolutions. Filters can apply to both the master as the media playlist.

Resolution

When streaming over networks with limited bandwidth (eg; mobile networks), removing higher-bitrate renditions can help prevent buffering issues or excessive data usage, or if you want to serve a specific set of users with a lower resolution.

{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "filter": {
    // Remove all renditions with a height greater than 480
    "resolution": "<= 480"
  }
}

Interstitials

Let's say you transcoded and packaged a new asset, a bumper for example. We'll add it as an interstitial. An HLS interstitials supported player will then switch to the new asset at position 10 and when finished, it'll go back to the primary content.

{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "interstitials": [
    {
      "timeOffset": 10,
      "uri": "asset://abbda878-8e08-40f6-ac8b-3507f263450a"
    }
  ]
}

If you'd like to add a bumper, you'd insert an interstitial at position 0.

Linear ads

We solely work with standards. VMAP (Video Multiple Ad Playlist) is an XML-based specification that defines how multiple ad breaks can be inserted into a video stream. Instruct Stitcher to add interstitials based on VMAP definitions. Each VMAP contains one or more AdBreak elements with a position of where the interstitial should be.

{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "vmap": {
    "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpost&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator="
  }
}

Stitcher will perform a couple of actions behind the scenes:

• Fetches the VMAP. Parses, resolves and flattens each corresponding VAST. For each ad that has not yet been transcoded, it'll start a transcode and package job with sane defaults.
• Each transcode or package job responsible for an ad is tagged with ad and can be observed in the dashboard.
• For each ad break that is available, it'll add an interstitial so that players can play the ad.

WARNING

Ad impressions are not tracked yet, we'd eventually like to provide a client wrapper that tracks ads in a certified manner. There's a spec on the way! More news later.