Implémentation d’objets de traitement audio

Article
05/27/2024

Cette rubrique explique comment implémenter un objet de traitement audio (APO). Pour des informations générales sur les APO, consultez la section Architecture des objets de traitement audio.

Implémentation des APO personnalisés

Les APO personnalisés sont implémentés en tant qu’objets COM en processus, ils fonctionnent donc en mode utilisateur et sont intégrés dans une bibliothèque de liens dynamiques (DLL). Il existe trois types d’APO, en fonction de l’endroit où ils sont insérés dans le graphe de traitement du signal.

Effets de flux (SFX)
Effets de mode (MFX)
Effets de point de terminaison (EFX)

Chaque appareil logique peut être associé à un APO de chaque type. Pour plus d’informations sur les modes et les effets, consultez la section Modes de traitement du signal audio.

Vous pouvez implémenter un APO en basant votre classe personnalisée sur la classe de base CBaseAudioProcessingObject, qui est déclarée dans le fichier Baseaudioprocessingobject.h. Cette approche consiste à ajouter de nouvelles fonctionnalités dans la classe de base CBaseAudioProcessingObject pour créer un APO personnalisé. La classe de base CBaseAudioProcessingObject implémente une grande partie des fonctionnalités requises par un APO. Elle fournit des implémentations par défaut pour la plupart des méthodes dans les trois interfaces requises. L’exception principale est la méthode IAudioProcessingObjectRT::APOProcess.

Suivez la procédure suivante pour implémenter vos APO personnalisés.

Créez des objets COM APO personnalisés pour fournir le traitement audio souhaité.
Créez éventuellement une interface utilisateur pour configurer les APO personnalisés.
Créez un fichier INF pour installer et enregistrer les APO et l’interface utilisateur personnalisée.

Considérations de conception pour le développement d’APO personnalisés

Tous les APO personnalisés doivent avoir les caractéristiques générales suivantes :

L’APO doit avoir une connexion d’entrée et une connexion de sortie. Ces connexions sont des tampons audio et peuvent avoir plusieurs canaux.
Un APO ne peut modifier que les données audio qui lui sont passées via sa routine IAudioProcessingObjectRT::APOProcess. L’APO ne peut pas modifier les paramètres de l’appareil logique sous-jacent, y compris sa topologie KS.
En plus de IUnknown, les APO doivent exposer les interfaces suivantes :
- IAudioProcessingObject. Une interface qui gère les tâches de configuration telles que l’initialisation et la négociation de format.
- IAudioProcessingObjectConfiguration. L’interface de configuration.
- IAudioProcessingObjectRT. Une interface en temps réel qui gère le traitement audio. Elle peut être appelée à partir d’un thread de traitement en temps réel.
- IAudioSystemEffects. L’interface qui permet au moteur audio de reconnaître une DLL en tant qu’APO des effets système.
Tous les APO doivent être compatibles avec le système en temps réel. Cela signifie que :
- Toutes les méthodes membres des interfaces en temps réel doivent être implémentées comme des membres non bloquants. Elles ne doivent pas bloquer, utiliser de la mémoire paginée ou appeler des routines système bloquantes.
- Tous les tampons traités par l’APO doivent être non paginables. Tout le code et les données dans le chemin de traitement doivent être non paginables.
- Les APO ne doivent pas introduire de latence significative dans la chaîne de traitement audio.
Les APO personnalisés ne doivent pas exposer l’interface IAudioProcessingObjectVBR.

Remarque

Pour des informations détaillées sur les interfaces requises, consultez les fichiers Audioenginebaseapo.h et Audioenginebaseapo.idl dans le dossier Windows Kits\<build number>\Include\um.

Utilisation de code d’exemple pour accélérer le processus de développement

Utiliser l’exemple de code SYSVAD Swap APO comme modèle peut accélérer le processus de développement des APO personnalisés. L’exemple Swap est conçu pour illustrer certaines fonctionnalités des objets de traitement audio. L’exemple Swap APO échange le canal gauche avec le canal droit et implémente à la fois des effets SFX et MFX. Vous pouvez activer et désactiver les effets audio d’échange de canal à l’aide de la boîte de dialogue des propriétés.

L’exemple audio SYSVAD est disponible sur le GitHub des exemples de pilotes Windows.

