使用 Media3 ExoPlayer 建立基本媒體播放器應用程式

Jetpack Media3 定義了 Player 介面，概述影片和音訊檔案的基本播放功能。ExoPlayer 是 Media3 中此介面的預設實作方式。我們建議您使用 ExoPlayer，因為它提供完整的功能組合，涵蓋大多數的播放用途，而且可自訂處理您可能遇到的任何其他用途。ExoPlayer 也會抽離裝置和作業系統的分散現象，讓程式碼在整個 Android 生態系統中一致運作。ExoPlayer 包含以下項目：

本頁會逐步說明建構播放應用程式的一些重要步驟。如需更多詳細資訊，請參閱 Media3 ExoPlayer 的完整指南。

開始使用

如要開始使用，請在 Jetpack Media3 的 ExoPlayer、UI 和 Common 模組上新增依附元件：

implementation "androidx.media3:media3-exoplayer:1.4.1"
implementation "androidx.media3:media3-ui:1.4.1"
implementation "androidx.media3:media3-common:1.4.1"

視用途而定，您可能還需要 Media3 的其他模組，例如 exoplayer-dash，才能播放 DASH 格式的串流。

請務必將 1.4.1 替換為您偏好的程式庫版本。您可以參閱版本資訊，查看最新版本。

建立媒體播放器

使用 Media3 時，您可以使用隨附的 Player 介面 ExoPlayer 實作項目，也可以自行建立自訂實作項目。

建立 ExoPlayer

建立 ExoPlayer 例項最簡單的方式如下：

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

您可以在 Activity、Fragment 或 Service 的 onCreate() 生命週期方法中建立媒體播放器。

Builder 包含您可能會感興趣的一系列自訂選項，例如：

Media3 提供 PlayerView UI 元件，可納入應用程式的版面配置檔案。這個元件會封裝 PlayerControlView 以便播放控制項、SubtitleView 以便顯示字幕，以及 Surface 以便轉譯影片。

準備播放器

將媒體項目新增至播放清單，以便透過 setMediaItem() 和 addMediaItem() 等方法播放。接著，呼叫 prepare() 開始載入媒體並取得必要資源。

應用程式處於前景之前，請勿執行這些步驟。如果播放器位於 Activity 或 Fragment，表示您是在 API 級別 24 以上版本的 onStart() 生命週期方法中，或在 API 級別 23 以下版本的 onResume() 生命週期方法中準備播放器。如果玩家位於 Service 中，您可以在 onCreate() 中準備。

控制播放器

玩家準備好後，您可以透過呼叫播放器的方法控製播放，例如：

PlayerView 或 PlayerControlView 等 UI 元件會在繫結至播放器時，相應更新。

釋放播放器

播放作業可能需要資源 (例如影片解碼器)，而這些資源的供應量有限，因此請務必在不再需要播放器時，在播放器上呼叫 release()，釋出資源。

如果播放器位於 Activity 或 Fragment 中，請在 API 級別 24 以上版本的 onStop() 生命週期方法中釋出播放器，或在 API 級別 23 以下版本的 onPause() 方法中釋出播放器。如果玩家位於 Service，您可以在 onDestroy() 中發布該玩家。

使用媒體工作階段管理播放

在 Android 上，媒體工作階段提供跨程序邊界與媒體播放器互動的標準化方式。將媒體工作階段連結至播放器，即可在外部宣傳媒體播放內容，並接收來自外部來源的播放指令，例如在行動裝置和大螢幕裝置上整合系統媒體控制項。

如要使用媒體工作階段，請為 Media3 工作階段模組新增依附元件：

implementation "androidx.media3:media3-session:1.4.1"

建立媒體工作階段

將播放器初始化後，您可以依下列方式建立 MediaSession：

Kotlin

val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

Media3 會自動將 Player 的狀態與 MediaSession 的狀態同步。這項功能適用於所有 Player 實作項目，包括 ExoPlayer、CastPlayer 或自訂實作項目。

將控制權授予其他用戶端

用戶端應用程式可以實作媒體控制器，控制媒體工作階段的播放。如要接收這些要求，請在建構 MediaSession 時設定回呼物件。

當控制器要連線至媒體工作階段時，系統會呼叫 onConnect() 方法。您可以使用提供的 ControllerInfo 決定是否要接受或拒絕要求。詳情請看 Media3 Session 試用版應用程式。

連線後，控制器就能傳送播放指令給工作階段。然後，工作階段會將這些指令委派給播放器。在 Player 介面中定義的播放和播放清單指令會由工作階段自動處理。

其他回呼方法可讓您處理自訂播放指令和修改播放清單等要求。這些回呼同樣包含 ControllerInfo 物件，因此您可以根據個別要求來決定存取控管。

在背景播放媒體

