0
# Media Sources
1

2
MediaSources define and provide media content to ExoPlayer. They handle loading, parsing, and providing media data to the player. The library includes implementations for various media types including progressive files, DASH, HLS, SmoothStreaming, and more.
3

4
## MediaSource Interface
5

6
The base interface for all media sources that provide media content to ExoPlayer.
7

8
```java { .api }
9
public interface MediaSource {
10
    /**
11
     * Factory for creating MediaSource instances from MediaItem objects.
12
     */
13
    interface Factory {
14
        /**
15
         * Creates a MediaSource for the given MediaItem.
16
         * 
17
         * @param mediaItem The MediaItem to create a source for
18
         * @return The created MediaSource
19
         */
20
        MediaSource createMediaSource(MediaItem mediaItem);
21
        
22
        /**
23
         * Returns the content types supported by media sources created by this factory.
24
         * 
25
         * @return An array of supported content types
26
         */
27
        @C.ContentType int[] getSupportedTypes();
28
        
29
        /**
30
         * Sets the SubtitleParserFactory for parsing subtitles.
31
         * 
32
         * @param subtitleParserFactory The SubtitleParser.Factory
33
         * @return This factory
34
         */
35
        MediaSource.Factory setSubtitleParserFactory(SubtitleParser.Factory subtitleParserFactory);
36
        
37
        /**
38
         * Sets the video codecs to parse within GOP sample dependencies (experimental).
39
         * 
40
         * @param codecsToParseWithinGopSampleDependencies The codec flags
41
         * @return This factory
42
         */
43
        MediaSource.Factory experimentalSetCodecsToParseWithinGopSampleDependencies(@C.VideoCodecFlags int codecsToParseWithinGopSampleDependencies);
44
        
45
        /**
46
         * Sets the CMCD configuration factory.
47
         * 
48
         * @param cmcdConfigurationFactory The CmcdConfiguration.Factory
49
         * @return This factory
50
         */
51
        MediaSource.Factory setCmcdConfigurationFactory(CmcdConfiguration.Factory cmcdConfigurationFactory);
52
    }
53
    
54
    /**
55
     * Prepares the source with the specified caller.
56
     * 
57
     * @param caller The MediaSourceCaller
58
     * @param mediaTransferListener The transfer listener
59
     * @param playerId The player ID
60
     */
61
    void prepareSource(MediaSourceCaller caller, @Nullable TransferListener mediaTransferListener, PlayerId playerId);
62
    
63
    /**
64
     * Creates a MediaPeriod for the specified period.
65
     * 
66
     * @param id The MediaPeriodId
67
     * @param allocator The Allocator for loading data
68
     * @param startPositionUs The start position in microseconds
69
     * @return The created MediaPeriod
70
     */
71
    MediaPeriod createPeriod(MediaPeriodId id, Allocator allocator, long startPositionUs);
72
    
73
    /**
74
     * Releases a MediaPeriod.
75
     * 
76
     * @param mediaPeriod The MediaPeriod to release
77
     */
78
    void releasePeriod(MediaPeriod mediaPeriod);
79
    
80
    /**
81
     * Returns whether the MediaItem can be updated.
82
     * 
83
     * @param mediaItem The new MediaItem
84
     * @return Whether the update is supported
85
     */
86
    boolean canUpdateMediaItem(MediaItem mediaItem);
87
    
88
    /**
89
     * Updates the MediaItem.
90
     * 
91
     * @param mediaItem The new MediaItem
92
     * @return The updated MediaSource
93
     */
94
    MediaSource updateMediaItem(MediaItem mediaItem);
95
}
96
```
97

98
## DefaultMediaSourceFactory
99

100
The default factory for creating MediaSources from MediaItems, supporting multiple formats.
101

