Media3

API リファレンス

メディアのユースケースのサポートライブラリ。

最新の更新	安定版リリース	リリース候補版	ベータ版リリース	アルファ版リリース
2022 年 3 月 9 日	-	-	-	1.0.0-alpha02

依存関係の宣言

Media3 への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

Groovy

dependencies {
    val media3_version = "1.0.0-alpha02"

    // 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-alpha02"

    // 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")
}

依存関係について詳しくは、ビルド依存関係の追加をご覧ください。

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。Media3 Issue Tracker を使用すると、質問への回答、既知の問題、機能リクエストを見つけたり、新しい問題を報告したりできます。

バージョン 1.0.0

バージョン 1.0.0-alpha03

2022 年 3 月 14 日

androidx.media3:media3-*:1.0.0-alpha03 がリリースされました。バージョン 1.0.0-alpha03 に含まれる commit については、こちらをご覧ください。

これは ExoPlayer 2.17.1 リリースに対応しています。

オーディオ:
- HLS でのドルビーアトモス（E-AC3-JOC）の音声機能に関するエラーを修正しました。
エクストラクタ:
- FMP4: v0 と v1 の両方の emsg アトムスを含むストリームに対して、emsg サンプルメタデータが誤った順序で出力される問題を修正しました（#9996）。
テキスト:
- SubtitleConfiguration フィールドの優先順位を設定し、Factory 値が設定されていない場合はその値に戻すために、SingleSampleMediaSource.Factory.setTrackId と MediaItem.SubtitleConfiguration.Builder.setId のインタラクションを修正しました（#10016）。
広告再生:
- ライブ HLS SSAI ストリームの広告期間における音声アンダーランを修正しました。

バージョン 1.0.0-alpha02

2022 年 3 月 2 日

androidx.media3:media3-*:1.0.0-alpha02 がリリースされました。バージョン 1.0.0-alpha02 に含まれる commit については、こちらをご覧ください。

これは ExoPlayer 2.17.0 リリースに対応しています。

