使用 MediaSession 控制和通告播放

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

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

何时选择媒体会话

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

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

这非常适用于许多用例。具体而言，在以下情况下，您强烈建议使用 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 库会使用播放器的状态自动更新媒体会话。因此，您无需手动处理玩家与会话之间的映射。

这与旧版方法不同，旧版方法需要您独立于播放器本身创建和维护 PlaybackStateCompat，例如指示任何错误。

注意： 如果您的应用依赖于上述播放状态与客户端通信（例如，向 Android Automotive OS 应用添加身份验证），则在迁移到 Media3 时需要注意。这是因为 Media3 的自动状态管理功能取代了之前的此功能。请稍后再回来查看有关如何妥善处理此类情况的更详细指南。

唯一会话 ID

默认情况下，MediaSession.Builder 会创建一个会话，并将空字符串用作会话 ID。如果应用打算仅创建单个会话实例（这是最常见的情况），则这已足够。

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

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

向其他客户端授予控制权

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

图 1：媒体控制器有助于将命令从外部来源传递到媒体会话。

注意： 在后台播放媒体时，您的 MediaSession 和播放器需要位于作为前台服务运行的 MediaSessionService 或 MediaLibraryService 中。如需了解详情，请参阅使用 MediaSessionService 进行后台播放。

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

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

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

修改播放列表

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

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

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

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

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

管理自定义布局和自定义命令

以下部分介绍了如何向客户端应用通告自定义命令按钮的自定义布局，以及如何授权控制器发送自定义命令。

定义会话的自定义布局

如需向客户端应用指明您希望向用户显示哪些播放控件，请在服务的 onCreate() 方法中构建 MediaSession 时设置会话的自定义布局。

Kotlin

override fun onCreate() {
  super.onCreate()

  val likeButton = CommandButton.Builder()
    .setDisplayName("Like")
    .setIconResId(R.drawable.like_icon)
    .setSessionCommand(SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
    .build()
  val favoriteButton = CommandButton.Builder()
    .setDisplayName("Save to favorites")
    .setIconResId(R.drawable.favorite_icon)
    .setSessionCommand(SessionCommand(SAVE_TO_FAVORITES, Bundle()))
    .build()

  session =
    MediaSession.Builder(this, player)
      .setCallback(CustomMediaSessionCallback())
      .setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
      .build()
}

Java

@Override
public void onCreate() {
  super.onCreate();

  CommandButton likeButton = new CommandButton.Builder()
    .setDisplayName("Like")
    .setIconResId(R.drawable.like_icon)
    .setSessionCommand(new SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING))
    .build();
  CommandButton favoriteButton = new CommandButton.Builder()
    .setDisplayName("Save to favorites")
    .setIconResId(R.drawable.favorite_icon)
    .setSessionCommand(new SessionCommand(SAVE_TO_FAVORITES, new Bundle()))
    .build();

  Player player = new ExoPlayer.Builder(this).build();
  mediaSession =
      new MediaSession.Builder(this, player)
          .setCallback(new CustomMediaSessionCallback())
          .setCustomLayout(ImmutableList.of(likeButton, favoriteButton))
          .build();
}

声明可用的玩家和自定义命令

媒体应用可以定义自定义命令，例如在自定义布局中使用。例如，您可能希望实现一些按钮，以便用户将媒体内容保存到收藏夹列表中。MediaController 发送自定义命令，MediaSession.Callback 接收这些命令。

您可以定义 MediaController 连接到媒体会话时可以使用哪些自定义会话命令。您可以通过替换 MediaSession.Callback.onConnect() 来实现这一目的。在 onConnect 回调方法中，接受来自 MediaController 的连接请求时配置并返回一组可用命令：

Kotlin

private inner 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 inner 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 属性来跟踪哪个媒体控制器正在发出请求。这样，您就可以根据给定命令（如果来自系统、您自己的应用或其他客户端应用）来定制应用的行为。

注意 ：您必须将自定义命令作为全新行为来实现。请勿使用自定义命令替换 Player 界面中定义的标准控件之一。

在用户互动后更新自定义布局

处理自定义命令或与玩家进行任何其他互动后，您可能需要更新控制器界面中显示的布局。一个典型的示例是，切换按钮会在触发与此按钮关联的操作后更改其图标。如需更新布局，您可以使用 MediaSession.setCustomLayout：

Kotlin

val removeFromFavoritesButton = CommandButton.Builder()
  .setDisplayName("Remove from favorites")
  .setIconResId(R.drawable.favorite_remove_icon)
  .setSessionCommand(SessionCommand(REMOVE_FROM_FAVORITES, Bundle()))
  .build()
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton))

