Spatial Audio zu Ihrer XR-App hinzufügen

XR‑Geräte, für die der Leitfaden gilt
Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.
Informationen zu XR-Gerätetypen →
XR-Headsets
Kabelgebundene XR-Datenbrille
Informationen zu XR-Gerätetypen →

Mit den Spatial Audio-Funktionen in Jetpack SceneCore können Sie immersive Audioerlebnisse in Ihren Android XR-Anwendungen erstellen.

Spatial Audio simuliert, wie Nutzer Ton in einer 3D-Umgebung wahrnehmen. Dadurch entsteht der Eindruck, dass der Ton aus allen Richtungen kommt, auch von oben und unten. Dazu werden ein oder mehrere „virtuelle Lautsprecher“ an bestimmten Positionen im 3D-Raum simuliert.

Bei vorhandenen Apps, die nicht für Android XR entwickelt oder angepasst wurden, wird der Ton in Android XR automatisch räumlich wiedergegeben. Wenn sich der Nutzer im Raum bewegt, wird der gesamte App-Audioinhalt über das Steuerfeld ausgegeben, auf dem die Benutzeroberfläche der App gerendert wird. Wenn beispielsweise ein Timer einer Uhr-App abläuft, klingt der Ton so, als käme er von der Position des App-Bereichs. Android XR passt den Ton automatisch an, um die Position realistisch wiederzugeben. Beispielsweise wird die wahrgenommene Entfernung zwischen dem App-Bereich und dem Nutzer die Audiolautstärke subtil beeinflussen, um ein realistischeres Gefühl zu vermitteln.

Weitere Informationen dazu, wie vorhandene Apps Spatial Audio rendern, finden Sie auf dieser Seite unter Stereo- und Surround-Sound zu Ihrer App hinzufügen.

Wenn Sie Ihre App für XR optimieren, bietet Jetpack SceneCore Tools für die erweiterte Anpassung von Spatial Audio. Sie können Sounds in der 3D-Umgebung präzise positionieren, Ambisonics-Audio für realistische Klangfelder verwenden und die integrierte Surround-Sound-Integration nutzen.

In Android XR verfügbare Arten von Spatial Audio

Android XR unterstützt positionales Audio, Stereo, Surround-Sound und Ambisonics.

Positionsabhängiges Audio

Positionsabhängiges Audio kann so positioniert werden, dass es von einem bestimmten Punkt im 3D-Raum wiedergegeben wird. Sie können beispielsweise ein 3D-Modell eines bellenden Hundes in der Ecke Ihrer virtuellen Umgebung platzieren. Sie können mehrere Entitäten haben, die von ihren jeweiligen Positionen aus Ton ausgeben. Für die Wiedergabe von positionellem Audio müssen die Dateien im Mono- oder Stereoformat vorliegen.

Spatialized Stereo und Surround-Sound

Alle Android-Medienformate werden für Positions-, Stereo- und Surround-Sound unterstützt. Zusätzlich zu diesen Formaten unterstützen Android XR-Geräte möglicherweise die Audioformate Dolby Atmos, Dolby Digital und Dolby Digital+.

Stereo-Audio bezieht sich auf Audioformate mit zwei Kanälen und Surround-Sound auf Audioformate mit mehr als zwei Kanälen, z. B. 5.1-Surround-Sound- oder 7.1-Surround-Sound-Konfigurationen. Die Audiodaten jedes Kanals sind einem Sprecher zugeordnet. Wenn du beispielsweise Musik in Stereo abspielst, werden über den linken Lautsprecherkanal möglicherweise andere Instrumentenspuren ausgegeben als über den rechten.

Surround-Sound wird häufig in Filmen und Fernsehsendungen verwendet, um die Realitätsnähe und das Eintauchen in die Handlung durch die Verwendung mehrerer Lautsprecherkanäle zu verbessern. Beispielsweise werden Dialoge oft über einen Center-Lautsprecherkanal wiedergegeben, während das Geräusch eines fliegenden Hubschraubers nacheinander über verschiedene Kanäle wiedergegeben werden kann, um den Eindruck zu erwecken, dass der Hubschrauber im 3D-Raum um Sie herumfliegt.

Ambisonic-Audio

Ambisonic-Audio (oder Ambisonics) ist wie eine Skybox für Audio und bietet Nutzern eine immersive Klanglandschaft. Verwenden Sie Ambisonics für Umgebungsgeräusche im Hintergrund oder andere Szenarien, in denen Sie ein kugelförmiges Klangfeld nachbilden möchten, das den Zuhörer umgibt. Android XR unterstützt das Ambisonics-Audioformat AmbiX in Ambisonics erster, zweiter und dritter Ordnung. Wir empfehlen die Dateitypen Opus (.ogg) und PCM/Wave (.wav).

Spatial Audio mit Jetpack SceneCore verwenden

Wenn Sie Spatial Audio mit Jetpack SceneCore implementieren möchten, müssen Sie die Spatial-Audio-Funktionen prüfen und eine API zum Laden von Spatial Audio auswählen.