コアライブラリ:
- 保護されたメソッド DefaultRenderersFactory.getCodecAdapterFactory() を追加し、buildVideoRenderers() または buildAudioRenderers() をオーバーライドする DefaultRenderersFactory のサブクラスが、コーデックアダプターファクトリにアクセスして MediaCodecRenderer インスタンスに渡せるようにしました。
- ICY ヘッダーフィールド name と genre をそれぞれ MediaMetadata.station と MediaMetadata.genre に反映し、Player.Listener.onMediaMetadataChanged() を介してアプリに到達できるようにしました（#9677）。
- DefaultHttpDataSource#getResponseHeaders から null のキーを削除しました。
- MediaCodec インスタンスの作成に失敗した場合、スリープと再試行を行います。これにより、サーフェスを安全なコーデックから別のコーデックに切り替えたときに一部のデバイスで発生する問題を回避できます（#8696）。
- MediaCodecAdapter.getMetrics() を追加して、ユーザーが MediaCodec から指標データを取得できるようにしました（#9766）。
- Maven の依存関係の解決を修正しました（#8353）。
- 低レイテンシ機能がないライブストリームや、速度設定のユーザーリクエストがないライブストリームについて、自動速度調整を無効にしました（#9329）。
- DecoderCounters#inputBufferCount から queuedInputBufferCount に名前を変更しました。
- SimpleExoPlayer.renderers を非公開にしました。レンダラには ExoPlayer.getRenderer を介してアクセスできます。
- Player.EventFlags の値と一致するように、一部の AnalyticsListener.EventFlags 定数値を更新しました。
- AnalyticsCollector をインターフェースとデフォルトの実装に分割し、アプリで必要ない場合は R8 によって削除されるようにしました。
トラック選択:
- トラック選択での優先動画ロールフラグをサポートしました（#9402）。
- 複数の動画トラックを選択する際に優先する MIME タイプとロールフラグが考慮されるように、動画トラック選択ロジックを更新しました（#9519）。
- デコーダとハードウェアのサポートレベルが同じである自動選択形式のみを選択するように、動画と音声のトラック選択ロジックを更新しました（#9565）。
- プライマリのハードウェアアクセラレーテッドデコーダで複数のコーデックがサポートされている場合は、より効率的なコーデックを優先するように、動画トラック選択ロジックを更新しました（#4835）。
- 技術的なトラック選択の制約（優先 MIME タイプ、最大チャンネル数など）よりも、音声コンテンツの設定（「デフォルト」の音声トラック、システムロケール言語に一致するトラックなど）を優先します。
- あるトラックグループをオーバーライドしても同じタイプの他のトラックグループが無効にならないという、トラック選択の問題を修正しました（#9675）。
- 空でないトラックと空のトラックのオーバーライドが混在していると正しく適用されないという、トラック選択の問題を修正しました（#9649）。
- TrackGroupArray 内の TrackGroup の重複を禁止しました。TrackGroup コンストラクタで id を設定することで、TrackGroup が常に区別できるようになります。これにより、アクティブなトラックのオーバーライドでアプリをバックグラウンド化した後に再生を再開するとクラッシュする問題が修正されます（#9718）。
- 再生がライブエッジに非常に近い場合でも、十分なネットワーク帯域幅があれば品質を向上させられるように、AdaptiveTrackSelection のロジックを修正しました（#9784）。
動画:
- 必要に応じて互換性のある H264/H265 デコーダを使用するように、ドルビービジョンのデコーダフォールバックロジックを修正しました。
オーディオ:
- 必要に応じて互換性のある E-AC3 デコーダを使用するように、ドルビーアトモス（E-AC3-JOC）のデコーダフォールバックロジックを修正しました。
- null ではなく AudioCapabilities.DEFAULT_AUDIO_CAPABILITIES を明示的に渡すことが必須になるように、AudioCapabilities API を変更しました。
- AudioTrackBufferSizeProvider を DefaultAudioSink に挿入することで、AudioTrack バッファサイズの計算をカスタマイズできるようにしました（#8891）。
- リクエストされたバッファサイズが 1 MB を超える場合は、AudioTrack の作成を再試行します（#9712）。
エクストラクタ:
- WAV: RF64 ストリームのサポートを追加しました（#9543）。
- H.265 SPS NAL ユニットの不適切な解析を修正しました（#9719）。
- Ogg Opus ファイルと Ogg Vorbis ファイルの Vorbis コメント（METADATA_BLOCK_PICTURE を含む）を解析します。
テキスト:
- 構成から作成された字幕トラックの Format.id フィールドに反映される MediaItem.SubtitleConfiguration.id フィールドを追加しました（#9673）。
- Matroska コンテナでの WebVTT 字幕の基本的なサポートを追加しました（#9886）。
- 宣言されたサイズを超えるサービスブロックを Cea708Decoder が読み取らないようにしました。
DRM:
- DrmSessionManager.(pre)acquireSession から playbackLooper を削除しました。カスタムの MediaSource でアプリが DrmSessionManager を使用している場合は、代わりに playbackLooper を DrmSessionManager.setPlayer に渡す必要があります。
広告の再生 / IMA:
- IMA ダイナミック広告挿入（DAI）のサポートを追加しました（#8213）。
- 広告グループをリセットしてもう一度再生できるように、AdPlaybackState にメソッドを追加しました（#9615）。
- 広告の再生時、再生速度 1.0 を強制適用します（#9018）。
- 広告グループの読み込みに失敗するとすぐに再生がリセットされる問題を修正しました（#9929）。
UI:
- 特定のテーマを使用している場合の、StyledPlayerView の巻き戻しボタンと早送りボタンの数字の色を修正しました（#9765）。
- 再生速度の文字列を正しく解釈するようになりました（#9811）。
DASH:
- 解析した必須プロパティと補足プロパティを Representation に追加しました（#9579）。
- forced-subtitle トラックロールをサポートしました（#9727）。
- main トラックロールを C.SELECTION_FLAG_DEFAULT として解釈しないようにしました。
- DVB 名前空間を宣言していないマニフェストのベース URL 除外ロジックを修正しました（#9856）。
- 相対 MPD.Location URL をサポートしました（#9939）。
HLS:
- 音声のみの HLS ストリームの Format.label を正しく入力できるようになりました（#9608）。
- 起動時間を改善するためにデフォルトでチャンクレス準備を使用します。マスタープレイリストで宣言されていないクローズドキャプショントラックが描出に含まれている場合は、マスタープレイリストに追加して再生できるようにするか、HlsMediaSource.Factory.setAllowChunklessPreparation(false) でチャンクレス準備をオフにする必要があります。
- HLS でのキーフレームの正確なシークをサポートしました（#2882）。
RTSP:
- 任意のサーバー接続に使用される SocketFactory をオーバーライドするクライアント API を提供しました（#9606）。
- DIGEST と BASIC がどちらも存在する場合、DIGEST 認証方式を優先します（#9800）。
- RTSP トラックタイミングを利用できない場合に対応しました（#9775）。
- 無効な RTP-Info ヘッダー値を無視するようになりました（#9619）。
Transformer:
- 必要な最小 API バージョンを 21 に増やしました。
- TransformationException は、変換中に発生するエラーの記述に使用されるようになりました。
- 変換オプションを指定するための TransformationRequest を追加しました。
- 複数のリスナーを登録できるようになりました。
- コーデック出力が部分的に読み取られたときに Transformer が停止する問題を修正しました。
- muxer スローを解放するときに Transformer.getProgress で発生する可能性がある NPE を修正しました。
- 変換を適用するためのデモアプリを追加しました。
MediaSession 拡張機能:
- デフォルトで、停止時に MediaSessionConnector がプレイリストを消去するようになりました。プレイリストを保持する必要があるアプリは、コネクタで setClearMediaItemsOnStop(false) を呼び出すことができます。
Cast 拡張機能:
- CastPlayer が onIsPlayingChanged を正しく呼び出せないバグを修正しました（#9792）。
- DefaultMediaItemConverter を使用したアートワークを含む音声メタデータをサポートしました（#9663）。
FFmpeg 拡張機能:
- build_ffmpeg.sh が GNU ではなく LLVM の bin utils に依存するようになりました（#9933）。
Android 12 の互換性:
- com.google.android.gms:play-services-cast-framework:20.1.0 に依存するように Cast 拡張機能をアップグレードしました。以前のバージョンの play-services-cast-framework は Android 12 をターゲットとするアプリに対応しておらず、PendingIntent の作成時に IllegalArgumentException でクラッシュします（#9528）。
サポートが終了したシンボルを削除しました。
- Player.EventLister を削除しました。代わりに Player.Listener を使用してください。
- MediaSourceFactory#setDrmSessionManager、MediaSourceFactory#setDrmHttpDataSourceFactory、MediaSourceFactory#setDrmUserAgent を削除しました。代わりに MediaSourceFactory#setDrmSessionManagerProvider を使用してください。
- MediaSourceFactory#setStreamKeys を削除しました。代わりに MediaItem.Builder#setStreamKeys を使用してください。
- MediaSourceFactory#createMediaSource(Uri) を削除しました。代わりに MediaSourceFactory#createMediaSource(MediaItem) を使用してください。
- DashMediaSource、HlsMediaSource、SsMediaSource から setTag を削除しました。代わりに MediaItem.Builder#setTag を使用してください。
- DashMediaSource#setLivePresentationDelayMs(long, boolean) を削除しました。MediaItem.Builder#setLiveConfiguration と MediaItem.LiveConfiguration.Builder#setTargetOffsetMs を使用してマニフェストをオーバーライドするか、DashMediaSource#setFallbackTargetLiveOffsetMs を使用してフォールバック値を提供してください。
- (Simple)ExoPlayer.setThrowsWhenUsingWrongThread を削除しました。スレッドの強制適用をオプトアウトすることはできなくなりました。
- ActionFile と ActionFileUpgradeUtil を削除しました。ExoPlayer 2.16.1 以前で ActionFileUpgradeUtil を使用して、以前のアクションファイルを DefaultDownloadIndex に統合してください。
- ProgressiveMediaSource#setExtractorsFactory を削除しました。代わりに ProgressiveMediaSource.Factory(DataSource.Factory, ExtractorsFactory) コンストラクタを使用してください。
- ProgressiveMediaSource.Factory#setTag と ProgressiveMediaSource.Factory#setCustomCacheKey を削除しました。代わりに MediaItem.Builder#setTag と MediaItem.Builder#setCustomCacheKey を使用してください。
- DefaultRenderersFactory(Context, @ExtensionRendererMode int) コンストラクタと DefaultRenderersFactory(Context, @ExtensionRendererMode int, long) コンストラクタを削除しました。代わりに DefaultRenderersFactory(Context) コンストラクタ、DefaultRenderersFactory#setExtensionRendererMode、DefaultRenderersFactory#setAllowedVideoJoiningTimeMs を使用してください。
- すべてのパブリック CronetDataSource コンストラクタを削除しました。代わりに CronetDataSource.Factory を使用してください。
次の IntDefs を @Target(TYPE_USE) のみに変更しました。Kotlin での使用のコンパイルが失敗するおそれがありますが、アノテーションを移動して型（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（com.google.android.exoplayer2.ext.flac パッケージ）
- @FlacExtractor.Flags（com.google.android.exoplayer2.extractor.flac パッケージ）
- @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

