Cómo reproducir contenido en segundo plano con un MediaSessionService

A menudo, es conveniente reproducir contenido multimedia cuando una app no está en primer plano. Por ejemplo, un reproductor de música generalmente sigue reproduciendo música cuando el usuario bloqueó su dispositivo o está usando otra app. La biblioteca de Media3 proporciona una serie de interfaces que te permiten admitir la reproducción en segundo plano.

Cómo usar un MediaSessionService

Para habilitar la reproducción en segundo plano, debes incluir Player y MediaSession dentro de un Service independiente. Esto permite que el dispositivo siga publicando contenido multimedia incluso cuando tu app no está en primer plano.

Cuando alojes a un jugador dentro de un servicio, debes usar un MediaSessionService. Para ello, crea una clase que extienda MediaSessionService y crea tu sesión de medios dentro de ella.

Usar MediaSessionService permite que los clientes externos, como el Asistente de Google, los controles multimedia del sistema, los botones multimedia en dispositivos periféricos o los dispositivos complementarios, como Wear OS, descubran tu servicio, se conecten a él y controlen la reproducción, todo sin acceder a la actividad de la IU de tu app. De hecho, pueden conectarse varias apps cliente al mismo MediaSessionService a la vez, cada aplicación con su propio MediaController.

Implementa el ciclo de vida del servicio

Debes implementar dos métodos de ciclo de vida de tu servicio:

• Se llama a onCreate() cuando el primer control está a punto de conectarse y se crea una instancia del servicio y se inicia. Es el mejor lugar para crear Player y MediaSession.
• Se llama a onDestroy() cuando se detiene el servicio. Se deben liberar todos los recursos, incluidos el reproductor y la sesión.

De manera opcional, puedes anular onTaskRemoved(Intent) para personalizar lo que sucede cuando el usuario descarta la app de las tareas recientes. De forma predeterminada, el servicio se deja en ejecución si la reproducción está en curso y se detiene en caso contrario.

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()
  }

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

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();
  }

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

Como alternativa para mantener la reproducción en segundo plano, puedes detener el servicio en cualquier caso cuando el usuario descarte la app:

override fun onTaskRemoved(rootIntent: Intent?) {
  pauseAllPlayersAndStopSelf()
}

@Override
public void onTaskRemoved(@Nullable Intent rootIntent) {
  pauseAllPlayersAndStopSelf();
}

Para cualquier otra implementación manual de onTaskRemoved, puedes usar isPlaybackOngoing() para verificar si la reproducción se considera en curso y si se inició el servicio en primer plano.

Proporciona acceso a la sesión multimedia

Anula el método onGetSession() para darles a otros clientes acceso a tu sesión de medios que se creó cuando se creó el servicio.

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

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

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

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

Cómo declarar el servicio en el manifiesto

Una app requiere los permisos FOREGROUND_SERVICE y FOREGROUND_SERVICE_MEDIA_PLAYBACK para ejecutar un servicio en primer plano de reproducción:

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

También debes declarar tu clase Service en el manifiesto con un filtro de intents de MediaSessionService y un foregroundServiceType que incluya mediaPlayback.

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

Controla la reproducción con un objeto MediaController

En la actividad o el fragmento que contiene la IU del reproductor, puedes establecer un vínculo entre la IU y la sesión multimedia con un MediaController. Tu IU usa el controlador multimedia para enviar comandos desde la IU al reproductor dentro de la sesión. Consulta la guía Crea un MediaController para obtener detalles sobre cómo crear y usar un MediaController.

Cómo controlar comandos de MediaController

El MediaSession recibe comandos del controlador a través de su MediaSession.Callback. Inicializar un MediaSession crea una implementación predeterminada de MediaSession.Callback que controla automáticamente todos los comandos que un MediaController envía a tu reproductor.

Notificación

Un MediaSessionService crea automáticamente un MediaNotification para ti que debería funcionar en la mayoría de los casos. De forma predeterminada, la notificación publicada es una notificación de MediaStyle que se mantiene actualizada con la información más reciente de tu sesión multimedia y muestra los controles de reproducción. El objeto MediaNotification conoce tu sesión y se puede usar para controlar la reproducción de cualquier otra app que esté conectada a la misma sesión.

Por ejemplo, una app de transmisión de música que usa un MediaSessionService crearía un MediaNotification que muestra el título, el artista y la portada del álbum del elemento multimedia actual que se está reproduciendo junto con los controles de reproducción basados en tu configuración de MediaSession.

Los metadatos obligatorios se pueden proporcionar en el medio o declarar como parte del elemento multimedia, como en el siguiente fragmento:

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()

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();

Ciclo de vida de las notificaciones

La notificación se crea en cuanto el Player tiene instancias de MediaItem en su playlist.

Todas las actualizaciones de notificaciones se realizan automáticamente según el estado de Player y MediaSession.

La notificación no se puede quitar mientras se ejecuta el servicio en primer plano. Para quitar la notificación de inmediato, debes llamar a Player.release() o borrar la playlist con Player.clearMediaItems().

Si el reproductor se pausa, se detiene o falla durante más de 10 minutos sin más interacciones del usuario, el servicio pasa automáticamente del estado de servicio en primer plano para que el sistema pueda destruirlo. Puedes implementar la reanudación de la reproducción para permitir que un usuario reinicie el ciclo de vida del servicio y reanude la reproducción en un momento posterior.

Personalización de notificaciones

