使用 MediaSession 控制和通告播放

媒体会话提供了一种与音频或视频播放器互动的方式。在 Media3 中，默认播放器是实现 Player 接口的 ExoPlayer 类。将媒体会话连接到播放器后，应用便可向外部宣传媒体播放，并接收来自外部来源的播放命令。

命令可能源自实体按钮，例如耳机或电视遥控器上的播放按钮。它们也可能来自具有媒体控制器的客户端应用，例如向 Google 助理发出“暂停”指令。媒体会话会将这些命令委托给媒体应用的播放器。

何时选择媒体会话

实现 MediaSession 后，用户可以控制播放：

  • 通过耳机。用户通常可以在耳机上执行按钮操作或触控操作，以播放或暂停媒体，或前往下一曲/上一曲。
  • 通过与 Google 助理对话。一种常见模式是说“OK Google，暂停”，以暂停设备上当前正在播放的任何媒体内容。
  • 通过 Wear OS 手表。这样一来，用户在手机上播放内容时，便可更轻松地访问最常用的播放控件。
  • 通过媒体控件。此轮播界面会显示每个正在运行的媒体会话的控件。
  • 在电视上。允许通过实体播放按钮、平台播放控制和电源管理来执行操作（例如，如果电视、条形音箱或 A/V 接收器关闭或输入源切换，应用中的播放应停止）。
  • 通过 Android Auto 媒体控件。这样，您就可以在驾驶时安全地控制播放。
  • 以及需要影响播放的任何其他外部进程。

这非常适合许多使用场景。具体而言，在以下情况下，您应强烈考虑使用 MediaSession：

  • 您正在播放长视频内容，例如电影或直播电视。
  • 您正在播放长音频内容，例如播客或音乐播放列表。
  • 您正在构建 TV 应用。

不过，并非所有使用情形都适合使用 MediaSession。在以下情况下，您可能只想使用 Player：

  • 您正在展示短篇幅内容，无需外部控制或后台播放。
  • 没有单个正在播放的视频，例如用户正在滚动浏览列表，并且屏幕上同时显示多个视频。
  • 您正在播放一次性介绍或说明视频，您希望用户主动观看，而无需外部播放控件。
  • 您的内容属于隐私敏感型，并且您不希望外部进程访问媒体元数据（例如浏览器中的无痕模式）。

如果您的使用情形不属于上述任何一种，请考虑您是否可以接受应用在用户未主动与内容互动时继续播放。如果回答是肯定的，您可能需要选择 MediaSession。如果答案为“否”，您可能需要改用 Player。

创建媒体会话

媒体会话与其管理的播放器共存。您可以使用 Context 和 Player 对象构建媒体会话。您应该在需要时创建并初始化媒体会话，例如 Activity 或 Fragment 的 onStart() 或 onResume() 生命周期方法，或者媒体会话及其关联播放器所属的 Service 的 onCreate() 方法。

如需创建媒体会话，请初始化 Player 并将其提供给 MediaSession.Builder，如下所示：

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 库会使用播放器的状态自动更新媒体会话。因此，您无需手动处理从玩家到会话的映射。

这与平台媒体会话不同，在平台媒体会话中，您需要独立于播放器本身创建和维护 PlaybackState，例如为了指示任何错误。

唯一会话 ID

默认情况下，MediaSession.Builder 会创建一个以空字符串作为会话 ID 的会话。如果应用仅打算创建一个会话实例（这是最常见的情况），则此方法就足够了。

如果应用想要同时管理多个会话实例，则必须确保每个会话的会话 ID 都是唯一的。使用 MediaSession.Builder.setId(String id) 构建会话时，可以设置会话 ID。

如果您发现 IllegalStateException 导致应用崩溃并显示错误消息 IllegalStateException: Session ID must be unique. ID=，则可能是因为在释放之前创建的具有相同 ID 的实例之前，意外创建了会话。为避免因编程错误而泄露会话，系统会检测到此类情况，并通过抛出异常来通知您。

向其他客户端授予控制权

媒体会话是控制播放的关键。它使您能够将来自外部来源的命令路由到负责播放媒体的播放器。这些来源可以是实体按钮，例如耳机或电视遥控器上的播放按钮，也可以是间接命令，例如向 Google 助理发出“暂停”指令。同样，您可能希望授予 Android 系统访问权限，以便实现通知和锁定屏幕控制，或者授予 Wear OS 手表访问权限，以便您可以通过表盘控制播放。外部客户端可以使用媒体控制器向媒体应用发出播放命令。这些命令由媒体会话接收，最终会委托给媒体播放器。

