通过 MediaSession 控制媒体

上次更新日期：2020 年 1 月 22 日

为视频播放添加 MediaSession 支持有什么好处？

媒体会话是连接 Android 平台和媒体应用的重要桥梁。它不仅会告知 Android 媒体内容正在播放，以便平台将媒体操作转发到正确的会话，还可以告知平台正在播放什么内容以及如何对其进行控制。

在您的应用中提供 MediaSession 可为用户带来诸多好处。以下是一些很好的示例。

Google 助理

用户可以在您的应用中，通过语音指令（例如“暂停”、“继续”和“下一个”）轻松与媒体内容互动。系统还可借助媒体内容的元数据弄清当前正在播放什么内容。

Android TV

在大屏幕上，对于使用支持 HDMI-CEC 的电视的用户，您的 Android TV 应用支持使用传统遥控器。由播放/暂停、停止、下一个和上一个按钮发出的命令将传送至您的应用。

屏幕媒体控件

从 Android 4.0（API 级别 14）开始，系统可以访问媒体会话的播放状态和元数据。此功能可让锁定屏幕显示媒体控件和海报图片。此行为因 Android 版本而异。

背景媒体

即使播放媒体内容的应用在后台运行，也可以在上述任意场景中控制媒体。

环境计算

提供媒体相关数据（即正在播放什么内容、如何对其进行控制）可在各个设备之间架起桥梁，以便用户能够以他们喜欢的方式与媒体互动。

您将构建的内容

在本 Codelab 中，您将扩展现有的 Exoplayer 示例，为其添加媒体会话支持。您的应用将：

• 正确反映媒体会话的活跃状态
• 将媒体控件传送到 ExoPlayer
• 将队列中媒体内容的元数据传递到媒体会话中

学习内容

• 媒体会话为何能够为用户提供更丰富的体验
• 如何创建媒体会话并管理其状态
• 如何将媒体会话连接到 ExoPlayer
• 如何在媒体会话的播放队列中添加媒体内容的元数据
• 如何添加其他（自定义）操作

本 Codelab 重点介绍 MediaSession SDK，这里不讨论无关的概念和代码块（包括与 ExoPlayer 实现相关的详细信息），但提供这些内容供您简单复制和粘贴。

所需条件

• 最新版 Android Studio（3.5 或更高版本）
• 开发 Android 应用的基础知识

我们从何处入手？

我们着手点是 ExoPlayer 中的主演示。此演示包含带有屏幕播放控件的视频，但不在一开始就使用媒体会话，非常适合我们将其作为起点并添加媒体会话！

获取 ExoPlayer 示例

我们先从 ExoPlayer 示例开始。通过以下链接从 GitHub 代码库中克隆该示例。

克隆 ExoPlayer 示例

注意：通常，您无需通过源代码获取 ExoPlayer；我们之所以在此这样做，是要从现有示例入手。对于您自己的应用，只需提取 ExoPlayer 依赖项即可。

打开演示

在 Android Studio 中，打开位于 demos/main 下的主演示项目。

Android Studio 将提示您设置 SDK 路径。如果遇到任何问题，可以按照更新 IDE 和 SDK 工具的建议进行操作。

如果系统要求您使用最新版 Gradle，请进行更新。

请花点时间大致了解应用的设计方式。请注意，涉及的 Activity 有两个：SampleChooserActivity 和 PlayerActivity。Codelab 的剩余部分将主要探讨实际播放媒体内容的类 PlayerActivity，因此，请打开这个类，然后转到下一部分。

创建媒体会话

打开 PlayerActivity.java。这个类可创建 ExoPlayer 并管理其函数，例如将视频呈现到屏幕上。在本 Activity 中，我们将把 ExoPlayer 连接到媒体会话。

在类的顶部声明以下两个字段。本部分会用到这些字段。

private MediaSessionCompat mediaSession;
private MediaSessionConnector mediaSessionConnector;

您将需要把“extension-mediasession”项目依赖项添加到“Module: demo”的模块级 build.gradle 中：

implementation project(path: ':extension-mediasession')

请注意，如果您将鼠标悬停在解析 MediaSessionConnector 时发生的错误上，Android Studio 可帮助您自动添加此依赖项：

