Härtung von Audio im Hintergrund

Ab Android 17 werden im Audio-Framework Einschränkungen für Audiointeraktionen im Hintergrund erzwungen, darunter Audiowiedergabe, Audiofokus-Anfragen und Lautstärkeänderungs-APIs. So soll sichergestellt werden, dass diese Änderungen vom Nutzer bewusst initiiert werden.

Wenn ein App-Entwickler Audio ohne sichtbare Aktivität steuern möchte, muss er dafür sorgen, dass die App einen Vordergrunddienst (der nicht vom Typ SHORT_SERVICE ist) hat, der mit While-in-Use-Funktionen (WIU) gestartet wurde. Ein Dienst im Vordergrund erhält WIU-Funktionen, wenn er als Reaktion auf eine MediaSessionEvent oder während die App für den Nutzer sichtbar ist gestartet wird.

Wenn die App versucht, Audio-APIs aufzurufen, während sie sich nicht in einem gültigen Lebenszyklus befindet, schlagen die APIs für die Audiowiedergabe und Lautstärkeänderung ohne Ausnahme oder Fehlermeldung fehl. Die Audiofokus-API schlägt mit dem Ergebniscode AUDIOFOCUS_REQUEST_FAILED fehl.

Mit diesen Einschränkungen möchten wir verhindern, dass Nutzer unbeabsichtigt Hintergrundaudio hören. Beispiele:

• Apps, die Audio ohne Vordergrunddienst wiedergeben, können eingefroren werden. Wenn die App schließlich wieder aktiviert wird, wird die Audiowiedergabe unerwartet fortgesetzt, möglicherweise Stunden später.
• Apps, die Audio ohne Vordergrunddienst abspielen, unterliegen verschiedenen Laufzeitbeschränkungen, die zu einer schlechten Audioleistung führen.
• Die Wiedergabe ist vom Aktivitätslebenszyklus getrennt, was zu einer nicht beendeten Wiedergabesitzung oder nicht beendeten Fokusereignissen führen kann, ohne dass der Nutzer die Wiedergabe beenden kann.

Wir empfehlen Entwicklern, ihre Apps zu testen und Feedback zu den Verhaltensänderungen zu geben, wenn beabsichtigte Audio-Anwendungsfälle negativ beeinträchtigt werden. Bitte melden Sie alle Probleme über diesen Issue-Tracker für die App-Kompatibilität unter Android 17.

Betroffene Anwendungsfälle für Hintergrundaudio identifizieren

Prüfen Sie die Implementierung der Audiowiedergabe und stellen Sie fest, ob Ihre App auch unter bestimmten Bedingungen Funktionen zur Interaktion mit Audio im Hintergrund bereitstellen soll.

Wenn Ihre App nur Audio wiedergeben oder Audio-APIs verwenden soll, während eine für den Nutzer sichtbare Aktivität angezeigt wird, einschließlich der Verwendung des Bild-im-Bild-Modus (BiB), ist sie von diesen Änderungen nicht betroffen.

Wenn Ihre App VOIP-Funktionen bietet, einschließlich Videoanruf-Apps, muss sie bereits die Anforderungen erfüllen, die für die Wiedergabe eingeführt werden (in der Regel durch die Verwendung der empfohlenen Telekommunikations-APIs), um Audio erfolgreich aufzunehmen. Daher ist es unwahrscheinlich, dass sie davon betroffen ist.

Wenn Ihre App die Audiowiedergabe fortsetzen soll, während der Bildschirm ausgeschaltet ist oder der Nutzer Ihre Aktivität vollständig geschlossen hat, was am häufigsten bei Musikstreaming- oder Podcast-Apps der Fall ist, gilt Ihre App als App mit Hintergrundaudiofunktion und muss die neuen Anforderungen erfüllen.

Szenarien mit Hintergrundaudio, die wahrscheinlich betroffen sind

Wenn Ihre App nicht dem Modell folgt, eine Audiointeraktion fortzusetzen, die gestartet wurde, als Ihre App geöffnet war, oder als Reaktion auf einen expliziten Nutzer-Trigger, wird die Funktion Ihrer App wahrscheinlich im Hintergrund unterdrückt.

Wenn Ihre App beispielsweise als Reaktion auf BOOT_COMPLETE einen Dienst im Vordergrund startet und versucht, mit Audio zu interagieren, wird dies unterdrückt.

Best Practices für Hintergrundaudio zur Minimierung von Auswirkungen

• Verwende die media3-Jetpack-Bibliothek mit der Komponente MediaSessionService, um die Audiowiedergabe im Hintergrund zu verwalten.

  In diesem Fall ist es unwahrscheinlich, dass Ihre App von der Hintergrundhärtung betroffen ist, da die Bibliothek bei der Verwaltung des Wiedergabe-Lebenszyklus hilft.

• Wenn Sie die Media3-Bibliothek nicht verwenden, müssen Sie manuell einen mediaPlayback-FGS starten. Starten Sie einen Dienst im Vordergrund immer, wenn die App im Vordergrund ausgeführt wird und Audio im Hintergrund wiedergegeben werden soll.

  Wenn Ihre App beispielsweise eine Videostreaming-App ist, die normalerweise nur im Vordergrund ausgeführt wird, aber eine Nutzerfunktion zum Fortsetzen der Wiedergabe bei ausgeschaltetem Bildschirm enthält, sollte Ihre App bei einem vom Nutzer initiierten Wiedergabe-Trigger trotzdem einen Dienst im Vordergrund starten.

  Dadurch wird sichergestellt, dass der Dienst im Vordergrund mit WIU-Funktionen gestartet wird.

