使用入门

对于简单的用例，开始使用 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.3.1")
implementation("androidx.media3:media3-exoplayer-dash:1.3.1")
implementation("androidx.media3:media3-ui:1.3.1")

Groovy

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

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

AndroidX Media3 具有依赖于外部库来提供附加功能的库模块。有些可从 Maven 制品库获取，而其他则需要手动构建。浏览库目录并查看各 README 文件以了解详情。

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

启用 Java 8 支持

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

启用 MultiDex

如果您的 Gradle minSdkVersion 为 20 或更低版本，您应启用 MultiDex，以防止出现构建错误。

创建播放器

您可以使用 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 来实现。