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‑Datenbrillen
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 Klang in einer 3D-Umgebung wahrnehmen. Es erzeugt den Eindruck, dass der Klang aus allen Richtungen kommt, auch von über und unter dem Nutzer. Das System simuliert dazu einen oder mehrere „virtuelle Lautsprecher“ an bestimmten Positionen im 3D-Raum.

Bei vorhandenen Apps, die nicht für Android XR entwickelt oder für Android XR geändert wurden, wird der Ton in Android XR automatisch räumlich dargestellt. Wenn sich der Nutzer im Raum bewegt, wird der gesamte App-Ton über das Panel ausgegeben, auf dem die Benutzeroberfläche der App gerendert wird. Wenn beispielsweise ein Timer in einer Uhr-App abläuft, klingt es so, als käme der Ton von der Position des App-Panels. Android XR ändert den Ton automatisch, um eine realistische Positionierung zu erreichen. Die wahrgenommene Entfernung zwischen dem App-Panel und dem Nutzer wirkt sich beispielsweise auf die Lautstärke aus, um ein realistischeres Gefühl zu erzeugen.

Weitere Informationen dazu, wie vorhandene Apps Spatial Audio rendern, finden Sie auf dieser Seite unter Stereo- und Surround-Sound zur 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 präzise in der 3D-Umgebung positionieren, Ambisonic-Audio für realistische Klangfelder verwenden und die integrierte Surround-Sound-Funktion nutzen.

Arten von Spatial Audio in Android XR

Android XR unterstützt positionelles Audio, Stereo, Surround-Sound und Ambisonic-Audio.

Positionelles Audio

Positionelles Audio kann so positioniert werden, dass es von einem bestimmten Punkt im 3D-Raum abgespielt wird. Sie können beispielsweise ein 3D-Modell eines bellenden Hundes an der Ecke Ihrer virtuellen Umgebung platzieren. Es können mehrere Entitäten Sound von ihren jeweiligen Positionen ausgeben. Für das Rendern von positionellem Audio müssen die Dateien Mono oder Stereo sein.

Räumlich dargestellter Stereo- und Surround-Sound

Alle Android-Mediaformate werden für positionelles Audio, 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 bezieht sich auf Audioformate mit mehr als zwei Kanälen, z. B. 5.1-Surround Sound oder 7.1-Surround-Sound Konfigurationen. Die Sounddaten jedes Kanals sind mit einem Lautsprecher verknüpft. Wenn Sie beispielsweise Musik in Stereo abspielen, gibt der linke Lautsprecherkanal möglicherweise andere Instrumentenspuren aus als der rechte.

Surround-Sound wird häufig in Filmen und Fernsehsendungen verwendet, um durch die Verwendung mehrerer Lautsprecherkanäle mehr Realismus und Immersion zu erzeugen. Dialoge werden beispielsweise oft über einen Center-Lautsprecherkanal wiedergegeben, während der Sound eines fliegenden Hubschraubers verschiedene Kanäle nacheinander verwendet, um den Eindruck zu erwecken, dass der Hubschrauber um Ihren 3D-Raum fliegt.

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 in anderen Szenarien, in denen Sie ein vollständig sphärisches Klangfeld nachbilden möchten, das den Zuhörer umgibt. Android XR unterstützt das Ambisonic-Audioformat AmbiX in der ersten, zweiten und dritten Ordnung. Wir empfehlen die Opus (.ogg) und PCM/Wave (.wav) Dateitypen.

Spatial Audio mit Jetpack SceneCore verwenden

Für die Implementierung von Spatial Audio mit Jetpack SceneCore müssen Sie prüfen, ob die räumlichen Funktionen unterstützt werden, und eine API zum Laden von Spatial Audio auswählen.

Prüfen, ob räumliche Funktionen unterstützt werden

Bevor Sie Spatial Audio-Funktionen verwenden, prüfen Sie, ob die Session unterstützt Spatial Audio. In allen Code-Snippets in den folgenden Abschnitten werden die Funktionen geprüft, bevor versucht wird, räumlich dargestelltes 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 mit einer Größe von weniger als 1 MB. Sie werden im Voraus geladen und die Sounds können wiederholt verwendet werden. So können Sie Audio für positionelles Audio laden.
  • ExoPlayer: Ideal zum Laden von Stereo- und Surround-Sound-Inhalten wie Musik und Videos. Ermöglicht auch die Medienwiedergabe im Hintergrund.
  • MediaPlayer: Bietet die einfachste Möglichkeit, Ambisonic-Audio zu laden.
  • AudioTrack: Bietet die größte Kontrolle darüber, wie Audiodaten geladen werden. Ermöglicht das direkte Schreiben von Audio-Puffern oder wenn Sie Ihre eigenen Audiodateien synthetisiert oder decodiert haben.

Unterstützung von Mediaformaten prüfen

