ExoPlayer.Builder


public final class ExoPlayer.Builder


A builder for ExoPlayer instances.

See Builder for the list of default values.

Summary

Public constructors

Builder(Context context)

Creates a builder.

@UnstableApi
Builder(Context context, MediaSource.Factory mediaSourceFactory)

Creates a builder with a custom MediaSource.Factory.

@UnstableApi
Builder(Context context, RenderersFactory renderersFactory)

Creates a builder with a custom RenderersFactory.

@UnstableApi
Builder(
    Context context,
    RenderersFactory renderersFactory,
    MediaSource.Factory mediaSourceFactory
)

Creates a builder with a custom RenderersFactory and MediaSource.Factory.

@UnstableApi
Builder(
    Context context,
    RenderersFactory renderersFactory,
    MediaSource.Factory mediaSourceFactory,
    TrackSelector trackSelector,
    LoadControl loadControl,
    BandwidthMeter bandwidthMeter,
    AnalyticsCollector analyticsCollector
)

Creates a builder with the specified custom components.

Public methods

ExoPlayer

Builds an ExoPlayer instance.

ExoPlayer.Builder

Sets whether dynamic scheduling is enabled.

ExoPlayer.Builder

Sets a limit on the time a call to setForegroundMode can spend.

ExoPlayer.Builder

Sets the AnalyticsCollector that will collect and forward all player events.

ExoPlayer.Builder
@CanIgnoreReturnValue
setAudioAttributes(
    AudioAttributes audioAttributes,
    boolean handleAudioFocus
)

Sets AudioAttributes that will be used by the player and whether to handle audio focus.

ExoPlayer.Builder

Sets the BandwidthMeter that will be used by the player.

ExoPlayer.Builder

Sets the Clock that will be used by the player.

ExoPlayer.Builder

Sets a timeout for detaching a surface from the player.

ExoPlayer.Builder

Sets whether the player is allowed to set, increase, decrease or mute device volume.

ExoPlayer.Builder
@CanIgnoreReturnValue
setHandleAudioBecomingNoisy(boolean handleAudioBecomingNoisy)

Sets whether the player should pause automatically when audio is rerouted from a headset to device speakers.

ExoPlayer.Builder

Sets the LivePlaybackSpeedControl that will control the playback speed when playing live streams, in order to maintain a steady target offset from the live stream edge.

ExoPlayer.Builder

Sets the LoadControl that will be used by the player.

ExoPlayer.Builder

Sets the Looper that must be used for all calls to the player and that is used to call listeners on.

ExoPlayer.Builder
@CanIgnoreReturnValue
@UnstableApi
setMaxSeekToPreviousPositionMs(
    @IntRange(from = 0) long maxSeekToPreviousPositionMs
)

Sets the maximum position for which seekToPrevious seeks to the previous .

ExoPlayer.Builder

Sets the MediaSource.Factory that will be used by the player.

ExoPlayer.Builder

Sets the player name that is included in the PlayerId for informational purpose to recognize the player by its PlayerId.

ExoPlayer.Builder

Sets whether to pause playback at the end of each media item.

ExoPlayer.Builder

Sets the Looper that will be used for playback.

ExoPlayer.Builder

Sets the C.Priority for this player.

ExoPlayer.Builder

Sets an PriorityTaskManager that will be used by the player.

ExoPlayer.Builder

Sets a timeout for calls to release and setForegroundMode.

ExoPlayer.Builder

Sets the RenderersFactory that will be used by the player.

ExoPlayer.Builder
@CanIgnoreReturnValue
@UnstableApi
setSeekBackIncrementMs(@IntRange(from = 1) long seekBackIncrementMs)

Sets the seekBack increment.

ExoPlayer.Builder
@CanIgnoreReturnValue
@UnstableApi
setSeekForwardIncrementMs(@IntRange(from = 1) long seekForwardIncrementMs)

Sets the seekForward increment.

ExoPlayer.Builder

Sets the parameters that control how seek operations are performed.

ExoPlayer.Builder