102
```java { .api }
103
public final class DefaultMediaSourceFactory implements MediaSource.Factory {
104
    /**
105
     * Creates a DefaultMediaSourceFactory.
106
     * 
107
     * @param context The context
108
     */
109
    public DefaultMediaSourceFactory(Context context);
110
    
111
    /**
112
     * Creates a DefaultMediaSourceFactory with custom DataSource.Factory.
113
     * 
114
     * @param dataSourceFactory The DataSource.Factory
115
     */
116
    public DefaultMediaSourceFactory(DataSource.Factory dataSourceFactory);
117
    
118
    /**
119
     * Sets the DrmSessionManagerProvider.
120
     * 
121
     * @param drmSessionManagerProvider The DrmSessionManagerProvider
122
     * @return This factory
123
     */
124
    public DefaultMediaSourceFactory setDrmSessionManagerProvider(DrmSessionManagerProvider drmSessionManagerProvider);
125
    
126
    /**
127
     * Sets the LoadErrorHandlingPolicy.
128
     * 
129
     * @param loadErrorHandlingPolicy The LoadErrorHandlingPolicy
130
     * @return This factory
131
     */
132
    public DefaultMediaSourceFactory setLoadErrorHandlingPolicy(LoadErrorHandlingPolicy loadErrorHandlingPolicy);
133
    
134
    /**
135
     * Sets live target offset for live streams.
136
     * 
137
     * @param liveTargetOffsetMs The target offset in milliseconds
138
     * @return This factory
139
     */
140
    public DefaultMediaSourceFactory setLiveTargetOffsetMs(long liveTargetOffsetMs);
141
    
142
    @Override
143
    public MediaSource createMediaSource(MediaItem mediaItem);
144
    
145
    @Override
146
    @C.ContentType public int[] getSupportedTypes();
147
}
148
```
149

150
## Progressive Media Sources
151

152
For playing progressive media files (MP4, WebM, MP3, etc.).
153

154
```java { .api }
155
public final class ProgressiveMediaSource extends BaseMediaSource {
156
    public static final class Factory implements MediaSource.Factory {
157
        /**
158
         * Creates a factory for ProgressiveMediaSource.
159
         * 
160
         * @param dataSourceFactory The DataSource.Factory
161
         * @param extractorsFactory The ExtractorsFactory
162
         */
163
        public Factory(DataSource.Factory dataSourceFactory, ExtractorsFactory extractorsFactory);
164
        
165
        /**
166
         * Creates a factory with default extractors.
167
         * 
168
         * @param dataSourceFactory The DataSource.Factory
169
         */
170
        public Factory(DataSource.Factory dataSourceFactory);
171
        
172
        /**
173
         * Sets custom loading check interval.
174
         * 
175
         * @param continueLoadingCheckIntervalBytes The interval in bytes
176
         * @return This factory
177
         */
178
        public Factory setContinueLoadingCheckIntervalBytes(int continueLoadingCheckIntervalBytes);
179
        
180
        @Override
181
        public MediaSource createMediaSource(MediaItem mediaItem);
182
        
183
        @Override
184
        @C.ContentType public int[] getSupportedTypes();
185
    }
186
}
187
```
188

189
## DASH Media Sources
190

191
For playing DASH (Dynamic Adaptive Streaming over HTTP) content.
192

193
```java { .api }
194
public final class DashMediaSource extends BaseMediaSource {
195
    public static final class Factory implements MediaSource.Factory {
196
        /**
197
         * Creates a factory for DashMediaSource.
198
         * 
199
         * @param dataSourceFactory The DataSource.Factory
200
         */
201
        public Factory(DataSource.Factory dataSourceFactory);
202
        
203
        /**
204
         * Creates a factory with custom chunk source factory.
205
         * 
206
         * @param chunkSourceFactory The DashChunkSource.Factory
207
         * @param dataSourceFactory The DataSource.Factory for manifest loading
208
         */
209
        public Factory(DashChunkSource.Factory chunkSourceFactory, DataSource.Factory dataSourceFactory);
210
        
211
        /**
212
         * Sets the manifest parser.
213
         * 
214
         * @param manifestParser The DashManifestParser
215
         * @return This factory
216
         */
217
        public Factory setManifestParser(ParsingLoadable.Parser<DashManifest> manifestParser);
218
        
219
        /**
220
         * Sets the compositor factory for effects.
221
         * 
222
         * @param compositorFactory The compositor factory
223
         * @return This factory
224
         */
225
        public Factory setCompositorFactory(Compositor.Factory compositorFactory);
226
        
227
        @Override
228
        public MediaSource createMediaSource(MediaItem mediaItem);
229
        
230
        @Override
231
        @C.ContentType public int[] getSupportedTypes();
232
    }
233
}
234
```
235

