Adaptation Sets Splitting

You can activate this plugin with the string manifest_edit.plugins.mpd.adaptation_sets_splitting.

When generating a DASH MPD manifest, mp4split or the Origin assign representations to a specific Adaptation Set based on a set of rules. The assignment depends on the characteristics of your input file (VOD case) or on your encoder configuration (Live) and is designed to maximize compatibility.

There may be situations though where you want to change the way representations are assigned to a given adaptation sets, either because you need a customized manifest or because changing your input configuration is not an option.

For those situations, the adaptation_sets_splitting plugin can be used to edit the manifest generated by the Origin in such a way that selected representations are "moved" to one or more different Adaptation Set.

A concrete case that can serve as an example guideline is when a Live encoder does not send any information on track names. In absence of such information, the Origin would group in the same adaptation set all tracks sharing the same type (e.g. video) and language (e.g. eng). This may lead to undesired results in case more than one track share the same type and language (e.g. representations with different codecs are in the same adaptation set). In such cases, you many need to "split" that adaptation set.

For a use case where one Adaptation Set needs to be split into two or more, the questions to answer are:

1. Which representations from an Adaptation Set do I need to pick and move?

2. How do I assign that representations selection to a new, separate adaptation set?

The answer to this questions depends on your specific use case. In our example, we can imagine that the answers could be something like this:

1. I want to select a few representations from a given adaptation set based on codec type (e.g. those with codec containing hvc1 in video adaptation sets)

2. I want to assign them to a new adaptation set where they are the only representations present

We can generalize this example by considering that there will always be two or more "selections" to make (pick at least two different Representation subsets from a single Adaptation Sets) and an "action" to specify (express how one or more subsets will be assigned to a dedicated Adaptation Set).

This approach (select and edit) is useful for many other use cases. For this reason the "selection" syntax used in this plugin is common to many others and is described in the following dedicated chapter.

• Element Selection
  • Selection syntax
  • Attributes that are common to Adaptation Sets and Representations
  • Limitations

Adaptation Set Splitting configuration

Adaptation Set Splitting configuration represents the "how" part in the introduction above, or how to answer question number 2.

This section of the configuration file is used to associate a set_id to a particular Reprentations subset, using the following syntax:

set_id: <id>

You should choose the <id> value for each of your Representation subset by keeping in mind that it will be used in the following ways:

• all representations sharing the same set_id value will be moved to the same Adaptation Set; on the other hand, representations having different set_id values will end up in different Adaptation Sets.

• if for any given period of the manifest, N is the highest Adaptation Set Id value in a given period, Representations with set_id equal to M will be moved to an Adaptation Set with Id = N+M

Notice that the above means that at least one new Adaptation Set will always be added to the manifest. It also means that you cannot move a Representation to an existing Adaption Set.

Note