Java

CommandButton removeFromFavoritesButton = new CommandButton.Builder()
  .setDisplayName("Remove from favorites")
  .setIconResId(R.drawable.favorite_remove_icon)
  .setSessionCommand(new SessionCommand(REMOVE_FROM_FAVORITES, new Bundle()))
  .build();
mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton));

自定义播放命令行为

如需自定义 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 方法。

应用可以通过替换 MediaSession.Callback.onMediaButtonEvent(Intent) 来替换默认行为。在这种情况下，应用可以/需要自行处理所有 API 细节。

错误处理和报告

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

严重的播放错误

播放器会将严重的播放错误报告给会话，然后再报告给控制器，以便通过 Player.Listener.onPlayerError(PlaybackException) 和 Player.Listener.onPlayerErrorChanged(@Nullable PlaybackException) 进行调用。

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

为了实现互操作性，系统会将严重错误复制到平台会话的 PlaybackStateCompat，方法是将其状态转换为 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();

转发播放器会向实际播放器注册 Player.Listener，并拦截报告错误的回调。然后，系统会将自定义的 PlaybackException 委托给在转发播放器上注册的监听器。为此，转发播放器会替换 Player.addListener 和 Player.removeListener，以便访问用于发送自定义错误代码、消息或 extra 的监听器：

Kotlin

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

  private val listeners: MutableList<Player.Listener> = mutableListOf()

  private var customizedPlaybackException: PlaybackException? = null

  init {
    player.addListener(ErrorCustomizationListener())
  }

  override fun addListener(listener: Player.Listener) {
    listeners.add(listener)
  }

  override fun removeListener(listener: Player.Listener) {
    listeners.remove(listener)
  }

  override fun getPlayerError(): PlaybackException? {
    return customizedPlaybackException
  }

  private inner class ErrorCustomizationListener : Player.Listener {

    override fun onPlayerErrorChanged(error: PlaybackException?) {
      customizedPlaybackException = error?.let { customizePlaybackException(it) }
      listeners.forEach { it.onPlayerErrorChanged(customizedPlaybackException) }
    }

    override fun onPlayerError(error: PlaybackException) {
      listeners.forEach { it.onPlayerError(customizedPlaybackException!!) }
    }

    private 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)
        }
        // Apps can customize further error messages by adding more branches.
        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)
    }

    override fun onEvents(player: Player, events: Player.Events) {
      listeners.forEach {
        it.onEvents(player, events)
      }
    }
    // Delegate all other callbacks to all listeners without changing arguments like onEvents.
  }
}

Java

private static class ErrorForwardingPlayer extends ForwardingPlayer {

  private final Context context;
  private List<Player.Listener> listeners;
  @Nullable private PlaybackException customizedPlaybackException;

  public ErrorForwardingPlayer(Context context, Player player) {
    super(player);
    this.context = context;
    listeners = new ArrayList<>();
    player.addListener(new ErrorCustomizationListener());
  }

  @Override
  public void addListener(Player.Listener listener) {
    listeners.add(listener);
  }

  @Override
  public void removeListener(Player.Listener listener) {
    listeners.remove(listener);
  }

  @Nullable
  @Override
  public PlaybackException getPlayerError() {
    return customizedPlaybackException;
  }

  private class ErrorCustomizationListener implements Listener {

    @Override
    public void onPlayerErrorChanged(@Nullable PlaybackException error) {
      customizedPlaybackException =
          error != null ? customizePlaybackException(error, context) : null;
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onPlayerErrorChanged(customizedPlaybackException);
      }
    }

    @Override
    public void onPlayerError(PlaybackException error) {
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onPlayerError(checkNotNull(customizedPlaybackException));
      }
    }

    private PlaybackException customizePlaybackException(
        PlaybackException error, Context context) {
      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;
        // Apps can customize further error messages by adding more case statements.
        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);
    }

    @Override
    public void onEvents(Player player, Events events) {
      for (int i = 0; i < listeners.size(); i++) {
        listeners.get(i).onEvents(player, events);
      }
    }
    // Delegate all other callbacks to all listeners without changing arguments like onEvents.
  }
}

非严重错误

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

Kotlin

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

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

// Interoperability: Sending a nonfatal error to the media notification controller 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));

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

// Interoperability: Sending a nonfatal error to the media notification controller 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);
}

发送到媒体通知控制器的非严重错误会复制到平台会话的 PlaybackStateCompat。因此，只有错误代码和错误消息会相应地设置为 PlaybackStateCompat，而 PlaybackStateCompat.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.
              }
            });