Sets whether silences silences in the audio stream is enabled.

ExoPlayer.Builder
@CanIgnoreReturnValue
@UnstableApi
setSuppressPlaybackOnUnsuitableOutput(
    boolean suppressPlaybackOnUnsuitableOutput
)

Sets whether the player should suppress playback that is attempted on an unsuitable output.

ExoPlayer.Builder

Sets the TrackSelector that will be used by the player.

ExoPlayer.Builder

Sets whether media sources should be initialized lazily.

ExoPlayer.Builder

Sets whether the player reports diagnostics data to the Android platform.

ExoPlayer.Builder

Sets a C.VideoChangeFrameRateStrategy that will be used by the player when provided with a video output Surface.

ExoPlayer.Builder

Sets the C.VideoScalingMode that will be used by the player.

ExoPlayer.Builder

Sets the C.WakeMode that will be used by the player.

Public constructors

Builder

public Builder(Context context)

Creates a builder.

Use Builder, Builder or Builder instead, if you intend to provide a custom RenderersFactory, or DefaultMediaSourceFactory. This is to ensure that ProGuard or R8 can remove ExoPlayer's DefaultRenderersFactory, DefaultExtractorsFactory and DefaultMediaSourceFactory from the APK.

The builder uses the following default values:

Parameters
Context context

A Context.

Builder

@UnstableApi
public Builder(Context context, MediaSource.Factory mediaSourceFactory)

Creates a builder with a custom MediaSource.Factory.

See Builder for a list of default values.

Note that this constructor is only useful to try and ensure that ExoPlayer's (and therefore DefaultExtractorsFactory) can be removed by ProGuard or R8.

Parameters
Context context

A Context.

MediaSource.Factory mediaSourceFactory

A factory for creating a MediaSource from a .

Builder

@UnstableApi
public Builder(Context context, RenderersFactory renderersFactory)

Creates a builder with a custom RenderersFactory.

See Builder for a list of default values.

Note that this constructor is only useful to try and ensure that ExoPlayer's can be removed by ProGuard or R8.

Parameters
Context context

A Context.

RenderersFactory renderersFactory

A factory for creating Renderers to be used by the player.

Builder

@UnstableApi
public Builder(
    Context context,
    RenderersFactory renderersFactory,
    MediaSource.Factory mediaSourceFactory
)

Creates a builder with a custom RenderersFactory and MediaSource.Factory.

See Builder for a list of default values.

Note that this constructor is only useful to try and ensure that ExoPlayer's , DefaultMediaSourceFactory (and therefore ) can be removed by ProGuard or R8.

Parameters
Context context

A Context.

RenderersFactory renderersFactory

A factory for creating Renderers to be used by the player.

MediaSource.Factory mediaSourceFactory

A factory for creating a MediaSource from a .

Builder

@UnstableApi
public Builder(
    Context context,
    RenderersFactory renderersFactory,
    MediaSource.Factory mediaSourceFactory,
    TrackSelector trackSelector,
    LoadControl loadControl,
    BandwidthMeter bandwidthMeter,
    AnalyticsCollector analyticsCollector
)

Creates a builder with the specified custom components.

Note that this constructor is only useful to try and ensure that ExoPlayer's default components can be removed by ProGuard or R8.

Parameters
Context context

A Context.

RenderersFactory renderersFactory

A factory for creating Renderers to be used by the player.

MediaSource.Factory mediaSourceFactory

A MediaSource.Factory.

TrackSelector trackSelector

A TrackSelector.

LoadControl loadControl

A LoadControl.

BandwidthMeter bandwidthMeter

A BandwidthMeter.

AnalyticsCollector analyticsCollector

An AnalyticsCollector.

Public methods

build

public ExoPlayer build()

Builds an ExoPlayer instance.

Throws
java.lang.IllegalStateException

If this method has already been called.

experimentalSetDynamicSchedulingEnabled

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder experimentalSetDynamicSchedulingEnabled(
    boolean dynamicSchedulingEnabled
)

Sets whether dynamic scheduling is enabled.

