Объединение пользовательских и WINDOWS API

Объекты обработки звука (API), обеспечивают настраиваемую обработку цифровых сигналов на основе программного обеспечения для аудиопотоков Windows. Вы можете объединить предоставляемые корпорацией Майкрософт API с разработанным партнером кодом, оболочкой и настройкой существующих функциональных возможностей.

Общую информацию об APO см. в этих разделах.

• Архитектура объекта обработки звука
• Реализация объектов обработки звука
• Реализация аппаратных APO-эффектов с разгрузкой

APO впервые были представлены в Windows Vista, и вы можете увидеть ссылки на более ранние системные APO - sAPO. Дополнительные сведения см. в техническом документе Пользовательские аудиофильтры в Windows Vista. Этот технический документ может ссылать на старые разделы разработки COM и пользовательского интерфейса .

Объединение пользовательских и WINDOWS API

В этом разделе содержатся рекомендации по реализации настраиваемых эффектов аудиосистемы APO, создав тонкую оболочку вокруг соответствующего APO. Пользовательский APO относится к реализации APO IHV.

Существует два типа APO: SFX (Stream) и MFX (Mode). В Windows 8.1 SFX назывались LFX (локальными), а MFX назывался GFX (глобальными) APO.

Производители оборудования (IHVs) могут реализовать пользовательские APOs эффектов аудиосистемы для замены одного или обоих пользовательских APOs звуковых эффектов Windows SFX и MFX. Широко говоря, IHV или OEM имеют две основные стратегии объединения пользовательских эффектов аудиосистемы с API, которые предоставляет Windows. Эти стратегии дают IHV гибкость в том, как они интегрируют свои пользовательские эффекты с эффектами Windows.

заменить

Разработайте подробное представление об APO Windows, который вы хотите заменить, и его функции. Используйте это понимание для реализации пользовательского APO, который вызывает APO Windows таким образом, что имеет наибольшее значение для IHV с точки зрения их целевого взаимодействия с пользователем. Эта стратегия лучше всего подходит для IHV или OEM, которые хотят:

• Легко интегрируйте пользовательские эффекты с эффектами Windows.
• Реализуйте собственный пользовательский интерфейс для управления их эффектами и эффектами, реализованными API Windows.

Дополнительные сведения о написании APO см. в разделе "Объекты обработки звука Windows".

Тонкая оболочка

Напишите пользовательский APO в виде тонкой оболочки вокруг APO Windows. Эта стратегия лучше всего подходит для IHV или OEM, которые хотят:

• Добавьте их настраиваемые эффекты самым простым способом.
• Пусть пользовательский интерфейс Windows продолжает управлять эффектами.

IHV или OEM, которые выбирают стратегию тонкой оболочки, должны по-прежнему просматривать объекты обработки звука Windows для получения тщательного понимания эффектов пользовательской звуковой системы Windows.

Примечание. При использовании тонкой стратегии оболочки IHV не удается добавить пользовательский интерфейс для управления добавленными пользовательскими эффектами аудиосистемы на вкладку "Улучшения Windows". Существует только одна вкладка "Улучшения", и она должна оставаться связанной со страницей свойств для API Windows. Пользовательский интерфейс IHV должен быть реализован другим способом, например отдельное приложение панели управления.

Сведения о программировании

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

Интерфейсы API пользовательских звуковых эффектов SFX(Stream) и MFX(Mode) имеют следующие общие характеристики:

• Они должны быть зарегистрированы как объекты сервера COM в процессе, которые можно создать с помощью CoCreateInstance.
• CLSID — это CLSID_CWMAudioLFXAPO и CLSID_CWMAudioGFXAPO для SFX и MFX APO соответственно. CLSID объявлены в wmcodecdsp.h и определены в wmcodecdspuuid.lib.
• Они должны поддерживать агрегирование COM. Однако агрегирование не должно использоваться в сценарии пользовательских эффектов аудиосистемы, поэтому она не должна представлять существенных проблем.

