使用 Media3 ExoPlayer 创建基本的媒体播放器应用

Jetpack Media3 定义了一个 Player 接口，该接口概述了视频和音频文件播放的基本功能。ExoPlayer 是 Media3 中此接口的默认实现。我们建议使用 ExoPlayer，因为它提供了一整套功能，涵盖了大多数播放用例，并且可以自定义以处理您可能拥有的任何其他用例。ExoPlayer 还抽象出了设备和操作系统碎片，因此您的代码可以在整个 Android 生态系统中保持一致。ExoPlayer 包括：

• 对播放列表的支持
• 对各种渐进式和自适应流式传输 格式的支持
• 对客户端和服务器端广告插播的支持
• 对受 DRM 保护的播放内容的支持

本页将引导您完成构建播放应用的一些关键步骤， 如需了解更多详细信息，您可以前往我们的 Media3 ExoPlayer 完整指南。

使用入门

如需开始使用，请添加对 Jetpack Media3 的 ExoPlayer、UI 和 Common 模块的依赖项：

Kotlin

implementation("androidx.media3:media3-exoplayer:1.11.0")
implementation("androidx.media3:media3-ui:1.11.0")
implementation("androidx.media3:media3-common:1.11.0")

Groovy

implementation "androidx.media3:media3-exoplayer:1.11.0"
implementation "androidx.media3:media3-ui:1.11.0"
implementation "androidx.media3:media3-common:1.11.0"

根据您的用例，您可能还需要 Media3 中的其他模块，例如 exoplayer-dash，用于播放 DASH 格式的流。

请务必将 1.11.0 替换为您偏好的库版本。您可以参阅版本说明，了解最新 版本。

创建媒体播放器

借助 Media3，您可以使用内置实现的 Player 接口，ExoPlayer，也可以构建自己的自定义实现。

创建 ExoPlayer

创建 ExoPlayer 实例的最简单方法如下：

Kotlin

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

Java

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

您可以在媒体播放器所在的 Activity、Fragment 或 Service 的 onCreate() 生命周期方法中创建媒体播放器。

Builder 包含一系列您可能感兴趣 的自定义选项，例如：

• setAudioAttributes()，用于配置音频焦点处理
• setHandleAudioBecomingNoisy() ，用于配置音频输出设备断开连接时的播放行为
• setTrackSelector()，用于配置轨道选择

Media3 提供了一个 PlayerView 界面组件，您可以将其添加到应用的布局文件中。此组件封装了用于播放控件的 PlayerControlView、用于显示字幕的 SubtitleView 和用于渲染视频的 Surface。

准备播放器

使用 媒体项添加到播放列表以进行播放，使用的方法包括 setMediaItem() 和 addMediaItem()。然后，调用 prepare() 以开始 加载媒体并获取必要的资源。

您不应在应用位于前台之前执行这些步骤。如果您的播放器位于 Activity 或 Fragment 中，这意味着在 API 级别 24 及更高级别上，在 onStart() 生命周期方法中准备播放器；在 API 级别 23 及更低级别上，在 onResume() 生命周期方法中准备播放器。对于位于 Service 中的播放器，您可以在 onCreate() 中准备它。如需查看如何实现生命周期方法的 示例，请参阅Exoplayer Codelab。

控制播放器

准备好播放器后，您可以通过调用播放器上的方法（例如以下方法）来控制播放：

• play() 和 pause()，用于开始和暂停播放
• seekTo() ，用于在当前媒体项中寻找某个位置
• seekToNextMediaItem() 和 seekToPreviousMediaItem()，用于在播放列表中导航

当界面组件（例如 PlayerView 或 PlayerControlView）绑定到播放器时，它们会相应地更新。

释放播放器

播放可能需要资源（例如视频 解码器），而这些资源是有限的，因此，当不再需要播放器时，请务必对播放器调用 release() 以释放 资源。

如果您的播放器位于 Activity 或 Fragment 中，请在 API 级别 24 及更高级别上，在 onStop() 生命周期方法中释放播放器；在 API 级别 23 及更低级别上，在 onPause() 方法中释放播放器。对于位于 Service 中的播放器，您可以在 onDestroy() 中释放它。如需查看如何实现生命周期方法的示例，请参阅 Exoplayer Codelab。

使用媒体会话管理播放

在 Android 上，媒体会话提供了一种跨进程边界与媒体播放器进行交互的标准化方式。将媒体会话连接到播放器后 ，您可以对外宣传媒体播放内容，并接收来自外部来源的播放 命令，例如与 系统媒体 控件集成，以便在移动设备和大屏设备上使用。

如需使用媒体会话，请添加对 Media3 会话模块的依赖项：

Kotlin

implementation("androidx.media3:media3-session:1.11.0")

Groovy

implementation "androidx.media3:media3-session:1.11.0"

创建媒体会话

您可以在初始化播放器后创建 MediaSession，如下所示：

Kotlin

val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

Media3 会自动将 Player 的状态与 MediaSession 的状态同步。这适用于任何 Player 实现，包括 ExoPlayer、CastPlayer 或自定义实现。

向其他客户端授予控制权

客户端应用可以实现媒体控制器来控制媒体 会话的播放。如需接收这些请求，请在构建您的 MediaSession时设置回调对象。

当控制器即将连接到您的媒体会话时，系统会调用 onConnect() 方法。您可以使用提供的 ControllerInfo 来决定是 接受还是拒绝该请求。如需查看相关示例，请参阅 Media3 会话演示版应用。

