Fix poor documentation and variable name choice in StreamKey

Issue #9284

PiperOrigin-RevId: 395443015

library/common/src/main/java/com/google/android/exoplayer2/offline/StreamKey.java

@@ -20,11 +20,18 @@ import android.os.Parcelable;
 import androidx.annotation.Nullable;
 
 /**
- * A key for a subset of media which can be separately loaded (a "stream").
+ * A key for a subset of media that can be separately loaded (a "stream").
  *
- * <p>The stream key consists of a period index, a group index within the period and a track index
+ * <p>The stream key consists of a period index, a group index within the period and a stream index
  * within the group. The interpretation of these indices depends on the type of media for which the
- * stream key is used.
+ * stream key is used. Note that they are <em>not</em> the same as track group and track indices,
+ * because multiple tracks can be multiplexed into a single stream.
+ *
+ * <p>Application code should not generally attempt to build StreamKey instances directly. Instead,
+ * {@code DownloadHelper.getDownloadRequest} can be used to generate download requests with the
+ * correct StreamKeys for the track selections that have been configured on the helper. {@code
+ * MediaPeriod.getStreamKeys} provides a lower level way of generating StreamKeys corresponding to a
+ * particular track selection.
  */
 public final class StreamKey implements Comparable<StreamKey>, Parcelable {
 
@@ -32,37 +39,48 @@ public final class StreamKey implements Comparable<StreamKey>, Parcelable {
   public final int periodIndex;
   /** The group index. */
   public final int groupIndex;
-  /** The track index. */
+  /** The stream index. */
-  public final int trackIndex;
+  public final int streamIndex;
+
+  /** @deprecated Use {@link #streamIndex}. */
+  @Deprecated public final int trackIndex;
 
   /**
+   * Creates an instance with {@link #periodIndex} set to 0.
+   *
    * @param groupIndex The group index.
-   * @param trackIndex The track index.
+   * @param streamIndex The stream index.
    */
-  public StreamKey(int groupIndex, int trackIndex) {
+  public StreamKey(int groupIndex, int streamIndex) {
-    this(0, groupIndex, trackIndex);
+    this(0, groupIndex, streamIndex);
   }
 
   /**
+   * Creates an instance.
+   *
    * @param periodIndex The period index.
    * @param groupIndex The group index.
-   * @param trackIndex The track index.
+   * @param streamIndex The stream index.
    */
-  public StreamKey(int periodIndex, int groupIndex, int trackIndex) {
+  @SuppressWarnings("deprecation")
+  public StreamKey(int periodIndex, int groupIndex, int streamIndex) {
     this.periodIndex = periodIndex;
     this.groupIndex = groupIndex;
-    this.trackIndex = trackIndex;
+    this.streamIndex = streamIndex;
+    trackIndex = streamIndex;
   }
 
+  @SuppressWarnings("deprecation")
   /* package */ StreamKey(Parcel in) {
     periodIndex = in.readInt();
     groupIndex = in.readInt();
-    trackIndex = in.readInt();
+    streamIndex = in.readInt();
+    trackIndex = streamIndex;
   }
 
   @Override
   public String toString() {
-    return periodIndex + "." + groupIndex + "." + trackIndex;
+    return periodIndex + "." + groupIndex + "." + streamIndex;
   }
 
   @Override
@@ -77,14 +95,14 @@ public final class StreamKey implements Comparable<StreamKey>, Parcelable {
     StreamKey that = (StreamKey) o;
     return periodIndex == that.periodIndex
         && groupIndex == that.groupIndex
-        && trackIndex == that.trackIndex;
+        && streamIndex == that.streamIndex;
   }
 
   @Override
   public int hashCode() {
     int result = periodIndex;
     result = 31 * result + groupIndex;
-    result = 31 * result + trackIndex;
+    result = 31 * result + streamIndex;
     return result;
   }
 
@@ -96,7 +114,7 @@ public final class StreamKey implements Comparable<StreamKey>, Parcelable {
     if (result == 0) {
       result = groupIndex - o.groupIndex;
       if (result == 0) {
-        result = trackIndex - o.trackIndex;
+        result = streamIndex - o.streamIndex;
       }
     }
     return result;
@@ -113,7 +131,7 @@ public final class StreamKey implements Comparable<StreamKey>, Parcelable {
   public void writeToParcel(Parcel dest, int flags) {
     dest.writeInt(periodIndex);
     dest.writeInt(groupIndex);
-    dest.writeInt(trackIndex);
+    dest.writeInt(streamIndex);
   }
 
   public static final Parcelable.Creator<StreamKey> CREATOR =

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

@@ -415,7 +415,7 @@ public final class DefaultDownloadIndex implements WritableDownloadIndex {
           .append('.')
           .append(streamKey.groupIndex)
           .append('.')
-          .append(streamKey.trackIndex)
+          .append(streamKey.streamIndex)
           .append(',');
     }
     if (stringBuilder.length() > 0) {

library/dash/src/main/java/com/google/android/exoplayer2/source/dash/manifest/DashManifest.java

@@ -189,7 +189,7 @@ public class DashManifest implements FilterableManifest<DashManifest> {
       List<Representation> representations = adaptationSet.representations;
       ArrayList<Representation> copyRepresentations = new ArrayList<>();
       do {
-        Representation representation = representations.get(key.trackIndex);
+        Representation representation = representations.get(key.streamIndex);
         copyRepresentations.add(representation);
         key = keys.poll();
       } while (key.periodIndex == periodIndex && key.groupIndex == adaptationSetIndex);

library/hls/src/main/java/com/google/android/exoplayer2/source/hls/playlist/HlsMasterPlaylist.java

@@ -308,7 +308,7 @@ public final class HlsMasterPlaylist extends HlsPlaylist {
       T stream = streams.get(i);
       for (int j = 0; j < streamKeys.size(); j++) {
         StreamKey streamKey = streamKeys.get(j);
-        if (streamKey.groupIndex == groupIndex && streamKey.trackIndex == i) {
+        if (streamKey.groupIndex == groupIndex && streamKey.streamIndex == i) {
           copiedStreams.add(stream);
           break;
         }

library/smoothstreaming/src/main/java/com/google/android/exoplayer2/source/smoothstreaming/manifest/SsManifest.java

@@ -339,7 +339,7 @@ public class SsManifest implements FilterableManifest<SsManifest> {
         copiedFormats.clear();
       }
       currentStreamElement = streamElement;
-      copiedFormats.add(streamElement.formats[key.trackIndex]);
+      copiedFormats.add(streamElement.formats[key.streamIndex]);
     }
     if (currentStreamElement != null) {
       // Add the last stream element.