Default language

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

This plugin allows to modify EXT-X-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, LANGUAGE, NAME and URI, 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.

In general, fields type, group-id, language, name and uri are used to perform selection of specific EXT-X-MEDIA tags, e.g. to select the track(s) you need to edit. The following rules apply:

  • the two supported values for the type field are 'AUDIO' and 'SUBTITLES'. This is a mandatory item and must always be included in your configuration

  • the value for fields group-id, language and uri can be any regular expression

  • fields group-id, language, name and uri are optional and can each be omitted, which is functionally equivalent to specifying a '.*' "match-all" regular expression

  • specifying an empty string '' for any of the fields group-id, language, name and uri can be used to perform "negative selection" on EXT-X-MEDIA tags, i.e. to select tracks that do not have one or more of such optional fields

The fields default, autoselect and characteristics are used to specify the modification to be applied to the EXT-X-MEDIA tag. The following rules apply:

  • the two supported values for the default and autoselect field are 'YES' and 'NO'.

  • the characteristics field can hold any string value. It is the user's responsibility to make sure that the string is a valid accessibility string as per HLS authoring guidelines.

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 track with name "German" as a default AUDIO language for any possible GROUP-ID value:

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

Setting accessibility attributes for track(s) matching a specific URI pattern:

m3u8_main:
  - manifest_edit.plugins.m3u8_main.default_language:
    - type: 'AUDIO'
      uri: '.*_describesvideo.*'
      characteristics: 'public.accessibility.describes-video'

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.