다음을 통해 공유

오디오 처리 개체 구현

  • 아티클

이 항목에서는 APO(오디오 처리 개체)를 구현하는 방법에 대해 설명합니다. API에 대한 일반적인 내용은 오디오 처리 개체 아키텍처를 참조 하세요.

사용자 지정 API 구현

사용자 지정 API는 In-process COM 개체로 구현되므로 사용자 모드에서 실행되고 DLL(동적 연결 라이브러리)에 패키지됩니다. 신호 처리 그래프에 삽입되는 위치에 따라 세 가지 유형의 APO가 있습니다.

  • 스트림 효과(SFX)
  • 모드 효과(MFX)
  • 엔드포인트 효과(EFX)

각 논리 디바이스는 각 유형의 하나의 APO와 연결할 수 있습니다. 모드 및 효과에 대한 자세한 내용은 오디오 신호 처리 모드를 참조 하세요.

Baseaudioprocessingobject.h 파일에 선언된 CBaseAudioProcessingObject 기본 클래스에 사용자 지정 클래스를 기반으로 하여 APO를 구현할 수 있습니다. 이 방법에는 CBaseAudioProcessingObject 기본 클래스에 새 기능을 추가하여 사용자 지정된 APO를 만드는 작업이 포함됩니다. CBaseAudioProcessingObject 기본 클래스는 APO에 필요한 많은 기능을 구현합니다. 세 가지 필수 인터페이스의 대부분의 메서드에 대한 기본 구현을 제공합니다. 주요 예외는 IAudioProcessingObjectRT::APOProcess 메서드입니다.

사용자 지정 API를 구현하려면 다음 단계를 수행합니다.

  1. 원하는 오디오 처리를 제공하는 사용자 지정 APO com 개체를 만듭니다.
  2. 필요에 따라 a를 사용하여 사용자 지정 API를 구성하기 위한 사용자 인터페이스를 만듭니다.
  3. API 및 사용자 지정 사용자 인터페이스를 설치하고 등록하는 INF 파일을 만듭니다.

사용자 지정 APO 개발에 대한 디자인 고려 사항

모든 사용자 지정 API에는 다음과 같은 일반적인 특성이 있어야 합니다.

  • APO에는 하나의 입력과 하나의 출력 연결이 있어야 합니다. 이러한 연결은 오디오 버퍼이며 여러 채널을 가질 수 있습니다.

  • APO는 IAudioProcessingObjectRT::APOProcess 루틴을 통해 전달되는 오디오 데이터만 수정할 수 있습니다 . APO는 KS 토폴로지 등 기본 논리 디바이스의 설정을 변경할 수 없습니다.

  • API는 IUnknown 외에도 다음 인터페이스를 노출해야 합니다.

  • 모든 API에는 실시간 시스템 호환성이 있어야 합니다. 이는 다음을 의미합니다.

    • 실시간 인터페이스의 멤버인 모든 메서드는 차단 해제 멤버로 구현되어야 합니다. 차단하거나, 페이징된 메모리를 사용하거나, 차단 시스템 루틴을 호출해서는 안 됩니다.

    • APO에서 처리되는 모든 버퍼는 페이지를 처리할 수 없어야 합니다. 프로세스 경로의 모든 코드와 데이터는 페이지를 처리할 수 없어야 합니다.

    • API는 오디오 처리 체인에 상당한 대기 시간을 도입해서는 안 됩니다.

  • 사용자 지정 API는 IAudioProcessingObjectVBR 인터페이스를 노출해서는 안 됩니다.

참고 항목

필요한 인터페이스에 대한 자세한 내용은 Windows Kits\build number>\<Include\um 폴더의 Audioenginebaseapo.h 및 Audioenginebaseapo.idl 파일을 참조하세요.

샘플 코드를 사용하여 개발 프로세스 가속화

SYSVAD Swap APO 코드 샘플을 템플릿으로 사용하면 사용자 지정 APO 개발 프로세스를 가속화할 수 있습니다. Swap 샘플은 오디오 처리 개체의 일부 기능을 설명하기 위해 개발된 샘플입니다. Swap APO 샘플은 왼쪽 채널을 오른쪽 채널로 교환하고 SFX 및 MFX 효과를 모두 구현합니다. 속성 대화 상자를 사용하여 채널 교환 오디오 효과를 사용하거나 사용하지 않도록 설정할 수 있습니다.

