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

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

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