最后，请通过添加以下内容来解析类导入：

import android.support.v4.media.session.MediaSessionCompat;
import com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector;

注意：在本 Codelab 中，“媒体会话”一词是指 MediaSessionCompat 的实例。此类来自 media-compat 库，建议用此库编写媒体应用。

创建 Activity 后，我们将创建一个媒体会话和一个媒体会话连接器，后者充当媒体会话和 ExoPlayer 之间的中间层。

插入上述代码的理想位置也是创建 ExoPlayer 的位置。在我们的演示应用中，我们可以将代码附加到 initializePlayer() 的末尾。请务必在播放器实例化之后添加此逻辑！

private void initializePlayer() {
  if (player == null) {
    ...
    player = ...
    ...
    mediaSession = new MediaSessionCompat(this, "sample");
    mediaSessionConnector = new MediaSessionConnector(mediaSession);
    mediaSessionConnector.setPlayer(player);
  }
  ...
}

释放媒体会话

不再需要媒体会话时，请将其释放。我们在 releasePlayer() 中释放 ExoPlayer 时，还添加了以下代码：

private void releasePlayer() {
  if (mediaSession != null) {
    mediaSession.release();
  }
  ...
}

管理媒体会话状态

现在，我们已实例化媒体会话，接下来需要确保在用户与 Activity 交互时正确反映媒体会话的状态。

用户启动 Activity 后，媒体会话应变为活动状态：

@Override
public void onStart() {
  ...
  if (mediaSession != null) {
    mediaSession.setActive(true);
  }
}

由于我们的应用不在后台播放媒体内容，因此请务必确保用户离开 Activity 后媒体会话变为非活动状态：

@Override
public void onStop() {
  super.onStop();
  if (mediaSession != null) {
    mediaSession.setActive(false);
  }
  ...
}

警告：未能将媒体会话转变为非活动状态可能会引发用户预期之外的后果。例如，如果用户退出 Activity 后系统释放了 ExoPlayer，用户的锁定屏幕上可能仍显示无法操作的播放控件。

运行演示

1. 连接 Android 设备或启动模拟器。
2. 请确保选择“演示”，以便从 Android Studio 工具栏运行演示。
   
3. 点击 Android Studio 工具栏中的 。
4. 应用在您的设备上启动后，请选择要播放的视频串流。
5. 开始播放后，尝试使用以下 adb 命令来控制媒体会话：
   adb shell media dispatch pause
adb shell media dispatch play
adb shell media dispatch play-pause
adb shell media dispatch fast-forward
adb shell media dispatch rewind
   

注意：如果您的设备不支持这些命令，请尝试使用模拟器。

6. 此外，您还可以通过执行以下命令了解 Android 如何访问您的媒体会话：
   adb shell dumpsys media_session
7. 如果您使用的是带有麦克风的实体设备，尝试调用 Google 助理并发出语音指令，例如：
   “暂停”、
   “继续”、
   “快进 1 分钟”。

在 Android TV 上运行的 ExoPlayer 示例。

现在，我们可以在刚才在 initializePlayer() 中创建 MediaSessionConnector 的位置，扩展媒体会话支持的功能。

注意：通过 Google 助理调用语音指令可能仅适用于 Android TV，或者适用于媒体内容继续在后台播放并且媒体会话仍然保持活动状态的情形。

添加 TimelineQueueNavigator

ExoPlayer 以时间轴的形式表示媒体内容的结构。如需详细了解相关工作原理，请花点时间了解 ExoPlayer 的 Timeline 对象。通过了解此结构，我们可以在内容变化时收到通知，并在收到请求时显示当前正在播放的内容的元数据。

为此，我们将指定一个 TimelineQueueNavigator。在 initializePlayer() 中找到 MediaSessionConnector 的实例化代码段，并在初始化 mediaSession 之后添加 TimelineQueueNavigator 的实现。

mediaSessionConnector.setQueueNavigator(new TimelineQueueNavigator(mediaSession) {
  @Override
  public MediaDescriptionCompat getMediaDescription(Player player, int windowIndex) {
    return new MediaDescriptionCompat.Builder()
            .setTitle("MediaDescription title")
            .setDescription("MediaDescription description for " + windowIndex)
            .setSubtitle("MediaDescription subtitle")
            .build();
  }
});