Инициализация

Настраиваемый APO должен инициализировать APO Window, вызвав его метод IAudioSystemEffects::Initialize . Обычно это делается из пользовательского метода Инициализации APO. Все аргументы, передаваемые пользовательскому методу Инициализации APO, должны передаваться непосредственно в инициализацию Windows APO. Это позволяет APO получить свои параметры из конечной точки и хранилища свойств Fx в структуре APOInitSystemEffects. Пользовательская служба APO может получить параметры и выборочно передать их в APO, но это по сути стратегия А.

Если настраиваемое APO заменяет функцию, рекомендуется отключить соответствующую функцию в APO. Однако отключение функции может быть не обязательной в зависимости от способа работы функции. Чтобы отключить функцию, запросите APO для своего интерфейса IPropertyStore и вызовите IPropertyStore::SetValue. Свойства, поддерживаемые хранилищем свойств APO, описаны далее в разделе "Поддерживаемые свойства IPropertyStore".

Примеры того, как взаимодействовать с пользовательскими системными аудиоэффектами Windows в хранилище свойств APO, можно найти в примерах на сайте GitHub: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/APO

Запросить состояние функции APO

Если настраиваемое APO просто заменяет функцию звуковых эффектов Windows и не имеет собственного пользовательского интерфейса конфигурации или хранилища параметров, может потребоваться определить, какие функции включены в соответствующем APO.

Эти сведения можно получить по крайней мере двумя способами:

• Вариант A. Путем прямого запроса к хранилищу свойств Fx.

• Вариант B: косвенно путем создания экземпляра APO и использования его интерфейса IPropertyStore для запроса хранилища свойств.

Вариант A

У этого параметра есть преимущество в том, что его можно использовать без создания экземпляра APO. Кроме того, если пользовательская APO хочет отслеживать хранилище свойств Fx, вариант A — единственный способ получения уведомлений о изменении свойств на лету. Пример параметра A см. в примере "сжатие".

С вариантом A настраиваемый APO запрашивает основное хранилище свойств конечной точки (а не Fx) для PKEY_AudioEngine_DeviceFormat. Затем он использует маску канала из этого формата в качестве PID для ключа свойства, который используется для запроса хранилища свойств Fx. GUID (fmtid) для ключа свойства, используемого для запроса хранилища свойств Fx, является одним из значений XXX_XXX_KEY_GUID из wmcodecdsp.h. Имена KEY_GUID соответствуют очевидным образом именаМ MFPKEY, которые обсуждались ранее в этой статье.

Вариант B

Этот параметр имеет то преимущество, что он может корректно обработать ситуацию, если в конечном итоге Windows APO будет иметь некоторые функции, включенные по умолчанию, в случае отсутствия соответствующего свойства в хранилище свойств Fx.

С вариантом B пользовательский APO просто запрашивает у APO его интерфейс IPropertyStore и вызывает IPropertyStore::GetValue с помощью одного из ключей MFPKEY_XXX, которые обсуждались ранее в этом разделе.

Согласование формата

При реализации пользовательского SFX APO, который является оболочкой для SFX APO, не указывайте APO_FLAG_FRAMESPERSECOND_MUST_MATCH в свойствах регистрации пользовательского APO. Это правило следует соблюдать независимо от того, может ли настраиваемый APO изменить формат канала или нет. Если настраиваемый SFX APO укажет этот флаг, он не позволит соответствующему SFX выполнять заполнение звукового пространства, виртуализацию наушников или виртуальное объемное звучание.

Пользовательская реализация APO SFX должна реализовать или переопределить IAudioProcessingObject::IsInputFormatSupported. Реализация базового класса IsInputFormatSupported вряд ли сможет точно отразить набор возможных преобразований каналов, которые были реализованы пользовательским SFX APO и стандартным SFX APO.

