0
# Core Player
1

2
The ExoPlayer interface is the main entry point for media playback, providing an extensible architecture for playing MediaSources with full control over playback state, seek operations, and component configuration.
3

4
## ExoPlayer Interface
5

6
The primary interface for media playback that extends the basic Player interface with ExoPlayer-specific functionality.
7

8
```java { .api }
9
public interface ExoPlayer extends Player {
10
    // Analytics
11
    void addAnalyticsListener(AnalyticsListener listener);
12
    void removeAnalyticsListener(AnalyticsListener listener);
13
    
14
    // Audio offload
15
    void addAudioOffloadListener(AudioOffloadListener listener);
16
    void removeAudioOffloadListener(AudioOffloadListener listener);
17
    
18
    // Renderer access
19
    int getRendererCount();
20
    @C.TrackType int getRendererType(int index);
21
    Renderer getRenderer(int index);
22
    
23
    // Media source management
24
    void setMediaSource(MediaSource mediaSource);
25
    void setMediaSources(List<MediaSource> mediaSources);
26
    void addMediaSource(MediaSource mediaSource);
27
    void addMediaSource(int index, MediaSource mediaSource);
28
    void addMediaSources(List<MediaSource> mediaSources);
29
    void addMediaSources(int index, List<MediaSource> mediaSources);
30
    void removeMediaItem(int index);
31
    void removeMediaItems(int fromIndex, int toIndex);
32
    void moveMediaItem(int currentIndex, int newIndex);
33
    void moveMediaItems(int fromIndex, int toIndex, int newIndex);
34
    
35
    // Audio configuration
36
    void setAudioSessionId(int audioSessionId);
37
    int getAudioSessionId();
38
    
39
    // Video configuration
40
    void setVideoEffects(List<Effect> videoEffects);
41
    void setVideoScalingMode(@C.VideoScalingMode int videoScalingMode);
42
    void setVideoChangeFrameRateStrategy(@C.VideoChangeFrameRateStrategy int videoChangeFrameRateStrategy);
43
    
44
    // Image output
45
    void setImageOutput(ImageOutput imageOutput);
46
    
47
    // Message passing
48
    PlayerMessage createMessage(PlayerMessage.Target target);
49
    
50
    // Seek configuration
51
    void setSeekParameters(SeekParameters seekParameters);
52
    
53
    // Preload configuration
54
    void setPreloadConfiguration(PreloadConfiguration preloadConfiguration);
55
    PreloadConfiguration getPreloadConfiguration();
56
    
57
    // Scrubbing mode
58
    void setScrubbingModeEnabled(boolean scrubbingModeEnabled);
59
    boolean isScrubbingModeEnabled();
60
    void setScrubbingModeParameters(ScrubbingModeParameters scrubbingModeParameters);
61
    ScrubbingModeParameters getScrubbingModeParameters();
62
    
63
    // Playback control
64
    void setForegroundMode(boolean foregroundMode);
65
    boolean isTunnelingEnabled();
66
    boolean isSleepingForOffload();
67
    boolean isReleased();
68
    
69
    // Device information
70
    DeviceInfo getDeviceInfo();
71
    int getDeviceVolume();
72
    boolean isDeviceMuted();
73
    void setDeviceVolume(int volume, @C.VolumeFlags int flags);
74
    void increaseDeviceVolume(@C.VolumeFlags int flags);
75
    void decreaseDeviceVolume(@C.VolumeFlags int flags);
76
    void setDeviceMuted(boolean muted, @C.VolumeFlags int flags);
77
}
78
```
79

80
## ExoPlayer Builder
81

82
The Builder class provides a fluent interface for constructing ExoPlayer instances with custom components.
83

