Inside Macintosh: Sound /

Chapter 3 - Sound Input Manager / Sound Input Manager Reference

Constants

Sound Input Device Information Selectors

You can call the SPBSetDeviceInfo and SPBGetDeviceInfo functions to set or get information about a sound input device. You pass each of those functions a sound input device information selector in the infoType parameter to specify the type of information you need. The available device information selectors are defined by constants.

IMPORTANT

Some of these selectors are intended for use only by the Sound Input Manager and other parts of the system software that need to interact directly with sound input device drivers. (For example, the Sound Input Manager sends the siCloseDriver selector to a sound input device driver when it is closing the device.) In general, applications should not use these reserved selectors.

CONST
   siActiveChannels        = 'chac';   {channels active}
   siActiveLevels          = 'lmac';   {levels active}
   siAGCOnOff              = 'agc ';   {automatic gain control state}
   siAsync                 = 'asyn';   {asynchronous capability}
   siChannelAvailable      = 'chav';   {number of channels available}
   siCloseDriver           = 'clos';   {reserved for internal use only}
   siCompressionAvailable  = 'cmav';   {compression types available}
   siCompressionFactor     = 'cmfa';   {current compression factor}
   siCompressionHeader     = 'cmhd';   {return compression header}
   siCompressionNames      = 'cnam';   {return compression type names}
   siCompressionType       = 'comp';   {current 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}
   siInitializeDriver      = 'init';   {reserved for internal use only}
   siInputGain             = 'gain';   {input gain level}
   siInputSource           = 'sour';   {input source selector}
   siInputSourceNames      = 'snam';   {input source names}
   siLevelMeterOnOff       = 'lmet';   {level meter state}
   siNumberChannels        = 'chan';   {current number of channels}
   siOptionsDialog         = 'optd';   {display options dialog box}
   siPauseRecording        = 'paus';   {reserved for internal use only}
   siPlayThruOnOff         = 'plth';   {play-through state}
   siRecordingQuality      = 'qual';   {recording quality}
   siSampleRate            = 'srat';   {current sample rate}
   siSampleRateAvailable   = 'srav';   {sample rates available}
   siSampleSize            = 'ssiz';   {current sample size}
   siSampleSizeAvailable   = 'ssav';   {sample sizes available}
   siStereoInputGain       = 'sgai';   {stereo input gain level}
   siTwosComplementOnOff   = 'twos';   {two's complement state}
   siUserInterruptProc     = 'user';   {reserved for internal use only}
   siVoxRecordInfo         = 'voxr';   {VOX record parameters}
   siVoxStopInfo           = 'voxs';   {VOX stop parameters}

Constant descriptions

siActiveChannels

Get or set the channels to record from. When setting the active channels, the data passed in is a long integer that is interpreted as a bitmap describing the channels to record from. For example, if bit 0 is set, then the first channel is made active. The samples for each active channel are interleaved in the application's buffer. When reading the active channels, the data returned is a bitmap of the active channels.

siActiveLevels

Get the current signal level for each active channel. The infoData parameter points to an array of integers, the size of which depends on the number of active channels. You can determine how many channels are active by calling SPBGetDeviceInfo with the siNumberChannels selector.

siAGCOnOff

Get or set the current state of the automatic gain control feature. The infoData parameter points to an integer, which is 0 if gain control is off and 1 if it is on.

siAsync

Determine whether the driver supports asynchronous recording functions. The infoData parameter points to an integer, which is 0 if the driver supports synchronous calls only and 1 otherwise. Some sound input drivers do not support asynchronous recording at all, and some might support asynchronous recording only on certain hardware configurations.

siChannelAvailable

Get the maximum number of channels this device can record. The infoData parameter points to an integer, which is the number of available channels.

siCloseDriver

The Sound Input Manager sends this selector when it closes a device previously opened with write permission. The sound input device driver should stop any recording in progress, deallocate the input hardware, and initialize local variables to default settings. Your application should never issue this selector directly. The infoData parameter is unused with this selector.

siCompressionAvailable

Get the number and list of compression types this device can produce. The infoData parameter points to an integer, which is the number of compression types, followed by a handle. The handle references a list of compression types, each of type OSType.

siCompressionFactor

Get the compression factor of the current compression type. For example, the compression factor for MACE 3:1 compression is 3. If a sound input device driver supports only compression type 'NONE', the returned compression type is 1. The infoData parameter points to an integer, which is the compression factor.

siCompressionHeader

Get a compressed sound header for the current recording settings. Your application passes in a pointer to a compressed sound header and the driver fills it in. Before calling SPBGetDeviceInfo with this selector, you should set the numFrames field of the compressed sound header to the number of bytes in the sound. When SPBGetDeviceInfo returns successfully, that field contains the number of sample frames in the sound. This selector is needed only by drivers that use compression types that are not directly supported by Apple. If you call this selector after recording a sound, your application can get enough information about the sound to play it or save it in a file. The infoData parameter points to a compressed sound header.

siCompressionNames

Get a list of names of the compression types supported by the sound input device. In response to a Status call, a sound input device driver returns, in the location specified by the infoData parameter, a handle to a block of memory that contains the names of all compression types supported by the driver. It is the driver's responsibility to allocate that block of memory, but it should not release it. The software issuing this selector is responsible for disposing of the handle. As a result, a device driver must detach any resource handles (by calling DetachResource) before returning them to the caller. The data in the handle has the same format as an 'STR#' resource: a two-byte count of the strings in the resource, followed by the strings themselves. The strings should occur in the same order as the compression types returned by the siCompressionAvailable selector. If the driver does not support compression, it returns siUnknownInfoType. If the driver supports compression but for some reason not all compression types are currently selectable, it returns a list of all available compression types.

siCompressionType

Get or set the compression type. Some devices allow the incoming samples to be compressed before being placed in your application's input buffer. The infoData parameter points to a buffer of type OSType, which is the compression type.

siContinuous

Get or set the state of continuous recording from this device. If recording is being turned off, the driver stops recording samples to its internal buffer. Only sound input device drivers that support asynchronous recording support continuous recording. The infoData parameter points to an integer, which is the state of continuous recording (0 is off, 1 is on).

siDeviceBufferInfo

Get the size of the device's internal buffer. This information can be useful when you want to modify sound input data at interrupt time. Note, however, that if a driver is recording continuously, then the size of the buffer passed to your sound input interrupt routine might be greater than the size this selector returns because data recorded between calls to SPBRecord as well as recorded during calls to SPBRecord will be sent to your interrupt routine. The infoData parameter points to a long integer, which is the size of the device's internal buffer.

siDeviceConnected

Get the state of the device connection. The infoData parameter points to an integer, which is one of the following constants:

               CONST
                  siDeviceIsConnected     = 1;
                  siDeviceNotConnected    = 0;
                  siDontKnowIfConnected   = -1;

The siDeviceIsConnected constant indicates that the device is connected and ready. The siDeviceNotConnected constant indicates that the device is not connected. The siDontKnowIfConnected constant indicates that the Sound Input Manager cannot determine whether the device is connected.

siDeviceIcon

Get the device's icon and icon mask. In response to a Status call, a sound input device driver should return, in the location specified by the infoData parameter, a handle to a block of memory that contains the icon and its mask in the format of an 'ICN#' resource. It is the driver's responsibility to allocate that block of memory, but it should not releasee it. The software issuing this selector is responsible for disposing of the handle. As a result, a device driver should detach any resource handles (by calling DetachResource) before returning them to the caller.

siDeviceName

Get the name of the sound input device. Your application must pass a pointer to a buffer that will be filled in with the device's name. The buffer needs to be large enough to hold a Str255 data type.

siInitializeDriver

The Sound Input Manager sends this selector when it opens a sound input device with write permission. The sound input device driver initializes local variables and prepares to start recording. If possible, the driver initializes the device to a sampling rate of 22 kHz, a sample size of 8 bits, mono recording, no compression, automatic gain control on, and all other features off. Your application should never issue this selector directly. The infoData parameter is unused with this selector.

siInputGain

Get and set the current sound input gain. If the available hardware allows adjustment of the recording gain, this selector lets you get and set the gain. In response to a Status call, a sound input driver returns the current gain setting. In response to a Control call, a sound input driver sets the gain level used for all subsequent recording to the specified value. The infoData parameter points to a 4-byte value of type Fixed ranging from 0.5 to 1.5, where 1.5 specifies maximum gain.

siInputSource

Get and set the current sound input source. If the available hardware allows recording from more than one source, this selector lets you get and set the source. In response to a Status call, a sound input driver returns the current source value; if the driver supports only one source, it returns siUnknownInfoType. In response to a Control call, a sound input driver sets the source of all subsequent recording to the value passed in. If the value is less than 1 or greater than the number of input sources, the driver returns paramErr; if the driver supports only one source, it returns siUnknownInfoType. The infoData parameter points to an integer, which is the index of the current sound input source.

siInputSourceNames

Get a list of the names of all the sound input sources supported by the sound input device. In response to a Status call, a sound input device driver returns, in the location specified by the infoData parameter, a handle to a block of memory that contains the names of all sound sources supported by the driver. It is the driver's responsibility to allocate that block of memory, but it should not release it. The software issuing this selector is responsible for disposing of the handle. As a result, a device driver must detach any resource handles (by calling DetachResource) before returning them to the caller. The data in the handle has the same format as an 'STR#' resource: a two-byte count of the strings in the resource, followed by the strings themselves. The strings should occur in the same order as the input sources returned by the siInputSource selector. If the driver supports only one source, it returns siUnknownInfoType. If the driver supports more than one source but for some reason not all of them are currently selectable, it returns a list of all available input sources.

siLevelMeterOnOff

Get or set the current state of the level meter. For calls to set the level meter, the infoData parameter points to an integer that indicates whether the level meter is off (0) or on (1). To get the level meter setting, the infoData parameter points to two integers; the first integer indicates the state of the level meter, and the second integer contains the level value of the meter. The level meter setting is an integer that ranges from 0 (no volume) to 255 (full volume).

siNumberChannels

Get or set the number of channels this device is to record. The infoData parameter points to an integer, which indicates the number of channels. Note that this selector determines the format of the data stream output by the driver. If the number of channels is 1, the driver should output monophonic data in response to a Read call. If the number of channels is 2, the driver should output interleaved stereo data.

siOptionsDialog

Determine whether the driver supports an Options dialog box (SPBGetDeviceInfo) or cause the driver to display the Options dialog box (SPBSetDeviceInfo). This dialog box is designed to allow the user to configure device-specific features of the sound input hardware. With SPBGetDeviceInfo, the infoData parameter points to an integer, which indicates whether the driver supports an Options dialog box (1 if it supports it, 0 otherwise). With SPBSetDeviceInfo, the infoData parameter is unused.

siPauseRecording

The Sound Input Manager uses this selector to get or set the current pause state. The sound input device driver continues recording but does not store the sampled data in a buffer. Your application should never issue this selector directly. The infoData parameter points to an integer, which indicates the state of pausing (0 is off, 1 is on).

siPlayThruOnOff

Get or set the current play-through state and volume. The infoData parameter points to an integer, which indicates the current play-through volume (1 to 7). If that integer is 0, then play-through is off.

siRecordingQuality

Get or set the current quality of recorded sound. The infoData parameter points to a buffer of type OSType, which is the recording quality. Currently three qualities are supported, defined by these constants:

                           CONST
                              siBestQuality           = 'best';
                              siBetterQuality         = 'betr';
                              siGoodQuality           = 'good';

These qualities are defined by the sound input device driver. Usually best means monaural, 8-bit, 22 kHz, sound with no compression.

siSampleRate

Get or set the sample rate to be produced by this device. The sample rate must be in the range 0 to 65535.65535 Hz. The sample rate is declared as a Fixed data type. In order to accommodate sample rates greater than 32 kHz, the most significant bit is not treated as a sign bit; instead, that bit is interpreted as having the value 32,768. The infoData parameter points to a buffer of type Fixed, which is the sample rate.

siSampleRateAvailable

Get the range of sample rates this device can produce. The infoData parameter points to an integer, which is the number of sample rates the device supports, followed by a handle. The handle references a list of sample rates, each of type Fixed. If the device can record a range of sample rates, the number of sample rates is set to 0 and the handle contains two rates, the minimum and the maximum of the range of sample rates. Otherwise, a list is returned that contains the sample rates supported. In order to accommodate sample rates greater than 32 kHz, the most significant bit is not treated as a sign bit; instead, that bit is interpreted as having the value 32,768.

siSampleSize

Get or set the sample size to be produced by this device. Because some compression formats require specific sample sizes, this selector might return an error when compression is used. The infoData parameter points to an integer, which is the sample size.

siSampleSizeAvailable

Get the range of sample sizes this device can produce. The infoData parameter points to an integer, which is the number of sample sizes the device supports, followed by a handle. The handle references a list of sample sizes, each of type Integer.

siStereoInputGain

Get and set the current stereo sound input gain. If the available hardware allows adjustment of the recording gain, this selector lets you get and set the gain for each of two channels (left or right). In response to a Status call, a sound input driver should return the current gain setting for the specified channel. In response to a Control call, a sound input driver should set the gain level used for all subsequent recording to the specified value. The infoData parameter points to two 4-byte values of type Fixed ranging from 0.5 to 1.5, where 1.5 specifies maximum gain. The first of these values is equivalent to the gain for the left channel and the second value is equivalent to the gain for the right channel.

siTwosComplementOnOff

Get or set the current state of the two's complement feature. This selector only applies to 8-bit data. (16-bit samples are always stored in two's complement format.) If on, the driver stores all samples in the application buffer as two's complement values (that is, -128 to 127). Otherwise, the driver stores the samples as offset binary values (that is, 0 to 255). The infoData parameter points to an integer, which is the current state of the two's complement feature (1 if two's complement output is desired, 0 otherwise).

siUserInterruptProc

The Sound Input Manager sends this selector to specify the sound input interrupt routine that the sound input device driver should call. Your application should never issue this selector directly. The infoData parameter points to a procedure pointer, which is the address of the sound input interrupt routine.

siVoxRecordInfo

Get or set the current VOX recording parameters. The infoData parameter points to two integers. The first integer indicates whether VOX recording is on or off (0 if off, 1 if on). The second integer indicates the VOX record trigger value. Trigger values range from 0 to 255 (0 is trigger immediately, 255 is trigger only on full volume).

siVoxStopInfo

Get or set the current VOX stopping parameters. The infoData parameter points to three integers. The first integer indicates whether VOX stopping is on or off (0 if off, 1 if on). The second integer indicates the VOX stop trigger value. Trigger values range from 0 to 255 (255 is stop immediately, 0 is stop only on total silence). The third integer indicates how many milliseconds the trigger value must be continuously valid for recording to be stopped. Delay values range from 0 to 65,535.