(Page 1 of 1 in this chapter)

Chapter 4

Using WAVE Functions

4.1 Supported WAVE Functions

4.2 Supported WAVE Audio Formats

4.3 Determining Supported WAVE Formats

: 4.3.1 Using waveInGetDevCaps and waveOutGetDevCaps
: 4.3.2 Using waveInOpen and waveOutOpen

4.4 The Audio Compression Manager

4.5 WAVE Device IDs

: 4.5.1 Managing I/O Buffers

4.1 Supported WAVE Functions

The Microsoft WAVE API enables applications to use audio devices for playback and recording. The NMS WAVE driver enables applications to use Microsoft WAVE API functions to play and record audio on NMS hardware. This chapter describes WAVE API calls that are available through the NMS WAVE driver.
The Microsoft WAVE API provides functions for controlling two device classes: waveIn, and waveOut. WaveIn functions control audio devices for low level WAVE audio input. waveOut functions control audio devices for low level WAVE audio output. The NMS Wave driver supports all waveIn and waveOut functions except waveOutSetPitch, waveOutGetPitch and waveOutBreakLoop.
The NMS WAVE driver must be used in conjunction with the NMS TSP. It is not intended to serve as a general-purpose stand-alone WAVE driver. It will, however, respond properly when queried by the Windows multimedia subsystem. For example, if both the NMS WAVE driver and the NMS TSP are installed, an application that enumerates waveIn and waveOut devices will see the appropriate number of NMSWAVEINxxx and NMSWAVEOUTxxx devices.

4.2 Supported WAVE Audio Formats

The NMS WAVE driver, working with the NMS TSP, supports the following audio formats: Audio Format Sampling Rate mu-law or A-law PCM 8 bits at 8 kHz NMS VCE ADPCM 16, 24, 32, and 64 Kbp/s OKI ADPCM (Dialogic VOX format) 24 and 32 Kbp/s Microsoft PCM 16 bits at 8 kHz or 8 or 16 bits at 11 kHz
Other formats may also be used on NMS hardware by using the format mapping capabilities of the Audio Compression Manager (ACM). For more information about the ACM, refer to Section 4.4.

Audio Format	Sampling Rate
mu-law or A-law PCM	8 bits at 8 kHz
NMS VCE ADPCM	16, 24, 32, and 64 Kbp/s
OKI ADPCM (Dialogic VOX format)	24 and 32 Kbp/s
Microsoft PCM	16 bits at 8 kHz or 8 or 16 bits at 11 kHz

4.3 Determining Supported WAVE Formats

Use the following functions to determine the audio formats supported by particular WAVE devices:

waveInGetDevCaps

waveOutGetDevCaps

waveInOpen

waveOutOpen

4.3.1 Using waveInGetDevCaps and waveOutGetDevCaps

Applications can use waveInGetDevCaps and waveOutGetDevCaps to determine which standard audio formats are supported by particular WAVE devices. Both functions return the dwFormats mask in the WAVEINCAPS and WAVEOUTCAPS structures.
The following table lists the formats are reported in the dwFormats mask and supported by the NMS WAVE driver:

Format
Description

Supported directly in the NMS WAVE Driver

WAVE_FORMAT_1M08

11.025 kHz, mono, 8-bit

Yes

WAVE_FORMAT_1M16

11.025 kHz, mono, 16-bit

Yes

WAVE_FORMAT_1S08

11.025 kHz, stereo, 8-bit

No

WAVE_FORMAT_1S16

11.025 kHz, stereo, 16-bit

No

WAVE_FORMAT_2M08

22.05 kHz, mono, 8-bit

No

WAVE_FORMAT_2M16

22.05 kHz, mono, 16-bit

No

WAVE_FORMAT_2S08

22.05 kHz, stereo, 8-bit

No

WAVE_FORMAT_2S16

22.05 kHz, stereo, 16-bit

No

WAVE_FORMAT_4M08