236
## HLS Media Sources
237

238
For playing HTTP Live Streaming (HLS) content.
239

240
```java { .api }
241
public final class HlsMediaSource extends BaseMediaSource {
242
    public static final class Factory implements MediaSource.Factory {
243
        /**
244
         * Creates a factory for HlsMediaSource.
245
         * 
246
         * @param dataSourceFactory The DataSource.Factory
247
         */
248
        public Factory(DataSource.Factory dataSourceFactory);
249
        
250
        /**
251
         * Sets the HlsExtractorFactory.
252
         * 
253
         * @param hlsExtractorFactory The HlsExtractorFactory
254
         * @return This factory
255
         */
256
        public Factory setExtractorFactory(HlsExtractorFactory hlsExtractorFactory);
257
        
258
        /**
259
         * Sets the playlist tracker factory.
260
         * 
261
         * @param playlistTrackerFactory The HlsPlaylistTracker.Factory
262
         * @return This factory
263
         */
264
        public Factory setPlaylistTrackerFactory(HlsPlaylistTracker.Factory playlistTrackerFactory);
265
        
266
        /**
267
         * Sets whether chunkless preparation is allowed.
268
         * 
269
         * @param allowChunklessPreparation Whether to allow chunkless preparation
270
         * @return This factory
271
         */
272
        public Factory setAllowChunklessPreparation(boolean allowChunklessPreparation);
273
        
274
        @Override
275
        public MediaSource createMediaSource(MediaItem mediaItem);
276
        
277
        @Override
278
        @C.ContentType public int[] getSupportedTypes();
279
    }
280
}
281
```
282

283
## Concatenating Media Sources
284

285
For creating playlists by concatenating multiple media sources.
286

287
```java { .api }
288
public final class ConcatenatingMediaSource extends CompositeMediaSource<MediaSource> {
289
    /**
290
     * Creates an empty ConcatenatingMediaSource.
291
     */
292
    public ConcatenatingMediaSource();
293
    
294
    /**
295
     * Creates a ConcatenatingMediaSource with the specified media sources.
296
     * 
297
     * @param mediaSources The media sources to concatenate
298
     */
299
    public ConcatenatingMediaSource(MediaSource... mediaSources);
300
    
301
    /**
302
     * Creates a ConcatenatingMediaSource with shuffle order support.
303
     * 
304
     * @param isAtomic Whether the source is atomic
305
     * @param shuffleOrder The shuffle order
306
     * @param mediaSources The media sources
307
     */
308
    public ConcatenatingMediaSource(boolean isAtomic, ShuffleOrder shuffleOrder, MediaSource... mediaSources);
309
    
310
    /**
311
     * Adds a media source to the end of the playlist.
312
     * 
313
     * @param mediaSource The media source to add
314
     */
315
    public void addMediaSource(MediaSource mediaSource);
316
    
317
    /**
318
     * Adds a media source at the specified index.
319
     * 
320
     * @param index The index to insert at
321
     * @param mediaSource The media source to add
322
     */
323
    public void addMediaSource(int index, MediaSource mediaSource);
324
    
325
    /**
326
     * Adds multiple media sources.
327
     * 
328
     * @param mediaSources The media sources to add
329
     */
330
    public void addMediaSources(Collection<MediaSource> mediaSources);
331
    
332
    /**
333
     * Removes a media source at the specified index.
334
     * 
335
     * @param index The index to remove
336
     */
337
    public void removeMediaSource(int index);
338
    
339
    /**
340
     * Removes media sources in the specified range.
341
     * 
342
     * @param fromIndex The start index (inclusive)
343
     * @param toIndex The end index (exclusive)
344
     */
345
    public void removeMediaSourceRange(int fromIndex, int toIndex);
346
    
347
    /**
348
     * Moves a media source from one index to another.
349
     * 
350
     * @param currentIndex The current index
351
     * @param newIndex The new index
352
     */
353
    public void moveMediaSource(int currentIndex, int newIndex);
354
    
355
    /**
356
     * Gets the size of the playlist.
357
     * 
358
     * @return The number of media sources
359
     */
360
    public int getSize();
361
}
362
```
363

364
## Clipping Media Sources
365

366
For playing only a portion of a media source.
367

