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


16



Sound




Classes





NXPlayStream


Inherits From: NXSoundStream : Object


Initializing an NXPlayStream

initOnDevice:anObject Initializes a newly allocated NXPlayStream


Activating and Playing

(NXSoundDeviceError)activate Prepares the NXPlayStream for playback
(NXSoundDeviceError)playBuffer:(void *)data Plays a buffer of sound
size:(unsigned int)bytes
tag:(int)aTag


Setting Gain and Peak Detection

(NXSoundDeviceError)setGainLeft:(float)leftAmp Sets the NXPlayStream's stereo gain
right:(float)rightAmp
getGainLeft:(float *)leftScale Returns the NXPlayStream's gain by reference
right:(float *)rightScale
(NXSoundDeviceError)getPeakLeft:(float *)leftAmp
right:(float *)rightAmp Returns the most recent peak amplitudes by reference


Delegate Methods

soundStreamDidUnderrun:sender Invoked when the sound driver underruns




NXRecordStream


Inherits From: NXSoundStream : Object


Enqueueing Buffers

(NXSoundDeviceError)recordSize:(unsigned int)bytes
tag:(int)anInt Enqueues a recording buffer


Requesting Data

(NXSoundDeviceError)sendRecordedDataToDelegate
Sends the current buffer to the delegate


Delegate Methods

soundStreamDidOverrun:sender Invoked when the sound driver overruns
soundStreamDidRecordData:(void *)data Delivers a buffer of recorded data
size:(unsigned int)numBytes
forBuffer:(int)tag




NXSoundDevice


Inherits From: Object
Conforms To: NXSoundParameters


Initializing and Freeing an NXSoundDevice

init Initializes a newly allocated NXSoundDevice
initOnHost:(const char *)hostName Initializes a new NXSoundDevice on the given host
free Frees the NXSoundDevice


Using a Separate Thread

+ (cthread_t)replyThread Returns the thread in which driver messages are sent
+ setUseSeparateThread:(BOOL)flag Sets whether a separate thread is used for driver messages
+ (BOOL)isUsingSeparateThread Returns whether a separate thread is used for driver messages
+ setThreadThreshold:(int)threshold Sets the message-reception threshold
+ (int)threadThreshold Returns the message-reception threshold


Examining Ports

(port_t)devicePort Returns the port used to communicate with the sound driver
+ (port_t)replyPort Returns the port to which the sound driver sends messages
(port_t)streamOwnerPort Returns the port used to connect to the sound driver


Identifying the Host Computer

(const char *)host Returns the name of the computer on which the NXSoundDevice was initialized


Configuring the Object

(id <NXSoundParameters>)parameters Returns the object's parameters
(NXSoundDeviceError)setParameters:(id <NXSoundParameters>)params
(BOOL)acceptsContinuousStreamSamplingRates

(NXSoundDeviceError)getStreamSamplingRatesLow:(float *)lowRate

high:(float *)highRate;
(NXSoundDeviceError)getStreamSamplingRates:(const float **)rates
count:(unsigned int *)numRates;
(NXSoundDeviceError)getStreamDataEncodings:(const NXSoundParameterTag **)encodings
count:(unsigned int *)numEncodings
(unsigned int)streamChannelCountLimit
(NXSoundDeviceError)setReserved:(BOOL)flag
Sets whether the underlying device is reserved
(BOOL)isReserved Returns whether the underlying device is reserved
+ setTimeout:(unsigned int)milliseconds Sets the timeout period
+ (unsigned int)timeout Returns the timeout period


Finding Peak Amplitudes

(NXSoundDeviceError)getPeakLeft:(float *)leftAmp
right:(float *)rightAmp Returns the most recent peak amplitudes by reference


Controlling Streams

abortStreams:sender Aborts all streams connected to this NXSoundDevice
pauseStreams:sender Pauses all streams connected to this NXSoundDevice
resumeStreams:sender Resumes all streams connected to this NXSoundDevice


