實作音訊處理物件

發行項
05/13/2024

本主題描述如何實作音訊處理物件（APO）。如需 APO 的一般資訊，請參閱音訊處理物件架構。

實作自定義 API

自定義 APO 會實作為同進程 COM 物件，因此會在使用者模式中執行，並封裝在動態連結庫（DLL）中。 APO 有三種類型，根據它們插入訊號處理圖形的位置。

串流效果（SFX）
模式效果（MFX）
端點效果（EFX）

每個邏輯裝置都可以與每種類型的一個 APO 相關聯。如需模式和效果的詳細資訊，請參閱音訊號處理模式。

您可以在 CBaseAudioProcessingObject 基類上以自定義類別為基礎來實作 APO，該基類是在 Baseaudioprocessingobject.h 檔案中宣告。此方法牽涉到將新功能新增至 CBaseAudioProcessingObject 基類，以建立自定義的 APO。 CBaseAudioProcessingObject 基類會實作 APO 所需的許多功能。它提供三個必要介面中大部分方法的默認實作。主要例外狀況是 IAudioProcessingObjectRT：：APOProcess 方法。

執行下列步驟來實作您的自定義 API。

建立自定義 APO com 物件，以提供所需的音訊處理。
選擇性地建立使用者介面，以使用來設定自定義 API。
建立 INF 檔案，以安裝和註冊 APOs 和自定義使用者介面。

自定義 APO 開發的設計考慮

所有自訂 APO 都必須具有下列一般特性：

APO 必須有一個輸入和輸出連線。這些連線是音訊緩衝區，而且可以有多個通道。
APO 只能修改透過其 IAudioProcessingObjectRT：：APOProcess 例程傳遞給它的音訊數據。 APO 無法變更基礎邏輯裝置的設定，包括其 KS 拓撲。
除了 IUnknown 之外，APOs 還必須公開下列介面：
- IAudioProcessingObject。處理設定工作的介面，例如初始化和格式交涉。
- IAudioProcessingObjectConfiguration。組態介面。
- IAudioProcessingObjectRT。處理音訊處理的即時介面。您可以從即時處理線程呼叫它。
- IAudioSystemEffects。讓音訊引擎將 DLL 辨識為系統效果 APO 的介面。
所有 APO 都必須具有即時系統相容性。這表示：
- 屬於即時介面成員的所有方法都必須實作為非封鎖成員。它們不得封鎖、使用分頁記憶體，或呼叫任何封鎖系統例程。
- APO 處理的所有緩衝區都必須不可分頁。進程路徑中的所有程式代碼和數據都必須不可分頁。
- ADO 不應在音訊處理鏈結中引入顯著的延遲。
自定義 API 不得公開 IAudioProcessingObjectVBR 介面。

注意

如需必要介面的詳細資訊，請參閱 Windows Kits\<build number>\Include\um 資料夾中的 Audioenginebaseapo.h 和 Audioenginebaseapo.idl 檔案。

使用範例程式代碼加速開發程式

使用SYSVAD交換 APO 程式代碼範例作為範本，可以加速自訂 APO 開發程式。 Swap 範例是開發來說明音訊處理物件的一些功能所開發的範例。交換 APO 範例會將左通道與右通道交換，並實作 SFX 和 MFX 效果。您可以使用 [屬性] 對話框來啟用和停用通道交換音訊效果。

Windows 驅動程式範例 GitHub 上提供 SYSVAD 音訊範例。

您可以在您可以瀏覽 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 中找出方案總管。（如果尚未開啟，請選擇從 [檢視] 功能表方案總管。在方案總管中，您可以看到一個有六個項目的解決方案。

SwapAPO 範例程序代碼

SYSVAD 範例中有五個專案，其中一個專案對 APO 開發人員有主要興趣。

計畫	說明
SwapAPO	範例 APO 的程式代碼範例

Sysvad 範例中的其他專案摘要如下。

計畫	說明
TabletAudioSample	替代音訊驅動程式的範例程序代碼。
KeywordDetectorAdapter	關鍵詞偵測器配接器的範例程序代碼
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 物件音訊處理程序代碼

您可以包裝系統提供的 APO，方法是在 CBaseAudioProcessingObject 基類上以自定義類別為基礎，該基類是在 Baseaudioprocessingobject.h 檔案中宣告。此方法牽涉到 將新功能引入 CBaseAudioProcessingObject 基類，以建立自定義的 APO。 CBaseAudioProcessingObject 基類會實作 APO 所需的許多功能。它提供三個必要介面中大部分方法的默認實作。主要例外狀況是 IAudioProcessingObjectRT：：APOProcess 方法。

藉由使用 CBaseAudioProcessingObject，您可以更輕鬆地實作 APO。如果 APO 沒有特殊格式需求，而且會以必要的 float32 格式運作，則 CBaseAudioProcessingObject 中包含的介面方法的預設實作應該就已足夠。假設預設實作，必須實作三個主要方法：IAudioProcessingObject：：IsInputFormatSupported、IAudioProcessingObjectRT：：APOProcess 和 ValidateAndCache 連線 ionInfo。

