Manifest Order

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

Manifest Order allows you to rearrange the order of Adaptation Sets and Representations present in a manifest. Ordering can be applied to all or part of your manifest and can be either a complete sort or o selective move of individual elements in a list.

For a use case where one or more of these elements needs to be reordered, the questions to answer are:

  1. What elements do I need to order?

  2. How exactly do I want to reorder them?

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 reorder Representations in the "video" Adaptation Set

  2. I want to sort them by "bandwidth" in decreasing order

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

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

Manifest Order configuration

Manifest Order configuration represents the "how" part in the introduction above. It allows you to specify what kind of ordering will be applied to the list that have been selected.

Two options are available: full sorting and manual order.

Full sorting

You can sort a list based on the values of one of their properties (i.e. sort representation by ascending order of bandwidth). You can do that using the following syntax:

orderBy: <sorting key>
orderCriteria: 'desc' | 'asc'

where <key> represents a manifest property you want to use as a sorting key and desc or asc are used to specify ascending or descending order.

Note

Descending and Ascending order will be applied in the alphabetical or numeric sorting, depending on the type of the chosen sorting key.

The following example would sort all representation sets in a manifest by ascending order of bandwidth:

mpd:
- manifest_edit.plugins.mpd.manifest_order:
    periods:
      - '*': '*'
        adaptationSets:
          - '*': '*'
            representations:
              plugin_config:
                orderBy: 'bandwidth'
                orderCriteria: 'asc'

In case some of the elements in the list to be sorted do not have a value for the chosen "orderBy" field (it could be optional), then those particular element will be considered having the minimum possible value for that field type (i.e. '0' for numeric field, or the empty string '' for string fields).

Manual Ordering

You can move those elements matching some criteria to a specific position in the list (i.e. move to the top a subtitle track with "eng" language). This is done with the following syntax:

manualOrder:
  - <key>: <expression>
    <key>: <expression>
    [...]
  - <key>: <expression>
    <key>: <expression>
    [...]
  - <key>: <expression>
    <key>: <expression>
    [...]
  [...]

The - <key>: <expression> [...] list is positional and expresses the order in which elements will appear in the reordered list. <key> is matched to a manifest element property and <expression> is a python regular expression.

The following example allows you to move an adaptation set with a given id to the first position in the manifest

mpd:
- manifest_edit.plugins.mpd.manifest_order:
    periods:
      - '*': '*'
        adaptationSets:
          plugin_config:
            manualOrder:
              - id: '5'

With the following modification, you can specify another id for position number 2:

mpd:
- manifest_edit.plugins.mpd.manifest_order:
    periods:
      - '*': '*'
        adaptationSets:
          plugin_config:
            manualOrder:
              - id: '5'
              - id: '3'

Notice that manual ordering effectively is equivalent to removing an element from the list and then performing an "insert" operation at the desired location. This operations will be done in the sequence specified in the configuration file. Elements not to be reordered may change position in the list due to these operations.

To clarify the concept, suppose the above configuration file is applied to a manifest whose subtitles adaptation sets appear in the following order:

[ '1', '2', '3', '4', '5' ]

Manifest Edit would then apply two operations in sequence:

  1. [ '1', '2', '3', '4', '5' ] ==> [ '5', '1', '2', '3', '4' ]
 ^                     |
 |_____________________|

  2. [ '5', '1', '2', '3', '4' ] ==> [ '5', '3', '1', '2', '4' ]
      ^           |
      |___________|

If no element matches the provided key value, then the move operation for that particular element is simply skipped.

You can select elements that match more than one selection criteria by using more than one <key>: <expression> couple under the same list entry. E.g.: the following example will put in first position an adaptation set that has both an italian language and an audio content type; second position will be assigned to that having both an english language and an "audio" content type:

mpd:
- manifest_edit.plugins.mpd.manifest_order:
    periods:
      - '*' : '.*'
        adaptationSets:
          plugin_config:
            manualOrder:
              - lang : 'it$'
                contentType : "audio"
              - lang : 'en$'
                contentType : "audio"

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