44.1 kHz, mono, 8-bit

No

WAVE_FORMAT_4M16

44.1 kHz, mono, 16-bit

No

WAVE_FORMAT_4S08

44.1 kHz, stereo, 8-bit

No

WAVE_FORMAT_4S16

44.1 kHz, stereo, 16-bit

No

Format	Description	Supported directly in the NMS WAVE Driver
`WAVE_FORMAT_1M08`	11.025 kHz, mono, 8-bit	Yes
`WAVE_FORMAT_1M16`	11.025 kHz, mono, 16-bit	Yes
`WAVE_FORMAT_1S08`	11.025 kHz, stereo, 8-bit	No
`WAVE_FORMAT_1S16`	11.025 kHz, stereo, 16-bit	No
`WAVE_FORMAT_2M08`	22.05 kHz, mono, 8-bit	No
`WAVE_FORMAT_2M16`	22.05 kHz, mono, 16-bit	No
`WAVE_FORMAT_2S08`	22.05 kHz, stereo, 8-bit	No
`WAVE_FORMAT_2S16`	22.05 kHz, stereo, 16-bit	No
`WAVE_FORMAT_4M08`	44.1 kHz, mono, 8-bit	No
`WAVE_FORMAT_4M16`	44.1 kHz, mono, 16-bit	No
`WAVE_FORMAT_4S08`	44.1 kHz, stereo, 8-bit	No
`WAVE_FORMAT_4S16`	44.1 kHz, stereo, 16-bit	No

4.3.2 Using waveInOpen and waveOutOpen

Applications can also determine whether a device supports a particular format (standard or nonstandard) by calling waveOutOpen or waveInOpen with the WAVE_FORMAT_QUERY flag. The following example uses this technique to determine whether a waveform-audio device supports a specified format:

// Returns MMSYSERR_NOERROR if the format is supported, // WAVEERR_BADFORMAT if the format is not supported, and one of the // other MMSYSERR_ error codes if there are other errors encountered // in opening the specified waveform-audio device. MMRESULT IsFormatSupported(LPWAVEFORMATEX pwfx, UINT uDeviceID) { return (waveOutOpen( NULL, \* Pointer can be NULL for query *\ uDeviceID, \* Device identifier *\ pwfx, \* Defines requested format *\ NULL, \* No callback *\ NULL, \* No instance data *\ WAVE_FORMAT_QUERY)); \* Query only, do not open device*\ }
This technique for determining non-standard format support also applies to waveform-audio input devices. The only difference is that waveInOpen is used in place of waveOutOpen to query for format support.
To determine whether a particular waveform-audio data format is supported by any waveform-audio device on the system, call the appropriate wavexxOpen function, but specify the WAVE_MAPPER constant used in the uDeviceID argument.
The table below shows which values are required in the wFormatTag, nSamplesPerSec, and wBitsPerSample fields of the WAVEFORMATEX structure for each supported format: . Audio Format Sampling Rate WformatTag nSamplesPerSec wBitsPerSample mu-law PCM 8 bits at 8 kHz WAVE_FORMAT_MULAW 8000 8 A-law PCM 8 bits at 8 kHz WAVE_FORMAT_ALAW 8000 8 NMS VCE ADPCM 2 bits at 8 kHz WAVE_FORMAT_NMS_VBXADPCM 8000 2 NMS VCE ADPCM 3 bits at 8 kHz WAVE_FORMAT_NMS_VBXADPCM 8000 3 NMS VCE ADPCM 4 bits at 8kHz WAVE_FORMAT_NMS_VBXADPCM 8000 4 NMS VCE ADPCM 8 bits at 8 kHz WAVE_FORMAT_NMS_VBXADPCM 8000 8 OKI ADPCM 4 bits at 6 kHz WAVE_FORMAT_OKI_ADPCM 6000 4 OKI ADPCM 4 bits at 8 kHz WAVE_FORMAT_OKI_ADPCM 8000 4 PCM 16 bits at 8 kHz WAVE_FORMAT_PCM 8000 16 PCM 8 bits at 11 kHz WAVE_FORMAT_PCM 11000 8 PCM 16 bits at 11 kHz WAVE_FORMAT_PCM 11000 16
The following table shows the field in the WAVEFORMATEX structure that is common for all supported formats: nChannels nAvgBytesPerSec nBlockAlign cbSize 1 Not used. Not used. 0 Note: The nChannels field should always be set to 1 to indicate monaural playing and recording. There is no support for stereo (dual track) audio data. Dual track audio data can be played without error but will not sound as expected.

