開始使用

如要開始使用 ExoPlayer，請按照下列步驟操作：

1. 將 ExoPlayer 新增為專案的依附元件。
2. 建立 ExoPlayer 執行個體。
3. 將播放器附加至檢視畫面 (用於影片輸出和使用者輸入)。
4. 準備播放器，並提供要播放的 MediaItem。
5. 完成後，請釋放播放器。

我們稍後會進一步說明這些步驟。如需完整範例，請參閱主要試用版應用程式中的 PlayerActivity。

將 ExoPlayer 新增為依附元件

如要在應用程式中使用 ExoPlayer，請新增必要模組並啟用 Java 8 支援。

新增 ExoPlayer 模組

如要開始使用 AndroidX Media3，最簡單的方法是在應用程式模組的 build.gradle 檔案中，新增所需程式庫的 Gradle 依附元件。

舉例來說，如要依附支援 DASH 播放功能和 UI 元件的 ExoPlayer，可以新增模組依附元件，如下所示：

implementation("androidx.media3:media3-exoplayer:1.11.1")
implementation("androidx.media3:media3-exoplayer-dash:1.11.1")
implementation("androidx.media3:media3-ui:1.11.1")
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

其中 1.11.1 是您偏好的版本 (如要查看最新版本，請參閱版本資訊)。所有模組都必須使用相同版本。

AndroidX Media3 具有依附外部程式庫的程式庫模組，可提供額外功能。有些可從 Maven 存放區取得，有些則必須手動建構。瀏覽程式庫目錄，並查看個別 README 檔案，瞭解詳情。

如要進一步瞭解可用的程式庫模組，請參閱 Google Maven AndroidX Media 頁面。

開啟 Java 8 支援

如果尚未啟用，您必須在所有依賴 ExoPlayer 的 build.gradle 檔案中，至少啟用 Java 8 支援，方法是在 android 區段中加入以下內容：

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

建立播放器

您可以使用 ExoPlayer.Builder 建立 ExoPlayer 執行個體，其中提供多種自訂選項。以下程式碼是建立執行個體的最簡單範例。

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

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

執行緒注意事項

ExoPlayer 執行個體必須透過單一應用程式執行緒存取。在大多數情況下，這應該是應用程式的主要執行緒。使用 ExoPlayer 的 UI 元件或 IMA 擴充功能時，必須使用應用程式的主要執行緒。

建立播放器時，您可以傳遞 Looper，明確指定存取 ExoPlayer 執行個體的執行緒。如未指定 Looper，系統會使用建立播放器的執行緒 Looper，如果該執行緒沒有 Looper，則會使用應用程式主執行緒的 Looper。在所有情況下，您都可以使用 Player.getApplicationLooper 查詢必須存取播放器的執行緒 Looper。

如要進一步瞭解 ExoPlayer 的執行緒模型，請參閱 ExoPlayer Javadoc 的「執行緒模型」一節。

將播放器附加至檢視畫面

media3-ui 程式庫提供一系列預先建構的媒體播放 UI 元件。包括 PlayerView，其中封裝了 PlayerControlView、SubtitleView 和 Surface，影片會算繪到這些項目上。PlayerView 可以包含在應用程式的版面配置 XML 中。舉例來說，如要將播放器繫結至檢視畫面，請按照下列步驟操作：

// Bind the player to the view.
playerView.player = player
HelloWorld.kt

// Bind the player to the view.
playerView.setPlayer(player);
HelloWorld.java

您可以選擇是否使用 Media3 預先建構的 UI 元件。如果影片應用程式實作自己的 UI，則可分別使用 Player 的 setVideoSurfaceView、setVideoTextureView、setVideoSurfaceHolder 和 setVideoSurface 方法，設定目標 SurfaceView、TextureView、SurfaceHolder 或 Surface。Listener.onCues 回呼可用於接收應在播放期間算繪的字幕，setImageOutput 則可用於接收解碼圖片。

為提供更舒適的使用者體驗，建議您新增 keepScreenOn 屬性。您可以在背景工作頁面中，調查讓裝置保持喚醒狀態的其他動作。

android:keepScreenOn="true"

如果應用程式使用 Jetpack Compose 做為 UI，您可以使用 media3-ui-compose-material3 程式庫中的 Player 可組合函式。Player 會顯示影片，並包含播放控制項版位的預先填入值。如要將 androidx.media3.common.Player 物件附加至 androidx.media3.ui.compose.material3.Player 可組合項，只要將其做為引數傳遞即可：

// Bind the player to the composable.
Player(player = player)
HelloWorld.kt

如要進一步瞭解如何使用 Media3 UI 元件及自訂這些元件，請參閱「UI 頁面」。

填入播放清單並準備播放器

在 ExoPlayer 中，每項媒體都以 MediaItem 表示。如要播放媒體，您需要建構對應的 MediaItem、將其新增至播放器、準備播放器，然後呼叫 play 開始播放：

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

ExoPlayer 直接支援播放清單，因此可以準備多個媒體項目，讓播放器依序播放：

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

播放清單可在播放期間更新，不必再次準備播放器。如要進一步瞭解如何填入及操控播放清單，請參閱「播放清單」頁面。如要進一步瞭解建立媒體項目時可用的不同選項，例如剪輯和附加字幕檔案，請參閱商品頁面。

控制播放器

播放器準備就緒後，您可以呼叫播放器的方法來控制播放。以下是一些最常用的方法：

• play 和 pause 可開始及暫停播放。
• seekTo 允許在媒體中跳轉。
• hasPrevious、hasNext、previous 和 next 可用於瀏覽播放清單。
• setRepeatMode 控制是否要循環播放媒體，以及循環播放的方式。
• setShuffleModeEnabled可控制播放清單隨機播放。
• setPlaybackParameters會調整播放速度和音訊音高。

如果播放器繫結至 PlayerView 或 PlayerControlView，則使用者與這些元件互動時，系統會叫用播放器上的對應方法。

釋出球員

請務必在不再需要播放器時釋出播放器，釋出影片解碼器等有限資源，供其他應用程式使用。方法是呼叫 ExoPlayer.release。