shaka-player/tutorials/language.html

<!--
 Copyright 2014 Google Inc.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<h3 class="tutorial-heading">
Multi-lingual Content
</h3>

<p>
Shaka Player supports multi-lingual content.  A multi-lingual manifest contains
separate AdaptationSets for each audio or subtitle language.  For example:
</p>

<pre class="prettyprint source"><code id="mpd_sample1">&lt;AdaptationSet id="0" mimeType="video/webm" codecs="vp8"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="1" mimeType="audio/webm" codecs="vorbis" lang="en"&gt;
  &lt;Role value="main" /&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="2" mimeType="audio/webm" codecs="vorbis" lang="de"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="3" mimeType="audio/webm" codecs="vorbis" lang="es"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="4" mimeType="audio/webm" codecs="vorbis" lang="fr"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="5" mimeType="audio/webm" codecs="vorbis" lang="it"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="6" mimeType="text/vtt" lang="en"&gt;
  &lt;Role value="main" /&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="7" mimeType="text/vtt" lang="fr"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="8" mimeType="text/vtt" lang="pt-BR"&gt;
  ...
&lt;/AdaptationSet&gt;
&lt;AdaptationSet id="9" mimeType="text/vtt" lang="el"&gt;
  ...
&lt;/AdaptationSet&gt;
</code></pre>

<p>
See assets/angel_one.mpd in the sources for a full example.
</p>


<h3 class="tutorial-heading">
Language Tags
</h3>

<p>
Languages are represented by {@link http://goo.gl/Lq37Vx 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.
</p>

<p>
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 {@link
http://goo.gl/9i0UUg BCP 47}.  However, MP4 track metadata always uses 3-letter
tags, and some MPD creation tools use what is in the MP4 track directly.
</p>

<p>
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".
</p>


<h3 class="tutorial-heading">
Language APIs
</h3>

<p>
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:

<ul>
  <li>{@link shaka.player.Player#getAudioTracks}</li>
  <li>{@link shaka.player.Player#getTextTracks}</li>
  <li>{@link shaka.player.Player#selectAudioTrack}</li>
  <li>{@link shaka.player.Player#selectTextTrack}</li>
  <li>{@link shaka.player.Player#enableTextTrack}</li>
</ul>

<i>
Please note that {@link shaka.player.Player#selectVideoTrack} is also provided,
but it can interfere with automatic bitrate adaptation.  If you allow your
users to choose video tracks manually, you should disable adaptation via
{@link shaka.player.Player#configure} with the 'enableAdaptation' option
set to false.
</i>
</p>

<p>
To avoid the necessity of choosing audio and text tracks manually, Shaka Player
provides a mechanism, via {@link 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.
</p>


<h3 class="tutorial-heading">
Automatic Stream Selection Using Language Preference
</h3>

<p>
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.
</p>

<p>
An exact language match is preferred ("en-US" &equiv; "en-US"), followed by the
base language of the user's sublanguage ("en" &sup; "en-US"), followed by other
sublanguages with the same base language ("en-GB" &asymp; "en-US").  If none of
these fuzzy matches work, the first available language from the MPD is used.
</p>

<p>
The matching algorithm can be found in {@link shaka.util.LanguageUtils.match}.
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
Let's say, however, that the user prefers Portuguese. If Portuguese audio isn't
available, the audio AdaptationSet tagged with &lt;Role value="main" /&gt; 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.
</p>