Inside Macintosh: Sound Manager

Legacy Document

Important: Sound Input Manager is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.

Getting and Setting Sound Input Device Information

You can get information about a specific sound input device and alter a sound input device's settings by calling the functions SPBGetDeviceInfo and SPBSetDeviceInfo . These functions accept sound input device information selectors that determine which information you need or want to change. The selectors currently available are defined by constants of type OSType .

Here is a list of the selectors that all sound input device drivers must support. For complete details on all the selectors described in this section, see "Sound Input Device Information Selectors" .



 
CONST

    siAsync                         = 'asyn';       {asynchronous capability}

    siChannelAvailable              = 'chav';       {number of channels available}

    siCompressionAvailable          = 'cmav';       {compression types available}

    siCompressionFactor             = 'cmfa';       {current compression factor}

    siCompressionType               = 'comp';       {compression type}

    siContinuous                    = 'cont';       {continuous recording}

    siDeviceBufferInfo              = 'dbin';       {size of interrupt buffer}

    siDeviceConnected               = 'dcon';       {input device connection status}

    siDeviceIcon                    = 'icon';       {input device icon}

    siDeviceName                    = 'name';       {input device name}

    siLevelMeterOnOff               = 'lmet';       {level meter state}

    siNumberChannels                = 'chan';       {current number of channels}

    siRecordingQuality              = 'qual';       {recording quality}

    siSampleRate                    = 'srat';       {current sample rate}

    siSampleRateAvailable           = 'srav';       {sample rates available}

    siSampleSizeAvailable           = 'ssav';       {sample sizes available}

    siSampleSize                    = 'ssiz';       {current sample size}

    siTwosComplementOnOff           = 'twos';       {two's complement state}

The Sound Input Manager defines several selectors that specifically help it interact with sound input device drivers. Your application should not use any of these selectors, but if you are implementing a sound input device driver, you need to support these selectors. They are:



 
CONST

    siCloseDriver                   = 'clos';       {release driver}

    siInitializeDriver              = 'init';       {initialize driver}

    siPauseRecording                = 'paus';       {pause recording}

    siUserInterruptProc             = 'user';       {set sound input interrupt routine}

Finally, there are a number of sound input device information selectors that sound input device drivers can optionally support. If you are writing an application, you can use these selectors to interact with a sound input device driver, but you should be aware that some drivers might not support all of them. To determine if a driver supports one of these selectors, you can use the SPBGetDeviceInfo function. If no errors are returned, then the selector is supported when using the SPBGetDeviceInfo and the SPBSetDeviceInfo functions.



 
CONST

    siActiveChannels                = 'chac';       {channels active}

    siActiveLevels                  = 'lmac';       {levels active}

    siAGCOnOff                      = 'agc ';       {automatic gain control state}

    siCompressionHeader             = 'cmhd';       {get compression header}

    siCompressionNames              = 'cnam';       {return compression type names}

    siInputGain                     = 'gain';       {input gain level}

    siInputSource                   = 'sour';       {input source selector}

    siInputSourceNames              = 'snam';       {input source names}

    siOptionsDialog                 = 'optd';       {display options dialog box}

    siPlayThruOnOff                 = 'plth';       {play-through state}

    siStereoInputGain               = 'sgai';       {stereo input gain level}

    siVoxRecordInfo                 = 'voxr';       {VOX record parameters}

    siVoxStopInfo                   = 'voxs';       {VOX stop parameters}

The format of the relevant data (either returned by the Sound Input Manager or provided by you) depends on the selector you provide. For example, if you want to determine the name of some sound input device, you can pass to the SPBGetDeviceInfo function the siDeviceName selector and a pointer to a 256-byte buffer. If the SPBGetDeviceInfo function can get the information, it fills that buffer with the name of the specified sound input device. Listing 43 illustrates one way you can determine the name of a particular sound input device.

Listing 43 Determining the name of a sound input device



 
FUNCTION MyGetDeviceName (myRefNum: LongInt; VAR dName: Str255): OSErr;

BEGIN

    MyGetDeviceName := SPBGetDeviceInfo(myRefNum, siDeviceName, Ptr(@dName));

END;

You can get the name and icon of all connected sound input devices without using sound input information selectors by using the SPBGetIndexedDevice function, which is described on [link] .

Some selectors cause the SPBGetDeviceInfo function to return data of other types. Listing 44 illustrates how to determine the number of channels, the sample rate, the sample size, and the compression type currently in use by a given sound input device. (The procedure defined in Listing 44 is called in the procedure defined in Listing 42 .)

Listing 44 Determining some sound input device settings



 
PROCEDURE MyGetDeviceSettings (myRefNum: LongInt; 

                                            VAR numChannels: Integer; 

                                            VAR sampleRate: Fixed; 

                                            VAR sampleSize: Integer; 

                                            VAR compressionType: OSType);

VAR

    myErr:          OSErr;

BEGIN

    {Get number of active channels.}

    myErr := SPBGetDeviceInfo (myRefNum, siNumberChannels, Ptr(@numChannels));

    {Get sample rate.}

    myErr := SPBGetDeviceInfo(myRefNum, siSampleRate, Ptr(@sampleRate));

    {Get sample size.}

    myErr := SPBGetDeviceInfo(myRefNum, siSampleSize, Ptr(@sampleSize));

    {Get compression type.}

    myErr := SPBGetDeviceInfo(myRefNum, siCompressionType, 

                                                                    Ptr(@compressionType));

END;

All of the selectors that return a handle allocate the memory for that handle in the current heap zone; you are responsible for disposing of that handle when you are done with it, and you should verify that there is enough memory for such a handle before calling the selector.

Inside Macintosh: Sound Manager

Legacy Document

Important: Sound Input Manager is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.