Handling errors

(NXSoundDeviceError)lastError Returns the most recent error
+ (const char *)textForError:(NXSoundDeviceError)errorCode
Returns a string that describes the given error




NXSoundIn


Inherits From: NXSoundDevice : Object

No methods




NXSoundOut


Inherits From: NXSoundDevice : Object

No methods




NXSoundParameters


Inherits From: Object
Conforms To: NXSoundParameters (the protocol)

+ (const char *)localizedNameForParameter:(NXSoundParameterTag)ptag

init

initFromSound:aSound

initFromSoundStruct:(SNDSoundStruct *)soundStruct

(void)configureSoundStruct:(SNDSoundStruct *)soundStruct




NXSoundStream


Inherits From: Object


Initializing and Freeing an NXSoundStream

init Initializes the NXSoundStream
initOnDevice:aDevice withParameters:params Initializes the NXSoundStream and connects it to aDevice
free Deactivates and frees the NXSoundStream.


Setting the Device

(NXSoundDeviceError)setDevice:aDevice Connects the NXSoundStream to aDevice
device Returns the NXSoundDevice that the NXSoundStream is connected to.


Activating and Deactivating

(NXSoundDeviceError)activate Adds the NXSoundStream to the list of active streams
(NXSoundDeviceError)deactivate Aborts the NXSoundStream's current activity


Controlling the stream

abort:sender Stops the NXSoundStream's playback or recording
(NXSoundDeviceError)abortAtTime:(NXSoundStreamTime *)time
Schedules the NXSoundStream to be aborted
pause:sender Pauses the NXSoundStream's recording or playback
(NXSoundDeviceError)pauseAtTime:(NXSoundStreamTime *)time
Schedules the NXSoundStream to be paused
resume:sender Resumes the NXSoundStream's recording or playback
(NXSoundDeviceError)resumeAtTime:(NXSoundStreamTime *)time
Schedules the NXSoundStream to be resumed


Querying the Object

(unsigned int)bytesProcessed Returns the number of bytes of sound that the NXSoundStream has recorded or played
(BOOL)isActive Returns whether the NXSoundStream is currently activate
(BOOL)isPaused Returns whether the NXSoundStream is currently paused
(port_t)streamPort Returns the port used to connect to the sound driver
(NXSoundDeviceError)lastError Returns the most recent sound device error


Assigning a Delegate

setDelegate:anObject Sets the NXSoundStream's delegate.
delegate Returns the NXSoundStream's delegate.


Delegate Methods

soundStream:sender didCompleteBuffer:(int)tag
Invoked when the driver finishes playing or recording
soundStream:sender didStartBuffer:(int)tag Invoked when the driver starts playing or recording
soundStreamDidAbort:sender Invoked when the driver aborts the stream
deviceReserved:(BOOL)flag
soundStreamDidPause:sender Invoked when the NXSoundStream is paused
soundStreamDidResume:sender Invoked when the NXSoundStream is resumed




Sound


Inherits From: Object
Conforms To: soundkit/Sound.h


Creating and Freeing a Sound Object

+ addName:(const char *)name Creates a Sound object from the sound resource named
fromBundle:(NXBundle *)aBundle name in the NXBundle aBundle
+ addName:(const char *)name Creates a Sound object from the sectionName section
fromSection:(const char *)sectionName of the sound segment in the application executable file
+ addName:(const char *)name Creates a Sound object from filename
fromSoundfile:(const char *)filename
initFromSection:(const char *)sectionName Creates a Sound object from the sectionName section of the sound segment in the application executable file
initFromPasteboard:(Pasteboard *)thePboard Creates a Sound object from the named pasteboard
initFromSoundfile:(const char *)filename Creates a Sound object from filename
free Frees the Sound object


Accessing the Sound Name Table

