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.
AUDIO_SYSTEMEFFECT_STATE

Specifies the state of a System Effects Audio Processing Object (sAPO) audio effect.
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.
Activate

The Activate method enables or disables the audio device under program control.
Activate

The Activate method activates or deactivates the synthesizer sink.
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.
AssignChannelToBuses

AssignChannelToBuses is unsupported and may be altered or unavailable in the future.
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.
Close

The Close method closes a DirectMusic "port", which is a DirectMusic term for a device that sends or receives music data.
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.
Download

The Download method downloads a wave or instrument definition to the synthesizer.
GetApoNotificationRegistrationInfo

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

The GetAppend method outputs the number of additional wave samples that the DirectMusic "port" needs to have appended to the end of a download buffer.
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.
GetChannelPriority

The GetChannelPriority method outputs the priority of a MIDI channel.
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.
GetDesiredBufferSize

The GetDesiredBufferSize method retrieves the synthesizer's preferred buffer size, expressed in samples.
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.
GetFormat

The GetFormat method retrieves information about the wave 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.
GetLatencyClock

The GetLatencyClock method retrieves a reference to the IReferenceClock interface (described in the Microsoft Windows SDK documentation) of the reference-clock object that tracks the current mix time.
GetLatencyClock

The GetLatencyClock method retrieves the latency clock, which measures the progress of the output audio stream.
GetPortCaps

The GetPortCaps method retrieves the capabilities of a DirectMusic "port", which is a DirectMusic term for a device that sends or receives music data.
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).
GetRunningStats

The GetRunningStats method retrieves current information about the state of the synthesizer so that an application can tell how the synth is performing.
GetUncompressedAudioFormat

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

This method retrieves the data for a specific property.
GetVoiceState

GetVoiceState is unsupported and may be altered or unavailable in the future.
HandleNotification

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

The Init method initializes the synth-sink object.
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.
Open

The Open method opens a DirectMusic synthesizer "port".
PlayBuffer

The PlayBuffer method downloads a stream of MIDI messages to the synthesizer.
PlayVoice

PlayVoice is unsupported and may be altered or unavailable in the future.
Refresh

Refresh is unsupported and may be altered or unavailable in the future.
RefTimeToSample

The RefTimeToSample method converts a reference time to a sample time.
RemoveAuxiliaryInput

Removes an auxiliary input from the APO.
Render

The Render method is called by the synth sink to render to a buffer in the audio stream.
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.
SampleToRefTime

The SampleToRefTime method converts a sample time to a reference time.
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.
SetChannelPriority

The SetChannelPriority method sets the priority of a MIDI channel.
SetDirectSound

The SetDirectSound method connects the synthesizer sink with an existing DirectSound object and a DirectSound buffer.
SetMasterClock

The SetMasterClock method provides the synthesizer with a master time source, which the synthesizer requires to synchronize itself with the rest of DirectMusic.
SetMasterClock

The SetMasterClock method provides the synth sink with a master time source, which is required for synchronization with the rest of DirectMusic.
SetNumChannelGroups

The SetNumChannelGroups method instructs the synthesizer to set its number of channel groups to a new value.
SetSynthSink

The SetSynthSink method establishes the connection of the synth to the wave sink.
SetValue

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

StopVoice is unsupported and may be altered or unavailable in the future.
Unload

The Unload method unloads a DLS resource (waveform or articulation data for a MIDI instrument) that was previously downloaded by a call to IDirectMusicSynth::Download.
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.
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.
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.
IDirectMusicSynth

The IDirectMusicSynth interface is used by DirectMusic to communicate with user-mode synthesizers.
IDirectMusicSynth8

IDirectMusicSynth8is unsupported and may be altered or unavailable in the future.
IDirectMusicSynthSink

The IDirectMusicSynthSink interface is now largely obsolete and is supported only by versions of DirectMusic before DirectX 8.
IPropertyStore

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

Structures

 
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_SYSTEMEFFECT

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

Represents a system audio effect APO notification.
DMUS_VOICE_STATE

DMUS_VOICE_STATE is not supported and may be altered or unavailable in the future.
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.