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

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

Общие сведения об API см. в этих разделах.

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

API были впервые представлены в Windows Vista, и вы можете увидеть ссылки на более ранние системные API — sAPOs. Дополнительные сведения см. в техническом документе Пользовательские звуковые эффекты в Windows Vista . В этом техническом документе могут содержаться ссылки на предыдущие разделы о разработке COM и пользовательского интерфейса.

Как комбинировать пользовательские api и API Windows

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

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

IHV могут реализовывать пользовательские api-интерфейсы эффектов аудиосистемы для замены или обоих api эффектов пользовательской аудиосистемы Windows SFX и MFX. В широком смысле, IHV или OEM-производители имеют две основные стратегии для объединения пользовательских эффектов аудиосистемы APOs с API, которые предоставляет Windows. Эти стратегии предоставляют IHV гибкость в том, как они интегрируют свои пользовательские эффекты с эффектами Windows.

Заменить

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Состояние функции APO запроса

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

Получить эту информацию можно по крайней мере двумя способами:

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

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

Вариант А

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

При использовании варианта A пользовательский объект APO запрашивает main хранилище свойств конечной точки, а не Fx, для PKEY_AudioEngine_DeviceFormat. Затем он использует маску канала из этого формата в качестве ИДЕНТИФИКАТОРа для ключа свойства, который используется для запроса к хранилищу свойств Fx. GUID (fmtid) для ключа свойства, используемого для запроса к хранилищу свойств Fx, является одним из XXX_XXX_KEY_GUID значений из wmcodecdsp.h. Имена KEY_GUID явно соответствуют именам MFPKEY , которые обсуждались ранее в этом разделе.

Вариант Б

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

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

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

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

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

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

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

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

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

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

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

LockForProcess/UnlockForProcess

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

GetLatency

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

APOProcess

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

Обработка ошибок 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 настраиваемых эффектов аудиосистемы.

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

Api-интерфейсы, предоставляемые Windows

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

Повышение баса

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

Улучшенный звук для ноутбуков

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

Низкочастотная защита

Исправление комнаты

Заливка говорящего

Фантомирование говорящего

Виртуальное окружение

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

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

Выравнивание громкости (SFX APO)

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

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

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

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

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

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

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

Виртуальное окружение

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

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

Заливка говорящего

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

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

Маски каналов заполнения говорящего

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

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

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

• 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

В этом разделе содержатся некоторые дополнительные сведения, которые могут оказаться полезными для IHV и OEM при реализации пользовательских эффектов аудиосистемы.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если функции не будут включаться или отключать в режиме реального времени, можно отключить нормализацию, установив MFPKEY_CORR_NORMALIZATION_GAIN для свойства значение FALSE, вызвав IPropertyStore::SetValue. По умолчанию свойство может иметь значение TRUE.

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

См. также раздел

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