Audio Devices DDI Reference

Overview of the Audio Devices DDI Reference technology.

To develop Audio Devices DDI Reference, you need these headers:

For programming guidance for this technology, see:

Enumerations

 
APO_FLAG

The APO_FLAG enumeration defines constants that are used as flags by an audio processing object (APO).
APO_LOG_LEVEL

Specifies the level of an APO event logged with IAudioProcessingObjectLoggingService::ApoLog.
APO_NOTIFICATION_TYPE

Specifies the type of an APO_NOTIFICATION.
APO_REFERENCE_STREAM_PROPERTIES

Specifies loopback stream properties for the IApoAcousticEchoCancellation2::GetDesiredReferenceStreamProperties callback method.
AUDIO_SYSTEMEFFECT_STATE

Specifies the state of a System Effects Audio Processing Object (sAPO) audio effect.
DEVICE_ORIENTATION_TYPE

Specifies device orientation values for notifications of type APO_NOTIFICATION_TYPE_DEVICE_ORIENTATION.
KSPROPERTY_AUDIOEFFECTSDISCOVERY

The KSPROPERTY_AUDIOEFFECTSDISCOVERY enumeration defines a constant that is used by the list of audio processing objects (APOs).

Functions

 
AcceptInput

Provides input to the APO on one of its auxiliary inputs.
AddAuxiliaryInput

Adds an auxiliary input to the APO, and provides initialization parameters.
AERT_Allocate

The AERT_Allocate utility function allocates and locks a segment of memory for use by audio processing objects.
AERT_Free

The AERT_Free utility function releases (frees) memory that was locked by the AERT_Allocate function, for use by audio processing objects to process audio data.
ApoLog

Logs an APO event.
APOProcess

The APOProcess method causes the APO to make a processing pass.
CalcInputFrames

The CalcInputFrames method returns the number of input frames that an APO requires to generate a given number of output frames.
CalcOutputFrames

The CalcOutputFrames method returns the number of output frames that an APO requires for a given number of input frames.
Commit

After a change has been made, this method saves the changes.
CreateAudioMediaType

The CreateAudioMediaType function uses the format specified by the caller to create a media type object that describes the audio format.
CreateAudioMediaTypeFromUncompressedAudioFormat

The CreateAudioMediaTypeFromUncompressedAudioFormat function uses the information provided in the UNCOMPRESSEDAUDIOFORMAT structure to create a media type object that describes the audio format.
GetApoNotificationRegistrationInfo

Called by the system to allow clients to register to receive notification callbacks for APO endpoint and system effect notifications.
GetApoNotificationRegistrationInfo2

Called by the system to allow clients to register to receive notification callbacks for APO endpoint and system effect notifications. This method adds a parameter that can be used to determine the notifications types supported on the version of Windows running on the current device.
GetAt

Gets a property key from the property array of an item.
GetAudioFormat

The GetAudioFormat method returns the WAVEFORMATEX structure for the audio data format.
GetControllableSystemEffectsList

Implemented by System Effects Audio Processing Object (sAPO) audio effects to allow the caller to get the current list of effects.
GetCount

This method returns a count of the number of properties that are attached to the file.
GetDesiredReferenceStreamProperties

Requests a set of properties for the loopback stream, if they are supported on the associated audio endpoint.
GetEffectsList

The GetEffectsList method is used for retrieving the list of audio processing effects that are currently active, and stores an event to be signaled if the list changes.
GetFormat

The GetFormat method retrieves an IAudioMediaType representation of a custom format.
GetFormatCount

The GetFormatCount method retrieves the number of custom formats supported by the system effects audio processing object (sAPO).
GetFormatRepresentation

The GetFormatRepresentation method retrieves a string representation of the custom format so that it can be displayed on a user-interface.
GetInputChannelCount

GetInputChannelCount returns the input channel count (samples-per-frame) for this APO.
GetLatency

The GetLatency method returns the latency for this APO. Latency is the amount of time it takes a frame to traverse the processing pass of an APO.
GetPreferredInputFormat