Vous pouvez consulter l’exemple audio Sysvad ici :

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

Télécharger et extraire l’échantillon audio Sysvad depuis GitHub

Suivez ces étapes pour télécharger et ouvrir l’exemple SYSVAD.

a. Vous pouvez utiliser les outils GitHub pour travailler avec les exemples. Vous pouvez également télécharger les exemples de pilotes universels dans un fichier zip.

https://github.com/Microsoft/Windows-driver-samples/archive/master.zip

b. Téléchargez le fichier master.zip sur votre disque dur local.

c. Sélectionnez et maintenez enfoncé (ou faites un clic droit) Windows-driver-samples-master.zip, et choisissez Extraire tout. Spécifiez un nouveau dossier ou parcourez-en un existant qui stockera les fichiers extraits. Par exemple, vous pouvez spécifier C:\DriverSamples\ comme le nouveau dossier dans lequel les fichiers seront extraits.

d. Après l’extraction des fichiers, accédez au sous-dossier suivant : C:\DriverSamples\Audio\Sysvad.

Ouvrez la solution du pilote dans Visual Studio

Dans Microsoft Visual Studio, sélectionnez Fichier>Ouvrir>Projet/Solution... et rendez-vous dans le dossier contenant les fichiers extraits (par exemple, C:\DriverSamples\Audio\Sysvad). Double-cliquez sur le fichier de solution Sysvad pour l’ouvrir.

Dans Visual Studio, localisez l’Explorateur de solutions. (Si ce n’est pas déjà ouvert, choisissez Explorateur de solutions dans le menu Affichage). Dans l’Explorateur de solutions, vous pouvez voir une solution contenant six projets.

Exemple de code SwapAPO

Il y a cinq projets dans l’exemple SYSVAD, dont un est d’intérêt principal pour le développeur d’APO.

Projet	Description
SwapAPO	Exemple de code pour un APO

Les autres projets dans l’exemple Sysvad sont résumés ci-dessous.

Projet	Description
TabletAudioSample	Exemple de code pour un pilote audio alternatif.
KeywordDetectorAdapter	Exemple de code pour un adaptateur de détecteur de mots-clés.
EndpointsCommon	Exemple de code pour des points de terminaison communs.

Les principaux fichiers d’en-tête pour l’exemple SwapAPO sont swapapo.h. Les autres éléments de code principaux sont résumés ci-dessous.

File	Description
Swap.cpp	Code C++ qui contient l’implémentation de Swap APO.
SwapAPOMFX.cpp	Implémentation de CSwapAPOMFX.
SwapAPOSFX.cpp	Implémentation de CSwapAPOSFX.
SwapAPODll.cpp	Implémentation des exportations de DLL.
SwapAPODll.idl	Définition des interfaces COM et des coclasses pour la DLL.
SwapAPOInterface.idl	Les définitions d’interface et de type pour la fonctionnalité Swap APO.
swapapodll.def	Définitions des exportations COM.

Implémentation du code de traitement audio de l’objet COM

Vous pouvez encapsuler un APO fourni par le système en basant votre classe personnalisée sur la classe de base CBaseAudioProcessingObject, qui est déclarée dans le fichier Baseaudioprocessingobject.h. Cette approche consiste à introduire de nouvelles fonctionnalités dans la classe de base CBaseAudioProcessingObject pour créer un APO personnalisé. La classe de base CBaseAudioProcessingObject implémente une grande partie des fonctionnalités requises par un APO. Elle fournit des implémentations par défaut pour la plupart des méthodes dans les trois interfaces requises. L’exception principale est la méthode IAudioProcessingObjectRT::APOProcess.

En utilisant CBaseAudioProcessingObject, vous pouvez plus facilement implémenter un APO. Si un APO n’a pas d’exigences de format particulières et fonctionne sur le format float32 requis, les implémentations par défaut des méthodes d’interface incluses dans CBaseAudioProcessingObject devraient être suffisantes. Étant donné les implémentations par défaut, seules trois méthodes principales doivent être implémentées : IAudioProcessingObject::IsInputFormatSupported, IAudioProcessingObjectRT::APOProcess et ValidateAndCacheConnectionInfo.

Pour développer vos APO basés sur la classe CBaseAudioProcessingObject, suivez la procédure suivante :

Créez une classe qui hérite de CBaseAudioProcessingObject.

