Add WrappingMediaSource

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/ClippingMediaSource.java

@@ -41,7 +41,7 @@
  * positions. The wrapped source must consist of a single period.
  */
 @UnstableApi
-public final class ClippingMediaSource extends CompositeMediaSource<Void> {
+public final class ClippingMediaSource extends WrappingMediaSource {
 
   /** Thrown when a {@link ClippingMediaSource} cannot clip its wrapped source. */
   public static final class IllegalClippingException extends IOException {
@@ -202,7 +202,7 @@ public MediaItem getMediaItem() {
   @Override
   protected void prepareSourceInternal(@Nullable TransferListener mediaTransferListener) {
     super.prepareSourceInternal(mediaTransferListener);
-    prepareChildSource(/* id= */ null, mediaSource);
+    prepareChildSource(mediaSource);
   }
 
   @Override
@@ -242,7 +242,7 @@ protected void releaseSourceInternal() {
   }
 
   @Override
-  protected void onChildSourceInfoRefreshed(Void id, MediaSource mediaSource, Timeline timeline) {
+  protected void onChildSourceInfoRefreshed(Timeline timeline) {
     if (clippingError != null) {
       return;
     }

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/LoopingMediaSource.java

@@ -43,7 +43,7 @@
  */
 @Deprecated
 @UnstableApi
-public final class LoopingMediaSource extends CompositeMediaSource<Void> {
+public final class LoopingMediaSource extends WrappingMediaSource {
 
   private final MaskingMediaSource maskingMediaSource;
   private final int loopCount;
@@ -95,7 +95,7 @@ public boolean isSingleWindow() {
   @Override
   protected void prepareSourceInternal(@Nullable TransferListener mediaTransferListener) {
     super.prepareSourceInternal(mediaTransferListener);
-    prepareChildSource(/* id= */ null, maskingMediaSource);
+    prepareChildSource(maskingMediaSource);
   }
 
   @Override
@@ -123,7 +123,7 @@ public void releasePeriod(MediaPeriod mediaPeriod) {
   }
 
   @Override
-  protected void onChildSourceInfoRefreshed(Void id, MediaSource mediaSource, Timeline timeline) {
+  protected void onChildSourceInfoRefreshed(Timeline timeline) {
     Timeline loopingTimeline =
         loopCount != Integer.MAX_VALUE
             ? new LoopingTimeline(timeline, loopCount)
@@ -134,7 +134,8 @@ protected void onChildSourceInfoRefreshed(Void id, MediaSource mediaSource, Time
   @Override
   @Nullable
   protected MediaPeriodId getMediaPeriodIdForChildMediaPeriodId(
-      Void id, MediaPeriodId mediaPeriodId) {
+      Void id, MediaPeriodId mediaPeriodId
+  ) {
     return loopCount != Integer.MAX_VALUE
         ? childMediaPeriodIdToMediaPeriodId.get(mediaPeriodId)
         : mediaPeriodId;

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MaskingMediaSource.java

@@ -37,7 +37,7 @@
  * structure is known.
  */
 @UnstableApi
-public final class MaskingMediaSource extends CompositeMediaSource<Void> {
+public final class MaskingMediaSource extends WrappingMediaSource {
 
   private final MediaSource mediaSource;
   private final boolean useLazyPreparation;
@@ -84,7 +84,7 @@ public void prepareSourceInternal(@Nullable TransferListener mediaTransferListen
     super.prepareSourceInternal(mediaTransferListener);
     if (!useLazyPreparation) {
       hasStartedPreparing = true;
-      prepareChildSource(/* id= */ null, mediaSource);
+      prepareChildSource(mediaSource);
     }
   }
 
@@ -115,7 +115,7 @@ public MaskingMediaPeriod createPeriod(
       unpreparedMaskingMediaPeriod = mediaPeriod;
       if (!hasStartedPreparing) {
         hasStartedPreparing = true;
-        prepareChildSource(/* id= */ null, mediaSource);
+        prepareChildSource(mediaSource);
       }
     }
     return mediaPeriod;
@@ -137,8 +137,7 @@ public void releaseSourceInternal() {
   }
 
   @Override
-  protected void onChildSourceInfoRefreshed(
-      Void id, MediaSource mediaSource, Timeline newTimeline) {
+  protected void onChildSourceInfoRefreshed(MediaSource mediaSource, Timeline newTimeline) {
     @Nullable MediaPeriodId idForMaskingPeriodPreparation = null;
     if (isPrepared) {
       timeline = timeline.cloneWithUpdatedTimeline(newTimeline);
@@ -208,8 +207,7 @@ protected void onChildSourceInfoRefreshed(
 
   @Override
   @Nullable
-  protected MediaPeriodId getMediaPeriodIdForChildMediaPeriodId(
-      Void id, MediaPeriodId mediaPeriodId) {
+  protected MediaPeriodId getMediaPeriodIdForChildMediaPeriodId(MediaPeriodId mediaPeriodId) {
     return mediaPeriodId.copyWithPeriodUid(getExternalPeriodUid(mediaPeriodId.periodUid));
   }
 

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/WrappingMediaSource.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright (C) 2022 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.exoplayer.source;
+
+import androidx.media3.common.Timeline;
+
+/**
+ * Single-child {@link CompositeMediaSource}.
+ */
+public abstract class WrappingMediaSource extends CompositeMediaSource<Void> {
+
+  /**
+   * @deprecated - Use {@link #onChildSourceInfoRefreshed}.
+   */
+  @Deprecated
+  @Override
+  protected final void onChildSourceInfoRefreshed(
+      Void id, MediaSource mediaSource, Timeline timeline
+  ) {
+    onChildSourceInfoRefreshed(timeline);
+  }
+
+  /**
+   * Called when the source info has been refreshed.
+   *
+   * @param timeline The timeline of the source.
+   */
+  protected abstract void onChildSourceInfoRefreshed(Timeline timeline);
+
+  /**
+   * Prepares a source.
+   *
+   * <p>{@link #onChildSourceInfoRefreshed(Timeline)} will be called when the
+   * child source updates its timeline with the same {@code id} passed to this method.
+   *
+   * <p>If sources aren't explicitly released with {@link #releaseChildSource()} they will be
+   * released in {@link #releaseSourceInternal()}.
+   *
+   * @param mediaSource The child {@link MediaSource}.
+   */
+  protected final void prepareChildSource(MediaSource mediaSource) {
+    prepareChildSource(CHILD_SOURCE_ID, mediaSource);
+  }
+
+  /**
+   * Enables the child source.
+   */
+  protected final void enableChildSource() {
+    enableChildSource(CHILD_SOURCE_ID);
+  }
+
+  /**
+   * Disables the child source.
+   */
+  protected final void disableChildSource() {
+    disableChildSource(CHILD_SOURCE_ID);
+  }
+
+  /**
+   * Releases the child source.
+   */
+  protected final void releaseChildSource() {
+    releaseChildSource(CHILD_SOURCE_ID);
+  }
+
+  private static final Void CHILD_SOURCE_ID = null;
+}

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

@@ -128,6 +128,7 @@
 import androidx.media3.exoplayer.source.ShuffleOrder;
 import androidx.media3.exoplayer.source.SinglePeriodTimeline;
 import androidx.media3.exoplayer.source.TrackGroupArray;
+import androidx.media3.exoplayer.source.WrappingMediaSource;
 import androidx.media3.exoplayer.source.ads.ServerSideAdInsertionMediaSource;
 import androidx.media3.exoplayer.trackselection.DefaultTrackSelector;
 import androidx.media3.exoplayer.upstream.Allocation;
@@ -3941,16 +3942,16 @@ public void delegatingMediaSourceApproach() throws Exception {
             new TimelineWindowDefinition(
                 /* isSeekable= */ true, /* isDynamic= */ false, /* durationUs= */ 10_000_000));
     final ConcatenatingMediaSource underlyingSource = new ConcatenatingMediaSource();
-    CompositeMediaSource<Void> delegatingMediaSource =
-        new CompositeMediaSource<Void>() {
+    WrappingMediaSource delegatingMediaSource =
+        new WrappingMediaSource() {
           @Override
           public void prepareSourceInternal(@Nullable TransferListener mediaTransferListener) {
             super.prepareSourceInternal(mediaTransferListener);
             underlyingSource.addMediaSource(
                 new FakeMediaSource(fakeTimeline, ExoPlayerTestRunner.VIDEO_FORMAT));
             underlyingSource.addMediaSource(
                 new FakeMediaSource(fakeTimeline, ExoPlayerTestRunner.VIDEO_FORMAT));
-            prepareChildSource(null, underlyingSource);
+            prepareChildSource(underlyingSource);
           }
 
           @Override
@@ -3965,8 +3966,7 @@ public void releasePeriod(MediaPeriod mediaPeriod) {
           }
 
           @Override
-          protected void onChildSourceInfoRefreshed(
-              Void id, MediaSource mediaSource, Timeline timeline) {
+          protected void onChildSourceInfoRefreshed(Timeline timeline) {
             refreshSourceInfo(timeline);
           }
 

libraries/exoplayer_ima/src/main/java/androidx/media3/exoplayer/ima/ImaServerSideAdInsertionMediaSource.java

@@ -56,11 +56,11 @@
 import androidx.media3.common.util.Util;
 import androidx.media3.datasource.TransferListener;
 import androidx.media3.exoplayer.drm.DrmSessionManagerProvider;
-import androidx.media3.exoplayer.source.CompositeMediaSource;
 import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
 import androidx.media3.exoplayer.source.ForwardingTimeline;
 import androidx.media3.exoplayer.source.MediaPeriod;
 import androidx.media3.exoplayer.source.MediaSource;
+import androidx.media3.exoplayer.source.WrappingMediaSource;
 import androidx.media3.exoplayer.source.ads.ServerSideAdInsertionMediaSource;
 import androidx.media3.exoplayer.source.ads.ServerSideAdInsertionMediaSource.AdPlaybackStateUpdater;
 import androidx.media3.exoplayer.source.ads.ServerSideAdInsertionUtil;
@@ -108,7 +108,7 @@
 
 /** MediaSource for IMA server side inserted ad streams. */
 @UnstableApi
-public final class ImaServerSideAdInsertionMediaSource extends CompositeMediaSource<Void> {
+public final class ImaServerSideAdInsertionMediaSource extends WrappingMediaSource {
 
   /**
    * Factory for creating {@link ImaServerSideAdInsertionMediaSource
@@ -521,8 +521,7 @@ public void prepareSourceInternal(@Nullable TransferListener mediaTransferListen
   }
 
   @Override
-  protected void onChildSourceInfoRefreshed(
-      Void id, MediaSource mediaSource, Timeline newTimeline) {
+  protected void onChildSourceInfoRefreshed(Timeline newTimeline) {
     refreshSourceInfo(
         new ForwardingTimeline(newTimeline) {
           @Override
@@ -655,7 +654,7 @@ private void setContentUri(Uri contentUri) {
               .withIsServerSideInserted(/* adGroupIndex= */ 0, true);
       mainHandler.post(() -> setAdPlaybackState(liveAdPlaybackState));
     }
-    prepareChildSource(/* id= */ null, serverSideAdInsertionMediaSource);
+    prepareChildSource(serverSideAdInsertionMediaSource);
   }
 
   // Static methods.