使用媒体会话

媒体会话提供了一种与音频或视频播放器交互的通用方式。通过告知 Android 媒体正在应用中播放,可以将播放控制权委托给该应用。与媒体会话集成允许应用在外部宣传媒体播放,并从外部源接收播放命令。这些来源可以是物理按钮(例如耳机或电视遥控器上的播放按钮)或间接命令(例如指示 Google 助理“暂停”)。然后,媒体会话将这些命令委托给应用,应用将其应用于媒体播放器,而命令的来源对于媒体播放器是透明的。

媒体会话与其管理的播放器共存。您应该在拥有媒体会话及其关联播放器的 Activity 或 Service 的 onCreate() 方法中创建并初始化媒体会话。

初始化媒体会话

新创建的媒体会话没有功能。您必须通过执行以下步骤来初始化会话:

  • 设置标志,以便媒体会话可以接收来自媒体控制器和媒体按钮的回调。
  • 创建并初始化一个 PlaybackStateCompat 实例并将其分配给会话。播放状态在整个会话期间都会发生变化,因此我们建议缓存 PlaybackStateCompat.Builder 以便重用。
  • 创建一个 MediaSessionCompat.Callback 实例并将其分配给会话(有关回调的更多信息,请参阅下文)。

您应该在拥有会话的ActivityServiceonCreate() 方法中创建并初始化媒体会话。

为了让媒体按钮在您的应用新初始化(或停止)时起作用,其 PlaybackState 必须包含一个与媒体按钮发送的 Intent 匹配的播放操作。这就是为什么在初始化期间将 ACTION_PLAY 分配给会话状态的原因。有关更多信息,请参阅响应媒体按钮

维护播放状态和元数据

有两个类表示媒体会话的状态。

PlaybackStateCompat 类描述了播放器当前的操作状态。这包括:

  • 传输状态(播放器是播放/暂停/缓冲等。请参阅 getState()
  • 适用的错误代码和可选错误消息。(请参阅 getErrorCode(),并阅读下面的状态和错误。)
  • 播放器位置
  • 当前状态下可以处理的有效控制器操作

MediaMetadataCompat 类描述了正在播放的媒体内容:

  • 艺术家、专辑和曲目的名称
  • 曲目时长
  • 在锁屏上显示的专辑封面。图像是最大尺寸为 320x320dp 的位图(如果更大,则会缩小)。
  • 指向更大版本封面的 ContentUris 实例

播放器状态和元数据可以在媒体会话的生命周期内发生变化。每次状态或元数据发生变化时,您都必须使用每个类的相应构建器,即 PlaybackStateCompat.Builder()MediaMetadataCompat.Builder(),然后通过调用 setPlaybackState()setMetaData() 将新实例传递给媒体会话。为了减少这些频繁操作的总内存消耗,最好一次性创建构建器并在会话的整个生命周期中重复使用它们。

状态和错误

请注意,PlaybackState 是一个对象,它包含用于会话播放状态 (getState()) 和必要时关联的错误代码 (getErrorCode()) 的单独值。错误可以是致命的或非致命的

每当播放中断时,您都应该生成一个致命错误:将传输状态设置为 STATE_ERROR,并使用 setErrorMessage(int, CharSequence) 指定关联的错误。只要播放因错误而受阻,PlaybackState 就应该继续报告 STATE_ERROR 和错误。

当您的应用无法处理请求但可以继续播放时,会发生非致命错误:传输保持“正常”状态(例如 STATE_PLAYING),但 PlaybackState 中包含错误代码。例如,如果正在播放最后一首歌曲,并且用户请求跳到下一首歌曲,播放可以继续,但您应该创建一个新的 PlaybackState,错误代码为 ERROR_CODE_END_OF_QUEUE,然后调用 setPlaybackState()。连接到会话的媒体控制器将收到回调 onPlaybackStateChanged() 并向用户解释发生了什么。非致命错误只应在发生时报告一次。下次会话更新 PlaybackState 时,不要再次设置相同的非致命错误(除非错误是响应新请求而发生的)。

媒体会话锁屏

从 Android 4.0(API 级别 14)开始,系统可以访问媒体会话的播放状态和元数据。这就是锁屏可以显示媒体控件和艺术作品的方式。其行为因 Android 版本而异。

专辑封面

在 Android 4.0(API 级别 14)到 Android 10(API 级别 29)中,锁屏背景会显示您的专辑封面 - 但前提是媒体会话元数据中包含背景位图。

传输控制

在 Android 4.0(API 级别 14)到 Android 4.4(API 级别 19)中,当媒体会话处于活动状态且媒体会话元数据中包含背景位图时,锁屏会自动显示传输控件。

在 Android 5.0(API 级别 21)或更高版本中,系统不在锁屏上提供传输控件。相反,您应该使用 MediaStyle 通知来显示传输控件。

添加自定义操作

媒体应用可以定义自定义操作;例如:点赞、喜欢或倒回 30 秒。自定义操作应实现全新的行为。请勿使用自定义操作替换 PlaybackStateCompat 中定义的标准传输控制操作之一。

使用 addCustomAction() 添加自定义操作。以下示例展示了如何添加点赞操作的控件

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

有关完整示例,请参阅 Universal Music Player

您可以使用 onCustomAction() 响应此操作。

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

另请参阅 Universal Music Player

媒体会话回调

主要的媒体会话回调方法是 onPlay()onPause()onStop()。您可以在此处添加控制播放器的代码。

由于您在运行时(在 onCreate() 中)实例化并设置会话的回调,因此您的应用可以定义使用不同播放器的替代回调,并根据设备和/或系统级别选择适当的回调/播放器组合。您可以在不更改应用其余部分的情况下更改播放器。例如,您可以在 Android 4.1(API 级别 16)或更高版本上运行时使用 ExoPlayer,而在早期系统上使用 MediaPlayer

除了控制播放器和管理媒体会话状态转换之外,回调还启用和禁用您的应用功能,并控制其与其他应用和设备硬件的交互方式。(请参阅控制音频输出)。

媒体会话回调方法的实现取决于您的应用结构。请参阅单独的页面,其中描述了如何在音频应用视频应用中使用回调,并描述了每种应用的回调应如何实现。