If enabled, ExoPlayer's playback loop will run as rarely as possible by scheduling work for when Renderer progress can be made.

This method is experimental, and will be renamed or removed in a future release.

Parameters
boolean dynamicSchedulingEnabled

Whether to enable dynamic scheduling.

experimentalSetForegroundModeTimeoutMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder experimentalSetForegroundModeTimeoutMs(long timeoutMs)

Sets a limit on the time a call to setForegroundMode can spend. If a call to setForegroundMode takes more than timeoutMs milliseconds to complete, the player will raise an error via onPlayerError.

This method is experimental, and will be renamed or removed in a future release.

Parameters
long timeoutMs

The time limit in milliseconds.

setAnalyticsCollector

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setAnalyticsCollector(AnalyticsCollector analyticsCollector)

Sets the AnalyticsCollector that will collect and forward all player events.

Parameters
AnalyticsCollector analyticsCollector

An AnalyticsCollector.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setAudioAttributes

@CanIgnoreReturnValue
public ExoPlayer.Builder setAudioAttributes(
    AudioAttributes audioAttributes,
    boolean handleAudioFocus
)

Sets AudioAttributes that will be used by the player and whether to handle audio focus.

If audio focus should be handled, the usage must be USAGE_MEDIA or USAGE_GAME. Other usages will throw an .

Parameters
AudioAttributes audioAttributes

AudioAttributes.

boolean handleAudioFocus

Whether the player should handle audio focus.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setBandwidthMeter

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setBandwidthMeter(BandwidthMeter bandwidthMeter)

Sets the BandwidthMeter that will be used by the player.

Parameters
BandwidthMeter bandwidthMeter

A BandwidthMeter.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setClock

@CanIgnoreReturnValue
@UnstableApi
@VisibleForTesting
public ExoPlayer.Builder setClock(Clock clock)

Sets the Clock that will be used by the player. Should only be set for testing purposes.

Parameters
Clock clock

A Clock.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setDetachSurfaceTimeoutMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setDetachSurfaceTimeoutMs(long detachSurfaceTimeoutMs)

Sets a timeout for detaching a surface from the player.

If detaching a surface or replacing a surface takes more than detachSurfaceTimeoutMs to complete, the player will report an error via onPlayerError.

Parameters
long detachSurfaceTimeoutMs

The timeout for detaching a surface, in milliseconds.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setDeviceVolumeControlEnabled

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setDeviceVolumeControlEnabled(boolean deviceVolumeControlEnabled)

Sets whether the player is allowed to set, increase, decrease or mute device volume.

Parameters
boolean deviceVolumeControlEnabled

Whether controlling device volume is enabled.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setHandleAudioBecomingNoisy

@CanIgnoreReturnValue
public ExoPlayer.Builder setHandleAudioBecomingNoisy(boolean handleAudioBecomingNoisy)

Sets whether the player should pause automatically when audio is rerouted from a headset to device speakers. See the audio becoming noisy documentation for more information.

Parameters
boolean handleAudioBecomingNoisy

Whether the player should pause automatically when audio is rerouted from a headset to device speakers.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setLivePlaybackSpeedControl

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setLivePlaybackSpeedControl(
    LivePlaybackSpeedControl livePlaybackSpeedControl
)

Sets the LivePlaybackSpeedControl that will control the playback speed when playing live streams, in order to maintain a steady target offset from the live stream edge.

Parameters
LivePlaybackSpeedControl livePlaybackSpeedControl

The LivePlaybackSpeedControl.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setLoadControl

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setLoadControl(LoadControl loadControl)

Sets the LoadControl that will be used by the player.

Parameters
LoadControl loadControl

A LoadControl.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setLooper

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setLooper(Looper looper)

Sets the Looper that must be used for all calls to the player and that is used to call listeners on.

Parameters
Looper looper

A Looper.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setMaxSeekToPreviousPositionMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setMaxSeekToPreviousPositionMs(
    @IntRange(from = 0) long maxSeekToPreviousPositionMs
)

