Agrega audio espacial a tu app de XR

Dispositivos de realidad extendida correspondientes

Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.

Más información sobre los tipos de dispositivos de realidad extendida →

Visores de realidad extendida

Lentes de realidad extendida con cable

Más información sobre los tipos de dispositivos de realidad extendida →

Las funciones de audio espacial de Jetpack SceneCore te permiten crear experiencias de audio envolventes en tus aplicaciones de Android XR.

El audio espacial simula cómo los usuarios perciben el sonido en un entorno 3D. Crea la sensación de que el sonido emana de todas las direcciones, incluso desde arriba y abajo del usuario. Para ello, el sistema simula una o más "bocinas virtuales" en ubicaciones específicas del espacio 3D.

Las apps existentes que no se diseñaron ni modificaron para Android XR tienen su audio espacializado automáticamente en Android XR. A medida que el usuario se mueva por su espacio, todo el audio de la app se emitirá desde el panel en el que se renderiza la IU de la app. Por ejemplo, si suena un temporizador de una app de reloj, el audio parecerá provenir de la posición del panel de la app. Android XR alterará automáticamente el sonido para lograr un realismo posicional. Por ejemplo, la distancia percibida entre el panel de la app y el usuario afectará sutilmente el volumen del audio para brindar una mayor sensación de realismo.

Para obtener más información sobre cómo las apps existentes renderizan el audio espacial, consulta Agrega sonido estéreo y envolvente a tu app en esta página.

Nota: El usuario puede inhabilitar los efectos de audio espacial a nivel de la app o del sistema, y elegir el audio estéreo en su lugar.

Si optimizas tu app para XR, Jetpack SceneCore proporciona herramientas para la personalización avanzada del audio espacial. Puedes posicionar sonidos con precisión en el entorno 3D, usar audio ambisónico para obtener campos de sonido realistas y aprovechar la integración de sonido envolvente integrada.

Tipos de audio espacial disponibles en Android XR

Android XR admite audio posicional, estéreo, envolvente y ambisónico.

Audio posicional

Un audio posicional se puede ubicar para que se reproduzca desde un punto específico en el espacio 3D. Por ejemplo, puedes tener un modelo 3D de un perro que ladra en la esquina de tu entorno virtual. Puedes tener varias entidades que emitan sonido desde cada una de sus posiciones respectivas. Para renderizar audio posicional, los archivos deben ser mono o estéreo.

Estéreo espacializado y sonido envolvente

Todos los formatos multimedia de Android son compatibles con el sonido posicional, estéreo y envolvente. Además de estos formatos, los dispositivos Android XR pueden admitir los formatos de audio Dolby Atmos, Dolby Digital y Dolby Digital+.

El audio estéreo se refiere a los formatos de audio con dos canales, y el sonido envolvente se refiere a los formatos de audio con más de dos canales, como las configuraciones de sonido envolvente 5.1 o sonido envolvente 7.1. Los datos de sonido de cada canal se asocian con un interlocutor. Por ejemplo, cuando se reproduce música en estéreo, el canal de la bocina izquierda puede emitir pistas de instrumentos diferentes a las de la derecha.

El sonido envolvente se suele usar en películas y programas de televisión para mejorar el realismo y la inmersión a través del uso de varios canales de bocinas. Por ejemplo, el diálogo suele reproducirse desde un canal de bocina central, mientras que el sonido de un helicóptero que vuela puede usar diferentes canales en secuencia para dar la sensación de que el helicóptero vuela alrededor de tu espacio 3D.

Audio ambisónico

El audio ambisónico (o ambisonics) es como un skybox para el audio, ya que proporciona un paisaje sonoro envolvente para los usuarios. Usa ambisónicos para los sonidos ambientales de fondo o en otras situaciones en las que quieras replicar un campo de sonido esférico completo que rodee al oyente. Android XR admite el formato de audio ambisónico AmbiX en ambisónicos de primer, segundo y tercer orden. Recomendamos los tipos de archivo Opus (.ogg) y PCM/Wave (.wav).

Cómo usar el audio espacial con Jetpack SceneCore

La implementación del audio espacial con Jetpack SceneCore implica verificar las capacidades espaciales y elegir una API para cargar el audio espacial.

Verifica las funciones espaciales

Antes de usar las funciones de audio espacial, verifica que Session admita el audio espacial. En todos los fragmentos de código de las siguientes secciones, se verifican las capacidades antes de intentar reproducir audio espacializado.

Nota: Si tu app usa el mismo código para factores de forma que no sean Android XR, la verificación tradicional de las capacidades espaciales siempre devuelve verdadero en Android XR.

Carga audio espacial

Puedes usar cualquiera de las siguientes APIs para cargar audio espacial y usarlo en Jetpack SceneCore.

• SoundPool: Es ideal para efectos de sonido cortos que tienen un tamaño inferior a 1 MB, se cargan con anticipación y los sonidos se pueden usar de forma repetida. Esta es una excelente manera de cargar audio para el audio posicional.
• ExoPlayer: Es ideal para cargar contenido de sonido estéreo y envolvente, como música y video. También permite la reproducción de contenido multimedia en segundo plano.
• MediaPlayer: Proporciona la forma más sencilla de cargar audio ambisónico.
• AudioTrack: Proporciona el mayor control sobre cómo cargar datos de audio. Permite escribir directamente búferes de audio o si sintetizaste o decodificaste tus propios archivos de audio.

Verifica la compatibilidad con formatos multimedia

La plataforma de Android admite algunos formatos multimedia. Sin embargo, un dispositivo Android XR en particular podría admitir formatos adicionales, como Dolby Atmos. Para consultar la compatibilidad con formatos de contenido multimedia, usa AudioCapabilities de 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.
}
SpatialAudio.kt