L’exemple de code C++ suivant montre la création d’une classe qui hérite de CBaseAudioProcessingObject. Pour une implémentation réelle de ce concept, suivez les instructions dans la section Exemple de pilote d’objets de traitement audio pour accéder à l’exemple Swap, puis consultez le fichier Swapapo.h.
```
// Custom APO class - SFX
Class MyCustomAPOSFX: public CBaseAudioProcessingObject
{
 public:
//Code for custom class goes here
...
};
```
Remarque : Étant donné que le traitement du signal effectué par un APO SFX est différent du traitement du signal effectué par un APO MFX ou EFX, vous devez créer des classes distinctes pour chacun.
Implémentez les trois méthodes suivantes :
- IAudioProcessingObject::IsInputFormatSupported. Cette méthode gère la négociation de format avec le moteur audio.
- IAudioProcessingObjectRT::APOProcess. Cette méthode utilise votre algorithme personnalisé pour effectuer le traitement du signal.
- ValidateAndCacheConnectionInfo. Cette méthode alloue de la mémoire pour stocker les détails du format, par exemple, le nombre de canaux, la fréquence d’échantillonnage, la profondeur d’échantillon et le masque de canal.

L’exemple de code C++ suivant montre une implémentation de la méthode APOProcess pour la classe d’exemple que vous avez créée à l’étape 1. Pour une implémentation réelle de ce concept, suivez les instructions dans la section Exemple de pilote d’objets de traitement audio pour accéder à l’exemple Swap, puis consultez le fichier 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.
...
}

L’exemple de code suivant montre une implémentation de la méthode ValidateAndCacheConnectionInfo. Pour une implémentation réelle de cette méthode, suivez les instructions dans la section Exemple de pilote d’objets de traitement audio pour accéder à l’exemple Swap, puis consultez le fichier 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.
...
}

Remarque : Les interfaces et méthodes restantes que votre classe hérite de CBaseAudioProcessingObject sont décrites en détail dans le fichier Audioenginebaseapo.idl.

Remplacement des APO fournis par le système

Lors de l’implémentation des interfaces APO, il existe deux approches : vous pouvez écrire votre propre implémentation ou appeler les APO intégrés.

Ce pseudo-code illustre l’encapsulation d’un APO système.

CMyWrapperAPO::CMyWrapperAPO {
    CoCreateInstance(CLSID_InboxAPO, m_inbox);
}

CMyWrapperAPO::IsInputFormatSupported {
    Return m_inbox->IsInputFormatSupported(…);
}

Ce pseudo-code illustre la création de votre propre APO personnalisé.

CMyFromScratchAPO::IsInputFormatSupported {
    my custom logic
}

Lorsque vous développez vos APO pour remplacer ceux fournis par le système, vous devez utiliser les mêmes noms dans la liste suivante pour les interfaces et méthodes. Certaines des interfaces ont plus de méthodes en plus des méthodes requises répertoriées. Consultez les pages de référence de ces interfaces pour déterminer si vous souhaitez implémenter toutes les méthodes ou seulement celles requises.

Les autres étapes de l’implémentation sont les mêmes que pour un APO personnalisé.

Implémentez les interfaces et méthodes suivantes pour le composant COM :

IAudioProcessingObject. Les méthodes requises pour cette interface sont : Initialize et IsInputFormatSupported.
IAudioProcessingObjectConfiguration. Les méthodes requises pour cette interface sont : LockForProcess et UnlockForProcess
IAudioProcessingObjectRT. La méthode requise pour cette interface est APOProcess et c’est la méthode qui implémente l’algorithme DSP.
IAudioSystemEffects. Cette interface permet au moteur audio de reconnaître une DLL en tant qu’APO.

Travailler avec Visual Studio et les APO

Lorsque vous travaillez avec les APO dans Visual Studio, effectuez ces tâches pour chaque projet APO.

Lier à la CRT

Les pilotes ciblant Windows 10 doivent se lier dynamiquement à la CRT universelle.

Si vous devez prendre en charge Windows 8.1, activez la liaison statique en définissant les propriétés du projet dans C/C++, Génération de code. Paramétrez « Bibliothèque d’exécution » sur /MT pour les builds de release ou /MTd pour les builds de débogage. Ce changement est apporté car pour un pilote, il est difficile de redistribuer le binaire MSVCRT<n>.dll. La solution consiste à lier statiquement libcmt.dll. Pour plus d’informations, consultez /MD, /MT, /LD (Utilisation de la bibliothèque d’exécution).

