Interstitials payload structure for Stitcher

[matvp91]

When we want to insert one or multiple interstitials with Stitcher, we use the interstitials array on session initialise. Each interstitial in the list is mapped as an asset internally. Given the following payload:

{
  "interstitials": [
    {
      "time": 0,
      "uri": "https://example.com/master.m3u8"
    },
    {
      "time": 0,
      "vast": {
        "url": "https://ad-server.com/vast.xml"
      }
    }
  ]
}

We would then loop over each interstitial defined above, for a given dateTime, and use that to populate the ASSETS response in the asset list. From a high level perspective, we're not defining an interstitial in a stream, we're defining an asset when we manually provide a uri, or we use the VAST url to resolve multiple assets behind the scenes. In the payload, there is no distinction between an interstitial and an asset (one or multiple) of a particular interstitial. This no longer makes sense to me for the following reasons:

• If we want to introduce properties solely related to the interstitial (like X-PLAYOUT-LIMIT), there would be no way to do that explicitly.
• Internally, we do have the concept of an "asset" and an "interstitial". An interstitial can contain a list of assets. An interstitial can contain a VAST url which will resolve to a list of interstitials, or an interstitial may not use our own ASSET-LIST uri at all. We map the list of "interstitials" (which are really a list of assets), group them and structure them in a "one to many" relation anyways.

We experimented with discriminated unions, keeping the structure above, but I felt it would add more unnecessary boilerplate. I think that an interstitial cannot be strictly discriminated. For all we care, an interstitial may be a combination of a VAST url and a bumper playlist at the end, aslong as an interstitial resolves to playable assets somehow. Ideally, we'd want to rely on something like resolveInterstitialToAssets, and not worry about what info the interstitial holds. At least not at the point where all we'd want is a list of assets derived from an interstitial.

{
  "interstitials": [
    {
      "time": 0,
      "type": "asset",
      "uri": "https://example.com/master.m3u8",
    },
    {
      "time": 0,
      "type": "vast",
      "url": "https://ad-server.com/vast.xml",
    },
  ],
}

I'm leaning towards a hard split between interstitials and assets, in a non discriminated manner.

{
  "interstitials": [
    {
      "time": 0,
      // The propery below would end up in X-PLAYOUT-LIMIT
      "duration"?: 100,
      "assets": [
        {
          "uri": "https://example.com/master.m3u8",
        },
      ],
      // and / or
      "vast": {
        "url": "https://ad-server.com/vast.xml",
      },
      // and / or (when exclude, we'll use the url as X-ASSET-LIST)
      "assetList": {
        "url": "https://my-third-party.com/asset-list.json",
      },
    },
  ],
}

People are still free to split them, although we would not recommend this.

{
  "interstitials": [
    {
      "time": 0,
      "assets": [
        {
          "uri": "https://example.com/master_1.m3u8"
        },
      ],
    },
    {
      "time": 0,
      "assets": [
        {
          "uri": "https://example.com/master_2.m3u8"
        },
      ],
    },
  ],
}

When we populate interstitials, whether it's from a VAST url, or from manually inserting them as assets, we should normalize them. Stitcher should be able to handle the payload above, as there is no discrimination. At least this'll make the API very approachable.

A rightful comment made by @fcancela stated that "we'd not be consistent with how the rest of the API works", and I initially agreed. Although, I now think that there's a fundamental difference to, for example, defining input & stream in the /transcode endpoint and the list of interstitials in the /session endpoint. For a stream, there is no combination possible, a stream is either audio, video or text. It can't be a mix of those, thus it's discriminated. For an interstitial, it can be a list of manually inserted assets and a VAST url combined. One does not exclude the other.