XAudio 2.9의 재배포 가능 버전에 대한 개발자 가이드

아티클
03/15/2025

XAudio 2.9 버전은 NuGet 패키지사용할 수 있습니다. 개발자는 이 버전의 XAudio 2.9를 앱으로 재배포할 수 있습니다. 이렇게 하면 앱이 운영 체제 이미지의 일부로 XAudio 2.9를 포함하지 않는 이전 버전의 Windows에서 XAudio 2.9를 사용할 수 있습니다. 이 재배포 가능 패키지는 2010년 이후 XAudio 2.7이 업데이트되지 않았기 때문에 DirectX SDK에서 XAudio 2.7을 재배포하는 대신 사용하는 것이 좋습니다.

DirectX 개발자를 위한 더 많은 리소스를 보려면 DirectX 방문 페이지 방문해야 합니다.

지원되는 플랫폼

XAudio 2.9 NuGet 패키지(Microsoft.XAudio2.Redist.*.nupkg)에는 XAudio 2.9 API를 구현하는 32비트 및 64비트 버전의 DLL이 포함되어 있습니다. DLL의 이름은 XAUDIO2_9REDIST.DLL입니다. 이 DLL은 Windows 7 SP1, Windows 8, Windows 8.1 및 Windows 10에서 작동합니다.

DLL이 Windows 10 시스템에서 사용되는 경우 운영 체제의 일부인 XAUDIO2_9.DLL 버전 번호를 확인하고 운영 체제가 최신인 경우 운영 체제에서 XAUDIO2_9.DLL 모든 API 호출을 위임합니다. 이렇게 하면 앱이 항상 현재 플랫폼에서 사용할 수 있는 최신 버전의 XAudio 2.9를 사용할 수 있습니다.

DLL은 Xbox One용이 아닙니다. Xbox One에서 사용되는 경우 DLL은 항상 모든 API 호출을 Xbox One 운영 체제의 XAUDIO2_9.DLL 위임합니다.

DLL은 UWP 앱용이 아닙니다. UWP 앱은 운영 체제의 일부인 XAUDIO2_9.DLL 사용해야 합니다.

NuGet 패키지 설치

NuGet 패키지를 설치하는 가장 쉬운 방법은 Microsoft Visual Studio에서 NuGet 패키지 관리자 사용하는 것입니다. 이렇게 하면 Microsoft.XAudio2.Redist.targets 포함하도록 Visual Studio 프로젝트 파일이 자동으로 업데이트됩니다. .targets 파일은 XAudio2의 헤더 파일이 있는 Include 폴더를 프로젝트 포함 경로 컬렉션에 추가합니다. .targets 파일은 .DLL 또는 .EXE가 XAUDIO2REDIST.LIB 및 XAPOBASEREDIST.LIB와 연결되도록 합니다.

라이브러리 XAPOBASEREDIST.LIB는 사용자 지정 XAudio 처리 개체(XAPO)를 구현하려는 경우에만 필요하며, 사용하지 않는 경우 Microsoft.XAudio2.Redist.targets에서 제거할 수 있습니다.

다른 도구를 사용하여 NuGet 패키지의 콘텐츠를 추출하거나 파일 확장명 이름을 바꿔 ZIP 추출기 도구를 사용하여 파일을 .zip 추출할 수도 있습니다.

VC++ 패키지 관리자사용할 수 있는 xaudio2redist 포트도 있습니다.

앱 컴파일

포함할 헤더 선택

XAudio 2.9 NuGet 패키지에는 Windows 10 SDK에 포함된 것과 동일한 XAudio2 헤더 파일이 포함되어 있습니다. 그러나 헤더 파일은 이전 버전의 Windows를 포함하여 지원되는 모든플랫폼을 명시적으로 대상으로 지정하면서 사용할 수 있도록 몇 가지 조정을 받았습니다.

Microsoft Visual Studio에서 NuGet 패키지 관리자를 사용하여 NuGet 패키지 을 설치하면 이 경우 헤더 파일의 경로가 Windows SDK 헤더 파일의 경로 앞에 위치합니다. 즉, 프로젝트의 코드에 XAUDIO2.H 헤더가 포함되어 있으면, NuGet 패키지에서 플랫폼 간 호환 가능한 헤더를 선택하게 됩니다. 일반적으로 원하는 동작입니다.