Désactiver l’utilisation d’un manifeste intégré

Désactivez l’utilisation d’un manifeste intégré en définissant les propriétés du projet pour votre projet APO. Sélectionnez Outil de manifeste, Entrée et sortie. Puis changez la valeur par défaut de « Intégrer le manifeste » de Oui à Non. Si vous avez un manifeste intégré, cela déclenche l’utilisation de certaines API interdites dans un environnement protégé. Cela signifie que votre APO fonctionnera avec DisableProtectedAudioDG=1, mais lorsque cette clé de test sera supprimée, votre APO ne se chargera pas, même s’il est signé WHQL.

Packaging de votre APO avec un pilote

Lorsque vous développez votre propre pilote audio et encapsulez ou remplacez les APO fournis par le système, vous devez fournir un package de pilote pour installer le pilote et les APO. Pour Windows 10, veuillez consulter Pilotes Windows universels pour audio. Vos packages de pilotes liés à l’audio doivent suivre les politiques et le modèle de packaging détaillés ici.

L’APO personnalisé est emballé en tant que DLL, et toute interface utilisateur de configuration est emballée en tant qu’application UWP ou Desktop Bridge séparée. Le fichier INF de l’appareil APO copie les DLL dans les dossiers système indiqués dans la directive INF CopyFile associée. La DLL contenant les APO doit s’enregistrer en incluant une section AddReg dans le fichier INF.

Les paragraphes et fragments de fichier INF suivants montrent les modifications nécessaires pour utiliser le fichier INF standard pour copier et enregistrer les APO.

Les fichiers INF inclus avec l’exemple Sysvad illustrent comment les APO SwapApo.dll sont enregistrés.

Enregistrer les APO pour les modes et effets de traitement dans le fichier INF

Vous pouvez enregistrer des APO pour des modes spécifiques en utilisant certaines combinaisons autorisées de clés de registre. Pour plus d’informations sur les effets disponibles et des informations générales sur les APO, consultez la section Architecture des objets de traitement audio.

Reportez-vous à ces rubriques de référence pour obtenir des informations sur chacun des paramètres de fichier INF d’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

Les exemples de fichiers INF suivants montrent comment enregistrer des objets de traitement audio (APO) pour des modes spécifiques. Ils illustrent les combinaisons possibles disponibles à partir de cette liste.

PKEY_FX_StreamEffectClsid avec PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid avec PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_ModeEffectClsid sans PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_EndpointEffectClsid sans PKEY_EFX_ProcessingModes_Supported_For_Streaming

Il existe une combinaison valide supplémentaire qui n’est pas montrée dans ces exemples.

PKEY_FX_EndpointEffectClsid avec PKEY_EFX_ProcessingModes_Supported_For_Streaming

Exemple de fichier INF de l’effet de streaming multi-mode pour tablette SYSVAD

Cet exemple montre un effet de streaming multi-mode enregistré à l’aide d’entrées AddReg dans le fichier INF de la tablette SYSVAD.

Cet exemple de code provient de l’exemple audio SYSVAD et est disponible sur GitHub : https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Cet exemple illustre cette combinaison d’effets système :

PKEY_FX_StreamEffectClsid avec PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid avec 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%

Notez que dans le fichier INF d’exemple, la propriété EFX_Streaming est commentée car le traitement audio est passé en mode noyau au-dessus de cette couche, de sorte que cette propriété de streaming n’est pas nécessaire et ne serait pas utilisée. Il serait valide de spécifier un PKEY_FX_EndpointEffectClsid à des fins de découverte, mais ce serait une erreur de spécifier PKEY_EFX_ProcessingModes_Supported_For_Streaming. C’est parce que le mélange / tee des modes se produit plus bas dans la pile, où il n’est pas possible d’insérer un APO de point de terminaison.

Installation d’APO en plusieurs composants

À partir de Windows 10, version 1809, l’enregistrement des APO avec le moteur audio utilise le modèle de pilote audio séparé en plusieurs composants. L’utilisation de la séparation en plusieurs composants audio crée une expérience d’installation plus fluide et plus fiable et prend mieux en charge le service des composants. Pour plus d’informations, consultez Créer une installation de pilote audio séparé en plusieurs composants.

