SndStreamClient Class Reference

A stream client is responsible for audio streaming, signal processing and synthesis. More...

#import <SndStreamClient.h>

Inheritance diagram for SndStreamClient:

List of all members.

Public Member Functions
(id)	- freeBufferMem
	Frees buffer memory.
(NSString *)	- description
	Describes SndStreamClient.
(id)	- welcomeClientWithBuffer:manager:
	Initialize the client with a buffer showing manager format and start its thread.
(id)	- startProcessingNextBufferWithInput:nowTime:
	Initiates the generation of the next buffer which will be retrieved by the SndStreamMixer in the next iteration.
(double)	- preemptQueuedStream
	Any audio buffers which have been processed and awaiting to be retrieved by the SndStreamMixer/SndStreamManager are preempted, clearing any sounds such that any new buffer processed will be mixed without waiting for earlier processed buffers to be mixed.
(void)	- processingThread
	Root method for the synthesis thread.
(SndAudioBuffer *)	- outputBuffer
	Accessor for the currently exposed output buffer.
(SndAudioBuffer *)	- synthOutputBuffer
	Accessor for the current synthesis buffer.
(SndAudioBuffer *)	- synthInputBuffer
	Accessor for the current input buffer.
(id)	- managerIsShuttingDown
	Message sent by the manager to tell any clients still connected to it that it is about to disappear.
(void)	- processBuffers
	The main synthesis/processing thread method.
(double)	- synthesisTime
	Return the client's current SYNTHESIS time.
(void)	- resetTime:
	Sets the clients sense of streamTime. Internal clientNowTime is recalculated relative to the new Time.
