Wiedergabesteuerung aktivieren

Wenn Sie die Medienwiedergabe in Android Auto und Android Automotive OS (AAOS) aktivieren möchten, müssen Sie die Wiedergabesteuerung implementieren. Dazu registrieren Sie eine Mediensitzung und verarbeiten ihre Callback-Methoden. Auf dieser Seite erfahren Sie, wie Sie:

  • Registrieren Sie ein MediaSessionCompat-Objekt in Ihrem Medienbrowser-Dienst.

  • Implementiere MediaSessionCompat.Callback-Methoden, um auf Wiedergabeanfragen von Nutzern zu reagieren.

  • Standard- und benutzerdefinierte Wiedergabeaktionen konfigurieren

  • Legen Sie den anfänglichen Wiedergabestatus für Ihre Mediensitzung fest.

  • Es wurden Symbole hinzugefügt, um das Audioformat anzugeben.

  • Links aus aktiv wiedergegebenen Media-Elementen erstellen

Android Auto und AAOS senden Befehle zur Wiedergabesteuerung über MediaSessionCompat für deinen Dienst. Sie müssen eine Sitzung registrieren und die zugehörigen Rückrufmethoden implementieren.

Mediensitzung registrieren

Erstelle in der Methode onCreate deines Media-Browser-Dienstes eine Instanz von MediaSessionCompat und rufe dann setSessionToken auf, um die Media-Sitzung zu registrieren. Dieses Code-Snippet zeigt, wie eine Mediensitzung erstellt und registriert wird:

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Wenn Sie das Media-Sitzungsobjekt erstellen, legen Sie ein Callback-Objekt fest, das zum Verarbeiten von Anfragen zur Wiedergabesteuerung verwendet wird. Sie erstellen dieses Callback-Objekt, indem Sie eine Implementierung der Klasse MediaSessionCompat.Callback für Ihre App bereitstellen. Im nächsten Abschnitt wird beschrieben, wie Sie dieses Objekt implementieren.

Wiedergabebefehle implementieren

Wenn ein Nutzer die Wiedergabe eines Media-Elements über Ihre App anfordert, verwenden Android Automotive OS und Android Auto die Klasse MediaSessionCompat.Callback aus dem MediaSessionCompat-Objekt Ihrer App, das das System von Ihrem Media-Browser-Dienst abruft. Wenn ein Nutzer die Wiedergabe steuern möchte, z. B. die Wiedergabe pausieren oder zum nächsten Titel springen, rufen Android Auto und Android Automotive OS eine der Methoden des Callback-Objekts auf.

Um die Wiedergabe von Inhalten zu verarbeiten, muss Ihre App die abstrakte Klasse MediaSessionCompat.Callback erweitern und die Methoden implementieren, die von Ihrer App unterstützt werden.

Implementieren Sie jede dieser Callback-Methoden, die für den Inhaltstyp Ihrer App sinnvoll sind:

onPrepare
AAOS ruft diese Methode auf, wenn sich die Media-Quelle ändert.
onPlay

Wird aufgerufen, wenn der Nutzer die Wiedergabe auswählt, ohne ein bestimmtes Element auszuwählen. Ihre App muss ihre Standardinhalte abspielen oder, wenn die Wiedergabe mit onPause pausiert wurde, die Wiedergabe fortsetzen.

onPlayFromMediaId

Wird aufgerufen, wenn der Nutzer ein bestimmtes Element abspielen möchte. Die Methode empfängt die ID, die Ihr Mediabrowserdienst dem Media-Element in der Inhaltshierarchie zugewiesen hat.

onPlayFromSearch

Wird aufgerufen, wenn der Nutzer die Wiedergabe über eine Suchanfrage startet. Die App muss eine geeignete Auswahl basierend auf dem übergebenen Suchstring treffen.

onPause

Wird aufgerufen, wenn der Nutzer die Wiedergabe pausiert.

onSkipToNext

Wird aufgerufen, wenn der Nutzer zum nächsten Element springt.

onSkipToPrevious

Wird aufgerufen, wenn der Nutzer zum vorherigen Element springen möchte.

onStop

Wird aufgerufen, wenn der Nutzer die Wiedergabe beenden möchte. Überschreiben Sie diese Methoden in Ihrer App, um das ausgewählte Ergebnis zu liefern. Sie müssen keine Methode implementieren, wenn Ihre App ihren Zweck nicht unterstützt. Wenn in Ihrer App beispielsweise ein Livestream wie eine Sportübertragung wiedergegeben wird, müssen Sie onSkipToNext nicht implementieren. Verwenden Sie stattdessen die Standardimplementierung von onSkipToNext.

Ihre App benötigt keine spezielle Logik, um Inhalte über die Lautsprecher des Autos abzuspielen. Wenn Ihre App eine Anfrage zum Abspielen von Inhalten erhält, wird Audio auf dieselbe Weise wiedergegeben wie über die Lautsprecher oder Kopfhörer eines Smartphones. Android Auto und AAOS senden die Audioinhalte automatisch an das System des Autos, damit sie über die Lautsprecher des Autos wiedergegeben werden.

