Hintergrundwiedergabe mit MediaSessionService

Häufig ist es sinnvoll, Medien abzuspielen, während sich eine App nicht im Vordergrund befindet. Ein Musikplayer spielt beispielsweise die Musik in der Regel weiter ab, wenn der Nutzer sein Gerät gesperrt hat oder eine andere App verwendet. Die Media3-Bibliothek bietet verschiedene Oberflächen, mit denen die Hintergrundwiedergabe unterstützt werden kann.

MediaSessionService verwenden

Zur Aktivierung der Hintergrundwiedergabe solltest du Player und MediaSession in einen separaten Service aufnehmen. So kann das Gerät weiterhin Medien bereitstellen, auch wenn deine App nicht im Vordergrund ausgeführt wird.

Wenn Sie einen Player in einem Dienst hosten, sollten Sie einen MediaSessionService verwenden. Erstellen Sie dazu eine Klasse, die MediaSessionService erweitert, und erstellen Sie darin Ihre Mediensitzung.

Mit MediaSessionService können externe Clients wie Google Assistant, die Mediensteuerung des Systems oder Companion-Geräte wie Wear OS deinen Dienst finden, eine Verbindung dazu herstellen und die Wiedergabe steuern, ohne auf die UI-Aktivitäten deiner App zugreifen zu müssen. Tatsächlich können mehrere Clientanwendungen gleichzeitig mit demselben MediaSessionService verbunden sein, wobei jede Anwendung eine eigene MediaController hat.

Dienstlebenszyklus implementieren

Sie müssen drei Lebenszyklusmethoden Ihres Dienstes implementieren:

• onCreate() wird aufgerufen, wenn der erste Controller eine Verbindung herstellt und der Dienst instanziiert und gestartet wird. Dies ist der beste Ort, um Player und MediaSession zu erstellen.
• onTaskRemoved(Intent) wird aufgerufen, wenn der Nutzer die App aus den letzten Aufgaben schließt. Wenn die Wiedergabe läuft, kann die App den Dienst auch im Vordergrund ausführen. Wenn der Player pausiert ist, befindet sich der Dienst nicht im Vordergrund und muss beendet werden.
• onDestroy() wird aufgerufen, wenn der Dienst angehalten wird. Alle Ressourcen, einschließlich Spieler und Sitzung, müssen freigegeben werden.

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

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

Anstatt die Wiedergabe im Hintergrund fortzusetzen, kann eine App den Dienst in jedem Fall beenden, wenn der Nutzer die App schließt:

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

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

Zugriff auf die Mediensitzung gewähren

Überschreiben Sie die Methode onGetSession(), um anderen Clients Zugriff auf Ihre Mediensitzung zu gewähren, die beim Erstellen des Dienstes erstellt wurde.

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

Dienst im Manifest deklarieren

Eine App benötigt eine Berechtigung zum Ausführen eines Diensts im Vordergrund. Fügen Sie dem Manifest die Berechtigung FOREGROUND_SERVICE hinzu. Wenn Sie auf API 34 und höher abzielen, fügen Sie auch FOREGROUND_SERVICE_MEDIA_PLAYBACK hinzu:

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

Außerdem müssen Sie im Manifest die Klasse Service mit dem Intent-Filter MediaSessionService deklarieren.

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

Wenn deine App auf einem Gerät mit Android 10 (API-Level 29) oder höher ausgeführt wird, musst du eine foregroundServiceType definieren, die mediaPlayback enthält.

Wiedergabe mit einem MediaController steuern

In der Aktivität oder dem Fragment, das deine Player-UI enthält, kannst du mithilfe eines MediaController eine Verknüpfung zwischen der UI und deiner Mediensitzung herstellen. Die UI verwendet den Mediacontroller, um Befehle von der UI an den Player innerhalb der Sitzung zu senden. Weitere Informationen zum Erstellen und Verwenden eines MediaController-Objekts finden Sie im Leitfaden zum Erstellen eines MediaController.

UI-Befehle verarbeiten

MediaSession empfängt Befehle vom Controller über seinen MediaSession.Callback. Durch das Initialisieren eines MediaSession wird eine Standardimplementierung von MediaSession.Callback erstellt, die automatisch alle Befehle verarbeitet, die ein MediaController an deinen Player sendet.

Benachrichtigung

Ein MediaSessionService erstellt automatisch eine MediaNotification, die in den meisten Fällen funktionieren sollte. Die veröffentlichte Benachrichtigung ist standardmäßig eine MediaStyle-Benachrichtigung, die mit den neuesten Informationen aus Ihrer Mediensitzung aktualisiert wird und die Wiedergabesteuerung enthält. Das MediaNotification erkennt Ihre Sitzung und kann verwendet werden, um die Wiedergabe für alle anderen Apps zu steuern, die mit derselben Sitzung verbunden sind.