84
```java { .api }
85
public static final class Builder {
86
    /**
87
     * Creates a builder with the specified context.
88
     *
89
     * @param context The context
90
     */
91
    public Builder(Context context);
92
    
93
    /**
94
     * Sets the RenderersFactory for creating Renderers for the player.
95
     * 
96
     * @param renderersFactory The RenderersFactory
97
     * @return This builder
98
     */
99
    public Builder setRenderersFactory(RenderersFactory renderersFactory);
100
    
101
    /**
102
     * Sets the TrackSelector for selecting tracks to be consumed by the player's renderers.
103
     * 
104
     * @param trackSelector The TrackSelector
105
     * @return This builder
106
     */
107
    public Builder setTrackSelector(TrackSelector trackSelector);
108
    
109
    /**
110
     * Sets the LoadControl that will control when the MediaSource buffers more media.
111
     * 
112
     * @param loadControl The LoadControl
113
     * @return This builder
114
     */
115
    public Builder setLoadControl(LoadControl loadControl);
116
    
117
    /**
118
     * Sets the BandwidthMeter that will be used by the player.
119
     * 
120
     * @param bandwidthMeter The BandwidthMeter
121
     * @return This builder
122
     */
123
    public Builder setBandwidthMeter(BandwidthMeter bandwidthMeter);
124
    
125
    /**
126
     * Sets the AnalyticsCollector that will collect and forward analytics events.
127
     * 
128
     * @param analyticsCollector The AnalyticsCollector
129
     * @return This builder
130
     */
131
    public Builder setAnalyticsCollector(AnalyticsCollector analyticsCollector);
132
    
133
    /**
134
     * Sets the Looper that must be used for all calls to the player.
135
     * 
136
     * @param looper The Looper
137
     * @return This builder
138
     */
139
    public Builder setLooper(Looper looper);
140
    
141
    /**
142
     * Sets the PriorityTaskManager that will be used to prioritize loading.
143
     * 
144
     * @param priorityTaskManager The PriorityTaskManager
145
     * @return This builder
146
     */
147
    public Builder setPriorityTaskManager(@Nullable PriorityTaskManager priorityTaskManager);
148
    
149
    /**
150
     * Sets the Clock that will be used by the player.
151
     * 
152
     * @param clock The Clock
153
     * @return This builder
154
     */
155
    public Builder setClock(Clock clock);
156
    
157
    /**
158
     * Sets whether to use the lazy preparation.
159
     * 
160
     * @param useLazyPreparation Whether to use lazy preparation
161
     * @return This builder
162
     */
163
    public Builder setUseLazyPreparation(boolean useLazyPreparation);
164
    
165
    /**
166
     * Sets the Looper that will be used for playback.
167
     * 
168
     * @param playbackLooper The playback Looper
169
     * @return This builder
170
     */
171
    public Builder setPlaybackLooper(Looper playbackLooper);
172
    
173
    /**
174
     * Sets the player name for identification in PlayerId.
175
     * 
176
     * @param playerName The player name
177
     * @return This builder
178
     */
179
    public Builder setName(String playerName);
180
    
181
    /**
182
     * Sets the foreground mode timeout (experimental).
183
     * 
184
     * @param timeoutMs The timeout in milliseconds
185
     * @return This builder
186
     */
187
    public Builder experimentalSetForegroundModeTimeoutMs(long timeoutMs);
188
    
189
    /**
190
     * Enables dynamic scheduling (experimental).
191
     * 
192
     * @param dynamicSchedulingEnabled Whether to enable dynamic scheduling
193
     * @return This builder
194
     */
195
    public Builder experimentalSetDynamicSchedulingEnabled(boolean dynamicSchedulingEnabled);
196
    
197
    /**
198
     * Sets the MediaSourceFactory to be used by the player.
199
     * 
200
     * @param mediaSourceFactory The MediaSourceFactory
201
     * @return This builder
202
     */
203
    public Builder setMediaSourceFactory(MediaSource.Factory mediaSourceFactory);
204
    
205
    /**
206
     * Builds an ExoPlayer instance.
207
     * 
208
     * @return The built ExoPlayer instance
209
     */
210
    public ExoPlayer build();
211
}
212
```
213

214
## Basic Player Construction
215

216
```java
217
// Create with default components
218
ExoPlayer player = new ExoPlayer.Builder(context).build();
219

220
// Create with custom track selector
221
DefaultTrackSelector trackSelector = new DefaultTrackSelector.Builder(context).build();
222
ExoPlayer player = new ExoPlayer.Builder(context)
223
    .setTrackSelector(trackSelector)
224
    .build();
225

226
// Create with custom renderers factory
227
DefaultRenderersFactory renderersFactory = new DefaultRenderersFactory(context);
228
ExoPlayer player = new ExoPlayer.Builder(context)
229
    .setRenderersFactory(renderersFactory)
230
    .build();
231
```
232

233
## Media Playback Control
234