Weitere Informationen zur Wiedergabe von Audioinhalten finden Sie in der Übersicht über MediaPlayer, der Übersicht über Audio-Apps und der ExoPlayer-Übersicht.

Standard-Wiedergabeaktionen festlegen

In Android Auto und AAOS werden Wiedergabesteuerelemente basierend auf den Aktionen angezeigt, die im PlaybackStateCompat-Objekt aktiviert sind. Standardmäßig muss Ihre App die folgenden Aktionen unterstützen:

Ihre App kann zusätzlich die folgenden Aktionen unterstützen, sofern sie für die Inhalte der App relevant sind:

Sie können auch eine Wiedergabeliste erstellen, die dem Nutzer angezeigt wird. Rufen Sie dazu die Methoden setQueue und setQueueTitle auf, aktivieren Sie die Aktion ACTION_SKIP_TO_QUEUE_ITEM und definieren Sie den Callback onSkipToQueueItem.

Außerdem wird das Symbol Now playing (Wird gerade wiedergegeben) unterstützt, das angibt, was gerade wiedergegeben wird. Rufen Sie dazu die Methode setActiveQueueItemId auf und übergeben Sie die ID des wiedergegebenen Elements in der Warteschlange. Sie müssen setActiveQueueItemId aktualisieren, wenn sich die Warteschlange ändert.

In Android Auto und AAOS werden Schaltflächen für jede aktivierte Aktion sowie die Wiedergabeliste angezeigt. Wenn Nutzer auf diese Schaltflächen klicken, ruft das System den entsprechenden Callback aus MediaSessionCompat.Callback auf.

Nicht genutzten Speicherplatz reservieren

In Android Auto und AAOS wird in der Benutzeroberfläche Platz für die Aktionen ACTION_SKIP_TO_PREVIOUS und ACTION_SKIP_TO_NEXT reserviert. Wenn Ihre App eine dieser Funktionen nicht unterstützt, wird der Bereich in Android Auto und AAOS verwendet, um benutzerdefinierte Aktionen anzuzeigen, die Sie erstellen.

Wenn Sie diese Bereiche nicht mit benutzerdefinierten Aktionen füllen möchten, können Sie sie reservieren, sodass Android Auto und AAOS den Bereich leer lassen, wenn Ihre App die entsprechende Funktion nicht unterstützt.

Rufen Sie dazu die Methode setExtras mit einem Extras-Bundle auf, das Konstanten enthält, die den reservierten Funktionen entsprechen. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT entspricht ACTION_SKIP_TO_NEXT und SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV entspricht ACTION_SKIP_TO_PREVIOUS. Verwenden Sie diese Konstanten als Schlüssel im Bundle und den booleschen Wert true als Werte.

Anfänglichen PlaybackState festlegen

Während Android Auto und AAOS mit Ihrem Media Browser-Dienst kommunizieren, wird der Status der Wiedergabe von Inhalten über die PlaybackStateCompat an Ihre Media Session gesendet.

Ihre App sollte nicht automatisch mit der Musikwiedergabe beginnen, wenn AAOS oder Android Auto eine Verbindung zu Ihrem Mediendienst herstellt. Verlassen Sie sich stattdessen auf Android Auto und AAOS, um die Wiedergabe basierend auf dem Status des Autos oder Nutzeraktionen fortzusetzen oder zu starten.

Setzen Sie dazu den anfänglichen PlaybackStateCompat Ihrer Mediensitzung auf STATE_STOPPED, STATE_PAUSED, STATE_NONE oder STATE_ERROR.

Mediensitzungen in Android Auto und AAOS dauern nur so lange wie die Fahrt. Nutzer starten und beenden diese Sitzungen daher häufig. Damit die Übergänge zwischen Fahrten reibungslos verlaufen, sollten Sie den Status der vorherigen Sitzung des Nutzers im Blick behalten. Wenn die Media-App eine Anfrage zum Fortsetzen erhält, kann der Nutzer automatisch dort weitermachen, wo er aufgehört hat. Dieser Status umfasst das zuletzt wiedergegebene Media-Element, das PlaybackStateCompat-Objekt und die Warteschlange.

Benutzerdefinierte Wiedergabeaktionen hinzufügen

Du kannst benutzerdefinierte Wiedergabeaktionen hinzufügen, um zusätzliche Aktionen anzuzeigen, die deine Media-App unterstützt. Wenn Platz vorhanden ist und Sie ihn nicht reservieren, fügt Android die benutzerdefinierten Aktionen den Transportsteuerungen hinzu. Andernfalls werden die benutzerdefinierten Aktionen im Dreipunkt-Menü angezeigt. Benutzerdefinierte Aktionen werden in Android in der Reihenfolge angezeigt, in der Sie sie PlaybackStateCompat hinzufügen.

