Реализация объектов обработки звука

Статья
05/05/2023

В этом разделе описывается реализация объекта обработки звука (APO). Общие сведения об API см. в разделе "Архитектура объектов обработки звука".

Реализация пользовательских API

Пользовательские API реализованы как объекты COM процесса, поэтому они выполняются в пользовательском режиме и упаковываются в библиотеку динамической компоновки (DLL). Существует три типа APO на основе того, где они вставляются в граф обработки сигналов.

Потоковые эффекты (SFX)
Эффекты режима (MFX)
Эффекты конечных точек (EFX)

Каждое логическое устройство может быть связано с одним APO каждого типа. Дополнительные сведения о режимах и эффектах см. в разделе "Режимы обработки звуковых сигналов".

Вы можете реализовать APO, базируя пользовательский класс на базовом классе CBaseAudioProcessingObject, который объявлен в файле Baseaudioprocessingobject.h. Этот подход включает добавление новых функций в базовый класс CBaseAudioProcessingObject для создания настраиваемого APO. Базовый класс CBaseAudioProcessingObject реализует большую часть функциональных возможностей, необходимых APO. Он предоставляет реализации по умолчанию для большинства методов в трех обязательных интерфейсах. Основным исключением является метод IAudioProcessingObjectRT::APOProcess.

Выполните следующие действия, чтобы реализовать пользовательские API.

Создайте пользовательские объекты APO com, чтобы обеспечить необходимую обработку звука.
При необходимости создайте пользовательский интерфейс для настройки пользовательских API с помощью a.
Создайте INF-файл для установки и регистрации API и пользовательского пользовательского интерфейса.

Использование примера кода для ускорения процесса разработки

Использование примера кода APO для замены SYSVAD в качестве шаблона может ускорить процесс разработки пользовательского APO. Пример замены — это пример, разработанный для иллюстрации некоторых функций объектов обработки звука. Пример APO swap переключает левый канал на правый канал и реализует эффекты SFX и MFX. Вы можете включить и отключить звуковые эффекты канала, используя диалоговое окно свойств.

Образец звука SYSVAD доступен на сайте GitHub для примеров драйверов Windows.

Здесь можно просмотреть пример звука Sysvad:

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

Скачайте и извлеките образец звука Sysvad из GitHub

Выполните следующие действия, чтобы скачать и открыть пример 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 выберите >файл open>Project/Solution... и перейдите в папку, содержащую извлеченные файлы (например, C:\DriverSamples\Audio\Sysvad). Дважды щелкните файл решения Sysvad , чтобы открыть его.

В Visual Studio найдите Обозреватель решений. (Если это еще не открыто, выберите Обозреватель решений в меню "Вид".) В Обозреватель решений можно увидеть одно решение с шестью проектами.

Пример кода SwapAPO

Существует пять проектов в примере SYSVAD, один из которых является основным интересом для разработчика APO.

Проект	Description
SwapAPO	Пример кода для примера APO

Ниже приведены другие проекты в примере Sysvad.

Проект	Description
TabletAudioSample	Пример кода для альтернативного звукового драйвера.
KeywordDetectorAdapter	Пример кода для адаптера детектора ключевое слово
EndpointsCommon	Пример кода для распространенных конечных точек.

Основными файлами заголовков для примера SwapAPO является swapapo.h. Ниже приведены другие основные элементы кода.

Файл	Description
Swap.cpp	Код C++, содержащий реализацию APO замены.
SwapAPOMFX.cpp	Реализация CSwapAPOMFX
SwapAPOSFX.cpp	Реализация CSwapAPOSFX
SwapAPODll.cpp	Реализация экспорта БИБЛИОТЕК DLL.
SwapAPODll.idl	Определение com-интерфейсов и соклассов для библиотеки DLL.
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.

Чтобы разработать API на основе класса CBaseAudioProcessingObject , выполните следующие действия:

Создайте класс, наследующий от CBaseAudioProcessingObject.

