使用入门

对于简单的用例，ExoPlayer 的使用入门包括以下步骤：

  1. 将 ExoPlayer 添加为项目的依赖项。
  2. 创建一个 ExoPlayer 实例。
  3. 将播放器附加到视图（用于视频输出和用户输入）。
  4. 为玩家准备一个 MediaItem 以供游戏。
  5. 完成后，松开播放器。

下面将详细介绍这些步骤。如需查看完整示例，请参阅主要演示应用中的 PlayerActivity。

将 ExoPlayer 添加为依赖项

添加 ExoPlayer 模块

如需开始使用 AndroidX Media3，最简单的方法是在应用模块的 build.gradle 文件中添加对所需库的 Gradle 依赖项。

例如，如需依赖于支持 DASH 播放的 ExoPlayer 和界面组件，您可以按如下方式添加对这些模块的依赖项：

Kotlin

implementation("androidx.media3:media3-exoplayer:1.5.0")
implementation("androidx.media3:media3-exoplayer-dash:1.5.0")
implementation("androidx.media3:media3-ui:1.5.0")

Groovy

implementation "androidx.media3:media3-exoplayer:1.5.0"
implementation "androidx.media3:media3-exoplayer-dash:1.5.0"
implementation "androidx.media3:media3-ui:1.5.0"

其中，1.5.0 是您的首选版本（如需查找最新版本，请参阅版本说明）。所有模块的版本必须相同。

AndroidX Media3 包含依赖于外部库来提供其他功能的库模块。其中一些可从 Maven 代码库中获取，而其他一些则必须手动构建。如需了解详情，请浏览库目录并查看各个自述文件。

如需详细了解可用的库模块，请参阅 Google Maven AndroidX Media 页面。

开启 Java 8 支持

如果尚未启用，您需要在依赖于 ExoPlayer 的所有 build.gradle 文件中启用 Java 8 支持，方法是将以下代码添加到 android 部分：

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

创建播放器

您可以使用 ExoPlayer.Builder 创建 ExoPlayer 实例，该实例提供了一系列自定义选项。以下代码是创建实例的最简单示例。

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

线程处理说明

必须从单个应用线程中访问 ExoPlayer 实例。在大多数情况下，这应该是应用的主线程。使用 ExoPlayer 的界面组件或 IMA 扩展程序时，必须使用应用的主线程。

您可以在创建播放器时传递 Looper，以明确指定必须在哪个线程中访问 ExoPlayer 实例。如果未指定 Looper，则使用创建播放器的线程的 Looper；如果该线程没有 Looper，则使用应用主线程的 Looper。在所有情况下，都可以使用 Player.getApplicationLooper 查询必须通过哪个线程访问玩家的 Looper。

如需详细了解 ExoPlayer 的线程模型，请参阅 ExoPlayer Javadoc 的“线程模型”部分。

将播放器附加到视图

ExoPlayer 库提供了一系列用于媒体播放的预构建界面组件。其中包括 PlayerView，它封装了 PlayerControlView、SubtitleView 和用于渲染视频的 Surface。您可以在应用的布局 XML 中添加 PlayerView。例如，如需将播放器绑定到视图，请执行以下操作：

Kotlin

// Bind the player to the view.
playerView.player = player

Java

// Bind the player to the view.
playerView.setPlayer(player);

您还可以将 PlayerControlView 用作独立组件，这对于仅音频用例非常有用。

使用 ExoPlayer 的预构建界面组件是可选操作。对于实现自己的界面的视频应用，可以分别使用 ExoPlayer 的 setVideoSurfaceView、setVideoTextureView、setVideoSurfaceHolder 和 setVideoSurface 方法设置目标 SurfaceView、TextureView、SurfaceHolder 或 Surface。ExoPlayer 的 addTextOutput 方法可用于接收应在播放期间呈现的字幕。

填充播放列表并准备播放器

在 ExoPlayer 中，每一段媒体内容都由 MediaItem 表示。如需播放一段媒体内容，您需要构建相应的 MediaItem，将其添加到播放器，准备播放器，然后调用 play 以开始播放：

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

可以在播放期间更新播放列表，而无需重新准备播放器。如需详细了解如何填充和操作播放列表，请参阅“播放列表”页面。如需详细了解制作媒体内容时可用的不同选项（例如剪辑和附加字幕文件），请前往“媒体内容”页面。

控制播放器

准备好播放器后，您可以通过调用播放器的方法来控制播放。以下是一些最常用的方法：

  • play 和 pause 可开始和暂停播放。
  • seekTo 允许在媒体中跳转。
  • hasPrevious、hasNext、previous 和 next 用于浏览播放列表。
  • setRepeatMode 用于控制媒体是否循环播放以及如何循环播放。
  • setShuffleModeEnabled 用于控制播放列表的随机播放。
  • setPlaybackParameters 用于调整播放速度和音频音高。

如果播放器绑定到 PlayerView 或 PlayerControlView，那么用户与这些组件的互动将导致系统调用播放器上的相应方法。

释放播放器

请务必在不再需要时释放播放器，以便释放视频解码器等有限资源，供其他应用使用。只需调用 ExoPlayer.release 即可实现这一点。