Inside Macintosh: Sound /

Chapter 3 - Sound Input Manager / Sound Input Manager Reference

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

SPBRecordToFile

You can use the SPBRecordToFile function to record audio data into a file, either synchronously or asynchronously.

FUNCTION SPBRecordToFile (fRefNum: Integer; inParamPtr: SPBPtr; 
                           asynchFlag: Boolean): OSErr;

fRefNum

The file reference number of an open file in which to place the recorded sound data.

inParamPtr

A pointer to a sound input parameter block.

asynchFlag

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

-->	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.
-->	completionRoutine	ProcPtr	A pointer to a completion routine.
-->	interruptRoutine	ProcPtr	Unused.
-->	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, 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, the number of milliseconds actually recorded.

completionRoutine

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

interruptRoutine

Unused. You should set this field to NIL before calling SPBRecordToFile.

userLong

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

error

On exit, the error that occurred during recording. This field contains the number 1 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 the SPBRecordToFile function.

DESCRIPTION

The SPBRecordToFile function starts recording from the specified device into a file. The sound data recorded is simply stored in the file, so it is up to your application to insert whatever headers are needed to play the sound with the Sound Manager. Your application must open the file specified by the fRefNum parameter with write access before calling SPBRecordToFile, and it must eventually close that file.

The fields in the parameter block specified by the inParamPtr parameter are identical to the fields in the parameter block passed to the SPBRecord function, except that the bufferLength and bufferPtr fields are not used. The interruptRoutine field is ignored by SPBRecordToFile because SPBRecordToFile copies data returned by the sound input device driver to disk during the sound input interrupt routine, but you should initialize this field to NIL.

The SPBRecordToFile function writes samples to disk in the same format that they are read in from the sound input device. If compression is enabled, then the samples written to the file are compressed. Multiple channels of sound are interleaved on a sample basis (or, for compressed sound data, on a packet basis). When you are recording 8-bit audio data to an AIFF file, you must set the siTwosComplementOnOff flag to so that the data is stored on disk in the two's-complement format. If you don't store the data in this format, it sounds distorted when you play it back.

If any errors occur during the file writing process, recording is suspended. All File Manager errors are returned through the function's return value if the routine is called synchronously. If the routine is called asynchronously and the completion routine is not NIL, the completion routine is called and is passed a single parameter on the stack that points to the sound input parameter block; any errors are returned in the error field of the sound input parameter block.

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

SPECIAL CONSIDERATIONS

Because the SPBRecordToFile function moves or purges memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the SPBRecordToFile function are

Trap macro	Selector
_SoundDispatch	$04240014

RESULT CODES

noErr	0	No error
permErr	-54	Attempt to open locked file for writing
siNoSoundInHardware	-220	No sound input hardware available
siBadSoundInDevice	-221	Invalid sound input device
siHardDriveTooSlow	-224	Hard drive too slow to record