响应媒体按钮

媒体按钮是 Android 设备和其他外围设备上的硬件按钮，例如蓝牙耳机上的暂停/播放按钮。当用户按下媒体按钮时，Android 会生成 KeyEvent，其中包含用于标识按钮的键码。媒体按钮 KeyEvents 的键码是以 KEYCODE_MEDIA 开头的常量（例如 KEYCODE_MEDIA_PLAY）。

应用应该能够在三种情况下处理媒体按钮事件，按以下顺序 优先级：

  • 应用的界面 Activity 可见时
  • 当界面 Activity 被隐藏且应用的媒体会话处于活动状态时
  • 当界面 Activity 被隐藏且应用的媒体会话处于非活动状态并需要重新启动时

处理前台 Activity 中的媒体按钮

前台 activity 在其 onKeyDown() 中接收媒体按钮键事件 方法。根据 Android 的运行版本，系统会通过两种方式将事件传送至 媒体控制器：

  • 如果您运行的是 Android 5.0（API 级别 21）或更高版本，请调用 FLAG_HANDLES_MEDIA_BUTTONS MediaBrowserCompat.ConnectionCallback.onConnected。这将 自动调用媒体控制器的 dispatchMediaButtonEvent(), 该函数会将键码转换为媒体会话回调。
  • 在 Android 5.0（API 级别 21）之前，您需要修改 onKeyDown() 来处理 事件本身 （如需了解详情，请参阅处理活动媒体会话中的媒体按钮。） 以下代码段展示了如何拦截 键码并调用 sendMediaButtonEvent()。请务必将 true 退回到 表示事件已处理：

    Kotlin

        fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            return super.onKeyDown(keyCode, event)
        }
        when (keyCode) {
            KeyEvent.KEYCODE_MEDIA_PLAY -> {
                yourMediaController.dispatchMediaButtonEvent(event)
                return true
            }
        }
        return super.onKeyDown(keyCode, event)
    }

    Java

        @Override
    boolean onKeyDown(int keyCode, KeyEvent event) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
              return super.onKeyDown(keyCode, event);
            }
            switch (keyCode) {
              case KeyEvent.KEYCODE_MEDIA_PLAY:
                      yourMediaController.dispatchMediaButtonEvent(event);
                      return true;
            }
            return super.onKeyDown(keyCode, event);
    }

查找媒体会话

如果前台 activity 不处理该事件，Android 将尝试查找 媒体会话。同样，具体取决于 在 Android 设备上，可通过以下两种方式搜索媒体会话：

  • 如果您运行的是 Android 8.0（API 级别 26）或更高版本，系统会尝试 找到最后一个具有 MediaSession 且在本地播放音频的应用。如果会话 Android 则直接向其发送事件。否则，如果 会话未处于活动状态且具有 Mediabutton 接收器时，Android 会将事件 发送到接收器，这将重新启动会话，以便接收事件。 （如需了解详情，请参阅使用媒体按钮重启非活动的媒体会话。） 如果会话没有媒体按钮接收器，系统会舍弃媒体 什么都不会发生逻辑如下所示 图表：

  • 在 Android 8.0（API 级别 26）之前，系统会尝试将事件发送到 活动媒体会话。如果存在多个活动的媒体会话，Android 会尝试 选择正准备播放（正在缓冲/连接）的媒体会话； 广告播放或暂停播放广告，而不是停止播放广告。（请参阅 处理活动媒体会话中的媒体按钮 了解详情。）如果没有有效的 会话，Android 会尝试将事件发送到最近处于活动状态的会话。 （如需了解详情，请参阅使用媒体按钮重启非活动的媒体会话。） 逻辑如下图所示：

处理活动媒体会话中的媒体按钮

在 Android 5.0（API 级别 21）及更高版本中，Android 通过调用 onMediaButtonEvent()。 默认情况下，此回调会将 KeyEvent 转换为与键码匹配的相应媒体会话回调方法。