• Lassen Sie die mediaPlayback-FGS bei vorübergehenden Fehlern von weniger als 10 Minuten aktiv.

  Wenn in deiner App ein vorübergehender Fehler auftritt, z. B. ein Problem mit dem Puffern aufgrund von Netzwerkaktivität, oder eine erwartete vorübergehende Unterbrechung wie AUDIOFOCUS_LOSS_TRANSIENT vorliegt, sollte die Wiedergabe fortgesetzt werden. Ihr FGS sollte also aktiv bleiben.

• Beenden Sie den Dienst im Vordergrund am Ende der Wiedergabe und starten Sie die Wiedergabe nur neu, wenn der Nutzer sie explizit fortsetzt.

  Bei einem permanenten Signal zum Beenden der Wiedergabe (z. B. wenn Inhalte ohne automatische Wiedergabe vollständig wiedergegeben wurden, bei einem AUDIOFOCUS_LOSS, einem Pausenereignis vom UMO oder einem Media-Tastenereignis) oder bei einem nicht behebaren Fehler sollte Ihre App die Audiointeraktion beenden, den Vordergrunddienst stoppen und die Mediensitzung beenden. All das entspricht der Vorstellung des Nutzers, die gewünschte Hintergrundaudio-Interaktion „abzuschließen“. Danach kann Ihre App nicht mehr im Hintergrund auf Audio reagieren.

  Wenn der Nutzer die Wiedergabe dann explizit fortsetzt, z. B. über die Benutzeroberfläche Ihrer App oder über die Schaltfläche „Wiedergabe“ des Universal Media Object, sollte die Intention zum Starten der Audiowiedergabe zurückgegeben werden, was zu einem neu gestarteten Dienst im Vordergrund führt.

• Testen Sie das Verhalten bei der Audiowiedergabe mit adb-Shell-Befehlen.

Änderungen unter Android 16 und Android 17 testen

Die Funktion ist bereits ab Android 16 auf der Warnstufe implementiert. Das bedeutet, dass Apps adb shell cmd audio set-enable-hardening verwenden können, um die Durchsetzung der Hintergrundaudio-Härtung manuell zu testen.

Führen Sie den folgenden Befehl aus, um die Erzwingung auf Geräten mit Android 16 zu aktivieren:

adb shell cmd audio set-enable-hardening 1

Führen Sie den folgenden Befehl aus, um die Erzwingung auf Geräten mit Android 17 zu deaktivieren:

adb shell cmd audio set-enable-hardening 0

Wir empfehlen außerdem, logcat oder den adb-Befehl adb dumpsys audio zu verwenden, um festzustellen, ob in der App aufgrund der Durchsetzung der Audio-Härtung stille Fehler aufgetreten sind. Wenn das der Fall ist, enthält das Log einen Eintrag mit dem Präfix AudioHardening und Ihrem Paketnamen.

Dienste im Vordergrund mit der Funktion „Während der Nutzung“

Dienste im Vordergrund müssen in der Regel gestartet werden, während sich eine App im Vordergrund befindet, um vom Nutzer initiierte Vorgänge zu verlängern. In bestimmten Fällen dürfen Apps einen Dienst im Vordergrund starten, während die App im Hintergrund ausgeführt wird. Diesen Diensten im Vordergrund werden jedoch in der Regel keine Berechtigungen für die Nutzung während der Nutzung (While-In-Use, WIU) gewährt.

WIU fungiert als Sicherheitstor und verhindert, dass FGS, die im Hintergrund gestartet werden, bestimmte sensible Verhaltensweisen ausführen, wenn der Nutzer sich der Aktivität der App möglicherweise nicht bewusst ist. Dadurch wird verhindert, dass die App auf vertrauliche Daten wie Standort, Kamera oder Mikrofon zugreift. Ab Android 17 werden auch Audio-APIs blockiert, für die normalerweise ein sichtbarer UI-Kontext erforderlich ist.

Hier finden Sie eine praktische Referenz:

• Standard-FGS: Dienste, die gestartet werden, während die App sichtbar ist oder die Berechtigung zum Starten von Hintergrundaktivitäten haben, erhalten WIU-Zugriff.
• Im Hintergrund gestartete FGS (BFSL): Die meisten gewähren keinen WIU-Zugriff. Die primären Ausnahmen, die WIU gewähren, sind Interaktionen mit expliziter Nutzerabsicht, z. B. Benachrichtigungsklicks, Widget-Interaktionen oder Media-Key-Ereignisse von einem externen Gerät.
• System started FGS: FGS, die mit der Systemserverdelegierung gestartet wurden (z. B. mit der Telecom Jetpack-Bibliothek), erhalten WIU-Zugriff.

Weitere Informationen finden Sie unter Beschränkungen für das Starten eines Dienstes im Vordergrund aus dem Hintergrund.

Vollständige Liste der betroffenen Audio-APIs

Audiofunktion	Ergebnis	Betroffene APIs
Audiowiedergabe	Die Wiedergabe ist stummgeschaltet Keine Ausnahmen, keine Fehlermeldung von einer API	AudioTrack.write() (NDK) AAudioStream_write OpenSL ES für Android Auch clientseitige Media-Bibliotheken, die die Wiedergabe verwalten, z. B. Media3, ExoPlayer und Oboe, könnten betroffen sein.
Anfrage zum Audiofokus	Gibt AUDIOFOCUS_REQUEST_FAILED zurück Keine Auswirkungen auf die Audiowiedergabe anderer Apps, kein Fokus	AudioManager.requestAudioFocus()
APIs für Lautstärke und Klingeltonmodus	Keine Auswirkungen auf den Klingeltonmodus oder die Lautstärke (Methodenaufruf wird stillschweigend ignoriert) Keine Ausnahmen, keine Fehlermeldung von einer API	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()