Descriptor Add

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

The Descriptor Add plugin allows you to add a Descriptor to any Adaptation Set or Representation of a Dash manifest (see 5.8.2 of ISO23009-1 standard).

Adding a descriptor to the MPD manifest root or to a Period is at the moment not supported.

For a use case where one or more Descriptors need to be added, the questions to answer are:

1. What elements do I need to add Descriptor to?

2. How exactly can I specify the details of the Descriptor I need to add?

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 add a Descriptor to all adaptation sets

2. I want to add an "EssentialProperty"

3. I want it to have attributes schemeIdUri="urn:dvb:dash:lowlatency:critical :2019" value="true"

We can generalize this example by considering that there will always be a "selection" to make (what to edit?) and an "action" to specify (how to specify the Descriptor values?).

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

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

Descriptor configuration

Descriptor configuration represents the "how" part in the introduction above. It allows you to specify what kind of Descriptor you want to add (i.e. EssentialProperty) and the values for the mandatory descriptor field schemeIdUri, as well as for the optional value and id.

This is achieved with the appropriate keys:

name : <the kind of descriptor>
schemeIdUri: <a schemeIdUri string>
value: <content of the optional value field>
id: <content of the optional id field>

A valid configuration includes at minimum the two fields name and schemeIdUri. The value and id fields are optional and can be safely omitted, in which case they will not appear at all in the manifest. The same can be obtained by providing an empty string as a value for these optional fields.

For the example cited in the introduction, the right configuration to add an "EssentialProperty" Descriptor to all adaptation sets would be:

mpd:
- manifest_edit.plugins.mpd.descriptor_add:
    periods:
      - id : '.*'
        adaptationSets:
          - '*': '.*'
            plugin_config:
              name: "EssentialProperty"
              schemeIdUri : "urn:dvb:dash:lowlatency:critical:2019"
              value: "true"

The supported values for the name field (i.e. the supported descriptor types) are:

EssentialProperty
SupplementalProperty
Accessibility
Role
AudioChannelConfiguration
UTCTiming

Providing any other value will generate a configuration error.

It is important to remember that some Descriptors can only appear in specific elements. For example, SupplementalProperty can be present in an Adaptation Set or in a Representation, but Accessibility and Role can only ever appear in Adaptation Sets. For this reason, based on the specific Descriptor type, the plugin, at runtime, will perform additional checks to make sure a supported, standard-compliant configuration has been provided. In case the configuration is invalid, a log will be emitted and the manifest will not be edited.

Regarding the schemeIdUri, value and id fields, it is the user's responsibility to provide sensitive and standard-compliant values. Extra care must be applied to their configuration, because the plugin will not perform any validity check on any of those. This means that a configuration error in one of those fields could produce a broken manifest.

An element can have many descriptors of the same type. In case the specific use case requires to add more than one Descriptor to the same adaptation set, this can be accomplished in the configuration by adding another item to the adaptationSets configuration, e.g.:

mpd:
- manifest_edit.plugins.mpd.descriptor_add:
    periods:
      - id : '.*'
        adaptationSets:
          - '*': '*'
            plugin_config:
              name: "EssentialProperty"
              schemeIdUri : "urn:dvb:dash:lowlatency:critical:2019"
              value: "true"
          - '*': '*'
            plugin_config:
              name: "EssentialProperty"
              schemeIdUri : "http://dashif.org/guidelines/trickmode"
              value: "1"

There is a chance that the manifest being edited already contains a descriptor in the same element where the user wants to add another.

The plugin will handle this case by comparing the descriptor to be added to the existing one, applying the following policy:

• if a descriptor with the same name and schemeIdUri already exist, then no modifications will be applied to the manifest and a log will be emitted to warn that no actions have been taken for this specific manifest.

• in all other cases, a new descriptor will be added.

Note

You can override the default behavior by adding force: True to the plugin_config section. In that case, no checks will be performed at runtime and you will be able to add a descriptor even if one with identical name and schemeIdUri exists.

If your intent is to modify an existing descriptor (i.e. adding a value attribute to a descriptor that doesn't have one), you can achieve your goal by first removing the descriptor, then adding another with the same name, schemeIdUri and the additional value field.

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

Warning

Remember that Descriptors cannot be added anywhere in a manifest. The following table summarizes where each descriptor can be present, based on supported features of the DASH specifications

Where Descriptors can be added

	MPD	Period	AdaptationSet	Representation
EssentialProperty	X	X	OK	OK
SupplementalProperty	X	X	OK	OK
Accessibility	X	X	OK	X
Role	X	X	OK	X
AudioChannelConfiguration	X	X	OK	OK
UTCTiming	OK	X	X	X