使用入门

对于简单的使用情形，开始使用 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.8.0")
implementation("androidx.media3:media3-exoplayer-dash:1.8.0")
implementation("androidx.media3:media3-ui:1.8.0")
implementation("androidx.media3:media3-ui-compose:1.8.0")

Groovy

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

其中，1.8.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 扩展服务时，必须使用应用的主线程。

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

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

将播放器附加到视图

ExoPlayer 库提供了一系列用于媒体播放的预构建界面组件。其中包括 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);

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

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

android:keepScreenOn="true"

如需详细了解如何使用 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 即可实现这一点。