オーディオ処理オブジェクトの実装

このトピックでは、オーディオ処理オブジェクト (APO) を実装する方法について説明します。 API の一般的な情報については、「オーディオ処理オブジェクトのアーキテクチャ」をご覧ください。

カスタム API の実装

カスタム API はインプロセス COM オブジェクトとして実装されるため、ユーザー モードで実行され、ダイナミック リンク ライブラリ (DLL) にパッケージ化されます。 APO は、信号処理グラフに挿入される場所に基づいて 3 種類あります。

• ストリーム エフェクト (SFX)
• モード エフェクト (MFX)
• エンドポイント エフェクト (EFX)

各論理デバイスは、種類ごとに 1 つの APO に関連付けることができます。 モードとエフェクトについて詳しくは、「オーディオ信号処理モード」をご覧ください。

APO を実装するには、Baseaudioprocessingobject.h ファイルで宣言されている CBaseAudioProcessingObject 基本クラスに基づいてカスタム クラスを作成します。 このアプローチでは、カスタマイズされた APO を作成するために、CBaseAudioProcessingObject 基本クラスに新しい機能を追加する必要があります。 CBaseAudioProcessingObject 基本クラスは、APO に必要な機能の多くを実装します。 これは、3 つの必須インターフェイスのほとんどのメソッドに既定の実装を提供します。 主な例外は、IAudioProcessingObjectRT::APOProcess メソッドです。

カスタム API を実装するには、次の手順を実行します。

1. 目的のオーディオ処理を提供するカスタム APO com オブジェクトを作成します。
2. 必要に応じて、以下を使用してカスタム API を構成するためのユーザー インターフェイスを作成します。
3. API とカスタム ユーザー インターフェイスをインストールして登録する INF ファイルを作成します。

カスタム APO 開発の設計に関する考慮事項

すべてのカスタム API には、以下の一般的な特性が必要です。

• APO には、1 つの入力接続と 1 つの出力接続が必要です。 これらの接続はオーディオ バッファーであり、複数のチャネルを持つことができます。

• APO は、IAudioProcessingObjectRT::APOProcess ルーチンを通じて渡されるオーディオ データのみを変更できます。 APO は、基になる論理デバイス (KS トポロジを含む) の設定を変更することができません。

• API は IUnknown に加えて、以下のインターフェイスを公開する必要があります。

  • IAudioProcessingObject。 初期化や形式ネゴシエーションなどのセットアップ タスクを処理するインターフェイス。

  • IAudioProcessingObjectConfiguration。 構成インターフェイス。

  • IAudioProcessingObjectRT。 オーディオ処理を処理するリアルタイム インターフェイス。 リアルタイム処理スレッドから呼び出すことができます。

  • IAudioSystemEffects。 オーディオ エンジンにシステム エフェクト APO として DLL を認識させるインターフェイス。

• すべての API にリアルタイムのシステム互換性が必要です。 これは、次のことを意味します。

  • リアルタイム インターフェイスのメンバーであるすべてのメソッドは、非ブロッキング メンバーとして実装する必要があります。 ブロック、ページングされたメモリの使用、またはブロッキング システム ルーチンの呼び出しを行ってはなりません。

  • APO によって処理されるすべてのバッファーは、ページング不可能である必要があります。 プロセス パス内のすべてのコードとデータは、ページング不可能である必要があります。

  • API によって、オーディオ処理チェーンに大幅な待機時間が発生することはありません。

• カスタム API は、IAudioProcessingObjectVBR インターフェイスを公開してはなりません。

Note

必要なインターフェイスについて詳しくは、Windows Kits\<ビルド番号>\Include\um フォルダーにある Audioenginebaseapo.h ファイルと Audioenginebaseapo.idl ファイルをご覧ください。

サンプル コードを使用した開発プロセスの高速化

テンプレートとして SYSVAD スワップ APO コード サンプルを使用すると、カスタム APO 開発プロセスを高速化することができます。 スワップ サンプルは、オーディオ処理オブジェクトのいくつかの機能を示すために開発されたサンプルです。 スワップ APO サンプルでは、左側のチャネルを右のチャネルにスワップし、SFX エフェクトと MFX エフェクトの両方を実装します。 プロパティ ダイアログを使用して、チャンネル スワップ オーディオ エフェクトを有効または無効にすることができます。