La verificación de estas capacidades puede implicar llamadas de bloqueo y no se debe llamar en el subproceso principal.

Nota: Si usas ExoPlayer, intentará seleccionar automáticamente formatos de audio con mayor cantidad de pistas, como Dolby Digital o Dolby Digital Plus, y formatos basados en objetos, como Dolby Atmos, cuando el dispositivo y el enrutamiento de salida de audio lo admitan.

Agrega audio posicional a tu app

Las fuentes de sonido posicionales se definen con PointSourceParams y un Entity asociado. La posición y la orientación de Entity determinan dónde se renderiza PointSourceParams en el espacio 3D. Llama a setPointSourceParams en SpatialMediaPlayer para establecer el PointSourceParams y su entity asociado en una instancia de MediaPlayer.

Importante: Para renderizar correctamente el audio posicional, los archivos deben ser mono o estéreo, y el uso en AudioAttributes no debe ser USAGE_MEDIA, ni el ContentType puede ser CONTENT_TYPE_MOVIE, CONTENT_TYPE_MUSIC ni CONTENT_TYPE_SPEECH.

Ejemplo de audio posicional

En el siguiente ejemplo, se carga un archivo de audio de efecto de sonido en un grupo de sonidos y se reproduce en la posición del Entity.

// 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
}
SpatialAudio.kt

Puntos clave sobre el código

• El primer paso es verificar si las funciones de audio espacial están disponibles con spatialCapabilities.
• Establecer contentType en CONTENT_TYPE_SONIFICATION y usage en USAGE_ASSISTANCE_SONIFICATION permite que el sistema trate este archivo de audio como un efecto de sonido.
• En el ejemplo anterior, se carga el archivo de audio en el grupo inmediatamente antes de usarlo para mantener el código unido por motivos de simplicidad. Lo ideal es que cargues todos los efectos de sonido de forma asíncrona mientras se carga la app, de modo que todos los archivos de audio estén disponibles en el grupo cuando los necesites.

Agrega sonido estéreo y envolvente a tu app

La forma recomendada de agregar sonido estéreo y envolvente a tu app es con Exoplayer. Para obtener más información sobre cómo usar el audio espacial con Exoplayer, consulta la guía de audio espacial.

Importante: Para renderizar correctamente el sonido estéreo o envolvente, los archivos deben tener dos o más canales, y el uso en AudioAttributes debe ser USAGE_MEDIA o el ContentType debe ser CONTENT_TYPE_MOVIE, CONTENT_TYPE_MUSIC o CONTENT_TYPE_SPEECH.

Posicionamiento de las bocinas estéreo y de sonido envolvente

Con el posicionamiento de las bocinas de sonido envolvente, las bocinas de sonido envolvente virtuales se posicionan y orientan en relación con una bocina central, alrededor del usuario en una configuración de ITU estándar.

De forma predeterminada, la bocina del canal central se coloca en el mainPanelEntity de la app. Esto incluye las apps para dispositivos móviles que tienen su audio espacializado automáticamente por Android XR.

En el caso del estéreo, la ubicación de las bocinas es similar a la del sonido envolvente, excepto que solo los canales izquierdo y derecho se colocan en los lados izquierdo y derecho del panel, respectivamente.

Si tienes varios paneles y quieres elegir cuál emite audio, o si quieres que el audio estéreo o envolvente se renderice en relación con otro Entity, puedes usar PointSourceAttributes para definir la ubicación del canal central. Los canales restantes se colocarán como se mencionó anteriormente. En estas situaciones, también debes usar MediaPlayer.

A medida que el usuario se mueva por su espacio, las bocinas virtuales estéreo y de sonido envolvente se moverán y ajustarán para garantizar que siempre estén en una posición óptima.

Si configuraste MediaPlayer o ExoPlayer para seguir reproduciendo sonido estéreo o envolvente en segundo plano, el posicionamiento de la bocina virtual se alterará cuando la app se ejecute en segundo plano. Como no hay un panel ni otro punto en el espacio para fijar el sonido, el audio espacial se mueve con el usuario (en otras palabras, está "bloqueado en la cabeza").

Ejemplo de sonido envolvente

En el siguiente ejemplo, se carga un archivo de audio 5.1 con MediaPlayer y se configura el canal central del archivo para que sea un Entity.

// 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
}
SpatialAudio.kt

Puntos clave sobre el código

• Al igual que en el ejemplo de audio posicional, el primer paso es verificar si las funciones de audio espacial están disponibles con spatialCapabilities.
• Si configuras contentType como AudioAttributes.CONTENT_TYPE_MUSIC y el uso como AudioAttributes.USAGE_MEDIA, el sistema tratará este archivo de audio como sonido envolvente.

Agrega campos de sonido ambisónico a tu app

La forma más sencilla de reproducir campos de sonido ambisónicos es cargar el archivo con un MediaPlayer. Dado que el sonido ambisónico se aplica a todo el paisaje sonoro, no es necesario que especifiques un Entity para proporcionar una posición. En su lugar, crea una instancia de SoundFieldAttributes con el orden ambisónico adecuado que especifique la cantidad de canales.

Ejemplo de Ambionics

En el siguiente ejemplo, se reproduce un campo de sonido ambisónico con MediaPlayer.

// 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
}
SpatialAudio.kt

Puntos clave sobre el código

• Al igual que con los fragmentos anteriores, el primer paso es verificar si las funciones de audio espacial están disponibles con spatialCapabilities.
• La contentType y el uso son meramente informativos.
• El SpatializerConstants.AmbisonicsOrder.FIRST_ORDER le indica a SceneCore que el archivo de campo de sonido define cuatro canales.