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

[アーティクル]
04/01/2024

このトピックでは、オーディオ処理オブジェクト (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 を実装するには、次の手順を実行します。

目的のオーディオ処理を提供するカスタム APO com オブジェクトを作成します。
必要に応じて、以下を使用してカスタム API を構成するためのユーザーインターフェイスを作成します。
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 を開発するには、次の手順を実行します。

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 によって実行される信号処理とは異なるため、それぞれに別個のクラスを作成する必要があります。
次の 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 個以上のエンドポイントプロパティストアとエフェクトプロパティストアがあります。最も具体的なエンドポイントプロパティストアと最も具体的な効果のプロパティストアは、重みが最も大きくなっており、使用されます。その他のプロパティストアはすべて無視されます。

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

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

特定の KSNODETYPE を持つ FX
KSNODETYPE_ANY を持つ FX
特定の KSNODETYPE を持つ MSFX
KSNODETYPE_ANY を持つ MSFX

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

特定の KSNODETYPE を持つ EP
KSNODETYPE_ANY を持つ EP
特定の KSNODETYPE を持つ MSEP
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 オーディオ処理オブジェクト

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

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

次の方法で共有

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

カスタム API の実装

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

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

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

Visual Studio でドライバーソリューションファイルを開く

SwapAPO サンプルコード

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

システムにより提供された API の置き換え

Visual Studio と APO の操作

CRT へのリンク

埋め込みマニフェストの使用を無効化

ドライバーを使用して APO をパッケージ化

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

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

コンポーネント化された APO のインストール

新しい APO バージョンがリリースされたときの CLSID の更新

HKCR から HKR への移行時の CLSID の更新要件

Bluetooth オーディオサンプル APO INF サンプル

APO INF オーディオサンプル

カスタム APO と CLSID APO INF サンプルの定義

APO エフェクト登録のサンプル

APO の登録

APO ノードの種類の互換性

APO 読み込みエラーのトラブルシューティング

フィードバック

その他のリソース

次の方法で共有

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

カスタム API の実装

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

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

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

Visual Studio でドライバー ソリューション ファイルを開く

SwapAPO サンプル コード

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

システムにより提供された API の置き換え

Visual Studio と APO の操作

CRT へのリンク

埋め込みマニフェストの使用を無効化

ドライバーを使用して APO をパッケージ化

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

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

コンポーネント化された APO のインストール

新しい APO バージョンがリリースされたときの CLSID の更新

HKCR から HKR への移行時の CLSID の更新要件

Bluetooth オーディオ サンプル APO INF サンプル

APO INF オーディオ サンプル

カスタム APO と CLSID APO INF サンプルの定義

APO エフェクト登録のサンプル

APO の登録

APO ノードの種類の互換性

APO 読み込みエラーのトラブルシューティング

関連トピック

フィードバック

その他のリソース

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

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

Visual Studio でドライバーソリューションファイルを開く

SwapAPO サンプルコード

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

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

Bluetooth オーディオサンプル APO INF サンプル

APO INF オーディオサンプル