SYSVAD オーディオ サンプルは、Windows ドライバー サンプル GitHub で入手できます。

Sysvad オーディオ サンプルは、以下の場所で参照できます。

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

GitHub から Sysvad オーディオ サンプルをダウンロードして抽出する

SYSVAD サンプルをダウンロードして開くには、次の手順を実行します。

a. GitHub ツールを使用してサンプルを操作できます。 ユニバーサル ドライバーのサンプルを 1 つの 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 で、File>Open>Project/Solution...を選択し、抽出されたファイルを含むフォルダー (たとえば、C:\DriverSamples\Audio\Sysvad) に移動します。 Sysvad ソリューション ファイルをダブルクリックして開きます。

Visual Studio で、ソリューション エクスプローラーを見つけます。 (まだ開いていない場合は、[表示] メニューから[ソリューション エクスプローラー] を選択します。ソリューション エクスプローラーでは、6 つのプロジェクトを含む 1 つのソリューションを確認できます。

SwapAPO サンプル コード

SYSVAD サンプルには 5 つのプロジェクトがあり、そのうちの 1 つは APO 開発者にとって主な関心事です。

プロジェクト	説明
SwapAPO	サンプル APO のサンプル コード

以下に、Sysvad サンプルの他のプロジェクトについてまとめます。

プロジェクト	説明
TabletAudioSample	代替オーディオ ドライバーのサンプル コード。
KeywordDetectorAdapter	キーワード検出機能アダプターのサンプル コード
EndpointsCommon	一般的なエンドポイントのサンプル コード。

SwapAPO サンプルのプライマリ ヘッダー ファイルは、swapapo.h です。 他の主要なコード要素を以下にまとめます。

ファイル	説明
Swap.cpp	スワップ APO の実装を含む C++ コード。
SwapAPOMFX.cpp	CSwapAPOMFX の実装
SwapAPOSFX.cpp	CSwapAPOSFX の実装
SwapAPODll.cpp	DLL エクスポートの実装。
SwapAPODll.idl	DLL の COM インターフェイスとコクラスの定義。
SwapAPOInterface.idl	スワップ APO 機能のインターフェイスと型の定義。
swapapodll.def	COM は定義をエクスポートします

COM オブジェクト オーディオ処理コードの実装

システムにより提供される APO をラップするには、Baseaudioprocessingobject.h ファイルで宣言されている CBaseAudioProcessingObject 基本クラスに基づいてカスタム クラスを使用します。 このアプローチでは、カスタマイズされた APO を作成するために、CBaseAudioProcessingObject 基本クラスに新しい機能を導入する必要があります。 CBaseAudioProcessingObject 基本クラスは、APO に必要な機能の多くを実装します。 これは、3 つの必須インターフェイスのほとんどのメソッドに既定の実装を提供します。 主な例外は、IAudioProcessingObjectRT::APOProcess メソッドです。

CBaseAudioProcessingObject を使用すると、APO をより簡単に実装することができます。 APO に特別な形式要件がなく、必要な float32 形式で動作する場合、CBaseAudioProcessingObject に含まれるインターフェイス メソッドの既定の実装で十分です。 既定の実装では、IAudioProcessingObject::IsInputFormatSupported、IAudioProcessingObjectRT::APOProcess、ValidateAndCacheConnectionInfo の 3 つのメイン メソッドのみ実装する必要があります。

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. 次の 3 つのメソッドを実装します。

   • IAudioProcessingObject::IsInputFormatSupported。 このメソッドは、オーディオ エンジンとの形式ネゴシエーションを処理します。

   • IAudioProcessingObjectRT::APOProcess。 このメソッドは、カスタム アルゴリズムを使用して信号処理を実行します。

   • ValidateAndCacheConnectionInfo。 このメソッドは、チャネル数、サンプリング レート、サンプル深度、チャネル マスクなどの形式の詳細を格納するためにメモリを割り当てます。

次の 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.
...
}