В следующем примере кода C++ показано создание класса, наследуемого от CBaseAudioProcessingObject. Для фактической реализации этой концепции следуйте инструкциям в разделе "Пример драйвера объектов обработки звука", чтобы перейти к примеру буфера, а затем перейдите к файлу Swapapo.h .
```
// Custom APO class - SFX
Class MyCustomAPOSFX: public CBaseAudioProcessingObject
{
 public:
//Code for custom class goes here
...
};
```
Обратите внимание , что обработка сигналов, выполняемая SFX APO, отличается от обработки сигналов, выполняемой MFX или APO EFX, необходимо создать отдельные классы для каждого.
Реализуйте следующие три метода:
- IAudioProcessingObject::IsInputFormatSupported. Этот метод обрабатывает согласование формата с звуковой подсистемой.
- IAudioProcessingObjectRT::APOProcess. Этот метод использует настраиваемый алгоритм для обработки сигналов.
- ValidateAndCache Подключение ionInfo. Этот метод выделяет память для хранения сведений о формате, например подсчета каналов, частоты выборки, глубины выборки и маски канала.

В следующем примере кода C++ показана реализация метода APOProcess для примера класса, созданного на шаге 1. Для фактической реализации этой концепции следуйте инструкциям в разделе "Пример драйвера объектов обработки звука", чтобы перейти к примеру буфера, а затем перейдите к файлу 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-интерфейсов для замены системных, необходимо использовать те же имена в следующем списке для интерфейсов и методов. Некоторые интерфейсы имеют больше методов в дополнение к перечисленным необходимым методам. Ознакомьтесь со справочными страницами для этих интерфейсов, чтобы определить, следует ли реализовать все методы или только необходимые.

Остальные шаги реализации совпадают с пользовательским APO.

Реализуйте следующие интерфейсы и методы для com-компонента:

IAudioProcessingObject. Необходимые методы для этого интерфейса: Initialize and IsInputFormatSupported.
IAudioProcessingObjectConfiguration. Необходимые методы для этого интерфейса: LockForProcess и UnlockForProcess
IAudioProcessingObjectRT. Обязательный метод для этого интерфейса — APOProcess , и это метод, реализующий алгоритм DSP.
IAudioSystemEffects. Этот интерфейс делает звуковой подсистемой распознавание библиотеки DLL как APO.

Работа с Visual Studio и API

При работе с API в Visual Studio выполните эти задачи для каждого проекта 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, и любой пользовательский интерфейс конфигурации упаковывается в виде отдельного приложения UWP или мост для классических приложений. INF-файл устройства APO копирует библиотеки DLL в системные папки, указанные в связанной директиве INF CopyFile. Библиотека DLL, содержащая API-интерфейсы, должна зарегистрировать себя, включив раздел AddReg в INF-файл.

В следующих абзацах и фрагментах INF-файла отображаются изменения, необходимые для копирования и регистрации API-интерфейсов с помощью стандартного INF-файла.

Inf-файлы, включенные в пример Sysvad, показывают, как зарегистрированы SwapApo.dll API.

Регистрация API для режимов обработки и эффектов в INF-файле

Вы можете зарегистрировать API для определенных режимов с помощью определенных допустимых сочетаний разделов реестра. Дополнительные сведения о том, какие эффекты доступны и общие сведения об API, см. в разделе "Архитектура объектов обработки звука".

Дополнительные сведения о каждом из параметров INF-файла APO см. в этих справочных разделах.

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_FX_StreamEffectClsid с PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid с PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_ModeEffectClsid без PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_EndpointEffectClsid без PKEY_EFX_ProcessingModes_Supported_For_Streaming

Существует одна дополнительная допустимая комбинация, которая не показана в этих примерах.

PKEY_FX_EndpointEffectClsid с PKEY_EFX_ProcessingModes_Supported_For_Streaming

Пример APO INF для планшета SYSVAD Для планшета с несколькими режимами

В этом примере показан эффект потоковой передачи с несколькими режимами, зарегистрированный с помощью записей AddReg в INF-файле SYSVAD Tablet INF.

Этот пример кода получен из примера звука SYSVAD и доступен на сайте GitHub: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

В этом примере показана эта комбинация системных эффектов:

PKEY_FX_StreamEffectClsid с PKEY_SFX_ProcessingModes_Supported_For_Streaming
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. См. пример звука SYSVAD, доступный на сайте GitHub: 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 активирует вторую часть, установку INF APO, в примере SYSVAD это делается в ComponentizedApoSample.inf. Этот INF-файл предназначен для компонента APO. Он задает класс компонента как AudioProcessingObject и добавляет все свойства APO для регистрации CLSID и регистрации в звуковом обработчике.

Примечание.