SYSVAD 오디오 샘플은 Windows 드라이버 샘플 GitHub에서 사용할 수 있습니다.

여기에서 Sysvad 오디오 샘플을 찾아볼 수 있습니다.

https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad

GitHub에서 Sysvad 오디오 샘플 다운로드 및 추출

다음 단계에 따라 SYSVAD 샘플을 다운로드하고 엽니다.

a. GitHub 도구를 사용하여 샘플을 사용할 수 있습니다. 하나의 zip 파일에서 유니버설 드라이버 샘플을 다운로드할 수도 있습니다.

https://github.com/Microsoft/Windows-driver-samples/archive/master.zip

b. 로컬 하드 드라이브에 master.zip 파일을 다운로드합니다.

c. Windows-driver-samples-master.zip 길게 누르거나 마우스 오른쪽 단추로 클릭하고 모두 추출을 선택합니다. 새 폴더를 지정하거나 추출된 파일을 저장할 기존 폴더를 찾습니다. 예를 들어 C:\DriverSamples\를 파일을 추출할 새 폴더로 지정할 수 있습니다.

d. 파일을 추출한 후 다음 하위 폴더 로 이동합니다. C:\DriverSamples\Audio\Sysvad

Visual Studio에서 드라이버 솔루션 열기

Microsoft Visual Studio에서 파일>열기>프로젝트/솔루션을 선택하고 추출된 파일이 포함된 폴더(예: C:\DriverSamples\Audio\Sysvad)로 이동합니다. Sysvad 솔루션 파일을 두 번 클릭하여 엽니다.

Visual Studio에서 솔루션 탐색기 찾습니다. (아직 열려 있지 않은 경우보기 메뉴에서 솔루션 탐색기.) 솔루션 탐색기 6개의 프로젝트가 있는 하나의 솔루션을 볼 수 있습니다.

SwapAPO 예제 코드

SYSVAD 샘플에는 5개의 프로젝트가 있으며, 그 중 하나는 APO 개발자에게 주요 관심사입니다.

프로젝트 설명
SwapAPO 예제 APO에 대한 샘플 코드

Sysvad 샘플의 다른 프로젝트는 아래에 요약되어 있습니다.

프로젝트 설명
TabletAudioSample 대체 오디오 드라이버에 대한 샘플 코드입니다.
KeywordDetectorAdapter 키워드(keyword) 감지기 어댑터에 대한 샘플 코드
EndpointsCommon 공통 엔드포인트에 대한 샘플 코드입니다.

SwapAPO 샘플의 기본 헤더 파일은 swapapo.h입니다. 다른 기본 코드 요소는 아래에 요약되어 있습니다.

파일 설명
Swap.cpp Swap APO의 구현을 포함하는 C++ 코드입니다.
SwapAPOMFX.cpp CSwapAPOMFX 구현
SwapAPOSFX.cpp CSwapAPOSFX 구현
SwapAPODll.cpp DLL 내보내기 구현.
SwapAPODll.idl DLL에 대한 COM 인터페이스 및 코클래스의 정의입니다.
SwapAPOInterface.idl 교환 APO 기능에 대한 인터페이스 및 형식 정의입니다.
swapapodll.def COM에서 정의를 내보냅니다.

COM 개체 오디오 처리 코드 구현

Baseaudioprocessingobject.h 파일에 선언된 CBaseAudioProcessingObject 기본 클래스에 사용자 지정 클래스를 기반으로 하여 시스템 제공 APO를 래핑할 수 있습니다. 이 방법에는 CBaseAudioProcessingObject 기본 클래스에 새 기능을 도입하여 사용자 지정된 APO를 만드는 작업이 포함됩니다. CBaseAudioProcessingObject 기본 클래스는 APO에 필요한 많은 기능을 구현합니다. 세 가지 필수 인터페이스의 대부분의 메서드에 대한 기본 구현을 제공합니다. 주요 예외는 IAudioProcessingObjectRT::APOProcess 메서드입니다.

CBaseAudioProcessingObject를 사용하면 APO를 보다 쉽게 구현할 수 있습니다. APO에 특별한 형식 요구 사항이 없고 필요한 float32 형식으로 작동하는 경우 CBaseAudioProcessingObject에 포함된 인터페이스 메서드의 기본 구현으로 충분해야 합니다. 기본 구현을 고려할 때 IAudioProcessingObject::IsInputFormatSupported, IAudioProcessingObjectRT::APOProcess 및 ValidateAndCache커넥트ionInfo의 세 가지 기본 메서드만 구현해야 합니다.

