Ensure normalized language code is used everywhere and update documentation.

Issue:#2867
PiperOrigin-RevId: 231385677

library/core/src/main/java/com/google/android/exoplayer2/C.java

@@ -536,9 +536,7 @@ public final class C {
    */
    */
   public static final int SELECTION_FLAG_AUTOSELECT = 1 << 2; // 4
   public static final int SELECTION_FLAG_AUTOSELECT = 1 << 2; // 4
 
 
-  /**
-   * Represents an undetermined language as an ISO 639 alpha-3 language code.
-   */
+  /** Represents an undetermined language as an ISO 639-2 language code. */
   public static final String LANGUAGE_UNDETERMINED = "und";
   public static final String LANGUAGE_UNDETERMINED = "und";
 
 
   /**
   /**

library/core/src/main/java/com/google/android/exoplayer2/Format.java

@@ -159,7 +159,7 @@ public final class Format implements Parcelable {
   @C.SelectionFlags
   @C.SelectionFlags
   public final int selectionFlags;
   public final int selectionFlags;
 
 
-  /** The language, or null if unknown or not applicable. */
+  /** The language as ISO 639-2/T three-letter code, or null if unknown or not applicable. */
   public final @Nullable String language;
   public final @Nullable String language;
 
 
   /**
   /**
@@ -932,7 +932,7 @@ public final class Format implements Parcelable {
     this.encoderDelay = encoderDelay == Format.NO_VALUE ? 0 : encoderDelay;
     this.encoderDelay = encoderDelay == Format.NO_VALUE ? 0 : encoderDelay;
     this.encoderPadding = encoderPadding == Format.NO_VALUE ? 0 : encoderPadding;
     this.encoderPadding = encoderPadding == Format.NO_VALUE ? 0 : encoderPadding;
     this.selectionFlags = selectionFlags;
     this.selectionFlags = selectionFlags;
-    this.language = language;
+    this.language = Util.normalizeLanguageCode(language);
     this.accessibilityChannel = accessibilityChannel;
     this.accessibilityChannel = accessibilityChannel;
     this.subsampleOffsetUs = subsampleOffsetUs;
     this.subsampleOffsetUs = subsampleOffsetUs;
     this.initializationData =
     this.initializationData =

library/core/src/main/java/com/google/android/exoplayer2/extractor/ts/TsPayloadReader.java

@@ -100,7 +100,7 @@ public interface TsPayloadReader {
     public final byte[] initializationData;
     public final byte[] initializationData;
 
 
     /**
     /**
-     * @param language The ISO 639-2 three character language.
+     * @param language The ISO 639-2 three-letter language code.
      * @param type The subtitling type.
      * @param type The subtitling type.
      * @param initializationData The composition and ancillary page ids.
      * @param initializationData The composition and ancillary page ids.
      */
      */

library/core/src/main/java/com/google/android/exoplayer2/offline/DownloadHelper.java

@@ -495,7 +495,7 @@ public final class DownloadHelper {
    * used instead. Must not be called until after preparation completes.
    * used instead. Must not be called until after preparation completes.
    *
    *
    * @param languages A list of audio languages for which tracks should be added to the download
    * @param languages A list of audio languages for which tracks should be added to the download
-   *     selection, as ISO 639-2/T tags.
+   *     selection, as ISO 639-1 two-letter or ISO 639-2 three-letter codes.
    */
    */
   public void addAudioLanguagesToSelection(String... languages) {
   public void addAudioLanguagesToSelection(String... languages) {
     assertPreparedWithMedia();
     assertPreparedWithMedia();
@@ -524,7 +524,7 @@ public final class DownloadHelper {
    *     selected for downloading if no track with one of the specified {@code languages} is
    *     selected for downloading if no track with one of the specified {@code languages} is
    *     available.
    *     available.
    * @param languages A list of text languages for which tracks should be added to the download
    * @param languages A list of text languages for which tracks should be added to the download
-   *     selection, as ISO 639-2/T tags.
+   *     selection, as ISO 639-1 two-letter or ISO 639-2 three-letter codes.
    */
    */
   public void addTextLanguagesToSelection(
   public void addTextLanguagesToSelection(
       boolean selectUndeterminedTextLanguage, String... languages) {
       boolean selectUndeterminedTextLanguage, String... languages) {

library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java

@@ -365,6 +365,8 @@ public class DefaultTrackSelector extends MappingTrackSelector {
     /**
     /**
      * See {@link Parameters#preferredAudioLanguage}.
      * See {@link Parameters#preferredAudioLanguage}.
      *
      *
+     * @param preferredAudioLanguage Preferred audio language as an ISO 639-1 two-letter or ISO
+     *     639-2 three-letter code.
      * @return This builder.
      * @return This builder.
      */
      */
     public ParametersBuilder setPreferredAudioLanguage(String preferredAudioLanguage) {
     public ParametersBuilder setPreferredAudioLanguage(String preferredAudioLanguage) {
@@ -430,6 +432,8 @@ public class DefaultTrackSelector extends MappingTrackSelector {
     /**
     /**
      * See {@link Parameters#preferredTextLanguage}.
      * See {@link Parameters#preferredTextLanguage}.
      *
      *
+     * @param preferredTextLanguage Preferred text language as an ISO 639-1 two-letter or ISO 639-2
+     *     three-letter code.
      * @return This builder.
      * @return This builder.
      */
      */
     public ParametersBuilder setPreferredTextLanguage(String preferredTextLanguage) {
     public ParametersBuilder setPreferredTextLanguage(String preferredTextLanguage) {
@@ -2313,8 +2317,7 @@ public class DefaultTrackSelector extends MappingTrackSelector {
    *     null.
    *     null.
    */
    */
   protected static boolean formatHasLanguage(Format format, @Nullable String language) {
   protected static boolean formatHasLanguage(Format format, @Nullable String language) {
-    return language != null
-        && TextUtils.equals(language, Util.normalizeLanguageCode(format.language));
+    return language != null && TextUtils.equals(language, format.language);
   }
   }
 
 
   private static List<Integer> getViewportFilteredTrackIndices(TrackGroup group, int viewportWidth,
   private static List<Integer> getViewportFilteredTrackIndices(TrackGroup group, int viewportWidth,

library/core/src/main/java/com/google/android/exoplayer2/util/Util.java

@@ -418,9 +418,10 @@ public final class Util {
   }
   }
 
 
   /**
   /**
-   * Returns a normalized RFC 639-2/T code for {@code language}.
+   * Returns a normalized ISO 639-2/T code for {@code language}.
    *
    *
-   * @param language A case-insensitive ISO 639 alpha-2 or alpha-3 language code.
+   * @param language A case-insensitive ISO 639-1 two-letter or ISO 639-2 three-letter language
+   *     code.
    * @return The all-lowercase normalized code, or null if the input was null, or {@code
    * @return The all-lowercase normalized code, or null if the input was null, or {@code
    *     language.toLowerCase()} if the language could not be normalized.
    *     language.toLowerCase()} if the language could not be normalized.
    */
    */

library/hls/src/test/java/com/google/android/exoplayer2/source/hls/playlist/HlsMasterPlaylistParserTest.java

@@ -225,7 +225,7 @@ public class HlsMasterPlaylistParserTest {
     Format closedCaptionFormat = playlist.muxedCaptionFormats.get(0);
     Format closedCaptionFormat = playlist.muxedCaptionFormats.get(0);
     assertThat(closedCaptionFormat.sampleMimeType).isEqualTo(MimeTypes.APPLICATION_CEA708);
     assertThat(closedCaptionFormat.sampleMimeType).isEqualTo(MimeTypes.APPLICATION_CEA708);
     assertThat(closedCaptionFormat.accessibilityChannel).isEqualTo(4);
     assertThat(closedCaptionFormat.accessibilityChannel).isEqualTo(4);
-    assertThat(closedCaptionFormat.language).isEqualTo("es");
+    assertThat(closedCaptionFormat.language).isEqualTo("spa");
   }
   }
 
 
   @Test
   @Test