Carbon


Sound Input Device and Sound Component Information Selectors

Header: Sound.h

enum {
    siActiveChannels = 'chac',
    siActiveLevels = 'lmac',
    siAGCOnOff = 'agc ',
    siAsync = 'asyn',
    siAVDisplayBehavior = 'avdb',
    siChannelAvailable = 'chav',
    siCompressionAvailable = 'cmav',
    siCompressionChannels = 'cpct',
    siCompressionFactor = 'cmfa',
    siCompressionHeader = 'cmhd',
    siCompressionNames = 'cnam',
    siCompressionParams = 'evaw',
    siCompressionSampleRate = 'cprt',
    siCompressionType = 'comp',
    siContinuous = 'cont',
    siDecompressionParams = 'wave',
    siDeviceBufferInfo = 'dbin',
    siDeviceConnected = 'dcon',
    siDeviceIcon = 'icon',
    siDeviceName = 'name',
    siEQSpectrumBands = ''eqsb'',
    siEQSpectrumLevels = ''eqlv'',
    siEQSpectrumOnOff = ''eqlo'',
    siEQToneControlGain = ''eqtg'',
    siEQToneControlOnOff = ''eqtc'',
    siHardwareBalance = ''hbal'',
    siHardwareBalanceSteps = ''hbls'',
    siHardwareBass = ''hbas'',
    siHardwareBassSteps = ''hbst'',
    siHardwareBusy = ''hwbs'',
    siHardwareFormat = ''hwfm'',
    siHardwareMute = ''hmut'',
    siHardwareMuteNoPrefs = ''hmnp'',
    siHardwareTreble = ''htrb'',
    siHardwareTrebleSteps = ''hwts'',
    siHardwareVolume = ''hvol'',
    siHardwareVolumeSteps = ''hstp'',
    siHeadphoneMute = ''pmut'',
    siHeadphoneVolume = ''pvol'',
    siHeadphoneVolumeSteps = ''hdst'',
    siInputAvailable = ''inav'',
    siInputGain = ''gain'',
    siInputSource = ''sour'',
    siInputSourceNames = ''snam'',
    siLevelMeterOnOff = ''lmet'',
    siModemGain = ''mgai'',
    siMonitorAvailable = ''mnav'',
    siMonitorSource = ''mons'',
    siNumberChannels = ''chan'',
    siOptionsDialog = ''optd'',
    siOSTypeInputSource = ''inpt'',
    siOSTypeInputAvailable = ''inav'',
    siOutputDeviceName = ''onam'',
    siPlayThruOnOff = ''plth'',
    siPostMixerSoundComponent = ''psmx'',
    siPreMixerSoundComponent = ''prmx'',
    siQuality = ''qual'',
    siRateMultiplier = ''rmul'',
    siRecordingQuality = ''qual'',
    siSampleRate = ''srat'',
    siSampleRateAvailable = ''srav'',
    siSampleSize = ''ssiz'',
    siSampleSizeAvailable = ''ssav'',
    siSetupCDAudio = ''sucd'',
    siSetupModemAudio = ''sumd'',
    siSlopeAndIntercept = ''flap'',
    siSoundClock = ''sclk'',
    siUseThisSoundClock = ''sclc'',
    siSpeakerMute = ''smut'',
    siSpeakerVolume = ''svol'',
    siSSpCPULoadLimit = ''3dll'',
    siSSpLocalization = ''3dif'',
    siSSpSpeakerSetup = ''3dst'',
    siStereoInputGain = ''sgai'',
    siSubwooferMute = ''bmut'',
    siTwosComplementOnOff = ''twos'',
    siVolume = ''volu'',
    siVoxRecordInfo = ''voxr'',
    siVoxStopInfo = ''voxs'',
    siWideStereo = ''wide'',
    siSupportedExtendedFlags = ''exfl''
};

Constant descriptions

siActiveChannels

For a sound input device, 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

For a sound input device, 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

For a sound input device, 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

For a sound input device, 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.

siAVDisplayBehavior
siChannelAvailable

For a sound input device, get the maximum number of channels this device can record. The infoData parameter points to an integer, which is the number of available channels.

For a sound component, get the maximum number of channels this sound component can manage, as well as the channels themselves. The infoPtr parameter points to a structure of type SoundInfoList, which contains an integer (the number of available channels) and a handle to an array of integers (which represent the channel numbers themselves).

siCompressionAvailable

For a sound input device, 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.