次のコード例は、ValidateAndCacheConnectionInfo メソッドの実装を示しています。 このメソッドの実際の実装については、「オーディオ処理オブジェクト ドライバーのサンプル」セクションの手順に従ってスワップ サンプルに移動し、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 を呼び出すかの 2 つの方法があります。

この擬似コードは、システム 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 と APO の操作

Visual Studio で API を使用する場合、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 をパッケージ化

独自のオーディオ ドライバーを開発し、システム提供の API をラップまたは交換する場合は、ドライバーと API をインストールするためのドライバー パッケージを提供する必要があります。 Windows 10 の場合、「オーディオ用ユニバーサル Windows ドライバー」をご覧ください。 オーディオ関連のドライバー パッケージは、そこで説明されているポリシーとパッケージ モデルに従う必要があります。

カスタム APO は DLL としてパッケージ化され、構成 UI は別の UWP またはデスクトップ ブリッジ アプリとしてパッケージ化されます。 APO デバイス INF は、関連付けられている INF CopyFile ディレクティブで示されているシステム フォルダーに DLL をコピーします。 API を含む DLL は、INF ファイルに AddReg セクションを含めることで自身を登録する必要があります。

次の段落と INF ファイル フラグメントは、API のコピーと登録に標準 INF ファイルを使用するために必要な変更を示しています。

Sysvad サンプルに含まれる inf ファイルは、SwapApo.dll API の登録方法を示しています。

INF ファイルでの処理モードおよびエフェクト用の APO の登録

レジストリ キーの特定の許容される組み合わせを使用し、特定のモードの 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

これらのサンプルには示されていない有効な組み合わせが 1 つ追加されています。

• PKEY_EFX_ProcessingModes_Supported_For_Streaming を持つ PKEY_FX_EndpointEffectClsid

SYSVAD タブレット マルチモード ストリーミング エフェクト APO INF サンプル

このサンプルでは、SYSVAD タブレット 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 登録では、コンポーネント化されたオーディオ ドライバー モデルが使用されます。 オーディオ コンポーネント化を使用すると、よりスムーズで信頼性の高いインストール エクスペリエンスが実現され、コンポーネントのサービスがサポートされます。 詳細については、「コンポーネント化されたオーディオ ドライバーのインストールの作成」を参照してください。

次のコード例は、パブリック ComponentizedAudioSampleExtension.inf および ComponentizedApoSample.inf から抽出されています。 GitHub (https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad) で入手できる SYSVAD オーディオ サンプルをご覧ください。

オーディオ エンジンへの APO の登録は、新しく作成された APO デバイスを使用して行われます。 オーディオ エンジンが新しい APO デバイスを使用するには、オーディオ デバイスの PNP の子 (オーディオ エンドポイントの兄弟) である必要があります。 新しいコンポーネント化された APO 設計では、APO をグローバルに登録し、複数の異なるドライバーで使用することはできません。 ドライバーごとに独自の APO を登録する必要があります。

APO のインストールは 2 つの部分で行われます。 まず、ドライバー拡張機能 INF によって APO コンポーネントがシステムに追加されます。

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

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

この APO コンポーネントは、2 番目の部分である APO INF のインストールを SYSVAD サンプルでトリガーします。これは ComponentizedApoSample.inf で行われます。 この INF ファイルは、APO コンポーネント専用です。 コンポーネント クラスを AudioProcessingObject として指定し、CLSID 登録とオーディオ エンジンへの登録のすべての APO プロパティを追加します。

Note

示された INF ファイル サンプルでは、HKR レジストリ キーを使用することにより、ドライバー パッケージの分離がサポートされます。 Windows 11 バージョン 22000 より前のサンプルでは、HKR ではなく CLSID 登録の永続的な値を格納するために HKCR が使用されていました。 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 登録 (HKCR) からデバイスの相対 HKR COM 登録に切り替えて COM クラス GUID を変更する場合に必要となります。 このアプローチにより、新しい 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} が使用されています。 この GUID を共同作成すると、IAudioProcessingObject インターフェイスを実装して KSPROPSETID_AudioEffectsDiscovery プロパティ セット経由で基になるドライバーにクエリを実行する MsApoFxProxy.dll のクラスがインスタンス化されます。