CBaseAudioProcessingObject 클래스를 기반으로 API를 개발하려면 다음 단계를 수행합니다.

  1. CBaseAudioProcessingObject에서 상속되는 클래스를 만듭니다.

    다음 C++ 코드 예제에서는 CBaseAudioProcessingObject에서 상속되는 클래스를 만드는 방법을 보여 줍니다. 이 개념의 실제 구현은 오디오 처리 개체 드라이버 샘플 섹션의 지침에 따라 교환 샘플로 이동한 다음 Swapapo.h 파일을 참조하세요.

    // Custom APO class - SFX
Class MyCustomAPOSFX: public CBaseAudioProcessingObject
{
 public:
//Code for custom class goes here
...
};

    참고 SFX APO에서 수행하는 신호 처리는 MFX 또는 EFX APO에서 수행하는 신호 처리와 다르므로 각각에 대해 별도의 클래스를 만들어야 합니다.

  2. 다음 세 가지 방법을 구현합니다.

    • IAudioProcessingObject::IsInputFormatSupported. 이 메서드는 오디오 엔진과의 형식 협상을 처리합니다.

    • IAudioProcessingObjectRT::APOProcess. 이 메서드는 사용자 지정 알고리즘을 사용하여 신호 처리를 수행합니다.

    • ValidateAndCache커넥트ionInfo. 이 메서드는 채널 수, 샘플링 속도, 샘플 깊이 및 채널 마스크와 같은 형식 세부 정보를 저장하기 위해 메모리를 할당합니다.

다음 C++ 코드 예제에서는 1단계에서 만든 샘플 클래스에 대한 APOProcess 메서드의 구현을 보여 줍니다. 이 개념의 실제 구현은 오디오 처리 개체 드라이버 샘플 섹션의 지침에 따라 교환 샘플로 이동한 다음 Swapapolfx.cpp 파일을 참조하세요.

// Custom implementation of APOProcess method
STDMETHODIMP_ (Void) MyCustomAPOSFX::APOProcess (...)
{
// Code for method goes here. This code is the algorithm that actually
// processes the digital audio signal.
...
}

다음 코드 예제에서는 ValidateAndCache커넥트ionInfo 메서드의 구현을 보여줍니다. 이 메서드의 실제 구현은 오디오 처리 개체 드라이버 샘플 섹션의 지침에 따라 교환 샘플로 이동한 다음 Swapapogfx.cpp 파일을 참조하세요.

// Custom implementation of the ValidateAndCacheConnectionInfo method.
HRESULT CSwapAPOGFX::ValidateAndCacheConnectionInfo( ... )
{
// Code for method goes here.
// The code should validate the input/output format pair.
...
}

참고 CBaseAudioProcessingObject에서 클래스가 상속하는 다시 기본 인터페이스 및 메서드는 Audioenginebaseapo.idl 파일에 자세히 설명되어 있습니다.

시스템 제공 API 대체

APO 인터페이스를 구현할 때는 두 가지 방법이 있습니다. 즉, 고유한 구현을 작성하거나 받은 편지함 API를 호출할 수 있습니다.

이 의사 코드는 시스템 APO 래핑을 보여 줍니다.

CMyWrapperAPO::CMyWrapperAPO {
    CoCreateInstance(CLSID_InboxAPO, m_inbox);
}

CMyWrapperAPO::IsInputFormatSupported {
    Return m_inbox->IsInputFormatSupported(…);
}

이 의사 코드는 사용자 지정 APO를 만드는 방법을 보여 줍니다.

CMyFromScratchAPO::IsInputFormatSupported {
    my custom logic
}

시스템에서 제공하는 API를 대체할 API를 개발하는 경우 인터페이스 및 메서드에 대해 다음 목록에서 동일한 이름을 사용해야 합니다. 일부 인터페이스에는 나열된 필수 메서드 외에도 더 많은 메서드가 있습니다. 해당 인터페이스에 대한 참조 페이지를 참조하여 모든 메서드를 구현할지 아니면 필요한 메서드만 구현할지 확인합니다.

나머지 구현 단계는 사용자 지정 APO와 동일합니다.

COM 구성 요소에 대해 다음 인터페이스 및 메서드를 구현합니다.

Visual Studio 및 API 작업

Visual Studio에서 APO를 사용하는 경우 각 APO 프로젝트에 대해 이러한 작업을 수행합니다.