+ addName:(const char *)name sound:aSound Assigns the name name to the Sound aSound and adds it to the name table
+ findSoundFor:(const char *)aName Finds and returns the named Sound object
+ removeSoundForName:(const char *)name Removes the named Sound from the name table


Accessing the Sound's Name

setName:(const char *)aName Set's the Sound object's name
(const char *)name Return's the Sound object's name


Reading and Writing Sound Data

(int)readSoundfile:(const char *)filename Replaces the Sound's data with that in filename
readSoundFromStream:(NXStream *)stream Replaces the Sound's data with that read from stream
(int)writeSoundfile:(const char *)filename Writes the Sound's data to filename
writeSoundToStream:(NXStream *)stream Writes the Sound's data to stream
(int)writeToPasteboard:(Pasteboard *)pboard Writes the Sound's data to the named pasteboard


Modifying Sound Data

(int)convertToFormat:(int)newFormat Converts the Sound's data to the specified format,
samplingRate:(double)newRate sampling rate, and channel count
channelCount:(int)newChannelCount
(int)convertToFormat:(int)newFormat Convert's the Sound's data to the specified format
(int)setDataSize:(int)newDataSize Set's the Sound's data as specified
dataFormat:(int)newDataFormat
samplingRate:(double)newSamplingRate
channelCount:(int)newChannelCount
infoSize:(int)newInfoSize
setSoundStruct:(SNDSoundStruct *)aStruct Set's the Sound's sound structure
soundStructSize:(int)size


Querying the Sound Data

(SNDSoundStruct *)soundStruct Returns the Sound's sound structure
(int)soundStructSize Gives the size of the Sound's sound structure
(unsigned char *)data Returns a pointer to the Sound's sound data
(int)dataFormat Returns the Sound's data format
(int)dataSize Returns the size in bytes of the Sound's data
(int)channelCount Returns the number of channels of sound
(double)samplingRate Returns the sound data's sampling rate
(int)sampleCount Returns the number of sample frames in the sound data
(double)duration Returns the sound's length in seconds
(char *)info Returns a pointer to the Sound's info string
(int)infoSize Returns the length in bytes of the Sound's info string
(BOOL)isEmpty Returns whether the Sound contains any sound data
(BOOL)compatibleWith:aSound Returns whether the Sound's format is compatiable with that of aSound


Recording and playing

(int)pause Pauses the Sound's activity
pause:sender Pauses the Sound's activity
(BOOL)isPlayable Returns whether the Sound can be played
(int)play Plays the Sound
play:sender Plays the Sound
(int)record Records into the Sound
record:sender Records into the Sound
(int)resume Resumes the Sound's activity
resume:sender Resumes the Sound's activity
(int)stop Stops the Sound's activity
stop:sender Stops the Sound's activity
(int)samplesProcessed Returns the number of sample frames played or recorded
(int)status Returns the Sound's activity code
soundBeingProcessed Returns self
(SNDSoundStruct *)soundStructBeingProcessed
Returns the sound structure that's being played or recorded
(int)processingError Returns the last error code that was generated


Editing Sound Data

(BOOL)isEditable Returns whether the Sound's data can be edited
(int)copySamples:aSound Copies a range of samples from aSound into the receiver
at:(int)startSample
count:(int)sampleCount
(int)copySound:aSound Replaces the Sound's data with that in aSound
(int)deleteSamples Removes the Sound's data
(int)deleteSamplesAt:(int)startSample Removes a range of samples from the Sound's data
count:(int)sampleCount
(int)insertSamples:aSound at:(int)startSample Inserts aSound's data into the Sound's data
(BOOL)needsCompacting Returns whether the Sound's data needs to be compacted
(int)compactSamples Compacts the Sound's data


Archiving the Object

finishUnarchiving Invoked automatically after unarchiving
read:(NXTypedStream *)stream Unarchives the Sound from stream
write:(NXTypedStream *)stream Archives the Sound to stream


Accessing the Delegate