프로젝트에 포함 헤더의 경로를 수동으로 추가할 경우, 잘못된 순서로 지정하면 Windows SDK의 OS 버전별 XAUDIO2.H 파일이 포함되어 플랫폼 간 버전의 XAUDIO2.H가 아닌 파일이 포함될 수 있으므로 주의해야 합니다.

헤더 포함 시 오류가 적도록 NuGet 패키지에는 각 헤더의 버전에 "REDIST"가 추가되어 있습니다. 예를 들어, NuGet 패키지에는 XAUDIO2.H 외에도 XAUDIO2REDIST.H가 포함됩니다. 선호하는 경우, 어떤 헤더 파일이 사용되는지에 대한 모호성을 제거하기 위해 코드에 XAUDIO2REDIST.H를 직접 포함할 수 있습니다. -REDIST를 포함하는 경우 헤더 파일의 H 버전으로, 포함 파일 디렉터리를 프로젝트 파일에 나열하는 순서는 중요하지 않습니다.

Xbox One용으로 앱을 컴파일할 경우, 계속해서 Xbox One 전용 API 중 일부가 XAUDIO2REDIST.H에서 제외되어 있으므로, XAUDIO2.H를 포함해야 합니다. 이 NuGet 패키지는 Xbox One용이 아닙니다.

DLL 로드

앱을 XAUDIO2REDIST.LIB에 연결하고, XAUDIO2_9REDIST.DLL을 앱의 실행 파일과 동일한 폴더에 설치하는 것을 권장합니다. 이로 인해 실행 파일이 시작되는 즉시 XAUDIO2_9REDIST.DLL 로드됩니다. 그러나 원하는 경우 LoadLibraryEx 사용하고 GetProcAddress사용하여 요청 시 XAUDIO2_9REDIST.DLL 로드할 수 있습니다. 앱에서 XAudio2 API를 항상 사용할 필요가 없는 경우 이 솔루션이 좋습니다. 그러나 이렇게 하면 백그라운드 스레드가 DLL에서 코드를 계속 실행하는 경우 DLL을 언로드하려고 하면 충돌이 발생할 수 있으므로 앱이 종료될 때까지 XAUDIO2_9REDIST.DLL 로드된 상태로 유지해야 합니다.

이전 XAudio 2.7과 달리 CoCreateInstance를 사용하여 DLL을 로드할 수 없습니다.

DLL 서명 확인

XAUDIO2_9REDIST.DLL 이진 파일은 SHA-2 서명을 사용하여 Microsoft에서 서명합니다. 서명의 유효성을 검사하려는 모든 코드(예: 게임의 치트 방지 모듈)는 SHA-2를 지원해야 합니다. Windows 7 SP1은 원래 SHA-2를 지원하지 않았으며 해당 기능을 추가하려면 업데이트가 필요합니다. 업데이트는 KB4474419사용할 수 있습니다.

테스트

오류 처리

오디오 장치의 변화를 게임이 처리할 수 있는지 테스트하는 것이 중요합니다. 예를 들어, 헤드폰이 연결되거나 분리될 때를 대비해서 말입니다. 44.1kHz 샘플링 속도만 지원하는 헤드폰으로 테스트해야 합니다. 많은 저가형 USB 헤드폰 및 Bluetooth 헤드셋은 44.1kHz만 지원합니다. 48kHz 샘플링 속도와 44.1kHz 샘플링 속도 사이의 전환은 가상 오디오 엔드포인트 기능을 사용하는 경우에도 오류를 일으킬 수 있습니다. 헤드폰도 48kHz를 지원하는 경우에는 오류가 발생하지 않습니다. Windows 7 SP1에서는 가상 오디오 엔드포인트 기능을 사용할 수 없습니다.

XAudio 2.9에서 오디오 엔드포인트의 변경으로 인해 자동 복구할 수 없는 경우 반환되는 오류 코드는 XAUDIO2_E_DEVICE_INVALIDATED입니다. 그러나 앱은 특정 값을 갖는 오류 코드에 대한 종속성을 하드 코딩하지 않는 것이 좋습니다.

