Element Selection

Some plugins (i.e. Manifest Order and Supplemental Property) share a common configuration syntax to specify what element of the manifest the plugin will operate on.

For such plugins, the configuration section can be thought as composed by two parts, one to specify "what" needs to be edited and another to specify "how" to edit.

This chapter is dedicate to the "what" part. Please refer to the individual plugin documentation for information on the specific "how" configuration.

In order to understand how Element Selection works, the basic hierarchy of a Dash manifest needs to be taken into consideration. An mpd manifest describes in fact a series of Representations; Representations are organized in Adaptation Sets; Adaptation Sets are organized in Periods (refer to 5.3.2, 5.3.3 and 5.3.5 of ISO23009-1 standard) and periods in turn belong to the MPD manifest root. The following figure illustrate such a hierarchy

../../../../../../_images/mpd_hierarchy.jpg

It may be useful to visualize what could be a possible document structure the follows this hierarchy. The following is just an example but is generic enough to serve our purpose (please notice that all elements not essential for this explanation have been removed from the manifest with an ellipsis other_attributes="..."):

<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Unified Streaming Platform (version=1.10.25-21981) -->
<MPD
  other_attributes="...">
  <Period
    id="1"
    duration="PT12M13.936333S">
    <AdaptationSet
      contentType="audio"
      lang="eng"
      other_attributes="...">
      <Representation
        id="audio_eng=64008"
        bandwidth="64008">
      </Representation>
      <Representation
        id="audio_eng=128002"
        bandwidth="128002">
      </Representation>
    </AdaptationSet>
    <AdaptationSet
      contentType="text"
      other_attributes="...">
      <Representation
        id="textstream_deu=1000"
        bandwidth="1000">
      </Representation>
    </AdaptationSet>
    <AdaptationSet
      contentType="video"
      other_attributes="...">
      <Representation
        bandwidth="902000"
        other_attributes="...">
      </Representation>
      <Representation
        bandwidth="1161000"
        other_attributes="...">
      </Representation>
      <Representation
        bandwidth="1583000"
        other_attributes="...">
      </Representation>
    </AdaptationSet>
  </Period>
</MPD>

This particular example shows a hierarchy where a single Period includes three different Adaptation Sets; each of those contains from one to three Representations.

Use cases generally may require to edit just one or few of these elements (either one specific adaptation set belonging to a given period; or a representation list from a given adaptation set).

This section of the Pipeline Configuration file provides you a syntax to express such selection logic.

Selection syntax 

Let's start with the easiest case of all: selection of the manifest root MPD. This is simply achievable with an empty configuration:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    plugin_config: {"how" config}

Since every manifest has one and only one MPD root, no specific selection syntax is needed to select it.

For all other cases, the Element Selection configuration must follow an ordered hierarchy of periods, adaptationSets and representations keywords. At each level of this hierarchy, selection can be performed by specifying couples of <key>: <value> pairs.

This is the schema to follow in a configuration file to select one representation list to edit:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - <key>: <value>
        <key>: <value>
        [...]
        adaptationSets:
          - <key>: <value>
            <key>: <value>
            [...]
            representations:
              plugin_config: {"how" config}

The schema is similar but shorter in case you need to select an adaptation set list to edit:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - <key>: <value>
        <key>: <value>
        [...]
        adaptationSets:
          plugin_config: {"how" config}

with <value> = <regular expression> | <empty string>.

<key>: <value> pairs are used to specify what list in the manifest is to be edited. With reference to the example manifest above, the following configuration will select the size-two representation list from the "audio" adaptation set only, from the period with id==1:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - id: '1' #Selects the period with id == 1
        adaptationSets:
          - contentType: 'audio' #Selects adaptationSets matching the "audio" regular expression
            representations:
              plugin_config: {"how" config}

In the above example, if more than one adaptation set with contentType matching the "audio" regular expression is present in the manifest, they all will be selected and independently edited.

In case you want to select multiple lists to edit, you can do that by specifying a list of selection keys. I.e. if you wanted to select "audio" and "video" adaptation sets from the example manifest, you could use the following configuration:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - id: '1'
        adaptationSets:
          - contentType: 'audio'
            representations:
              plugin_config: {"how" config}
          - contentType: 'video'
            representations:
              plugin_config: {"how" config}

Note

Repeating two identical plugin_config: {"how" config} sections is also the recommended way to implement an OR condition on the selection criteria. In that case in fact, the above configuration file will effectively apply the "how" config to adaptation sets having contentType == 'audio' OR 'video'.

If you need that your list to be edited matches more than one <key>: <value> pair (that is, multiple selection criteria in AND combination), you can do that by adding them to the same selection list entry, as in the following example:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - id: '1' #Selects the period with id == 1
        adaptationSets:
          - contentType: 'audio' #Selects adaptationSets with contentType field matching the "audio" regular expression
            lang: 'eng'          # AND lang == "eng"
            representations:
              plugin_config: {"how" config}

which will select all the representation lists from audio adaptation sets in english language.

Wildcards can be used in both <key> and <value> fields to select "any" level of the manifest hierarchy. The possible uses are:

<key> : '.*' will select all elements having the <key> property, irrespective of its value. Will not select elements that do not have the <key> property
<key> : '' will select all elements NOT having the <key> property, effectively implementing a "negative selection".
'*' : '.*' will select all elements

The following example better illustrates wildcard usage:

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - id: '.*'

will select all those periods having an id field. All periods not having an id field will not be selected.

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - id: ''

will select all those periods NOT having an id field. All periods having an id field will not be selected.

mpd:
- manifest_edit.plugins.mpd.<plugin name>:
    periods:
      - '*': '.*'

will just select each and every periods.

Limitations 

At the current stage of implementations, some limitations apply on the properties on which a particular element selection can be performed. In particular, only attributes can be used to select, and not elements.

In addition, periods are only selectable by "id".

Element Selection

Selection syntax

Limitations

Selection syntax 

Limitations 