setDelegate:anObject Sets the Sound's delegate object
delegate Returns the Sound's delegate
tellDelegate:(SEL)theMessage Sends theMessage to the delegate


Accessing the Sound Hardware

+ getVolume:(float *)left :(float *)right Returns the left and right volume settings by reference
+ setVolume:(float)left :(float)right Sets the left and right volumes (0.0 to 1.0)
+ (BOOL)isMuted Returns whether the internal speaker is muted
+ setMute:(BOOL)aFlag Sets whether the internal speaker is muted


Delegate Methods

didPlay:sender Sent to the delegate when the Sound stops playing
didRecord:sender Sent to the delegate when the Sound stops recording
hadError:sender Sent to the delegate if an error occurs during recording or playback
willPlay:sender Sent to the delegate when the Sound begins to play
willRecord:sender Sent to the delegate when the Sound begins to record




SoundMeter


Inherits From: View : Responder : Object



Initializing a SoundMeter

initFrame:(const NXRect *)frameRect Initializes the SoundMeter


Graphic Attributes

setBackgroundGray:(float)aValue Sets the SoundMeter's background color
(float)backgroundGray Returns the SoundMeter's background color
setForegroundGray:(float)aValue Sets the SoundMeter's running bar color
(float)foregroundGray Returns the color of the running bar
setBezeled:(BOOL)aFlag Sets whether a bezeled border is drawn
(BOOL)isBezeled Returns whether the SoundMeter has a border
setPeakGray:(float)aValue Sets the SoundMeter's peak bubble color
(float)peakGray Returns the SoundMeter's peak bubble gray


Metering Attributes

setSound:aSound Sets the SoundMeter's Sound object
sound Returns the Sound object that the SoundMeter is metering
setFloatValue:(float)aValue Sets the current running value
setHoldTime:(float)seconds Sets the SoundMeter's peak value hold time in seconds
(float)holdTime Returns the SoundMeter's peak hold time


Retrieving Meter Values

(float)floatValue Returns the current running amplitude value
(float)maxValue Returns the maximum running value so far
(float)minValue Returns the minimum running value so far
(float)peakValue Returns the most recently detected peak value


Operating the Object

run:sender Starts the SoundMeter running
(BOOL)isRunning Returns whether the SoundMeter is currently running
stop:sender Stops the SoundMeter's metering activity


Drawing the Object

drawCurrentValue Draws the SoundMeter's running bar and peak bubble
drawSelf:(const NXRect *)rects :(int)rectCount Draws all the components of the SoundMeter


Archiving

read:(NXTypedStream *)aStream Unarchives the SoundMeter by reading it from aStream
write:(NXTypedStream *)aStream Archives the SoundMeter by writing it to aStream




SoundView


Inherits From: View : Responder : Object


Initializing and Freeing a SoundView

initFrame:(const NXRect *)frameRect Initializes the SoundView
free Frees the SoundView


Modifying the Object

scaleToFit Fits the sound data within the current frame
setBackgroundGray:(float)aGray Sets the SoundView's background gray
setBezeled:(BOOL)aFlag Sets whether the SoundView has a bezeled border
setContinuous:(BOOL)aFlag Sets the state of continuous action messages.
setDelegate:anObject Sets the SoundView's delegate
setDisplayMode:(int)aMode Sets the SoundView's display mode
setEnabled:(BOOL)aFlag Enables or disables the SoundView
setForegroundGray:(float)aGray Sets the SoundView's foreground gray
setOptimizedForSpeed:(BOOL)flag Sets whether the SoundView's display mechanism is optimized
setSound:aSound Sets the SoundView's Sound object
sizeToFit Resizes the SoundView's frame to maintain a constant reduction factor


Querying the Object

