播放列表

播放列表 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 之外，每个媒体项目还可以配置一个自定义标签 (tag)，它可以是应用提供的任何对象。自定义标签的一种用途是为每个媒体项目附加元数据

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);
}

如果更新 UI 所需的元数据是使用自定义标签附加到每个媒体项目的，那么实现方式可能如下所示

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。导致时间轴更新的其他原因包括

  • 在准备好自适应媒体项目后，清单 (manifest) 可用。
  • 在直播流播放期间，清单被定期更新。