Настраиваемый метод SFX APO IsInputFormatSupported должен вызывать соответствующий метод APO IsInputFormatSupported. Это гарантирует, что SFX APO обрабатывает любые преобразования каналов, с которыми не справляется пользовательский SFX APO. Обратите внимание, что SFX APO может быть обновлен для поддержки дополнительных преобразований в будущих выпусках Windows. Вызов метода APO IsInputFormatSupported является одним из способов обеспечения того, чтобы набор преобразований каналов, поддерживаемых настраиваемым APO, полностью содержал набор преобразований каналов, поддерживаемых SFX APO.

Что должно делать настраиваемое APO с возвращаемым значением метода SFX APO IsInputFormatSupported, зависит от того, какие преобразования каналов, если таковые имеются, поддерживаются пользовательским SFX APO.

Если настраиваемый объект SFX APO не поддерживает какие-либо из своих собственных преобразований каналов, его метод IsInputFormatSupported может возвращать значение, которое возвращается методом IsInputFormatSupported SFX APO непосредственно вызывающему объекту. Пример см. в примерах "swap" и "compress".

Если настраиваемый SFX APO поддерживает собственные преобразования каналов, то отрицательное возвращаемое значение, включая S_FALSE, из метода IsInputFormatSupported SFX APO может не обязательно преобразовываться в отрицательное значение для вызывающей стороны. Настраиваемый SFX APO может, например, поддерживать преобразования каналов, которые не поддерживаются соответствующим APO. В этом случае пользовательский SFX APO должен объединить возвращаемое значение из метода IsInputFormatSupported SFX APO с собственной логикой для определения поддерживаемых входных данных. Обратите внимание, что оптимальное значение "комбинирования" зависит от того, какой вид преобразования канала должен иметь приоритет. Оптимальный подход зависит от точного проектирования пользовательской реализации.

Метод IsOutputFormatSupported для SFX APO не представляет интереса, поскольку выходной формат SFX APO совпадает с форматом микширования устройства. Этот формат основан на внешних соображениях и не может подвергаться влиянию со стороны SFX APO или его входного формата. По этой причине примеры не пытаются реализовать правильную логику для IsOutputFormatSupported.

Приведенные выше рекомендации не применяются к API MFX, так как MFX APO не реализует какие-либо функции, требующие или подразумевающие изменение формата канала. По этой причине пример MFX не выполняет ничего особенного ни для IsInputFormatSupported, ни для IsOutputFormatSupported. Логика согласования формата пользовательского APO MFX не влияет на тот факт, что он упаковывает APO MFX.

LockForProcess/UnlockForProcess

Пользовательский метод IAudioProcessingObjectConfiguration::LockForProcess должен вызывать соответствующий метод в APO. LockForProcess() — это хорошее место для принятия решений в том порядке, в котором должны выполняться различные этапы обработки. Например, можно выбрать, следует ли сначала применять настраиваемую обработку APO или стандартную обработку APO. Все три примера содержат примеры такой логики принятия решений, а комментарии в примерах предоставляют некоторые фоновые данные. Однако в этом документе невозможно предоставить полное общее руководство по этому вопросу, так как в нем требуются знания о конкретных функциях пользовательского APO и о том, как они могут взаимодействовать с функциями API.

GetLatency

Пользовательская реализация APO IAudioProcessingObject::GetLatency должна вызывать GetLatency в APO, которая упаковывается. Если пользовательская обработка APO вызывает задержку, она должна добавить ее в результат, возвращенный APO, прежде чем возвращать значение вызывающему объекту.

APOProcess

Пользовательский метод APO IAudioProcessingObjectRT::APOProcess должен вызывать метод APOProcess до, после или даже во время обработки. Решение о том, когда следует вызывать APOProcess, необходимо принять в LockForProcess, чтобы можно было выделить все необходимые промежуточные буферы. API поддерживают обработку на месте всякий раз, когда их входные и выходные форматы идентичны. В этом случае пользовательский APO может передавать те же APO_CONNECTION_PROPERTY, что и свойство входного и выходного подключения для Windows APO. Однако настраиваемый APO не должен использовать свойство входного подключения пользовательского APO в качестве свойства выходного подключения для APO. Как правило, API-интерфейсы не должны изменять входной буфер.