Mit benutzerdefinierten Aktionen können Sie ein Verhalten festlegen, das sich von Standardaktionen unterscheidet. Sie dürfen nicht verwendet werden, um Standardaktionen zu ersetzen oder zu duplizieren.

Verwenden Sie die Methode addCustomAction in der Klasse PlaybackStateCompat.Builder, um benutzerdefinierte Aktionen hinzuzufügen. In diesem Code-Snippet sehen Sie, wie Sie die benutzerdefinierte Aktion „Radiosender starten“ hinzufügen:

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Ein detaillierteres Beispiel für diese Methode finden Sie in der setCustomAction-Methode in der Universal Android Music Player-Beispiel-App auf GitHub. Nachdem Sie Ihre benutzerdefinierte Aktion erstellt haben, kann Ihre Mediensitzung auf die Aktionen reagieren, indem Sie die Methode onCustomAction überschreiben.

Dieses Code-Snippet zeigt, wie Ihre App auf die Aktion „Starte einen Radiosender“ reagieren könnte:

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Weitere Informationen finden Sie in der Methode onCustomAction in der Universal Android Music Player-Beispiel-App auf GitHub.

Symbole für benutzerdefinierte Aktionen erstellen

Für jede benutzerdefinierte Aktion, die Sie erstellen, ist ein Symbol erforderlich.

Wenn die Beschreibung dieses Symbols mit einer der CommandButton.ICON_-Konstanten übereinstimmt, legen Sie den Ganzzahlwert für den Schlüssel EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT der Extras der benutzerdefinierten Aktion fest. Auf unterstützten Systemen wird dadurch die an CustomAction.Builder übergebene Symbolressource überschrieben, sodass Systemkomponenten deine Aktion und andere Wiedergabeaktionen einheitlich rendern können.

Sie müssen auch eine Symbolressource angeben. Apps in Autos können auf vielen verschiedenen Bildschirmgrößen und ‑dichten ausgeführt werden. Daher müssen die von Ihnen bereitgestellten Symbole Vektordrawables sein. Verwenden Sie ein Vektor-Drawable, um Assets zu skalieren, ohne dass Details verloren gehen. Bei geringeren Auflösungen können mit einer Vektorgrafik Kanten und Ecken an Pixelgrenzen ausgerichtet werden.

Wenn eine benutzerdefinierte Aktion zustandsbehaftet ist (wenn sie eine Wiedergabeeinstellung ein- oder ausschaltet), stellen Sie verschiedene Symbole für die verschiedenen Zustände bereit, damit Nutzer eine Änderung sehen, wenn sie die Aktion auswählen.

Alternative Symbolstile für deaktivierte Aktionen bereitstellen

Wenn eine benutzerdefinierte Aktion für den aktuellen Kontext nicht verfügbar ist, ersetzen Sie das Symbol für die benutzerdefinierte Aktion durch ein alternatives Symbol, das die Aktion als deaktiviert anzeigt.

Beispiele für benutzerdefinierte Aktionssymbole, die nicht dem Stil entsprechen.
Abbildung 1. Beispiele für benutzerdefinierte Aktionssymbole, die nicht dem Stil entsprechen.

Audioformat angeben

Wenn die wiedergegebenen Medien ein spezielles Audioformat verwenden, können Sie Symbole angeben, die in Autos gerendert werden, die diese Funktion unterstützen. Sie können KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI und KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI im Extras-Bundle des aktuell wiedergegebenen Media-Elements festlegen, das an MediaSession.setMetadata übergeben wird. Legen Sie beide Extras fest, um die verschiedenen Layouts zu berücksichtigen.

Außerdem kannst du das KEY_IMMERSIVE_AUDIO-Extra festlegen, um Autoherstellern mitzuteilen, dass es sich um immersiven Audioinhalt handelt. Sie sollten daher sehr vorsichtig sein, wenn sie entscheiden, ob sie Audioeffekte anwenden, die die immersiven Inhalte beeinträchtigen könnten.

Sie können das wiedergegebene Media-Element so konfigurieren, dass sein Untertitel, seine Beschreibung oder beides Links zu anderen Media-Elementen sind. So können Nutzer schnell zu ähnlichen Inhalten springen, z. B. zu anderen Songs desselben Künstlers oder zu anderen Folgen eines Podcasts. Wenn das Auto diese Funktion unterstützt, können Nutzer auf den Link tippen, um die Inhalte aufzurufen.

Wenn Sie Links hinzufügen möchten, konfigurieren Sie die Metadaten KEY_SUBTITLE_LINK_MEDIA_ID (um über den Untertitel zu verlinken) oder KEY_DESCRIPTION_LINK_MEDIA_ID (um über die Beschreibung zu verlinken). Weitere Informationen finden Sie in der Referenzdokumentation zu diesen Metadatenfeldern.