L’exemple de code suivant est extrait des fichiers ComponentizedAudioSampleExtension.inf et ComponentizedApoSample.inf publics. Consultez l’exemple audio SYSVAD qui est disponible sur GitHub ici : https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

L’enregistrement de l’APO avec le moteur audio se fait en utilisant un appareil APO nouvellement créé. Pour que le moteur audio utilise le nouvel appareil APO, il doit être un enfant PNP de l’appareil audio, frère des points de terminaison audio. La nouvelle conception APO en plusieurs composants ne permet pas à un APO d’être enregistré globalement et utilisé par plusieurs pilotes différents. Chaque pilote doit enregistrer ses propres APO.

L’installation de l’APO se fait en deux parties. Tout d’abord, le fichier INF d’extension du pilote ajoutera un composant APO au système :

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

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

Ce composant APO déclenche la deuxième partie, l’installation du fichier INF de l’APO, dans l’exemple SYSVAD cela est fait dans ComponentizedApoSample.inf. Ce fichier INF est dédié au composant APO. Il spécifie la classe de composant en tant qu’AudioProcessingObject et ajoute toutes les propriétés APO pour l’enregistrement CLSID et l’enregistrement avec le moteur audio.

Remarque

Les exemples de fichiers INF montrés prennent en charge l’isolation du package de pilotes en utilisant la clé de registre HKR. Avant Windows 11, version 22000, les exemples utilisaient HKCR pour stocker des valeurs persistantes pour les enregistrements CLSID, au lieu de HKR. L’enregistrement APO a été pris en charge en utilisant HKR à partir de Windows 10, version 1809. Pour plus d’informations, consultez Utiliser un fichier INF universel.

[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%
...

Lorsque ce fichier INF installe l’APO en plusieurs composants, sur un système de bureau « Objets de traitement audio » sera affiché dans le Gestionnaire de périphériques Windows.

Mises à jour des CLSID lorsqu’une nouvelle version d’APO est publiée

Lorsqu’une nouvelle version d’APO est publiée, il est bon de mettre à jour et généralement recommandé de mettre à jour le CLSID de la classe COM. Utilisez des outils tels que GUIDGEN pour créer de nouveaux GUID.

Exigence de mise à jour des CLSID lors du passage de HKCR à HKR

Il est nécessaire de changer le GUID de la classe COM lors du passage des enregistrements COM globaux (HKCR) aux enregistrements COM relatifs aux appareils HKR. Cette approche réduit la possibilité que les nouveaux objets COM ne soient pas correctement enregistrés et échouent à se charger.

Exemple de fichier INF APO audio Bluetooth

Cet exemple illustre cette combinaison d’effets système :

PKEY_FX_StreamEffectClsid avec PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid avec PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

Cet exemple de code prend en charge les appareils mains libres et stéréo 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}"

Exemple de fichier INF APO audio

Cet exemple de fichier INF illustre la combinaison suivante d’effets système :

PKEY_FX_StreamEffectClsid avec PKEY_SFX_ProcessingModes_Supported_For_Streaming
PKEY_FX_ModeEffectClsid avec PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
PKEY_FX_EndpointEffectClsid sans 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%

Définir un APO personnalisé et exemple de fichier INF CLSID APO

Cet exemple montre comment définir votre propre CLSID pour un APO personnalisé. Cet exemple utilise le CLSID MsApoFxProxy {889C03C8-ABAD-4004-BF0A-BC7BB825E166}. La création de ce GUID instancie une classe dans MsApoFxProxy.dll qui implémente les interfaces IAudioProcessingObject et interroge le pilote sous-jacent via l’ensemble de propriétés KSPROPSETID_AudioEffectsDiscovery.

Cet exemple de fichier INF montre la section [BthHfAud], qui inclut [MsApoFxProxy.Registration] de wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], qui enregistre ensuite PKEY_FX_EndpointEffectClsid en tant que CLSID bien connu pour MsApoFxProxy.dll.

Cet exemple de fichier INF illustre également l’utilisation de cette combinaison d’effets système :

PKEY_FX_EndpointEffectClsid sans 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

Exemple d’enregistrement d’effet APO