in order to avoid unnecessary manifest modifications, the plugin will always verify that the specified configuration actually describes a valid Adaptation Set splitting (e.g. if your selection does not match any representation or if you haven't specified at least two distinct values for set_id, no modifications will be applied).

Examples

The above is better explained with a couple of examples. Let's assume we have the following manifest, where representations with both avc1 and hvc1 codecs are present in the same video adaptation set.

<MPD
other_attributes="...">
  <Period
    other_attributes="...">
    <AdaptationSet
      id="3"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="349952"
      maxBandwidth="12000000"
      other_attributes="...">
      <Representation
        id="video=349952"
        bandwidth="349952"
        width="640"
        height="360"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=400000"
        bandwidth="400000"
        width="640"
        height="360"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1299968"
        bandwidth="1299968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1499968"
        bandwidth="1499968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2499968"
        bandwidth="2499968"
        width="1280"
        height="720"
        frameRate="25"
        codecs="hvc1.2.20000000.L120.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2800000"
        bandwidth="2800000"
        width="1280"
        height="720"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=4499968"
        bandwidth="4499968"
        width="1920"
        height="1080"
        frameRate="50"
        codecs="hvc1.2.20000000.L123.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=5000000"
        bandwidth="5000000"
        width="1920"
        height="1080"
        frameRate="25"
        codecs="avc1.4D4032"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=6499968"
        bandwidth="6499968"
        width="2560"
        height="1440"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=12000000"
        bandwidth="12000000"
        width="3840"
        height="2160"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>

Simple splitting with two subsets

If the goal is to just separate the representations with avc1 codec from the ones with hvc1 codec, then the following configuration can be used:

mpd:
  - manifest_edit.plugins.mpd.adaptation_sets_splitting:
      periods:
        - '*' : '.*'
          adaptationSets:
            - contentType : 'video'
              representations:
                - codecs: 'avc1.*'
                  plugin_config:
                    set_id: '1'
                - codecs: 'hvc1.*'
                  plugin_config:
                    set_id: '2'

This configuration creates two different Representations subset, based on the value of the codecs attribute (notice the use of a regular expression to match any variant of hvc1 codecs). By assigning a different set_id value (1 and 2) to each subset, this configuration generates two separate destination adaptation sets. The resulting manifest:

<MPD
other_attributes="...">
  <Period
    other_attributes="...">
    <AdaptationSet
      id="4"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="400000"
      maxBandwidth="5000000"
      maxWidth="1920"
      maxHeight="1080"
      other_attributes="...">
      <Representation
        id="video=400000"
        bandwidth="400000"
        width="640"
        height="360"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1499968"
        bandwidth="1499968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2800000"
        bandwidth="2800000"
        width="1280"
        height="720"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=5000000"
        bandwidth="5000000"
        width="1920"
        height="1080"
        frameRate="25"
        codecs="avc1.4D4032"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
    <AdaptationSet
      id="5"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="349952"
      maxBandwidth="12000000"
      maxWidth="3840"
      maxHeight="2160"
      other_attributes="...">
      <Representation
        id="video=349952"
        bandwidth="349952"
        width="640"
        height="360"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1299968"
        bandwidth="1299968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2499968"
        bandwidth="2499968"
        width="1280"
        height="720"
        frameRate="25"
        codecs="hvc1.2.20000000.L120.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=4499968"
        bandwidth="4499968"
        width="1920"
        height="1080"
        frameRate="50"
        codecs="hvc1.2.20000000.L123.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=6499968"
        bandwidth="6499968"
        width="2560"
        height="1440"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=12000000"
        bandwidth="12000000"
        width="3840"
        height="2160"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>

The resulting manifest has now two separate video Adaptation Sets, one only with Representations having avc1 codec, another with only Representations having hvc1 codec.

Since 3 was the highest Adaptation Set id value in the original manifest and considering that the values for set_id was 1 for avc1 representations and 2 for hvc1 ones, the resulting Adaptation Set ids will respectively be 3+1=4 and 3+2=5.

Splitting with multiple subsets

In case a finer selection is needed, multiple selections can be performed and selected ones can be assigned to the same destination Adaptation Set. In the following example, all the avc1 are selected, as in the previous examples, while the hvc1 Representations are grouped by codec profile and each group is split to a different Adaptation Set.

mpd:
  - manifest_edit.plugins.mpd.adaptation_sets_splitting:
      periods:
        - '*' : '.*'
          adaptationSets:
            - contentType : 'video'
              representations:
                - codecs: 'avc1.*'
                  plugin_config:
                    set_id: '1'
                - codecs: 'hvc1.2.20000000.L93.*'
                  plugin_config:
                    set_id: '2'
                - codecs: 'hvc1.2.20000000.L120.*'
                  plugin_config:
                    set_id: '2'
                - codecs: 'hvc1.2.20000000.L123.*'
                  plugin_config:
                    set_id: '3'
                - codecs: 'hvc1.2.20000000.L153.*'
                  plugin_config:
                    set_id: '3'

The purpose is to group the two lowest hvc1 profiles separately from the highest two. See the resulting manifest:

<MPD
other_attributes="...">
  <Period
    other_attributes="...">
    <AdaptationSet
      id="4"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="400000"
      maxBandwidth="5000000"
      maxWidth="1920"
      maxHeight="1080"
      other_attributes="...">
      <Representation
        id="video=400000"
        bandwidth="400000"
        width="640"
        height="360"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1499968"
        bandwidth="1499968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2800000"
        bandwidth="2800000"
        width="1280"
        height="720"
        frameRate="25"
        codecs="avc1.4D401F"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=5000000"
        bandwidth="5000000"
        width="1920"
        height="1080"
        frameRate="25"
        codecs="avc1.4D4032"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
    <AdaptationSet
      id="5"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="349952"
      maxBandwidth="2499968"
      maxWidth="1280"
      maxHeight="720"
      other_attributes="...">
      <Representation
        id="video=349952"
        bandwidth="349952"
        width="640"
        height="360"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=1299968"
        bandwidth="1299968"
        width="1024"
        height="576"
        frameRate="25"
        codecs="hvc1.2.20000000.L93.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=2499968"
        bandwidth="2499968"
        width="1280"
        height="720"
        frameRate="25"
        codecs="hvc1.2.20000000.L120.00.B0"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
    <AdaptationSet
      id="6"
      group="2"
      contentType="video"
      par="16:9"
      minBandwidth="4499968"
      maxBandwidth="12000000"
      maxWidth="3840"
      maxHeight="2160"
      other_attributes="...">
      <Representation
        id="video=4499968"
        bandwidth="4499968"
        width="1920"
        height="1080"
        frameRate="50"
        codecs="hvc1.2.20000000.L123.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=6499968"
        bandwidth="6499968"
        width="2560"
        height="1440"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
      <Representation
        id="video=12000000"
        bandwidth="12000000"
        width="3840"
        height="2160"
        frameRate="50"
        codecs="hvc1.2.20000000.L153.00.B0"
        scanType="progressive">
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>

Since 3 was the highest Adaptation Set id value in the original manifest and considering that the values for set_id was 1 for avc1, 2 and 3 for the two hvc1 groups, the resulting Adaptation Set id for avc1 is 3+1=4, for the lowest profiles hvc1 is 3+2=5, for the highest two hvc1 profiles is 3+3=6.