本頁面由 Cloud Translation API 翻譯而成。

Media2

API 參考資料
androidx.media2.common
androidx.media2.player
androidx.media2.session
androidx.media2.widget

與其他應用程式共用媒體內容和控制項。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2024 年 1 月 10 日	1.3.0	-	-	-

宣告依附元件

如要新增 Media2 的依附元件，必須將 Google Maven 存放區新增至您的專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

dependencies {
    def media2_version = "1.3.0"

    // Interacting with MediaSessions
    implementation "androidx.media2:media2-session:$media2_version"
    // optional - UI widgets for VideoView and MediaControlView
    implementation "androidx.media2:media2-widget:$media2_version"
    // optional - Implementation of a SessionPlayer
    implementation "androidx.media2:media2-player:$media2_version"
}

Kotlin

dependencies {
    val media2_version = "1.3.0"

    // Interacting with MediaSessions
    implementation("androidx.media2:media2-session:$media2_version")
    // optional - UI widgets for VideoView and MediaControlView
    implementation("androidx.media2:media2-widget:$media2_version")
    // optional - Implementation of a SessionPlayer
    implementation("androidx.media2:media2-player:$media2_version")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋：

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.3 版

1.3.0 版

2024 年 1 月 10 日

發布 androidx.media2:media2-*:1.3.0。1.3.0 版包含此連結所列的修訂項目。

自 1.2.0 版以來的重要變更

androidx.media2 現已完全淘汰。請改用 androidx.media3。

1.3.0-rc01 版

2023 年 12 月 13 日

發布了 androidx.media2:media2-*:1.3.0-rc01，且自 Media2 1.3.0-beta01 版本以來皆無異動。查看 1.3.0-rc01 版的修訂項目。

1.3.0-beta01 版

2023 年 11 月 29 日

發布了 androidx.media2:media2-*:1.3.0-beta01，且自 Media2 1.3.0-alpha01 版本以來皆無異動。1.3.0-beta01 版本包含以下修訂項目。

1.3.0-alpha01 版

2023 年 11 月 15 日

發布 androidx.media2:media2-*:1.3.0-alpha01。查看 1.3.0-alpha01 版的修訂項目。

API 變更

androidx.media2 現已完全淘汰。請改用 androidx.media3 (I53164)。

1.2.1 版

2022 年 2 月 9 日

發布 androidx.media2:media2-*:1.2.1。查看 1.2.1 版的修訂項目。

修正錯誤

修正指定 API 33 時檢查自訂 Parcelables 的問題。

1.2.0 版

1.2.0 版本

2021 年 9 月 15 日

發布 androidx.media2:media2-*:1.2.0。1.2.0 版包含此連結所列的修訂項目。

自 1.1.0 版以來的重要變更

支援 (prepare|play)From(MediaId|Uri|Search) AndroidX 媒體互通性
已在 MediaConstants 中新增 MEDIA_URI_PATH_SET_MEDIA_URI 和 MEDIA_URI_QUERY_URI

1.2.0-rc01 版

2021 年 9 月 1 日

發布 androidx.media2:media2-*:1.2.0-rc01。查看 1.2.0-rc01 版的修訂項目。

修正錯誤

修正關閉媒體通知時發生的 ANR (Ifdcc2、b/148011394)

1.2.0-beta01 版

2021 年 6 月 30 日

發布 androidx.media2:media2-*:1.2.0-beta01。查看 1.2.0-beta01 版的修訂項目。

新功能

支援 (prepare|play)From(MediaId|Uri|Search) AndroidX 媒體互通性

API 變更

已在 MediaConstants 中新增 MEDIA_URI_PATH_SET_MEDIA_URI 和 MEDIA_URI_QUERY_URI

1.2.0-alpha01 版

2021 年 4 月 21 日

發布 androidx.media2:media2-*:1.2.0-alpha01。查看 1.2.0-alpha01 版的修訂項。

API 變更

新增對 (prepare|play)From(MediaId|Uri|Search) 的支援 (I13475、b/176949057)

修正錯誤

修正因不必要的同步區塊導致的死結問題。
沒有可播放的項目時重設播放器
允許 onCurrentMediaItemChanged 接受空值的媒體項目
目前的媒體項目變更時更新通知
修正工作階段建立後立即與控制器相容性的互通問題

1.1.3 版本

2021 年 4 月 21 日

發布 androidx.media2:media2-*:1.1.3。1.1.3 版包含此連結所列的修訂項目。

修正錯誤

修正因不必要的同步區塊導致的死結問題。

1.1.2 版本

2021 年 1 月 27 日

發布 androidx.media2:media2-*:1.1.2。1.1.2 版包含此連結所列的修訂項目。

修正錯誤

已修正 VersionedParcelable 發出的 NPE (I1ec28、b/177060207)

1.1.1 版

2020 年 12 月 16 日

發布 androidx.media2:media2-*:1.1.1。1.1.1 版包含此連結所列的修訂項目。

修正錯誤

讓媒體通知在目前的媒體項目變更時更新。

1.1.0 版本

2020 年 12 月 2 日

發布 androidx.media2:media2-*:1.1.0。1.1.0 版本包含以下修訂項目。

自 1.0.0 版起的重大異動

新增更多處理媒體曲目的 API
改善與 AndroidX 媒體庫的互通性
- 新增了 MediaSession#setMediaUri
- 已透過 MediaSession#getSessionCompatToken() 公開 MediaSessionCompat.Token

1.1.0-rc01 版本

2020 年 10 月 28 日

發布 androidx.media2:media2-*:1.1.0-rc01。1.1.0-rc01 版包含此連結所列的修訂項目。

修正 MediaController 在按住鎖定時通知回呼，可能造成死結的問題 (I76c56)
修正 MediaSessionImplBase#isClosed() 在發布的 MediaSessionCompat 呼叫 getCurrentControllerInfo() 時可能會異常終止的問題。(aosp/1423291)。
修正 media2 MediaSession 未將有效佇列項目 ID 設為 PlaybackStateCompat 的問題 (aosp/1421652)
已在繫結至服務時新增 BIND_INCLUDE_CAPABILITIES 標記，這樣無頭媒體應用程式只要具備權限，就能存取位置資訊。這對 Android Auto 應用程式特別實用。(aosp/1440731)。

1.1.0-beta01 版本

2020 年 9 月 16 日

發布 androidx.media2:media2-*:1.1.0-beta01。查看 1.1.0-beta01 版的修訂項。

修正錯誤

媒體項目變更時重設目前位置
連線時傳送中繼資料和緩衝狀態
修正在工作階段和控制器之間傳送大型資料時異常終止的問題
將 <queries> 新增至 Android 11 的 media 和 media2 資訊清單
修正 MediaController.getPlaylist() 的 NPE
不允許使用搜尋指令時，停用「MediaControlView」的進度列
工作階段目前的媒體項目變更時通知 PlaybackStateCompat
修正 SessionPlayer.TrackInfo 的包裹處理

1.1.0-alpha01 版

2020 年 6 月 24 日

發布 androidx.media2:media2-*:1.1.0-alpha01。1.1.0-alpha01 版包含此連結所列的修訂項目。

修正錯誤

修正了更新中繼資料的時機問題 (I45567、b/143999611)
SessionResult 會保留來自 PlayerResult 的 MediaItem (I927b0、b/154885520)
修正 MediaController#setVolumeTo() 可能會變更錯誤串流量的錯誤。(I76870、b/151204736)

1.0.3 版本

2020 年 2 月 19 日

發布了 androidx.media2:media2-*:1.0.3。1.0.3 版的 media2-{common,player,session} 包含這些修訂項目和 1.0.3 版的 media2-widget 含有這些修訂項目

修正錯誤

修正以空值回呼建立 MediaController 時發生 NullPointerException
修正了 MediaPlayer.setMediaItem 之後無法呼叫 onPlaylistChanged() 的問題

1.0.2 版

2020 年 2 月 5 日

發布了 androidx.media2:media2-*:1.0.2。1.0.2 版的 media2-{common,player,session} 包含以下修訂項目和 1.0.2 版的 media2-widget 含有這些修訂項目

修正錯誤

修正了 MediaPlayer#getSelectedTrack() 中的 IndexOutOfBoundsException。(aosp/987003)。
改善 ExoPlayer 呼叫 getDuration() 且媒體項目不存在時的處理方式 (aosp/987484)
修正在 IDLE 狀態中呼叫 getDuration() 時，ExoPlayer 不會擲回 IllegalStateException 的錯誤 (aosp/987246)
不允許針對 media2 使用自訂 Parcelable (aosp/1091056)
修正導致 close() 中懸掛的問題 (aosp/1096455)
MediaBrowser：改善使用 MediaBrowserService 時 subscribe() 中錯誤的處理方式 (aosp/1158057)
修正使用 Framework MediaSession 時發生 MediaController 當機的問題(aosp/1177663)
請勿在連線時透過回呼通知工作階段資訊 (aosp/1195030、b/142925848)
修正可意外從 MediaController 多次傳送 SessionResult 的問題 (aosp/1198634)
修正 MediaController 可能會將不允許的指令傳送至 MediaSession，因此現在 MediaSession 會傳送 RESULT_ERROR_PERMISSION_DENIED (aosp/1204183)
修正 MediaControllerView#setPlayer 不穩定的問題。(aosp/987004)

1.0.1 版

2019 年 10 月 9 日

發布了 androidx.media2:media2-*:1.0.1。androidx.media2:media2-{player, session}:1.0.1 1.0.1 版包含此連結所列的修訂項目，1.0.1 版的 androidx.media2:media2-widget:1.0.1 含有這些修訂項目。

修正錯誤

修正了 MediaItem 的子類別在程序間傳送時的 RuntimeException 問題 (aosp/1098971)
修正 MediaPlayer 在播放播放清單時只會呼叫 onCurrentMediaItemChanged() 一次的問題
修正 MediaPlayer 能夠播放含有超過 2 個項目的播放清單的問題 (aosp/1108440)
修正即使無法看見，播放器仍會繼續在 SurfaceView 上播放的問題
修正了在 setPlayer 之前呼叫 setViewType 時發生的 VideoView 播放問題

1.0.0 版本

2019 年 9 月 5 日

發布了 androidx.media2:media2-*:1.0.0。以下修訂項目包含 media2-{player, session}:1.0.0，以下則 media2-widget:1.0.0 包含的修訂項目。

Media2 1.0.0 的主要功能

Media2 是下列 Media API 的新一代：MediaSession、MediaController、MediaBrowser、MediaBrowserService、VideoView 和 MediaControlView。

media2.player.MediaPlayer
- API 大部分與 android.media.MediaPlayer 相符，而基礎引擎為 ExoPlayer
- 內建音訊焦點和雜訊處理功能
- 實作 SessionPlayer
media2.session.MediaSession
- 提供精細的權限控管機制
- 支援自訂版面配置
- 可輕鬆與 SessionPlayer 搭配使用，例如 androidx.media2.player.MediaPlayer
- 可與 MediaControllerCompat 互通
media2.session.MediaSessionService
- 輕量版 MediaLibraryService
- 提供背景播放的服務生命週期管理
- 可與 MediaControllerCompat 和 MediaBrowserServiceCompat 互通
media2.session.MediaLibraryService
- 更適合瀏覽媒體項目，或是含有大量項目的搜尋結果
- 可與 MediaControllerCompat 和 MediaBrowserServiceCompat 互通
media2.session.MediaController
- 可連結 MediaSession、MediaSessionService 和 MediaLibraryService
- 可與 MediaSessionCompat 和 MediaBrowserServiceCompat 互通
media2.session.MediaBrowser
- 沿用MediaController
- 可連結 MediaSession、MediaSessionService 和 MediaLibraryService
- 可與 MediaSessionCompat 和 MediaBrowserServiceCompat 互通
media2.widget.VideoView
- 含有 android.widget.VideoView 的所有功能
- 提供 TextureView 和 SurfaceView 切換的功能
- 可與 MediaSession 搭配運作
media2.widget.MediaControlView
- 提升外觀和風格
- 含有 android.widget.MediaController 的所有功能
- 提供字幕軌選項、播放速度選擇和全螢幕模式

1.0.0-rc02 版

2019 年 8 月 22 日

「androidx.media2:media2-*:1.0.0-rc02」已發布。這個版本的異動內容可參閱此處。這個版本包含 androidx.media2:media2-widget:1.0.0-rc02。這個版本包含的變更，可按這裡查看。

新功能

當 MediaControlView 隸屬於 VideoView 時，無法再透過 MediaControlView (MCV) 呼叫 setPlayer 或 setController

修正錯誤

MediaControlView：下一個和上一個按鈕只有在下一個或上一個媒體項目時可供點選
MediaControlView：修正了呼叫 onAttachedToWindow() 時 NullPointerException 不穩定的問題
目前的媒體項目有所變更時，Media2 小工具現在可正確處理新媒體項目的中繼資料

2019 年 7 月 2 日

發布 androidx.media2:media2-widget:1.0.0-beta01。您可以前往這裡查看這個版本包含的修訂項目。

新功能

背景播放：您不必在 VideoView 內建立播放器，VideoView 可以採用 SessionPlayer 或 MediaController，讓應用程式能順暢地進入背景播放模式。
已移除與 media2-player 程式庫的依附元件
新增了 onViewTypeChangedListener

API 相關異動

瀏覽權限從公開變更為受保護：
- VideoView.onMeasure(int, int)
- VideoView.onAttachedToWindow()
- VideoView.onDetachedFromWindow()
- MediaControlView.onMeasure(int, int)
已移除：
- VideoView.getSessionToken()
- VideoView.setAudioAttributes(AudioAttributesCompat)
- VideoView.setMedaItem(MediaItem)
- MediaControlView.setSessionToken(SessionToken)
已新增：
- VideoView.setMediaController(MediaController)
- VideoView.getMediaControlView()
- VideoView.setMediaController(MediaController)
- VideoView.setPlayer(SessionPlayer)
- VideoView.setOnViewTypeChangedListener()
- MediaControlView.setPlayer(SessionPlayer)
- MediaControlView.setMediaController(MediaContoller)

1.0.0-rc01 版本

2019 年 6 月 18 日

發布 androidx.media2:media2-common:1.0.0-rc01、androidx.media2:media2-player:1.0.0-rc01 和 androidx.media2:media2-session:1.0.0-rc01。您可以前往這裡查看這個版本包含的修訂項目。

API 相關異動

ListenableFuture 的依附元件已遷移至 Guava 的獨立實作。
請注意，如果您的測試目標必須依附於完整的 Guava 構件，則使用特定版本的 Android Gradle 外掛程式時，可能會發生依附元件解析衝突。如果遇到與 ListenableFuture 相關的 Could not resolve all artifacts 錯誤，可在專案的建構設定中加入 android.dependency.useConstraints=false，以暫時解決問題。我們正在研究 Android Gradle 外掛程式內的永久修正內容，日後就會發布。

1.0.0-beta02 版

2019 年 6 月 5 日

發布 androidx.media2:media2-common:1.0.0-beta02、androidx.media2:media2-player:1.0.0-beta02 和 androidx.media2:media2-session:1.0.0-beta02。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

在 androidx.media.player.MediaPlayer 上設定負的播放速度，可傳回 RESULT_ERROR_BAD_VALUE。
將 Guava ListenableFuture 替換為 Jetpack 實作項目 (aosp/968828)

1.0.0-beta01 版本

2019 年 5 月 7 日

發布 androidx.media2:media2-common:1.0.0-beta01、androidx.media2:media2-player:1.0.0-beta01 和 androidx.media2:media2-session:1.0.0-beta01。您可以前往這裡查看這個版本包含的修訂項目。

新功能

程式庫分為 3 部分：media2-common、media2-player 及 media2-session
針對標示為 @NonNull 的空值引數，將 IllegalPointerException 變更為 NullPointerException。

API 相關異動

推出了 MediaController.Builder
已為 FileMediaItem.Builder 的選填欄位新增 setter 方法
MediaController 和 MediaBrowser 可將應用程式的連線提示傳送至 MediaSession、MediaSessionService 或 MediaLibraryService
部分方法經過重新命名，以便依循 Android 10 Media2 API

1.0.0-alpha04 版

2018 年 12 月 17 日

API 相關異動

下列類別已重新命名：
- MediaPlayer2 → MediaPlayer
- MediaSession2 → MediaSession
- MediaController2 → MediaController
- MediaSessionService2 → MediaSessionService
- MediaLibraryService2 → MediaLibraryService
- MediaBrowser2 → MediaBrowser
- MediaMetadata2 → MediaMetadata
- Rating2 → Rating
- SessionToken2 → SessionToken
- SessionCommand2 → SessionCommand
- SessionCommandGroup2 → SessionCommandGroup
已合併下列類別：
- 已將 DataSourceDesc2 和 MediaItem2 合併為 MediaItem
- 已將 MediaPlaylistAgent 和 MediaPlayerConnector 合併為 SessionPlayer
已新增下列 Rating 的子類別：HeartRating、PercentageRating、StarRating 和 ThumbRating
Media2 現在會使用 ListenableFuture 執行非同步方法

Media2

宣告依附元件

Groovy

Kotlin

意見回饋：

1.3 版

1.3.0 版

1.3.0-rc01 版

1.3.0-beta01 版

1.3.0-alpha01 版

1.2.1 版

1.2.1 版

1.2.0 版

1.2.0 版本

1.2.0-rc01 版

1.2.0-beta01 版

1.2.0-alpha01 版

1.1.3 版本

1.1.3 版本

1.1.2 版本

1.1.2 版本

1.1.1 版

1.1.1 版

1.1.0 版本

1.1.0 版本

1.1.0-rc01 版本

1.1.0-beta01 版本

1.1.0-alpha01 版

1.0.3 版本

1.0.3 版本

1.0.2 版

1.0.2 版

1.0.1 版

1.0.1 版

1.0.0 版本

1.0.0-rc02 版

Media2-Widget 1.0.0-beta01 版本

1.0.0-rc01 版本

1.0.0-beta02 版

1.0.0-beta01 版本

1.0.0-alpha04 版