Обработка ошибок APO

Если APO возвращает ошибку соответствующему кастомному APO, кастомный APO должен продолжать действовать так, как если бы APO не существовало. В примерах все ошибки APO трактуются как эквивалентные неудаче CoCreateInstance в создании APO. При необходимости пользовательский APO может ограничить влияние ошибок метода LockForProcess APO на текущий сеанс. Другими словами, настраиваемый APO не использует APO во время последующих вызовов своего метода APOProcess. Однако настраиваемый APO может попытаться снова использовать APO, если впоследствии будет другой вызов LockForProcess с различными форматами.

Компиляция и связывание

Чтобы использовать определения CLSID и ключей свойств APO, включите wmcodecdsp.h и свяжите с wmcodecdspuuid.lib. Дополнительные сведения см. в заголовке wmcodecdsp.h.

Примеры APO

Существует четыре примера примеров эффектов аудиосистемы. Примеры APO доступны на сайте GitHub по адресу: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad/APO

Общие рекомендации по пользовательским эффектам аудиосистемы

Ниже приведены некоторые рекомендации, которые IHV следует соблюдать при реализации api-интерфейсов пользовательских звуковых систем.

• Все эффекты аудиосистемы должны предоставлять параметры включения и отключения. Пользователи не должны быть вынуждены использовать эффект звуковой системы.
• Взаимодействие между функциями в SFX и MFX APO должно быть опосредовано API и соответствующим пользовательским интерфейсом.
• Функции, указанные как SFX или MFX, можно перемещать между SFX и MFX в пользовательских реализациях. Однако это необходимо сделать с учетом того, что параметры включения и выключения должны существовать, и что доступность и соответствие параметров не должны быть скомпрометированы.
• Разработчики должны помнить, что SFX может иметь разные маски входных и выходных каналов. MFX APO должен иметь те же маски входных и выходных каналов.

Предоставленные API Windows

Сведения о других предоставленных API Windows см. в этих разделах.

Усиление басов

Управление басами

Расширенный звук для ноутбуков

DSP для равенства громкости

Защита с низкой частотой

Калибровка помещения

Заполнение динамиков

Фантомный динамик

Виртуальный объемный звук

Виртуализированный объёмный звук в наушниках

Конкретные сведения о настройке APO

Эквализация громкости (SFX APO)

Уравнивание громкости — это сжимаемая (динамическая) обработка, которая зависит от метрики перцептуальной громкости. Коррекция помещения (MFX APO)

Коррекция акустики помещения использует профиль, созданный Мастером калибровки комнаты. Этот профиль хранится в виде двоичного объекта BLOB. Формат BLOB в настоящее время не опубликован.

Преобразование каналов (SFX APO)

APO преобразования каналов обрабатывает несколько задач.

Виртуализация наушников

Этот эффект включен, если формат канала воспроизводимого содержимого (N.x) равен 2.0 или больше, где x может быть 0 или 1. Маска вывода должна быть стерео (0x3). Маска ввода ограничена несколькими поддерживаемыми сочетаниями, которые перечислены в таблице ниже.

Маски каналов виртуализации наушников

Виртуальный объемный звук

Этот эффект также называется свёрткой LTRT (Left/Right Total) или кодированием в стереоматрице. Он используется, если формат канала воспроизводимого содержимого (N.x) равен 2,0 или больше, где x может быть 0 или 1. Снижение LTRT обычно составляет от 4,0 до 2,0. Любой другой формат ввода обычно обрабатывается сначала применением N.x для 4.0 универсального сворачивания. Однако в нашей реализации LTRT сведение по умолчанию осуществляется с 5.1 до 2.0. Любые другие входные данные обрабатываются, сначала применяя N.x к универсальному сворачиванию 5.1.