Callback function that allows APOs to specify a preferred input format for the provided output format.
GetPreferredOutputFormat

Callback function that allows APOs to specify a preferred output format for the provided input format.
GetRealTimeWorkQueue

Gets the ID of a work queue that the APO can use to schedule tasks that need to run at a real-time priority.
GetRegistrationProperties

GetRegistrationProperties returns the registration properties of the audio processing object (APO).
GetUncompressedAudioFormat

The IAudioMediaType::GetUncompressedAudioFormat returns information about the audio data format.
GetValue

This method retrieves the data for a specific property.
HandleNotification

Called by the system to notify clients of changes to APO endpoints or system effects.
Initialize

The Initialize method initializes the APO and supports data of variable length.
IsCompressedFormat

The IsCompressedFormat method determines whether the audio data format is a compressed format.
IsEqual

The IsEqual method compares two media types and determines whether they are identical.
IsInputFormatSupported

Verifies that a specific auxiliary input format is supported by the APO.
IsInputFormatSupported

This method negotiates with the Windows Vista audio engine to establish a data format for the stream of audio data.
IsOutputFormatSupported

The IsOutputFormatSupported method is used to verify that a specific output format is supported.
LockForProcess

The LockForProcess method is used to verify that the APO is locked and ready to process data.
RemoveAuxiliaryInput

Removes an auxiliary input from the APO.
Reset

The Reset method resets the APO to its original state. This method does not cause any changes in the connection objects that are attached to the input or the output of the APO.
SetAudioDeviceModulesManager

Called by the system to pass an instance of IAudioDeviceModulesManager to Audio Processing Objects (APOs) that implement the IAudioDeviceModulesClient interface.
SetAudioSystemEffectState

Implemented by System Effects Audio Processing Object (sAPO) audio effects to allow the caller to set the state of effects.
SetValue

This method sets a property value or replaces or removes an existing value.
UnlockForProcess

The UnlockForProcess method releases the lock that was imposed on the APO by the LockForProcess method.

Interfaces

 
IApoAcousticEchoCancellation

This interface is implemented by APOs to enable acoustic echo cancellation (AEC) scenarios.
IApoAcousticEchoCancellation2

Extends IAcousticEchoCancellation to allow APOs to specify desired properties of the reference stream.
IApoAuxiliaryInputConfiguration

Provides methods that APOs can implement so that the audio engine can add and remove auxiliary input streams.
IApoAuxiliaryInputRT

The realtime-safe interface used to drive the auxiliary inputs of an APO.
IAudioDeviceModulesClient

Audio Processing Objects (APOs) implement this interface to obtain a reference to an IAudioDeviceModulesManager instance.
IAudioMediaType

The IAudioMediaType interface exposes methods that allow an sAPO to get information that is used to negotiate with the audio engine for the appropriate audio data format.
IAudioProcessingObject

System Effects Audio Processing Objects (sAPOs) are typically used in or called from real-time process threads.
IAudioProcessingObjectConfiguration

The IAudioProcessingObjectConfiguration interface is used to configure the APO. This interface uses its methods to lock and unlock the APO for processing.
IAudioProcessingObjectLoggingService

Represents a logging service for APOs.
IAudioProcessingObjectNotifications

Implemented by clients to register for and receive common audio-related notifications for APO endpoint and system effect notifications.
IAudioProcessingObjectNotifications2

Implemented by clients to register for and receive common audio-related notifications for APO endpoint and system effect notifications. This interface adds the ability to determine the notifications types supported on the on the version of Windows running on the current device.
IAudioProcessingObjectPreferredFormatSupport

This interface is implemented by APOs to enable them to specify preferred input or output formats.
IAudioProcessingObjectRT

This interface can operate in real-time mode and its methods can be called form real-time processing threads.
IAudioProcessingObjectRTQueueService

Represents a realtime work queue service for APOs.
IAudioSystemEffects

The IAudioSystemEffects interface uses the basic methods that are inherited from IUnknown, and must implement an Initialize method.
IAudioSystemEffects2

