管理及播放內容

本頁說明如何使用預先載入管理工具管理影片內容。使用預先載入管理工具，可以為使用者提供更優質的體驗；當使用者從一個媒體項目切換到另一個媒體項目時，播放作業會更快開始，因為管理工具已載入部分內容。

本頁面涵蓋下列主題：

將媒體項目新增至預先載入管理工具

您必須告知預先載入管理工具要追蹤哪些媒體項目。舉例來說，如果應用程式有影片輪轉介面，請將影片新增至預先載入管理工具。視用途而定，您可以新增所有影片，或只新增目前播放影片附近的影片。您也可以稍後再將新項目新增至預先載入管理工具。

如要這麼做，請使用 addMediaItems (或 addMediaSources) 等批次新增方法。或者，您也可以呼叫 add (或 addMediaSource) 來個別新增媒體項目。不過，個別新增媒體項目不會自動觸發預先載入。使用個別方法時，您必須在新增項目後明確呼叫 invalidate，指示預先載入管理工具更新優先順序並開始預先載入。

val initialMediaItems = pullMediaItemsFromService(count = 20)
val rankingDataList = initialMediaItems.indices.toList()
preloadManager.addMediaItems(initialMediaItems, rankingDataList)

程式碼重點

  • 以下程式碼片段說明如何在建立預先載入管理工具後，以批次模式初步填入資料。您可以呼叫 addMediaItems，將項目新增至現有且已填入資料的預先載入管理工具。
  • 在這個程式碼片段中，pullMediaItemsFromService() 是應用程式擷取要播放內容清單的邏輯。程式碼會呼叫該方法，擷取最多 20 個項目的清單。
  • preloadManager 是在「建立 DefaultPreloadManager」中建立的 DefaultPreloadManager。
  • 預先載入管理工具會使用 rankingData 值，判斷各個媒體項目的優先順序。在 DefaultPreloadManager 中，rankingData 是代表項目在輪轉介面中位置的整數。預先載入管理工具會根據每個項目與目前播放項目的距離，決定優先順序。

擷取及播放媒體

當使用者切換至新的媒體項目時，您需要從預先載入管理工具取得媒體項目。如果預先載入管理工具已載入任何內容，播放速度會比未使用預先載入管理工具時更快。如果預先載入管理工具尚未載入該項目的內容，內容會正常播放。

您也需要呼叫 setCurrentPlayingIndex，更新預先載入管理工具上目前播放的索引，讓預先載入管理工具判斷日後預先載入作業的優先順序。

// When a media item is about to be displayed on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
  player.setMediaSource(mediaSource)
} else {
  // If the mediaSource is null, its mediaItem hasn't been added to the preload
  // manager yet. Send it directly to the player when it's about to play.
  player.setMediaItem(mediaItem)
}
player.prepare()

// When the media item is being displayed at the center of the screen ("in focus")
player.play()
// Update the current playing index to let the preload manager know where the user
// is in the carousel/pagination/list.
preloadManager.setCurrentPlayingIndex(currentIndex)

程式碼重點

  • player 是應用程式用來播放內容的 Media3 ExoPlayer。您必須在用於建立預先載入管理工具的建構工具上呼叫 DefaultPreloadManager.Builder.buildExoPlayer()，才能建立該播放器。
  • 使用者切換至新的媒體項目時，應用程式會呼叫 getMediaSource()，從預先載入管理工具取得媒體來源。這必須是您已新增至預先載入管理工具的 mediaItem。如果預先載入管理工具尚未開始載入內容，則會傳回不含預先載入資料的 MediaSource。舉例來說，如果使用者突然在輪轉介面中跳到很前面的位置，就可能發生這種情況。
  • 使用者播放新的媒體項目後，請呼叫 setCurrentPlayingIndex，告知預先載入管理工具新項目在輪轉介面中的位置。預先載入管理工具需要這項資訊，才能優先載入下一個項目。

從預先載入管理工具中移除項目

為維持預先載入管理工具的效率，請移除預先載入管理工具不再需要追蹤的項目。您也可以移除仍在輪轉介面中，但距離使用者目前位置較遠的項目。舉例來說，您可以決定如果某個項目與使用者正在觀看的項目相距超過 15 個項目，就不需要預先載入。在這種情況下，您會在項目距離這麼遠時將其移除。如果使用者移回這些移除的項目，您隨時可以加回這些項目。

如要移除多個媒體項目，可以使用 removeMediaItems (或 removeMediaSources)。您也可以呼叫 remove (或 removeMediaSource) 來個別移除媒體項目。

preloadManager.removeMediaItems(mediaItemsToRemove)

程式碼重點

  • 如要從預先載入管理工具中移除「所有」項目，可以呼叫 reset()，而非 remove()。如需變更輪轉介面中的所有項目，這個方法非常實用。在這種情況下，移除項目後，您需要將新項目新增至預先載入管理工具。

使用完畢後，請釋放預先載入管理工具

不再需要預先載入管理工具時，請務必釋出，以釋放資源。特別是，請務必在活動刪除時釋出。

preloadManager.release()

程式碼重點

  • 釋出物件後，不得呼叫任何物件方法。
  • 如需建立其他預先載入管理工具，請建立新的 DefaultPreloadManager.Builder，並用來建立 DefaultPreloadManager。請勿嘗試重複使用舊的建構工具。