368
```java { .api }
369
public final class ClippingMediaSource extends WrappingMediaSource {
370
    /**
371
     * Creates a ClippingMediaSource that clips from the start.
372
     * 
373
     * @param mediaSource The media source to clip
374
     * @param startPositionUs The start position in microseconds
375
     */
376
    public ClippingMediaSource(MediaSource mediaSource, long startPositionUs);
377
    
378
    /**
379
     * Creates a ClippingMediaSource with start and end positions.
380
     * 
381
     * @param mediaSource The media source to clip
382
     * @param startPositionUs The start position in microseconds
383
     * @param endPositionUs The end position in microseconds
384
     */
385
    public ClippingMediaSource(MediaSource mediaSource, long startPositionUs, long endPositionUs);
386
    
387
    /**
388
     * Creates a ClippingMediaSource with full configuration.
389
     * 
390
     * @param mediaSource The media source to clip
391
     * @param startPositionUs The start position in microseconds
392
     * @param endPositionUs The end position in microseconds
393
     * @param enableInitialDiscontinuity Whether to enable initial discontinuity
394
     * @param allowDynamicClippingUpdates Whether to allow dynamic updates
395
     * @param relativeToDefaultPosition Whether positions are relative to default position
396
     */
397
    public ClippingMediaSource(MediaSource mediaSource, long startPositionUs, long endPositionUs, 
398
                              boolean enableInitialDiscontinuity, boolean allowDynamicClippingUpdates, 
399
                              boolean relativeToDefaultPosition);
400
}
401
```
402

403
## Usage Examples
404

405
### Basic Media Source Creation
406

407
```java
408
// Create from URI
409
MediaItem mediaItem = MediaItem.fromUri("https://example.com/video.mp4");
410
DefaultMediaSourceFactory factory = new DefaultMediaSourceFactory(context);
411
MediaSource mediaSource = factory.createMediaSource(mediaItem);
412

413
// Set to player
414
player.setMediaSource(mediaSource);
415
player.prepare();
416
```
417

418
### Creating Specific Media Sources
419

420
```java
421
// Progressive media source
422
DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(context);
423
ProgressiveMediaSource progressiveSource = new ProgressiveMediaSource.Factory(dataSourceFactory)
424
    .createMediaSource(MediaItem.fromUri("https://example.com/video.mp4"));
425

426
// DASH media source  
427
DashMediaSource dashSource = new DashMediaSource.Factory(dataSourceFactory)
428
    .createMediaSource(MediaItem.fromUri("https://example.com/manifest.mpd"));
429

430
// HLS media source
431
HlsMediaSource hlsSource = new HlsMediaSource.Factory(dataSourceFactory)
432
    .createMediaSource(MediaItem.fromUri("https://example.com/playlist.m3u8"));
433
```
434

435
### Playlist Creation
436

437
```java
438
// Create concatenating source for playlist
439
ConcatenatingMediaSource concatenatingSource = new ConcatenatingMediaSource();
440

441
// Add multiple sources
442
concatenatingSource.addMediaSource(progressiveSource);
443
concatenatingSource.addMediaSource(dashSource);
444
concatenatingSource.addMediaSource(hlsSource);
445

446
// Play playlist
447
player.setMediaSource(concatenatingSource);
448
```
449

450
### Clipping Media
451

452
```java
453
// Play only 30-60 seconds of a video
454
long startUs = 30 * C.MICROS_PER_SECOND;
455
long endUs = 60 * C.MICROS_PER_SECOND;
456

457
ClippingMediaSource clippingSource = new ClippingMediaSource(
458
    progressiveSource, 
459
    startUs, 
460
    endUs
461
);
462

463
player.setMediaSource(clippingSource);
464
```
465

466
### Dynamic Playlist Management
467

468
```java
469
ConcatenatingMediaSource playlist = new ConcatenatingMediaSource();
470
player.setMediaSource(playlist);
471
player.prepare();
472

473
// Add items dynamically during playback
474
playlist.addMediaSource(factory.createMediaSource(MediaItem.fromUri("uri1")));
475
playlist.addMediaSource(factory.createMediaSource(MediaItem.fromUri("uri2")));
476

477
// Remove items
478
playlist.removeMediaSource(0);
479

480
// Move items
481
playlist.moveMediaSource(0, 2);
482
```