public final class

ExoPlayer.Builder

extends java.lang.Object

 java.lang.Object

↳androidx.media3.exoplayer.ExoPlayer.Builder

Overview

A builder for ExoPlayer instances.

See ExoPlayer.Builder.Builder(Context) for the list of default values.

Summary

Constructors
publicBuilder(Context context)

Creates a builder.

publicBuilder(Context context, MediaSource.Factory mediaSourceFactory)

Creates a builder with a custom .

publicBuilder(Context context, RenderersFactory renderersFactory)

Creates a builder with a custom RenderersFactory.

publicBuilder(Context context, RenderersFactory renderersFactory, MediaSource.Factory mediaSourceFactory)

Creates a builder with a custom RenderersFactory and .

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

Creates a builder with the specified custom components.

Methods
public ExoPlayerbuild()

Builds an ExoPlayer instance.

public ExoPlayer.BuilderexperimentalSetDynamicSchedulingEnabled(boolean dynamicSchedulingEnabled)

Sets whether dynamic scheduling is enabled.

public ExoPlayer.BuilderexperimentalSetForegroundModeTimeoutMs(long timeoutMs)

Sets a limit on the time a call to ExoPlayer.setForegroundMode(boolean) can spend.

public ExoPlayer.BuildersetAnalyticsCollector(AnalyticsCollector analyticsCollector)

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

public ExoPlayer.BuildersetAudioAttributes(AudioAttributes audioAttributes, boolean handleAudioFocus)

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

public ExoPlayer.BuildersetBandwidthMeter(BandwidthMeter bandwidthMeter)

Sets the BandwidthMeter that will be used by the player.

public ExoPlayer.BuildersetClock(Clock clock)

Sets the Clock that will be used by the player.

public ExoPlayer.BuildersetDetachSurfaceTimeoutMs(long detachSurfaceTimeoutMs)

Sets a timeout for detaching a surface from the player.

public ExoPlayer.BuildersetDeviceVolumeControlEnabled(boolean deviceVolumeControlEnabled)

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

public ExoPlayer.BuildersetHandleAudioBecomingNoisy(boolean handleAudioBecomingNoisy)

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