Audio Format	Sampling Rate	WformatTag	nSamplesPerSec	wBitsPerSample
mu-law PCM	8 bits at 8 kHz	`WAVE_FORMAT_MULAW`	8000	8
A-law PCM	8 bits at 8 kHz	`WAVE_FORMAT_ALAW`	8000	8
NMS VCE ADPCM	2 bits at 8 kHz	`WAVE_FORMAT_NMS_VBXADPCM`	8000	2
NMS VCE ADPCM	3 bits at 8 kHz	`WAVE_FORMAT_NMS_VBXADPCM`	8000	3
NMS VCE ADPCM	4 bits at 8kHz	`WAVE_FORMAT_NMS_VBXADPCM`	8000	4
NMS VCE ADPCM	8 bits at 8 kHz	`WAVE_FORMAT_NMS_VBXADPCM`	8000	8
OKI ADPCM	4 bits at 6 kHz	`WAVE_FORMAT_OKI_ADPCM`	6000	4
OKI ADPCM	4 bits at 8 kHz	`WAVE_FORMAT_OKI_ADPCM`	8000	4
PCM	16 bits at 8 kHz	`WAVE_FORMAT_PCM`	8000	16
PCM	8 bits at 11 kHz	`WAVE_FORMAT_PCM`	11000	8
PCM	16 bits at 11 kHz	`WAVE_FORMAT_PCM`	11000	16

nChannels	nAvgBytesPerSec	nBlockAlign	cbSize
1	Not used.	Not used.	0

4.4 The Audio Compression Manager

The Audio Compression Manager (ACM) is a part of the Windows multimedia subsystem. The ACM uses driver-interface mapper hooks for WAVE devices. This allows the ACM to decode or encode WAVE data before passing the data to WAVE device drivers. The ACM can also search for data converters to translate audio data into appropriate formats for destination devices.
When an application uses waveOutOpen or waveInOpen to open a WAVE device for input or output, the application must specify the WAVE data format in the fdwOpen and the device in the uDeviceID arguments. The following rules apply:

If fdwOpen does not specify the WAVE_MAPPED flag, the multimedia subsystem tries to use the specified format directly with the specified device ID, and the function fails if the device does not support the format.

If fdwOpen specifies the WAVE_MAPPED flag, the uDeviceID parameter must specify the waveform-audio device to which the ACM will map. The multimedia subsystem uses the ACM to query the WAVE device to see if the device supports the given format. If the device does not support the format, the ACM searches for a CODEC or converter that converts the specified format into a format that is supported by the device specified by uDeviceID. If the search is successful, the ACM can honor requests to play or record the format originally requested, even though the waveform-audio device does not directly support that format. This is transparent to the application.

4.5 WAVE Device IDs

When the Windows NT multimedia subsystem enumerates waveIn and waveOut devices, lines that have been configured by the NMS TSP appear as both waveIn and waveOut devices. These appear as NMS WAVE000 - NMS WAVEnnn, where nnn is one less than the number of NMS lines configured on the system.
For example, if an AG-8 board (a Natural MicroSystems eight-port analog board) is configured with the NMS TSP, the NMS WAVE driver responds to enumeration requests with NMS WAVE000 through NMS WAVE007 for both waveIn and waveOut devices. The sequence in which audio hardware and NMS WAVE driver software are installed on the system determines the WAVE device ID numbers assigned to NMS board ports.
For example, if you install the NMS TAPI driver and sound card on a computer that includes an AG-8 board, the audio input and output devices are assigned the following ID numbers:

