Inside Macintosh: Sound /

Chapter 3 - Sound Input Manager / Sound Input Manager Reference

Sound Input Manager Routines / Recording Sounds Directly From Sound Input Devices

SPBRecord

You can use the SPBRecord function to record audio data into memory, either synchronously or asynchronously.

FUNCTION SPBRecord (inParamPtr: SPBPtr; asynchFlag: Boolean): 
                     OSErr;

inParamPtr

A pointer to a sound input parameter block.

asynchFlag

A Boolean value that specifies whether the recording occurs asynchronously (TRUE) or synchronously (FALSE).

You specify values and receive return values in the sound input parameter block.

-->	inRefNum	LongInt	A reference number of a sound input device.
<-->	count	LongInt	The number of bytes of recording.
<-->	milliseconds	LongInt	The number of milliseconds of recording.
-->	bufferLength	LongInt	The length of the buffer beginning at bufferPtr.
-->	bufferPtr	Ptr	A pointer to a buffer for sampled-sound data.
-->	completionRoutine	ProcPtr	A pointer to a completion routine.
-->	interruptRoutine	ProcPtr	A pointer to an interrupt routine.
-->	userLong	LongInt	Free for application's use.
<--	error	OSErr	The error value returned after recording.
-->	unused1	LongInt	Reserved.

Field Description

inRefNum

The device reference number of the sound input device, as obtained from the SPBOpenDevice function.

count

On input, the number of bytes to record. If this field indicates a longer recording time than the milliseconds field, then the milliseconds field is ignored. On output, this field indicates the number of bytes actually recorded.

milliseconds

On input, the number of milliseconds to record. If this field indicates a longer recording time than the count field, then the count field is ignored. On output, this field indicates the number of milliseconds actually recorded.

bufferLength

The number of bytes in the buffer specified by the bufferPtr parameter. If this buffer length is too small to contain the amount of sampled-sound data specified in the count and milliseconds fields, then recording time is truncated so that the sampled-sound data fits in the buffer.

bufferPtr

A pointer to the buffer for the sampled-sound data, or NIL if you wish to record sampled-sound data without saving it. On exit, this buffer contains the sampled-sound data, which is interleaved for stereo sound on a sample basis (or on a packet basis if the data is compressed). This buffer contains only sampled-sound data, so if you need a sampled sound header, you should set that up in a buffer before calling SPBRecord and then record into the buffer following the sound header.

completionRoutine

A pointer to a completion routine. This routine is called when the recording terminates (either after you call the SPBStopRecording function or when the prescribed limit is reached). The completion routine is called only for asynchronous recording.

interruptRoutine

A pointer to an interrupt routine. The interrupt routine specified in the interruptRoutine field is called by asynchronous recording devices when their internal buffers are full.

userLong

A long integer that your application can use to pass data to your application's completion or interrupt routines.

error

On exit, a value greater than 0 while recording unless an error occurs, in which case it contains a value less than 0 that indicates an operating system error. Your application can poll this field to check on the status of an asynchronous recording. If recording terminates without an error, this field contains 0.

unused1

Reserved. You should set this field to 0 before calling SPBRecord.

DESCRIPTION

The SPBRecord function starts recording into memory from a device specified in a sound input parameter block. The sound data recorded is stored in the buffer specified by the bufferPtr and bufferLength fields of the parameter block. Recording lasts the longer of the times specified by the count and milliseconds fields of the parameter block, or until the buffer is filled. Recording is asynchronous if the asynchFlag parameter is TRUE and the specified sound input device supports asynchronous recording.

If the bufferPtr field of the parameter block contains NIL, then the count, milliseconds, and bufferLength fields are ignored, and the recording continues indefinitely until you call the SPBStopRecording function. In this case, the audio data is not saved anywhere; this feature is useful only if you want to do something in your interrupt routine and do not want to save the audio data. However, if the recording is synchronous and bufferPtr is NIL, SPBRecord returns the result code siNoBufferSpecified.

The SPBRecord function returns the value that the error field of the parameter block contains when recording finishes.

SPECIAL CONSIDERATIONS

You can call the SPBRecord function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the SPBRecord function are

Trap macro	Selector
_SoundDispatch	$03200014

RESULT CODES

noErr	0	No error
siNoSoundInHardware	-220	No sound input hardware available
siBadSoundInDevice	-221	Invalid sound input device
siNoBufferSpecified	-222	No buffer specified
siDeviceBusyErr	-227	Sound input device is busy

SEE ALSO

For an example of the use of the SPBRecord function, see Listing 3-1.