Cet exemple montre la section [Apo_AddReg] de Sysvad ComponentizedApoSample.inx. Cette section enregistre le GUID du flux d’échange avec COM et enregistre l’effet de flux d’échange APO. La section [Apo_CopyFiles] a une DestinationDirs de 13, qui copie swapapo.dll dans le Driverstore. Pour plus d’informations, consultez « Exécuter à partir de Driverstore » dans Isolation du package de pilote.

Pour des informations générales sur les fichiers INF, consultez Vue d’ensemble des fichiers 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}"

...

Inscription APO

L’enregistrement des APO est utilisé pour prendre en charge un processus qui associe dynamiquement les effets aux points de terminaison à l’aide d’un calcul pondéré. Le calcul pondéré utilise les magasins de propriétés suivants. Chaque interface audio a zéro ou plus de magasins de propriétés de point de terminaison et magasins de propriétés d’effets enregistrés soit via le .inf, soit à l’exécution. Le magasin de propriétés de point de terminaison le plus spécifique et le magasin de propriétés d’effets le plus spécifique ont les poids les plus élevés et sont utilisés. Tous les autres magasins de propriétés sont ignorés.

La spécificité est calculée comme suit :

Pondération des magasins de propriétés de point de terminaison

FX avec KSNODETYPE spécifique
FX avec KSNODETYPE_ANY
MSFX avec KSNODETYPE spécifique
MSFX avec KSNODETYPE_ANY

Pondération des magasins de propriétés d’effets

EP avec KSNODETYPE spécifique
EP avec KSNODETYPE_ANY
MSEP avec KSNODETYPE spécifique
MSEP avec KSNODETYPE_ANY

Les numéros doivent commencer à 0 et augmenter séquentiellement : MSEP\0, MSEP\1, …, MSEP\n. Si (par exemple) EP\3 manque, Windows cessera de chercher EP\n et ne verra pas EP\4, même s’il existe.

La valeur de PKEY_FX_Association (pour les magasins de propriétés d’effets) ou PKEY_EP_Association (pour les magasins de propriétés de point de terminaison) est comparée à la valeur KSPINDESCRIPTOR.Category pour la fabrique de broches à l’extrémité matérielle du chemin du signal, tel qu’exposé par Kernel Streaming.

Seuls les pilotes de classe Microsoft intégrés (qui peuvent être encapsulés par un développeur tiers) doivent utiliser MSEP et MSFX ; tous les pilotes tiers doivent utiliser EP et FX.

Compatibilité du type de nœud APO

L’exemple de fichier INF suivant illustre la définition de la clé PKEY_FX_Association sur un GUID associé à l’APO.

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

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

Étant donné qu’un adaptateur audio est capable de prendre en charge plusieurs entrées et sorties, vous devez indiquer explicitement le type de nœud de streaming (KS) avec lequel votre APO personnalisé est compatible. Dans le fragment de fichier INF précédent, l’APO est associé à un type de nœud KS de %KSNODETYPE_ANY%. Plus loin dans ce fichier INF, KSNODETYPE_ANY est défini comme suit :

[Strings]
;; Define the strings used in MyINF.inf
...
KSNODETYPE_ANY      = "{00000000-0000-0000-0000-000000000000}"
KSNODETYPE_SPEAKER  = "{DFF21CE1-F70F-11D0-B917-00A0C9223196}"
...

Une valeur de NULL pour KSNODETYPE_ANY signifie que cet APO est compatible avec n’importe quel type de nœud KS. Pour indiquer, par exemple, que votre APO n’est compatible qu’avec un type de nœud KS de KSNODETYPE_SPEAKER, le fichier INF montrerait le type de nœud KS et l’association APO comme suit :

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

Pour plus d’informations sur les valeurs GUID pour les différents types de nœuds KS, consultez le fichier d’en-tête Ksmedia.h.

Dépannage des échecs de chargement d’APO

Les informations suivantes sont fournies pour vous aider à comprendre comment les échecs sont surveillés pour les APO. Vous pouvez utiliser ces informations pour résoudre les problèmes des APO qui ne parviennent pas à être incorporés dans le graphe audio.

