此页面由 Cloud Translation API 翻译。

使用 MediaSessionService 在后台播放

人们通常希望在应用不在前台时播放媒体。例如，当用户锁定设备或使用其他应用时，音乐播放器通常会继续播放音乐。Media3 库提供了一系列接口，可让您支持后台播放。

使用 MediaSessionService

如需启用后台播放，您应在单独的 Service 中包含 Player 和 MediaSession。这样一来，即使您的应用不在前台运行，设备也能继续提供媒体内容。

MediaSessionService 允许媒体会话单独运行
从应用的 activity — **图 1**：`MediaSessionService` 允许媒体与应用的 activity 分开运行

在 Service 中托管播放器时，您应使用 MediaSessionService。为此，请创建一个扩展 MediaSessionService 的类，并在其中创建媒体会话。

使用 MediaSessionService 可允许 Google 等外部客户端支持 Google 助理、系统媒体控件或 Wear OS 等配套设备您的服务、连接到该服务并控制播放，所有这些操作都无需访问您的应用的界面活动事实上，您可以连接多个客户端应用 MediaSessionService，每个应用都有自己的 MediaController。

实现服务生命周期

您需要实现服务的三个生命周期方法：

当第一个控制器即将连接且服务被实例化并启动时，系统会调用 onCreate()。这是构建 Player 和 MediaSession。
当用户从近期任务中关闭应用时，系统会调用 onTaskRemoved(Intent)。如果播放正在进行，应用可以选择保留该服务在前台运行的应用如果播放器已暂停，则该服务不在需要停止在前台运行
当服务停止时，系统会调用 onDestroy()。需要释放所有资源，包括播放器和会话。

Kotlin

class PlaybackService : MediaSessionService() {
  private var mediaSession: MediaSession? = null

  // Create your player and media session in the onCreate lifecycle event
  override fun onCreate() {
    super.onCreate()
    val player = ExoPlayer.Builder(this).build()
    mediaSession = MediaSession.Builder(this, player).build()
  }

  // The user dismissed the app from the recent tasks
  override fun onTaskRemoved(rootIntent: Intent?) {
    val player = mediaSession?.player!!
    if (!player.playWhenReady
        || player.mediaItemCount == 0
        || player.playbackState == Player.STATE_ENDED) {
      // Stop the service if not playing, continue playing in the background
      // otherwise.
      stopSelf()
    }
  }

  // Remember to release the player and media session in onDestroy
  override fun onDestroy() {
    mediaSession?.run {
      player.release()
      release()
      mediaSession = null
    }
    super.onDestroy()
  }
}

Java

public class PlaybackService extends MediaSessionService {
  private MediaSession mediaSession = null;

  // Create your Player and MediaSession in the onCreate lifecycle event
  @Override
  public void onCreate() {
    super.onCreate();
    ExoPlayer player = new ExoPlayer.Builder(this).build();
    mediaSession = new MediaSession.Builder(this, player).build();
  }

  // The user dismissed the app from the recent tasks
  @Override
  public void onTaskRemoved(@Nullable Intent rootIntent) {
    Player player = mediaSession.getPlayer();
    if (!player.getPlayWhenReady()
        || player.getMediaItemCount() == 0
        || player.getPlaybackState() == Player.STATE_ENDED) {
      // Stop the service if not playing, continue playing in the background
      // otherwise.
      stopSelf();
    }
  }

  // Remember to release the player and media session in onDestroy
  @Override
  public void onDestroy() {
    mediaSession.getPlayer().release();
    mediaSession.release();
    mediaSession = null;
    super.onDestroy();
  }
}

除了在后台继续播放之外，应用还可以在用户关闭应用时停止服务：

Kotlin

override fun onTaskRemoved(rootIntent: Intent?) {
  val player = mediaSession.player
  if (player.playWhenReady) {
    // Make sure the service is not in foreground.
    player.pause()
  }
  stopSelf()
}

Java

@Override
public void onTaskRemoved(@Nullable Intent rootIntent) {
  Player player = mediaSession.getPlayer();
  if (player.getPlayWhenReady()) {
    // Make sure the service is not in foreground.
    player.pause();
  }
  stopSelf();
}

提供对媒体会话的访问权限

替换 onGetSession() 方法，以向其他客户端授予对在创建服务时构建的媒体会话的访问权限。

Kotlin

class PlaybackService : MediaSessionService() {
  private var mediaSession: MediaSession? = null
  // [...] lifecycle methods omitted

  override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? =
    mediaSession
}

Java

public class PlaybackService extends MediaSessionService {
  private MediaSession mediaSession = null;
  // [...] lifecycle methods omitted

  @Override
  public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
    return mediaSession;
  }
}

在清单中声明服务

应用需要权限才能运行前台服务。将 FOREGROUND_SERVICE 权限，如果您以 API 34 及更高级别为目标平台，上方还有FOREGROUND_SERVICE_MEDIA_PLAYBACK：

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

您还必须在清单中声明 Service 类，并为其设置 intent 过滤器 MediaSessionService。

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

