Segment Url Modify
You can activate this plugin with the string
manifest_edit.plugins.mpd.segment_url_modify.
DASH manifests can provide Segment URL information to clients in several different ways. Relevant information is available at ISO23009-1 standard, section 5.3.9 covering the usage of BaseURL, SegmentBase, SegmentTemplate and/or SegmentList elements.
The Segment Url Modify plugin allows you to edit the BaseURL and SegmentTemplate DASH manifest elements in order to customize segment URLs based on your needs.
Possible use cases involve serving segments from different origin servers or customizing dynamic segment generation by using specific ism server manifests for specific segments.
BaseURL and SegmentTemplate can appear in several places in a DASH manifest, including the manifest root, any Period or Adaptation Set or Representation. Thus, for a use case where one or more BaseURL or SegmentTemplate elements need to be modified, the questions to answer are:
Where exactly do I need to modify an element
What element do I need to modify?
How exactly can I specify the details of how I want to modify a BaseURL or a SegmentTemplate?
The answer to this questions depends on your use case. As an example, we can imagine that the answers could be something like this:
I want to modify baseURL in all Periods
I want to modify the "initialization" attribute of segmentTemplate in "video" Adaptation Sets by prepending "video.ism" to the existing value
I want to modify the "media" attribute of segmentTemplate in "video" Adaptation Sets by prepending "video.ism" to the existing value
We can generalize this example by considering that there will always be a "selection" to make (where to edit?) and an "action" to specify (what to edit, baseURL or SegmentTemplate? Edit them how exactly?)
This approach (select and edit) is shared by many other use cases. For this reason the "selection" syntax used in the Segment Url Modify plugin is common to many other plugins and is described in the following dedicated chapter.
Segment Url Modify configuration
Segment Url Modify configuration represents the "what" and "how" part in the introduction above: it allows you to specify the changes you want to apply to baseURL, SegmentTemplate or both.
This is achieved with the appropriate configuration sections:
baseURL: # optional section
match : <a regular expression, capture groups are possible>
replace: <a python-style replace string>
segmentTemplate : # optional section
<"media" | "initialization">:
match : <a regular expression, capture groups are possible>
replace: <a python-style replace string>
It is not required to include both a baseURL and a segmentTemplate section, but a valid configuration includes either one of the two.
For the example cited in the introduction, the right configuration to achieve the desired goal would be:
mpd:
- manifest_edit.plugins.mpd.segment_url_modify:
periods:
- id : '.*'
# Look in all periods
plugin_config:
# edit baseURL (if it matches)
baseURL:
match: '^.*$' # matches anything
replace: 'http://my.new.segment.origin/dash/'
- id : '.*'
adaptationSets:
- 'contentType': 'video'
# Look in video Adaptation Sets, belonging to any Period
plugin_config:
segmentTemplate:
# edit segmentTemplate's initialization attribute (if it matches)
initialization:
match: '^(.*)$' # matches and captures any value
replace: 'video.ism/\\g<1>' # prefixing the existing value
# edit segmentTemplate's media attribute (if it matches)
media:
match: '^(.*)$' # matches and captures any value
replace: 'video.ism/\\g<1>' # prefixing the existing value
The match string should be a regular expression parseable by python. Similarly,
the syntax for the replace string follows the python syntax for repl strings
as used, i.e. in the re.sub method. Notice the escaped \\g<i> syntax
to refer to the i-th capture group.
In addition to editing existing values, this syntax also allows you to add
a value if not present (i.e. match the ^$ empty string and replace with
your new value) or remove entirely a value (i.e. match all ^.*$ and replace
with an empty string).
This syntax allows you to express configurations that are impossible to realize based on the DASH standard (i.e. you could erroneously try to add a SegmentTemplate to the manifest root). Such configurations are ignored, a warning is issued and an unmodified manifest body is returned.
Values for the replace field can be user-defined static strings or they can use a template syntax and be dynamic, e.g. evaluated at runtime to use values from other fields in the manifest.
Replacing using dynamic strings - template syntax
It is often desirable that segment URLs are formed based on some specific track
properties (i.e. language, resolution, content type,...). For example, you may
wish to serve your video tracks from an URL including the video/ path and
audio tracks from audio/ URLs.
Such information is usually available in the element that baseURL or SegmentTemplate belong to. For this reason, a template syntax is available for the yaml configuration file so that those values are read by Manifest Edit at runtime and used to populate the desired fields.
This is better clarified with an example: let's expand the original example in
the introduction. In addition to using a video.ism value for video
adaptation sets, we also want to use a audio.ism for audio and a
text.ism for subs.
One can always manually configure three different match/replace values that
cover this case, but the contentType field of any Adaptation Set already
contains that information, so one could use the following:
mpd:
- manifest_edit.plugins.mpd.segment_url_modify:
periods:
- id : '.*'
# Look in all periods
plugin_config:
# edit baseURL (if it matches)
baseURL:
match: '^.*$' # matches anything
replace: 'http://my.new.segment.origin/dash/'
- id : '.*'
adaptationSets:
- '*': '.*'
# Look in all Adaptation Sets, belonging to any Period
plugin_config:
segmentTemplate:
# edit segmentTemplate's initialization attribute (if it matches)
initialization:
match: '^(.*)$' # matches and captures any value
replace: '{contentType}.ism/\\g<1>' # prefixing the existing value with a dynamic field
# edit segmentTemplate's media attribute (if it matches)
media:
match: '^(.*)$' # matches and captures any value
replace: '{contentType}.ism/\\g<1>' # prefixing the existing value with a dynamic field
The {contentType} part will be dynamically replaced with the value
as reported in the @contentType attribute of the Adaptation Set.
(see Table 5 of ISO23009-1 standard).
Notice that when you are editing an Adaptation Set, the template syntax can refer to fields of that Adaptation Set. When you are editing a Representation, the template syntax can refer to fields of that Representation and so on. This implies, i.e. that you cannot edit a segmentTemplate in a Representation, using a template syntax referring 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.
Note
Please do not confuse the template syntax mentioned in this chapter with
that used in SegmentTemplate and documented in 5.3.9.4.4 of
ISO23009-1 standard!
The template syntax for Segment Url Modify plugin uses curly braces { }
and is solved server-side by Manifest Edit, by replacing fields in curly
braces with the corresponding values.
The template syntax used in SegmentTemplate uses the $ escape character
and is supposed to be solved by DASH clients: when editing the media and
initialization attributes with Segment Url Modify plugin, you should
always be careful to not change these parts. They are generated by
you Origin server, changing them will lead to broken streams.