本頁面由 Cloud Translation API 翻譯而成。

播放清單

播放清單 API 是由 Player 介面定義，可由所有 ExoPlayer 實作項目。播放清單可讓多個影片依序播放媒體項目。以下範例說明如何開始播放播放清單含有兩部影片：

Kotlin

// 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()

Java

// 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();

播放清單中的項目可以流暢切換。沒有規定使用相同格式 (例如，一個播放清單可以同時包含這兩種格式) H264 和 VP9 影片)。而且可能是不同類型的網站 ( 播放清單，其中只包含影片、圖片和純音訊內容的串流)。您可以使用重複 MediaItem 的播放清單。

修改播放清單

您可透過新增、移動、移除或取代等方式動態修改播放清單媒體項目。只要在播放前和播放期間呼叫對應的播放清單 API 方法：

Kotlin

// Adds a media item at position 1 in the playlist.
player.addMediaItem(/* index= */ 1, MediaItem.fromUri(thirdUri))
// Moves the third media item from position 2 to the start of the playlist.
player.moveMediaItem(/* currentIndex= */ 2, /* newIndex= */ 0)
// Removes the first item from the playlist.
player.removeMediaItem(/* index= */ 0)
// Replace the second item in the playlist.
player.replaceMediaItem(/* index= */ 1, MediaItem.fromUri(newUri))

Java

// Adds a media item at position 1 in the playlist.
player.addMediaItem(/* index= */ 1, MediaItem.fromUri(thirdUri));
// Moves the third media item from position 2 to the start of the playlist.
player.moveMediaItem(/* currentIndex= */ 2, /* newIndex= */ 0);
// Removes the first item from the playlist.
player.removeMediaItem(/* index= */ 0);
// Replace the second item in the playlist.
player.replaceMediaItem(/* index= */ 1, MediaItem.fromUri(newUri));

系統也支援替換及清除整份播放清單：

Kotlin

// Replaces the playlist with a new one.
val newItems: List<MediaItem> = listOf(MediaItem.fromUri(fourthUri), MediaItem.fromUri(fifthUri))
player.setMediaItems(newItems, /* resetPosition= */ true)
// Clears the playlist. If prepared, the player transitions to the ended state.
player.clearMediaItems()

Java

// Replaces the playlist with a new one.
ImmutableList<MediaItem> newItems =
    ImmutableList.of(MediaItem.fromUri(fourthUri), MediaItem.fromUri(fifthUri));
player.setMediaItems(newItems, /* resetPosition= */ true);
// Clears the playlist. If prepared, the player transitions to the ended state.
player.clearMediaItems();

播放器在播放過程中自動處理正確的方式：

如果正在播放目前播放的「MediaItem」位置移動，播放過程不會中斷，而且完成後就會播放新的續版
如果移除目前正在播放的「MediaItem」，播放器會自動移除播放第一個剩餘的後續資產；如果沒有，請轉換至已結束狀態這些繼子確實存在
如果正在更換正在播放的「MediaItem」，播放時不會中斷如果 MediaItem 中沒有任何與播放相關的屬性已變更。例如，您可以更新 MediaItem.MediaMetadata 欄位，在大多數情況下都不會影響播放。

查詢播放清單

您可以使用 Player.getMediaItemCount 和 Player.getMediaItemAt。你可以查詢目前正在播放的媒體項目呼叫 Player.getCurrentMediaItem。其他的例如 Player.hasNextMediaItem 或 Player.getNextMediaItemIndex 簡化播放清單的導覽方式

重複模式

播放器支援 3 種重複模式，可以隨時選擇 Player.setRepeatMode：

Player.REPEAT_MODE_OFF：播放清單不會重複播放，播放器會將轉換至 Player.STATE_ENDED 。
Player.REPEAT_MODE_ONE：目前項目會在無限迴圈中重複。 Player.seekToNextMediaItem 等方法會忽略此方法，並使下一個項目會在無限迴圈中重複。
Player.REPEAT_MODE_ALL：整個播放清單重複播放不間斷。

隨機播放模式

您隨時可以透過 Player.setShuffleModeEnabled。在隨機播放模式下，玩家會並透過預先計算的隨機順序排列播放清單所有項目將播放一次隨機播放模式也可以與 Player.REPEAT_MODE_ALL 結合，重複播放產生相同的隨機順序關閉隨機播放模式後從目前項目從目前項目在播放清單

請注意，由類似 Player.getCurrentMediaItemIndex 一律參考未重組的原始原始版本順序。同樣地，「Player.seekToNextMediaItem」也不會在 player.getCurrentMediaItemIndex() + 1，但根據。如果在播放清單中插入新項目或移除項目，系統會保留其他項目現有的重組順序已盡可能維持不變

設定自訂重組順序