The IAudioSystemEffects2 interface was introduced with Windows 8.1 for retrieving information about the processing objects in a given mode.
IAudioSystemEffects3

Implemented by clients that require an APOInitSystemEffects3 structure to be passed into the IAudioProcessingObject::Initialize method.
IAudioSystemEffectsCustomFormats

The IAudioSystemEffectsCustomFormats interface is supported in Windows Vista and later versions of Windows.
IPropertyStore

This interface exposes methods used to enumerate and manipulate property values.

Structures

 
AcousticEchoCanceller_Reference_Input

Contains expanded information pertaining to the current Acoustic Echo Cancellation (AEC) configuration.
APO_NOTIFICATION

Represents a notification for a change to an APO endpoint or system effects.
APO_NOTIFICATION_DESCRIPTOR

Specifies a requested APO notification.
APO_REG_PROPERTIES

The APO_REG_PROPERTIES structure is used by IAudioProcessingObject::GetRegistrationProperties for returning the registration properties of an audio processing object (APO).
APOInitBaseStruct

The APOInitBaseStruct structure is the base initialization header that must precede other initialization data in IAudioProcessingObject::Initialize.
APOInitSystemEffects

The APOInitSystemEffects structure gets passed to the system effects APO for initialization.
APOInitSystemEffects2

The APOInitSystemEffects2 structure was introduced with Windows 8.1, to make it possible to provide additional initialization context to the audio processing object (APO) for initialization.
APOInitSystemEffects3

Provides APO initialization parameters, extending APOInitSystemEffects2 to add the ability to specify a service provider for logging.
AUDIO_ENDPOINT_PROPERTY_CHANGE_APO_NOTIFICATION_DESCRIPTOR

Specifies an endpoint property change APO notification.
AUDIO_ENDPOINT_PROPERTY_CHANGE_NOTIFICATION

Represents a property change APO notification.
AUDIO_ENDPOINT_VOLUME_APO_NOTIFICATION_DESCRIPTOR

Specifies an endpoint volume APO notification.
AUDIO_ENDPOINT_VOLUME_CHANGE_NOTIFICATION

Represents an audio endpoint volume change APO notification.
AUDIO_ENDPOINT_VOLUME_CHANGE_NOTIFICATION2

Represents an audio endpoint volume change APO notification. This is an updated version of AUDIO_ENDPOINT_VOLUME_CHANGE_NOTIFICATION that provides additional information in about the volume change event.
AUDIO_ENVIRONMENT_STATE_CHANGE_NOTIFICATION

Represents an audio environment change APO notification.
AUDIO_MICROPHONE_BOOST_APO_NOTIFICATION_DESCRIPTOR

Specifies an endpoint microphone boost APO notification.
AUDIO_MICROPHONE_BOOST_NOTIFICATION

Represents an audio microphone boost APO notification.
AUDIO_SYSTEMEFFECT

Represents a System Effects Audio Processing Object (sAPO) audio effect.
AUDIO_SYSTEMEFFECTS_PROPERTY_CHANGE_NOTIFICATION

Represents a system audio effect APO notification.
AUDIO_VOLUME_NOTIFICATION_DATA2

Represents information about a volume change notification event. This structure is used by the AUDIO_ENDPOINT_VOLUME_CHANGE_NOTIFICATION2 structure.
KSP_PINMODE

The KSP_PINMODE structure specifies the pin property and the supported audio processing modes for a pin factory.
MDEVICECAPSEX

The MDEVICECAPSEX structure contains device capability information for Plug and Play (PnP) device drivers.
MIDIOPENDESC

The MIDIOPENDESC structure is a client-filled structure that provides information about how to open a MIDI device.
UNCOMPRESSEDAUDIOFORMAT

The UNCOMPRESSEDAUDIOFORMAT structure specifies the frame rate, channel mask, and other attributes of the uncompressed audio data format.
WAVEFORMATEX

The WAVEFORMATEX structure specifies the data format of a wave audio stream.