235
```java
236
// Set single media item
237
MediaItem mediaItem = MediaItem.fromUri("https://example.com/video.mp4");
238
player.setMediaItem(mediaItem);
239

240
// Set multiple media items
241
List<MediaItem> mediaItems = Arrays.asList(
242
    MediaItem.fromUri("https://example.com/video1.mp4"),
243
    MediaItem.fromUri("https://example.com/video2.mp4")
244
);
245
player.setMediaItems(mediaItems);
246

247
// Add media items dynamically
248
player.addMediaItem(MediaItem.fromUri("https://example.com/video3.mp4"));
249
player.addMediaItem(1, MediaItem.fromUri("https://example.com/video_insert.mp4"));
250

251
// Prepare and play
252
player.prepare();
253
player.setPlayWhenReady(true);
254
```
255

256
## Renderer Information
257

258
```java
259
// Get renderer information
260
int rendererCount = player.getRendererCount();
261
for (int i = 0; i < rendererCount; i++) {
262
    @C.TrackType int trackType = player.getRendererType(i);
263
    Renderer renderer = player.getRenderer(i);
264
    
265
    switch (trackType) {
266
        case C.TRACK_TYPE_AUDIO:
267
            // Handle audio renderer
268
            break;
269
        case C.TRACK_TYPE_VIDEO:
270
            // Handle video renderer
271
            break;
272
        case C.TRACK_TYPE_TEXT:
273
            // Handle text renderer
274
            break;
275
        case C.TRACK_TYPE_METADATA:
276
            // Handle metadata renderer
277
            break;
278
    }
279
}
280
```
281

282
## Player Messages
283

284
```java
285
// Send message to a renderer
286
PlayerMessage message = player.createMessage(player.getRenderer(0))
287
    .setType(MediaCodecRenderer.MSG_SET_VIDEO_DECODER_OUTPUT_BUFFER_RENDERER)
288
    .setPayload(outputBufferRenderer)
289
    .send();
290

291
// Cancel message if needed
292
message.cancel();
293
```
294

295
## Audio Session Management
296

297
```java
298
// Set audio session ID for integration with audio effects
299
player.setAudioSessionId(audioSessionId);
300

301
// Get current audio session ID
302
int currentSessionId = player.getAudioSessionId();
303
```
304

305
## Video Configuration
306

307
```java
308
// Set video effects
309
List<Effect> videoEffects = Arrays.asList(/* your effects */);
310
player.setVideoEffects(videoEffects);
311

312
// Set video scaling mode
313
player.setVideoScalingMode(C.VIDEO_SCALING_MODE_SCALE_TO_FIT);
314

315
// Set frame rate change strategy
316
player.setVideoChangeFrameRateStrategy(C.VIDEO_CHANGE_FRAME_RATE_STRATEGY_ONLY_IF_SEAMLESS);
317
```
318

319
## Seek Parameters
320

321
```java
322
// Set seek parameters for different seeking behaviors
323
player.setSeekParameters(SeekParameters.EXACT);           // Exact seeking
324
player.setSeekParameters(SeekParameters.CLOSEST_SYNC);     // Seek to closest sync point
325
player.setSeekParameters(SeekParameters.PREVIOUS_SYNC);    // Seek to previous sync point
326
player.setSeekParameters(SeekParameters.NEXT_SYNC);        // Seek to next sync point
327

328
// Custom seek parameters
329
SeekParameters customSeek = new SeekParameters(1000000, 2000000); // 1s before, 2s after tolerance
330
player.setSeekParameters(customSeek);
331
```
332

333
## Player State Management
334

335
```java
336
// Check player state
337
@Player.State int playbackState = player.getPlaybackState();
338
boolean isPlaying = player.isPlaying();
339
boolean playWhenReady = player.getPlayWhenReady();
340

341
// Control playback
342
player.setPlayWhenReady(true);  // Start/resume playback
343
player.setPlayWhenReady(false); // Pause playback
344
player.stop();                  // Stop playback
345
player.seekTo(30000);           // Seek to 30 seconds
346
player.seekToDefaultPosition(); // Seek to default position
347

348
// Get playback position
349
long currentPosition = player.getCurrentPosition();
350
long duration = player.getDuration();
351
long bufferedPosition = player.getBufferedPosition();
352
```
353

354
## Cleanup
355

356
```java
357
// Always release the player when done
358
player.release();
359

360
// Check if player is released
361
boolean isReleased = player.isReleased();
362
```