Additional clean-up and formatting

Author: tonihei

RELEASENOTES.md

@@ -3,6 +3,7 @@
 ### Unreleased changes
 
 *   Common Library:
+    *   Add `Format.labels` to allow localized or other alternative labels.
 *   ExoPlayer:
     *   Fix issue where `PreloadMediaPeriod` cannot retain the streams when it
         is preloaded again.
@@ -100,6 +101,8 @@
 *   RTMP Extension:
 *   HLS Extension:
 *   DASH Extension:
+    *   Populate all `Label` elements from the manifest into `Format.labels`
+        ([#1054](https://github.com/androidx/media/pull/1054)).
 *   Smooth Streaming Extension:
 *   RTSP Extension:
     *   Skip empty session information values (i-tags) in SDP parsing

libraries/common/src/main/java/androidx/media3/common/Format.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.common;
 
+import static androidx.media3.common.util.Assertions.checkState;
 import static java.lang.annotation.ElementType.TYPE_USE;
 
 import android.os.Bundle;
@@ -140,7 +141,7 @@ public static final class Builder {
 
     @Nullable private String id;
     @Nullable private String label;
-    @Nullable private List<Label> labels;
+    private List<Label> labels;
     @Nullable private String language;
     private @C.SelectionFlags int selectionFlags;
     private @C.RoleFlags int roleFlags;
@@ -196,6 +197,7 @@ public static final class Builder {
 
     /** Creates a new instance with default values. */
     public Builder() {
+      labels = ImmutableList.of();
       averageBitrate = NO_VALUE;
       peakBitrate = NO_VALUE;
       // Sample specific.
@@ -298,6 +300,9 @@ public Builder setId(int id) {
     /**
      * Sets {@link Format#label}. The default value is {@code null}.
      *
+     * If both this default label and a list of {@link #setLabels labels} are set, this default
+     * label must be part of label list.
+     *
      * @param label The {@link Format#label}.
      * @return The builder.
      */
@@ -308,14 +313,17 @@ public Builder setLabel(@Nullable String label) {
     }
 
     /**
-     * Sets {@link Format#labels}. The default value is {@code null}.
+     * Sets {@link Format#labels}. The default value is an empty list.
+     *
+     * If both the default {@linkplain #setLabel label} and this list are set, the default label
+     * must be part of this list of labels.
      *
      * @param labels The {@link Format#labels}.
      * @return The builder.
      */
     @CanIgnoreReturnValue
-    public Builder setLabels(@Nullable List<Label> labels) {
-      this.labels = labels;
+    public Builder setLabels(List<Label> labels) {
+      this.labels = ImmutableList.copyOf(labels);
       return this;
     }
 
@@ -757,10 +765,20 @@ public Format build() {
   /** An identifier for the format, or null if unknown or not applicable. */
   @Nullable public final String id;
 
-  /** The human readable label, or null if unknown or not applicable. */
+  /**
+   * The default human readable label, or null if unknown or not applicable.
+   *
+   * If non-null, the same label will be part of {@link #labels} too. If null, {@link #labels}
+   * will be empty.
+   */
   @Nullable public final String label;
 
-  /** The human readable list of labels, or null if unknown or not applicable. */
+  /**
+   * The human readable list of labels, or an empty list if unknown or not applicable.
+   *
+   * If non-empty, the default {@link #label} will be part of this list. If empty, the default
+   * {@link #label} will be null.
+   */
   @UnstableApi public final List<Label> labels;
 
   /** The language as an IETF BCP 47 conformant tag, or null if unknown or not applicable. */
@@ -952,17 +970,19 @@ public Format build() {
   private Format(Builder builder) {
     id = builder.id;
     language = Util.normalizeLanguageCode(builder.language);
-    @Nullable String tmpLabel = builder.label;
-    labels = builder.labels == null ? new ArrayList<>() : builder.labels;
-    if (labels.isEmpty() && !TextUtils.isEmpty(tmpLabel)) {
-      labels.add(new Label(language, tmpLabel));
-      label = tmpLabel;
-    } else if (!labels.isEmpty() && TextUtils.isEmpty(tmpLabel)) {
-      label = getDefaultLabel(tmpLabel, labels);
+    if (builder.labels.isEmpty() && builder.label != null) {
+      labels = ImmutableList.of(new Label(language, builder.label));
+      label = builder.label;
+    } else if (!builder.labels.isEmpty() && builder.label == null) {
+      labels = builder.labels;
+      label = getDefaultLabel(builder.labels, language);
     } else {
-      label = tmpLabel;
+      checkState(
+          (builder.labels.isEmpty() && builder.label == null)
+              || (builder.labels.stream().anyMatch(l -> l.value.equals(builder.label))));
+      labels = builder.labels;
+      label = builder.label;
     }
-    checkLabels(label, labels);
     selectionFlags = builder.selectionFlags;
     roleFlags = builder.roleFlags;
     averageBitrate = builder.averageBitrate;
@@ -1010,29 +1030,6 @@ private Format(Builder builder) {
     }
   }
 
-  private @Nullable String getDefaultLabel(@Nullable String label, List<Label> labels) {
-    if (TextUtils.isEmpty(label)) {
-      for (Label l : labels) {
-        if (TextUtils.equals(l.lang, language)) {
-          return l.value;
-        }
-      }
-      if (!labels.isEmpty()) {
-        return labels.get(0).value;
-      }
-    }
-    return label;
-  }
-
-  private void checkLabels(@Nullable String label, List<Label> labels)
-      throws IllegalStateException {
-    if (!TextUtils.isEmpty(label)
-        && !labels.isEmpty()
-        && labels.stream().noneMatch(l -> TextUtils.equals(l.value, label))) {
-      throw new IllegalStateException();
-    }
-  }
-
   /** Returns a {@link Format.Builder} initialized with the values of this instance. */
   @UnstableApi
   public Builder buildUpon() {
@@ -1056,7 +1053,7 @@ public Format withManifestFormatInfo(Format manifestFormat) {
 
     // Prefer manifest values, but fill in from sample format if missing.
     @Nullable String label = manifestFormat.label != null ? manifestFormat.label : this.label;
-    List<Label> labels = manifestFormat.labels;
+    List<Label> labels = !manifestFormat.labels.isEmpty() ? manifestFormat.labels : this.labels;
     @Nullable String language = this.language;
     if ((trackType == C.TRACK_TYPE_TEXT || trackType == C.TRACK_TYPE_AUDIO)
         && manifestFormat.language != null) {
@@ -1246,6 +1243,7 @@ public boolean equals(@Nullable Object obj) {
         && Float.compare(pixelWidthHeightRatio, other.pixelWidthHeightRatio) == 0
         && Util.areEqual(id, other.id)
         && Util.areEqual(label, other.label)
+        && labels.equals(other.labels)
         && Util.areEqual(codecs, other.codecs)
         && Util.areEqual(containerMimeType, other.containerMimeType)
         && Util.areEqual(sampleMimeType, other.sampleMimeType)
@@ -1254,8 +1252,7 @@ public boolean equals(@Nullable Object obj) {
         && Util.areEqual(metadata, other.metadata)
         && Util.areEqual(colorInfo, other.colorInfo)
         && Util.areEqual(drmInitData, other.drmInitData)
-        && initializationDataEquals(other)
-        && labels.equals(other.labels);
+        && initializationDataEquals(other);
   }
 
   /**
@@ -1338,7 +1335,7 @@ public static String toLogString(@Nullable Format format) {
     if (format.language != null) {
       builder.append(", language=").append(format.language);
     }
-    if (format.labels.size() > 0) {
+    if (!format.labels.isEmpty()) {
       builder.append(", labels=[");
       Joiner.on(',').appendTo(builder, format.labels);
       builder.append("]");
@@ -1561,4 +1558,13 @@ private static String keyForInitializationData(int initialisationDataIndex) {
   private static <T> T defaultIfNull(@Nullable T value, @Nullable T defaultValue) {
     return value != null ? value : defaultValue;
   }
+
+  private static String getDefaultLabel(List<Label> labels, @Nullable String language) {
+    for (Label l : labels) {
+      if (TextUtils.equals(l.language, language)) {
+        return l.value;
+      }
+    }
+    return labels.get(0).value;
+  }
 }

libraries/common/src/main/java/androidx/media3/common/Label.java

@@ -1,94 +1,86 @@
+/*
+ * Copyright 2024 The Android Open Source Project
+ *
+ * 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.
+ */
 package androidx.media3.common;
 
 import static androidx.media3.common.util.Assertions.checkNotNull;
 
 import android.os.Bundle;
-import android.os.Parcel;
-import android.os.Parcelable;
-import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.media3.common.util.UnstableApi;
 import androidx.media3.common.util.Util;
 
-/** A Label, as defined by ISO 23009-1, 4th edition, 5.3.7.2. */
+/** A label for a {@link Format}. */
 @UnstableApi
-public class Label implements Parcelable, Bundleable {
-  /** Declares the language code(s) for this Label. */
-  @Nullable public final String lang;
+public class Label {
+  /**
+   * The language of this label, as an IETF BCP 47 conformant tag, or null if unknown or not
+   * applicable.
+   */
+  @Nullable public final String language;
 
-  /** The value for this Label. */
+  /** The value for this label. */
   public final String value;
 
   /**
-   * @param lang The lang code.
-   * @param value The value.
+   * Creates a label.
+   *
+   * @param language The language of this label, as an IETF BCP 47 conformant tag, or null if
+   *     unknown or not applicable.
+   * @param value The label value.
    */
-  public Label(@Nullable String lang, String value) {
-    this.lang = lang;
+  public Label(@Nullable String language, String value) {
+    this.language = Util.normalizeLanguageCode(language);
     this.value = value;
   }
 
-  /* package */ Label(Parcel in) {
-    lang = in.readString();
-    value = in.readString();
-  }
-
   @Override
   public boolean equals(@Nullable Object o) {
-    if (this == o) return true;
-    if (o == null || getClass() != o.getClass()) return false;
+    if (this == o) {
+      return true;
+    }
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
     Label label = (Label) o;
-    return Util.areEqual(lang, label.lang) && Util.areEqual(value, label.value);
+    return Util.areEqual(language, label.language) && Util.areEqual(value, label.value);
   }
 
   @Override
   public int hashCode() {
     int result = value.hashCode();
-    result = 31 * result + (lang != null ? lang.hashCode() : 0);
+    result = 31 * result + (language != null ? language.hashCode() : 0);
     return result;
   }
 
-  @Override
-  public int describeContents() {
-    return 0;
-  }
-
-  @Override
-  public void writeToParcel(@NonNull Parcel dest, int flags) {
-    dest.writeString(lang);
-    dest.writeString(value);
-  }
-
-  public static final Parcelable.Creator<Label> CREATOR =
-      new Parcelable.Creator<Label>() {
-
-        @Override
-        public Label createFromParcel(Parcel in) {
-          return new Label(in);
-        }
-
-        @Override
-        public Label[] newArray(int size) {
-          return new Label[size];
-        }
-      };
-
-  private static final String FIELD_LANG_INDEX = Util.intToStringMaxRadix(0);
+  private static final String FIELD_LANGUAGE_INDEX = Util.intToStringMaxRadix(0);
   private static final String FIELD_VALUE_INDEX = Util.intToStringMaxRadix(1);
 
-  @Override
+  /** Serializes this instance to a {@link Bundle}. */
   public Bundle toBundle() {
     Bundle bundle = new Bundle();
-    bundle.putString(FIELD_LANG_INDEX, lang);
+    if (language != null) {
+      bundle.putString(FIELD_LANGUAGE_INDEX, language);
+    }
     bundle.putString(FIELD_VALUE_INDEX, value);
     return bundle;
   }
 
-  /**
-   * Constructs an instance of {@link Label} from a {@link Bundle} produced by {@link #toBundle()}.
-   */
+  /** Deserializes an instance from a {@link Bundle} produced by {@link #toBundle()}. */
   public static Label fromBundle(Bundle bundle) {
     return new Label(
-        bundle.getString(FIELD_LANG_INDEX), checkNotNull(bundle.getString(FIELD_VALUE_INDEX)));
+        bundle.getString(FIELD_LANGUAGE_INDEX), checkNotNull(bundle.getString(FIELD_VALUE_INDEX)));
   }
 }