MCI_SETAUDIO

This MCI command message sets various values associated with audio playback and capture.

Parameters

DWORD lParam1

The following flags apply to all devices supporting MCI_SETAUDIO:


MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window that receives this message is specified in the dwCallback field of the data structure identified by lParam2.

MCI_TEST

Queries the device to determine if it can execute the command. The device returns an error if it is incapable of executing the command. It returns no error if it can handle the command. MCI returns control to the application without executing the command.

MCI_WAIT

Specifies that the set operation should finish before MCI returns control to the application.

MCI_DGV_SETAUDIO_ITEM

Indicates an audio constant is specified in the dwAdjustParm field of the data structure identified by lParam2. The constant identifies the value which is being set. The following constants are defined:


MCI_DGV_SETAUDIO_BASS

Indicates that the audio low frequency level is specified as a factor in the dwValue field of the data structure identified by lParam2.

MCI_DGV_SETAUDIO_TREBLE

Indicates that the audio high-frequency level is specified as a factor in the dwValue field of the data structure identified by lParam2.

MCI_DGV_SETAUDIO_SOURCE

Indicates that a constant specifying the source of audio input is included in the dwValue field of the data structure identified by lParam2. The following constants are defined for the audio input sources:

MCI_DGV_SETAUDIO_SOURCE_LEFT—

Specifies the left audio channel.

MCI_DGV_SETAUDIO_SOURCE_RIGHT—

Specifies the right audio channel.

MCI_DGV_SETAUDIO_SOURCE_AVERAGE—

Specifies the average of the left and right audio channels.

MCI_DGV_SETAUDIO_SOURCE_STEREO—

Specifies stereo.

MCI_DGV_SETAUDIO_STREAM

Indicates an audio-stream is specified in the dwValue field of the data structure identified by lParam2. The integer value specifies the audio stream played back from the workspace. If the stream is not specified, the first physically interleaved audio stream is played.

MCI_DGV_SETAUDIO_VOLUME

Indicates that the audio level for one or both audio channels is specified as a factor in the dwValue field of the data structure identified by lParam2. If the left and right volumes have been set to different values, then the ratio of left to right volume is approximately unchanged.

MCI_DGV_SETAUDIO_AVGBYTESPERSEC

Indicates that the average number of bytes is specified in the dwValue field of the data structure identified by lParam2. This value sets the average number of bytes per second for playing or recording in the PCM and ADPCM formats. The file is saved in this format.

MCI_DGV_SETAUDIO_BITSPERSAMPLE

Indicates that the number of bits per sample is specified in the dwValue field of the data structure identified by lParam2. This value sets the number of bits per sample played or recorded in the PCM format. The file is saved in this format.

MCI_DGV_SETAUDIO_BLOCKALIGN

Indicates that the data block alignment is specified in the dwValue field of the data structure identified by lParam2. This value sets the alignment of data blocks relative to the start of input waveform data.

MCI_DGV_SETAUDIO_SAMPLESPERSEC

Indicates that the sample rate is specified in the dwValue field of the data structure identified by lParam2. This value sets the sample rate for playing and recording with the PCM and ADPCM algorithms. The file is saved in this format.


MCI_DGV_SETAUDIO_CLOCKTIME

When used with MCI_DGV_SETAUDIO_OVER, indicates that the time specified is in milliseconds and is absolute time. (This time is not in step with the playing of the workspace.)

MCI_DGV_SETAUDIO_ALG

Indicates the lpstrAlgorithm field of the MCI_DGV_SETAUDIO_PARMS data structure contains a pointer to a buffer containing the name of an audio compression algorithm. The compression algorithm is used by subsequent MCI_RESERVE or MCI_RECORD commands. The available algorithms are device dependent. If the algorithm is incompatible with the current file format, the file format is changed to the default format for the algorithm.

MCI_DGV_SETAUDIO_LEFT

When used with MCI_SET_ON, enables the left audio channel. When used with MCI_SET_OFF, it disables the left audio channel. When this flag is used with the combination of MCI_DGV_SETAUDIO_VALUE and MCI_DGV_SETAUDIO_VOLUME, it sets the volume of the left audio channel. When this flag is used with MCI_DGV_SETAUDIO_SOURCE, it specifies the left audio channel as the source for the audio input digitizer.

MCI_DGV_SETAUDIO_OVER

Specifies a transition length parameter is included in the dwOver field of the data structure identified by lParam2. The length value specifies how long (in units of the current time format) it should take to make a change that uses a factor. If this flag is not used, changes occur immediately.

MCI_DGV_SETAUDIO_QUALITY

Indicates the lpstrQuality field of the MCI_DGV_SETAUDIO_PARMS data structure contains a pointer to a buffer defining the audio quality. A text-string within the buffer specifies the characteristics of the audio compression algorithm.

The MCI_DGV_SETAUDIO_ALG flag can be used to select a quality desciptor for the specified algorithm. If this flag is omitted then the current algorithm is used.

The algorithms and descriptor names available depend on the device. Each device will supply documentation for the available algorithms and a description of the applicable descriptor names. The MCI_QUALITY command can define additional descriptor names.

MCI_DGV_SETAUDIO_RIGHT

When used with MCI_SET_ON, enables the right audio channel. When used with MCI_SET_OFF, it disables the right audio channel. When this flag is used with the combination of MCI_DGV_SETAUDIO_VALUE and MCI_DGV_SETAUDIO_VOLUME, it sets the volume of the right audio channel.

MCI_DGV_SETAUDIO_RECORD

Specifies whether recording should include or exclude audio data. When combined with MCI_SET_ON, audio data is recorded. When combined with MCI_SET_OFF, audio data is excluded. The default includes audio data.

MCI_DGV_SETAUDIO_VALUE

Indicates that a value is specified in the dwValue field of the data structure identified by lParam2. The meaning of the value is specified by the constant defined for the MCI_DGV_SETAUDIO_ITEM flag.

MCI_DGV_SETAUDIO_INPUT

Modifies the bass, treble, or volume flag so that it affects the input signal and modifies what is recorded. If possible, this is the default when monitoring the input.

MCI_SETAUDIO_OUTPUT

Modifies the bass, treble, or volume flag so that it modifies only the played signal and not what is recorded. If possible, this is the default when monitoring the input.

MCI_SET_ON

Enables the specified audio channel.

MCI_SET_OFF

Disables the specified audio channel.

LPMCI_DGV_SETAUDIO_PARMS lParam2

Specifies a far pointer to the MCI_DGV_SETAUDIO_PARMS data structure.

Return Value

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

Some values are specified as factors. For these values, 0 represents a minimal amount of the specified characteristic, and 1000 represents the maximum value. The linearity of the mapping for these values is device-specific. If a device cannot set the requested value, it does the best it can, and it returns the actual values of the specified characteristics in response to the MCI_STATUS command.