В примерах INF-файла показана изоляция пакета драйвера с помощью раздела реестра HKR. До Windows 11 версии 22000 примеры использовали HKCR для хранения постоянных значений для регистрации CLSID вместо HKR. Регистрация APO поддерживается с помощью HKR, начиная с Windows 10, выпуск 1809. Дополнительные сведения см. в разделе "Использование универсального 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 диспетчер устройств.

Обновления к CLSID при выпуске новой версии APO

При выпуске новой версии APO рекомендуется обновить CLSID класса COM. Используйте такие средства, как GUIDGEN, чтобы создать новые идентификаторы GUID.

Требование обновить CLSID при переходе из HKCR в HKR

Это требование при переходе с глобальных регистраций COM (HKCR) на относительные регистрации COM устройства для изменения GUID класса COM. Этот подход снижает вероятность того, что новые COM-объекты не будут зарегистрированы должным образом и не будут загружены.

Пример APO APO для Bluetooth Audio

В этом примере показана эта комбинация системных эффектов:

PKEY_FX_StreamEffectClsid с PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid с PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

Этот пример кода поддерживает устройства 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_FX_StreamEffectClsid с PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid с PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_EndpointEffectClsid без PKEY_EFX_ProcessingModes_Supported_For_Streaming

[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

В этом примере показано, как определить собственный CLSID для пользовательского APO. В этом примере используется CLSID MsApoFxProxy {889C03C8-ABAD-4004-BF0A-BC7BB825E166}. CoCreate-ing этот GUID создает экземпляр класса в MsApoFxProxy.dll который реализует интерфейсы IAudioProcessingObject и запрашивает базовый драйвер через набор свойств KSPROPSETID_AudioEffectsDiscovery.

В этом примере INF-файла показан раздел [BthHfAud], который извлекает [MsApoFxProxy.Registration] из wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], который затем регистрирует PKEY_FX_EndpointEffectClsid как известный CLSID для MsApoFxProxy.dll.

Этот пример INF-файла также иллюстрирует использование этого сочетания системных эффектов:

PKEY_FX_EndpointEffectClsid без PKEY_EFX_ProcessingModes_Supported_For_Streaming

;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

В этом примере показан раздел [Apo_AddReg] из sysvad ComponentizedApoSample.inx. В этом разделе регистрируется GUID потока обмена с помощью COM и регистрируется эффект APO потока обмена. В разделе [Apo_CopyFiles] есть ЦелевойDirs 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-файл или во время выполнения. Наиболее конкретное хранилище свойств конечной точки и наиболее конкретное хранилище свойств эффектов имеют самый высокий вес и используются. Все остальные хранилища свойств игнорируются.

Специфика вычисляется следующим образом:

Свойство Endpoint сохраняет весовую конечную точку

FX с определенным KSNODETYPE
FX с KSNODETYPE_ANY
MSFX с определенным KSNODETYPE
MSFX с KSNODETYPE_ANY

Свойства Effects хранят весовые значения

EP с определенным KSNODETYPE
EP с KSNODETYPE_ANY
MSEP с определенным KSNODETYPE
MSEP с KSNODETYPE_ANY

Числа должны начинаться с 0 и увеличиваться последовательно: MSEP\0, MSEP\1, ..., MSEP\n Если (например) EP\3 отсутствует, Windows перестанет искать EP\n и не увидит EP\4, даже если он существует

Значение PKEY_FX_Association (для хранилищ свойств эффектов) или PKEY_EP_Association (для хранилищ свойств конечной точки) сравнивается с KSPINDESCRIPTOR. Значение категории для фабрики закреплений на аппаратном конце пути сигнала, которое предоставляется потоковой передачей ядра.

Использовать MSEP и MSFX должны только драйверы классов Microsoft (которые могут быть упакованы сторонним разработчиком); Все сторонние драйверы должны использовать EP и FX.

Совместимость типов узлов APO

В следующем примере INF-файла показана настройка ключа PKEY_FX_Association guid, связанного с APO.

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

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

Так как звуковой адаптер поддерживает несколько входных и выходных данных, необходимо явно указать тип узла потоковой передачи ядра (KS), с которым совместим настраиваемый APO. В предыдущем фрагменте INF-файла объект APO отображается для сопоставления с типом узла KS %KSNODETYPE_ANY%. Далее в этом 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}"
...

