Ensure that ShuffleOrder has the same length as the current playlist

Add a fail-fast check in `ExoPlayerImpl` to ensure the equality of the lengths of `ShuffleOrder` and the current playlist. Also improve the documentation of `setShuffleOrder(ShuffleOrder)` with explicit instruction on this.

Issue: androidx/media#480

#minor-release

PiperOrigin-RevId: 544009359

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java

@@ -1494,6 +1494,9 @@ public interface ExoPlayer extends Player {
   /**
    * Sets the shuffle order.
    *
+   * <p>The {@link ShuffleOrder} passed must have the same length as the current playlist ({@link
+   * Player#getMediaItemCount()}).
+   *
    * @param shuffleOrder The shuffle order.
    */
   @UnstableApi

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayerImpl.java

@@ -776,6 +776,7 @@ import java.util.concurrent.TimeoutException;
   @Override
   public void setShuffleOrder(ShuffleOrder shuffleOrder) {
     verifyApplicationThread();
+    checkArgument(shuffleOrder.getLength() == mediaSourceHolderSnapshots.size());
     this.shuffleOrder = shuffleOrder;
     Timeline timeline = createMaskingTimeline();
     PlaybackInfo newPlaybackInfo =

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/ExoPlayerTest.java

@@ -6961,6 +6961,15 @@ public final class ExoPlayerTest {
     assertThat(capturedTimelineShuffleIndexes).isEqualTo(newShuffleOrderIndexes);
   }
 
+  @Test
+  public void setShuffleOrder_shuffleOrderLengthNotEqualToCurrentPlaylistLength_shouldThrow() {
+    ExoPlayer player = new TestExoPlayerBuilder(context).build();
+    player.addMediaSources(ImmutableList.of(new FakeMediaSource(), new FakeMediaSource()));
+
+    assertThrows(
+        IllegalArgumentException.class, () -> player.setShuffleOrder(new FakeShuffleOrder(3)));
+  }
+
   @Test
   public void setMediaSources_empty_whenEmpty_correctMaskingMediaItemIndex() throws Exception {
     final int[] currentMediaItemIndices = {C.INDEX_UNSET, C.INDEX_UNSET, C.INDEX_UNSET};