Räumliche Funktionen prüfen

Prüfe vor der Verwendung von Spatial Audio-Funktionen, ob das Session Spatial Audio unterstützt. In allen Code-Snippets in den folgenden Abschnitten werden die Funktionen geprüft, bevor versucht wird, Spatial Audio abzuspielen.

Spatial Audio laden

Sie können eine der folgenden APIs verwenden, um Spatial Audio für die Verwendung in Jetpack SceneCore zu laden.

  • SoundPool: Ideal für kurze Soundeffekte, die kleiner als 1 MB sind. Sie werden im Voraus geladen und können wiederholt verwendet werden. Dies ist eine gute Möglichkeit, Audio für positionales Audio zu laden.
  • ExoPlayer: Ideal zum Laden von Stereo- und Surround-Sound-Inhalten wie Musik und Videos. Außerdem ist die Medienwiedergabe im Hintergrund möglich.
  • MediaPlayer: Die einfachste Möglichkeit, Ambisonics-Audio zu laden.
  • AudioTrack: Bietet die größte Kontrolle darüber, wie Audiodaten geladen werden. Ermöglicht das direkte Schreiben von Audio-Zwischenspeichern oder das Synthetisieren oder Decodieren eigener Audiodateien.

Unterstützung von Medienformaten prüfen

Einige Medienformate werden von der Android-Plattform unterstützt. Ein bestimmtes Android XR-Gerät unterstützt jedoch möglicherweise zusätzliche Formate wie Dolby Atmos. Wenn Sie die Unterstützung von Medienformaten abfragen möchten, verwenden Sie AudioCapabilities von ExoPlayer:

val audioCapabilities = AudioCapabilities.getCapabilities(
    context,
    androidx.media3.common.AudioAttributes.DEFAULT,
    null,
    emptyList()
)

if (audioCapabilities.supportsEncoding(C.ENCODING_AC3)) {
    // Device supports playback of the Dolby Digital media format.
}
if (audioCapabilities.supportsEncoding(C.ENCODING_E_AC3)) {
    // Device supports playback of the Dolby Digital Plus media format.
}
if (audioCapabilities.supportsEncoding(C.ENCODING_E_AC3_JOC)) {
    // Device supports playback of the Dolby Digital Plus with Dolby Atmos media format.
}

Die Prüfung auf diese Funktionen kann zu blockierenden Aufrufen führen und sollte nicht im Hauptthread aufgerufen werden.

Positionsbezogenes Audio zu Ihrer App hinzufügen

Positionsbezogene Tonquellen werden durch PointSourceParams und eine zugehörige Entity definiert. Die Position und Ausrichtung des Entity bestimmt, wo der PointSourceParams im 3D-Raum gerendert wird. Rufen Sie setPointSourceParams für SpatialMediaPlayer auf, um die PointSourceParams und die zugehörige entity für eine MediaPlayer-Instanz festzulegen.

Beispiel für positionales Audio

Im folgenden Beispiel wird eine Audiodatei mit einem Soundeffekt in einen Soundpool geladen und an der Position des Entity wiedergegeben.

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_AUDIO)
) { // The session has spatial audio capabilities
    val maxVolume = 1F
    val lowPriority = 0
    val infiniteLoop = -1
    val normalSpeed = 1F

    val soundPool = SoundPool.Builder()
        .setAudioAttributes(
            AudioAttributes.Builder()
                .setContentType(CONTENT_TYPE_SONIFICATION)
                .setUsage(USAGE_ASSISTANCE_SONIFICATION)
                .build()
        )
        .build()

    val pointSource = PointSourceParams()

    val soundEffect = appContext.assets.openFd("sounds/tiger_16db.mp3")
    val pointSoundId = soundPool.load(soundEffect, lowPriority)

    soundPool.setOnLoadCompleteListener { soundPool, sampleId, status ->
        // wait for the sound file to be loaded into the soundPool
        if (status == 0) {
            SpatialSoundPool.play(
                session = session,
                entity = entity,
                soundPool = soundPool,
                soundID = pointSoundId,
                params = pointSource,
                volume = maxVolume,
                priority = lowPriority,
                loop = infiniteLoop,
                rate = normalSpeed
            )
        }
    }
} else {
    // The session does not have spatial audio capabilities
}

Wichtige Informationen zum Code

  • Im ersten Schritt wird mit spatialCapabilities geprüft, ob Spatial Audio-Funktionen verfügbar sind.
  • Wenn Sie contentType auf CONTENT_TYPE_SONIFICATION und usage auf USAGE_ASSISTANCE_SONIFICATION setzen, wird diese Audiodatei vom System als Soundeffekt behandelt.
  • Im vorherigen Beispiel wird die Audiodatei unmittelbar vor der Verwendung in den Pool geladen, damit der Code der Einfachheit halber zusammenbleibt. Idealerweise sollten Sie alle Soundeffekte asynchron laden, während Sie Ihre App laden, damit alle Audiodateien im Pool verfügbar sind, wenn Sie sie benötigen.