如要在應用程式不在前景時繼續播放媒體 (例如播放音樂、有聲書或 Podcast)，讓使用者在未開啟應用程式的情況下，Player 和 MediaSession 應封裝在前景服務中。為此，Media3 提供 MediaSessionService 介面。

實作 MediaSessionService

建立可擴充 MediaSessionService 的類別，並在 onCreate() 生命週期方法中例項化 MediaSession。

Kotlin

class PlaybackService : MediaSessionService() {
    private var mediaSession: MediaSession? = null

    // Create your Player and MediaSession in the onCreate lifecycle event
    override fun onCreate() {
        super.onCreate()
        val player = ExoPlayer.Builder(this).build()
        mediaSession = MediaSession.Builder(this, player).build()
    }

    // Remember to release the player and media session in onDestroy
    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
            mediaSession = null
        }
        super.onDestroy()
    }
}

Java

public class PlaybackService extends MediaSessionService {
    private MediaSession mediaSession = null;

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

    @Override
    public void onDestroy() {
        mediaSession.getPlayer().release();
        mediaSession.release();
        mediaSession = null;
        super.onDestroy();
    }
}

在資訊清單中，Service 類別會使用 MediaSessionService 意圖篩選器，並要求 FOREGROUND_SERVICE 權限來執行前景服務：

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

最後，請在您建立的類別中覆寫 onGetSession() 方法，以便控管用戶端對媒體工作階段的存取權。傳回 MediaSession 以接受連線要求，或傳回 null 以拒絕要求。

Kotlin

// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession

Java

@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}

連線至使用者介面

由於媒體工作階段位於 Service 中，而非播放器 UI 所在的 Activity 或 Fragment，因此您可以使用 MediaController 將這兩者連結在一起。在 Activity 或 Fragment 的 onStart() 方法中，為 MediaSession 建立 SessionToken，然後使用 SessionToken 建構 MediaController。建構 MediaController 會以非同步方式進行。

Kotlin

override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}

Java

@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}

MediaController 會實作 Player 介面，因此您可以使用相同的方法 (例如 play() 和 pause()) 控製播放。與其他元件類似，請記得不再需要使用 MediaController 時 (例如 Activity 的 onStop() 生命週期方法)，方法是呼叫 MediaController.releaseFuture()。

發布通知

前景服務必須在啟用時發布通知。MediaSessionService 會以 MediaNotification 的形式自動為您建立 MediaStyle 通知。如要提供自訂通知，請使用 DefaultMediaNotificationProvider.Builder 建立 MediaNotification.Provider，或建立自訂的供應商介面實作方式。使用 setMediaNotificationProvider 將供應商新增至 MediaSession。

宣傳內容庫

MediaLibraryService 可在 MediaSessionService 上建構，讓用戶端應用程式瀏覽應用程式提供的媒體內容。用戶端應用程式會實作 MediaBrowser，與 MediaLibraryService 互動。

實作 MediaLibraryService 與實作 MediaSessionService 類似，差別只在於在 onGetSession() 中，您應傳回 MediaLibrarySession，而非 MediaSession。與 MediaSession.Callback 相比，MediaLibrarySession.Callback 包含其他方法，可讓瀏覽器用戶端瀏覽程式庫服務提供的內容。

與 MediaSessionService 類似，請在資訊清單中宣告 MediaLibraryService，並要求 FOREGROUND_SERVICE 權限以執行前景服務：

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

上述範例包含 MediaLibraryService 和舊版 MediaBrowserService 的意圖篩選器，以便回溯相容。額外的意圖篩選器可讓使用 MediaBrowserCompat API 的用戶端應用程式辨識您的 Service。

MediaLibrarySession 可讓您以樹狀結構提供內容資料庫，並包含單一根目錄 MediaItem。樹狀結構中的每個 MediaItem 都可以擁有任意數量的子項 MediaItem 節點。您可以根據用戶端應用程式的要求，提供不同的根目錄或樹狀結構。舉例來說，如果您要傳回建議媒體項目清單給用戶端，傳回的樹狀結構可能只包含根 MediaItem 和單一層級的子 MediaItem 節點，但傳回給其他用戶端應用程式的樹狀結構可能會代表更完整的內容資料庫。

建立 MediaLibrarySession

MediaLibrarySession 可擴充 MediaSession API，用於新增內容瀏覽 API。相較於 MediaSession 回呼，MediaLibrarySession 回呼會新增以下方法：

  • onGetLibraryRoot() 用於用戶端要求內容樹狀結構的根目錄 MediaItem
  • onGetChildren() 用於用戶端要求內容樹狀結構中 MediaItem 的子項
  • onGetSearchResult() 用於當用戶端針對特定查詢要求內容樹狀結構中的搜尋結果時

相關的回呼方法將包含 LibraryParams 物件，並提供有關用戶端應用程式感興趣的內容樹狀結構類型的其他信號。