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:

  1. Where exactly do I need to modify an element

  2. What element do I need to modify?

  3. 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:

  1. I want to modify baseURL in all Periods

  2. I want to modify the "initialization" attribute of segmentTemplate in "video" Adaptation Sets by prepending "video.ism" to the existing value

  3. 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
  <"URL" | "serviceLocation">:
    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:
            URL:
              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.

Modifying the serviceLocation attribute

Starting from version 1.14.5, this plugin can also modify the "serviceLocation" attribute of any given baseURL element, with the same "match" and "replace" approach applied to existing attribute values.

The following is an example configuration that could be used to replace an existing serviceLocation attribute in baseURL elements in all periods

mpd:
- manifest_edit.plugins.mpd.segment_url_modify:
    periods:
      - id : '.*'
        # Look in all periods
        plugin_config:
          baseURL:
            # edit serviceLocation attribute of baseURL
            serviceLocation:
              match: 'alpha' # matches existing value
              replace: 'beta'

Notice that this plugin is only able to modify existing serviceLocation values (or to replace empty serviceLocation attributes with a value).

If you wish to implement redundant baseURLs for CDN failover support (as in ISO23009-1 standard, 5.6.5) or full Content Steering capabilities for DASH (as in TS103.998 standard), be aware these are out-of-scope for this specific plugin: please contact support@unified-streaming.com to know how we can help you.

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.