Stereo- und Surround-Sound zu deiner App hinzufügen

Wir empfehlen, Stereo- und Surround-Sound mit Exoplayer in deine App einzubinden. Weitere Informationen zur Verwendung von Spatial Audio mit Exoplayer findest du im Leitfaden zu Spatial Audio.

Positionierung von Stereo- und Surround-Sound-Lautsprechern

Bei der Surround-Sound-Lautsprecherpositionierung werden die virtuellen Surround-Sound-Lautsprecher relativ zu einem Center-Lautsprecher um den Nutzer herum in einer standardmäßigen ITU-Konfiguration positioniert und ausgerichtet.

Standardmäßig wird der Center-Lautsprecher auf der mainPanelEntity der App platziert. Dazu gehören auch mobile Apps, deren Audioinhalte von Android XR automatisch räumlich dargestellt werden.

Bei Stereo ist die Platzierung der Lautsprecher ähnlich wie bei Surround-Sound, nur dass die linken und rechten Kanäle auf der linken bzw. rechten Seite des Displays positioniert sind.

Wenn Sie mehrere Panels haben und auswählen möchten, welches Panel Audio ausgibt, oder wenn Sie möchten, dass das Stereo- oder Surround-Audio relativ zu einem anderen Entity gerendert wird, können Sie mit dem PointSourceAttributes die Position des Center-Kanals definieren. Die verbleibenden Kanäle werden wie zuvor erwähnt platziert. In diesen Situationen müssen Sie auch MediaPlayer verwenden.

Wenn sich der Nutzer im Raum bewegt, werden die virtuellen Stereo- und Surround-Sound-Lautsprecher bewegt und angepasst, damit sie sich immer in einer optimalen Position befinden.

Wenn du MediaPlayer oder ExoPlayer so konfiguriert hast, dass Stereo- oder Surround-Sound im Hintergrund weiter abgespielt wird, wird die Positionierung der virtuellen Lautsprecher geändert, wenn die App im Hintergrund ausgeführt wird. Da es kein Panel oder einen anderen Punkt im Raum gibt, an dem der Ton verankert werden kann, bewegt sich das Spatial Audio mit dem Nutzer (es ist also „head-locked“).

Beispiel für Surround-Sound

Im folgenden Beispiel wird eine 5.1-Audiodatei mit MediaPlayer geladen und der mittlere Kanal der Datei auf Entity festgelegt.

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_AUDIO)) {
    // The session has spatial audio capabilities

    val pointSourceAttributes = PointSourceParams()

    val mediaPlayer = MediaPlayer()

    val fivePointOneAudio = appContext.assets.openFd("sounds/aac_51.ogg")
    mediaPlayer.reset()
    mediaPlayer.setDataSource(fivePointOneAudio)

    val audioAttributes =
        AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()

    SpatialMediaPlayer.setPointSourceParams(
        session,
        mediaPlayer,
        pointSourceAttributes,
        entity = session.scene.mainPanelEntity,
    )

    mediaPlayer.setAudioAttributes(audioAttributes)
    mediaPlayer.prepare()
    mediaPlayer.start()
} else {
    // The session does not have spatial audio capabilities
}

Wichtige Informationen zum Code

Ambisonic-Schallfelder in Ihre App einfügen

Die einfachste Möglichkeit, Ambisonics-Schallfelder wiederzugeben, besteht darin, die Datei mit einem MediaPlayer zu laden. Da Ambisonics-Sound für die gesamte Klanglandschaft gilt, musst du keine Entity angeben, um eine Position anzugeben. Stattdessen erstellst du eine Instanz von SoundFieldAttributes mit der entsprechenden Ambisonics-Ordnung, die die Anzahl der Kanäle angibt.

Beispiel für Ambionics

Im folgenden Beispiel wird ein Ambisonics-Schallfeld mit MediaPlayer wiedergegeben.

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_AUDIO)) {
    // The session has spatial audio capabilities

    val soundFieldAttributes =
        SoundFieldAttributes(SpatializerConstants.AmbisonicsOrder.FIRST_ORDER)

    val mediaPlayer = MediaPlayer()

    val soundFieldAudio = appContext.assets.openFd("sounds/foa_basketball_16bit.wav")

    mediaPlayer.reset()
    mediaPlayer.setDataSource(soundFieldAudio)

    val audioAttributes =
        AudioAttributes.Builder()
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .setUsage(AudioAttributes.USAGE_MEDIA)
            .build()

    SpatialMediaPlayer.setSoundFieldAttributes(
        session,
        mediaPlayer,
        soundFieldAttributes
    )

    mediaPlayer.setAudioAttributes(audioAttributes)
    mediaPlayer.prepare()
    mediaPlayer.start()
} else {
    // The session does not have spatial audio capabilities
}

Wichtige Informationen zum Code