Sets the maximum position for which seekToPrevious seeks to the previous .

Parameters
@IntRange(from = 0) long maxSeekToPreviousPositionMs

The maximum position, in milliseconds.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalArgumentException

If maxSeekToPreviousPositionMs is negative.

java.lang.IllegalStateException

If build has already been called.

setMediaSourceFactory

@CanIgnoreReturnValue
public ExoPlayer.Builder setMediaSourceFactory(MediaSource.Factory mediaSourceFactory)

Sets the MediaSource.Factory that will be used by the player.

Parameters
MediaSource.Factory mediaSourceFactory

A MediaSource.Factory.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setName

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setName(String playerName)

Sets the player name that is included in the PlayerId for informational purpose to recognize the player by its PlayerId.

The default is an empty string.

Parameters
String playerName

A name for the player in the PlayerId.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setPauseAtEndOfMediaItems

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setPauseAtEndOfMediaItems(boolean pauseAtEndOfMediaItems)

Sets whether to pause playback at the end of each media item.

This means the player will pause at the end of each window in the current timeline. Listeners will be informed by a call to onPlayWhenReadyChanged with the reason PLAY_WHEN_READY_CHANGE_REASON_END_OF_MEDIA_ITEM when this happens.

Parameters
boolean pauseAtEndOfMediaItems

Whether to pause playback at the end of each media item.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setPlaybackLooper

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setPlaybackLooper(Looper playbackLooper)

Sets the Looper that will be used for playback.

The backing thread should run with priority THREAD_PRIORITY_AUDIO and should handle messages within 10ms.

Parameters
Looper playbackLooper

A Looper.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setPriority

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setPriority(@C.Priority int priority)

Sets the C.Priority for this player.

The priority may influence resource allocation between multiple players or other components running in the same app.

This priority is used for the PriorityTaskManager, if set.

Parameters
@C.Priority int priority

The C.Priority.

setPriorityTaskManager

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setPriorityTaskManager(
    @Nullable PriorityTaskManager priorityTaskManager
)

Sets an PriorityTaskManager that will be used by the player.

The priority set via setPriority (or by default) will be set while the player is loading.

Parameters
@Nullable PriorityTaskManager priorityTaskManager

A PriorityTaskManager, or null to not use one.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setReleaseTimeoutMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setReleaseTimeoutMs(long releaseTimeoutMs)

Sets a timeout for calls to release and setForegroundMode.

If a call to release or setForegroundMode takes more than timeoutMs to complete, the player will report an error via onPlayerError.

Parameters
long releaseTimeoutMs

The release timeout, in milliseconds.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setRenderersFactory

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setRenderersFactory(RenderersFactory renderersFactory)

Sets the RenderersFactory that will be used by the player.

Parameters
RenderersFactory renderersFactory

A RenderersFactory.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setSeekBackIncrementMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setSeekBackIncrementMs(@IntRange(from = 1) long seekBackIncrementMs)

Sets the seekBack increment.

Parameters
@IntRange(from = 1) long seekBackIncrementMs

The seek back increment, in milliseconds.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalArgumentException

If seekBackIncrementMs is non-positive.

java.lang.IllegalStateException

If build has already been called.

setSeekForwardIncrementMs

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setSeekForwardIncrementMs(@IntRange(from = 1) long seekForwardIncrementMs)

Sets the seekForward increment.

Parameters
@IntRange(from = 1) long seekForwardIncrementMs

The seek forward increment, in milliseconds.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalArgumentException

If seekForwardIncrementMs is non-positive.

java.lang.IllegalStateException

If build has already been called.

setSeekParameters

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setSeekParameters(SeekParameters seekParameters)

Sets the parameters that control how seek operations are performed.

Parameters
SeekParameters seekParameters

The SeekParameters.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setSkipSilenceEnabled

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setSkipSilenceEnabled(boolean skipSilenceEnabled)

Sets whether silences silences in the audio stream is enabled.

Parameters
boolean skipSilenceEnabled

