Wiedergabesteuerung aktivieren

Wenn du die Medienwiedergabe in Android Auto und Android Automotive OS (AAOS) aktivieren möchtest, musst du die Wiedergabesteuerung implementieren, indem du eine Mediensitzung registrierst und ihre Callback-Methoden verarbeitest. Auf dieser Seite erfahren Sie, wie Sie:

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

  • Implementieren Sie 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.

  • Symbole für das Audioformat hinzugefügt

  • Links aus aktuell wiedergegebenen Media-Elementen erstellen

Android Auto und AAOS senden Wiedergabesteuerungsbefehle über MediaSessionCompat für Ihren 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 sie vom Media-Browser-Dienst Ihrer App erhalten haben. Wenn ein Nutzer die Wiedergabe von Inhalten 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.

Für die Wiedergabe von Inhalten 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 Medienquelle ä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 springt.

onStop

Wird aufgerufen, wenn der Nutzer die Wiedergabe beendet. Überschreiben Sie diese Methoden in Ihrer App, um das ausgewählte Ergebnis zu liefern. Sie müssen keine Methode implementieren, wenn der Zweck nicht von Ihrer App unterstützt wird. Wenn Ihre App beispielsweise einen Livestream wie eine Sportübertragung abspielt, 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 Inhalte ü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 unter Media Player – Übersicht, Audio-App – Übersicht und 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:

Außerdem können Sie optional 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 wurde Unterstützung für das Symbol Wird gerade wiedergegeben hinzugefügt, 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 Wert.

Anfänglichen PlaybackState festlegen

Da Android Auto und AAOS mit Ihrem Media-Browser-Dienst kommunizieren, wird der Status der Wiedergabe von Inhalten über die PlaybackStateCompat kommuniziert.

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

Dazu legen Sie den anfänglichen PlaybackStateCompat Ihrer Mediensitzung auf STATE_STOPPED, STATE_PAUSED, STATE_NONE oder STATE_ERROR fest.

Mediensitzungen in Android Auto und AAOS dauern nur so lange wie die Fahrt. Nutzer starten und beenden diese Sitzungen daher häufig. Damit der Wechsel zwischen Fahrten reibungslos verläuft, sollten Sie den vorherigen Sitzungsstatus des Nutzers im Blick behalten. Wenn die Media-App eine Fortsetzungsanfrage erhält, kann der Nutzer automatisch dort weitermachen, wo er aufgehört hat. Das gilt beispielsweise für das zuletzt wiedergegebene Media-Element, die PlaybackStateCompat 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. Android zeigt benutzerdefinierte Aktionen in der Reihenfolge an, 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 der Aktion „Radiosender starten“ eine benutzerdefinierte Aktion 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 Methode setCustomAction 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. So können Systemkomponenten deine Aktion und andere Wiedergabeaktionen einheitlich rendern.

Sie müssen auch eine Symbolressource angeben. Apps für 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 Autohersteller darauf hinzuweisen, 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 kann der 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 entsprechenden 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.