根據預設，播放器支援使用 DefaultShuffleOrder 隨機播放。這可以透過提供自訂重組順序實作的方式進行自訂，或在 DefaultShuffleOrder 建構函式中設定自訂順序：

Kotlin

// Set a custom shuffle order for the 5 items currently in the playlist:
exoPlayer.setShuffleOrder(DefaultShuffleOrder(intArrayOf(3, 1, 0, 4, 2), randomSeed))
// Enable shuffle mode.
exoPlayer.shuffleModeEnabled = true

Java

// Set a custom shuffle order for the 5 items currently in the playlist:
exoPlayer.setShuffleOrder(new DefaultShuffleOrder(new int[] {3, 1, 0, 4, 2}, randomSeed));
// Enable shuffle mode.
exoPlayer.setShuffleModeEnabled(/* shuffleModeEnabled= */ true);

識別播放清單項目

如要識別播放清單項目，可以在建立 MediaItem.mediaId 時設定項目：

Kotlin

// Build a media item with a media ID.
val mediaItem = MediaItem.Builder().setUri(uri).setMediaId(mediaId).build()

Java

// Build a media item with a media ID.
MediaItem mediaItem = new MediaItem.Builder().setUri(uri).setMediaId(mediaId).build();

如果應用程式未明確定義媒體項目的媒體 ID，則這個字串則會使用 URI 表示法

為應用程式資料與播放清單項目建立關聯

除了 ID 以外，每個媒體項目都能透過自訂代碼進行設定可以是任何應用程式提供的物件要附加自訂代碼，其中一種是每個媒體項目的中繼資料

Kotlin

// Build a media item with a custom tag.
val mediaItem = MediaItem.Builder().setUri(uri).setTag(metadata).build()

Java

// Build a media item with a custom tag.
MediaItem mediaItem = new MediaItem.Builder().setUri(uri).setTag(metadata).build();

偵測播放內容移至其他媒體項目的時機

切換到其他媒體項目或開始重複播放相同的內容媒體項目，系統會呼叫 Listener.onMediaItemTransition(MediaItem, @MediaItemTransitionReason)。這個回呼接收新媒體項目，以及 @MediaItemTransitionReason 指出進行轉換的原因。onMediaItemTransition 的常見用途是更新新媒體項目的應用程式 UI：

Kotlin

override fun onMediaItemTransition(
  mediaItem: MediaItem?,
  @MediaItemTransitionReason reason: Int,
) {
  updateUiForPlayingMediaItem(mediaItem)
}

Java

@Override
public void onMediaItemTransition(
    @Nullable MediaItem mediaItem, @MediaItemTransitionReason int reason) {
  updateUiForPlayingMediaItem(mediaItem);
}

如果更新使用者介面所需的中繼資料已附加至每個媒體項目自訂代碼，導入方式可能會如下所示：

Kotlin

override fun onMediaItemTransition(
  mediaItem: MediaItem?,
  @MediaItemTransitionReason reason: Int,
) {
  var metadata: CustomMetadata? = null
  mediaItem?.localConfiguration?.let { localConfiguration ->
    metadata = localConfiguration.tag as? CustomMetadata
  }
  updateUiForPlayingMediaItem(metadata)
}

Java

@Override
public void onMediaItemTransition(
    @Nullable MediaItem mediaItem, @MediaItemTransitionReason int reason) {
  @Nullable CustomMetadata metadata = null;
  if (mediaItem != null && mediaItem.localConfiguration != null) {
    metadata = (CustomMetadata) mediaItem.localConfiguration.tag;
  }
  updateUiForPlayingMediaItem(metadata);
}

偵測播放清單變更的時間

新增、移除或移動媒體項目時已呼叫 Listener.onTimelineChanged(Timeline, @TimelineChangeReason) 立即取得 TIMELINE_CHANGE_REASON_PLAYLIST_CHANGED 認證。這個回呼為就會呼叫這類呼叫

Kotlin

override fun onTimelineChanged(timeline: Timeline, @TimelineChangeReason reason: Int) {
  if (reason == Player.TIMELINE_CHANGE_REASON_PLAYLIST_CHANGED) {
    // Update the UI according to the modified playlist (add, move or remove).
    updateUiForPlaylist(timeline)
  }
}

Java

@Override
public void onTimelineChanged(Timeline timeline, @TimelineChangeReason int reason) {
  if (reason == TIMELINE_CHANGE_REASON_PLAYLIST_CHANGED) {
    // Update the UI according to the modified playlist (add, move or remove).
    updateUiForPlaylist(timeline);
  }
}

播放清單中媒體項目的時間長度等資訊可用的資源，系統會更新 Timeline，並呼叫 onTimelineChanged 搭配 TIMELINE_CHANGE_REASON_SOURCE_UPDATE。其他可能導致時間軸更新包括：

準備自動調整媒體項目後可供使用的資訊清單。
會在直播播放期間定期更新的資訊清單。