连接后，控制器可以向会话发送播放命令。然后，会话会将这些命令委托给播放器。在 Player 接口中定义的播放和播放列表命令由会话自动处理。

其他回调方法允许您处理自定义 播放命令的请求和修改播放列表等。这些回调类似地 包含 ControllerInfo 对象，因此您可以根据 每个请求确定访问权限控制。

注意： 如果您希望允许控制器向播放器添加媒体项， 请实现 onAddMediaItems() 回调。除了处理来自 Media3 MediaController 的 setMediaItems() 和 addMediaItems() 请求之外，此方法还向后兼容旧版 API，例如 TransportControls.prepareFrom* 和 TransportControls.playFrom*。您可以在会话演示版应用的PlaybackService 中找到 onAddMediaItems() 的实现示例。

在后台播放媒体内容

如需在应用不在前台时继续播放媒体内容（例如播放 音乐、有声读物或播客，即使用户未打开您的应用 ），您的 Player 和 MediaSession 应封装在某个 前台 服务中。Media3 为此提供了 MediaSessionService 接口。

实现 MediaSessionService

创建一个扩展 MediaSessionService 的类，并在 onCreate() 生命周期方法中实例化您的 MediaSession。

Kotlin

class PlaybackService : MediaSessionService() {
    private var mediaSession: MediaSession? = null

    // Create your Player and MediaSession in the onCreate lifecycle event
    override fun onCreate() {
        super.onCreate()
        val player = ExoPlayer.Builder(this).build()
        mediaSession = MediaSession.Builder(this, player).build()
    }

    // Remember to release the player and media session in onDestroy
    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
            mediaSession = null
        }
        super.onDestroy()
    }
}

Java

public class PlaybackService extends MediaSessionService {
    private MediaSession mediaSession = null;

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

    @Override
    public void onDestroy() {
        mediaSession.getPlayer().release();
        mediaSession.release();
        mediaSession = null;
        super.onDestroy();
    }
}

在清单中，声明您的 Service 类，并使用 MediaSessionService intent 过滤器，然后请求 FOREGROUND_SERVICE 权限以运行 前台服务：

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

最后，在您创建的类中，替换 onGetSession() 方法以控制客户端对媒体会话的访问。返回 MediaSession 以接受连接请求，或返回 null 以拒绝该请求。

Kotlin

// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession

Java

@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}

连接到界面

现在，您的媒体会话位于与播放器界面所在的 Activity 或 Fragment 分开的 Service 中，您可以使用 MediaController 将它们关联在一起。在包含界面的 Activity 或 Fragment 的 onStart() 方法中，为 MediaSession 创建 SessionToken，然后使用 SessionToken 构建 MediaController。构建 MediaController 是异步发生的。

Kotlin

override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}

Java

@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}

MediaController 实现 Player 接口，因此您可以使用相同的方法（例如 play() 和 pause()）来控制播放。与其他 组件类似，请记得在不再需要 MediaController 时，通过调用 MediaController.releaseFuture() 来释放它，该操作在 onStop() 生命周期方法中进行，适用于 Activity。

发布通知

前台服务在处于活动状态时必须发布通知。A MediaSessionService 会自动以 MediaNotification 的形式为您创建 MediaStyle 通知 。如需提供自定义 通知，请使用 MediaNotification.Provider 或通过创建提供程序接口的自定义 实现来创建 DefaultMediaNotificationProvider.Builder。使用 setMediaNotificationProvider 将提供方添加到您的 MediaSession。

宣传您的内容库

MediaLibraryService 基于 MediaSessionService 构建，允许客户端应用浏览您的应用提供的媒体内容。客户端应用实现 MediaBrowser 以与您的 MediaLibraryService 互动。

实现 MediaLibraryService 与实现 MediaSessionService 类似，只不过在 onGetSession() 中，您应返回 MediaLibrarySession 而不是 MediaSession。与 MediaSession.Callback 相比，MediaLibrarySession.Callback 包含其他方法，允许浏览器客户端浏览您的库服务提供的内容。

与 MediaSessionService 类似，在清单中声明 MediaLibraryService 并请求 FOREGROUND_SERVICE 权限以运行前台服务：

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

上面的示例包含 MediaLibraryService 和旧版 MediaBrowserService 的 intent 过滤器，以实现向后兼容性。其他 intent 过滤器使使用 MediaBrowserCompat API 的客户端应用能够识别您的 Service。

MediaLibrarySession 可让您以树形结构提供内容库，其中包含单个根 MediaItem。树中的每个 MediaItem 都可以包含任意数量的子 MediaItem 节点。您可以根据客户端应用的请求提供不同的根或不同的树。例如，您返回给正在查找推荐媒体项列表的客户端的树可能仅包含根 MediaItem 和单级子 MediaItem 节点，而您返回给不同客户端应用的树可能代表更完整的内容库。

创建 MediaLibrarySession

A MediaLibrarySession 扩展了 MediaSession API 以添加内容浏览 API。与 MediaSession 回调 相比，MediaLibrarySession 回调 添加了以下方法：

• onGetLibraryRoot() ，用于客户端请求内容树的根 MediaItem 时
• onGetChildren() ，用于客户端请求内容树中 MediaItem 的子项时
• onGetSearchResult() ，用于客户端请求给定查询的内容树中的搜索结果时

相关回调方法将包含一个 LibraryParams 对象，其中包含 有关客户端应用感兴趣的内容树类型的 其他信号。