Значение NULL для KSNODETYPE_ANY означает, что этот APO совместим с любым типом узла KS. Чтобы указать, например, что APO совместим только с типом узла KS KSNODETYPE_SPEAKER, INF-файл будет отображать тип узла KS и связь APO следующим образом:

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

Дополнительные сведения о значениях GUID для различных типов узлов KS см. в файле заголовка Ksmedia.h.

Устранение неполадок загрузки APO

Ниже приведены сведения, которые помогут вам понять, как выполняется мониторинг сбоев для API. Эти сведения можно использовать для устранения неполадок с API, которые не вошли в аудиограф.

Звуковая система отслеживает коды возврата APO, чтобы определить, успешно ли api-интерфейсы включены в граф. Он отслеживает коды возврата путем отслеживания значений HRESULT, возвращаемых любым из назначенных методов. Система поддерживает отдельное значение счетчика сбоев для каждого SFX, MFX и EFX APO, который включается в граф.

Звуковая система отслеживает возвращаемые значения HRESULT из следующих четырех методов.

CoCreateInstance
IsInputFormatSupported
IsOutputFormatSupported
LockForProcess

Значение счетчика сбоев увеличивается для APO каждый раз, когда один из этих методов возвращает код сбоя. Количество сбоев сбрасывается до нуля, когда APO возвращает код, указывающий, что он успешно включен в звуковой граф. Успешный вызов метода LockForProcess является хорошим признаком успешного включения APO.

В частности, Для CoCreateInstance есть ряд причин, по которым возвращенный код HRESULT может указать на сбой. Ниже приведены три основные причины.

Граф выполняет защищенное содержимое, и APO не подписан должным образом.
APO не зарегистрирован.
APO переименован или изменен.

Кроме того, если значение счетчика сбоев для SFX, MFX или EFX APO достигает заданного системой ограничения, api SFX, MFX и EFX отключены, установив для раздела реестра PKEY_Endpoint_Disable_SysFx значение 1. В настоящее время указанное системой ограничение равно 10.

Объекты обработки звука Windows

Создание компонента установки звукового драйвера

Изоляция пакета драйвера

Поделиться через

Реализация объектов обработки звука

Реализация пользовательских API

Рекомендации по проектированию для разработки пользовательских APO

Использование примера кода для ускорения процесса разработки

Скачайте и извлеките образец звука Sysvad из GitHub

Открытие решения драйвера в Visual Studio

Пример кода SwapAPO

Реализация кода обработки звука COM-объекта

Замена системных API

Работа с Visual Studio и API

Ссылка на CRT

Отключение использования внедренного манифеста

Упаковка APO с драйвером

Регистрация API для режимов обработки и эффектов в INF-файле

Пример APO INF для планшета SYSVAD Для планшета с несколькими режимами

Компонентная установка APO

Обновления к CLSID при выпуске новой версии APO

Требование обновить CLSID при переходе из HKCR в HKR

Пример APO APO для Bluetooth Audio

Пример аудиофайла APO INF

Определение пользовательского примера APO и CLSID APO INF

Пример регистрации эффектов APO

Регистрация APO

Совместимость типов узлов APO

Устранение неполадок загрузки APO

Обратная связь

Дополнительные ресурсы

Поделиться через

Реализация объектов обработки звука

Реализация пользовательских API

Рекомендации по проектированию для разработки пользовательских APO

Использование примера кода для ускорения процесса разработки

Скачайте и извлеките образец звука Sysvad из GitHub

Открытие решения драйвера в Visual Studio

Пример кода SwapAPO

Реализация кода обработки звука COM-объекта

Замена системных API

Работа с Visual Studio и API

Ссылка на CRT

Отключение использования внедренного манифеста

Упаковка APO с драйвером

Регистрация API для режимов обработки и эффектов в INF-файле

Пример APO INF для планшета SYSVAD Для планшета с несколькими режимами

Компонентная установка APO

Обновления к CLSID при выпуске новой версии APO

Требование обновить CLSID при переходе из HKCR в HKR

Пример APO APO для Bluetooth Audio

Пример аудиофайла APO INF

Определение пользовательского примера APO и CLSID APO INF

Пример регистрации эффектов APO

Регистрация APO

Совместимость типов узлов APO

Устранение неполадок загрузки APO

См. также

Обратная связь

Дополнительные ресурсы