一张图表，展示了 MediaSession 和 MediaController 之间的互动。
图 1：媒体控制器有助于将命令从外部来源传递到媒体会话。

当控制器即将连接到您的媒体会话时，系统会调用 onConnect() 方法。您可以使用提供的 ControllerInfo 来决定是接受还是拒绝请求。如需查看接受连接请求的示例，请参阅声明自定义命令部分。

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

其他回调方法可让您处理自定义命令请求和修改播放列表等操作。这些回调同样包含 ControllerInfo 对象，因此您可以根据每个控制器的具体情况修改对每个请求的响应方式。

修改播放列表

媒体会话可以直接修改其播放器的播放列表，如 ExoPlayer 播放列表指南中所述。 如果控制器拥有 COMMAND_SET_MEDIA_ITEM 或 COMMAND_CHANGE_MEDIA_ITEMS，则还可以修改播放列表。

向播放列表中添加新内容时，播放器通常需要 MediaItem 个具有已定义 URI 的实例才能播放这些内容。默认情况下，如果新添加的项定义了 URI，系统会自动将其转发给播放器方法（例如 player.addMediaItem）。

如果您想自定义添加到播放器的 MediaItem 实例，可以替换 onAddMediaItems()。如果您想支持请求媒体但没有定义 URI 的控制器，则需要执行此步骤。相反，MediaItem 通常会设置以下一个或多个字段来描述所请求的媒体：

  • MediaItem.id：用于标识媒体的通用 ID。
  • MediaItem.RequestMetadata.mediaUri：可能使用自定义架构且不一定能直接由播放器播放的请求 URI。
  • MediaItem.RequestMetadata.searchQuery：文本搜索查询，例如来自 Google 助理的查询。
  • MediaItem.MediaMetadata：结构化元数据，例如“标题”或“艺术家”。

如需获取更多用于自定义全新播放列表的选项，您还可以替换 onSetMediaItems()，以便在播放列表中定义起始项和位置。例如，您可以将单个请求的项扩展为整个播放列表，并指示播放器从最初请求的项的索引处开始播放。您可以在会话演示应用中找到包含此功能的 onSetMediaItems() 示例实现。

管理媒体按钮偏好设置

每个控制器（例如系统界面、Android Auto 或 Wear OS）都可以自行决定向用户显示哪些按钮。如需指明要向用户公开哪些播放控件，您可以在 MediaSession 上指定媒体按钮偏好设置。这些偏好设置包含一个 CommandButton 实例的有序列表，每个实例都定义了界面中某个按钮的偏好设置。

定义命令按钮

CommandButton 实例用于定义媒体按钮偏好设置。每个按钮都定义了所需界面元素的三个方面：

  1. 图标，用于定义视觉外观。创建 CommandButton.Builder 时，必须将图标设置为预定义的常量之一。请注意，这并非实际的位图或图片资源。通用常量有助于控制器在其自己的界面中选择合适的资源，以实现一致的外观和风格。如果没有预定义的图标常量适合您的使用情形，您可以改用 setCustomIconResId。
  2. 命令，用于定义用户与按钮互动时触发的操作。您可以将 setPlayerCommand 用于 Player.Command，或将 setSessionCommand 用于预定义或自定义的 SessionCommand。
  3. 插槽，用于定义按钮在控制器界面中的放置位置。此字段是可选字段，系统会根据图标和命令自动设置。例如，它允许指定按钮应显示在界面的“前进”导航区域中，而不是默认的“溢出”区域中。

Kotlin

val button =
  CommandButton.Builder(CommandButton.ICON_SKIP_FORWARD_15)
    .setSessionCommand(SessionCommand(CUSTOM_ACTION_ID, Bundle.EMPTY))
    .setSlots(CommandButton.SLOT_FORWARD)
    .build()

Java

CommandButton button =
    new CommandButton.Builder(CommandButton.ICON_SKIP_FORWARD_15)
        .setSessionCommand(new SessionCommand(CUSTOM_ACTION_ID, Bundle.EMPTY))
        .setSlots(CommandButton.SLOT_FORWARD)
        .build();