Windows 10을 대상으로 하는 드라이버는 범용 CRT에 동적으로 연결해야 합니다.

Windows 8,1을 지원해야 하는 경우 C/C++, 코드 생성에서 프로젝트 속성을 설정하여 정적 연결을 사용하도록 설정합니다. 릴리스 빌드의 경우 "런타임 라이브러리"를 /MT 로, 디버그 빌드 의 경우 /MTd 로 설정합니다. 드라이버의 경우 MSVCRT<n>.dll 이진 파일을 재배포하기가 어렵기 때문에 이 변경이 수행됩니다. 해결 방법은 libcmt.dll 정적으로 연결하는 것입니다. 자세한 내용은 /MD, /MT, /LD(런타임 라이브러리 사용) 를 참조하세요.

포함된 매니페스트 사용 사용 안 함

APO 프로젝트에 대한 프로젝트 속성을 설정하여 포함된 매니페스트 사용을 사용하지 않도록 설정합니다. 매니페스트 도구, 입력 및 출력을 선택합니다. 그런 다음, "매니페스트 포함"을 기본 예 에서 아니요로 변경합니다. 포함된 매니페스트가 있는 경우 보호된 환경 내에서 금지된 특정 API의 사용을 트리거합니다. 즉, APO가 DisableProtectedAudioDG=1로 실행되지만 이 테스트 키가 제거되면 WHQL 서명된 경우에도 APO가 로드되지 않습니다.

드라이버로 APO 패키징

고유한 오디오 드라이버를 개발하고 시스템 제공 API를 래핑하거나 교체하는 경우 드라이버 및 API를 설치하기 위한 드라이버 패키지를 제공해야 합니다. Windows 10의 경우 오디오용 유니버설 Windows 드라이버를 참조하세요. 오디오 관련 드라이버 패키지는 설명된 정책 및 패키징 모델을 따라야 합니다.

사용자 지정 APO는 DLL로 패키지되고 모든 구성 UI는 별도의 UWP 또는 데스크톱 브리지 앱으로 패키지됩니다. APO 디바이스 INF는 DLL을 연결된 INF CopyFile 지시문에 표시된 시스템 폴더에 복사합니다. API가 포함된 DLL은 INF 파일에 AddReg 섹션을 포함하여 자체 등록해야 합니다.

다음 단락 및 INF 파일 조각은 표준 INF 파일을 사용하여 API를 복사하고 등록하는 데 필요한 수정 사항을 보여 줍니다.

Sysvad 샘플에 포함된 inf 파일은 SwapApo.dll API가 등록되는 방법을 보여 줍니다.

INF 파일에서 처리 모드 및 효과에 대한 API 등록

레지스트리 키의 허용 가능한 특정 조합을 사용하여 특정 모드에 API를 등록할 수 있습니다. 사용할 수 있는 효과에 대한 자세한 내용과 API에 대한 일반적인 정보는 오디오 처리 개체 아키텍처를 참조 하세요.

각 APO INF 파일 설정에 대한 자세한 내용은 다음 참조 항목을 참조하세요.

PKEY_FX_StreamEffectClsid

PKEY_FX_ModeEffectClsid

PKEY_FX_EndpointEffectClsid

PKEY_SFX_ProcessingModes_Supported_For_Streaming

PKEY_MFX_ProcessingModes_Supported_For_Streaming

PKEY_EFX_ProcessingModes_Supported_For_Streaming

다음 INF 파일 샘플에서는 특정 모드에 대한 API(오디오 처리 개체)를 등록하는 방법을 보여 줍니다. 이 목록에서 사용할 수 있는 가능한 조합을 보여 줍니다.

  • PKEY_SFX_ProcessingModes_Supported_For_Streaming 사용하여 PKEY_FX_StreamEffectClsid
  • PKEY_MFX_ProcessingModes_Suppoted_For_Streaming 사용하여 PKEY_FX_ModeEffectClsid
  • PKEY_MFX_ProcessingModes_Suppoted_For_Streaming 없는 PKEY_FX_ModeEffectClsid
  • PKEY_EFX_ProcessingModes_Supported_For_Streaming 없는 PKEY_FX_EndpointEffectClsid

이러한 샘플에는 표시되지 않는 하나의 유효한 조합이 추가로 있습니다.

  • PKEY_EFX_ProcessingModes_Supported_For_Streaming 사용하여 PKEY_FX_EndpointEffectClsid