Le système audio surveille les codes de retour APO pour déterminer si les APO sont incorporés avec succès dans le graphe. Il surveille les codes de retour en suivant les valeurs HRESULT qui sont renvoyées par l’une des méthodes désignées. Le système maintient une valeur de compteur d’échecs séparée pour chaque APO SFX, MFX et EFX qui est incorporé dans le graphe.

Le système audio surveille les valeurs HRESULT renvoyées par les quatre méthodes suivantes.

CoCreateInstance
IsInputFormatSupported
IsOutputFormatSupported
LockForProcess

La valeur du compteur d’échecs est incrémentée pour un APO chaque fois qu’une de ces méthodes renvoie un code d’échec. Le compteur d’échecs est réinitialisé à zéro lorsqu’un APO renvoie un code indiquant qu’il a été incorporé avec succès dans le graphe audio. Un appel réussi à la méthode LockForProcess est un bon indicateur que l’APO a été incorporé avec succès.

Pour CoCreateInstance en particulier, il existe un certain nombre de raisons pour lesquelles le code HRESULT renvoyé pourrait indiquer un échec. Les trois principales raisons sont les suivantes :

Le graphe exécute du contenu protégé et l’APO n’est pas correctement signé.
L’APO n’est pas enregistré.
L’APO a été renommé ou modifié.

De plus, si la valeur du compteur d’échecs pour un APO SFX, MFX ou EFX atteint une limite spécifiée par le système, les APO SFX, MFX et EFX sont désactivés en définissant la clé de registre PKEY_Endpoint_Disable_SysFx à « 1 ». La limite spécifiée par le système est actuellement une valeur de 10.

Objets de traitement audio Windows

Créer une installation de pilote audio séparé en plusieurs composants

Isolation du package de pilote

Partager via

Implémentation d’objets de traitement audio

Implémentation des APO personnalisés

Considérations de conception pour le développement d’APO personnalisés

Utilisation de code d’exemple pour accélérer le processus de développement

Télécharger et extraire l’échantillon audio Sysvad depuis GitHub

Ouvrez la solution du pilote dans Visual Studio

Exemple de code SwapAPO

Implémentation du code de traitement audio de l’objet COM

Remplacement des APO fournis par le système

Travailler avec Visual Studio et les APO

Lier à la CRT

Désactiver l’utilisation d’un manifeste intégré

Packaging de votre APO avec un pilote

Enregistrer les APO pour les modes et effets de traitement dans le fichier INF

Exemple de fichier INF de l’effet de streaming multi-mode pour tablette SYSVAD

Installation d’APO en plusieurs composants

Mises à jour des CLSID lorsqu’une nouvelle version d’APO est publiée

Exigence de mise à jour des CLSID lors du passage de HKCR à HKR

Exemple de fichier INF APO audio Bluetooth

Exemple de fichier INF APO audio

Définir un APO personnalisé et exemple de fichier INF CLSID APO

Exemple d’enregistrement d’effet APO

Inscription APO

Compatibilité du type de nœud APO

Dépannage des échecs de chargement d’APO

Commentaires

Ressources supplémentaires

Partager via

Implémentation d’objets de traitement audio

Implémentation des APO personnalisés

Considérations de conception pour le développement d’APO personnalisés

Utilisation de code d’exemple pour accélérer le processus de développement

Télécharger et extraire l’échantillon audio Sysvad depuis GitHub

Ouvrez la solution du pilote dans Visual Studio

Exemple de code SwapAPO

Implémentation du code de traitement audio de l’objet COM

Remplacement des APO fournis par le système

Travailler avec Visual Studio et les APO

Lier à la CRT

Désactiver l’utilisation d’un manifeste intégré

Packaging de votre APO avec un pilote

Enregistrer les APO pour les modes et effets de traitement dans le fichier INF

Exemple de fichier INF de l’effet de streaming multi-mode pour tablette SYSVAD

Installation d’APO en plusieurs composants

Mises à jour des CLSID lorsqu’une nouvelle version d’APO est publiée

Exigence de mise à jour des CLSID lors du passage de HKCR à HKR

Exemple de fichier INF APO audio Bluetooth

Exemple de fichier INF APO audio

Définir un APO personnalisé et exemple de fichier INF CLSID APO

Exemple d’enregistrement d’effet APO

Inscription APO

Compatibilité du type de nœud APO

Dépannage des échecs de chargement d’APO

Rubriques connexes

Commentaires

Ressources supplémentaires