0
# ExoPlayer
1

2
ExoPlayer is the core media player implementation for local media playback on Android within the AndroidX Media3 ecosystem. It provides an extensible media player library that handles various audio and video formats, streaming protocols, and playback scenarios with high performance and reliability.
3

4
## Package Information
5

6
- **Package Name**: androidx.media3:media3-exoplayer
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'androidx.media3:media3-exoplayer:1.8.0'`
10

11
## Core Imports
12

13
```java
14
import androidx.media3.exoplayer.ExoPlayer;
15
import androidx.media3.exoplayer.ExoPlayer.AudioOffloadListener;
16
import androidx.media3.exoplayer.ExoPlayer.PreloadConfiguration;
17
import androidx.media3.exoplayer.DefaultRenderersFactory;
18
import androidx.media3.exoplayer.DefaultLoadControl;
19
import androidx.media3.exoplayer.ScrubbingModeParameters;
20
import androidx.media3.exoplayer.trackselection.DefaultTrackSelector;
21
import androidx.media3.exoplayer.source.MediaSource;
22
import androidx.media3.exoplayer.image.ImageOutput;
23
import androidx.media3.common.MediaItem;
24
import androidx.media3.common.DeviceInfo;
25
```
26

27
## Basic Usage
28

29
```java
30
import androidx.media3.exoplayer.ExoPlayer;
31
import androidx.media3.common.MediaItem;
32
import android.content.Context;
33

34
// Create ExoPlayer instance
35
ExoPlayer player = new ExoPlayer.Builder(context).build();
36

37
// Set media item and prepare
38
MediaItem mediaItem = MediaItem.fromUri("https://example.com/video.mp4");
39
player.setMediaItem(mediaItem);
40
player.prepare();
41

42
// Start playback
43
player.setPlayWhenReady(true);
44