For a sound component, get the number and list of compression types this sound component can manage. The infoPtr parameter points to a structure of type SoundInfoList, which contains the number of compression types, followed by a handle that references a list of compression types, each of type OSType.

siCompressionChannels
siCompressionFactor

For a sound input device, 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.

For a sound component, get information about the current compression type. The infoData parameter points to a compression information structure (CompressionInfo).

siCompressionHeader

For a sound input device, 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

For a sound input device, 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.

siCompressionParams
siCompressionSampleRate
siCompressionType

For a sound input device, get or set the compression type.

For a sound input device, 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.

For a sound component, get or set the current compression type. The infoPtr parameter points to a buffer of type OSType, which is the compression type.

siContinuous

For a sound input device, 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).

siDecompressionParams
siDeviceBufferInfo

For a sound input device, 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 function 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 function. The infoData parameter points to a long integer, which is the size of the device’s internal buffer.

siDeviceConnected

For a sound input device, get the state of the device connection. The infoData parameter points to an integer, which is one of three constants. See “Device Connection State Constants”.

siDeviceIcon

For a sound input device, 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 release 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

For a sound input device, 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.

siEQSpectrumBands
siEQSpectrumLevels
siEQSpectrumOnOff
siEQToneControlGain
siEQToneControlOnOff
siHardwareBalance
siHardwareBalanceSteps
siHardwareBass
siHardwareBassSteps
siHardwareBusy
siHardwareFormat
siHardwareMute

For a sound component, get or set the current mute state of the audio hardware. A value of 0 indicates that the hardware is not muted, and a value of 1 indicates that the hardware is muted. Not all sound components need to support this selector; it’s intended for sound output device components whose associated hardware can be muted.

siHardwareMuteNoPrefs
siHardwareTreble
siHardwareTrebleSteps
siHardwareVolume

For a sound component, get or set the current volume level of all sounds produced on the sound output device. The infoPtr parameter points to a long integer, where the high-order word represents the right volume level and the low-order word represents the left volume level. A volume level is specified by an unsigned 16-bit number: 0x0000 represents silence and 0x0100 represents full volume. (You can use the constant kFullVolume for full volume.) You can specify values larger than 0x0100 to overdrive the volume, although doing so might result in clipping. This selector applies to the volume of the output device. If a sound output device supports more than one output port (for example, both headphones and speakers), the siHardwareVolume selector applies to all those ports.

siHardwareVolumeSteps

For a sound component, get the number of audible volume levels supported by the audio hardware. If the device supports a range of volume levels (for example, 0x000 to 0x1000), you should return only the number of levels that are audible. The Sound Manager uses this information to handle the volume slider in the Alert Sounds control panel.

siHeadphoneMute

For a sound component, get or set the current mute state of the headphone. A value of 0 indicates that the headphone is not muted, and a value of 1 indicates that the headphone is muted. Not all sound components need to support this selector; it’s intended for sound output device components whose associated headphone can be muted.

siHeadphoneVolume

For a sound component, get or set the current volume level of all sounds produced on the headphone. The infoPtr parameter points to a long integer, where the high-order word represents the right volume level and the low-order word represents the left volume level. A volume level is specified by an unsigned 16-bit number: 0x0000 represents silence and 0x0100 represents full volume. (You can use the constant kFullVolume for full volume.) You can specify values larger than 0x0100 to overdrive the volume, although doing so might result in clipping. This selector applies to the volume of the headphones.

siHeadphoneVolumeSteps

For a sound component, get the number of audible volume levels supported by the headphones. If the headphones support a range of volume levels (for example, 0x000 to 0x1000), you should return only the number of levels that are audible.

siInputAvailable
siInputGain

For a sound input device, 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

For a sound input device, 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

For a sound input device, 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

For a sound input device, 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).

siModemGain

The constants in this enumeration are used to define information selectors for both sound input devices and sound components.

For a sound input device, you can call the SPBSetDeviceInfo and SPBGetDeviceInfo functions to set or get information about the 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.

More sound input device information selectors are described in “Sound Input Device Information Constants”.

The Sound Manager calls your sound component’s SoundComponentGetInfo and SoundComponentSetInfo functions to determine the capabilities of your component and to change those capabilities. It passes those functions a sound component information selector in the function’s selector parameter to specify the type of information it wants to get or set.

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.

For those selectors used by sound components, most can be passed to both SoundComponentGetInfo and SoundComponentSetInfo. Some of them, however, can be sent to only one or the other.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)