当应用在搭载 Android 10（API 级别 29）及更高版本的设备上运行时，您必须定义包含 mediaPlayback 的 foregroundServiceType。

使用 `MediaController` 控制播放

在包含播放器界面的 activity 或 fragment 中，您可以与使用 MediaController 在界面与媒体会话之间进行切换。您的界面使用媒体控制器可将命令从界面发送到会话。如需详细了解如何创建和使用 MediaController，请参阅创建 MediaController 指南。

处理界面命令

MediaSession 通过其 MediaSession.Callback 接收来自控制器的命令。初始化 MediaSession 会创建默认值 MediaSession.Callback 的实现，可自动处理所有 MediaController 发送给播放器的命令。

通知

MediaSessionService 会自动为您创建 MediaNotification，在大多数情况下应该可以正常运行。默认情况下，已发布的通知为 MediaStyle 通知及时了解最新信息屏幕上会显示播放控件。MediaNotification 会感知您的会话，可用于控制与同一会话关联的任何其他应用的播放。

例如，使用 MediaSessionService 的音乐在线播放应用会创建一个 MediaNotification，用于根据您的 MediaSession 配置显示当前播放的媒体内容的标题、音乐人和专辑封面以及播放控件。

所需的元数据可以在媒体中提供，也可以作为媒体项，如以下代码段所示：

Kotlin

val mediaItem =
    MediaItem.Builder()
      .setMediaId("media-1")
      .setUri(mediaUri)
      .setMediaMetadata(
        MediaMetadata.Builder()
          .setArtist("David Bowie")
          .setTitle("Heroes")
          .setArtworkUri(artworkUri)
          .build()
      )
      .build()

mediaController.setMediaItem(mediaItem)
mediaController.prepare()
mediaController.play()

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setMediaId("media-1")
        .setUri(mediaUri)
        .setMediaMetadata(
            new MediaMetadata.Builder()
                .setArtist("David Bowie")
                .setTitle("Heroes")
                .setArtworkUri(artworkUri)
                .build())
        .build();

mediaController.setMediaItem(mediaItem);
mediaController.prepare();
mediaController.play();

应用可以自定义 Android 媒体控件的命令按钮。详细了解如何自定义 Android 媒体控件。

通知自定义

如需自定义通知，请使用 DefaultMediaNotificationProvider.Builder 或通过创建提供程序接口的自定义实现来创建 MediaNotification.Provider。使用 setMediaNotificationProvider 将您的提供商添加到 MediaSessionService。

继续播放

媒体按钮是 Android 设备和其他外围设备上的硬件按钮，例如蓝牙耳机上的播放或暂停按钮。在服务运行时，Media3 会为您处理媒体按钮输入。

声明 Media3 媒体按钮接收器

Media3 包含一个 API，可让用户在应用终止后（甚至在设备重启后）继续播放。默认情况下，播放恢复功能处于关闭状态。这意味着，当您的服务未运行时，用户无法恢复播放。如需选择启用，请先在清单中声明 MediaButtonReceiver：

<receiver android:name="androidx.media3.session.MediaButtonReceiver"
  android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</receiver>

实现继续播放回调

当蓝牙设备或 Android 系统界面恢复功能； onPlaybackResumption() 回调方法。

Kotlin

override fun onPlaybackResumption(
    mediaSession: MediaSession,
    controller: ControllerInfo
): ListenableFuture<MediaItemsWithStartPosition> {
  val settable = SettableFuture.create<MediaItemsWithStartPosition>()
  scope.launch {
    // Your app is responsible for storing the playlist and the start position
    // to use here
    val resumptionPlaylist = restorePlaylist()
    settable.set(resumptionPlaylist)
  }
  return settable
}

Java

@Override
public ListenableFuture<MediaItemsWithStartPosition> onPlaybackResumption(
    MediaSession mediaSession,
    ControllerInfo controller
) {
  SettableFuture<MediaItemsWithStartPosition> settableFuture = SettableFuture.create();
  settableFuture.addListener(() -> {
    // Your app is responsible for storing the playlist and the start position
    // to use here
    MediaItemsWithStartPosition resumptionPlaylist = restorePlaylist();
    settableFuture.set(resumptionPlaylist);
  }, MoreExecutors.directExecutor());
  return settableFuture;
}

如果您已经存储了其他参数（如播放速度、重复模式或随机播放模式，onPlaybackResumption() 是配置播放器的理想位置参数，然后 Media3 准备播放器，并在出现以下情况时开始播放回调完成。

高级控制器配置和向后兼容性

一种常见的场景就是在应用界面中使用 MediaController 来控制播放并显示播放列表。同时，该会话会公开给外部客户端，例如移动设备或电视上的 Android 媒体控件和 Google 助理、手表上的 Wear OS 和汽车上的 Android Auto。Media3 会话演示应用是实现此类场景的应用示例。

这些外部客户端可能会使用旧版 AndroidX 库的 MediaControllerCompat 或 Android 框架的 android.media.session.MediaController 等 API。Media3 与旧版库完全向后兼容，并支持与 Android 框架 API 互操作。

