管理及播放內容

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

本頁面涵蓋下列主題：

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

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

新增媒體項目本身不會導致預先載入管理工具開始載入內容。如要觸發預先載入，請在預先載入管理工具中使優先順序失效。

val initialMediaItems = pullMediaItemsFromService(/* count= */ 20);
for (index in 0 until initialMediaItems.size) {
  preloadManager.add(initialMediaItems.get(index), /* rankingData= */ index)
}
// items aren't actually loaded yet! need to call invalidate() after this

程式碼重點

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

在預先載入管理工具中使優先順序失效

如要觸發預先載入管理工具開始預先載入內容，您需要呼叫 invalidate()，告知預先載入管理工具項目的優先順序已過時。在下列情況下，您應該這麼做：

  • 將新媒體項目新增至預先載入管理工具，或移除媒體項目。 如果要新增或移除多個項目，請先全部新增，然後呼叫 invalidate()。
  • 使用者從一個媒體項目切換到另一個項目時。在這種情況下，請務必先更新目前的播放索引，再呼叫 invalidate()，如「擷取及播放內容」一文所述。

當您使預先載入管理工具失效時，系統會呼叫您建立的 TargetPreloadStatusControl，瞭解應從每個項目載入多少內容。然後依優先順序 (由高到低) 載入每個項目的內容。

preloadManager.invalidate()

程式碼重點

  • 呼叫 invalidate() 會觸發預先載入管理工具，重新評估其所知的每個媒體項目的優先順序。因此，如果您要對預先載入管理工具進行大量變更，請先完成變更，再呼叫 invalidate()。

擷取及播放媒體

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

// When a media item is about to display on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
    player.setMediaSource(mediaSource)
}
player.prepare()

// When the media item is displaying at the center of the screen
player.play()
preloadManager.setCurrentPlayingIndex(currentIndex)

// Need to call invalidate() to update the priorities
preloadManager.invalidate()

程式碼重點

  • player 是應用程式用來播放內容的 Media3 ExoPlayer。您必須呼叫用於建立預先載入管理工具的相同建構工具，藉此建立播放器 DefaultPreloadManager.Builder.buildExoPlayer()。
  • 使用者切換至新的媒體項目時，應用程式會呼叫 getMediaSource()，從預先載入管理工具取得媒體來源。這必須是mediaItem您已新增至預先載入管理工具的資源。如果預先載入管理工具尚未開始載入內容，也沒關係；在這種情況下，系統會傳回沒有預先載入資料的 MediaSource。舉例來說，如果使用者突然在輪轉介面中大幅跳轉，就可能發生這種情況。
  • 使用者播放新媒體項目後，請呼叫 setCurrentPlayingIndex，告知預先載入管理工具新項目在輪播中的位置。預先載入管理工具需要這項資訊，才能優先載入下一個項目。更新目前的索引後，呼叫 invalidate()，讓預先載入管理工具重新判斷每個項目的優先順序。

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

為確保預先載入管理工具的效率，請移除預先載入管理工具不再需要追蹤的項目。你也可以移除仍在輪播介面中，但距離使用者目前位置很遠的項目。舉例來說，如果某個項目與使用者觀看的內容相差超過 15 個項目，您可能會決定不必預先載入該項目。在這種情況下，您會在物品離得太遠時移除物品。如果使用者再次靠近已移除的項目，您隨時可以重新新增這些項目。

preloadManager.remove(mediaItem)

程式碼重點

完成後釋放預先載入管理員

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

preloadManager.release()

程式碼重點

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