Маска выходного канала должна быть 0x3 (стерео) и количество входных каналов, включая подвуфер, если присутствует, должно быть не более восьми.

Заполнение звука

Этот эффект используется, если число входных каналов (N) меньше количества выходных каналов (M). Эффект заполняет канал N.x каналами M.x, где x может иметь значение 0 или 1.

Маски каналов в таблице 4 , игнорирующие канал LFE, поддерживаются для заливки говорящего. Поддержка динамического заполнения гарантирует корректную работу при любом сочетании наличия входных или выходных каналов сабвуфера, поэтому цифры слева являются только примерами. Фактические конфигурации могут или не имеют подвуфера.

Маски каналов заполнения динамика

Заполнение для колонок не поддерживается, если выполнено одно из следующих условий:

• Маска ввода равна маске вывода.
• Единственное различие между входом и выходом заключается в том, что в одном случае имеются боковые левые/правые каналы, а в другом - задние левые/правые каналы.
• Входные данные имеют больше основных каналов, чем выходные данные.
• Маска вывода включает центральные левые и правые динамики, но маска ввода их не включает.
• Набор каналов в выходных данных, который отсутствует в входных данных, не включает по крайней мере один из следующих: передний центр, задний слева/справа, или боковой слева/справа.

Существует одно исключение для второго элемента в списке. Если единственное различие между входными и выходными данными заключается в том, что у одного присутствуют боковые левый/правый каналы, а у другого задние левый/правый каналы, заливка динамиков поддерживается, если любой формат содержит каналы, которые располагаются между боковыми и задними каналами в порядке битовой маски канала. Существует три таких канала:

• SPEAKER_FRONT_LEFT_OF_CENTER
• SPEAKER_FRONT_RIGHT_OF_CENTER
• SPEAKER_BACK_CENTER

Если входная или выходная маска содержит любой из этих трех каналов, поддержка функции заполнения аудиоканалов может быть возможна, даже если второе условие в списке не выполнено, но только при выполнении других условий. Например, заполнение звуковых каналов из MASK_7_FRONT_BACK в MASK_7_FRONT_SIDE или наоборот поддерживается технологией заполнения для этой цели.

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

Задержки используются для каналов в выходных конфигурациях, которые находятся вне диапазона "вперёд-назад" во входной конфигурации. И наоборот, если динамик в выходной конфигурации "между" некоторыми динамиками во входной конфигурации в передне-заднем смысле, выходные данные для этого динамика создаются путем смешивания некоторых входных каналов с любой стороны выходного канала.

вопросы Run-Time при повторном использовании API Windows

Этот раздел содержит дополнительные сведения, которые могут быть полезны для IHVs и OEMs при реализации пользовательских эффектов аудиосистемы.

Пользовательская реализация APO:

• Использует CoCreateInstance для создания одного или нескольких экземпляров пользовательских эффектов аудиосистемы Windows APO.
• Настройка каждого экземпляра для включения требуемого набора функций.
• Вставляет каждый экземпляр в соответствующее место внутри внутреннего конвейера APO.

Почему один или несколько экземпляров?

Чтобы избежать нежелательных взаимодействий, большинство функций требуют определенного относительного упорядочения. Так как API Windows реализуют несколько функций в одном APO, для правильного упорядочивания может потребоваться несколько экземпляров этого APO. Например, предположим, что три включенные функции A, B и C должны быть упорядочены в порядке ABC. Пользовательская реализация обрабатывает B, но делегирует A и C на APO Windows. Затем A и C должны находиться в отдельных экземплярах Microsoft APO, чтобы пользовательская реализация B могла бы произойти между ними.

Windows реализует коррекцию звука для помещения в MFX APO, то есть это отдельный COM-объект от SFX APO. Пользовательская реализация может делегировать исправление помещений в реализацию Windows, но поместить ее в пользовательский SFX APO. Пользовательская реализация SFX может затем делегировать некоторую обработку в реализацию Windows SFX APO, а другую обработку в реализацию Windows MFX APO.

