diff --git a/docs/track-selection.md b/docs/track-selection.md index 4df5821473..e2a998c079 100644 --- a/docs/track-selection.md +++ b/docs/track-selection.md @@ -113,25 +113,27 @@ specifying specific tracks directly: ### Selecting specific tracks -It's possible to specify specific tracks in `TrackSelectionParameters` that -should be selected for the current set of tracks. Note that a change in the -available tracks, for example when changing items in a playlist, will also -invalidate such a track override. - -The simplest way to specify track overrides is to specify the `TrackGroup` that -should be selected for its track type. For example, you can specify an audio -track group to select this audio group and prevent any other audio track groups -from being selected: +It's possible to specify in `TrackSelectionParameters` which of the currently +available tracks should be selected. First, the player's currently available +tracks should be queried using `Player.getTracksInfo`. Second, having identified +which tracks to select, they can be set on `TrackSelectionParameters` using +`TrackSelectionOverrides`. For example, to select the first track from a +specific `audioTrackGroup`: ~~~ player.setTrackSelectionParameters( player.getTrackSelectionParameters() .buildUpon() - .setOverrideForType(new TrackSelectionOverride(audioTrackGroup)) + .setOverrideForType( + new TrackSelectionOverride(audioTrackGroup, /* trackIndex= */ 0)) .build()); ~~~ {: .language-java} +Note that a `TrackSelectionOverride` will only apply to media items that contain +the `TrackGroup` specified in the override. Hence an override may not apply to +a subsequent media item if that item contains different tracks. + ### Disabling track types or groups Track types, like video, audio or text, can be disabled completely using diff --git a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java b/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java index 9c4550416d..572dbeea83 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java +++ b/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java @@ -62,14 +62,14 @@ public final class TrackSelectionOverride implements Bundleable { private static final int FIELD_TRACK_GROUP = 0; private static final int FIELD_TRACKS = 1; - /** Constructs an instance to force all tracks in {@code trackGroup} to be selected. */ - public TrackSelectionOverride(TrackGroup trackGroup) { - this.trackGroup = trackGroup; - ImmutableList.Builder builder = new ImmutableList.Builder<>(); - for (int i = 0; i < trackGroup.length; i++) { - builder.add(i); - } - this.trackIndices = builder.build(); + /** + * Constructs an instance to force {@code trackIndex} in {@code trackGroup} to be selected. + * + * @param trackGroup The {@link TrackGroup} for which to override the track selection. + * @param trackIndex The index of the track in the {@link TrackGroup} to select. + */ + public TrackSelectionOverride(TrackGroup trackGroup, int trackIndex) { + this(trackGroup, ImmutableList.of(trackIndex)); } /** @@ -123,13 +123,9 @@ public final class TrackSelectionOverride implements Bundleable { /** Object that can restore {@code TrackSelectionOverride} from a {@link Bundle}. */ public static final Creator CREATOR = bundle -> { - @Nullable Bundle trackGroupBundle = bundle.getBundle(keyForField(FIELD_TRACK_GROUP)); - checkNotNull(trackGroupBundle); // Mandatory as there are no reasonable defaults. + Bundle trackGroupBundle = checkNotNull(bundle.getBundle(keyForField(FIELD_TRACK_GROUP))); TrackGroup trackGroup = TrackGroup.CREATOR.fromBundle(trackGroupBundle); - @Nullable int[] tracks = bundle.getIntArray(keyForField(FIELD_TRACKS)); - if (tracks == null) { - return new TrackSelectionOverride(trackGroup); - } + int[] tracks = checkNotNull(bundle.getIntArray(keyForField(FIELD_TRACKS))); return new TrackSelectionOverride(trackGroup, Ints.asList(tracks)); }; diff --git a/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverrideTest.java b/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverrideTest.java index 7034903c47..783109d5e9 100644 --- a/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverrideTest.java +++ b/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverrideTest.java @@ -31,12 +31,12 @@ import org.junit.runner.RunWith; public final class TrackSelectionOverrideTest { @Test - public void newTrackSelectionOverride_withJustTrackGroup_selectsAllTracks() { + public void newTrackSelectionOverride_withOneTrack_selectsOneTrack() { TrackSelectionOverride trackSelectionOverride = - new TrackSelectionOverride(newTrackGroupWithIds(1, 2)); + new TrackSelectionOverride(newTrackGroupWithIds(1, 2), /* trackIndex= */ 1); assertThat(trackSelectionOverride.trackGroup).isEqualTo(newTrackGroupWithIds(1, 2)); - assertThat(trackSelectionOverride.trackIndices).containsExactly(0, 1).inOrder(); + assertThat(trackSelectionOverride.trackIndices).containsExactly(1).inOrder(); } @Test diff --git a/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionParametersTest.java b/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionParametersTest.java index 7c7c5618ea..64c7646e16 100644 --- a/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionParametersTest.java +++ b/library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionParametersTest.java @@ -71,7 +71,8 @@ public final class TrackSelectionParametersTest { @Test public void parametersSet_fromDefault_isAsExpected() { TrackSelectionOverride override1 = - new TrackSelectionOverride(new TrackGroup(new Format.Builder().build())); + new TrackSelectionOverride( + new TrackGroup(new Format.Builder().build()), /* trackIndex= */ 0); TrackSelectionOverride override2 = new TrackSelectionOverride( new TrackGroup( @@ -105,7 +106,9 @@ public final class TrackSelectionParametersTest { // General .setForceLowestBitrate(false) .setForceHighestSupportedBitrate(true) - .addOverride(new TrackSelectionOverride(new TrackGroup(new Format.Builder().build()))) + .addOverride( + new TrackSelectionOverride( + new TrackGroup(new Format.Builder().build()), /* trackIndex= */ 0)) .addOverride( new TrackSelectionOverride( new TrackGroup( @@ -206,8 +209,10 @@ public final class TrackSelectionParametersTest { @Test public void addOverride_onDifferentGroups_addsOverride() { - TrackSelectionOverride override1 = new TrackSelectionOverride(newTrackGroupWithIds(1)); - TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(2)); + TrackSelectionOverride override1 = + new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0); + TrackSelectionOverride override2 = + new TrackSelectionOverride(newTrackGroupWithIds(2), /* trackIndex= */ 0); TrackSelectionParameters trackSelectionParameters = new TrackSelectionParameters.Builder(getApplicationContext()) @@ -238,8 +243,10 @@ public final class TrackSelectionParametersTest { @Test public void setOverrideForType_onSameType_replacesOverride() { - TrackSelectionOverride override1 = new TrackSelectionOverride(newTrackGroupWithIds(1)); - TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(2)); + TrackSelectionOverride override1 = + new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0); + TrackSelectionOverride override2 = + new TrackSelectionOverride(newTrackGroupWithIds(2), /* trackIndex= */ 0); TrackSelectionParameters trackSelectionParameters = new TrackSelectionParameters.Builder(getApplicationContext()) @@ -252,8 +259,10 @@ public final class TrackSelectionParametersTest { @Test public void clearOverridesOfType_ofTypeAudio_removesAudioOverride() { - TrackSelectionOverride override1 = new TrackSelectionOverride(AAC_TRACK_GROUP); - TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(1)); + TrackSelectionOverride override1 = + new TrackSelectionOverride(AAC_TRACK_GROUP, /* trackIndex= */ 0); + TrackSelectionOverride override2 = + new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0); TrackSelectionParameters trackSelectionParameters = new TrackSelectionParameters.Builder(getApplicationContext()) .addOverride(override1) @@ -266,8 +275,10 @@ public final class TrackSelectionParametersTest { @Test public void clearOverride_ofTypeGroup_removesOverride() { - TrackSelectionOverride override1 = new TrackSelectionOverride(AAC_TRACK_GROUP); - TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(1)); + TrackSelectionOverride override1 = + new TrackSelectionOverride(AAC_TRACK_GROUP, /* trackIndex= */ 0); + TrackSelectionOverride override2 = + new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0); TrackSelectionParameters trackSelectionParameters = new TrackSelectionParameters.Builder(getApplicationContext()) .addOverride(override1) diff --git a/library/core/src/test/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelectorTest.java b/library/core/src/test/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelectorTest.java index 9be3c4bb56..d7edf1790f 100644 --- a/library/core/src/test/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelectorTest.java +++ b/library/core/src/test/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelectorTest.java @@ -300,7 +300,7 @@ public final class DefaultTrackSelectorTest { trackSelector.setParameters( trackSelector .buildUponParameters() - .setOverrideForType(new TrackSelectionOverride(videoGroupH264)) + .setOverrideForType(new TrackSelectionOverride(videoGroupH264, /* trackIndex= */ 0)) .build()); TrackSelectorResult result = trackSelector.selectTracks( @@ -317,7 +317,7 @@ public final class DefaultTrackSelectorTest { trackSelector.setParameters( trackSelector .buildUponParameters() - .setOverrideForType(new TrackSelectionOverride(videoGroupAv1)) + .setOverrideForType(new TrackSelectionOverride(videoGroupAv1, /* trackIndex= */ 0)) .build()); result = trackSelector.selectTracks( @@ -348,7 +348,8 @@ public final class DefaultTrackSelectorTest { trackSelector.setParameters( trackSelector .buildUponParameters() - .setOverrideForType(new TrackSelectionOverride(audioGroupUnsupported)) + .setOverrideForType( + new TrackSelectionOverride(audioGroupUnsupported, /* trackIndex= */ 0)) .build()); TrackSelectorResult result = trackSelector.selectTracks(