Multi-lingual Content
Shaka Player supports multi-lingual content. A multi-lingual manifest contains separate AdaptationSets for each audio or subtitle language. For example:
<AdaptationSet id="0" mimeType="video/webm" codecs="vp8">
...
</AdaptationSet>
<AdaptationSet id="1" mimeType="audio/webm" codecs="vorbis" lang="en">
<Role value="main" />
...
</AdaptationSet>
<AdaptationSet id="2" mimeType="audio/webm" codecs="vorbis" lang="de">
...
</AdaptationSet>
<AdaptationSet id="3" mimeType="audio/webm" codecs="vorbis" lang="es">
...
</AdaptationSet>
<AdaptationSet id="4" mimeType="audio/webm" codecs="vorbis" lang="fr">
...
</AdaptationSet>
<AdaptationSet id="5" mimeType="audio/webm" codecs="vorbis" lang="it">
...
</AdaptationSet>
<AdaptationSet id="6" mimeType="text/vtt" lang="en">
<Role value="main" />
...
</AdaptationSet>
<AdaptationSet id="7" mimeType="text/vtt" lang="fr">
...
</AdaptationSet>
<AdaptationSet id="8" mimeType="text/vtt" lang="pt-BR">
...
</AdaptationSet>
<AdaptationSet id="9" mimeType="text/vtt" lang="el">
...
</AdaptationSet>
See assets/angel_one.mpd in the sources for a full example.
Language Tags
Languages are represented by ISO 639 language tags such as "en", "fra-CA", "deu-AT", etc. Both 2-letter and 3-letter ISO tags are supported, as are sublanguages.
Some languages have both 2-letter and 3-letter tags defined, and some languages even have more than one 3-letter tag defined. The DASH spec says that language tags in an MPD must always be given in their shortest form. This follows BCP 47. However, MP4 track metadata always uses 3-letter tags, and some MPD creation tools use what is in the MP4 track directly.
The Shaka Player will normalize all language tags (from MPDs or in the language preference setting) to their shortest form when they are ingested. Any 3-letter tag with an equivalent 2-letter tag will be mapped to 2 letters. Languages with multiple 3-letter tags are also handled through this mapping. For example, you could use either of Greek's 3-letter tags ("ell" and "gre"), and both would map to the 2-letter tag "el".
Language APIs
The Player library provides APIs to list and select audio and text tracks. The audio and text track objects include a language property. This allows a user to manually change audio or subtitle languages. There is also an API to enable or disable the selected subtitles. See:
- shaka.player.Player#getAudioTracks
- shaka.player.Player#getTextTracks
- shaka.player.Player#selectAudioTrack
- shaka.player.Player#selectTextTrack
- shaka.player.Player#enableTextTrack
To avoid the necessity of choosing audio and text tracks manually, Shaka Player provides a mechanism, via shaka.player.Player#configure with the 'preferredLanguage' option, to set a user's preferred language. The language preference defaults to "en" (English) if not set.
Automatic Stream Selection Using Language Preference
When starting a video, the Player will choose streams which best fit the user's language preference. This uses a fuzzy matching algorithm for languages.
An exact language match is preferred ("en-US" ≡ "en-US"), followed by the base language of the user's sublanguage ("en" ⊃ "en-US"), followed by other sublanguages with the same base language ("en-GB" ≈ "en-US"). If none of these fuzzy matches work, the first available language from the MPD is used.
The matching algorithm can be found in shaka.util.LanguageUtils.match.
The same matching algorithm is used to select both audio and text tracks. When no audio track matches the user preference, text tracks are enabled by default.
For example, if the user prefers French, and French is available for both audio and subtitles, then French is selected for both. The subtitles are not enabled by default because the user's preferred audio language was found.
Let's say, however, that the user prefers Portuguese. If Portuguese audio isn't available, the audio AdaptationSet tagged with <Role value="main" /> will be chosen. If there is no set tagged with "main", then the first AdaptationSet in the MPD will be chosen. Since there was no Portuguese audio, the Portuguese subtitles, if found, will be enabled.