(float)backgroundGray Returns the SoundView's background gray
delegate Returns the SoundView's delegate
(int)displayMode Returns the SoundView's display mode
(float)foregroundGray Returns the SoundView's foreground gray
getSelection:(int *)firstSample
size:(int *)sampleCount Returns the selection by reference
(BOOL)isAutoScale Returns whether the SoundView is in autoscaling mode
(BOOL)isBezeled Returns whether the SoundView has a bezeled border
(BOOL)isContinuous Returns whether the SoundView responds to mouse-dragged events
(BOOL)isEnabled Returns whether the SoundView is enabled
(BOOL)isOptimizedForSpeed Returns whether the SoundView is optimized for speedy display
(float)reductionFactor Returns the SoundView's reduction factor
sound Returns the SoundView's Sound object.


Selecting and Editing the Sound Data

copy:sender Copies the current selection to the pasteboard
cut:sender Deletes the current selection
delete:sender Deletes the current selection
mouseDown:(NXEvent *)theEvent Allows a selection to be defined
paste:sender Replaces the current selection
selectAll:sender Creates a selection over the SoundView's entire sound
setSelection:(int)firstSample size:(int)sampleCount
Sets the selection
(BOOL)isEditable Returns whether the SoundView's data can be edited.
setEditable:(BOOL)aFlag Sets whether the SoundView can be edited


Pasteboard and Services Support

pasteboard:thePasteboard provideData:(const char *)pboardType
Places the SoundView's sound on the given pasteboard
readSelectionFromPasteboard:thePasteboard Replaces the SoundView's current selection
validRequestorForSendType:(NXAtom)sendType
andReturnType:(NXAtom)returnType You never invoke this method
writeSelectionToPasteboard:thePasteboard Places a copy of the SoundView's current selection
types:(NXAtom *)pboardTypes on the given pasteboard


Modifying the Display Coordinates

setAutoscale:(BOOL)aFlag Sets the SoundView's automatic scaling mode
setReductionFactor:(float)reductionFactor Recomputes the size of the SoundView's frame


Drawing the Object

drawSelf:(const NXRect *)rects :(int)rectCount Displays the SoundView's sound data
drawSamplesFrom:(int)first to:(int)last Redisplays the given range of samples
hideCursor Hides the SoundView's cursor
showCursor Displays the SoundView's cursor
sizeTo:(NXCoord)width :(NXCoord)height Sets the width and height of the SoundView's frame


Responding to Events

(BOOL)acceptsFirstResponder Returns YES
becomeFirstResponder Promotes the SoundView to first responder
resignFirstResponder Resigns the position of first responder


Performing the Sound Data

(BOOL)isPlayable Returns whether the SoundView's sound can be played
play:sender Play the current selection
record:sender Replaces the SoundView's current selection
pause:sender Pauses the current playback or recording
resume:sender Resumes the current playback or recording
stop:sender Stops the SoundView's current recording or playback
soundBeingProcessed Returns the Sound object that's currently being played or recorded into


Archiving the Object

read:(void *)stream Unarchives the SoundView by reading it from stream
write:(void *)stream Archives the SoundView by writing it to stream


Accessing the Delegate

didPlay:sender Used to redirect delegate messages
didRecord:sender Used to redirect delegate messages
hadError:sender Used to redirect delegate messages
tellDelegate:(SEL)theMessage Sends theMessage to the SoundView's delegate
willPlay:sender Used to redirect delegate messages
willRecord:sender Used to redirect delegate messages


Delegate Methods

didPlay:sender Sent to the delegate just after the SoundView is played.
didRecord:sender Sent to the delegate just after the SoundView is recorded into.
hadError:sender Sent to the delegate if an error is encountered .
selectionChanged:sender Sent to the delegate when the SoundView's selection changes.
soundDidChange:sender Sent to the delegate when the SoundView's sound is edited
willFree:sender Sent to the delegate when the SoundView is freed.
willPlay:sender Sent to the delegate just before the SoundView's sound is played.
willRecord:sender Sent to the delegate just before the SoundView's sound is recorded into.