SYSVAD 태블릿 다중 모드 스트리밍 효과 APO INF 샘플

이 샘플에서는 SYSVAD Tablet INF 파일의 AddReg 항목을 사용하여 등록되는 다중 모드 스트리밍 효과를 보여 줍니다.

이 샘플 코드는 SYSVAD 오디오 샘플에서 제공되며 GitHub에서 https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad사용할 수 있습니다.

이 샘플에서는 시스템 효과의 조합을 보여 줍니다.

  • PKEY_SFX_ProcessingModes_Supported_For_Streaming 사용하여 PKEY_FX_StreamEffectClsid
  • PKEY_MFX_ProcessingModes_Suppoted_For_Streaming 사용하여 PKEY_FX_ModeEffectClsid
[SWAPAPO.I.Association0.AddReg]
; Instruct audio endpoint builder to set CLSID for property page provider into the
; endpoint property store
HKR,EP\0,%PKEY_AudioEndpoint_ControlPanelPageProvider%,,%AUDIOENDPOINT_EXT_UI_CLSID%

; Instruct audio endpoint builder to set the CLSIDs for stream, mode, and endpoint APOs
; into the effects property store
HKR,FX\0,%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,FX\0,%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,FX\0,%PKEY_FX_UserInterfaceClsid%,,%FX_UI_CLSID%

; Driver developer would replace the list of supported processing modes here
; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

;HKR,FX\0,%PKEY_EFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%

샘플 INF 파일에서 오디오 처리가 해당 계층 위의 커널 모드로 전환되어 스트리밍 속성이 필요하지 않고 사용되지 않기 때문에 EFX_Streaming 속성이 주석 처리됩니다. 검색 목적으로 PKEY_FX_EndpointEffectClsid 지정하는 것은 유효하지만 PKEY_EFX_ProcessingModes_Supported_For_Streaming 지정하는 것은 오류입니다. 이는 엔드포인트 APO를 삽입할 수 없는 스택에서 모드 혼합/티가 더 낮아지기 때문입니다.

구성 요소화된 APO 설치

Windows 10 릴리스 1809부터 오디오 엔진을 사용한 APO 등록은 구성 요소화된 오디오 드라이버 모델을 사용합니다. 오디오 구성 요소를 사용하면 더 원활하고 안정적인 설치 환경을 만들고 구성 요소 서비스를 더 잘 지원합니다. 자세한 내용은 구성 요소화된 오디오 드라이버 설치 만들기를 참조하세요.

다음 예제 코드는 public ComponentizedAudioSampleExtension.inf 및 ComponentizedApoSample.inf에서 추출됩니다. GitHub에서 사용할 수 있는 SYSVAD 오디오 샘플을 참조하세요 https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

오디오 엔진에 APO 등록은 새로 만든 APO 디바이스를 사용하여 수행됩니다. 오디오 엔진이 새 APO 디바이스를 사용하려면 오디오 디바이스의 PNP 자식이어야 하며 오디오 엔드포인트의 형제여야 합니다. 구성 요소화된 새 APO 디자인에서는 APO를 전역적으로 등록하고 여러 다른 드라이버에서 사용할 수 없습니다. 각 드라이버는 자체 APO를 등록해야 합니다.

APO 설치는 두 부분으로 이루어집니다. 먼저 드라이버 확장 INF는 시스템에 APO 구성 요소를 추가합니다.

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

[Apo_AddComponent]
ComponentIDs = VEN_SMPL&CID_APO
Description = "Audio Proxy APO Sample"

이 APO 구성 요소는 SYSVAD 샘플에서 두 번째 부분인 APO INF 설치를 트리거합니다. 이 작업은 ComponentizedApoSample.inf에서 수행됩니다. 이 INF 파일은 APO 구성 요소 전용입니다. 구성 요소 클래스를 AudioProcessingObject로 지정하고 CLSID 등록 및 오디오 엔진에 등록하기 위한 모든 APO 속성을 추가합니다.

참고 항목

INF 파일 샘플은 HKR 레지스트리 키를 사용하여 드라이버 패키지 격리를 지원하는 것으로 나타났습니다. Windows 11 버전 22000 이전의 샘플에서는 HKCR을 사용하여 HKR 대신 CLSID 등록에 대한 영구 값을 저장했습니다. APO 등록은 Windows 10 릴리스 1809부터 HKR을 사용하여 지원되었습니다. 자세한 내용은 유니버설 INF 파일 사용을 참조 하세요.

