Media3

Support libraries for media use cases.
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 and MediaItem.SubtitleConfiguration.Builder.setId to prioritise the SubtitleConfiguration field and fall back to the Factory value if it's not set (#10016).
  • 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 of DefaultRenderersFactory that override buildVideoRenderers() or buildAudioRenderers() can access the codec adapter factory and pass it to MediaCodecRenderer instances they create.
    • Propagate ICY header fields name and genre to MediaMetadata.station and MediaMetadata.genre respectively so that they reach the app via Player.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 from MediaCodec. (#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 to queuedInputBufferCount.
    • Make SimpleExoPlayer.renderers private. Renderers can be accessed via ExoPlayer.getRenderer.
    • Updated some AnalyticsListener.EventFlags constant values to match values in Player.EventFlags.
    • Split AnalyticsCollector into an interface and default implementation to allow it to be stripped by R8 if an app doesn't need it.
  • 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 TrackGroups in a TrackGroupArray. TrackGroups can always be made distinguishable by setting an id in the TrackGroup 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 explicitly AudioCapabilities.DEFAULT_AUDIO_CAPABILITIES instead of null.
    • Allow customization of the AudioTrack buffer size calculation by injecting an AudioTrackBufferSizeProvider to DefaultAudioSink. (#8891).
    • Retry AudioTrack creation if the requested buffer size was > 1MB. (#9712).
  • Extractors:
    • WAV: Add support for RF64 streams (#9543).
    • Fix incorrect parsing of H.265 SPS NAL units (#9719).
    • Parse Vorbis Comments (including METADATA_BLOCK_PICTURE) in Ogg Opus and Ogg Vorbis files.
  • Text:
    • Add a MediaItem.SubtitleConfiguration.id field which is propagated to the Format.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.
  • DRM:
    • Remove playbackLooper from DrmSessionManager.(pre)acquireSession. When a DrmSessionManager is used by an app in a custom MediaSource, the playbackLooper needs to be passed to DrmSessionManager.setPlayer instead.
  • 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:
    • Fix the color of the numbers in StyledPlayerView rewind and fastforward buttons when using certain themes (#9765).
    • Correctly translate playback speed strings (#9811).
  • DASH:
    • Add parsed essential and supplemental properties to the Representation (#9579).
    • Support the forced-subtitle track role (#9727).
    • Stop interpreting the main track role as C.SELECTION_FLAG_DEFAULT.
    • Fix base URL exclusion logic for manifests that do not declare the DVB namespace (#9856).
    • Support relative MPD.Location URLs (#9939).
  • 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).
  • RTSP:
    • Provide a client API to override the SocketFactory used for any server connection (#9606).
    • Prefer DIGEST authentication method over BASIC if both are present (#9800).
    • Handle when RTSP track timing is not available (#9775).
    • Ignore invalid RTP-Info header values (#9619).
  • 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 call setClearMediaItemsOnStop(false) on the connector.
  • Cast extension:
    • Fix bug that prevented CastPlayer from calling onIsPlayingChanged correctly (#9792).
    • Support audio metadata including artwork with DefaultMediaItemConverter (#9663).
  • FFmpeg extension:
    • Make build_ffmpeg.sh depend on LLVM's bin utils instead of GNU's (#9933).
  • Android 12 compatibility:
    • Upgrade the Cast extension to depend on com.google.android.gms:play-services-cast-framework:20.1.0. Earlier versions of play-services-cast-framework are not compatible with apps targeting Android 12, and will crash with an IllegalArgumentException when creating PendingIntents (#9528).
  • Remove deprecated symbols:
    • Remove Player.EventLister. Use Player.Listener instead.
    • Remove MediaSourceFactory#setDrmSessionManager, MediaSourceFactory#setDrmHttpDataSourceFactory, and MediaSourceFactory#setDrmUserAgent. Use MediaSourceFactory#setDrmSessionManagerProvider instead.
    • Remove MediaSourceFactory#setStreamKeys. Use MediaItem.Builder#setStreamKeys instead.
    • Remove MediaSourceFactory#createMediaSource(Uri). Use MediaSourceFactory#createMediaSource(MediaItem) instead.
    • Remove setTag from DashMediaSource, HlsMediaSource and SsMediaSource. Use MediaItem.Builder#setTag instead.
    • Remove DashMediaSource#setLivePresentationDelayMs(long, boolean). Use MediaItem.Builder#setLiveConfiguration and MediaItem.LiveConfiguration.Builder#setTargetOffsetMs to override the manifest, or DashMediaSource#setFallbackTargetLiveOffsetMs to provide a fallback value.
    • Remove (Simple)ExoPlayer.setThrowsWhenUsingWrongThread. Opting out of the thread enforcement is no longer possible.
    • Remove ActionFile and ActionFileUpgradeUtil. Use ExoPlayer 2.16.1 or before to use ActionFileUpgradeUtil to merge legacy action files into DefaultDownloadIndex.
    • Remove ProgressiveMediaSource#setExtractorsFactory. Use ProgressiveMediaSource.Factory(DataSource.Factory, ExtractorsFactory) constructor instead.
    • Remove ProgressiveMediaSource.Factory#setTag and, and ProgressiveMediaSource.Factory#setCustomCacheKey. Use MediaItem.Builder#setTag and MediaItem.Builder#setCustomCacheKey instead.
    • Remove DefaultRenderersFactory(Context, @ExtensionRendererMode int) and DefaultRenderersFactory(Context, @ExtensionRendererMode int, long) constructors. Use the DefaultRenderersFactory(Context) constructor, DefaultRenderersFactory#setExtensionRendererMode, and DefaultRenderersFactory#setAllowedVideoJoiningTimeMs instead.
    • Remove all public CronetDataSource constructors. Use CronetDataSource.Factory instead.
  • 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 (in com.google.android.exoplayer2.ext.flac package)
    • @FlacExtractor.Flags (in com.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.