在 Android 5.0（API 级别 21）之前，Android 通过广播 intent 来处理媒体按钮事件 ACTION_MEDIA_BUTTON 操作触发。您的应用必须注册 BroadcastReceiver 来拦截这些 intent。通过 MediaButtonReceiver 类是专为 。它是 Android 设备 media-compat 库 处理 ACTION_MEDIA_BUTTON 并将传入的 Intent 转换为 相应的 MediaSessionCompat.Callback 方法调用。

MediaButtonReceiver 是一个存在时间很短的 BroadcastReceiver。它会将传入的 intent 传递给管理媒体会话的服务。如果您想使用 Android 5.0 之前的系统中的媒体按钮，您必须添加 使用 MEDIA_BUTTON intent 过滤器在清单中的 MediaButtonReceiver：

<receiver android:name="android.support.v4.media.session.MediaButtonReceiver" >
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
 </receiver>

BroadcastReceiver 会将 Intent 转发给您的服务。解析 intent 并生成媒体会话的回调，请在服务的 onStartCommand() 中添加 MediaButtonReceiver.handleIntent() 方法。 这会将键码转换为相应的会话回调方法。

Kotlin

private val mediaSessionCompat: MediaSessionCompat = ...

override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
    MediaButtonReceiver.handleIntent(mediaSessionCompat, intent)
    return super.onStartCommand(intent, flags, startId)
}

Java

private MediaSessionCompat mediaSessionCompat = ...;

 public int onStartCommand(Intent intent, int flags, int startId) {
   MediaButtonReceiver.handleIntent(mediaSessionCompat, intent);
   return super.onStartCommand(intent, flags, startId);
 }

使用媒体按钮重启非活动的媒体会话

如果 Android 可以识别上一个活动的媒体会话，它会尝试通过向清单注册的组件（例如某项服务或 BroadcastReceiver）发送 ACTION_MEDIA_BUTTON Intent 来重启会话。

这可让您的应用在其界面不可见的情况下重新开始播放，大多数音频应用都是如此。

使用 MediaSessionCompat 时会自动启用此行为。如果您 使用 Android 框架的 MediaSession 或支持库 24.0.0 至 25.1.1 您必须调用 setMediaButtonReceiver 才能让媒体按钮重启 处于非活动状态的媒体会话。

您可以通过以下方法在 Android 5.0（API 级别 21）及更高版本中停用此行为： 设置 null 媒体按钮接收器：

Kotlin

// Create a MediaSessionCompat
mediaSession = MediaSessionCompat(context, LOG_TAG)
mediaSession.setMediaButtonReceiver(null)

Java

// Create a MediaSessionCompat
mediaSession = new MediaSessionCompat(context, LOG_TAG);
mediaSession.setMediaButtonReceiver(null);

自定义媒体按钮处理程序

onMediaButtonEvent() 的默认行为是提取键码，并使用媒体会话的当前状态和受支持操作的列表来确定要调用的方法。例如，KEYCODE_MEDIA_PLAY 会调用 onPlay()。

为了在所有应用中提供一致的媒体按钮体验，您应该使用 默认行为，并且仅出于特定目的而偏离。如果媒体按钮 需要自定义处理，请替换回调的 onMediaButtonEvent() 方法，使用以下代码提取 KeyEvent： intent.getParcelableExtra(Intent.EXTRA_KEY_EVENT), 自行处理事件，并返回 true。

摘要

如需在所有 Android 版本中正确处理媒体按钮事件，您必须 指定FLAG_HANDLES_MEDIA_BUTTONS 都会用到这个应用

此外，根据您计划支持的 Android 版本， 您还必须满足以下要求：

在 Android 5.0 或更高版本中运行时：

  • 从媒体控制器 onConnected() 回调中调用 MediaControllerCompat.setMediaController()
  • 如需允许媒体按钮重启非活跃会话，请调用以下内容，动态创建 MediaButtonReceiver： setMediaButtonReceiver() 并向其传递 PendingIntent

在 Android 5.0 之前的系统中运行时：

  • 替换 Activity 的 onKeyDown() 以处理媒体按钮
  • 通过将 MediaButtonReceiver 添加到应用的清单来静态创建该接收器