Media3
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
March 14, 2022 | - | - | - | 1.0.0-alpha03 |
Declaring dependencies
To add a dependency on Media3, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.
Add the dependencies for the artifacts you need in the build.gradle
file for
your app or module:
Groovy
dependencies { val media3_version = "1.0.0-alpha03" // For media playback using ExoPlayer implementation "androidx.media3:media3-exoplayer:$media3_version" // For DASH playback support with ExoPlayer implementation "androidx.media3:media3-exoplayer-dash:$media3_version" // For HLS playback support with ExoPlayer implementation "androidx.media3:media3-exoplayer-hls:$media3_version" // For RTSP playback support with ExoPlayer implementation "androidx.media3:media3-exoplayer-rtsp:$media3_version" // For ad insertion using the Interactive Media Ads SDK with ExoPlayer implementation "androidx.media3:media3-exoplayer-ima:$media3_version" // For loading data using the Cronet network stack implementation "androidx.media3:media3-datasource-cronet:$media3_version" // For loading data using the OkHttp network stack implementation "androidx.media3:media3-datasource-okhttp:$media3_version" // For loading data using librtmp implementation "androidx.media3:media3-datasource-rtmp:$media3_version" // For building media playback UIs implementation "androidx.media3:media3-ui:$media3_version" // For building media playback UIs for Android TV using the Jetpack Leanback library implementation "androidx.media3:media3-ui-leanback:$media3_version" // For exposing and controlling media sessions implementation "androidx.media3:media3-session:$media3_version" // For extracting data from media containers implementation "androidx.media3:media3-extractor:$media3_version" // For integrating with Cast implementation "androidx.media3:media3-cast:$media3_version" // For scheduling background operations using Jetpack Work's WorkManager with ExoPlayer implementation "androidx.media3:media3-exoplayer-workmanager:$media3_version" // For transforming media files implementation "androidx.media3:media3-transformer:$media3_version" // Utilities for testing media components (including ExoPlayer components) implementation "androidx.media3:media3-test-utils:$media3_version" // Utilities for testing media components (including ExoPlayer components) via Robolectric implementation "androidx.media3:media3-test-utils-robolectric:$media3_version" // Common functionality for media database components implementation "androidx.media3:media3-database:$media3_version" // Common functionality for media decoders implementation "androidx.media3:media3-decoder:$media3_version" // Common functionality for loading data implementation "androidx.media3:media3-datasource:$media3_version" // Common functionality used across multiple media libraries implementation "androidx.media3:media3-common:$media3_version" }
Kotlin
dependencies { val media3_version = "1.0.0-alpha03" // For media playback using ExoPlayer implementation("androidx.media3:media3-exoplayer:$media3_version") // For DASH playback support with ExoPlayer implementation("androidx.media3:media3-exoplayer-dash:$media3_version") // For HLS playback support with ExoPlayer implementation("androidx.media3:media3-exoplayer-hls:$media3_version") // For RTSP playback support with ExoPlayer implementation("androidx.media3:media3-exoplayer-rtsp:$media3_version") // For ad insertion using the Interactive Media Ads SDK with ExoPlayer implementation("androidx.media3:media3-exoplayer-ima:$media3_version") // For loading data using the Cronet network stack implementation("androidx.media3:media3-datasource-cronet:$media3_version") // For loading data using the OkHttp network stack implementation("androidx.media3:media3-datasource-okhttp:$media3_version") // For loading data using librtmp implementation("androidx.media3:media3-datasource-rtmp:$media3_version") // For building media playback UIs implementation("androidx.media3:media3-ui:$media3_version") // For building media playback UIs for Android TV using the Jetpack Leanback library implementation("androidx.media3:media3-ui-leanback:$media3_version") // For exposing and controlling media sessions implementation("androidx.media3:media3-session:$media3_version") // For extracting data from media containers implementation("androidx.media3:media3-extractor:$media3_version") // For integrating with Cast implementation("androidx.media3:media3-cast:$media3_version") // For scheduling background operations using Jetpack Work's WorkManager with ExoPlayer implementation("androidx.media3:media3-exoplayer-workmanager:$media3_version") // For transforming media files implementation("androidx.media3:media3-transformer:$media3_version") // Utilities for testing media components (including ExoPlayer components) implementation("androidx.media3:media3-test-utils:$media3_version") // Utilities for testing media components (including ExoPlayer components) via Robolectric implementation("androidx.media3:media3-test-utils-robolectric:$media3_version") // Common functionality for media database components implementation("androidx.media3:media3-database:$media3_version") // Common functionality for media decoders implementation("androidx.media3:media3-decoder:$media3_version") // Common functionality for loading data implementation("androidx.media3:media3-datasource:$media3_version") // Common functionality used across multiple media libraries implementation("androidx.media3:media3-common:$media3_version") }
For more information about dependencies, see Add Build Dependencies.
Feedback
Your feedback helps make Jetpack better. You can use the Media3 issue tracker to find answers to questions, known issues and feature requests, and to file new issues.
Version 1.0.0
Version 1.0.0-alpha03
March 14, 2022
androidx.media3:media3-*:1.0.0-alpha03
is released.
Version 1.0.0-alpha03 contains these commits.
This corresponds to the ExoPlayer 2.17.1 release.
- Audio:
- Fix error checking audio capabilities for Dolby Atmos (E-AC3-JOC) in HLS.
- Extractors:
- FMP4: Fix issue where emsg sample metadata could be output in the wrong order for streams containing both v0 and v1 emsg atoms (#9996).
- Text:
- Fix the interaction of
SingleSampleMediaSource.Factory.setTrackId
andMediaItem.SubtitleConfiguration.Builder.setId
to prioritise theSubtitleConfiguration
field and fall back to theFactory
value if it's not set (#10016).
- Fix the interaction of
- Ad playback:
- Fix audio underruns between ad periods in live HLS SSAI streams.
Version 1.0.0-alpha02
March 2, 2022
androidx.media3:media3-*:1.0.0-alpha02
is released.
Version 1.0.0-alpha02 contains these commits.
This corresponds to the ExoPlayer 2.17.0 release.
- Core Library:
- Add protected method
DefaultRenderersFactory.getCodecAdapterFactory()
so that subclasses ofDefaultRenderersFactory
that overridebuildVideoRenderers()
orbuildAudioRenderers()
can access the codec adapter factory and pass it toMediaCodecRenderer
instances they create. - Propagate ICY header fields
name
andgenre
toMediaMetadata.station
andMediaMetadata.genre
respectively so that they reach the app viaPlayer.Listener.onMediaMetadataChanged()
(#9677). - Remove null keys from
DefaultHttpDataSource#getResponseHeaders
. - Sleep and retry when creating a
MediaCodec
instance fails. This works around an issue that occurs on some devices when switching a surface from a secure codec to another codec (#8696). - Add
MediaCodecAdapter.getMetrics()
to allow users obtain metrics data fromMediaCodec
. (#9766). - Fix Maven dependency resolution (#8353).
- Disable automatic speed adjustment for live streams that neither have low-latency features nor a user request setting the speed (#9329).
- Rename
DecoderCounters#inputBufferCount
toqueuedInputBufferCount
. - Make
SimpleExoPlayer.renderers
private. Renderers can be accessed viaExoPlayer.getRenderer
. - Updated some
AnalyticsListener.EventFlags
constant values to match values inPlayer.EventFlags
. - Split
AnalyticsCollector
into an interface and default implementation to allow it to be stripped by R8 if an app doesn't need it.
- Add protected method
- Track selection:
- Support preferred video role flags in track selection (#9402).
- Update video track selection logic to take preferred MIME types and role flags into account when selecting multiple video tracks for adaptation (#9519).
- Update video and audio track selection logic to only choose formats for adaptive selections that have the same level of decoder and hardware support (#9565).
- Update video track selection logic to prefer more efficient codecs if multiple codecs are supported by primary, hardware-accelerated decoders (#4835).
- Prefer audio content preferences (for example, the "default" audio track or a track matching the system locale language) over technical track selection constraints (for example, preferred MIME type, or maximum channel count).
- Fix track selection issue where overriding one track group did not disable other track groups of the same type (#9675).
- Fix track selection issue where a mixture of non-empty and empty track overrides is not applied correctly (#9649).
- Prohibit duplicate
TrackGroup
s in aTrackGroupArray
.TrackGroup
s can always be made distinguishable by setting anid
in theTrackGroup
constructor. This fixes a crash when resuming playback after backgrounding the app with an active track override (#9718). - Amend logic in
AdaptiveTrackSelection
to allow a quality increase under sufficient network bandwidth even if playback is very close to the live edge (#9784).
- Video:
- Fix decoder fallback logic for Dolby Vision to use a compatible H264/H265 decoder if needed.
- Audio:
- Fix decoder fallback logic for Dolby Atmos (E-AC3-JOC) to use a compatible E-AC3 decoder if needed.
- Change
AudioCapabilities
APIs to require passing explicitlyAudioCapabilities.DEFAULT_AUDIO_CAPABILITIES
instead ofnull
. - Allow customization of the
AudioTrack
buffer size calculation by injecting anAudioTrackBufferSizeProvider
toDefaultAudioSink
. (#8891). - Retry
AudioTrack
creation if the requested buffer size was > 1MB. (#9712).
- Extractors:
- Text:
- Add a
MediaItem.SubtitleConfiguration.id
field which is propagated to theFormat.id
field of the subtitle track created from the configuration (#9673). - Add basic support for WebVTT subtitles in Matroska containers (#9886).
- Prevent
Cea708Decoder
from reading more than the declared size of a service block.
- Add a
- DRM:
- Remove
playbackLooper
fromDrmSessionManager.(pre)acquireSession
. When aDrmSessionManager
is used by an app in a customMediaSource
, theplaybackLooper
needs to be passed toDrmSessionManager.setPlayer
instead.
- Remove
- Ad playback / IMA:
- Add support for IMA Dynamic Ad Insertion (DAI) (#8213).
- Add a method to
AdPlaybackState
to allow resetting an ad group so that it can be played again (#9615). - Enforce playback speed of 1.0 during ad playback (#9018).
- Fix issue where an ad group that failed to load caused an immediate playback reset (#9929).
- UI:
- DASH:
- Add parsed essential and supplemental properties to the
Representation
(#9579). - Support the
forced-subtitle
track role (#9727). - Stop interpreting the
main
track role asC.SELECTION_FLAG_DEFAULT
. - Fix base URL exclusion logic for manifests that do not declare the DVB namespace (#9856).
- Support relative
MPD.Location
URLs (#9939).
- Add parsed essential and supplemental properties to the
- HLS:
- Correctly populate
Format.label
for audio only HLS streams (#9608). - Use chunkless preparation by default to improve start up time. If your
renditions contain muxed closed-caption tracks that are not declared
in the master playlist, you should add them to the master playlist to be
available for playback, or turn off chunkless preparation with
HlsMediaSource.Factory.setAllowChunklessPreparation(false)
. - Support key-frame accurate seeking in HLS (#2882).
- Correctly populate
- RTSP:
- Transformer:
- Increase required min API version to 21.
TransformationException
is now used to describe errors that occur during a transformation.- Add
TransformationRequest
for specifying the transformation options. - Allow multiple listeners to be registered.
- Fix Transformer being stuck when the codec output is partially read.
- Fix potential NPE in
Transformer.getProgress
when releasing the muxer throws. - Add a demo app for applying transformations.
- MediaSession extension:
- By default,
MediaSessionConnector
now clears the playlist on stop. Apps that want the playlist to be retained can callsetClearMediaItemsOnStop(false)
on the connector.
- By default,
- Cast extension:
- FFmpeg extension:
- Make
build_ffmpeg.sh
depend on LLVM's bin utils instead of GNU's (#9933).
- Make
- Android 12 compatibility:
- Upgrade the Cast extension to depend on
com.google.android.gms:play-services-cast-framework:20.1.0
. Earlier versions ofplay-services-cast-framework
are not compatible with apps targeting Android 12, and will crash with anIllegalArgumentException
when creatingPendingIntent
s (#9528).
- Upgrade the Cast extension to depend on
- Remove deprecated symbols:
- Remove
Player.EventLister
. UsePlayer.Listener
instead. - Remove
MediaSourceFactory#setDrmSessionManager
,MediaSourceFactory#setDrmHttpDataSourceFactory
, andMediaSourceFactory#setDrmUserAgent
. UseMediaSourceFactory#setDrmSessionManagerProvider
instead. - Remove
MediaSourceFactory#setStreamKeys
. UseMediaItem.Builder#setStreamKeys
instead. - Remove
MediaSourceFactory#createMediaSource(Uri)
. UseMediaSourceFactory#createMediaSource(MediaItem)
instead. - Remove
setTag
fromDashMediaSource
,HlsMediaSource
andSsMediaSource
. UseMediaItem.Builder#setTag
instead. - Remove
DashMediaSource#setLivePresentationDelayMs(long, boolean)
. UseMediaItem.Builder#setLiveConfiguration
andMediaItem.LiveConfiguration.Builder#setTargetOffsetMs
to override the manifest, orDashMediaSource#setFallbackTargetLiveOffsetMs
to provide a fallback value. - Remove
(Simple)ExoPlayer.setThrowsWhenUsingWrongThread
. Opting out of the thread enforcement is no longer possible. - Remove
ActionFile
andActionFileUpgradeUtil
. Use ExoPlayer 2.16.1 or before to useActionFileUpgradeUtil
to merge legacy action files intoDefaultDownloadIndex
. - Remove
ProgressiveMediaSource#setExtractorsFactory
. UseProgressiveMediaSource.Factory(DataSource.Factory, ExtractorsFactory)
constructor instead. - Remove
ProgressiveMediaSource.Factory#setTag
and, andProgressiveMediaSource.Factory#setCustomCacheKey
. UseMediaItem.Builder#setTag
andMediaItem.Builder#setCustomCacheKey
instead. - Remove
DefaultRenderersFactory(Context, @ExtensionRendererMode int)
andDefaultRenderersFactory(Context, @ExtensionRendererMode int, long)
constructors. Use theDefaultRenderersFactory(Context)
constructor,DefaultRenderersFactory#setExtensionRendererMode
, andDefaultRenderersFactory#setAllowedVideoJoiningTimeMs
instead. - Remove all public
CronetDataSource
constructors. UseCronetDataSource.Factory
instead.
- Remove
- Change the following
IntDefs
to@Target(TYPE_USE)
only. This may break the compilation of usages in Kotlin, which can be fixed by moving the annotation to annotate the type (Int
).@AacAudioObjectType
@Ac3Util.SyncFrameInfo.StreamType
@AdLoadException.Type
@AdtsExtractor.Flags
@AmrExtractor.Flags
@AspectRatioFrameLayout.ResizeMode
@AudioFocusManager.PlayerCommand
@AudioSink.SinkFormatSupport
@BinarySearchSeeker.TimestampSearchResult.Type
@BufferReplacementMode
@C.BufferFlags
@C.ColorRange
@C.ColorSpace
@C.ColorTransfer
@C.CryptoMode
@C.Encoding
@C.PcmEncoding
@C.Projection
@C.SelectionReason
@C.StereoMode
@C.VideoOutputMode
@CacheDataSource.Flags
@CaptionStyleCompat.EdgeType
@DataSpec.Flags
@DataSpec.HttpMethods
@DecoderDiscardReasons
@DecoderReuseResult
@DefaultAudioSink.OutputMode
@DefaultDrmSessionManager.Mode
@DefaultTrackSelector.SelectionEligibility
@DefaultTsPayloadReaderFactory.Flags
@EGLSurfaceTexture.SecureMode
@EbmlProcessor.ElementType
@ExoMediaDrm.KeyRequest.RequestType
@ExtensionRendererMode
@Extractor.ReadResult
@FileTypes.Type
@FlacExtractor.Flags
(incom.google.android.exoplayer2.ext.flac
package)@FlacExtractor.Flags
(incom.google.android.exoplayer2.extractor.flac
package)@FragmentedMp4Extractor.Flags
@HlsMediaPlaylist.PlaylistType
@HttpDataSourceException.Type
@IllegalClippingException.Reason
@IllegalMergeException.Reason
@LoadErrorHandlingPolicy.FallbackType
@MatroskaExtractor.Flags
@Mp3Extractor.Flags
@Mp4Extractor.Flags
@NotificationUtil.Importance
@PlaybackException.FieldNumber
@PlayerNotificationManager.Priority
@PlayerNotificationManager.Visibility
@PlayerView.ShowBuffering
@Renderer.State
@RendererCapabilities.AdaptiveSupport
@RendererCapabilities.Capabilities
@RendererCapabilities.DecoderSupport
@RendererCapabilities.FormatSupport
@RendererCapabilities.HardwareAccelerationSupport
@RendererCapabilities.TunnelingSupport
@SampleStream.ReadDataResult
@SampleStream.ReadFlags
@StyledPlayerView.ShowBuffering
@SubtitleView.ViewType
@TextAnnotation.Position
@TextEmphasisSpan.MarkFill
@TextEmphasisSpan.MarkShape
@Track.Transformation
@TrackOutput.SampleDataPart
@Transformer.ProgressState
@TsExtractor.Mode
@TsPayloadReader.Flags
@WebvttCssStyle.FontSizeUnit
Version 1.0.0-alpha01
October 27, 2021
androidx.media3:media3-*:1.0.0-alpha01
is released.
Version 1.0.0-alpha01 contains these commits.
New features
Media3 is the new home for media support libraries, including ExoPlayer. The first alpha contains early, functional implementations of libraries for implementing media use cases, including:
- ExoPlayer, an application-level media player for Android that is easy to customize and extend.
- Media session functionality, for exposing and controlling playbacks. This new
session module uses the same
Player
interface as ExoPlayer. - UI components for building media playback user interfaces.
- Modules wrapping functionality in other libraries for use with ExoPlayer, for example, ad insertion via the IMA SDK.
For more information, see the Media3 GitHub project.
ExoPlayer was previously hosted in a separate
ExoPlayer GitHub project. In Media3 its
package name is androidx.media3.exoplayer
. We plan to continue to maintain and
release the ExoPlayer GitHub project for a while to give apps time to migrate to
Media3. Media3 has replacements for all the ExoPlayer modules, except for the
legacy media2 and mediasession extensions, which are replaced by the new
media3-session
module. This provides direct integration between players and
media sessions without needing to use an adapter/connector class.