(double)	- streamTime
	Return the global (the MANAGER'S) current time.
(BOOL)	- isActive
	Returns whether the client is active.
(id)	- setDetectPeaks:
	enables / disables peak detection
(id)	- getPeakLeft:right:
	Get the most recent peak values for the stereo stream.
(BOOL)	- generatesOutput
	Returns whether the client is an audio-producer (synthesizer, FX).
(BOOL)	- needsInput
	Returns whether the client is an audio-consumer (recorder, FX, signal analyzer).
(id)	- setGeneratesOutput:
	Determines whether the client's output buffer will be considered for mixing downstream.
(id)	- setNeedsInput:
	Sets whether the client requires an input uadio stream or not.
(id)	- setManager:
	Sets the SndStreamManager for this client.
(id)	- lockOutputBuffer
	Blocks calling thread until outputBuffer is available for locking.
(id)	- unlockOutputBuffer
	Releases lock on the outputBuffer.
(id)	- prepareToStreamWithBuffer:
	Prepare to stream with buffers that look like the supplied buffer.
(id)	- didFinishStreaming
	streaming thread is shutting down message.
(SndAudioProcessorChain *)	- audioProcessorChain
	Returns the client's SndAudioProcessorChain.
(void)	- setAudioProcessorChain:
	Assigns a replacement audio processor chain.
(void)	- setDelegate:
	Sets the client's delegate object.
(id)	- delegate
	Accessor method to the delegate member.
(int)	- inputBufferCount
(int)	- outputBufferCount
(BOOL)	- setInputBufferCount:
	Sets the input buffer queue length (only when client is NOT active).
(BOOL)	- setOutputBufferCount:
	Sets the output buffer queue length (only when client is NOT active).
(double)	- outputLatencyInSeconds
	Calculates the stream latency of the client.
(long)	- outputLatencyInSamples
	Calculates the current stream latency of the client.
(NSString *)	- clientName
	Accessor to the client name.
(id)	- setClientName:
	Sets the client's name.
(id)	- offlineProcessBuffer:nowTime:
	To come.
Static Public Member Functions
(id)	+ streamClient
	Factory method to creates and initializes an autoreleased SndStreamClient instance.
Protected Attributes
SndAudioBuffer *	exposedOutputBuffer
SndAudioBuffer *	synthOutputBuffer
SndAudioBuffer *	synthInputBuffer
SndAudioBufferQueue *	outputQueue
SndAudioBufferQueue *	inputQueue
NSConditionLock *	synthThreadLock
NSConditionLock *	outputBufferLock
BOOL	active
BOOL	needsInput
BOOL	generatesOutput
SndAudioProcessorChain *	processorChain
SndStreamManager *	manager
id	delegate
double	clientNowTime
double	lastManagerTime
NSString *	clientName

---

Detailed Description

A stream client is responsible for audio streaming, signal processing and synthesis.

A SndStreamClient provides basic streaming services such as double buffering, thread handling, automatic start up and and shut down of lower-level streaming services. Each SndStreamClient instance has a SndAudioProcessorChain instance, so each client can be part of a signal processing chain.

---

Member Function Documentation

+ (id) streamClient

Factory method to creates and initializes an autoreleased SndStreamClient instance.

Returns:

An autoreleased SndStreamClient object.

- (id) freeBufferMem

Frees buffer memory.

For internal use only.

- (NSString *) description

Describes SndStreamClient.

Describes SndStreamClient

Returns:

Returns an NSString describing the SndStreamClient.

Reimplemented in SndStreamRecorder, SndPlayer, and SndStreamRecorder.

- (id) welcomeClientWithBuffer:		(SndAudioBuffer *)	buff
manager:		(SndStreamManager *)	m

Initialize the client with a buffer showing manager format and start its thread.

Each SndStreamClient instance receives welcomeClientWithBuffer:manager: message from SndStreamManager when the client is first added to the manager. The receiving instance is supplied the first output buffer to use. This method prepares input and/or output queues as needed then initiates one thread per stream client. The SndStreamClient method processingThread is executed by that thread.

Parameters:

	buff	The buffer to use for output and as a prototype for I/O SndAudioBufferQueues.
	m	The SndStreamManager responsible for this client.

Returns:

Returns self

- (id) startProcessingNextBufferWithInput:		(SndAudioBuffer *)	inB
nowTime:		(double)	t

Initiates the generation of the next buffer which will be retrieved by the SndStreamMixer in the next iteration.

SndStreamMixer in the method processInBuffer:outBuffer:nowTime: iterates through all its SndStreamClients sending them the message startProcessingNextBufferWithInput:nowTime: after retrieving the SndStreamClient's outputBuffer. This method is responsible for placing the last exposedOutputBuffer onto the pending portion of the output queue (an instance of SndAudioBufferQueue). The exposedOutputBuffer is then retrieved as the next processed buffer using popNextProcessedBuffer.

Parameters:

	inB	The Input Buffer. Ignore input buffer if you don't want it.
	t	The current now time.

Returns:

Returns self.

- (double) preemptQueuedStream

Any audio buffers which have been processed and awaiting to be retrieved by the SndStreamMixer/SndStreamManager are preempted, clearing any sounds such that any new buffer processed will be mixed without waiting for earlier processed buffers to be mixed.

Returns:

Returns the number of seconds that the stream has been preempted by.

Reimplemented in SndPlayer.

- (SndAudioBuffer *) outputBuffer

Accessor for the currently exposed output buffer.

Don't store the object returned, as the output buffer swaps to the synthesis buffer each processing cycle.

Returns:

Returns the output buffer as a SndAudioBuffer instance.

- (SndAudioBuffer *) synthOutputBuffer

Accessor for the current synthesis buffer.

This is typically used internally in a SndStreamClient subclass to retrieve the current buffer to be processed.

Returns:

Returns the buffer to be synthesized as a SndAudioBuffer instance.

- (SndAudioBuffer *) synthInputBuffer

Accessor for the current input buffer.

Returns:

Returns the input buffer member

- (id) managerIsShuttingDown

Message sent by the manager to tell any clients still connected to it that it is about to disappear.

Returns:

Returns self

- (void) processBuffers

The main synthesis/processing thread method.

A subclass should override this method with its buffer processing method. This should be along the lines of (in pseudo code):

 SndAudioBuffer *b = [self synthBuffer];

 for(i = 0; i < [b length]; i++)
  ([b sample])[i] = a_synth_sample();
 

Reimplemented in SndPlayer.

- (double) synthesisTime

Return the client's current SYNTHESIS time.

The client synthesis thread's sense of time. Since the client's synthesis (processing) thread can process several buffers ahead of the manager, the client must maintain an independent sense of time. This is the time your derived stream client class MUST use inside its processBuffers overridden method.

NOTE - This means all operations must be fed to a stream client thread with a look-ahead delta time greater or equal to the process-ahead latency to ensure correct timing.

(See streamTime)

Returns:

Returns the synthesis thread time, in seconds.

- (void) resetTime:

(double)

originTimeInSeconds

Sets the clients sense of streamTime. Internal clientNowTime is recalculated relative to the new Time.

Parameters:

originTimeInSeconds

New now time.

- (double) streamTime

Return the global (the MANAGER'S) current time.

The manager's sense of time. For most time-operations outside of the synthesis thread, your stream client will probably want the "absolute" stream time as determined by the manager. For example, a client that it told to perform an operation 0.5 seconds in the future must compute the time-till-operation based on the global time; if it were to use the synthesis time, the operation would be performed 0.5 seconds PLUS the synth-ahead latency into the future.

(See synthesisTime)

Returns:

Returns the global (manager) time, in seconds.

- (BOOL) isActive

Returns whether the client is active.

Returns:

Returns a boolean indicating whether the client is active.

- (id) setDetectPeaks:

(BOOL)

detectPeaks

enables / disables peak detection

Not implemented yet - not convinced this should be here - maybe inside an SndAudioProcessor?

Returns:

Returns self.

- (id) getPeakLeft:		(float *)	leftPeak
right:		(float *)	rightPeak

Get the most recent peak values for the stereo stream.

Not implemented yet - not convinced this should be here - maybe inside an SndAudioProcessor?

Parameters:

	leftPeak	Left peak value
	rightPeak	Righ peak value

Returns:

Returns self.

- (BOOL) generatesOutput

Returns whether the client is an audio-producer (synthesizer, FX).

Returns:

Returns TRUE if the client generates output

- (BOOL) needsInput

Returns whether the client is an audio-consumer (recorder, FX, signal analyzer).

Returns:

Returns TRUE if the client requires an input stream.

- (id) setGeneratesOutput:

(BOOL)

b

Determines whether the client's output buffer will be considered for mixing downstream.

Normally you should only need to call this when initializing a derived stream client

Parameters:

b

Boolean switch

Returns:

Returns self.

- (id) setNeedsInput:

(BOOL)

b

Sets whether the client requires an input uadio stream or not.

Normally you should only need to call this when initializing a derived stream client. If true, the stream manager will copy the most recent input buffer into the client's input buffer each processing cycle provided the client hasn't choked the CPU. If the client is running in less than real time, the input buffer is not updated, since the manager must assume that the client's copy of the previous input buffer may still be in use.

Parameters:

b

Boolean switch

Returns:

Returns self.

- (id) setManager:

(SndStreamManager *)

m

Sets the SndStreamManager for this client.

Should never be called explicitly, it is invoked as part of the process of a manager welcoming a client into the fray.

Parameters:

m

The new SndStreamManager instance.

Returns:

Returns self.

- (id) lockOutputBuffer

Blocks calling thread until outputBuffer is available for locking.

Lock the output buffer before doing anything with it, otherwise the synthesis thread may swap the buffers on you!

Returns:

Returns self.

- (id) unlockOutputBuffer

Releases lock on the outputBuffer.

Returns:

Returns self.

- (id) prepareToStreamWithBuffer:

(SndAudioBuffer *)

buff

Prepare to stream with buffers that look like the supplied buffer.

Called before streaming commences to allow client an opportunity to setup internal generation buffers.

Parameters:

buff

Returns:

Returns self.

- (id) didFinishStreaming

streaming thread is shutting down message.

Called just before the streaming thread shuts down, giving a derived client a chance to clean up after itself.

Returns:

Returns self.

- (SndAudioProcessorChain *) audioProcessorChain

Returns the client's SndAudioProcessorChain.

Returns:

Reference to the data member audioProcessorChain

- (void) setAudioProcessorChain:

(SndAudioProcessorChain *)

newAudioProcessorChain

Assigns a replacement audio processor chain.

Parameters:

newAudioProcessorChain

A SndAudioProcessorChain instance.

- (void) setDelegate:

(id)

d

Sets the client's delegate object.

Parameters:

d

Returns:

Returns self.

- (id) delegate

Accessor method to the delegate member.

Returns:

The stream client's delegate object

- (int) inputBufferCount

Returns:

Returns the number of buffers in the input queue.

- (int) outputBufferCount

Returns:

Returns the number of buffers in the output queue.

- (BOOL) setInputBufferCount:

(int)

n

Sets the input buffer queue length (only when client is NOT active).

Parameters:

n

Number of buffers

Returns:

TRUE if all is well, FALSE if input buffer length could not be set.

- (BOOL) setOutputBufferCount:

(int)

n

Sets the output buffer queue length (only when client is NOT active).

Parameters:

n

Number of buffers

Returns:

TRUE if all is well, FALSE if output buffer length could not be set.

- (double) outputLatencyInSeconds

Calculates the stream latency of the client.

Number of buffers in queue times buffer duration.

Returns:

Returns latency, in seconds.

- (long) outputLatencyInSamples

Calculates the current stream latency of the client.

Number of buffers in queue times buffer duration.

Returns:

Returns latency, in samples.

- (NSString *) clientName

Accessor to the client name.

Returns:

Returns the NSString with the client's name.

- (id) setClientName:

(NSString *)

name

Sets the client's name.

Useful for identifying clients, especially when debugging - several SndStreamClient warning and error messages will display the name of the client reporting the error.

Parameters:

name

The client's name.

Returns:

Returns self.

- (id) offlineProcessBuffer:		(SndAudioBuffer *)	anAudioBuffer
nowTime:		(double)	t

To come.

Parameters:

	anAudioBuffer	the audio buffer to process
	t	nowTime

---

Member Data Documentation

- (SndAudioBuffer*) exposedOutputBuffer [protected]

The buffer in the output queue retrieved by the SndStreamMixer (driven by the output thread).

- (SndAudioBuffer*) synthOutputBuffer [protected]

The buffer in the output queue modified by the synthesis thread.

- (SndAudioBuffer*) synthInputBuffer [protected]

The buffer in the input queue currently ready for retrieval.

- (SndAudioBufferQueue*) outputQueue [protected]

A FIFO queue of SndAudioBuffers holding those pending output and those processed.

- (SndAudioBufferQueue*) inputQueue [protected]

A FIFO queue of SndAudioBuffers holding those pending input and those processed.

- (NSConditionLock*) synthThreadLock [protected]

- (NSConditionLock*) outputBufferLock [protected]

Controls access to the output buffer, particularly when changing the exposedOutputBuffer.

- (BOOL) active [protected]

- (BOOL) needsInput [protected]

Indicates this client processes audio data received from a SndStreamMixer instance by -startProcessingNextBufferWithInput:nowTime:

- (BOOL) generatesOutput [protected]

Indicates this client generates audio output data, retrieved from this client using -?

- (SndAudioProcessorChain*) processorChain [protected]

A chain of SndAudioProcessors processing this stream clients output.

- (SndStreamManager*) manager [protected]

The stream clients manager.

- (id) delegate [protected]

The delegate to receive messages from the client.

- (double) clientNowTime [protected]

The clients sense of time as used by subclasses for synthesis.

- (double) lastManagerTime [protected]

The last time received from the calling SndStreamManager. When streaming to non-interleaved buffers time does not monotonically advance. We check that using this.

- (NSString*) clientName [protected]

The descriptive name of the client.

---

The documentation for this class was generated from the following file:

• SndStreamClient.h