この 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] セクションを示しています。 このセクションでは、スワップ ストリーム GUID を COM に登録し、スワップ ストリーム APO エフェクトを登録します。 [Apo_CopyFiles] セクションの DestinationDirs は 13 であり、swapapo.dll を Driverstore にコピーします。 詳しくは、「ドライバー パッケージの分離」の「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 経由または実行時に登録された 0 個以上のエンドポイント プロパティ ストアとエフェクト プロパティ ストアがあります。 最も具体的なエンドポイント プロパティ ストアと最も具体的な効果のプロパティ ストアは、重みが最も大きくなっており、使用されます。 その他のプロパティ ストアはすべて無視されます。

特定性は、次のように計算されます。

エンドポイント プロパティに重み付けが格納される

1. 特定の KSNODETYPE を持つ FX
2. KSNODETYPE_ANY を持つ FX
3. 特定の KSNODETYPE を持つ MSFX
4. KSNODETYPE_ANY を持つ MSFX

Effects プロパティには重み付けが格納されます

1. 特定の KSNODETYPE を持つ EP
2. KSNODETYPE_ANY を持つ EP
3. 特定の KSNODETYPE を持つ MSEP
4. KSNODETYPE_ANY を持つ MSEP

数値は 0 から始まり、順番に増やす必要があります: MSEP\0、MSEP\1、...、MESEP\n(たとえば) EP\3 がない場合、Windows は EP\n の検索を停止します。EP\4 は、存在する場合でも表示されません

PKEY_FX_Association (エフェクト プロパティ ストアの場合) または PKEY_EP_Association (エンドポイント プロパティ ストアの場合) の値が、KSPINDESCRIPTOR と比較されます。カーネル ストリーミングによって公開される、信号パスのハードウェア末尾にあるピン ファクトリのカテゴリ値。

マイクロソフト受信トレイ クラス ドライバー (サード パーティの開発者がラップ可能) のみが MSEP および MSFX を使用する必要があります。すべてのサード パーティ製ドライバーは EP と FX を使用する必要があります。

APO ノードの種類の互換性

次の INF ファイル サンプルは、APO に関連付けられている GUID に PKEY_FX_Association キーを設定する方法を示しています。

;; 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 リターン コードを監視して、API がグラフに正常に組み込まれているかどうかを判断します。 指定されたメソッドのいずれかによって返される HRESULT 値を追跡することにより、リターン コードを監視します。 システムには、グラフに組み込まれている SFX、MFX、EFX APO ごとに個別の障害数の値が保持されます。

オーディオ システムは、次の 4 つのメソッドから返された HRESULT 値を監視します。

• Cocreateinstance

• IsInputFormatSupported

• IsOutputFormatSupported

• LockForProcess

これらのメソッドのいずれかがエラー コードを返すたびに、APO のエラー カウント値がインクリメントされます。 APO がオーディオ グラフに正常に組み込まれたことを示すコードを返すと、エラー カウントが 0 にリセットされます。 LockForProcess メソッドの正常な呼び出しは、APO が正常に組み込まれたことを示しています。

特に CoCreateInstance の場合、返された HRESULT コードがエラーを示す理由は多数あります。 3 つの主な理由は次のとおりです。

• グラフは保護されたコンテンツを実行しており、APO が正しく署名されていません。

• APO が登録されていません。

• APO の名前が変更または改ざんされました。

また、SFX、MFX、EFX の APO のエラー数の値がシステム指定の制限に達した場合、PKEY_Endpoint_Disable_SysFx レジストリ キーを '1' に設定することにより、SFX、MFX、EFX の APO が無効になります。 現在、システムにより指定された制限値は 10 です。

関連トピック

Windows オーディオ処理オブジェクト

コンポーネント化されたオーディオ ドライバーのインストールの作成

ドライバー パッケージの分離