若要根據 CBaseAudioProcessingObject 類別開發 API，請執行下列步驟：

建立繼承自 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 所執行的訊號處理不同，因此您必須為每個專案建立個別的類別。
實作下列三種方法：
- 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 檔案中詳細說明。

取代系統提供的APOs

實作 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 元件實作下列介面和方法：

IAudioProcessingObject。這個介面的必要方法是： Initialize 和 IsInputFormatSupported。
IAudioProcessingObjectConfiguration。此介面的必要方法是：LockForProcess 和 UnlockForProcess
IAudioProcessingObjectRT。這個介面 的必要方法是 APOProcess ，它是實作 DSP 演算法的方法。
IAudioSystemEffects。這個介面可讓音訊引擎將 DLL 辨識為 APO。

使用 Visual Studio 和 APOS

在 Visual Studio 中使用 APOs 時，請針對每個 APO 專案執行這些工作。

CRT 的連結

以 Windows 10 為目標的驅動程式應該動態連結至通用 CRT。

如果您需要支援 Windows 8,1，請在 C/C++、程式代碼產生中設定專案屬性，以啟用靜態連結。將 [運行時間連結庫] 設定為 /MT 以用於發行組建或 偵錯組建的 /MTd 。這項變更是因為對於驅動程式而言，很難轉散發 MSVCRT<n>.dll 二進位檔。解決方案是靜態連結libcmt.dll。如需詳細資訊，請參閱 /MD、/MT、/LD （使用執行時間連結庫）。

停用使用內嵌指令清單

設定 APO 專案的項目屬性，以停用使用內嵌指令清單。選取 [ 指令清單工具]、 [輸入和輸出]。然後將 [內嵌指令清單] 從預設值 [是 ] 變更為 [否]。如果您有內嵌指令清單，這會觸發使用受保護的環境內禁止的特定 API。這表示您的 APO 會以 DisableProtectedAudioDG=1 執行，但移除此測試金鑰時，您的 APO 將無法載入，即使它是 WHQL 簽署也一樣。

使用驅動程式封裝您的 APO

當您開發自己的音訊驅動程式並包裝或取代系統提供的 APOs 時，您必須提供驅動程式套件來安裝驅動程式和 APOs。針對 Windows 10，請參閱適用於音訊的通用 Windows 驅動程式。您的音訊相關驅動程式套件應遵循該處詳述的原則和封裝模型。

自定義 APO 會封裝為 DLL，而且任何組態 UI 會封裝為個別的 UWP 或傳統型橋接器應用程式。 APO 裝置 INF 會將 DLL 複製到相關 INF CopyFile 指示詞中所指示的系統資料夾。包含 APOs 的 DLL 必須藉由在 INF 檔案中包含 AddReg 區段來註冊本身。

下列段落和 INF 檔案片段會顯示使用標準 INF 檔案來複製和註冊 APOs 所需的修改。

Sysvad 範例隨附的 inf 檔案說明如何註冊SwapApo.dll APOs。

在 INF 檔案中註冊處理模式和效果的 API

您可以使用特定允許的登錄機碼組合來註冊特定模式的 API。如需哪些效果可用的詳細資訊，以及有關APOS的一般資訊，請參閱音訊處理物件架構。

如需每個 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 檔案範例示範如何註冊特定模式的音訊處理物件（APOS）。它們說明此清單中可用的可能組合。

使用 PKEY_SFX_ProcessingModes_Supported_For_Streaming PKEY_FX_StreamEffectClsid
PKEY_FX_ModeEffectClsid PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
沒有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 範例

此範例顯示使用SVAD平板電腦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_FX_ModeEffectClsid PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

[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 會使用元件化音訊驅動程式模型。使用音訊元件化可建立更順暢且更可靠的安裝體驗，並更支援元件服務。如需詳細資訊，請參閱建立元件化音訊驅動程序安裝。

下列範例程式代碼會從公用 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 來儲存 CLSID 註冊的永續性值，而不是 HKR。從 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 註冊（HKCR）切換至相對 HKR COM 註冊的裝置，以變更 COM 類別 GUID 時，這是一項需求。此方法可減少新 COM 物件無法正確註冊且無法載入的可能性。

藍牙音訊範例 APO INF 範例

此範例說明系統效果的這種組合：

使用 PKEY_SFX_ProcessingModes_Supported_For_Streaming PKEY_FX_StreamEffectClsid
PKEY_FX_ModeEffectClsid PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

此範例程式代碼支援藍牙免手和立體聲裝置。

; 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_FX_ModeEffectClsid PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
沒有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 會在 MsApoFxProxy.dll 中具現化類別，以實作 IAudioProcessingObject 介面，並透過KSPROPSETID_AudioEffectsDiscovery屬性集查詢基礎驅動程式。

此 INF 檔案範例顯示 [BthHfAud] 區段，該區段會從 wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave] 提取 [MsApoFxProxy.Registration]，然後註冊PKEY_FX_EndpointEffectClsid作為MsApoFxProxy.dll的已知 CLSID。

