在 XR 應用程式中加入空間音訊

Jetpack SceneCore 的空間音訊功能可讓您在 Android XR 應用程式中，打造沉浸式音訊體驗。

空間音訊會模擬使用者在 3D 環境中感知聲音的方式，營造出聲音從四面八方傳來的感覺，包括使用者上方和下方。系統會在 3D 空間的特定位置模擬一或多個「虛擬揚聲器」，藉此達到上述效果。

如果現有應用程式並非專為 Android XR 設計或修改，Android XR 會自動將音訊空間化。使用者在空間中移動時，所有應用程式音訊都會從應用程式 UI 顯示的面板發出。舉例來說，如果時鐘應用程式的計時器響起，音訊會從應用程式面板的位置發出。Android XR 會自動調整音效，呈現真實的位置感。舉例來說，應用程式面板與使用者之間的距離會影響音量，讓使用者更有身歷其境的感覺。

如要進一步瞭解現有應用程式如何算繪空間音訊，請參閱本頁面的「在應用程式中加入立體聲和環繞音效」一節。

如果您要針對 XR 最佳化應用程式，Jetpack SceneCore 提供進階空間音訊自訂工具。您可以在 3D 環境中精確定位聲音、使用全向性音訊呈現逼真的音場，以及運用內建的環繞音效整合功能。

Android XR 支援的空間音訊類型

Android XR 支援定位、立體聲、環場音效和雙聲道音訊。

位置音訊

位置音訊可設定在 3D 空間中的特定點播放。 舉例來說，您可以在虛擬環境的角落放置一隻狗的3D 模型，並讓牠發出吠叫聲。您可以讓多個實體從各自的位置發出聲音。如要算繪位置音訊，檔案必須是單聲道或立體聲。

空間化立體聲和環場音效

系統支援所有Android 媒體格式，可提供定位、立體聲和環場音效。

立體聲音訊是指有兩個聲道的音訊格式，環場音效是指有超過兩個聲道的音訊格式，例如 5.1 環場音效或 7.1 環場音效設定。每個聲道的聲音資料都會與一個音箱相關聯。舉例來說，以立體聲播放音樂時，左揚聲器聲道發出的樂器音軌可能與右揚聲器不同。

電影和電視節目通常會使用環場音效，透過多個音箱聲道增強真實感和沉浸感。舉例來說，對話通常會透過中央揚聲器聲道播放，而直升機飛行的聲音可能會依序使用不同聲道，營造直升機在 3D 空間中飛行的感覺。

全景聲

全景聲音訊 (或全景聲) 就像音訊的空中攝影棚，可為使用者提供沉浸式音景。使用 Ambisonics 技術，模擬背景環境音效，或在其他情境中複製環繞聆聽者的全球形音場。Android XR 支援一階、二階和三階環繞聲的 AmbiX 環繞聲音訊格式。建議使用 Opus (.ogg) 和 PCM/Wave (.wav) 檔案類型。

使用 Jetpack SceneCore 空間音訊

使用 Jetpack SceneCore 實作空間音訊時，需要檢查空間功能，並選擇用於載入空間音訊的 API。

檢查空間功能

使用空間音訊功能前，請確認 Session 支援空間音訊。在下列各節的所有程式碼片段中，系統都會先檢查功能，再嘗試播放空間音訊。

載入空間音訊

您可以使用下列任一 API 載入空間音訊，以便在 Jetpack SceneCore 中使用。

  • SoundPool：適合大小不到 1 MB 的短音效，會預先載入，且可重複使用。這是載入位置音訊的絕佳方式。
  • ExoPlayer：適合載入立體聲和環繞音效內容，例如音樂和影片。還能讓媒體在背景播放。
  • MediaPlayer：提供載入 Ambisonics 音訊最簡單的方式。
  • AudioTrack：可充分控管音訊資料的載入方式。 可直接寫入音訊緩衝區，或寫入您合成或解碼的音訊檔案。

在應用程式中加入位置音訊

位置音效來源是由 PointSourceParams 和相關聯的 Entity 定義。Entity 的位置和方向會決定 PointSourceParams 在 3D 空間中的算繪位置。

位置音訊範例

以下範例會將音效音訊檔案載入音效集區，並在 Entity 的位置播放。

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities
    .hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_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
}
SpatialAudio.kt

程式碼相關重點

  • 首先，請使用 spatialCapabilities 確認目前是否支援空間音訊功能。
  • 將 contentType 設為 CONTENT_TYPE_SONIFICATION，並將 usage 設為 USAGE_ASSISTANCE_SONIFICATION，系統就會將這個音訊檔案視為音效。
  • 上述範例會將音訊檔案載入集區，然後立即使用，方便您將程式碼放在一起。理想情況下，您應該在載入應用程式時，非同步載入所有音效，這樣一來，需要時就能從集區中取得所有音訊檔案。

在應用程式中加入立體聲和環繞音效

建議使用 Exoplayer，在應用程式中加入立體聲和環場音效。如要進一步瞭解如何搭配 Exoplayer 使用空間音訊，請參閱空間音訊指南。

立體聲和環場音效揚聲器位置

透過環繞喇叭定位，虛擬環繞喇叭會根據中央喇叭的位置和方向，以標準 ITU 設定環繞使用者。

根據預設，中央聲道喇叭會放在應用程式的 mainPanelEntity。包括 Android XR 自動空間化的行動應用程式。

如果是立體聲，揚聲器擺放位置與環繞音效類似，但只有左聲道和右聲道分別位於面板的左右兩側。

如果你有多個面板，並想選擇要發出音訊的面板，或是想讓立體聲或環繞音訊相對於另一個  進行算繪，可以使用  定義中央聲道的所在位置。EntityPointSourceAttributes其餘管道會如先前所述放置。在這些情況下，您也必須使用 MediaPlayer。

使用者在空間中移動時，立體聲和環繞音效虛擬音箱會隨之移動和調整，確保音箱始終處於最佳位置。

如果已設定 MediaPlayer 或 ExoPlayer 在背景繼續播放立體聲或環繞音效，應用程式在背景執行時，虛擬揚聲器位置會改變。由於沒有面板或其他空間點可將聲音錨定在特定位置，空間音訊會隨著使用者移動 (也就是「頭部鎖定」)。

環場音效範例

以下範例會使用 MediaPlayer 載入 5.1 音訊檔案，並將檔案的中央聲道設為 Entity。

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities.hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_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
}
SpatialAudio.kt

程式碼相關重點

在應用程式中新增全景聲音場

如要播放環場音場，最簡單的方法是使用 MediaPlayer 載入檔案。由於全景聲適用於整個音場，因此您不需要指定 Entity 來提供位置。您必須先建立 SoundFieldAttributes 的執行個體，並指定適當的 Ambisonics 階數和聲道數。

Ambionics 示例

以下範例使用 MediaPlayer 播放 Ambisonics 音場。

// Check spatial capabilities before using spatial audio
if (session.scene.spatialCapabilities.hasCapability(SpatialCapabilities.SPATIAL_CAPABILITY_SPATIAL_AUDIO)) {
    // The session has spatial audio capabilities

    val soundFieldAttributes =
        SoundFieldAttributes(SpatializerConstants.AMBISONICS_ORDER_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

程式碼相關重點

  • 與先前的程式碼片段相同，第一步是使用 hasCapability() 檢查空間音訊功能是否可用。
  • contentType 和使用方式僅供參考。
  • AMBISONICS_ORDER_FIRST_ORDER 訊號會向 SceneCore 指出音場檔案定義了四個聲道。