在确定媒体按钮偏好设置时，系统会应用以下算法：

  1. 对于媒体按钮偏好设置中的每个 CommandButton，将按钮放置在第一个可用的允许插槽中。
  2. 如果任何中央、向前和向后插槽未填充按钮，请为此插槽添加默认按钮。

您可以使用 CommandButton.DisplayConstraints 生成媒体按钮偏好设置在不同界面显示限制条件下的解析方式的预览。

设置媒体按钮偏好设置

设置媒体按钮偏好的最简单方法是在构建 MediaSession 时定义列表。或者，您也可以替换 MediaSession.Callback.onConnect，以自定义每个已连接控制器的媒体按钮偏好设置。

Kotlin

val mediaSession =
  MediaSession.Builder(context, player)
    .setMediaButtonPreferences(ImmutableList.of(likeButton, favoriteButton))
    .build()

Java

MediaSession mediaSession =
  new MediaSession.Builder(context, player)
      .setMediaButtonPreferences(ImmutableList.of(likeButton, favoriteButton))
      .build();

在用户互动后更新媒体按钮偏好设置

在处理与玩家的互动后，您可能需要更新控制器界面中显示的按钮。一个典型的示例是切换按钮，该按钮在触发与其关联的操作后会更改其图标和操作。如需更新媒体按钮偏好设置，您可以使用 MediaSession.setMediaButtonPreferences 来更新所有控制器或特定控制器的偏好设置：

Kotlin

// Handle "favoritesButton" action, replace by opposite button
mediaSession.setMediaButtonPreferences(
  ImmutableList.of(likeButton, removeFromFavoritesButton))

Java

// Handle "favoritesButton" action, replace by opposite button
mediaSession.setMediaButtonPreferences(
    ImmutableList.of(likeButton, removeFromFavoritesButton));

添加自定义命令并自定义默认行为

可通过自定义命令扩展可用的播放器命令，还可以拦截传入的播放器命令和媒体按钮来更改默认行为。

声明和处理自定义命令

媒体应用可以定义自定义命令，例如，这些命令可用于媒体按钮偏好设置。例如，您可能想要实现一些按钮，让用户能够将媒体项保存到收藏项列表中。MediaController 发送自定义命令，MediaSession.Callback 接收这些命令。

如需定义自定义命令，您需要替换 MediaSession.Callback.onConnect() 以设置每个已连接控制器的可用自定义命令。

Kotlin

private class CustomMediaSessionCallback: MediaSession.Callback {
  // Configure commands available to the controller in onConnect()
  override fun onConnect(
    session: MediaSession,
    controller: MediaSession.ControllerInfo
  ): MediaSession.ConnectionResult {
    val sessionCommands = ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
        .add(SessionCommand(SAVE_TO_FAVORITES, Bundle.EMPTY))
        .build()
    return AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build()
  }
}

Java

