Gradle dependencies
compile group: 'androidx.media3', name: 'media3-exoplayer', version: '1.0.0-alpha03'
- groupId: androidx.media3
- artifactId: media3-exoplayer
- version: 1.0.0-alpha03
Artifact androidx.media3:media3-exoplayer:1.0.0-alpha03 it located at Google repository (https://maven.google.com/)
Overview
MediaSource that wraps a source and clips its timeline based on specified start/end
positions. The wrapped source must consist of a single period.
Summary
Constructors |
---|
public | ClippingMediaSource(MediaSource mediaSource, long durationUs)
Creates a new clipping source that wraps the specified source and provides samples from the
default position for the specified duration. |
public | ClippingMediaSource(MediaSource mediaSource, long startPositionUs, long endPositionUs)
Creates a new clipping source that wraps the specified source and provides samples between the
specified start and end position. |
public | ClippingMediaSource(MediaSource mediaSource, long startPositionUs, long endPositionUs, boolean enableInitialDiscontinuity, boolean allowDynamicClippingUpdates, boolean relativeToDefaultPosition)
Creates a new clipping source that wraps the specified source. |
Methods |
---|
public MediaPeriod | createPeriod(MediaSource.MediaPeriodId id, Allocator allocator, long startPositionUs)
|
public MediaItem | getMediaItem()
|
public void | maybeThrowSourceInfoRefreshError()
|
protected abstract void | onChildSourceInfoRefreshed(java.lang.Object id, MediaSource mediaSource, Timeline timeline)
Called when the source info of a child source has been refreshed. |
protected abstract void | prepareSourceInternal(TransferListener mediaTransferListener)
Starts source preparation and enables the source, see MediaSource.prepareSource(MediaSource.MediaSourceCaller, TransferListener, PlayerId). |
public void | releasePeriod(MediaPeriod mediaPeriod)
|
protected abstract void | releaseSourceInternal()
Releases the source, see MediaSource.releaseSource(MediaSource.MediaSourceCaller). |
from CompositeMediaSource<T> | disableChildSource, disableInternal, enableChildSource, enableInternal, getMediaPeriodIdForChildMediaPeriodId, getMediaTimeForChildMediaTime, getWindowIndexForChildWindowIndex, prepareChildSource, releaseChildSource |
from BaseMediaSource | addDrmEventListener, addEventListener, createDrmEventDispatcher, createDrmEventDispatcher, createEventDispatcher, createEventDispatcher, createEventDispatcher, disable, enable, getPlayerId, isEnabled, prepareSource, refreshSourceInfo, releaseSource, removeDrmEventListener, removeEventListener |
from java.lang.Object | clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructors
public
ClippingMediaSource(
MediaSource mediaSource, long startPositionUs, long endPositionUs)
Creates a new clipping source that wraps the specified source and provides samples between the
specified start and end position.
Parameters:
mediaSource: The single-period source to wrap.
startPositionUs: The start position within mediaSource's window at which to start
providing samples, in microseconds.
endPositionUs: The end position within mediaSource's window at which to stop
providing samples, in microseconds. Specify C.TIME_END_OF_SOURCE to provide samples
from the specified start point up to the end of the source. Specifying a position that
exceeds the mediaSource's duration will also result in the end of the source not
being clipped.
public
ClippingMediaSource(
MediaSource mediaSource, long durationUs)
Creates a new clipping source that wraps the specified source and provides samples from the
default position for the specified duration.
Parameters:
mediaSource: The single-period source to wrap.
durationUs: The duration from the default position in the window in mediaSource's
timeline at which to stop providing samples. Specifying a duration that exceeds the mediaSource's duration will result in the end of the source not being clipped.
public
ClippingMediaSource(
MediaSource mediaSource, long startPositionUs, long endPositionUs, boolean enableInitialDiscontinuity, boolean allowDynamicClippingUpdates, boolean relativeToDefaultPosition)
Creates a new clipping source that wraps the specified source.
If the start point is guaranteed to be a key frame, pass false to enableInitialPositionDiscontinuity to suppress an initial discontinuity when a period is first
read from.
For live streams, if the clipping positions should move with the live window, pass true to allowDynamicClippingUpdates. Otherwise, the live stream ends when the playback
reaches endPositionUs in the last reported live window at the time a media period was
created.
Parameters:
mediaSource: The single-period source to wrap.
startPositionUs: The start position at which to start providing samples, in microseconds.
If relativeToDefaultPosition is false, this position is relative to the
start of the window in mediaSource's timeline. If relativeToDefaultPosition
is true, this position is relative to the default position in the window in mediaSource's timeline.
endPositionUs: The end position at which to stop providing samples, in microseconds.
Specify C.TIME_END_OF_SOURCE to provide samples from the specified start point up
to the end of the source. Specifying a position that exceeds the mediaSource's
duration will also result in the end of the source not being clipped. If relativeToDefaultPosition is false, the specified position is relative to the
start of the window in mediaSource's timeline. If relativeToDefaultPosition
is true, this position is relative to the default position in the window in mediaSource's timeline.
enableInitialDiscontinuity: Whether the initial discontinuity should be enabled.
allowDynamicClippingUpdates: Whether the clipping of active media periods moves with a
live window. If false, playback ends when it reaches endPositionUs in the
last reported live window at the time a media period was created.
relativeToDefaultPosition: Whether startPositionUs and endPositionUs are
relative to the default position in the window in mediaSource's timeline.
Methods
protected abstract void
prepareSourceInternal(
TransferListener mediaTransferListener)
Starts source preparation and enables the source, see MediaSource.prepareSource(MediaSource.MediaSourceCaller, TransferListener, PlayerId). This method is called at most once until the next call to BaseMediaSource.releaseSourceInternal().
Parameters:
mediaTransferListener: The transfer listener which should be informed of any media data
transfers. May be null if no listener is available. Note that this listener should usually
be only informed of transfers related to the media loads and not of auxiliary loads for
manifests and other data.
public void
maybeThrowSourceInfoRefreshError()
protected abstract void
releaseSourceInternal()
Releases the source, see MediaSource.releaseSource(MediaSource.MediaSourceCaller). This method is called
exactly once after each call to BaseMediaSource.prepareSourceInternal(TransferListener).
protected abstract void
onChildSourceInfoRefreshed(java.lang.Object id,
MediaSource mediaSource,
Timeline timeline)
Called when the source info of a child source has been refreshed.
Parameters:
id: The unique id used to prepare the child source.
mediaSource: The child source whose source info has been refreshed.
timeline: The timeline of the child source.
Source
/*
* Copyright (C) 2016 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 static java.lang.Math.max;
import static java.lang.Math.min;
import static java.lang.annotation.ElementType.TYPE_USE;
import androidx.annotation.IntDef;
import androidx.annotation.Nullable;
import androidx.media3.common.C;
import androidx.media3.common.MediaItem;
import androidx.media3.common.Timeline;
import androidx.media3.common.util.Assertions;
import androidx.media3.common.util.UnstableApi;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.TransferListener;
import androidx.media3.exoplayer.upstream.Allocator;
import java.io.IOException;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.ArrayList;
/**
* {@link MediaSource} that wraps a source and clips its timeline based on specified start/end
* positions. The wrapped source must consist of a single period.
*/
@UnstableApi
public final class ClippingMediaSource extends CompositeMediaSource<Void> {
/** Thrown when a {@link ClippingMediaSource} cannot clip its wrapped source. */
public static final class IllegalClippingException extends IOException {
/**
* The reason clipping failed. One of {@link #REASON_INVALID_PERIOD_COUNT}, {@link
* #REASON_NOT_SEEKABLE_TO_START} or {@link #REASON_START_EXCEEDS_END}.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(TYPE_USE)
@IntDef({REASON_INVALID_PERIOD_COUNT, REASON_NOT_SEEKABLE_TO_START, REASON_START_EXCEEDS_END})
public @interface Reason {}
/** The wrapped source doesn't consist of a single period. */
public static final int REASON_INVALID_PERIOD_COUNT = 0;
/** The wrapped source is not seekable and a non-zero clipping start position was specified. */
public static final int REASON_NOT_SEEKABLE_TO_START = 1;
/** The wrapped source ends before the specified clipping start position. */
public static final int REASON_START_EXCEEDS_END = 2;
/** The reason clipping failed. */
public final @Reason int reason;
/** @param reason The reason clipping failed. */
public IllegalClippingException(@Reason int reason) {
super("Illegal clipping: " + getReasonDescription(reason));
this.reason = reason;
}
private static String getReasonDescription(@Reason int reason) {
switch (reason) {
case REASON_INVALID_PERIOD_COUNT:
return "invalid period count";
case REASON_NOT_SEEKABLE_TO_START:
return "not seekable to start";
case REASON_START_EXCEEDS_END:
return "start exceeds end";
default:
return "unknown";
}
}
}
private final MediaSource mediaSource;
private final long startUs;
private final long endUs;
private final boolean enableInitialDiscontinuity;
private final boolean allowDynamicClippingUpdates;
private final boolean relativeToDefaultPosition;
private final ArrayList<ClippingMediaPeriod> mediaPeriods;
private final Timeline.Window window;
@Nullable private ClippingTimeline clippingTimeline;
@Nullable private IllegalClippingException clippingError;
private long periodStartUs;
private long periodEndUs;
/**
* Creates a new clipping source that wraps the specified source and provides samples between the
* specified start and end position.
*
* @param mediaSource The single-period source to wrap.
* @param startPositionUs The start position within {@code mediaSource}'s window at which to start
* providing samples, in microseconds.
* @param endPositionUs The end position within {@code mediaSource}'s window at which to stop
* providing samples, in microseconds. Specify {@link C#TIME_END_OF_SOURCE} to provide samples
* from the specified start point up to the end of the source. Specifying a position that
* exceeds the {@code mediaSource}'s duration will also result in the end of the source not
* being clipped.
*/
public ClippingMediaSource(MediaSource mediaSource, long startPositionUs, long endPositionUs) {
this(
mediaSource,
startPositionUs,
endPositionUs,
/* enableInitialDiscontinuity= */ true,
/* allowDynamicClippingUpdates= */ false,
/* relativeToDefaultPosition= */ false);
}
/**
* Creates a new clipping source that wraps the specified source and provides samples from the
* default position for the specified duration.
*
* @param mediaSource The single-period source to wrap.
* @param durationUs The duration from the default position in the window in {@code mediaSource}'s
* timeline at which to stop providing samples. Specifying a duration that exceeds the {@code
* mediaSource}'s duration will result in the end of the source not being clipped.
*/
public ClippingMediaSource(MediaSource mediaSource, long durationUs) {
this(
mediaSource,
/* startPositionUs= */ 0,
/* endPositionUs= */ durationUs,
/* enableInitialDiscontinuity= */ true,
/* allowDynamicClippingUpdates= */ false,
/* relativeToDefaultPosition= */ true);
}
/**
* Creates a new clipping source that wraps the specified source.
*
* <p>If the start point is guaranteed to be a key frame, pass {@code false} to {@code
* enableInitialPositionDiscontinuity} to suppress an initial discontinuity when a period is first
* read from.
*
* <p>For live streams, if the clipping positions should move with the live window, pass {@code
* true} to {@code allowDynamicClippingUpdates}. Otherwise, the live stream ends when the playback
* reaches {@code endPositionUs} in the last reported live window at the time a media period was
* created.
*
* @param mediaSource The single-period source to wrap.
* @param startPositionUs The start position at which to start providing samples, in microseconds.
* If {@code relativeToDefaultPosition} is {@code false}, this position is relative to the
* start of the window in {@code mediaSource}'s timeline. If {@code relativeToDefaultPosition}
* is {@code true}, this position is relative to the default position in the window in {@code
* mediaSource}'s timeline.
* @param endPositionUs The end position at which to stop providing samples, in microseconds.
* Specify {@link C#TIME_END_OF_SOURCE} to provide samples from the specified start point up
* to the end of the source. Specifying a position that exceeds the {@code mediaSource}'s
* duration will also result in the end of the source not being clipped. If {@code
* relativeToDefaultPosition} is {@code false}, the specified position is relative to the
* start of the window in {@code mediaSource}'s timeline. If {@code relativeToDefaultPosition}
* is {@code true}, this position is relative to the default position in the window in {@code
* mediaSource}'s timeline.
* @param enableInitialDiscontinuity Whether the initial discontinuity should be enabled.
* @param allowDynamicClippingUpdates Whether the clipping of active media periods moves with a
* live window. If {@code false}, playback ends when it reaches {@code endPositionUs} in the
* last reported live window at the time a media period was created.
* @param relativeToDefaultPosition Whether {@code startPositionUs} and {@code endPositionUs} are
* relative to the default position in the window in {@code mediaSource}'s timeline.
*/
public ClippingMediaSource(
MediaSource mediaSource,
long startPositionUs,
long endPositionUs,
boolean enableInitialDiscontinuity,
boolean allowDynamicClippingUpdates,
boolean relativeToDefaultPosition) {
Assertions.checkArgument(startPositionUs >= 0);
this.mediaSource = Assertions.checkNotNull(mediaSource);
startUs = startPositionUs;
endUs = endPositionUs;
this.enableInitialDiscontinuity = enableInitialDiscontinuity;
this.allowDynamicClippingUpdates = allowDynamicClippingUpdates;
this.relativeToDefaultPosition = relativeToDefaultPosition;
mediaPeriods = new ArrayList<>();
window = new Timeline.Window();
}
@Override
public MediaItem getMediaItem() {
return mediaSource.getMediaItem();
}
@Override
protected void prepareSourceInternal(@Nullable TransferListener mediaTransferListener) {
super.prepareSourceInternal(mediaTransferListener);
prepareChildSource(/* id= */ null, mediaSource);
}
@Override
public void maybeThrowSourceInfoRefreshError() throws IOException {
if (clippingError != null) {
throw clippingError;
}
super.maybeThrowSourceInfoRefreshError();
}
@Override
public MediaPeriod createPeriod(MediaPeriodId id, Allocator allocator, long startPositionUs) {
ClippingMediaPeriod mediaPeriod =
new ClippingMediaPeriod(
mediaSource.createPeriod(id, allocator, startPositionUs),
enableInitialDiscontinuity,
periodStartUs,
periodEndUs);
mediaPeriods.add(mediaPeriod);
return mediaPeriod;
}
@Override
public void releasePeriod(MediaPeriod mediaPeriod) {
Assertions.checkState(mediaPeriods.remove(mediaPeriod));
mediaSource.releasePeriod(((ClippingMediaPeriod) mediaPeriod).mediaPeriod);
if (mediaPeriods.isEmpty() && !allowDynamicClippingUpdates) {
refreshClippedTimeline(Assertions.checkNotNull(clippingTimeline).timeline);
}
}
@Override
protected void releaseSourceInternal() {
super.releaseSourceInternal();
clippingError = null;
clippingTimeline = null;
}
@Override
protected void onChildSourceInfoRefreshed(Void id, MediaSource mediaSource, Timeline timeline) {
if (clippingError != null) {
return;
}
refreshClippedTimeline(timeline);
}
private void refreshClippedTimeline(Timeline timeline) {
long windowStartUs;
long windowEndUs;
timeline.getWindow(/* windowIndex= */ 0, window);
long windowPositionInPeriodUs = window.getPositionInFirstPeriodUs();
if (clippingTimeline == null || mediaPeriods.isEmpty() || allowDynamicClippingUpdates) {
windowStartUs = startUs;
windowEndUs = endUs;
if (relativeToDefaultPosition) {
long windowDefaultPositionUs = window.getDefaultPositionUs();
windowStartUs += windowDefaultPositionUs;
windowEndUs += windowDefaultPositionUs;
}
periodStartUs = windowPositionInPeriodUs + windowStartUs;
periodEndUs =
endUs == C.TIME_END_OF_SOURCE
? C.TIME_END_OF_SOURCE
: windowPositionInPeriodUs + windowEndUs;
int count = mediaPeriods.size();
for (int i = 0; i < count; i++) {
mediaPeriods.get(i).updateClipping(periodStartUs, periodEndUs);
}
} else {
// Keep window fixed at previous period position.
windowStartUs = periodStartUs - windowPositionInPeriodUs;
windowEndUs =
endUs == C.TIME_END_OF_SOURCE
? C.TIME_END_OF_SOURCE
: periodEndUs - windowPositionInPeriodUs;
}
try {
clippingTimeline = new ClippingTimeline(timeline, windowStartUs, windowEndUs);
} catch (IllegalClippingException e) {
clippingError = e;
// The clipping error won't be propagated while we have existing MediaPeriods. Setting the
// error at the MediaPeriods ensures it will be thrown as soon as possible.
for (int i = 0; i < mediaPeriods.size(); i++) {
mediaPeriods.get(i).setClippingError(clippingError);
}
return;
}
refreshSourceInfo(clippingTimeline);
}
/** Provides a clipped view of a specified timeline. */
private static final class ClippingTimeline extends ForwardingTimeline {
private final long startUs;
private final long endUs;
private final long durationUs;
private final boolean isDynamic;
/**
* Creates a new clipping timeline that wraps the specified timeline.
*
* @param timeline The timeline to clip.
* @param startUs The number of microseconds to clip from the start of {@code timeline}.
* @param endUs The end position in microseconds for the clipped timeline relative to the start
* of {@code timeline}, or {@link C#TIME_END_OF_SOURCE} to clip no samples from the end.
* @throws IllegalClippingException If the timeline could not be clipped.
*/
public ClippingTimeline(Timeline timeline, long startUs, long endUs)
throws IllegalClippingException {
super(timeline);
if (timeline.getPeriodCount() != 1) {
throw new IllegalClippingException(IllegalClippingException.REASON_INVALID_PERIOD_COUNT);
}
Window window = timeline.getWindow(0, new Window());
startUs = max(0, startUs);
if (!window.isPlaceholder && startUs != 0 && !window.isSeekable) {
throw new IllegalClippingException(IllegalClippingException.REASON_NOT_SEEKABLE_TO_START);
}
long resolvedEndUs = endUs == C.TIME_END_OF_SOURCE ? window.durationUs : max(0, endUs);
if (window.durationUs != C.TIME_UNSET) {
if (resolvedEndUs > window.durationUs) {
resolvedEndUs = window.durationUs;
}
if (startUs > resolvedEndUs) {
throw new IllegalClippingException(IllegalClippingException.REASON_START_EXCEEDS_END);
}
}
this.startUs = startUs;
this.endUs = resolvedEndUs;
durationUs = resolvedEndUs == C.TIME_UNSET ? C.TIME_UNSET : (resolvedEndUs - startUs);
isDynamic =
window.isDynamic
&& (resolvedEndUs == C.TIME_UNSET
|| (window.durationUs != C.TIME_UNSET && resolvedEndUs == window.durationUs));
}
@Override
public Window getWindow(int windowIndex, Window window, long defaultPositionProjectionUs) {
timeline.getWindow(/* windowIndex= */ 0, window, /* defaultPositionProjectionUs= */ 0);
window.positionInFirstPeriodUs += startUs;
window.durationUs = durationUs;
window.isDynamic = isDynamic;
if (window.defaultPositionUs != C.TIME_UNSET) {
window.defaultPositionUs = max(window.defaultPositionUs, startUs);
window.defaultPositionUs =
endUs == C.TIME_UNSET ? window.defaultPositionUs : min(window.defaultPositionUs, endUs);
window.defaultPositionUs -= startUs;
}
long startMs = Util.usToMs(startUs);
if (window.presentationStartTimeMs != C.TIME_UNSET) {
window.presentationStartTimeMs += startMs;
}
if (window.windowStartTimeMs != C.TIME_UNSET) {
window.windowStartTimeMs += startMs;
}
return window;
}
@Override
public Period getPeriod(int periodIndex, Period period, boolean setIds) {
timeline.getPeriod(/* periodIndex= */ 0, period, setIds);
long positionInClippedWindowUs = period.getPositionInWindowUs() - startUs;
long periodDurationUs =
durationUs == C.TIME_UNSET ? C.TIME_UNSET : durationUs - positionInClippedWindowUs;
return period.set(
period.id, period.uid, /* windowIndex= */ 0, periodDurationUs, positionInClippedWindowUs);
}
}
}