오류 알림을 받도록 앱은 IXAudio2EngineCallback 인터페이스를 구현하고 IXAudio2::RegisterForCallbacks 메서드를 호출하여 해당 인터페이스에 대한 포인터를 제공해야 합니다. 재생 중에 오류가 발생하면 XAudio2 API에서 IXAudio2EngineCallback::OnCriticalError 앱의 구현이 호출됩니다.

오디오 파이프라인이 일시 중지된 경우 IXAudio2EngineCallback::OnCriticalError이(가) 반드시 호출되는 것은 아닙니다. 예를 들어 사용자가 앱을 최소화하거나 어떤 이유로든 앱이 일시 중단되면 오디오 재생이 일시 중지될 수 있습니다. 이 시간 동안 오디오 디바이스의 변경이 발생하는 경우 앱이 IXAudio2::StartEngine 호출하거나 IXAudio2SourceVoice::Start호출할 때만 오류가 반환됩니다. 앱에서 재생을 일시 중지할 수 있는 경우 재생이 일시 중지된 동안 오디오 장치 변경을 테스트하여 앱이 이 상황에서 복구할 수 있는지 확인해야 합니다.

XAudio 2.7과 비교한 XAudio 2.9 API 차이점

이 섹션에서는 XAudio 2.7과 XAudio 2.9의 재배포 가능 버전 간의 몇 가지 API 차이점에 대한 요약을 제공합니다.

지원되는 형식

XAudio 2.9는 PC에서 다음과 같은 입력 형식을 지원합니다.

선형 16비트 PCM
선형 32비트 Float PCM
16비트 ADPCM
xWMA

XMA 형식은 Xbox One에서만 지원됩니다.

기본 CPU 코어

오디오 처리 스레드에 사용해야 하는 CPU 코어 XAudio 2.9를 지정할 수 있습니다. 그러나 일반적으로 XAudio 2.9에서 이 값을 단독으로 선택할 수 있도록 하는 것이 좋습니다. 이 작업은 XAudio2Create 호출에서 XAudio2Processor 매개 변수를 XAUDIO2_USE_DEFAULT_PROCESSOR로 설정하여 수행됩니다.

XAudio 2.9는 PC가 아닌 Xbox One에서 다른 CPU 코어를 선택합니다. IXAudio2Extension::GetProcessor 메서드를 사용하여 선택한 CPU 코어 XAudio2를 확인할 수 있습니다.

가상 오디오 엔드포인트

XAudio 2.9는 Windows 8 이상에서 실행할 때 기본적으로 가상 오디오 엔드포인트를 사용합니다. 즉, XAudio 2.9를 사용하는 동안 기본 오디오 엔드포인트가 변경되면 새 오디오 엔드포인트로 자동 전환하려고 시도합니다. 기본 오디오 엔드포인트가 USB로 연결된 헤드폰일 때, 사용자가 헤드폰을 뽑으면 발생할 수 있는 문제의 예입니다. 이로 인해 스피커가 새로운 기본 오디오 엔드포인트가 됩니다.

앱이 IXAudio2::CreateMasteringVoice호출할 때 특정 오디오 형식을 지정하는 경우 XAudio 2.9에서 이 스위치를 수행할 수 없습니다. 예를 들어 마스터링 음성이 48kHz 샘플링 속도를 사용하고 새 오디오 디바이스가 44.1kHz만 지원한다고 앱이 지정한 경우 자동 스위치가 실패하고 XAudio 2.9가 XAUDIO2_E_DEVICE_INVALIDATED 오류를 보고합니다.

앱은 IXAudio2::CreateMasteringVoice에서XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT 플래그를 전달하여 가상 오디오 엔드포인트 사용을 중단할 수 있습니다.

가상 오디오 엔드포인트는 Windows 7 SP1에서 사용할 수 없습니다. XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT 플래그는 Windows 7 SP1에 영향을 주지 않습니다.

오디오 범주