[Version]
...
Class       = AudioProcessingObject
ClassGuid   = {5989fce8-9cd0-467d-8a6a-5419e31529d4}
...

[ApoComponents.NT$ARCH$]
%Apo.ComponentDesc% = ApoComponent_Install,APO\VEN_SMPL&CID_APO

[Apo_AddReg]
; CLSID registration
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%%SystemRoot%%\System32\swapapo.dll
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"
...
;Audio engine registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
...

이 INF가 구성 요소화된 APO를 설치하면 데스크톱 시스템 "오디오 처리 개체"가 Windows 장치 관리자 표시됩니다.

새 APO 버전이 릴리스될 때 CLSID에 업데이트

새 APO 버전이 릴리스되면 일반적으로 COM 클래스 CLSID를 업데이트하는 것이 좋습니다. GUIDGEN과 같은 도구를 사용하여 새 GUID를 만듭니다.

HKCR에서 HKR로 이동할 때 CLSID 업데이트 요구 사항

COM 클래스 GUID를 변경하기 위해 HKCR(전역 COM 등록)에서 디바이스 상대 HKR COM 등록으로 전환할 때 요구 사항입니다. 이 방법을 사용하면 새 COM 개체가 제대로 등록되지 않고 로드에 실패할 가능성이 줄어듭니다.

Bluetooth 오디오 샘플 APO INF 샘플

이 샘플에서는 시스템 효과의 조합을 보여 줍니다.

  • PKEY_SFX_ProcessingModes_Supported_For_Streaming 사용하여 PKEY_FX_StreamEffectClsid

  • PKEY_MFX_ProcessingModes_Suppoted_For_Streaming 사용하여 PKEY_FX_ModeEffectClsid

이 샘플 코드는 Bluetooth 핸즈프리 및 스테레오 디바이스를 지원합니다.

; wdma_bt.inf – example usage
...
[BthA2DP]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration,WDMAUDIO.Registration,BtaMPM.CopyFilesOnly,mssysfx.CopyFilesAndRegister
...
[BTAudio.SysFx.Render]
HKR,"FX\\0",%PKEY_ItemNameDisplay%,,%FX_FriendlyName%
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_UiClsid%,,%FX_UI_CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
...
[Strings]
FX_UI_CLSID      = "{5860E1C5-F95C-4a7a-8EC8-8AEF24F379A1}"
FX_STREAM_CLSID  = "{62dc1a93-ae24-464c-a43e-452f824c4250}"
PKEY_FX_StreamEffectClsid   = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},5"
PKEY_FX_ModeEffectClsid     = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},6"
PKEY_SFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},5"
PKEY_MFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},6"
AUDIO_SIGNALPROCESSINGMODE_DEFAULT = "{C18E2F7E-933D-4965-B7D1-1EEF228D2AF3}"

APO INF 오디오 샘플

이 샘플 INF 파일은 다음과 같은 시스템 효과 조합을 보여 줍니다.

  • PKEY_SFX_ProcessingModes_Supported_For_Streaming 사용하여 PKEY_FX_StreamEffectClsid

  • PKEY_MFX_ProcessingModes_Suppoted_For_Streaming 사용하여 PKEY_FX_ModeEffectClsid

  • PKEY_EFX_ProcessingModes_Supported_For_Streaming 없는 PKEY_FX_EndpointEffectClsid

[MyDevice.Interfaces]
AddInterface=%KSCATEGORY_AUDIO%,%MyFilterName%,MyAudioInterface

[MyAudioInterface]
AddReg=MyAudioInterface.AddReg

[MyAudioInterface.AddReg]
;To register an APO for discovery, use the following property keys in the .inf (or at runtime when registering the KSCATEGORY_AUDIO device interface):
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_MODE_CLSID%

;To register an APO for streaming and discovery, add the following property keys as well (to the same section):
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

;To register an APO for streaming in multiple modes, use a REG_MULTI_SZ property and include all the modes:
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

사용자 지정 APO 및 CLSID APO INF 샘플 정의

이 샘플에서는 사용자 지정 APO에 대한 고유한 CLSID를 정의하는 방법을 보여 줍니다. 이 샘플에서는 MsApoFxProxy CLSID {889C03C8-ABAD-4004-BF0A-BC7BB825E166}을 사용합니다. CoCreate-ing 이 GUID는 IAudioProcessingObject 인터페이스를 구현하고 KSPROPSETID_AudioEffectsDiscovery 속성 집합을 통해 기본 드라이버를 쿼리하는 MsApoFxProxy.dll 클래스를 인스턴스화합니다.

