Default language

Table of Contents

You can activate this plugin with the string manifest_edit.plugins.m3u8_main.default_language.

This plugin allows to modify EXT-MEDIA tag's DEFAULT, AUTOSELECT and CHARACTERISTICS attributes of an m3u8 Main Manifest.

The DEFAULT attribute is used to specify a rendition that a client should play in absence of information from the user specifying a different choice. The AUTOSELECT attribute is used to specify renditions that a client may play in absence of information from the user specifying a different choice. The CHARACTERISTICS attribute is used to specify accessibility properties of an audio or subtitle track. See RFC-8216 standard §4.3.4.1 for reference.

Plugin configuration

The "default_language" plugin allows you to select one or more EXT-X-MEDIA tags in a manifest by TYPE, GROUP-ID and VALUE, and then set the DEFAULT, CHARACTERISTICS and/or AUTOSELECT attributes.

This is an example of pipeline configuration including the default_language plugin.

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'SUBTITLES'
      group-id: 'textstream'
      language: 'de'
      default: 'YES'
      autoselect: 'YES'

The above example will select all EXT-X-MEDIA tags in a Main Playlist having TYPE=SUBTITLES, GROUP-ID="textstream" and LANGUAGE="de" attributes. For these tags, it will set the DEFAULT=YES and the AUTOSELECT=YES attributes, overwriting any previous values, if present.

The following rules apply:

  • the two supported values for the type field are 'AUDIO' and 'SUBTITLES'
  • any regular expression can be used as a value for the group-id and language fields
  • the group-id field is optional and can be omitted, which is functionally equivalent to specifying a '.*' "match-all" regular expression
  • the two supported values for the default and autoselect field are 'YES' and 'NO'.

When setting the DEFAULT and AUTOSELECT properties, there are some requirements that one should take into consideration. In particular, RFC-8216 standard §4.3.4.1 and §4.3.4.1.1 require that:

If the AUTOSELECT attribute is present, its value MUST be YES if
the value of the DEFAULT attribute is YES.

[...]

A Group MUST NOT have more than one member with a DEFAULT
attribute of YES.

As a user, your plugin configuration doesn't need to explicitly handle this requirements (i.e. when setting DEFAULT=YES for a track, you don't have to explicitly set 'DEFAULT=NO' for any other track in the same group). In fact, the plugin automatically enforces the above requirements with the following behavior:

  • anytime the configuration specifies default: 'YES' for a particular EXT-X-MEDIA entry, the plugin will modify all other EXT-X-MEDIA tags sharing the same TYPE and GROUP-ID so that their DEFAULT value is set to "NO".
  • anytime the configuration specifies default: 'YES' for a particular EXT-X-MEDIA entry, the plugin will also set AUTOSELECT = "YES" even if the configuration does not specify so.
  • anytime the configuration specifies autoselect: 'NO' for a particular EXT-X-MEDIA entry, the plugin will ignore the setting if the same entry also has a DEFAULT="YES" value.

Warning

The result of setting DEFAULT=NO is to completely remove the attribute from the playlist, as opposed to the AUTOSELECT attribute which is always added to the playlist, if a value is present in the configuration.

When setting the CHARACTERISTICS attribute, the Apple Authoring specification recommends that the AUTOSELECT attribute is set as well when this is used to select a "hard of hearing" or "video description" track. The plugin will automatically enforce this recommendation even if not explicitly configured.

Examples

Setting German as a default AUDIO language for any possible GROUP-ID value:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'AUDIO'
      language: 'de'
      default: 'YES'
      # AUTOSELECT=YES will be automatically added

Setting German as a default SUBTITLE language for any possible GROUP-ID value:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'SUBTITLES'
      language: 'de'
      default: 'YES'
      # AUTOSELECT=YES will be automatically added

Setting German as a "hard of hearing" subtitle track:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'SUBTITLES'
      language: 'de'
      characteristics: 'public.accessibility.describes-spoken-dialog,public.accessibility.describes-music-and-sound'
      # AUTOSELECT=YES will be automatically added

Setting German as a default language for both AUDIO and SUBTITLES, for any possible GROUP-ID value:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'AUDIO'
      language: 'de'
      default: 'YES'
      # AUTOSELECT=YES will be automatically added
    - type: 'SUBTITLES'
      language: 'de'
      default: 'YES'
      # AUTOSELECT=YES will be automatically added

Deactivating DEFAULT and AUTOSELECT for all subtitles:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'SUBTITLES'
      language: '.*'
      default: 'NO'
      autoselect: 'NO'

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