앱은 오디오 스트림에 대한 범주를 지정해야 합니다. 이 작업은 IXAudio2::CreateMasteringVoice 메서드를 호출할 때 AudioCategory 열거형의 값을 제공하여 수행됩니다. 예를 들어 AudioCategory_GameEffects. 오디오 범주는 Windows에서 소리를 처리하는 방법 또는 볼륨 제어판의 오디오 스트림을 나타내는 방식에 영향을 줄 수 있습니다. 오디오 범주는 가상 서라운드 사운드이 자동으로 활성화되는지에 영향을 줍니다.

오디오 처리 시간 양자

대부분의 PC에서 XAudio 2.9는 오디오를 10밀리초 단위로 처리합니다. 이를 처리 양자라고 합니다. 그러나 이 양자의 기간은 일부 하드웨어에서 10밀리초와 다를 수 있습니다. 정확한 양자를 알아야 하는 앱은 IXAudio2Extension::GetProcessingQuantum 메서드를 호출하여 값을 검색할 수 있습니다.

공간 사운드 및 가상 서라운드

Windows 10 1903 업데이트부터 XAudio 2.9는 특정 조건이 충족되는 경우 가상 서라운드 사운드를 자동으로 사용합니다. Windows 10 1903 이상에서 다중 채널 사운드를 생성하는 게임을 테스트하여 게임이 예상대로 들리는지 확인하는 것이 좋습니다. 공간 사운드 섹션에서 이 기능을 테스트하는 방법에 대한 논의를 확인하세요.

일반적으로 XAudio 2.9는 오디오 엔드포인트에서 지원하는 "실제" 오디오 채널 수에 맞게 다채널 오디오를 다운믹스합니다. 예를 들어 게임에서 7.1 채널 오디오 소스를 제공하지만 헤드폰에서 소리가 재생되는 경우 XAudio 2.9는 업계 표준 접이식 매트릭스를 사용하여 7.1 채널 오디오를 스테레오로 접습니다. PC가 HDMI 오디오 엔드포인트에 연결된 경우 HDMI 연결을 통해 as-is 7.1 채널 오디오가 전송됩니다.

Windows 10은 사용자가 선택한 공간 사운드 형식으로 오디오를 인코딩하는 중앙 집중식 인코더를 사용하여 공간 오디오에 대한 지원을 추가합니다. Windows 10에는 Windows Sonic이라는 공간 사운드 형식이 포함되어 있습니다. 헤드폰용 Dolby Atmos와 같은 다른 형식은 Microsoft Store에서 다운로드할 수 있습니다. Windows Sonic 및 Dolby Atmos for Headphones와 같은 일부 공간 사운드 형식은 스테레오 오디오 엔드포인트에서 사용하도록 설계되었습니다. 이러한 형식은 "가상" 서라운드 사운드 효과를 달성하는 독점 알고리즘을 사용하여 서라운드 사운드를 스테레오로 접습니다. 즉, 수신기는 헤드폰을 착용하는 동안이나 스테레오 스피커 한 켤레에서 듣는 동안에도 3D 공간에서 다른 위치에서 나타나는 소리를 인식할 수 있습니다.

XAudio 2.9에 포함된 X3DAudio API를 사용하여 유사한 효과를 달성할 수 있습니다. 주요 차이점은 X3DAudio를 사용하려면 앱 개발자가 3D 오디오를 명시적으로 프로그래밍해야 하는 반면 가상 서라운드 사운드는 모든 트래디언 채널 기반 사운드 소스에 자동으로 적용된다는 점입니다.

Windows 10 1903 이상에서는 XAudio 2.9를 사용하는 게임이 오디오 엔드포인트에서 사용하도록 설정한 시스템 전체 공간 사운드 형식(있는 경우)을 사용합니다. 즉, XAudio 2.9는 서라운드 사운드를 스테레오로 다운믹스하는 일반적인 작업을 수행하지 않습니다. 대신, 서라운드 사운드 신호는 가상 서라운드 사운드 효과를 얻기 위해 공간 사운드 인코더(예: Windows Sonic)에 전달됩니다.

CreateHrtfApo

CreateHrtfApo 함수는 Windows 10에서만 사용할 수 있습니다. XAudio 2.9 재배포 가능 패키지에서는 구현되지 않습니다.

다음을 통해 공유