Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

NXRecordStream

	Inherits From:	NXSoundStream : Object
	Declared In:	soundkit/NXRecordStream.h

Class Description

The NXRecordStream class defines methods that retrieve data recorded through the microphone.  To use an NXRecordStream object, you must first connect it to an NXSoundIn object and then activate it; these tasks are done through the initOnDevice:withParameters: and activate methods, both of which NXRecordStream inherits from its superclass, NXSoundStream. To record a sound, you must tell the NXRecordStream to enqueue a buffer in which the sound data will be placed by invoking the recordSize:tag: method.  You don't have to supply the buffer, just its size (and other specifications); the buffer itself is allocated by the sound driver.  If you're recording a determinate amount of data, there's no loss in enqueuing one large buffer to hold the entire recording.  In any case, you should note that you don't have to wait for a buffer to be recorded before enqueuing the next one. As each buffer is recorded, it's returned to the NXRecordStream's delegate through a soundStream:didRecordData:size:forBuffer: message.  You can force a buffer to return early through the sendRecordedDataToDelegate method. The sound data in the buffers that are returned to the delegate is a single channel of 8-bit mu-law samples at the CODEC sampling rate.  You have to convert the format and sampling rate before playing the sound through an NXPlayStream object (as explained in NXPlayStream).  If you're using a Sound object or the SNDStartPlaying() function to play the sound, these conversions are performed for you. The sound driver sends recorded data to all NXRecordStreams that are being used simultaneously.  This extends to all applications:  Any number of applications may recieve record at the same time (each application gets a separate copy of the recorded data). You can reserve the sound-in facilities for your application through NXSoundIn's setReserved: method. Error Codes Many of the methods described here access underlying sound devices.  Such methods return error codes that declare success or describe failure.  A catalog of these error codes can be found in the section "Types and Constants" under the heading "NXSoundDeviceError."

Instance Variables

None declared in this class.

Method Types

	Enqueueing buffers	recordSize:tag:
	Requesting data	sendRecordedDataToDelegate

Instance Methods

recordSize:tag:

(NXSoundDeviceError)recordSize:(unsigned int)bytes tag:(int)anInt

Enqueues a recording buffer with the given size in bytes.  The buffer is identified, when it's returned to the delegate, by aTag, an integer that must be greater than or equal to 0.  When the buffer is filled, it's returned to the NXRecordStream's delegate, through its soundStream:didRecordData:size:forBuffer: method.  You can force the buffer to be returned before it's filled by sending sendRecordedDataToDelegate to the NXRecordStream.  Returns an error code. See also:  soundStream:didRecordData:size:forBuffer: (delegate)

sendRecordedDataToDelegate

(NXSoundDeviceError)sendRecordedDataToDelegate

Forces the current buffer to be returned immediately in a soundStream:didRecordData:size:forBuffer: message sent to the delegate.  The recording continues into the remaining portion of the buffer.  An error code is returned. See also:  soundStream:didRecordData:size:forBuffer: (delegate)

Methods Implemented by the Delegate

soundStreamDidOverrun:

soundStreamDidOverrun:sender

Invoked when memory can't be wired down fast enough, thus causing the driver to drop recorded data.  Usually this means that the overall system load is too high.  The return value is ignored.

soundStream:didRecordData:size:forBuffer:

soundStream:sender

didRecordData:(void *)data size:(unsigned int)numBytes forBuffer:(int)tag

Returns, in data, the most recently recorded buffer of sound data.  The size of the data is given by numBytes; the tag argument is the tag that was placed on the buffer by the recordSize:... message that enqueued it.  Normally, this is invoked when the driver fills the entire buffer with data.  It's also invoked when the NXRecordStream is deactivated, and when it receives a sendRecordedDataToDelegate message.  When you're finished with data, you must free it yourself, through the vm_deallocate() function.