管理及播放內容

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

本頁面涵蓋下列主題：

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

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

如要執行這項操作，請使用批次新增方法，例如 addMediaItems。或者，您也可以呼叫 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。或者，您也可以呼叫 remove (或 removeMediaSource) 來個別移除媒體項目。

preloadManager.removeMediaItems(mediaItemsToRemove)

程式碼重點

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

完成後釋放預先載入管理工具

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

preloadManager.release()

程式碼重點

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