开始使用

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

Groovy

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

其中,1.3.0 是您的首选版本(如需获取最新版本,请参阅版本说明)。所有模块的版本都必须相同。

AndroidX Media3 具有库模块,这些模块依赖于外部库来提供附加功能。其中一些映像可从 Maven 制品库获取,另一些则必须手动构建。浏览库目录,并查看各个 README 文件以了解详情。

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

开启 Java 8 支持

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

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 库提供了一系列用于媒体播放的预构建界面组件。这些 API 包括 PlayerView,它封装了 PlayerControlViewSubtitleViewSurface(用于渲染视频)。PlayerView 可包含在应用的布局 XML 中。例如,如需将播放器绑定到视图,请使用以下代码:

Kotlin

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

Java

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

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

您可以选择使用 ExoPlayer 的预构建界面组件。对于实现自己的界面的视频应用,可以分别使用 ExoPlayer 的 setVideoSurfaceViewsetVideoTextureViewsetVideoSurfaceHoldersetVideoSurface 方法设置目标 SurfaceViewTextureViewSurfaceHolderSurface。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();

播放列表可在播放期间更新,而无需再次准备播放器。如需详细了解如何填充和操控播放列表,请参阅“播放列表”页面。如需详细了解构建媒体项(例如剪辑和附加字幕文件)时可用的不同选项,请参阅“媒体项”页面

控制播放器

播放器准备就绪后,即可通过对播放器调用方法来控制播放。下面是一些最常用的方法:

  • 使用 playpause 开始和暂停播放。
  • seekTo 允许在媒体内跳转。
  • hasPrevioushasNextpreviousnext 允许浏览播放列表。
  • setRepeatMode 用于控制媒体是否循环播放以及如何循环播放。
  • setShuffleModeEnabled 用于控制播放列表随机播放。
  • setPlaybackParameters:可调整播放速度和音调。

如果播放器已绑定到 PlayerViewPlayerControlView,则用户与这些组件的互动会导致调用播放器上的相应方法。

释放播放器

请务必在不再需要播放器时将其释放,以便释放视频解码器等有限的资源以供其他应用使用。这可以通过调用 ExoPlayer.release 来实现。