通过添加以下内容解析类导入：

import android.support.v4.media.MediaDescriptionCompat;
import com.google.android.exoplayer2.ext.mediasession.TimelineQueueNavigator;

注意观察 windowIndex 参数是否与播放队列中该索引的媒体内容相对应。

注意：此队列的内容由播放器的媒体来源决定。在提供的演示中，您可以从使用 ConcatenatingMediaSource 的示例选择 Activity 中选择播放列表示例。

现在，您已经添加了一些元数据，接下来可以测试 Google 助理是否理解当前正在播放什么内容。在 Android TV 上播放视频时，调用 Google 助理并询问“正在播放什么？”

您的播放器可能不支持某些操作，或者您希望添加对更多操作的支持？现在，我们来深入了解一下刚才我们在 initializePlayer() 中创建 MediaSessionConnector 所在的媒体会话。

声明支持的操作

尝试使用 mediaSessionConnector.setEnabledPlaybackActions() 自定义您希望媒体会话支持哪些操作。

请注意，完整的集合如下所示：

mediaSessionConnector.setEnabledPlaybackActions(
        PlaybackStateCompat.ACTION_PLAY_PAUSE
                | PlaybackStateCompat.ACTION_PLAY
                | PlaybackStateCompat.ACTION_PAUSE
                | PlaybackStateCompat.ACTION_SEEK_TO
                | PlaybackStateCompat.ACTION_FAST_FORWARD
                | PlaybackStateCompat.ACTION_REWIND
                | PlaybackStateCompat.ACTION_STOP
                | PlaybackStateCompat.ACTION_SET_REPEAT_MODE
                | PlaybackStateCompat.ACTION_SET_SHUFFLE_MODE
);

我们再次看一下此数据在平台上的显示方式：

1. 和之前一样，播放视频。
2. 通过执行以下命令，了解 Android 如何从您的媒体会话访问元数据：
   adb shell dumpsys media_session
3. 找到包含元数据的行，并注意观察其中包含的与 com.google.android.exoplayer2.demo/sample 关联的标题和说明。

添加其他操作

我们扩展我们的视频会话，使其支持更多操作。在本部分中，我们仅添加字幕支持。

字幕支持

为媒体会话添加字幕支持可让用户通过语音打开/关闭字幕。找到初始化媒体会话连接器的位置，添加以下内容：

mediaSessionConnector.setCaptionCallback(new MediaSessionConnector.CaptionCallback() {
      @Override
      public void onSetCaptioningEnabled(Player player, boolean enabled) {
        Log.d("MediaSession", "onSetCaptioningEnabled: enabled=" + enabled);
      }

      @Override
      public boolean hasCaptions(Player player) {
        return true;
      }

      @Override
      public boolean onCommand(Player player, ControlDispatcher controlDispatcher, String command, Bundle extras, ResultReceiver cb) {
        return false;
      }
    }
);

最后，解析缺失的任意导入。

如需测试此功能，您可以调用 Android TV 上的 Google 助理，然后说“启用字幕”。检查 Logcat 中的消息，查看此功能如何调用您的代码。

注意：hasCaptions() 返回 false 时，Google 助理会告知用户系统不支持字幕。

恭喜，您已成功向示例添加媒体会话！

您可以通过以下方式实现大量功能：

• 添加媒体会话；
• 将媒体会话连接到 ExoPlayer 实例；
• 添加元数据和其他操作。

现在您已了解丰富媒体应用所需的关键步骤，快试着为用户提供更丰富多样的体验！

结语

本 Codelab 是基于 ExoPlayer 源代码中的示例构建的。您无需通过源代码使用 ExoPlayer，建议您提取 ExoPlayer 和 MediaSessionConnector 的依赖项，以便轻松获取最新版本。

为此，只需替换项目依赖项即可，例如：

implementation project(modulePrefix + 'library-core')
implementation project(path: ':extension-mediasession')

并从 Maven 代码库中提取数据，例如：

implementation 'com.google.android.exoplayer:exoplayer-core:2.+'
implementation 'com.google.android.exoplayer:extension-mediasession:2.+'

参考文档

• 使用媒体会话
• ExoPlayer 的时间轴结构