Adaptation Sets Switching

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

This plugin implements the Adaptation Sets Switching feature as described in DASH-IF Interoperability, 3.8.

This feature can signal the possibility for a player to switch from an Adaptation Set to another if the former contains a Supplemental Descriptor with schemeIdUri set to urn:mpeg:dash:adaptation-set-switching:2016 and value equal to the id of the Adaptation Set it can switch to.

An example taken directly from the standard can better clarify this scenario:

As an example, a content author may signal that seamless switching across an
H.264/AVC Adaptation Set with AdaptationSet@id=”264” and an HEVC Adaptation
Set with AdaptationSet@id=”265” is possible by adding a Supplemental
Descriptor to the H.264/AVC Adaptation Set with @schemeIdUri set to
urn:mpeg:dash:adaptation-set-switching:2016 and the @value=”265” and by
adding a Supplemental Descriptor to the HEVC Adaptation Set with @schemeIdUri
set to urn:mpeg:dash:adaptation-set7 switching:2016 and the @value=”264”.

It has to be noticed that the Supplemental Descriptor may be added either by using a SupplementalProperty or an EssentialProperty element in the manifest, depending on the needs.

For a use case where one or more Adaptation Switching Sets needs to be defined, the questions to answer are:

  1. Which Adaptation Sets should belong to the same Switching Set?
  2. How can I specify whether a Supplemental or Essential property should be used?

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 that all Adaptation Sets with contentType="video" belong to the same Switching Set
  2. I want to signal this using the SupplementalProperty element.

We can generalize this example by considering that there will always be a "selection" to make (pick Adaptation Sets) and an "action" to specify (how to specify the Switching Set signaling?).

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

Adaptation Set Switching configuration

Adaptation Set Switching configuration represents the "how" part in the introduction above. It allows you to associate the selected Adaptation Set to a specific Switching Set, as well as specifying whether to use Supplemental or Essential properties in the manifest.

This is achieved with the following syntax:

switching_set: <id>
destination: 'essential_property_add' | 'supplemental_property_add'

where <id> is a unique identifier used to tie different Adaptation Sets to the same Switching Set. This id will not be mentioned anywhere in the manifest: its only meaning is that all selected adaptation sets sharing the same switching_set id value belong to the same Switching Set.

destination values can be either 'essential_property_add' or 'supplemental_property_add': you pick one based on your choice of EssentialProperty or SupplementalProperty to signal the switching capability.

For the example cited in the introduction, the right configuration to add all "video" adaptation set to the same Switching Set, using SupplementalProperty, would be:

mpd:
- manifest_edit.plugins.mpd.adaptation_sets_switching:
    periods:
      - '*' : '.*'
        adaptationSets:
          - contentType: 'video'
            switching_set: '1'
            destination: 'supplemental_property_add'

- manifest_edit.plugins.mpd.supplemental_property_add:

Note

Notice that the configuration includes a line enabling the "supplemental_property_add" plugin. This is required, because it is the plugin that will perform the actual insertion of "SupplementalProperty" elements in the manifest. In case a destination: 'essential_property_add' configuration is selected, the corresponding plugin needs to be activated with the line - manifest_edit.plugins.mpd.essential_property_add:.

It is possible to define multiple switching sets and configuration by specifying different values for the "switching_set" field. The following configuration defines two different Switching Sets, one for the video and one for the audio adaptation sets, one using SupplementalProperty, the other using EssentialProperty:

mpd:
- manifest_edit.plugins.mpd.adaptation_sets_switching:
    periods:
      - '*' : '.*'
        adaptationSets:
          - contentType: 'video'
            switching_set: '1'
            destination: 'essential_property_add'
          - contentType: 'audio'
            switching_set: '2'
            destination: 'supplemental_property_add'

- manifest_edit.plugins.mpd.supplemental_property_add:
- manifest_edit.plugins.mpd.essential_property_add:

The last example shows you how to add to the same switching set two adaptation sets selected with different criteria:

mpd:
- manifest_edit.plugins.mpd.adaptation_sets_switching:
    periods:
      - '*' : '.*'
        adaptationSets:
          - codecs: 'avc1.*'
            switching_set: '1'
            destination: 'supplemental_property_add'
          - codecs: 'hvc1.*'
            switching_set: '1'
            destination: 'supplemental_property_add'

- manifest_edit.plugins.mpd.supplemental_property_add:

The adaptation_sets_switching plugin will perform some basic checks before creating a Switching Set. In particular, it will check that:

  • a Switching Set contains at least two Adaptation Sets
  • within a Switching Set, all Adaptation Sets have the same "contentType" value
  • within a Switching Set, all Adaptation Sets have the same "lang" value
  • within a "video" Switching Set, all Adaptation Sets have the same "par" and "sar" values.

In case one or more of these check fails, the manifest will not be edited and a warning message will be logged.

Warning

Based on DASH-IF Interoperability, 3.8, Adaptation Sets can belong to the same Switching Set only if they respect certain criteria. This plugin does not check that these criteria apply and leaves to the user the responsibility of defining Switching Sets conforming to the standard.

You can find additional examples of configuration in the Included Use Cases chapter.