Eine Musikstreaming-App mit MediaSessionService würde beispielsweise ein MediaNotification erstellen, das den Titel, den Künstler und das Albumcover des aktuellen Medienelements anzeigt, das zusammen mit der Wiedergabesteuerung basierend auf Ihrer MediaSession-Konfiguration wiedergegeben wird.

Die erforderlichen Metadaten können im Medium bereitgestellt oder als Teil des Medienelements wie im folgenden Snippet deklariert werden:

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

Apps können die Befehlsschaltflächen der Android Media-Steuerelemente anpassen. Weitere Informationen zum Anpassen der Android Media-Steuerelemente

Benachrichtigungsanpassung

Wenn Sie die Benachrichtigung anpassen möchten, erstellen Sie einen MediaNotification.Provider mit DefaultMediaNotificationProvider.Builder oder erstellen Sie eine benutzerdefinierte Implementierung der Anbieterschnittstelle. Fügen Sie Ihren Anbieter mit setMediaNotificationProvider zu MediaSessionService hinzu.

Wiedergabe wird fortgesetzt

Medientasten sind Hardwaretasten auf Android-Geräten und anderen Peripheriegeräten, z. B. die Wiedergabe- oder Pausetaste an einem Bluetooth-Headset. Media3 verarbeitet die Eingaben von Medienschaltflächen für Sie, wenn der Dienst ausgeführt wird.

Media3-Medienschaltflächen-Empfänger deklarieren

Media3 enthält eine API, mit der Nutzer die Wiedergabe nach dem Beenden einer App und sogar nach dem Neustart des Geräts fortsetzen können. Standardmäßig ist die Fortsetzung der Wiedergabe deaktiviert. Das bedeutet, dass der Nutzer die Wiedergabe nicht fortsetzen kann, wenn Ihr Dienst nicht ausgeführt wird. Zur Aktivierung musst du zuerst MediaButtonReceiver in deinem Manifest deklarieren:

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

Callback für die Wiederaufnahme der Wiedergabe implementieren

Wenn die Fortsetzung der Wiedergabe entweder von einem Bluetooth-Gerät oder von der Wiederaufnahmefunktion der Android System-UI angefordert wird, wird die Callback-Methode onPlaybackResumption() aufgerufen.

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
}

@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;
}

Wenn du andere Parameter wie Wiedergabegeschwindigkeit, Wiederholungsmodus oder Zufallsmix gespeichert hast, eignet sich onPlaybackResumption() am besten, um den Player mit diesen Parametern zu konfigurieren, bevor Media3 den Player vorbereitet und die Wiedergabe startet, wenn der Callback abgeschlossen ist.

Erweiterte Controller-Konfiguration und Abwärtskompatibilität

In einem häufig verwendeten Szenario wird ein MediaController in der App-UI verwendet, um die Wiedergabe zu steuern und die Playlist anzuzeigen. Gleichzeitig wird die Sitzung externen Clients wie der Android-Mediensteuerung und Assistant auf Mobilgeräten oder Fernsehern, Wear OS für Uhren und Android Auto in Autos präsentiert. Die Media3-Sitzungsdemo-App ist ein Beispiel für eine App, in der ein solches Szenario implementiert wird.

Diese externen Clients können APIs wie MediaControllerCompat der alten AndroidX-Bibliothek oder android.media.session.MediaController des Android-Frameworks verwenden. Media3 ist vollständig abwärtskompatibel mit der Legacy-Bibliothek und bietet Interoperabilität mit der Android Framework API.

Controller für Medienbenachrichtigungen verwenden

Es ist wichtig zu verstehen, dass diese Legacy- oder Framework-Controller dieselben Werte aus dem Framework PlaybackState.getActions() und PlaybackState.getCustomActions() lesen. Um Aktionen und benutzerdefinierte Aktionen der Framework-Sitzung zu ermitteln, kann eine App den Media Notification Controller verwenden und die verfügbaren Befehle und das benutzerdefinierte Layout festlegen. Der Dienst verbindet den Media Notification-Controller mit Ihrer Sitzung. Die Sitzung verwendet das vom onConnect() des Callbacks zurückgegebene ConnectionResult, um Aktionen und benutzerdefinierte Aktionen der Framework-Sitzung zu konfigurieren.

In einem rein mobilen Szenario kann eine App eine Implementierung von MediaSession.Callback.onConnect() bereitstellen, um verfügbare Befehle und ein benutzerdefiniertes Layout speziell für die Framework-Sitzung festzulegen:

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

@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 zum Senden benutzerdefinierter Befehle autorisieren

Wenn ein MediaLibraryService verwendet wird und Android Auto mit der mobilen App unterstützt wird, benötigt der Android Auto-Controller entsprechende verfügbare Befehle. Andernfalls würde Media3 eingehende benutzerdefinierte Befehle von diesem Controller ablehnen:

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

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

Die Sitzungsdemo-App hat ein Automotive-Modul, das die Unterstützung für Automotive OS veranschaulicht, für die ein separates APK erforderlich ist.