Legacy Document
Important: Sound Input Manager 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.
Inside Macintosh: Sound Manager
| Previous | Chapter contents | Chapter top | Section top | Next |
Important: Sound Input Manager 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.
The Sound Input Manager provides a number of routines that allow you to begin, pause, resume, and stop recording directly from a sound input device. These low-level routines do not display the sound recording dialog box to the user.
You can use the SPBRecord function to record audio data into memory, either synchronously or asynchronously.
FUNCTION SPBRecord (inParamPtr: SPBPtr; asynchFlag: Boolean):
OSErr;
A pointer to a sound input parameter block.
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.
Æ |
|||
´ |
|||
´ |
|||
Æ |
|||
Æ |
|||
Æ |
|||
Æ |
|||
Æ |
|||
¨ |
|||
Æ |
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
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.
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.
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.
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.
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.
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.
A long integer that your application can use to pass data to your application's completion or interrupt routines.
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.
Reserved. You should set this field to 0 before calling SPBRecord .
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.
For an example of the use of the SPBRecord function, see Listing 42 .
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;
The file reference number of an open file in which to place the recorded sound data.
A pointer to a sound input parameter block.
A Boolean value that specifies whether the recording occurs asynchronously ( TRUE ) or synchronously ( FALSE ).
Æ |
|||
´ |
|||
´ |
|||
Æ |
|||
Æ |
|||
Æ |
|||
¨ |
|||
Æ |
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
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.
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.
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.
Unused. You should set this field to NIL before calling SPBRecordToFile .
A long integer that your application can use to pass data to your application's completion or interrupt routines.
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.
Reserved. You should set this field to 0 before calling the SPBRecordToFile function.
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.
Because the SPBRecordToFile function moves or purges memory, you should not call it at interrupt time.
You can use the SPBPauseRecording function to pause recording from a sound input device.
FUNCTION SPBPauseRecording (inRefNum: LongInt): OSErr;
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
The SPBPauseRecording function pauses recording from the device specified by the inRefNum parameter. The recording must be asynchronous for this call to have any effect.
You can use the SPBResumeRecording function to resume recording from a sound input device.
FUNCTION SPBResumeRecording (inRefNum: LongInt): OSErr;
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
The SPBResumeRecording function resumes recording from the device specified by the inRefNum parameter. Recording on that device must previously have been paused by a call to the SPBPauseRecording function for SPBResumeRecording to have any effect.
You can use the SPBStopRecording function to end a recording from a sound input device.
FUNCTION SPBStopRecording (inRefNum: LongInt): OSErr;
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
The SPBStopRecording function stops recording from the device specified by the inRefNum parameter. The recording must be asynchronous for SPBStopRecording to have any effect. When you call SPBStopRecording , the sound input completion routine specified in the completionRoutine field of the sound input parameter block is called and the error field of that parameter block is set to abortErr . If you are writing a device driver, you will receive a KillIO Status call. See the section "Writing a Sound Input Device Driver" for more information.
You can use SPBGetRecordingStatus to obtain recording status information about a sound input device.
FUNCTION SPBGetRecordingStatus (inRefNum: LongInt;
VAR recordingStatus: Integer;
VAR meterLevel: Integer;
VAR totalSamplesToRecord:
LongInt;
VAR numberOfSamplesRecorded:
LongInt;
VAR totalMsecsToRecord: LongInt;
VAR numberOfMsecsRecorded:
LongInt):
OSErr;
The device reference number of the sound input device, as obtained from the SPBOpenDevice function.
The status of the recording. While the input device is recording, this parameter is set to a number greater than 0. When a recording terminates without an error, this parameter is set to 0. When an error occurs during recording or the recording has been terminated by a call to the SPBStopRecording function, this parameter is less than 0 and contains an error code.
The current input signal level. This level ranges from 0 to 255.
The total number of samples to record, including those samples already recorded.
The number of samples already recorded.
The total duration of recording time, including recording time already elapsed.
The amount of recording time that has elapsed.
The SPBGetRecordingStatus function returns, in its second through seventh parameters, information about the recording on the device specified by the inRefNum parameter.
Inside Macintosh: Sound Manager
| Previous | Chapter contents | Chapter top | Section top | Next |
Important: Sound Input Manager 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.