Einige Mediaformate werden von der Android-Plattform unterstützt. Ein bestimmtes Android XR-Gerät unterstützt jedoch möglicherweise zusätzliche Formate wie Dolby Atmos. Verwenden Sie ExoPlayer's AudioCapabilities, um die Unterstützung von Mediaformaten abzufragen:

val audioCapabilities = AudioCapabilities.getCapabilities(context, androidx.media3.common.AudioAttributes.DEFAULT, null)
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 dieser Funktionen kann möglicherweise blockierende Aufrufe umfassen und sollte nicht im Hauptthread aufgerufen werden.

Positionelles Audio zur App hinzufügen

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

AudioAttributesUSAGE_MEDIACONTENT_TYPE_MOVIECONTENT_TYPE_MUSICCONTENT_TYPE_SPEECH

Beispiel für positionelles Audio

Im folgenden Beispiel wird eine Soundeffekt-Audiodatei in einen Soundpool geladen und an der Position der 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(entity)

    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,
                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 geprüft, ob Spatial Audio-Funktionen verfügbar sind, indem spatialCapabilities verwendet wird.
  • Wenn Sie den contentType auf CONTENT_TYPE_SONIFICATION und die Verwendung auf USAGE_ASSISTANCE_SONIFICATION festlegen, behandelt das System diese Audiodatei als Soundeffekt.
  • Im obigen Beispiel wird die Audiodatei unmittelbar vor der Verwendung in den Pool geladen, um den Code zu vereinfachen. 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 zur App hinzufügen

Die empfohlene Methode zum Hinzufügen von Stereo- und Surround-Sound zu Ihrer App ist die Verwendung von Exoplayer. Weitere Informationen zur Verwendung von Spatial Audio mit Exoplayer, finden Sie im Leitfaden zu Spatial Audio.

Lautsprecherpositionierung für Stereo- und Surround-Sound

Bei der Lautsprecherpositionierung für Surround-Sound werden die virtuellen Surround-Sound-Lautsprecher relativ zu einem Center-Lautsprecher um den Nutzer herum in einer Standard-ITU-Konfiguration positioniert und ausgerichtet.

Standardmäßig wird der Center-Lautsprecher auf der App's mainPanelEntity platziert. Das gilt auch für mobile Apps, bei denen der Ton automatisch von Android XR räumlich dargestellt wird.

Bei Stereo ist die Lautsprecherpositionierung ähnlich wie bei Surround-Sound, nur dass die linken und rechten Kanäle jeweils auf der linken und rechten Seite des Panels positioniert sind.

Wenn Sie mehrere Panels haben und auswählen möchten, welches Panel Audio ausgibt, oder wenn Sie möchten, dass Stereo- oder Surround-Audio relativ zu einer anderen Entity gerendert wird, können Sie mit PointSourceAttributes die Position des Center-Kanals definieren. Die übrigen Kanäle werden wie oben beschrieben platziert. In diesen Fällen müssen Sie auch MediaPlayer verwenden.

Wenn sich der Nutzer im Raum bewegt, bewegen sich die virtuellen Lautsprecher für Stereo- und Surround-Sound und passen sich an, damit sie immer optimal positioniert sind.

Wenn Sie MediaPlayer oder ExoPlayer so konfiguriert haben, dass Stereo- oder Surround-Sound im Hintergrund weitergegeben wird, ändert sich die Positionierung der virtuellen Lautsprecher, wenn die App in den Hintergrund verschoben wird. Da es kein Panel oder einen anderen Punkt im Raum gibt, an dem der Sound verankert werden kann, bewegt sich das Spatial Audio mit dem Nutzer (es ist also „kopfgebunden“).

Beispiel für Surround-Sound

Im folgenden Beispiel wird eine 5.1-Audiodatei mit MediaPlayer geladen und der Center-Kanal der Datei als 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(session.scene.mainPanelEntity)

    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
    )

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

Wichtige Informationen zum Code

Ambisonic-Klangfelder zur App hinzufügen

Die einfachste Möglichkeit, Ambisonic-Klangfelder wiederzugeben, besteht darin, die Datei mit einem MediaPlayer zu laden. Da Ambisonic-Sound für die gesamte Klanglandschaft gilt, müssen Sie keine Entity angeben, um eine Position festzulegen. Erstellen Sie stattdessen eine Instanz von SoundFieldAttributes mit der entsprechenden Ambisonic Ordnung, die die Anzahl der Kanäle angibt.

Beispiel für Ambisonics

Im folgenden Beispiel wird ein Ambisonic-Klangfeld 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

  • Wie bei den vorherigen Snippets wird im ersten Schritt geprüft, ob Spatial Audio Funktionen verfügbar sind, indem hasCapability() verwendet wird.
  • contentType und die Verwendung sind rein informativ.
  • The AMBISONICS_ORDER_FIRST_ORDER signalisiert SceneCore, dass die Klang felddatei vier Kanäle definiert.