Inside Macintosh: Sound /: Chapter 3 - Sound Input Manager

Legacy Document

Important: Inside Macintosh: Sound 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.

Summary of the Sound Input Manager

Pascal Summary

Constants

CONST
   gestaltSoundAttr           = 'snd ';{sound attributes selector}
   
   {Gestalt response bit flags related to sound input}
   gestaltSoundIOMgrPresent   = 3;     {sound input routines available}
   gestaltBuiltInSoundInput   = 4;     {built-in input hw available}
   gestaltHasSoundInputDevice = 5;     {sound input device available}
   gestaltPlayAndRecord       = 6;     {built-in hw can play while recording}
   gestalt16BitSoundIO        = 7;     {built-in hw can handle 16-bit data}
   gestaltStereoInput         = 8;     {built-in hw can record stereo sounds}
   gestaltLineLevelInput      = 9;     {built-in input hw needs line level}
   
   {available information selectors for sound input device drivers}
   siActiveChannels        = 'chac';   {channels active}
   siActiveLevels          = 'lmac';   {levels active}
   siAGCOnOff              = 'agc ';   {automatic gain control state}
   siAsync                 = 'asyn';   {asynchronous capability}
   siChannelAvailable      = 'chav';   {number of channels available}
   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}
   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}
   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}
   siVoxRecordInfo         = 'voxr';   {VOX record parameters}
   siVoxStopInfo           = 'voxs';   {VOX stop parameters}
   
   {internal information selectors for sound input device drivers}
   siCloseDriver           = 'clos';   {release driver}
   siInitializeDriver      = 'init';   {initialize driver}
   siPauseRecording        = 'paus';   {pause recording}
   siUserInterruptProc     = 'user';   {set sound input interrupt routine}
   
   {sound-recording qualities}
   siBestQuality           = 'best';   {the best quality available}
   siBetterQuality         = 'betr';   {a quality better than good}
   siGoodQuality           = 'good';   {a good quality}
   
   {sound input device permissions}
   siReadPermission        = 0;        {open device for reading}
   siWritePermission       = 1;        {open device for reading/writing}
   
   {device-connection states}
   siDeviceIsConnected     = 1;        {device is connected and ready}
   siDeviceNotConnected    = 0;        {device is not connected}
   siDontKnowIfConnected   = -1;       {can't tell if device is connected}

Data Types

Sound Input Parameter Block

TYPE SPB =
RECORD
   inRefNum:            LongInt;    {reference number of input device}
   count:               LongInt;    {number of bytes to record}
   milliseconds:        LongInt;    {number of milliseconds to record}
   bufferLength:        LongInt;    {length of buffer to record into}
   bufferPtr:           Ptr;        {pointer to buffer to record into}
   completionRoutine:   ProcPtr;    {pointer to a completion routine}
   interruptRoutine:    ProcPtr;    {pointer to an interrupt routine}
   userLong:            LongInt;    {for application's use}
   error:               OSErr;      {error returned after recording}
   unused1:             LongInt;    {reserved}
END;
SPBPtr = ^SPB;

Sound Input Manager Routines

Recording Sounds

FUNCTION	SndRecord		(filterProc: ProcPtr; corner: Point; 
					quality: OSType; VAR sndHandle: Handle): OSErr;
FUNCTION	SndRecordToFile		(filterProc: ProcPtr; corner: Point; 
					quality: OSType; fRefNum: Integer): OSErr;

Opening and Closing Sound Input Devices

FUNCTION	SPBOpenDevice	(deviceName: Str255; permission: Integer; 
				VAR inRefNum: LongInt): OSErr;
FUNCTION	SPBCloseDevice	(inRefNum: LongInt): OSErr;

Recording Sounds Directly From Sound Input Devices

FUNCTION	SPBRecord		(inParamPtr: SPBPtr; asynchFlag: Boolean): 
					OSErr;
FUNCTION	SPBRecordToFile		(fRefNum: Integer; inParamPtr: SPBPtr; 
					asynchFlag: Boolean): OSErr;
FUNCTION	SPBPauseRecording
					(inRefNum: LongInt): OSErr;
FUNCTION	SPBResumeRecording
					(inRefNum: LongInt): OSErr;
FUNCTION	SPBStopRecording
					(inRefNum: LongInt): OSErr;
FUNCTION	SPBGetRecordingStatus
					(inRefNum: LongInt; 
					VAR recordingStatus: Integer; 
					VAR meterLevel: Integer; 
					VAR totalSamplesToRecord: LongInt; 
					VAR numberOfSamplesRecorded: LongInt; 
					VAR totalMsecsToRecord: LongInt; 
					VAR numberOfMsecsRecorded: LongInt): OSErr;

Manipulating Device Settings

FUNCTION	SPBGetDeviceInfo
					(inRefNum: LongInt; infoType: OSType; 
					infoData: Ptr): OSErr;
FUNCTION	SPBSetDeviceInfo
					(inRefNum: LongInt; infoType: OSType; 
					infoData: Ptr): OSErr;

Constructing Sound Resource and File Headers

FUNCTION	SetupSndHeader		(sndHandle: Handle; numChannels: Integer; 
					sampleRate: Fixed; sampleSize: Integer; 
					compressionType: OSType; baseFrequency: Integer; numBytes: LongInt; 
					VAR headerLen: Integer): OSErr;
FUNCTION	SetupAIFFHeader		(fRefNum: Integer; numChannels: Integer; 
					sampleRate: Fixed; sampleSize: Integer; 
					compressionType: OSType; numBytes: LongInt; 
					numFrames: LongInt): OSErr;

Registering Sound Input Devices

FUNCTION	SPBSignInDevice		(deviceRefNum: Integer; deviceName: Str255): 
					OSErr;
FUNCTION	SPBGetIndexedDevice
					(count: Integer; VAR deviceName: Str255; 
					VAR deviceIconHandle: Handle): OSErr;
					FUNCTION SPBSignOutDevice(deviceRefNum: Integer): OSErr;

Converting Between Milliseconds and Bytes

FUNCTION	SPBMilliSecondsToBytes
					(inRefNum: LongInt; VAR milliseconds: LongInt): OSErr;
FUNCTION	SPBBytesToMilliSeconds
					(inRefNum: LongInt; VAR byteCount: LongInt): OSErr;

Obtaining Information

FUNCTION	SPBVersion			: NumVersion;

Application-Defined Routines

PROCEDURE	MySICompletionRoutine
					(inParamPtr: SPBPtr);
PROCEDURE	MySIInterruptRoutine;

C Summary

Constants

#define gestaltSoundAttr    'snd '  /*sound attributes selector*/
enum {
   /*Gestalt response bit flags related to sound input*/
   gestaltSoundIOMgrPresent   = 3,  /*sound input routines available*/
   gestaltBuiltInSoundInput   = 4,  /*built-in input hw available*/
   gestaltHasSoundInputDevice = 5,  /*sound input device available*/
   gestaltPlayAndRecord       = 6,  /*built-in hw can play while recording*/
   gestalt16BitSoundIO        = 7,  /*built-in hw can handle 16-bit data*/
   gestaltStereoInput         = 8,  /*built-in hw can record stereo sounds*/
   gestaltLineLevelInput      = 9   /*built-in input hw needs line level*/
};
/*available information selectors for sound input device drivers*/
#define siActiveChannels      'chac'   /*channels active*/
#define siActiveLevels        'lmac'   /*levels active*/
#define siAGCOnOff            'agc '   /*automatic gain control state*/
#define siAsync               'asyn'   /*asynchronous capability*/
#define siChannelAvailable    'chav'   /*number of channels available*/
#define siCompressionAvailable'cmav'   /*compression types available*/
#define siCompressionFactor   'cmfa'   /*current compression factor*/
#define siCompressionHeader   'cmhd'   /*return compression header*/
#define siCompressionNames    'cnam'   /*return compression type names*/
#define siCompressionType     'comp'   /*current compression type*/
#define siContinuous          'cont'   /*continuous recording*/
#define siDeviceBufferInfo    'dbin'   /*size of interrupt buffer*/
#define siDeviceConnected     'dcon'   /*input device connection status*/
#define siDeviceIcon          'icon'   /*input device icon*/
#define siDeviceName          'name'   /*input device name*/
#define siInputGain           'gain'   /*input gain level*/
#define siInputSource         'sour'   /*input source selector*/
#define siInputSourceNames    'snam'   /*input source names*/
#define siLevelMeterOnOff     'lmet'   /*level meter state*/
#define siNumberChannels      'chan'   /*current number of channels*/
#define siOptionsDialog       'optd'   /*display options dialog box*/
#define siPlayThruOnOff       'plth'   /*play-through state*/
#define siRecordingQuality    'qual'   /*recording quality*/
#define siSampleRate          'srat'   /*current sample rate*/
#define siSampleRateAvailable 'srav'   /*sample rates available*/
#define siSampleSize          'ssiz'   /*current sample size*/
#define siSampleSizeAvailable 'ssav'   /*sample sizes available*/
#define siStereoInputGain     'sgai'   /*stereo input gain level*/
#define siTwosComplementOnOff 'twos'   /*two's complement state*/
#define siVoxRecordInfo       'voxr'   /*VOX record parameters*/
#define siVoxStopInfo         'voxs'   /*VOX stop parameters*/
/*internal information selectors for sound input device drivers*/
#define siCloseDriver         'clos'   /*release driver*/
#define siInitializeDriver    'init'   /*initialize driver*/
#define siPauseRecording      'paus'   /*pause recording*/
#define siUserInterruptProc   'user'   /*set sound input interrupt routine*/
/*sound-recording qualities*/
#define siBestQuality         'best'   /*the best quality available*/
#define siBetterQuality       'betr'   /*a quality better than good*/
#define siGoodQuality         'good'   /*a good quality*/
/*sound input device permissions*/
enum {
   siReadPermission           = 0,     /*open device for reading*/
   siWritePermission          = 1      /*open device for reading/writing*/
};
/*device-connection states*/
enum {
   siDeviceIsConnected        = 1,     /*device is connected and ready*/
   siDeviceNotConnected       = 0,     /*device is not connected*/
   siDontKnowIfConnected      = -1     /*can't tell if device is connected*/
};

Data Types

Sound Input Parameter Block

struct SPB {
   long                 inRefNum;      /*reference number of input device*/
   unsigned long        count;         /*number of bytes to record*/
   unsigned long        milliseconds;  /*number of milliseconds to record*/
   unsigned long        bufferLength;  /*length of buffer to record into*/
   Ptr                  bufferPtr;     /*pointer to buffer to record into*/
   ProcPtr              completionRoutine;
                                       /*pointer to a completion routine*/
   ProcPtr              interruptRoutine;
                                       /*pointer to an interrupt routine*/
   long                 userLong;      /*for application's use*/
   OSErr                error;         /*error returned after recording*/
   long                 unused1;       /*reserved*/
};
typedef struct SPB SPB;
typedef SPB *SPBPtr;

Sound Input Manager Routines

Recording Sounds

pascal  OSErr SndRecord   (ModalFilterProcPtr filterProc, Point corner,
                           OSType quality, Handle *sndHandle);
pascal  OSErr SndRecordToFile
                          (ModalFilterProcPtr filterProc, Point corner,
                           OSType quality, short fRefNum);

Opening and Closing Sound Input Devices

pascal  OSErr SPBOpenDevice (ConstStr255Param deviceName, short permission,
                             long *inRefNum);
pascal OSErr SPBCloseDevice
                            (long inRefNum);

Recording Sounds Directly From Sound Input Devices

pascal  OSErr SPBRecord   (SPBPtr inParamPtr, Boolean asynchFlag);
pascal  OSErr SPBRecordToFile
                          (short fRefNum, SPBPtr inParamPtr, 
                           Boolean asynchFlag);
pascal  OSErr SPBPauseRecording
                          (long inRefNum);
pascal  OSErr SPBResumeRecording
                          (long inRefNum);
pascal  OSErr SPBStopRecording
                          (long inRefNum);
pascal  OSErr SPBGetRecordingStatus
                          (long inRefNum, short *recordingStatus, 
                           short *meterLevel, 
                           unsigned long *totalSamplesToRecord, 
                           unsigned long *numberOfSamplesRecorded, 
                           unsigned long *totalMsecsToRecord, 
                           unsigned long *numberOfMsecsRecorded);

Manipulating Device Settings

pascal  OSErr SPBGetDeviceInfo
                         (long inRefNum, OSType infoType, 
                          char *infoData);
pascal  OSErr SPBSetDeviceInfo
                         (long inRefNum, OSType infoType, 
                          char *infoData);

Constructing Sound Resource and File Headers

pascal  OSErr SetupSndHeader
                         (Handle sndHandle, short numChannels, 
                          Fixed sampleRate, short sampleSize, 
                          OSType compressionType, short baseFrequency, 
                          unsigned long numBytes, short *headerLen);
pascal  OSErr SetupAIFFHeader
                         (short fRefNum, short numChannels, 
                          Fixed sampleRate, short sampleSize, 
                          OSType compressionType,
                          unsigned long numBytes, 
                          unsigned long numFrames);

Registering Sound Input Devices

pascal  OSErr SPBSignInDevice
                         (short deviceRefNum, 
                          ConstStr255Param deviceName);
pascal  OSErr SPBGetIndexedDevice
                         (short count, Str255 deviceName, 
                          Handle *deviceIconHandle);
pascal  OSErr SPBSignOutDevice
                         (short deviceRefNum);

Converting Between Milliseconds and Bytes

pascal  OSErr SPBMilliSecondsToBytes
                         (long inRefNum, long *milliseconds);
pascal  OSErr SPBBytesToMilliSeconds
                         (long inRefNum, long *byteCount);

Obtaining Information

pascal  NumVersion SPBVersion
                         (void);

Application-Defined Routines

pascal  void MySICompletionRoutine
                         (SPBPtr inParamPtr);
pascal  void MySIInterruptRoutine
                         (void);

Assembly-Language Summary

Data Structures

Sound Input Parameter Block Data Structure

0 `inRefNum` long The input device reference number
4 `count` long The number of bytes to record
8 `milliseconds` long The number of milliseconds to record
12 `bufferLength` long The length of the buffer
16 `bufferPtr` long The address of the buffer
20 `completionRoutine` long A pointer to a completion routine
24 `interruptRoutine` long A pointer to an interrupt routine
28 `userLong` long For application's use
32 `error` word The error value returned after recording
36 `unused1` long Reserved

Trap Macros

Trap Macros Requiring Routine Selectors

_SoundDispatch

Selector	Routine
$00000014	`SPBVersion`
$01100014	`SPBSignOutDevice`
$021C0014	`SPBCloseDevice`
$02280014	`SPBPauseRecording`
$022C0014	`SPBResumeRecording`
$02300014	`SPBStopRecording`
$030C0014	`SPBSignInDevice`
$03200014	`SPBRecord`
$04240014	`SPBRecordToFile`
$04400014	`SPBMillisecondsToBytes`
$04440014	`SPBBytesToMilliseconds`
$05140014	`SPBGetIndexedDevice`
$05180014	`SPBOpenDevice`
$06380014	`SPBGetDeviceInfo`
$063C0014	`SPBSetDeviceInfo`
$07080014	`SndRecordToFile`
$08040014	`SndRecord`
$0B4C0014	`SetupAIFFHeader`
$0D480014	`SetupSndHeader`
$0E340014	`SPBGetRecordingStatus`

Result Codes

`noErr` 0 No error
`abortErr` -27 Asynchronous recording was cancelled
`permErr` -54 Attempt to open locked file for writing
`userCanceledErr` -128 User canceled the operation
`siNoSoundInHardware` -220 No sound input hardware available
`siBadSoundInDevice` -221 Invalid sound input device
`siNoBufferSpecified` -222 No buffer specified
`siInvalidCompression` -223 Invalid compression type
`siHardDriveTooSlow` -224 Hard drive too slow to record
`siInvalidSampleRate` -225 Invalid sample rate
`siInvalidSampleSize` -226 Invalid sample size
`siDeviceBusyErr` -227 Sound input device is busy
`siBadDeviceName` -228 Invalid device name
`siBadRefNum` -229 Invalid reference number
`siInputDeviceErr` -230 Input device hardware failure
`siUnknownInfoType` -231 Unknown type of information
`siUnknownQuality` -232 Unknown quality

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

0	`inRefNum`	long	The input device reference number
4	`count`	long	The number of bytes to record
8	`milliseconds`	long	The number of milliseconds to record
12	`bufferLength`	long	The length of the buffer
16	`bufferPtr`	long	The address of the buffer
20	`completionRoutine`	long	A pointer to a completion routine
24	`interruptRoutine`	long	A pointer to an interrupt routine
28	`userLong`	long	For application's use
32	`error`	word	The error value returned after recording
36	`unused1`	long	Reserved

`noErr`	0	No error
`abortErr`	-27	Asynchronous recording was cancelled
`permErr`	-54	Attempt to open locked file for writing
`userCanceledErr`	-128	User canceled the operation
`siNoSoundInHardware`	-220	No sound input hardware available
`siBadSoundInDevice`	-221	Invalid sound input device
`siNoBufferSpecified`	-222	No buffer specified
`siInvalidCompression`	-223	Invalid compression type
`siHardDriveTooSlow`	-224	Hard drive too slow to record
`siInvalidSampleRate`	-225	Invalid sample rate
`siInvalidSampleSize`	-226	Invalid sample size
`siDeviceBusyErr`	-227	Sound input device is busy
`siBadDeviceName`	-228	Invalid device name
`siBadRefNum`	-229	Invalid reference number
`siInputDeviceErr`	-230	Input device hardware failure
`siUnknownInfoType`	-231	Unknown type of information
`siUnknownQuality`	-232	Unknown quality