public ExoPlayer.BuildersetLivePlaybackSpeedControl(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.

public ExoPlayer.BuildersetLoadControl(LoadControl loadControl)

Sets the LoadControl that will be used by the player.

public ExoPlayer.BuildersetLooper(Looper looper)

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

public ExoPlayer.BuildersetMaxSeekToPreviousPositionMs(long maxSeekToPreviousPositionMs)

Sets the maximum position for which Player.seekToPrevious() seeks to the previous MediaItem.

public ExoPlayer.BuildersetMediaSourceFactory(MediaSource.Factory mediaSourceFactory)

Sets the that will be used by the player.

public ExoPlayer.BuildersetName(java.lang.String playerName)

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

public ExoPlayer.BuildersetPauseAtEndOfMediaItems(boolean pauseAtEndOfMediaItems)

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

public ExoPlayer.BuildersetPlaybackLooper(Looper playbackLooper)

Sets the that will be used for playback.

public ExoPlayer.BuildersetPriority(int priority)

Sets the for this player.

public ExoPlayer.BuildersetPriorityTaskManager(PriorityTaskManager priorityTaskManager)

Sets an PriorityTaskManager that will be used by the player.

public ExoPlayer.BuildersetReleaseTimeoutMs(long releaseTimeoutMs)

Sets a timeout for calls to ExoPlayer.release() and ExoPlayer.setForegroundMode(boolean).

public ExoPlayer.BuildersetRenderersFactory(RenderersFactory renderersFactory)

Sets the RenderersFactory that will be used by the player.

public ExoPlayer.BuildersetSeekBackIncrementMs(long seekBackIncrementMs)

Sets the Player.seekBack() increment.

public ExoPlayer.BuildersetSeekForwardIncrementMs(long seekForwardIncrementMs)

Sets the Player.seekForward() increment.

public ExoPlayer.BuildersetSeekParameters(SeekParameters seekParameters)

Sets the parameters that control how seek operations are performed.

public ExoPlayer.BuildersetSkipSilenceEnabled(boolean skipSilenceEnabled)

Sets whether silences silences in the audio stream is enabled.

public ExoPlayer.BuildersetSuitableOutputChecker(SuitableOutputChecker suitableOutputChecker)

Sets the SuitableOutputChecker to check the suitability of the selected outputs for playback.

public ExoPlayer.BuildersetSuppressPlaybackOnUnsuitableOutput(boolean suppressPlaybackOnUnsuitableOutput)

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

public ExoPlayer.BuildersetTrackSelector(TrackSelector trackSelector)

Sets the TrackSelector that will be used by the player.

public ExoPlayer.BuildersetUseLazyPreparation(boolean useLazyPreparation)

Sets whether media sources should be initialized lazily.

public ExoPlayer.BuildersetUsePlatformDiagnostics(boolean usePlatformDiagnostics)

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

public ExoPlayer.BuildersetVideoChangeFrameRateStrategy(int videoChangeFrameRateStrategy)

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

public ExoPlayer.BuildersetVideoScalingMode(int videoScalingMode)

Sets the that will be used by the player.

public ExoPlayer.BuildersetWakeMode(int wakeMode)

Sets the that will be used by the player.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

public Builder(Context context)

Creates a builder.

Use ExoPlayer.Builder.Builder(Context, RenderersFactory), ExoPlayer.Builder.Builder(Context, MediaSource.Factory) or ExoPlayer.Builder.Builder(Context, RenderersFactory, MediaSource.Factory) instead, if you intend to provide a custom RenderersFactory, ExtractorsFactory 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: A .

public Builder(Context context, RenderersFactory renderersFactory)

Creates a builder with a custom RenderersFactory.

See ExoPlayer.Builder.Builder(Context) for a list of default values.

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

Parameters:

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

public Builder(Context context, MediaSource.Factory mediaSourceFactory)

Creates a builder with a custom .

See ExoPlayer.Builder.Builder(Context) for a list of default values.

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

Parameters:

context: A .
mediaSourceFactory: A factory for creating a MediaSource from a MediaItem.

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

Creates a builder with a custom RenderersFactory and .

See ExoPlayer.Builder.Builder(Context) for a list of default values.

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

Parameters:

context: A .
renderersFactory: A factory for creating Renderers to be used by the player.
mediaSourceFactory: A factory for creating a MediaSource from a MediaItem.

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: A .
renderersFactory: A factory for creating Renderers to be used by the player.
mediaSourceFactory: A .
trackSelector: A TrackSelector.
loadControl: A LoadControl.
bandwidthMeter: A BandwidthMeter.
analyticsCollector: An AnalyticsCollector.

Methods

public ExoPlayer.Builder experimentalSetForegroundModeTimeoutMs(long timeoutMs)

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

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

Parameters:

timeoutMs: The time limit in milliseconds.

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:

dynamicSchedulingEnabled: Whether to enable dynamic scheduling.

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 with the value Player.PLAYBACK_SUPPRESSION_REASON_UNSUITABLE_AUDIO_OUTPUT.

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

Parameters:

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

Returns:

This builder.

public ExoPlayer.Builder setRenderersFactory(RenderersFactory renderersFactory)

Sets the RenderersFactory that will be used by the player.

Parameters:

renderersFactory: A RenderersFactory.

Returns:

This builder.

public ExoPlayer.Builder setMediaSourceFactory(MediaSource.Factory mediaSourceFactory)

Sets the that will be used by the player.

Parameters:

mediaSourceFactory: A .

Returns:

This builder.

public ExoPlayer.Builder setTrackSelector(TrackSelector trackSelector)

Sets the TrackSelector that will be used by the player.

Parameters:

trackSelector: A TrackSelector.

Returns:

This builder.

public ExoPlayer.Builder setLoadControl(LoadControl loadControl)

Sets the LoadControl that will be used by the player.

Parameters:

loadControl: A LoadControl.

Returns:

This builder.

public ExoPlayer.Builder setBandwidthMeter(BandwidthMeter bandwidthMeter)

Sets the BandwidthMeter that will be used by the player.

Parameters:

bandwidthMeter: A BandwidthMeter.

Returns:

This builder.

public ExoPlayer.Builder setLooper(Looper looper)

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

Parameters:

looper: A .

Returns:

This builder.

public ExoPlayer.Builder setAnalyticsCollector(AnalyticsCollector analyticsCollector)

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

Parameters:

analyticsCollector: An AnalyticsCollector.

Returns:

This builder.

public ExoPlayer.Builder setPriority(int priority)

Sets the 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:

priority: The .

public ExoPlayer.Builder setPriorityTaskManager(PriorityTaskManager priorityTaskManager)

Sets an PriorityTaskManager that will be used by the player.

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

Parameters:

priorityTaskManager: A PriorityTaskManager, or null to not use one.

Returns:

This builder.

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 AudioAttributes.usage must be C.USAGE_MEDIA or C.USAGE_GAME. Other usages will throw an java.lang.IllegalArgumentException.

Parameters:

audioAttributes: AudioAttributes.
handleAudioFocus: Whether the player should handle audio focus.

Returns:

This builder.

public ExoPlayer.Builder setWakeMode(int wakeMode)

Sets the that will be used by the player.

Enabling this feature requires the permission. It should be used together with a foreground 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 ( / ) will be held whenever the player is in the Player.STATE_READY or Player.STATE_BUFFERING states with playWhenReady = true. The locks held depend on the specified .

Parameters:

wakeMode: A .

Returns:

This builder.

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:

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

Returns:

This builder.

public ExoPlayer.Builder setSkipSilenceEnabled(boolean skipSilenceEnabled)

Sets whether silences silences in the audio stream is enabled.

Parameters:

skipSilenceEnabled: Whether skipping silences is enabled.

Returns:

This builder.

public ExoPlayer.Builder setDeviceVolumeControlEnabled(boolean deviceVolumeControlEnabled)

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

Parameters:

deviceVolumeControlEnabled: Whether controlling device volume is enabled.

Returns:

This builder.

public ExoPlayer.Builder setVideoScalingMode(int videoScalingMode)

Sets the 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 .

Parameters:

videoScalingMode: A .

Returns:

This builder.

public ExoPlayer.Builder setVideoChangeFrameRateStrategy(int videoChangeFrameRateStrategy)

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

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

Parameters:

videoChangeFrameRateStrategy: A .

Returns:

This builder.

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:

useLazyPreparation: Whether to use lazy preparation.

Returns:

This builder.

public ExoPlayer.Builder setSeekParameters(SeekParameters seekParameters)

Sets the parameters that control how seek operations are performed.

Parameters:

seekParameters: The SeekParameters.

Returns:

This builder.

public ExoPlayer.Builder setSeekBackIncrementMs(long seekBackIncrementMs)

Sets the Player.seekBack() increment.

Parameters:

seekBackIncrementMs: The seek back increment, in milliseconds.

Returns:

This builder.

public ExoPlayer.Builder setSeekForwardIncrementMs(long seekForwardIncrementMs)

Sets the Player.seekForward() increment.

Parameters:

seekForwardIncrementMs: The seek forward increment, in milliseconds.

Returns:

This builder.

public ExoPlayer.Builder setMaxSeekToPreviousPositionMs(long maxSeekToPreviousPositionMs)

Sets the maximum position for which Player.seekToPrevious() seeks to the previous MediaItem.

Parameters:

maxSeekToPreviousPositionMs: The maximum position, in milliseconds.

Returns:

This builder.

public ExoPlayer.Builder setReleaseTimeoutMs(long releaseTimeoutMs)

Sets a timeout for calls to ExoPlayer.release() and ExoPlayer.setForegroundMode(boolean).

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

Parameters:

releaseTimeoutMs: The release timeout, in milliseconds.

Returns:

This builder.

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 .

Parameters:

detachSurfaceTimeoutMs: The timeout for detaching a surface, in milliseconds.

Returns:

This builder.

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 with the reason Player.PLAY_WHEN_READY_CHANGE_REASON_END_OF_MEDIA_ITEM when this happens.

Parameters:

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

Returns:

This builder.

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: The LivePlaybackSpeedControl.

Returns:

This builder.

public ExoPlayer.Builder setUsePlatformDiagnostics(boolean usePlatformDiagnostics)

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

If enabled, the player will use the to create a 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:

usePlatformDiagnostics: Whether the player reports diagnostics data to the Android platform.

Returns:

This builder.

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: A Clock.

Returns:

This builder.

public ExoPlayer.Builder setSuitableOutputChecker(SuitableOutputChecker suitableOutputChecker)

Sets the SuitableOutputChecker to check the suitability of the selected outputs for playback.

If this method is not called, the library uses a default implementation based on framework APIs.

Returns:

This builder.

public ExoPlayer.Builder setPlaybackLooper(Looper playbackLooper)

Sets the that will be used for playback.

The backing thread should run with priority java.lang.Process and should handle messages within 10ms.

Parameters:

playbackLooper: A .

Returns:

This builder.

public ExoPlayer.Builder setName(java.lang.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:

playerName: A name for the player in the PlayerId.

Returns:

This builder.

public ExoPlayer build()

Builds an ExoPlayer instance.