이 INF 파일 샘플은 wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave]에서 [MsApoFxProxy.Registration]을 끌어온 다음 PKEY_FX_EndpointEffectClsid MsApoFxProxy.dll 잘 알려진 CLSID로 등록하는 [BthHfAud] 섹션을 보여 줍니다.

이 INF 파일 샘플에서는 시스템 효과의 이 조합을 사용하는 방법을 보여 줍니다.

  • PKEY_EFX_ProcessingModes_Supported_For_Streaming 없는 PKEY_FX_EndpointEffectClsid
;wdma_bt.inf
[BthHfAud]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration, WDMAUDIO.Registration, BtaMPM.CopyFilesOnly, MsApoFxProxy.Registration
CopyFiles=BthHfAud.CopyList
AddReg=BthHfAud.AddReg

; Called by needs entry in oem inf
[BthHfAudOEM.CopyFiles]
CopyFiles=BthHfAud.CopyList

[BthHfAud.AnlgACapture.AddReg.Wave]
HKR,,CLSID,,%KSProxy.CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_DISCOVER_EFFECTS_APO_CLSID%
#endif

샘플 APO 효과 등록

이 샘플에서는 Sysvad ComponentizedApoSample.inx의 [Apo_AddReg] 섹션을 보여 줍니다. 이 섹션에서는 COM에 스왑 스트림 GUID를 등록하고 스왑 스트림 APO 효과를 등록합니다. [Apo_CopyFiles] 섹션에는 swapapo.dll Driverstore에 복사하는 DestinationDirs가 13입니다. 자세한 내용은 드라이버 패키지 격리의 "드라이버 저장소에서 실행"을 참조하세요.

INF 파일에 대한 일반적인 내용은 INF 파일 개요를 참조 하세요.

; ComponentizedApoSample.inx

...

[ApoComponent_Install]
CopyFiles = Apo_CopyFiles
AddReg    = Apo_AddReg

[Apo_CopyFiles]
swapapo.dll

...

[Apo_AddReg]
; Swap Stream effect APO COM registration
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%13%\swapapo.dll
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"

