Included Use Cases

Introduction

The previous chapters have shown how Manifest Edit comes with a preinstalled Plugins Library and how these can be combined, by means of the Pipeline Configuration File, into pipelines.

We encourage users to think creatively about the possible different ways of combining plugins to realize specific functionalities they may need. However, we think it's very useful to provide a list of specific use cases that Unified Streaming has encountered and how they can be solved by Manifest Edit.

MPD Use Cases

Sidecar subtitles removal

Depending on the subtitle format, the DASH manifest can generate both fragmented and sidecar subtitle tracks.

Possible related issue:

  • players or devices may not be able, for any reason, to handle one or the other format
  • players or devices will treat these as two separate subtitle tracks (instead than two different formats for the same subtitles).

Consequences:

  • subtitle track won't playback
  • duplicated subtitles are shown on screen

Solution: use the element_remove plugin to keep one or the other format, depending on player support.

The customer's toolchain may involve a third-party ad-insertion tool that does not support the presence of "sidecar" subtitles along with fragmented ones. The Origin's default behavior is instead to add by default such sidecar subtitles, which are carried in an adaptation set with contentType = 'text' and mimeType = 'text/vtt'. For such scenario, it is possible to remove with manifest-edit the unsupported adaptation set by means of the following configuration:

mpd:
- manifest_edit.plugins.mpd.element_remove:
    periods:
      - '*' : '.*'
        adaptationSets:
          - contentType : 'text'
            mimeType: 'text/vtt'
            plugin_config:
              remove: 'this'

You can find a similar configuration in the provided adaptation_sets_removal.yaml and representations_removal.yaml files available in the example folder.

Accessibility setting for subtitles

Possible related issue:

  • best practices and regulations may impose the presence of "hard of hearing" subtitle tracks
  • vod content or encoder settings may lack to signal the tracks appropriately, which in turn affects DASH signaling

Consequences:

  • subtitle track will not be rendered
  • "hard of hearing" subtitle may not be present in the streaming

Solution:: explicitly set a "text" track of your choice with the correct "hard of hearing" signaling, using the descriptor_add plugin for DASH and the default_language plugin for HLS.

For DASH, this means appropriately settings the Accessibility and Role elements in those Adaptation Sets having a contentType set to text, which is achievable by means of a combination of the descriptor_add and descriptor_remove plugins. The manifest in fact could already include Accessibility and Role elements, probably with different schemeIdUri and value content.

It is best to first remove the existing Accessibility and Role and then add the ones that are surely compatible with the device.

The resulting configuration is:

mpd:
  - manifest_edit.plugins.mpd.descriptor_remove:
      periods:
        - '*' : '.*'
          adaptationSets:
            - contentType :  "text"
              plugin_config:
                name: "Accessibility"
            - contentType :  "text"
              plugin_config:
                name: "Role"

  - manifest_edit.plugins.mpd.descriptor_add:
      periods:
        - '*' : '.*'
          adaptationSets:
            - contentType :  "text"
              plugin_config:
                name: "Accessibility"
                schemeIdUri: "urn:tva:metadata:cs:AudioPurposeCS:2007"
                value: "2"
            - contentType :  "text"
              plugin_config:
                name: "Role"
                schemeIdUri: "urn:mpeg:dash:role:2011"
                value: "main"

For HLS, this means setting the CHARACTERISTICS attribute in the EXT-X-MEDIA tag of a the desired track in a main HLS playlist. This is achievable using the default_language plugin, using a configuration similar to the following, which sets the french track as "hard of hearing":

m3u8_main:
- manifest_edit.plugins.m3u8_main.default_language:
   - type: 'SUBTITLES'
     language: 'fr'
     characteristics: "public.accessibility.describes-spoken-dialog,public.accessibility.describes-music-and-sound"
     # autoselect will be added implicitly as required by HLS authoring guidelines

Content tailoring to regions or devices

By default a manifest returns all streams available in the server manifest.

Possible related issue:

  • some audio, video or subtitle tracks are only necessary in certain geographical regions
  • regulations or rights management may require to limit some content to only specific reasons or devices
  • some devices are not compatible with one or more codecs used in the stream
  • it is desirable to stream HD-only or SD-only to certain devices or regions

Consequences:

  • rights infringement
  • poor user experience
  • device or player crashes

Solution: create variants of a given manifest, tailored to specific regions or devices, by using element_remove plugin

Depending on your requirement, you may want to remove entire Adaptation Sets or specific Representations.

This configuration removes all HD video Representations (e.g. width>=720) from a DASH manifest, leaving only SD tracks (also adjusting the 'maxWidth', 'minWidth', 'maxBitrate', 'minBitrate' attributes of the corresponding Adaptation Set). Such a configuration may be suitable to provide SD-only content to specific customer tiers or to simplify the manifest for non-HD-capable devices or players:

mpd:
- manifest_edit.plugins.mpd.element_remove:
    periods:
      - '*' : '.*'
        adaptationSets:
          - contentType: "video"
            representations:
              # matches width >= 720
              - width: '^([8-9]\d+|[7][2-9]\d|\d{4,})$'
                plugin_config:
                  remove: 'this'

When providing multiple video or audio encoding, it may be useful to remove one or more to force specific devices and players to use only the other codecs.

I.e. this example removes all audio tracks with a 'dtse' codec:

mpd:
- manifest_edit.plugins.mpd.element_remove:
    periods:
      - '*' : '.*'
        adaptationSets:
          - codecs : 'dtse'
            plugin_config:
              remove: 'this'

I.e. this example removes all video tracks with an 'hevc' codec:

mpd:
- manifest_edit.plugins.mpd.element_remove:
    periods:
      - '*' : '.*'
        adaptationSets:
          - codecs : '^hevc.*'
            plugin_config:
              remove: 'this'

Refer to the element_remove plugin doc page for a complete overview on the selection options.

Adaptation Sets Switching

Sometimes, similar tracks are split in different Adaptation Sets (i.e. when using different DRM keys).

Possible related issue:

  • some players and devices may not be able to switch across tracks belonging to different Adaptation Sets
  • some audio, video or subtitle tracks are not played back

Consequences:

  • poor user experience
  • broken playback
  • device or player crashes

Solution: enable adaptation set switching using adaptation_sets_switching plugin (requires a supported player).

In this use case, the customer wants to offer the same content with different encryption keys for different resolutions (HD and SD). The DASH implementation guidelines (Chapter 7) clearly states that in this case, two different adaptation sets must be created. This is the default behavior of Unified Origin.

For such scenarios, the separate adaptation sets can be added to a same Switching Set to enable seamless switching functionality in players supporting it.

The following example adds all the "video" adaptation sets of a manifest to the same Switching Set:

mpd:
- manifest_edit.plugins.mpd.adaptation_sets_switching:
    periods:
      - '*' : '.*'
        adaptationSets:
          - contentType: 'video'
            plugin_config:
              switching_set: '1'
              destination: 'supplemental_property'

- manifest_edit.plugins.mpd.descriptor_add:

You can find a similar configuration in the provided adaptation_sets_switching.yaml file available in the example folder.

Adding a "value" attribute to EventStreams

This is an example of specific device bugs that can be worked around using Manifest Edit

Possible related issue:

  • a specific set-top-box crashes if a "value" field is not present in the EventStream element

Consequences:

  • broken playback for a specific audience
  • need to wait for a firmware update from the set-top-box manufacturer

Solution: enable a workaround using eventstream_value_add plugin.

Despite recognizing that "value" is an optional attribute and that this behaviour is clearly faulty on the device side, this plugin seems the easiest way forward to provide compatibility in a short time.

The specific content of the "value" element is not important, however this plugin allows to configure it. We will just use the string "1" in this example.

This is the resulting configuration:

mpd:
- manifest_edit.plugins.mpd.eventstream_value_add:
    value: "1"

HLS Use Cases

Default Subtitle/Audio Language

When multiple audio/subtitle languages are present, different regions should playback by default different languages.

Possible related issue:

  • playback starts with a foreign language
  • the wrong subtitle track is enabled by default
  • at every playback, users need to manually select audio/subtitles

Consequences:

  • poor user experience

Solution: use the default_language plugin to choose default languages.

The customer needs to serve several regions with different languages. They need players to automatically start playback of the audio track with the region's main language. Unfortunately the DEFAULT audio track is determined at packaging time and that implies having different manifest per region, which is undesirable.

With Manifest Edit, it is possible to change the manifest on the fly and have audio or subtitle tracks default to a specific language.

The solution is based on having one pipeline configuration file per language and the use query parameters to select the pipeline applying the desired one.

For audio tracks (but the same applies to the subtitle case, just use type: 'SUBTITLES'), if we suppose to support two languages, i.e. Swedish and Danish, the solution would involve creating two pipeline configuration files such as the following:

default_swedish.yaml:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'AUDIO'
      language: 'sv'
      default: 'YES'

default_danish.yaml:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'AUDIO'
      language: 'da'
      default: 'YES'

If your configuration reflects the one suggested in the installation manual ( see Manifest Edit-related configuration), then you would use either one of the following URL to select the desired language:

http://my-origin.com/my-video.ism/.mpd?python_pipeline_config=default_swedish
http://my-origin.com/my-video.ism/.mpd?python_pipeline_config=default_danish