Creates and configures a mastering voice.
public:
HRESULT CreateMasteringVoice(
IXAudio2MasteringVoice **ppMasteringVoice,
UINT32 InputChannels,
UINT32 InputSampleRate,
UINT32 Flags,
LPCWSTR szDeviceId,
const XAUDIO2_EFFECT_CHAIN *pEffectChain,
AUDIO_STREAM_CATEGORY StreamCategory
)
ppMasteringVoice
Type: IXAudio2MasteringVoice **
[out] If successful, returns a pointer to the new IXAudio2MasteringVoice object.
InputChannels
Type: UINT32
Number of channels the mastering voice expects in its input audio. InputChannels must be less than or equal to XAUDIO2_MAX_AUDIO_CHANNELS.
You can set InputChannels to XAUDIO2_DEFAULT_CHANNELS, which causes XAudio2 to try to detect the system speaker configuration setup.
InputSampleRate
Type: UINT32
Sample rate of the input audio data of the mastering voice. This rate must be a multiple of XAUDIO2_QUANTUM_DENOMINATOR. y InputSampleRate must be between XAUDIO2_MIN_SAMPLE_RATE and XAUDIO2_MAX_SAMPLE_RATE.
You can set InputSampleRate to XAUDIO2_DEFAULT_SAMPLERATE, with the default being 48000 on Xbox One.
Flags
Type: UINT32
Flags that specify the behavior of the mastering voice. This is either zero or a bitwise-OR combination of the values listed in the following table.
| Flag | Value | Description |
|---|---|---|
| XAUDIO2_EXCLUDE_FROM_GAME_DVR_CAPTURE | 0x4000 | Prevents Game DVR from recording this mastering voice. |
szDeviceId
Type: LPCWSTR
[in, optional] Identifier of the device to receive the output audio. Specifying the default value of NULL causes XAudio2 to select the global default audio device.
pEffectChain
Type: XAUDIO2_EFFECT_CHAIN *
[in, optional] Pointer to an XAUDIO2_EFFECT_CHAIN structure that describes an effect chain to use in the mastering voice, or NULL to use no effects.
StreamCategory
Type: AUDIO_STREAM_CATEGORY
[in] The audio stream category to use for this mastering voice.
Type: HRESULT
Returns S_OK if successful; otherwise, an error code. Returns ERROR_NOT_FOUND if no default audio device exists and NULL is passed in as the szDeviceId parameter.
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
Mastering voices receive the output of one or more source or submix voices. They process the data, and send it to the audio output device.
Typically, you should create a mastering voice with an input sample rate that will be used by the majority of the title’s audio content. The mastering voice performs a sample rate conversion from this input sample rate to the actual device output rate.
You cannot create a source or submix voices until a mastering voice exists. You cannot destroy a mastering voice if any source or submix voices still exist.
Mastering voices are always processed after all source and submix voices. This means that you need not specify a ProcessingStage parameter to control the processing order.
XAudio2 only allows one mastering voice to exist at once. If you attempt to create more than one voice, XAUDIO2_E_INVALID_CALL is returned. If an additional mastering voice is needed, for example for an output device with a different audio category set, you will need to create an additional XAudio2 instance.
When first created, mastering voices are in the started state.
It is invalid to call CreateMasteringVoice from within a callback (that is, IXAudio2EngineCallback or IXAudio2VoiceCallback). If you call CreateMasteringVoice within a callback, it returns XAUDIO2_E_INVALID_CALL.
The XAUDIO2_EFFECT_CHAIN that is passed in as the pEffectChain argument and any XAUDIO2_EFFECT_DESCRIPTOR information contained within it are no longer needed after CreateMasteringVoice successfully completes, and may be deleted immediately after CreateMasteringVoice is called.
Header: Declared in xaudio2.h.
Library: Use xaudio2.lib.