Label Add
You can activate this plugin with the string
manifest_edit.plugins.mpd.label_add.
The Label Add plugin allows you to add a Label or groupLabel elements to any Adaptation Set or Representation of a Dash manifest (see 5.3.10 of ISO23009-1 standard).
For a use case where one or more Label or GroupLabel elements need to be added, the questions to answer are:
What elements do I need to add Label to?
How exactly can I specify the details of the Label 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:
I want to add a Label to all adaptation sets
I want the label to have a specific text "My Label"
I want the label to have the "id" attribute equal to 0.
I want the label to have the "lang" attribute equal to "en".
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 Label text and attributes?).
This approach (select and edit) is useful for many other use cases. For this reason the "selection" syntax used in the Label Add plugin is common to many other plugins and is described in the following dedicated chapter.
Label Add configuration
Label Add configuration represents the "how" part in the introduction above. It allows you to specify a Label or GroupLabel element, along with their text and optional attributes.
This is achieved with the appropriate keys, which map one-on-one with the Label and GroupLabel definitions found in the DASH standard:
id : <an integer to be used for the id field, optional, default=0>
lang: <a string to be used for the lang field, optional, default="">
data: <the label text, optional, default="">
A valid configuration includes at minimum one of this field.
For the example cited in the introduction, the right configuration to add a "Label" element to all adaptation sets would be:
mpd:
- manifest_edit.plugins.mpd.label_add:
periods:
- id : '.*'
adaptationSets:
- '*': '.*'
plugin_config:
label:
id: 0
lang: "en"
data: "My Label"
It is important to remember that Labels and GroupLabels can only appear in Representation and Adaptation Set elements, and as such a configuration that tries to add one to the MPD root or to a Period will silently be ignored.
It is the user's responsibility to provide sensible values for the id and lang field. In particular, this plugin makes no effort in checking that the provided id values are unique or not, and it does not check that the lang field is a valid language string.
Values for the lang and data field can be user-defined static strings or they can use a templating format and be dynamic, e.g. evaluated at runtime to use values from other fields in the manifest.
An element can have many Labels and GroupLabels. In case the specific use case requires to add more than one Label / GroupLabel to the same element, i.e. an adaptation set, this can be accomplished in the configuration by adding another item to the adaptationSets configuration, e.g.:
mpd:
- manifest_edit.plugins.mpd.label_add:
periods:
- id : '.*'
adaptationSets:
- '*': '.*'
plugin_config:
label:
id: 0
lang : "en"
data: "My Label"
- '*': '.*'
plugin_config:
groupLabel:
id: 1
lang : "it"
data: "My Label"
There is a chance that the manifest being edited already contains a Label in the same element where the user wants to add another.
The plugin will handle this case by comparing the Label to be added to the existing one, applying the following policy:
if a label with the same id, lang and data 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 label 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 label even if an identical one exists.
If your intent is to modify an existing label (i.e. changing the text attribute to a descriptor that doesn't have one), you can achieve your goal by first removing it, then adding another with the desired data, id and lang fields.
Dynamic labels - template syntax
It is often desirable to have labels contain information about specific track properties (i.e. track language, resolution). When this information is available in the element the Label belongs to, it is possible to use a template syntax in the yaml configuration file (for the data and lang fields) so that those values are read by Manifest Edit at runtime and used to populate the label fields.
This is better clarified with an example: suppose a manifest has three tracks with different resolutions; your use case involves generating a label, for each track, that reports the track resolution. Considering how many different resolutions can be available for different assets and different bitrate ladders, it could be unfeasible to manually provide one label string per possible resolution. It would be much more desirable if the label could just report the values as they appear in the track width and height fields.
This is feasible by using the following Label template syntax:
mpd:
- manifest_edit.plugins.mpd.label_add:
periods:
- id : '.*'
adaptationSets:
- '*': '.*'
representations:
- '*': '.*'
plugin_config:
label:
id: 0
data: "This track has resolution {width}x{height}"
The {width} and {height} will be dynamically replaced with the values
as reported in the @width and @height attributes of any representation
(see Table 13 of ISO23009-1 standard).
In the above example, a manifest including these representations
<Representation
id="video_eng=401000"
bandwidth="401000"
width="224"
height="100"
codecs="avc1.42C00D"
scanType="progressive">
</Representation>
<Representation
id="video_eng=751000"
bandwidth="751000"
width="448"
height="200"
codecs="avc1.42C016"
scanType="progressive">
</Representation>
<Representation
id="video_eng=1001000"
bandwidth="1001000"
width="784"
height="350"
codecs="avc1.4D401F"
scanType="progressive">
</Representation>
would include, when edited by Manifest Edit, the following labels
<Representation
id="video_eng=401000"
bandwidth="401000"
width="224"
height="100"
codecs="avc1.42C00D"
scanType="progressive">
<Label
id="0">This track has resolution 224x100</Label>
</Representation>
<Representation
id="video_eng=751000"
bandwidth="751000"
width="448"
height="200"
codecs="avc1.42C016"
scanType="progressive">
<Label
id="0">This track has resolution 448x200</Label>
</Representation>
<Representation
id="video_eng=1001000"
bandwidth="1001000"
width="784"
height="350"
codecs="avc1.4D401F"
scanType="progressive">
<Label
id="0">This track has resolution 784x350</Label>
</Representation>
When you are adding a Label/GroupLabel to an Adaptation Set, the template syntax can refer to fields of that Adaptation Set. When you are adding a Label/GroupLabel to a Representation, the template syntax can refer to fields of that Representation. This implies, i.e. that you cannot add a Label to a Representation, using a field that refers to the Adaptation Set it belongs to.
Please refer to Table 5, Table 9 and Table 13 of ISO23009-1 standard for a list of attributes you can use in the template syntax.
Dynamic labels - utility functions
The template syntax comes with a few utility functions that allow to work with ISO-639-3 language codes and translate back and forth the different ways a language can be represented with that standard.
The functions are three:
ISO639Name
ISO639Alpha2
ISO639Alpha3
ISO639Name allows to transform an alpha-2 or alpha-3 code into the corresponding name (i.e. 'en' or 'eng' to 'English'). ISO639Alpha3 allows to transform an alpha-2 or language name into the corresponding alpha-3 representation (i.e. 'en' or 'English' to 'eng'). ISO639Alpha2 allows to transform an alpha-3 or language name into the corresponding alpha-2 representation (i.e. 'eng' or 'English' to 'en'). Notice that this is not always possible, since the domain of languages that can be represented using alpha-3 is way larger than that of those representable with alpha-2 codes.
The syntax allows to apply any of this function to an existing manifest attribute, with a logic similar to that explained in the previous chapter, that is referring to attributes of the Adaptation Set/Representation one is adding a Label to.
The typical use case is to generate a Label with the name of the language, corresponding to the language code reported by the "lang" attribute of an Adaptation Set/Representation.
To better clarify with an example, the following configuration file could be used to produce a label with an alpha-3 "lang" attribute and a text that reports the language Name:
mpd:
- manifest_edit.plugins.mpd.label_add:
periods:
- id: ".*"
adaptationSets:
- contentType : "audio"
plugin_config:
label:
id : 1
lang: "{ISO639Alpha3(lang)}"
data: "{ISO639Name(lang)}"
Assuming an initial manifest with the following Adaptation Set:
[ ... ]
<AdaptationSet
id="1"
group="1"
contentType="audio"
lang="en"
minBandwidth="64008"
maxBandwidth="128002"
[ ... ]
</AdaptationSet>
the previous configuration would generate the following label
[ ... ]
<AdaptationSet
id="1"
group="1"
contentType="audio"
lang="en"
minBandwidth="64008"
maxBandwidth="128002"
<Label
id="1"
lang="eng">English</Label>
[ ... ]
</AdaptationSet>
You can find this and other additional examples of configuration in the Included Use Cases chapter.