播放清單

播放清單 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.getMediaItemCountPlayer.getMediaItemAt。你可以查詢目前正在播放的媒體項目 呼叫 Player.getCurrentMediaItem。其他的 例如 Player.hasNextMediaItemPlayer.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。其他可能導致 時間軸更新包括:

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