45
// Release when done
46
player.release();
47
```
48

49
## Architecture
50

51
ExoPlayer is built around several key components that work together to provide flexible media playback:
52

53
- **ExoPlayer Interface**: The main player interface providing playback control and state management
54
- **MediaSource**: Components that define, load, and provide media to be played
55
- **Renderer**: Components that render individual media streams (audio, video, text, metadata)
56
- **TrackSelector**: Selects which tracks to play from available options
57
- **LoadControl**: Controls buffering behavior and timing
58
- **Analytics System**: Comprehensive event tracking and performance monitoring
59

60
## Capabilities
61

62
### Core Player Interface
63

64
Main ExoPlayer interface providing extensible media playback functionality with builder pattern construction.
65

66
```java { .api }
67
public interface ExoPlayer extends Player {
68
    static final class Builder {
69
        public Builder(Context context);
70
        public Builder setRenderersFactory(RenderersFactory renderersFactory);
71
        public Builder setTrackSelector(TrackSelector trackSelector);
72
        public Builder setLoadControl(LoadControl loadControl);
73
        public Builder setBandwidthMeter(BandwidthMeter bandwidthMeter);
74
        public Builder setAnalyticsCollector(AnalyticsCollector analyticsCollector);
75
        public Builder setLooper(Looper looper);
76
        public Builder setPriorityTaskManager(PriorityTaskManager priorityTaskManager);
77
        public Builder setClock(Clock clock);
78
        public Builder setUseLazyPreparation(boolean useLazyPreparation);
79
        public Builder setPlaybackLooper(Looper playbackLooper);
80
        public Builder setName(String playerName);
81
        public Builder experimentalSetForegroundModeTimeoutMs(long timeoutMs);
82
        public Builder experimentalSetDynamicSchedulingEnabled(boolean dynamicSchedulingEnabled);
83
        public ExoPlayer build();
84
    }
85
    
86
    void addAnalyticsListener(AnalyticsListener listener);
87
    void removeAnalyticsListener(AnalyticsListener listener);
88
    void addAudioOffloadListener(AudioOffloadListener listener);
89
    void removeAudioOffloadListener(AudioOffloadListener listener);
90
    int getRendererCount();
91
    @C.TrackType int getRendererType(int index);
92
    Renderer getRenderer(int index);
93
    void setMediaSource(MediaSource mediaSource);
94
    void setMediaSources(List<MediaSource> mediaSources);
95
    void addMediaSource(MediaSource mediaSource);
96
    void setAudioSessionId(int audioSessionId);
97
    int getAudioSessionId();
98
    void setVideoEffects(List<Effect> videoEffects);
99
    void setVideoScalingMode(@C.VideoScalingMode int videoScalingMode);
100
    void setVideoChangeFrameRateStrategy(@C.VideoChangeFrameRateStrategy int videoChangeFrameRateStrategy);
101
    void setImageOutput(ImageOutput imageOutput);
102
    PlayerMessage createMessage(PlayerMessage.Target target);
103
    void setSeekParameters(SeekParameters seekParameters);
104
    void setPreloadConfiguration(PreloadConfiguration preloadConfiguration);
105
    PreloadConfiguration getPreloadConfiguration();
106
    void setScrubbingModeEnabled(boolean scrubbingModeEnabled);
107
    boolean isScrubbingModeEnabled();
108
    void setScrubbingModeParameters(ScrubbingModeParameters scrubbingModeParameters);
109
    ScrubbingModeParameters getScrubbingModeParameters();
110
    void setForegroundMode(boolean foregroundMode);
111
    DeviceInfo getDeviceInfo();
112
    int getDeviceVolume();
113
    boolean isDeviceMuted();
114
    void setDeviceVolume(int volume, @C.VolumeFlags int flags);
115
    void increaseDeviceVolume(@C.VolumeFlags int flags);
116
    void decreaseDeviceVolume(@C.VolumeFlags int flags);
117
    void setDeviceMuted(boolean muted, @C.VolumeFlags int flags);
118
    boolean isTunnelingEnabled();
119
    boolean isSleepingForOffload();
120
    boolean isReleased();
121
}
122
```
123

124
[Core Player](./core-player.md)
125

126
### Media Source Management
127

128
Defines and provides media content to ExoPlayer with support for various formats and streaming protocols.
129

130
```java { .api }
131
public interface MediaSource {
132
    interface Factory {
133
        MediaSource createMediaSource(MediaItem mediaItem);
134
        @C.ContentType int[] getSupportedTypes();
135
    }
136
    
137
    void prepareSource(MediaSourceCaller caller, @Nullable TransferListener mediaTransferListener, PlayerId playerId);
138
    MediaPeriod createPeriod(MediaPeriodId id, Allocator allocator, long startPositionUs);
139
    void releasePeriod(MediaPeriod mediaPeriod);
140
    boolean canUpdateMediaItem(MediaItem mediaItem);
141
    MediaSource updateMediaItem(MediaItem mediaItem);
142
}
143
```
144

145
[Media Sources](./media-sources.md)
146

147
### Track Selection
148

149
Automatic and manual track selection for optimal playback experience across different network conditions and device capabilities.
150

151
```java { .api }
152
public class DefaultTrackSelector extends MappingTrackSelector {
153
    public static final class Builder {
154
        public Builder(Context context);
155
        public Builder setForceLowestBitrate(boolean forceLowestBitrate);
156
        public Builder setForceHighestSupportedBitrate(boolean forceHighestSupportedBitrate);
157
        public Builder setTunnelingEnabled(boolean tunnelingEnabled);
158
        public DefaultTrackSelector build();
159
    }
160
    
161
    public static final class Parameters extends TrackSelectionParameters {
162
        public static final class Builder extends TrackSelectionParameters.Builder {
163
            public Builder(Context context);
164
            public Builder setForceLowestBitrate(boolean forceLowestBitrate);
165
            public Builder setForceHighestSupportedBitrate(boolean forceHighestSupportedBitrate);
166
            public Parameters build();
167
        }
168
    }
169
    
170
    public void setParameters(Parameters parameters);
171
    public Parameters getParameters();
172
    public Parameters.Builder buildUponParameters();
173
}
174
```
175

176
[Track Selection](./track-selection.md)
177

178
### Audio Rendering
179

180
Audio processing and output with support for various codecs, effects, and output configurations.
181

182
```java { .api }
183
public interface AudioSink {
184
    void configure(Format format, int specifiedBufferSize, @Nullable int[] outputChannels) throws ConfigurationException;
185
    void play();
186
    void pause();
187
    void playToEndOfStream() throws WriteException;
188
    void reset();
189
    void release();
190
    void setVolume(float volume);
191
    void setAudioAttributes(AudioAttributes audioAttributes);
192
    void setAuxEffectInfo(AuxEffectInfo auxEffectInfo);
193
    PlaybackParameters getPlaybackParameters();
194
    void setPlaybackParameters(PlaybackParameters playbackParameters);
195
    boolean handleBuffer(ByteBuffer buffer, long presentationTimeUs, int encodedAccessUnitCount) throws WriteException;
196
}
197
```
198

199
[Audio Rendering](./audio-rendering.md)
200

201
### Video Rendering
202

203
Video decoding, processing, and display with support for hardware acceleration and various surface types.
204

205
```java { .api }
206
public class MediaCodecVideoRenderer extends MediaCodecRenderer {
207
    public MediaCodecVideoRenderer(Context context, MediaCodecSelector mediaCodecSelector, long allowedJoiningTimeMs);
208
    public void setVideoFrameMetadataListener(VideoFrameMetadataListener listener);
209
    public void clearVideoFrameMetadataListener();
210
}
211