此 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] 區段的 DestinationDirs 為 13，會將swapapo.dll複製到 Driverstore。如需詳細資訊，請參閱驅動程式套件隔離中的。

如需 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 或運行時間註冊的效果屬性存放區 。最特定的端點屬性存放區和最特定的效果屬性存放區具有最高的權數並使用。所有其他屬性存放區都會被忽略。

具體性計算如下：

端點屬性儲存加權

具有特定 KSNODETYPE 的 FX
FX with KSNODETYPE_ANY
具有特定 KSNODETYPE 的 MSFX
MSFX 搭配KSNODETYPE_ANY

Effects 屬性會儲存加權

具有特定 KSNODETYPE 的 EP
具有KSNODETYPE_ANY的 EP
具有特定 KSNODETYPE 的 MSEP
具有 KSNODETYPE_ANY 的 MSEP

數字必須從 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 只與KSNODETYPE_SPEAKER的 KS 節點類型相容，INF 檔案會顯示 KS 節點類型和 APO 關聯，如下所示：

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

如需不同 KS 節點類型之 GUID 值的詳細資訊，請參閱 Ksmedia.h 頭檔。

針對 APO 載入失敗進行疑難解答

下列資訊可協助您瞭解如何監視APOs的失敗。您可以使用這項資訊來針對無法併入音訊圖表的 API 進行疑難解答。

音訊系統會監視 APO 傳回碼，以判斷 APO 是否成功併入圖形。它會追蹤任何一個指定方法所傳回的 HRESULT 值，藉此監視傳回碼。系統會針對要併入圖表的每個SFX、MFX和EFX APO維護個別的失敗計數值。

音訊系統會從下列四種方法監視傳回的 HRESULT 值。

CoCreateInstance
IsInputFormatSupported
IsOutputFormatSupported
LockForProcess

每次其中一個方法傳回失敗碼時，APO 的失敗計數值就會遞增。當 APO 傳回表示已成功併入音訊圖形的程式代碼時，失敗計數會重設為零。成功呼叫 LockForProcess 方法表示已成功併入 APO。

特別是針對 CoCreateInstance ，傳回的 HRESULT 程式代碼可能會指出失敗的原因有很多。三個主要原因如下：

圖表正在執行受保護的內容，且 APO 未正確簽署。
APO 未註冊。
APO 已重新命名或遭到竄改。

此外，如果 SFX、MFX 或 EFX APO 的失敗計數值達到系統指定的限制，SFX、MFX 和 EFX APOs 會藉由將PKEY_Endpoint_Disable_SysFx登錄機碼設定為『1』來停用。系統指定的限制目前為 10。

Windows 音訊處理物件

建立元件化音訊驅動程式安裝

驅動程式套件隔離

共用方式為

實作音訊處理物件

實作自定義 API

自定義 APO 開發的設計考慮

使用範例程式代碼加速開發程式

從 GitHub 下載並擷取 Sysvad 音訊範例

在 Visual Studio 中開啟驅動程式解決方案

SwapAPO 範例程序代碼

實作 COM 物件音訊處理程序代碼

取代系統提供的APOs

使用 Visual Studio 和 APOS

CRT 的連結

停用使用內嵌指令清單

使用驅動程式封裝您的 APO

在 INF 檔案中註冊處理模式和效果的 API

SYSVAD 平板電腦多重模式串流效果 APO INF 範例

元件化 APO 安裝

當發行新的 APO 版本時，更新 CLSID

從 HKCR 移至 HKR 時更新 CLSID 的需求

藍牙音訊範例 APO INF 範例

APO INF 音訊範例

定義自定義 APO 和 CLSID APO INF 範例

範例 APO 效果註冊

APO 註冊

APO 節點類型相容性

針對 APO 載入失敗進行疑難解答

意見反應

其他資源

共用方式為

實作音訊處理物件

實作自定義 API

自定義 APO 開發的設計考慮

使用範例程式代碼加速開發程式

從 GitHub 下載並擷取 Sysvad 音訊範例

在 Visual Studio 中開啟驅動程式解決方案

SwapAPO 範例程序代碼

實作 COM 物件音訊處理程序代碼

取代系統提供的APOs

使用 Visual Studio 和 APOS

CRT 的連結

停用使用內嵌指令清單

使用驅動程式封裝您的 APO

在 INF 檔案中註冊處理模式和效果的 API

SYSVAD 平板電腦多重模式串流效果 APO INF 範例

元件化 APO 安裝

當發行新的 APO 版本時，更新 CLSID

從 HKCR 移至 HKR 時更新 CLSID 的需求

藍牙 音訊範例 APO INF 範例

APO INF 音訊範例

定義自定義 APO 和 CLSID APO INF 範例

範例 APO 效果註冊

APO 註冊

APO 節點類型相容性

針對 APO 載入失敗進行疑難解答

相關主題

意見反應

其他資源

藍牙音訊範例 APO INF 範例