响应媒体按钮

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

应用应能够按以下优先级顺序处理媒体按钮事件：

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

在前景活动中处理媒体按钮

前景活动在其onKeyDown()方法中接收媒体按钮按键事件。根据 Android 的运行版本，系统将事件路由到媒体控制器的两种方式：

  • 如果您运行的是 Android 5.0（API 级别 21）或更高版本，请调用FLAG_HANDLES_MEDIA_BUTTONS MediaBrowserCompat.ConnectionCallback.onConnected。这将自动调用媒体控制器的dispatchMediaButtonEvent()，该方法将键码转换为媒体会话回调。
  • 在 Android 5.0（API 级别 21）之前，您需要修改onKeyDown()来自己处理事件。（有关详细信息，请参见在活动媒体会话中处理媒体按钮）。以下代码片段显示了如何拦截键码并调用 dispatchMediaButtonEvent()。请务必返回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);
    }

查找媒体会话

如果前景活动未处理事件，Android 将尝试查找可以处理该事件的媒体会话。同样，根据 Android 的运行版本，有两种方法可以搜索媒体会话：

  • 如果您运行的是 Android 8.0（API 级别 26）或更高版本，系统将尝试查找最近一个播放本地音频的带有 MediaSession 的应用。如果会话仍然处于活动状态，Android 会直接将事件发送给它。否则，如果会话未处于活动状态并且它具有媒体按钮接收器，Android 会将事件发送到接收器，该接收器将重新启动会话，以便它可以接收事件。（有关详细信息，请参见使用媒体按钮重新启动非活动媒体会话）。逻辑如下图所示：

  • 在 Android 8.0（API 级别 26）之前，系统会尝试将事件发送到活动媒体会话。如果有多个活动媒体会话，Android 会尝试选择正在准备播放（缓冲/连接）、正在播放或已暂停的媒体会话，而不是已停止的媒体会话。（有关详细信息，请参见在活动媒体会话中处理媒体按钮）。如果没有活动会话，Android 会尝试将事件发送到最近的活动会话。（有关详细信息，请参见使用媒体按钮重新启动非活动媒体会话）。逻辑如下图所示：

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

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

在 Android 5.0（API 级别 21）之前，Android 通过广播带有ACTION_MEDIA_BUTTON操作的意图来处理媒体按钮事件。您的应用必须注册一个 BroadcastReceiver 来拦截这些意图。MediaButtonReceiver类专门为此目的而设计。它是Android media-compat 库中的一个便捷类，它处理ACTION_MEDIA_BUTTON并将传入的意图转换为相应的MediaSessionCompat.Callback方法调用。

一个MediaButtonReceiver是一个短暂的 BroadcastReceiver。它将传入的意图转发到管理媒体会话的服务。如果您想在早于 Android 5.0 的系统中使用媒体按钮，则必须在清单中包含MediaButtonReceiver以及MEDIA_BUTTON意图过滤器。

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

BroadcastReceiver将意图转发到您的服务。要解析意图并生成到媒体会话的回调，请在服务的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 可以识别最近的活动媒体会话，它会尝试通过将ACTION_MEDIA_BUTTON意图发送到清单注册的组件（例如服务或BroadcastReceiver）来重新启动会话。

这允许您的应用在 UI 不可见时重新启动播放，这对于大多数音频应用来说都是这种情况。

当您使用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()方法，使用intent.getParcelableExtra(Intent.EXTRA_KEY_EVENT)提取KeyEvent，自行处理事件，然后返回true。

总结

为了在所有版本的 Android 中正确处理媒体按钮事件，您必须在创建媒体会话时指定FLAG_HANDLES_MEDIA_BUTTONS。

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

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

  • 从媒体控制器onConnected()回调中调用MediaControllerCompat.setMediaController()
  • 要允许媒体按钮重新启动非活动会话，请通过调用setMediaButtonReceiver()并向其传递一个PendingIntent来动态创建一个MediaButtonReceiver

在早于 Android 5.0 的系统中运行时

  • 重写活动的onKeyDown()以处理媒体按钮
  • 通过将其添加到应用的清单中来静态创建MediaButtonReceiver