使用入门

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

Groovy

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

其中 1.11.1 是您的首选版本（可通过查阅版本说明找到最新版本）。所有模块必须具有相同的版本。

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 的“线程模型”部分。

将播放器附加到视图

media3-ui 库提供了一系列预构建的媒体播放界面组件。其中包括 PlayerView，它将 PlayerControlView、SubtitleView 和 Surface 封装到视频渲染的目标上。PlayerView 可以包含在应用的布局 XML 中。例如，如需将播放器绑定到视图，请使用以下代码：

Kotlin

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

Java

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

Media3 的预构建界面组件是可选的。对于实现自己的界面的视频应用，可以分别使用 Player 的 setVideoSurfaceView、setVideoTextureView、setVideoSurfaceHolder 和 setVideoSurface 方法设置目标 SurfaceView、TextureView、SurfaceHolder 或 Surface。Listener.onCues 回调可用于接收应在播放期间呈现的字幕，setImageOutput 可用于接收解码后的图片。

为了提供更舒适的用户体验，请考虑添加 keepScreenOn 属性。您可以在后台工作页面中调查使设备保持唤醒状态的其他操作。

android:keepScreenOn="true"

如果您的应用使用 Jetpack Compose 作为界面，您可以使用 media3-ui-compose-material3 库中的 Player 可组合项。Player 会显示视频，并包含播放控件槽的预填充值。如需将 androidx.media3.common.Player 对象附加到 androidx.media3.ui.compose.material3.Player 可组合项，只需将其作为参数传递即可：

// Bind the player to the composable.
Player(player = player)

如需详细了解如何使用 Media3 界面组件及其自定义，请参阅界面页面。

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

在 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 来实现。