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">
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 can interfere with automatic bitrate adaptation. If you allow your users to
choose video tracks manually, call {@link shaka.player.Player#enableAdaptation}
(false) to disable automatic video adaptation when a manual choice is made.
</i>
</p>

<p>
To avoid the necessity of choosing audio and text tracks manually, Shaka Player
provides {@link shaka.player.Player#setPreferredLanguage an API 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>