212
public interface VideoSink {
213
    void onInputStreamChanged(@C.TrackType int inputType, Format format);
214
    void registerInputStream(@C.TrackType int inputType, List<Effect> effects);
215
    void setOutputSurfaceInfo(Surface outputSurface, Size outputResolution);
216
    boolean render(long presentationTimeUs, long releaseTimeNs) throws VideoSinkException;
217
    void join();
218
    void release();
219
}
220
```
221

222
[Video Rendering](./video-rendering.md)
223

224
### Analytics and Monitoring
225

226
Comprehensive event tracking, performance monitoring, and debugging capabilities.
227

228
```java { .api }
229
public interface AnalyticsListener {
230
    void onPlaybackStateChanged(EventTime eventTime, @Player.State int state);
231
    void onPlayWhenReadyChanged(EventTime eventTime, boolean playWhenReady, @Player.PlayWhenReadyChangeReason int reason);
232
    void onIsPlayingChanged(EventTime eventTime, boolean isPlaying);
233
    void onTimelineChanged(EventTime eventTime, @Player.TimelineChangeReason int reason);
234
    void onTracksChanged(EventTime eventTime, Tracks tracks);
235
    void onPlayerError(EventTime eventTime, PlaybackException error);
236
    void onSeekStarted(EventTime eventTime);
237
    void onSeekProcessed(EventTime eventTime);
238
    void onVideoSizeChanged(EventTime eventTime, VideoSize videoSize);
239
    void onAudioSessionIdChanged(EventTime eventTime, int audioSessionId);
240
}
241
```
242

243
[Analytics](./analytics.md)
244

245
### DRM Support
246

247
Digital Rights Management for protected content playback with various DRM schemes.
248

249
```java { .api }
250
public interface DrmSessionManager {
251
    void prepare();
252
    @C.CryptoType int getCryptoType(Format format);
253
    DrmSession acquireSession(Looper playbackLooper, DrmInitData drmInitData);
254
    void releaseSession(DrmSession drmSession);
255
    void setMode(@C.CryptoMode int mode, @Nullable byte[] offlineLicenseKeySetId);
256
    void setPlayer(Looper playbackLooper, PlayerId playerId);
257
}
258
```
259

260
[DRM Support](./drm-support.md)
261

262
### Offline Support
263

264
Download management for offline media playback capabilities.
265

266
```java { .api }
267
public class DownloadManager {
268
    public DownloadManager(Context context, DownloadIndex downloadIndex, DownloaderFactory downloaderFactory);
269
    public void addListener(Listener listener);
270
    public void removeListener(Listener listener);
271
    public void start();
272
    public void stop();
273
    public void pause();
274
    public void resume();
275
}
276