I/O Device

ID Number
(sound card installed first)

ID Number
(NMS TAPI installed first)

Sound card

0

8

AG-8 port 1

1

0

AG-8 port 2

2

1

AG-8 port 3

3

2

AG-8 port 4

4

3

AG-8 port 5

5

4

AG-8 port 6

6

5

AG-8 port 7

7

6

AG-8 port 8

8

7

Note: Windows NT assigns device ID numbers at load time. When an application uses the Windows multimedia subsystem, the multimedia subsystem enumerates both the waveIn and the waveOut devices at the time the program is loaded. Calls to waveInGetNumDevs or waveOutGetNumDevs retrieve information cached by the multimedia subsystem at load time.

I/O Device	ID Number (sound card installed first)	ID Number (NMS TAPI installed first)
Sound card	0	8
AG-8 port 1	1	0
AG-8 port 2	2	1
AG-8 port 3	3	2
AG-8 port 4	4	3
AG-8 port 5	5	4
AG-8 port 6	6	5
AG-8 port 7	7	6
AG-8 port 8	8	7

4.5.1 Managing I/O Buffers

Applications that use WAVE functions must manage buffered I/O. Applications must copy output data into buffers to submit to the driver, and copy input data from buffers returned by the driver.
The NMS WAVE driver allows applications to submit buffers of any size when recording and playback. During recording and playback, applications can optimize performance by using buffers sizes that are multiples of the NMS board's base buffer size. Note: Using buffer sizes that are smaller than base buffer sizes may slow system performance because of increased CPU processing requirements.
The following table shows base buffer sizes for a variety of audio formats (constants for these formats appear in the header file nmstapi.h): Audio Data Format Sampling Rate Base Buffer Size WAVE_FORMAT_MULAW 8 kHz, 8 bit 4960 WAVE_FORMAT_ALAW 8 kHz, 8 bit 4960 WAVE_FORMAT_PCM 8 kHz, 16 bit 4960 WAVE_FORMAT_PCM 11 kHz, 8 bit 4950 WAVE_FORMAT_PCM 11 kHz, 16 bit 4840 WAVE_FORMAT_NMS_VBX_ADPCM 16 kHz 4998 WAVE_FORMAT_NMS_VBX_ADPCM 24 kHz 4960 WAVE_FORMAT_NMS_VBX_ADPCM 32 kHz 4920 WAVE_FORMAT_NMS_VBX_ADPCM 64 kHz 4860 WAVE_FORMAT_OKI_ADPCM 24 kHz 4980 WAVE_FORMAT_OKI_ADPCM 32 kHz 5000

Audio Data Format	Sampling Rate	Base Buffer Size
`WAVE_FORMAT_MULAW`	8 kHz, 8 bit	4960
`WAVE_FORMAT_ALAW`	8 kHz, 8 bit	4960
`WAVE_FORMAT_PCM`	8 kHz, 16 bit	4960
`WAVE_FORMAT_PCM`	11 kHz, 8 bit	4950
`WAVE_FORMAT_PCM`	11 kHz, 16 bit	4840
`WAVE_FORMAT_NMS_VBX_ADPCM`	16 kHz	4998
`WAVE_FORMAT_NMS_VBX_ADPCM`	24 kHz	4960
`WAVE_FORMAT_NMS_VBX_ADPCM`	32 kHz	4920
`WAVE_FORMAT_NMS_VBX_ADPCM`	64 kHz	4860
`WAVE_FORMAT_OKI_ADPCM`	24 kHz	4980
`WAVE_FORMAT_OKI_ADPCM`	32 kHz	5000

(Page 1 of 1 in this chapter)

tech_support@nmss.com