Whether skipping silences is enabled.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setSuppressPlaybackOnUnsuitableOutput

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setSuppressPlaybackOnUnsuitableOutput(
    boolean suppressPlaybackOnUnsuitableOutput
)

Sets whether the player should suppress playback that is attempted on an unsuitable output. An example of an unsuitable audio output is the built-in speaker on a Wear OS device (unless it is explicitly selected by the user).

If called with suppressPlaybackOnUnsuitableOutput = true, then a playback attempt on an unsuitable audio output will result in calls to onPlaybackSuppressionReasonChanged with the value PLAYBACK_SUPPRESSION_REASON_UNSUITABLE_AUDIO_OUTPUT.

Callers of this may also want to enable setHandleAudioBecomingNoisy to prevent playback from continuing on the built-in speaker when a headset is disconnected.

Parameters
boolean suppressPlaybackOnUnsuitableOutput

Whether the player should suppress the playback when it is attempted on an unsuitable output.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setTrackSelector

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setTrackSelector(TrackSelector trackSelector)

Sets the TrackSelector that will be used by the player.

Parameters
TrackSelector trackSelector

A TrackSelector.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setUseLazyPreparation

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setUseLazyPreparation(boolean useLazyPreparation)

Sets whether media sources should be initialized lazily.

If false, all initial preparation steps (e.g., manifest loads) happen immediately. If true, these initial preparations are triggered only when the player starts buffering the media.

Parameters
boolean useLazyPreparation

Whether to use lazy preparation.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setUsePlatformDiagnostics

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setUsePlatformDiagnostics(boolean usePlatformDiagnostics)

Sets whether the player reports diagnostics data to the Android platform.

If enabled, the player will use the android.media.metrics.MediaMetricsManager to create a android.media.metrics.PlaybackSession and forward playback events and performance data to this session. This helps to provide system performance and debugging information for media playback on the device. This data may also be collected by Google if sharing usage and diagnostics data is enabled by the user of the device.

Parameters
boolean usePlatformDiagnostics

Whether the player reports diagnostics data to the Android platform.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setVideoChangeFrameRateStrategy

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setVideoChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int videoChangeFrameRateStrategy
)

Sets a C.VideoChangeFrameRateStrategy that will be used by the player when provided with a video output Surface.

The strategy only applies if a MediaCodec-based video Renderer is enabled. Applications wishing to use CHANGE_FRAME_RATE_ALWAYS should set the mode to VIDEO_CHANGE_FRAME_RATE_STRATEGY_OFF to disable calls to setFrameRate from ExoPlayer, and should then call setFrameRate directly from application code.

Parameters
@C.VideoChangeFrameRateStrategy int videoChangeFrameRateStrategy

A C.VideoChangeFrameRateStrategy.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setVideoScalingMode

@CanIgnoreReturnValue
@UnstableApi
public ExoPlayer.Builder setVideoScalingMode(@C.VideoScalingMode int videoScalingMode)

Sets the C.VideoScalingMode that will be used by the player.

The scaling mode only applies if a MediaCodec-based video Renderer is enabled and if the output surface is owned by a SurfaceView.

Parameters
@C.VideoScalingMode int videoScalingMode

A C.VideoScalingMode.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.

setWakeMode

@CanIgnoreReturnValue
public ExoPlayer.Builder setWakeMode(@C.WakeMode int wakeMode)

Sets the C.WakeMode that will be used by the player.

Enabling this feature requires the WAKE_LOCK permission. It should be used together with a foreground android.app.Service for use cases where playback occurs and the screen is off (e.g. background audio playback). It is not useful when the screen will be kept on during playback (e.g. foreground video playback).

When enabled, the locks (android.os.PowerManager.WakeLock / ) will be held whenever the player is in the STATE_READY or STATE_BUFFERING states with playWhenReady = true. The locks held depend on the specified C.WakeMode.

Parameters
@C.WakeMode int wakeMode

A C.WakeMode.

Returns
ExoPlayer.Builder

This builder.

Throws
java.lang.IllegalStateException

If build has already been called.