バージョン 1.0.0-alpha01

2021 年 10 月 27 日

androidx.media3:media3-*:1.0.0-alpha01 がリリースされました。バージョン 1.0.0-alpha01 に含まれる commit については、こちらをご覧ください。

新機能

Media3 は、ExoPlayer を含むメディアサポートライブラリの新しいホームです。最初のアルファ版には、メディアのユースケースを実装するためのライブラリの機能の初期実装が含まれています。

カスタマイズと拡張が簡単な Android 用のアプリレベルのメディアプレーヤーである ExoPlayer。
再生を公開して制御するためのメディアセッション機能。この新しいセッションモジュールは、ExoPlayer と同じ Player インターフェースを使用します。
メディア再生のユーザーインターフェースを作成するための UI コンポーネント。
IMA SDK による広告の挿入など、ExoPlayer で使用する他のライブラリの機能をラップするモジュール。

詳しくは、Media3 GitHub プロジェクトをご覧ください。

ExoPlayer は、以前は別の ExoPlayer GitHub プロジェクトでホストされていました。Media3 のパッケージ名は androidx.media3.exoplayer です。しばらくの間、ExoPlayer GitHub プロジェクトの維持とリリースを続け、アプリが Media3 に移行できるようにする予定です。Media3 には、ExoPlayer のすべてのモジュールの置き換えが用意されています。ただし、以前の media2 と mediasession 拡張機能は新しい media3-session モジュールに置き換えられています。これにより、アダプターやコネクタのクラスを使用する必要なく、プレーヤーとメディアセッションを直接統合できます。