277
public interface Downloader {
278
    void download(@Nullable ProgressListener progressListener) throws IOException, InterruptedException;
279
    void cancel();
280
    void remove() throws IOException;
281
}
282
```
283

284
[Offline Support](./offline-support.md)
285

286
## Types
287

288
```java { .api }
289
public final class ExoPlaybackException extends PlaybackException {
290
    public static final int TYPE_SOURCE = 0;
291
    public static final int TYPE_RENDERER = 1;
292
    public static final int TYPE_UNEXPECTED = 2;
293
    public static final int TYPE_REMOTE = 3;
294
    
295
    @Type public int type;
296
    @Nullable public int rendererIndex;
297
    @Nullable public Format rendererFormat;
298
    @Nullable public String rendererName;
299
    @Nullable public MediaPeriodId mediaPeriodId;
300
    
301
    public int getType();
302
    public int getRendererIndex();
303
    @Nullable public Format getRendererFormat();
304
    @Nullable public String getRendererName();
305
    @Nullable public MediaPeriodId getMediaPeriodId();
306
    public ExoPlaybackException copyWithMediaPeriodId(@Nullable MediaPeriodId mediaPeriodId);
307
}
308

309
public final class SeekParameters {
310
    public static final SeekParameters DEFAULT;
311
    public static final SeekParameters EXACT;
312
    public static final SeekParameters CLOSEST_SYNC;
313
    public static final SeekParameters PREVIOUS_SYNC;
314
    public static final SeekParameters NEXT_SYNC;
315
    
316
    public final long toleranceBeforeUs;
317
    public final long toleranceAfterUs;
318
}
319

320
public final class PlayerMessage {
321
    public PlayerMessage.Target getTarget();
322
    public int getType();
323
    @Nullable public Object getPayload();
324
    public Looper getLooper();
325
    public PlayerMessage setType(int messageType);
326
    public PlayerMessage setPayload(@Nullable Object payload);
327
    public PlayerMessage setPosition(long positionMs);
328
    public PlayerMessage setPosition(int mediaItemIndex, long positionMs);
329
    public PlayerMessage setHandler(Handler handler);
330
    public PlayerMessage send();
331
    public boolean cancel();
332
}
333

334
public static final class PreloadConfiguration {
335
    public static final PreloadConfiguration DEFAULT;
336
    
337
    public final long targetPreloadDurationUs;
338
    
339
    public PreloadConfiguration(long targetPreloadDurationUs);
340
}
341

342
public final class ScrubbingModeParameters {
343
    public static final ScrubbingModeParameters DEFAULT;
344
    
345
    public final long maxSeekToPreviousPositionMs;
346
    public final long seekBackIncrementMs;
347
    public final long seekForwardIncrementMs;
348
    
349
    public ScrubbingModeParameters(long maxSeekToPreviousPositionMs, long seekBackIncrementMs, long seekForwardIncrementMs);
350
}
351

352
public interface AudioOffloadListener {
353
    default void onSleepingForOffloadChanged(boolean isSleepingForOffload);
354
    default void onOffloadedPlayback(boolean isOffloadedPlayback);
355
}
356

357
// Constants
358
public interface ExoPlayer extends Player {
359
    long DEFAULT_RELEASE_TIMEOUT_MS = 500;
360
    long DEFAULT_DETACH_SURFACE_TIMEOUT_MS = 2000;
361
}
362
```