Обработка ограничений различных сочетаний форматов ввода-вывода

Многие функции, особенно управление басами, не всегда работают. Например, прямое управление басами не определено, если значение конфигурации динамиков баса — "AllSmall" или "AllLarge", а выходной формат не включает канал сабвуфера или установлен флаг NoSub. Во время вызова IPropertyStore::SetValue невозможно обнаружить сбой. Метод пытается включить функцию, но входные и выходные форматы не известны в то время, так как LockForProcess должен произойти после всех операций с свойствами. Это означает, что можно включить функцию, которая, казалось бы, работает успешно, но соответствующая обработка при этом не выполняется.

Для решения таких ситуаций доступны две стратегии:

• Тщательно изучите разделы этого документа, чтобы точно предсказать, когда данная функция будет или не будет выполнена успешно.
• Вызов IPropertyStore::GetValue после вызова LockForProcess для проверки состояния важных свойств.

Если LockForProcess определяет, что определенная функция не может быть включена( из-за входных и выходных форматов или значения какого-либо другого свойства— LockForProcess обновляет значение соответствующего свойства в хранилище свойств.

Взаимодействие между заливкой динамиков и управлением басами

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

Если заливка динамиков включена и не подключен подвуфер, возможны два типа управления басами вперед:

• Если передние левые и правые динамики большие, управление басами направляет низкочастотную часть окружающих и центральных каналов в передние левые и правые динамики. Передовая обработка басов должна выполняться после настройки колонок в этом случае.
• Если все динамики небольшие, то управление низкими частотами становится защитой от низких частот для всех основных динамиков.

Это может произойти либо до, либо после заполнения звуковой панели. Тем не менее, по соображениям производительности лучше сначала провести управление басами перед заполнением звука в динамиках.

Windows APO реализует некоторые распространенные конфигурации заполнения динамиков, например 2.0 => 5.1, со специальным оптимизированным кодом, который обрабатывает обратное управление басами на том же шаге, что и заполнение динамиков.

Взаимодействие фолдауна и бас-менеджмента

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

• Продвинутое управление басами не имеет смысла с виртуализацией звука для наушников.
• Для простоты реализации низкочастотная защита и повышение басов не поддерживаются.

Когда включена любая из функций виртуализации наушников, кодировки виртуального окружения или заливки динамиков, управление обратными басами осуществляется на этом этапе. Управление обратными басами по-прежнему контролируется с помощью свойства обратного управления басами APO, как если бы это была отдельная функция. В таких случаях обратное управление басами просто управляет коэффициентами свертывания для входного канала .1. Одна из открытых проблем заключается в том, что управление обратными басами невозможно отключить при включении LTRT. В этом случае обратное управление басами использует нестандартное увеличение канала сабвуфера.

Эффекты аудиосистемы Windows применяют некоторые незначительные обработки — усиление и задержку, даже если функции не включены. Целью такой обработки является обеспечение того, чтобы параметры усиления и задержки не изменялись, когда функция включена в рабочем режиме. Причина заключается в том, что задержка присуща реализации некоторых функций, и коэффициент усиления <1 применяется некоторыми функциями, чтобы избежать чрезмерно высокого выходного сигнала в определенных ситуациях. Набор доступных функций зависит от форматов входных и выходных данных и определенных свойств, а также от совокупного выигрыша от нормализации и задержки.

Если функции не нужно включать или отключать на лету, нормализацию можно отключить, установив значение свойства MFPKEY_CORR_NORMALIZATION_GAIN в FALSE с помощью вызова IPropertyStore::SetValue. Свойство может иметь значение TRUE по умолчанию.

Нет механизма отключения задержки нормализации, так как предполагается, что она вызывает меньше возражений, чем усиление нормализации. Если задержка нормализации является нежелательной, просто обойдите упомянутый APO.

См. также

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