'''
; Swap Stream effect APO registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Copyright",,%Copyright%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MajorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Flags",0x00010001,%APO_FLAG_DEFAULT%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInstances",0x00010001,0xffffffff
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"NumAPOInterfaces",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"APOInterface0",,"{FD7F2B29-24D0-4B5C-B177-592C39F9CA10}"
...

[Strings]
; Driver developers would replace these CLSIDs with those of their own APOs
SWAP_FX_STREAM_CLSID   = "{B48DEA3F-D962-425a-8D9A-9A5BB37A9904}"

...

APO 등록

APO 등록은 가중 계산을 사용하여 엔드포인트에 대한 효과와 동적으로 일치하는 프로세스를 지원하는 데 사용됩니다. 가중 계산에서는 다음 속성 저장소를 사용합니다. 모든 오디오 인터페이스에는 .inf 또는 런타임에 등록된 0개 이상의 엔드포인트 속성 저장소 및 효과 속성 저장소 가 있습니다. 가장 구체적인 엔드포인트 속성 저장소 및 가장 구체적인 효과 속성 저장소는 가장 높은 가중치를 가지며 사용됩니다. 다른 모든 속성 저장소는 무시됩니다.

특이성은 다음과 같이 계산됩니다.

엔드포인트 속성은 가중치를 저장합니다.

  1. 특정 KSNODETYPE을 사용하는 FX
  2. FX with KSNODETYPE_ANY
  3. 특정 KSNODETYPE을 사용하는 MSFX
  4. MSFX 및 KSNODETYPE_ANY

Effects 속성은 가중치를 저장합니다.

  1. 특정 KSNODETYPE을 사용하는 EP
  2. EP with KSNODETYPE_ANY
  3. 특정 KSNODETYPE을 사용하는 MSEP
  4. MSEP 및 KSNODETYPE_ANY

숫자는 0부터 시작하여 순차적으로 증가해야 합니다. MSEP\0, MSEP\1, ..., MSEP\n(예: EP\3)이 없으면 Windows는 EP\n을 찾는 것을 중지하고 EP\4가 있더라도 표시되지 않습니다.

PKEY_FX_Association 값(효과 속성 저장소의 경우) 또는 PKEY_EP_Association(엔드포인트 속성 저장소의 경우)는 KSPINDESCRIPTOR와 비교됩니다. 커널 스트리밍에 의해 노출되는 신호 경로의 하드웨어 끝에 있는 핀 팩터리의 범주 값입니다.

타사 개발자가 래핑할 수 있는 Microsoft 받은 편지함 클래스 드라이버만 MSEP 및 MSFX를 사용해야 합니다. 모든 타사 드라이버는 EP 및 FX를 사용해야 합니다.

APO 노드 형식 호환성

다음 INF 파일 샘플에서는 PKEY_FX_Association 키를 APO와 연결된 GUID로 설정하는 방법을 보여 줍니다.

;; Property Keys
PKEY_FX_Association = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},0"
"

;; Key value pairs
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%

오디오 어댑터는 여러 입력 및 출력을 지원할 수 있으므로 사용자 지정 APO와 호환되는 KS(커널 스트리밍) 노드 형식을 명시적으로 나타내야 합니다. 앞의 INF 파일 조각에서 APO는 %KSNODETYPE_ANY%의 KS 노드 형식과 연결된 것으로 표시됩니다. 이 INF 파일의 뒷부분에서 KSNODETYPE_ANY 다음과 같이 정의됩니다.

[Strings]
;; Define the strings used in MyINF.inf
...
KSNODETYPE_ANY      = "{00000000-0000-0000-0000-000000000000}"
KSNODETYPE_SPEAKER  = "{DFF21CE1-F70F-11D0-B917-00A0C9223196}"
...

KSNODETYPE_ANY 대한 NULL 값은 이 APO가 모든 유형의 KS 노드 형식과 호환된다는 것을 의미합니다. 예를 들어 APO가 KS 노드 형식의 KSNODETYPE_SPEAKER만 호환된다는 것을 나타내기 위해 INF 파일은 다음과 같이 KS 노드 형식 및 APO 연결을 표시합니다.

;; Key value pairs
...
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_SPEAKER%
...

다양한 KS 노드 형식의 GUID 값에 대한 자세한 내용은 Ksmedia.h 헤더 파일을 참조하세요.

APO 로드 오류 문제 해결

다음 정보는 API에 대해 오류를 모니터링하는 방법을 이해하는 데 도움이 됩니다. 이 정보를 사용하여 오디오 그래프에 통합되지 않는 API 문제를 해결할 수 있습니다.

오디오 시스템은 APO 반환 코드를 모니터링하여 APO가 그래프에 성공적으로 통합되는지 여부를 확인합니다. 지정된 메서드 중 하나에서 반환되는 HRESULT 값을 추적하여 반환 코드를 모니터링합니다. 시스템은 그래프에 통합되는 각 SFX, MFX 및 EFX APO에 대해 별도의 오류 수 값을 기본.

오디오 시스템은 다음 네 가지 메서드에서 반환된 HRESULT 값을 모니터링합니다.

  • CoCreateInstance

  • IsInputFormatSupported

  • IsOutputFormatSupported

  • LockForProcess

이러한 메서드 중 하나가 실패 코드를 반환할 때마다 APO에 대한 오류 수 값이 증가합니다. APO가 오디오 그래프에 성공적으로 통합되었음을 나타내는 코드를 반환하면 오류 수가 0으로 다시 설정됩니다. LockForProcess 메서드를 성공적으로 호출하면 APO가 성공적으로 통합되었음을 알 수 있습니다.

특히 CoCreateInstance의 경우 반환된 HRESULT 코드가 오류를 나타낼 수 있는 여러 가지 이유가 있습니다. 세 가지 주요 이유는 다음과 같습니다.

  • 그래프가 보호된 콘텐츠를 실행하고 있으며 APO가 제대로 서명되지 않았습니다.

  • APO가 등록되지 않았습니다.

  • APO의 이름이 변경되거나 변조되었습니다.

또한 SFX, MFX 또는 EFX APO의 오류 수 값이 시스템 지정 제한에 도달하면 PKEY_Endpoint_Disable_SysFx 레지스트리 키를 '1'로 설정하여 SFX, MFX 및 EFX API를 사용하지 않도록 설정합니다. 시스템 지정 제한은 현재 값 10입니다.

Windows 오디오 처리 개체

구성 요소화된 오디오 드라이버 설치 만들기

드라이버 패키지 격리