class CustomMediaSessionCallback implements MediaSession.Callback {
  // Configure commands available to the controller in onConnect()
  @Override
  public ConnectionResult onConnect(
    MediaSession session,
    ControllerInfo controller) {
    SessionCommands sessionCommands =
        ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
            .add(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
            .build();
    return new AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
}

如需接收来自 MediaController 的自定义命令请求，请替换 Callback 中的 onCustomCommand() 方法。

Kotlin

private class CustomMediaSessionCallback: MediaSession.Callback {
  ...
  override fun onCustomCommand(
    session: MediaSession,
    controller: MediaSession.ControllerInfo,
    customCommand: SessionCommand,
    args: Bundle
  ): ListenableFuture<SessionResult> {
    if (customCommand.customAction == SAVE_TO_FAVORITES) {
      // Do custom logic here
      saveToFavorites(session.player.currentMediaItem)
      return Futures.immediateFuture(
        SessionResult(SessionResult.RESULT_SUCCESS)
      )
    }
    ...
  }
}

Java

class CustomMediaSessionCallback implements MediaSession.Callback {
  ...
  @Override
  public ListenableFuture<SessionResult> onCustomCommand(
    MediaSession session, 
    ControllerInfo controller,
    SessionCommand customCommand,
    Bundle args
  ) {
    if(customCommand.customAction.equals(SAVE_TO_FAVORITES)) {
      // Do custom logic here
      saveToFavorites(session.getPlayer().getCurrentMediaItem());
      return Futures.immediateFuture(
        new SessionResult(SessionResult.RESULT_SUCCESS)
      );
    }
    ...
  }
}

您可以使用传递到 Callback 方法中的 MediaSession.ControllerInfo 对象的 packageName 属性来跟踪哪个媒体控制器正在发出请求。这样，您就可以根据给定命令的来源（系统、您自己的应用或其他客户端应用）来调整应用的行为。

自定义默认播放器命令

所有默认命令和状态处理都委托给 MediaSession 上的 Player。如需自定义 Player 接口中定义的命令（例如 play() 或 seekToNext()）的行为，请先将 Player 封装在 ForwardingSimpleBasePlayer 中，然后再将其传递给 MediaSession：

Kotlin

val player = (logic to build a Player instance)

val forwardingPlayer = object : ForwardingSimpleBasePlayer(player) {
  // Customizations
}

val mediaSession = MediaSession.Builder(context, forwardingPlayer).build()

Java

ExoPlayer player = (logic to build a Player instance)

ForwardingSimpleBasePlayer forwardingPlayer =
    new ForwardingSimpleBasePlayer(player) {
      // Customizations
    };

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

如需详细了解 ForwardingSimpleBasePlayer，请参阅有关自定义的 ExoPlayer 指南。

识别播放器命令的请求控制器

当对 Player 方法的调用由 MediaController 发起时，您可以使用 MediaSession.controllerForCurrentRequest 识别来源，并获取当前请求的 ControllerInfo：

Kotlin

class CallerAwarePlayer(player: Player) :
  ForwardingSimpleBasePlayer(player) {

  override fun handleSeek(
    mediaItemIndex: Int,
    positionMs: Long,
    seekCommand: Int,
  ): ListenableFuture<*> {
    Log.d(
      "caller",
      "seek operation from package ${session.controllerForCurrentRequest?.packageName}",
    )
    return super.handleSeek(mediaItemIndex, positionMs, seekCommand)
  }
}

Java

public class CallerAwarePlayer extends ForwardingSimpleBasePlayer {
  public CallerAwarePlayer(Player player) {
    super(player);
  }

  @Override
  protected ListenableFuture<?> handleSeek(
        int mediaItemIndex, long positionMs, int seekCommand) {
    Log.d(
        "caller",
        "seek operation from package: "
            + session.getControllerForCurrentRequest().getPackageName());
    return super.handleSeek(mediaItemIndex, positionMs, seekCommand);
  }
}

自定义媒体按钮处理

媒体按钮是 Android 设备和其他外围设备上的硬件按钮，例如蓝牙耳机上的播放/暂停按钮。当媒体按钮事件到达会话时，Media3 会为您处理这些事件，并在会话播放器上调用相应的 Player 方法。

建议在相应的 Player 方法中处理所有传入的媒体按钮事件。对于更高级的用例，可以在 MediaSession.Callback.onMediaButtonEvent(Intent) 中拦截媒体按钮事件。

错误处理和报告

会话会发出两种类型的错误并将其报告给控制器。 严重错误是指会中断播放的会话播放器技术性播放失败。严重错误发生时，系统会自动向控制器报告。非严重错误是指不会中断播放的非技术或政策错误，由应用手动发送给控制器。

致命的播放错误

播放器会向会话报告严重播放错误，然后通过 Player.Listener.onPlayerError(PlaybackException) 和 Player.Listener.onPlayerErrorChanged(@Nullable PlaybackException) 向控制器报告该错误。

在这种情况下，播放状态会转换为 STATE_IDLE，而 MediaController.getPlaybackError() 会返回导致转换的 PlaybackException。控制器可以检查 PlayerException.errorCode 以获取有关错误原因的信息。

为了实现互操作性，系统会将严重错误复制到平台会话，方法是将其状态转换为 STATE_ERROR，并根据 PlaybackException 设置错误代码和消息。

自定义严重错误

为了向用户提供本地化且有意义的信息，可以在构建会话时使用 ForwardingPlayer 自定义严重播放错误的错误代码、错误消息和错误 extra：

Kotlin

val forwardingPlayer = ErrorForwardingPlayer(player)
val session = MediaSession.Builder(context, forwardingPlayer).build()

Java

Player forwardingPlayer = new ErrorForwardingPlayer(player);
MediaSession session =
    new MediaSession.Builder(context, forwardingPlayer).build();

转发播放器可以使用 ForwardingSimpleBasePlayer 拦截错误并自定义错误代码、消息或 extra。同样，您也可以生成原始播放器中不存在的新错误：

Kotlin

class ErrorForwardingPlayer (private val context: Context, player: Player) :
    ForwardingSimpleBasePlayer(player) {

  override fun getState(): State {
    var state = super.getState()
    if (state.playerError != null) {
      state =
        state.buildUpon()
          .setPlayerError(customizePlaybackException(state.playerError!!))
          .build()
    }
    return state
  }

  fun customizePlaybackException(error: PlaybackException): PlaybackException {
    val buttonLabel: String
    val errorMessage: String
    when (error.errorCode) {
      PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW -> {
        buttonLabel = context.getString(R.string.err_button_label_restart_stream)
        errorMessage = context.getString(R.string.err_msg_behind_live_window)
      }
      else -> {
        buttonLabel = context.getString(R.string.err_button_label_ok)
        errorMessage = context.getString(R.string.err_message_default)
      }
    }
    val extras = Bundle()
    extras.putString("button_label", buttonLabel)
    return PlaybackException(errorMessage, error.cause, error.errorCode, extras)
  }
}

Java

class ErrorForwardingPlayer extends ForwardingSimpleBasePlayer {

  private final Context context;

  public ErrorForwardingPlayer(Context context, Player player) {
    super(player);
    this.context = context;
  }

  @Override
  protected State getState() {
    State state = super.getState();
    if (state.playerError != null) {
      state =
          state.buildUpon()
              .setPlayerError(customizePlaybackException(state.playerError))
              .build();
    }
    return state;
  }

  private PlaybackException customizePlaybackException(PlaybackException error) {
    String buttonLabel;
    String errorMessage;
    switch (error.errorCode) {
      case PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW:
        buttonLabel = context.getString(R.string.err_button_label_restart_stream);
        errorMessage = context.getString(R.string.err_msg_behind_live_window);
        break;
      default:
        buttonLabel = context.getString(R.string.err_button_label_ok);
        errorMessage = context.getString(R.string.err_message_default);
        break;
    }
    Bundle extras = new Bundle();
    extras.putString("button_label", buttonLabel);
    return new PlaybackException(errorMessage, error.getCause(), error.errorCode, extras);
  }
}

非严重错误

并非源自技术异常的非严重错误可由应用发送给所有控制器或特定控制器：

Kotlin

val sessionError = SessionError(
  SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED,
  context.getString(R.string.error_message_authentication_expired),
)

// Option 1: Sending a nonfatal error to all controllers.
mediaSession.sendError(sessionError)

// Option 2: Sending a nonfatal error to the media notification controller only
// to set the error code and error message in the playback state of the platform
// media session.
mediaSession.mediaNotificationControllerInfo?.let {
  mediaSession.sendError(it, sessionError)
}

Java

SessionError sessionError = new SessionError(
    SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED,
    context.getString(R.string.error_message_authentication_expired));

// Option 1: Sending a nonfatal error to all controllers.
mediaSession.sendError(sessionError);

// Option 2: Sending a nonfatal error to the media notification controller only
// to set the error code and error message in the playback state of the platform
// media session.
ControllerInfo mediaNotificationControllerInfo =
    mediaSession.getMediaNotificationControllerInfo();
if (mediaNotificationControllerInfo != null) {
  mediaSession.sendError(mediaNotificationControllerInfo, sessionError);
}

当非致命错误发送到媒体通知控制器时，错误代码和错误消息会复制到平台媒体会话，而 PlaybackState.state 不会更改为 STATE_ERROR。

接收非严重错误

MediaController 通过实现 MediaController.Listener.onError 接收非致命错误：

Kotlin

val future = MediaController.Builder(context, sessionToken)
  .setListener(object : MediaController.Listener {
    override fun onError(controller: MediaController, sessionError: SessionError) {
      // Handle nonfatal error.
    }
  })
  .buildAsync()

Java

MediaController.Builder future =
    new MediaController.Builder(context, sessionToken)
        .setListener(
            new MediaController.Listener() {
              @Override
              public void onError(MediaController controller, SessionError sessionError) {
                // Handle nonfatal error.
              }
            });