Los metadatos sobre el elemento que se está reproduciendo actualmente se pueden personalizar modificando MediaItem.MediaMetadata. Si deseas actualizar los metadatos de un elemento existente, puedes usar Player.replaceMediaItem para actualizar los metadatos sin interrumpir la reproducción.

También puedes personalizar algunos de los botones que se muestran en la notificación configurando preferencias de botones multimedia personalizados para los controles multimedia de Android. Obtén más información para personalizar los controles multimedia de Android.

Para personalizar aún más la notificación, crea un MediaNotification.Provider con DefaultMediaNotificationProvider.Builder o crea una implementación personalizada de la interfaz del proveedor. Agrega tu proveedor a tu MediaSessionService con setMediaNotificationProvider.

Reanudación de la reproducción

Después de que se finaliza el MediaSessionService, e incluso después de que se reinicia el dispositivo, es posible ofrecer la reanudación de la reproducción para permitir que los usuarios reinicien el servicio y reanuden la reproducción donde la dejaron. De forma predeterminada, la reanudación de la reproducción está desactivada, lo que significa que el usuario no puede reanudar la reproducción cuando el servicio no se está ejecutando. Para habilitar esta función, debes declarar un receptor de botones de medios e implementar el método onPlaybackResumption.

Declara el receptor del botón de medios de Media3

Comienza por declarar MediaButtonReceiver en tu manifiesto:

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

Implementa la devolución de llamada de reanudación de la reproducción

Cuando un dispositivo Bluetooth o la función de reanudación de la IU del sistema Android solicitan la reanudación de la reproducción, se llama al método de devolución de llamada onPlaybackResumption().

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

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

Si almacenaste otros parámetros, como la velocidad de reproducción, el modo de repetición o el modo aleatorio, onPlaybackResumption() es un buen lugar para configurar el reproductor con estos parámetros antes de que Media3 lo prepare y comience la reproducción cuando se complete la devolución de llamada.

Se llama a este método durante el tiempo de inicio para crear la notificación de reanudación de la IU del sistema de Android después de reiniciar el dispositivo. En el caso de una notificación enriquecida, se recomienda completar los campos MediaMetadata, como title y artworkData o artworkUri del elemento actual, con valores disponibles de forma local, ya que es posible que el acceso a la red aún no esté disponible. También puedes agregar MediaConstants.EXTRAS_KEY_COMPLETION_STATUS y MediaConstants.EXTRAS_KEY_COMPLETION_PERCENTAGE a MediaMetadata.extras para indicar la posición de reproducción de reanudación.

Configuración avanzada del controlador y retrocompatibilidad

Un caso de uso común es usar un MediaController en la IU de la app para controlar la reproducción y mostrar la playlist. Al mismo tiempo, la sesión se expone a clientes externos, como los controles multimedia de Android y el Asistente en dispositivos móviles o TVs, Wear OS para relojes y Android Auto en automóviles. La app de demostración de sesiones de Media3 es un ejemplo de una app que implementa una situación de este tipo.

Estos clientes externos pueden usar APIs como MediaControllerCompat de la biblioteca heredada de AndroidX o android.media.session.MediaController de la plataforma de Android. Media3 es totalmente retrocompatible con la biblioteca heredada y proporciona interoperabilidad con la API de la plataforma de Android.

Cómo usar el controlador de notificaciones de contenido multimedia

Es importante comprender que estos controladores heredados y de la plataforma comparten el mismo estado y que la visibilidad no se puede personalizar por controlador (por ejemplo, los PlaybackState.getActions() y PlaybackState.getCustomActions() disponibles). Puedes usar el controlador de notificaciones de medios para configurar el conjunto de estados en la sesión de medios de la plataforma para lograr la compatibilidad con estos controladores heredados y de la plataforma.

Por ejemplo, una app puede proporcionar una implementación de MediaSession.Callback.onConnect() para establecer los comandos disponibles y las preferencias de los botones multimedia específicamente para la sesión de la plataforma de la siguiente manera:

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 button preferences and commands to configure the platform session.
    return AcceptedResultBuilder(session)
      .setMediaButtonPreferences(
        ImmutableList.of(
          createSeekBackwardButton(customCommandSeekBackward),
          createSeekForwardButton(customCommandSeekForward))
      )
      .setAvailablePlayerCommands(playerCommands)
      .setAvailableSessionCommands(sessionCommands)
      .build()
  }
  // Default commands with default button preferences for all other controllers.
  return AcceptedResultBuilder(session).build()
}

@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 button preferences and commands to configure the platform session.
    return new AcceptedResultBuilder(session)
        .setMediaButtonPreferences(
            ImmutableList.of(
                createSeekBackwardButton(customCommandSeekBackward),
                createSeekForwardButton(customCommandSeekForward)))
        .setAvailablePlayerCommands(playerCommands)
        .setAvailableSessionCommands(sessionCommands)
        .build();
  }
  // Default commands with default button preferences for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

Autoriza a Android Auto para enviar comandos personalizados

Cuando se usa un MediaLibraryService y para admitir Android Auto con la app para dispositivos móviles, el controlador de Android Auto requiere los comandos disponibles adecuados. De lo contrario, Media3 rechazaría los comandos personalizados entrantes de ese controlador:

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 for all other controllers.
  return AcceptedResultBuilder(session).build()
}

@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 for all other controllers.
  return new AcceptedResultBuilder(session).build();
}

La app de demostración de la sesión tiene un módulo para automóviles que demuestra la compatibilidad con el SO Automotive, que requiere un APK independiente.