使用媒体通知控制器

请务必注意，这些旧版控制器或框架控制器框架 PlaybackState.getActions() 中的相同值 PlaybackState.getCustomActions()。要确定框架会话，那么应用可以使用媒体通知控制器并设置其可用命令和自定义布局。该服务会将媒体通知控制器连接到您的会话，而会话会使用回调的 onConnect() 返回的 ConnectionResult 来配置框架会话的操作和自定义操作。

鉴于仅针对移动设备的情况，应用可以提供 MediaSession.Callback.onConnect() 用于设置可用命令，自定义布局，如下所示：

Kotlin

override fun onConnect(
  session: MediaSession,
  controller: MediaSession.ControllerInfo
): ConnectionResult {
  if (session.isMediaNotificationController(controller)) {
    val sessionCommands =
      ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
        .add(customCommandSeekBackward)
        .add(customCommandSeekForward)
        .build()
    val playerCommands =
      ConnectionResult.DEFAULT_PLAYER_COMMANDS.buildUpon()
        .remove(COMMAND_SEEK_TO_PREVIOUS)
        .remove(COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
        .remove(COMMAND_SEEK_TO_NEXT)
        .remove(COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
        .build()
    // Custom layout and available commands to configure the legacy/framework session.
    return AcceptedResultBuilder(session)
      .setCustomLayout(
        ImmutableList.of(
          createSeekBackwardButton(customCommandSeekBackward),
          createSeekForwardButton(customCommandSeekForward))
      )
      .setAvailablePlayerCommands(playerCommands)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default custom layout for all other controllers.
  return AcceptedResultBuilder(session).build()
}

Java

@Override
public ConnectionResult onConnect(
    MediaSession session, MediaSession.ControllerInfo controller) {
  if (session.isMediaNotificationController(controller)) {
    SessionCommands sessionCommands =
        ConnectionResult.DEFAULT_SESSION_COMMANDS
            .buildUpon()
            .add(customCommandSeekBackward)
            .add(customCommandSeekForward)
            .build();
    Player.Commands playerCommands =
        ConnectionResult.DEFAULT_PLAYER_COMMANDS
            .buildUpon()
            .remove(COMMAND_SEEK_TO_PREVIOUS)
            .remove(COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM)
            .remove(COMMAND_SEEK_TO_NEXT)
            .remove(COMMAND_SEEK_TO_NEXT_MEDIA_ITEM)
            .build();
    // Custom layout and available commands to configure the legacy/framework session.
    return new AcceptedResultBuilder(session)
        .setCustomLayout(
            ImmutableList.of(
                createSeekBackwardButton(customCommandSeekBackward),
                createSeekForwardButton(customCommandSeekForward)))
        .setAvailablePlayerCommands(playerCommands)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands without default custom layout for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

授权 Android Auto 发送自定义命令

使用 MediaLibraryService 并通过移动应用支持 Android Auto 时，Android Auto 控制器需要适当的可用命令，否则 Media3 会拒绝来自该控制器的传入自定义命令：

Kotlin

override fun onConnect(
  session: MediaSession,
  controller: MediaSession.ControllerInfo
): ConnectionResult {
  val sessionCommands =
    ConnectionResult.DEFAULT_SESSION_AND_LIBRARY_COMMANDS.buildUpon()
      .add(customCommandSeekBackward)
      .add(customCommandSeekForward)
      .build()
  if (session.isMediaNotificationController(controller)) {
    // [...] See above.
  } else if (session.isAutoCompanionController(controller)) {
    // Available session commands to accept incoming custom commands from Auto.
    return AcceptedResultBuilder(session)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default custom layout for all other controllers.
  return AcceptedResultBuilder(session).build()
}

Java

@Override
public ConnectionResult onConnect(
    MediaSession session, MediaSession.ControllerInfo controller) {
  SessionCommands sessionCommands =
      ConnectionResult.DEFAULT_SESSION_COMMANDS
          .buildUpon()
          .add(customCommandSeekBackward)
          .add(customCommandSeekForward)
          .build();
  if (session.isMediaNotificationController(controller)) {
    // [...] See above.
  } else if (session.isAutoCompanionController(controller)) {
    // Available commands to accept incoming custom commands from Auto.
    return new AcceptedResultBuilder(session)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands without default custom layout for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

会话演示应用具有汽车模块，，用于证明对需要单独 APK 的 Automotive OS 的支持。

使用 MediaSessionService 在后台播放

使用 MediaSessionService

实现服务生命周期

Kotlin

Java

Kotlin

Java

提供对媒体会话的访问权限

Kotlin

Java

在清单中声明服务

使用 MediaController 控制播放

处理界面命令

通知

Kotlin

Java

通知自定义

继续播放

声明 Media3 媒体按钮接收器

实现继续播放回调

Kotlin

Java

高级控制器配置和向后兼容性

使用媒体通知控制器

Kotlin

Java

授权 Android Auto 发送自定义命令

Kotlin

Java

使用 `MediaController` 控制播放