MusicKit  0.0.0
Public Member Functions | Static Public Member Functions | Protected Attributes
SndStreamManager Class Reference

SndStreamManager abstracts the playing of streams of audio. Provides streaming client connection and stream mixing services, and acts as an abstraction of the sound playing hardware. More...

#import <SndStreamManager.h>

Inherits <SndDelegateMessagePassing>, and <SndDelegateMessagePassing>.

List of all members.

Public Member Functions

(id) - init
 Initialise a SndStreamManager instance on the default input and output devices.
(id) - initOnDeviceForInput:deviceForOutput:
 Initialise a SndStreamManager instance on the named input and output devices.
(int) - assignedDriverIndexForOutput:
 Returns the index into the NSArray returned by +driverNamesForOutput: for the current driver.
(BOOL) - setAssignedDriverToIndex:forOutput:
 Assigns the sound hardware to be the driver referenced by the driver index number.
(NSString *) - assignedDriverNameForOutput:
 Returns an NSString of the current driver.
(BOOL) - setHardwareBufferSize:
 Sets the number of sample frames used by the audio input and output hardware.
(long) - inputBufferSize
 Returns the number of sample frames currently used by the audio input hardware.
(long) - outputBufferSize
 Returns the number of sample frames currently used by the audio output hardware.
(float) - inputLatency
 Returns an estimate of the number of seconds of latency between the hardware recording audio and when it will first be processed by this class's processStreamAtTime: method.
(float) - outputLatency
 Returns an estimate of the number of seconds of latency between when an audio buffer will be dispatched to be output by this class's processStreamAtTime: method and when the hardware will play it.
(NSString *) - description
 Returns an NSString with description of SndStreamManager.
(void) - startStreaming
 Starts streaming.
(void) - stopStreaming
 Stops streaming.
(BOOL) - addClient:
 Adds an SndStreamClient to the manager's mixer.
(BOOL) - removeClient:
 Removes the SndStreamClient from the manager's mixer.
(BOOL) - removeAllClients
 Removes all the SndStreamClients from the manager's mixer.
(NSArray *) - clients
 Returns an NSArray of clients of the SndStreamManager instance.
(void) - processStreamAtTime:input:output:
 Passes new input and output buffers from the underlying API to the mixer.
(SndFormat- format
 Returns the output format to be used during streaming.
(double) - nowTime
 Return the current time as understood by the SndStreamManager.
(SndStreamMixer *) - mixer
 Mixer member accessor method.
(BOOL) - isActive
 indicates whether streaming is happening (active)
(double) - samplingRate
(void) - resetTime:
 Resets the global stream time to originTimeInSeconds.
(void) - sendMessageInMainThreadToTarget:sel:arg1:arg2:
 Sends messages from any thread to any object in the main thread.
(id) - init
 Initialise a SndStreamManager instance on the default input and output devices.
(id) - initOnDeviceForInput:deviceForOutput:
 Initialise a SndStreamManager instance on the named input and output devices.
(int) - assignedDriverIndexForOutput:
 Returns the index into the NSArray returned by +driverNamesForOutput: for the current driver.
(BOOL) - setAssignedDriverToIndex:forOutput:
 Assigns the sound hardware to be the driver referenced by the driver index number.
(NSString *) - assignedDriverNameForOutput:
 Returns an NSString of the current driver.
(BOOL) - setHardwareBufferSize:
 Sets the number of sample frames used by the audio input and output hardware.
(long) - inputBufferSize
 Returns the number of sample frames currently used by the audio input hardware.
(long) - outputBufferSize
 Returns the number of sample frames currently used by the audio output hardware.
(float) - inputLatency
 Returns an estimate of the number of seconds of latency between the hardware recording audio and when it will first be processed by this class's processStreamAtTime: method.
(float) - outputLatency
 Returns an estimate of the number of seconds of latency between when an audio buffer will be dispatched to be output by this class's processStreamAtTime: method and when the hardware will play it.
(NSString *) - description
 Returns an NSString with description of SndStreamManager.
(void) - startStreaming
 Starts streaming.
(void) - stopStreaming
 Stops streaming.
(BOOL) - addClient:
 Adds an SndStreamClient to the manager's mixer.
(BOOL) - removeClient:
 Removes the SndStreamClient from the manager's mixer.
(BOOL) - removeAllClients
 Removes all the SndStreamClients from the manager's mixer.
(NSArray *) - clients
 Returns an NSArray of clients of the SndStreamManager instance.
(void) - processStreamAtTime:input:output:
 Passes new input and output buffers from the underlying API to the mixer.
(SndFormat- format
 Returns the output format to be used during streaming.
(double) - nowTime
 Return the current time as understood by the SndStreamManager.
(SndStreamMixer *) - mixer
 Mixer member accessor method.
(BOOL) - isActive
 indicates whether streaming is happening (active)
(double) - samplingRate
(void) - resetTime:
 Resets the global stream time to originTimeInSeconds.
(void) - sendMessageInMainThreadToTarget:sel:arg1:arg2:
 Sends messages from any thread to any object in the main thread.

Static Public Member Functions

(void) + initialize
 Class initialization method.
(SndStreamManager *) + defaultStreamManager
 Accessor to the default stream manager created upon class initialization.
(id) + streamManagerOnDeviceForInput:deviceForOutput:
 Creates and returns an autoreleased instance with the specified devices for output and input.
(NSArray *) + driverNamesForOutput:
 Returns an NSArray of NSStrings listing the sound drivers available.
(void) + initialize
 Class initialization method.
(SndStreamManager *) + defaultStreamManager
 Accessor to the default stream manager created upon class initialization.
(id) + streamManagerOnDeviceForInput:deviceForOutput:
 Creates and returns an autoreleased instance with the specified devices for output and input.
(NSArray *) + driverNamesForOutput:
 Returns an NSArray of NSStrings listing the sound drivers available.

Protected Attributes

SndStreamMixermixer
BOOL active
BOOL bg_active
SndFormat outputFormat
SndFormat inputFormat
double nowTime
char bg_sem
char bgdm_sem
NSConditionLock * bg_threadLock
NSConditionLock * bgdm_threadLock
BOOL isStopping

Detailed Description

SndStreamManager abstracts the playing of streams of audio. Provides streaming client connection and stream mixing services, and acts as an abstraction of the sound playing hardware.

In practice, the hardware is further abstracted by a platform specific interface that encapsulated by the lowlevel MKPerformSndMIDI C functions.

Each SndStreamManager has a SndStreamMixer which has a SndAudioProcessorChain which has a SndAudioFader. Adding clients to a manager adds them to the underlying mixer.


Member Function Documentation

- (BOOL) addClient: (SndStreamClient *)  client

Adds an SndStreamClient to the manager's mixer.

If the SndStreamClient is already a client of the mixer, it is NOT added again. If the client is the first connected to the manager, the manager will automatically start streaming.

Parameters:
clientThe SndStreamClient instance to begin managing and mixing.
Returns:
YES if client was successfully added, FALSE if the client is already registered, or the audio device couldn't start streaming.
- (BOOL) addClient: (SndStreamClient *)  client

Adds an SndStreamClient to the manager's mixer.

If the SndStreamClient is already a client of the mixer, it is NOT added again. If the client is the first connected to the manager, the manager will automatically start streaming.

Parameters:
clientThe SndStreamClient instance to begin managing and mixing.
Returns:
YES if client was successfully added, FALSE if the client is already registered, or the audio device couldn't start streaming.
- (int) assignedDriverIndexForOutput: (BOOL)  forOutputDevices

Returns the index into the NSArray returned by +driverNamesForOutput: for the current driver.

Parameters:
forOutputDevicesYES to retrieve the assigned output device number, NO to retrieve the assigned input device number.
- (int) assignedDriverIndexForOutput: (BOOL)  forOutputDevices

Returns the index into the NSArray returned by +driverNamesForOutput: for the current driver.

Parameters:
forOutputDevicesYES to retrieve the assigned output device number, NO to retrieve the assigned input device number.
- (NSString *) assignedDriverNameForOutput: (BOOL)  forOutputDevices

Returns an NSString of the current driver.

Parameters:
forOutputDevicesYES to retrieve the assigned output device name, NO to retrieve the assigned input device name.
- (NSString *) assignedDriverNameForOutput: (BOOL)  forOutputDevices

Returns an NSString of the current driver.

Parameters:
forOutputDevicesYES to retrieve the assigned output device name, NO to retrieve the assigned input device name.
- (NSArray *) clients

Returns an NSArray of clients of the SndStreamManager instance.

Returns:
Return the clients in an immutable autoreleased array.
- (NSArray *) clients

Returns an NSArray of clients of the SndStreamManager instance.

Returns:
Return the clients in an immutable autoreleased array.

Accessor to the default stream manager created upon class initialization.

SndStreamClients will usually connect to the default stream manager, unless the user wishes to explicitly create their own manager.

Returns:
Returns the default manager

Accessor to the default stream manager created upon class initialization.

SndStreamClients will usually connect to the default stream manager, unless the user wishes to explicitly create their own manager.

Returns:
Returns the default manager
- (NSString *) description

Returns an NSString with description of SndStreamManager.

Returns:
Returns an NSString with description of SndStreamManager
- (NSString *) description

Returns an NSString with description of SndStreamManager.

Returns:
Returns an NSString with description of SndStreamManager
+ (NSArray *) driverNamesForOutput: (BOOL)  forOutputDevices

Returns an NSArray of NSStrings listing the sound drivers available.

Parameters:
forOutputDevicesYES to retrieve only the output devices, NO to retrieve only the input devices. The format of the names is dependent on the underlying operating system.
+ (NSArray *) driverNamesForOutput: (BOOL)  forOutputDevices

Returns an NSArray of NSStrings listing the sound drivers available.

Parameters:
forOutputDevicesYES to retrieve only the output devices, NO to retrieve only the input devices. The format of the names is dependent on the underlying operating system.

Returns the output format to be used during streaming.

Returns:
Returns a SndFormat structure.

Returns the output format to be used during streaming.

Returns:
Returns a SndFormat structure.
- (id) init

Initialise a SndStreamManager instance on the default input and output devices.

The actual devices chosen are platform dependent.

- (id) init

Initialise a SndStreamManager instance on the default input and output devices.

The actual devices chosen are platform dependent.

+ (void) initialize

Class initialization method.

Creates the default stream manager

Returns:
void.
+ (void) initialize

Class initialization method.

Creates the default stream manager

Returns:
void.
- (id) initOnDeviceForInput: (NSString *)  inputDeviceName
deviceForOutput: (NSString *)  outputDeviceName 

Initialise a SndStreamManager instance on the named input and output devices.

The input and output device names must match those in the arrays returned by +driverNamesForOutput:.

Parameters:
inputDeviceNameName of the device to stream audio from.
outputDeviceNameName of the device to stream audio to.
- (id) initOnDeviceForInput: (NSString *)  inputDeviceName
deviceForOutput: (NSString *)  outputDeviceName 

Initialise a SndStreamManager instance on the named input and output devices.

The input and output device names must match those in the arrays returned by +driverNamesForOutput:.

Parameters:
inputDeviceNameName of the device to stream audio from.
outputDeviceNameName of the device to stream audio to.
- (long) inputBufferSize

Returns the number of sample frames currently used by the audio input hardware.

Returns:
Returns 0 if unable to retrieve the size of the audio input buffer.
- (long) inputBufferSize

Returns the number of sample frames currently used by the audio input hardware.

Returns:
Returns 0 if unable to retrieve the size of the audio input buffer.
- (float) inputLatency

Returns an estimate of the number of seconds of latency between the hardware recording audio and when it will first be processed by this class's processStreamAtTime: method.

Note that SndStreamClients may create their own additional latency, based on the number and size of processing buffers they use.

Returns:
Returns 0.0 if unable to retrieve the latency of the audio input.
- (float) inputLatency

Returns an estimate of the number of seconds of latency between the hardware recording audio and when it will first be processed by this class's processStreamAtTime: method.

Note that SndStreamClients may create their own additional latency, based on the number and size of processing buffers they use.

Returns:
Returns 0.0 if unable to retrieve the latency of the audio input.
- (BOOL) isActive

indicates whether streaming is happening (active)

Returns:
YES if streaming is active
- (BOOL) isActive

indicates whether streaming is happening (active)

Returns:
YES if streaming is active

Mixer member accessor method.

Returns:
The internal SndStreamMixer

Mixer member accessor method.

Returns:
The internal SndStreamMixer
- (double) nowTime

Return the current time as understood by the SndStreamManager.

The current time indicates the time at the start of the next buffer to be mixed and then played. This is about as close to actual playing time as can be calculated. The actual time of play will depend on the operating system dependent latency between receiving a buffer to play and actually sending it to the DAC.

Returns:
nowTime as a double floating point value of time in seconds.
- (double) nowTime

Return the current time as understood by the SndStreamManager.

The current time indicates the time at the start of the next buffer to be mixed and then played. This is about as close to actual playing time as can be calculated. The actual time of play will depend on the operating system dependent latency between receiving a buffer to play and actually sending it to the DAC.

Returns:
nowTime as a double floating point value of time in seconds.
- (long) outputBufferSize

Returns the number of sample frames currently used by the audio output hardware.

Returns:
Returns 0 if unable to retrieve the size of the audio output buffer.
- (long) outputBufferSize

Returns the number of sample frames currently used by the audio output hardware.

Returns:
Returns 0 if unable to retrieve the size of the audio output buffer.
- (float) outputLatency

Returns an estimate of the number of seconds of latency between when an audio buffer will be dispatched to be output by this class's processStreamAtTime: method and when the hardware will play it.

Note that SndStreamClients may create their own additional latency, based on the number and size of processing buffers they use.

Returns:
Returns 0.0 if unable to retrieve the latency of the audio output.
- (float) outputLatency

Returns an estimate of the number of seconds of latency between when an audio buffer will be dispatched to be output by this class's processStreamAtTime: method and when the hardware will play it.

Note that SndStreamClients may create their own additional latency, based on the number and size of processing buffers they use.

Returns:
Returns 0.0 if unable to retrieve the latency of the audio output.
- (void) processStreamAtTime: (double)  bufferTime
input: (SndAudioBuffer *)  inB
output: (SndAudioBuffer *)  outB 

Passes new input and output buffers from the underlying API to the mixer.

Do not call this method - it is part of the audio callback handler.

Parameters:
bufferTimeTime in seconds when the buffer will play.
inBThe input buffer holding samples recorded from the ADC.
outBThe output buffer holding samples to be played.
- (void) processStreamAtTime: (double)  bufferTime
input: (SndAudioBuffer *)  inB
output: (SndAudioBuffer *)  outB 

Passes new input and output buffers from the underlying API to the mixer.

Do not call this method - it is part of the audio callback handler.

Parameters:
bufferTimeTime in seconds when the buffer will play.
inBThe input buffer holding samples recorded from the ADC.
outBThe output buffer holding samples to be played.
- (BOOL) removeAllClients

Removes all the SndStreamClients from the manager's mixer.

Streaming will be automatically shut down.

Returns:
Returns YES only if all the clients were successfully removed.
- (BOOL) removeAllClients

Removes all the SndStreamClients from the manager's mixer.

Streaming will be automatically shut down.

Returns:
Returns YES only if all the clients were successfully removed.
- (BOOL) removeClient: (SndStreamClient *)  client

Removes the SndStreamClient from the manager's mixer.

If the removed client was the last client connected to the manager, streaming will be automatically shut down.

Parameters:
clientThe client to be disconnected from the manager.
Returns:
YES if the client was successfully removed.
- (BOOL) removeClient: (SndStreamClient *)  client

Removes the SndStreamClient from the manager's mixer.

If the removed client was the last client connected to the manager, streaming will be automatically shut down.

Parameters:
clientThe client to be disconnected from the manager.
Returns:
YES if the client was successfully removed.
- (void) resetTime: (double)  originTimeInSeconds

Resets the global stream time to originTimeInSeconds.

Parameters:
originTimeInSecondsNew origin time, in seconds.

The new origin time is propagated to the mixer, and thus to the stream clients.

- (void) resetTime: (double)  originTimeInSeconds

Resets the global stream time to originTimeInSeconds.

Parameters:
originTimeInSecondsNew origin time, in seconds.

The new origin time is propagated to the mixer, and thus to the stream clients.

- (double) samplingRate
Returns:
The streaming sampling rate.
- (double) samplingRate
Returns:
The streaming sampling rate.
- (void) sendMessageInMainThreadToTarget: (id)  target
sel: (SEL)  sel
arg1: (id)  arg1
arg2: (id)  arg2 

Sends messages from any thread to any object in the main thread.

This method was introduced to allow easy delegate messaging from the underlying audio threads, but can be used by any object. The method creates an NSInvocation out of the parameters given, and adds it to an array of waiting messages. Then a background thread with an NSConnection to the main thread is notified, and the messages are passed up the connection one by one, and dispatched in the main thread. Note that the final dispatch is only done as part of the application's NSRunLoop, which means that if the main thread is busy doing anything, it can tke a little while for the delegate message to appear. Even if this is the case, this method should not block for long.

Parameters:
targetid target object
selSEL the selector to be sent, eg @selector(description:withObject:)
arg1the first argument in the selector
arg2the second argument in the selector
- (void) sendMessageInMainThreadToTarget: (id)  target
sel: (SEL)  sel
arg1: (id)  arg1
arg2: (id)  arg2 

Sends messages from any thread to any object in the main thread.

This method was introduced to allow easy delegate messaging from the underlying audio threads, but can be used by any object. The method creates an NSInvocation out of the parameters given, and adds it to an array of waiting messages. Then a background thread with an NSConnection to the main thread is notified, and the messages are passed up the connection one by one, and dispatched in the main thread. Note that the final dispatch is only done as part of the application's NSRunLoop, which means that if the main thread is busy doing anything, it can tke a little while for the delegate message to appear. Even if this is the case, this method should not block for long.

Parameters:
targetid target object
selSEL the selector to be sent, eg @selector(description:withObject:)
arg1the first argument in the selector
arg2the second argument in the selector
- (BOOL) setAssignedDriverToIndex: (unsigned int)  driverIndex
forOutput: (BOOL)  forOutputDevices 

Assigns the sound hardware to be the driver referenced by the driver index number.

Parameters:
driverIndexMust be a number that corresponds to the list of driver names returned by +driverNamesForOutput:
forOutputDevicesYES to retrieve the assigned output device number, NO to retrieve the assigned input device number.
- (BOOL) setAssignedDriverToIndex: (unsigned int)  driverIndex
forOutput: (BOOL)  forOutputDevices 

Assigns the sound hardware to be the driver referenced by the driver index number.

Parameters:
driverIndexMust be a number that corresponds to the list of driver names returned by +driverNamesForOutput:
forOutputDevicesYES to retrieve the assigned output device number, NO to retrieve the assigned input device number.
- (BOOL) setHardwareBufferSize: (unsigned int)  frames

Sets the number of sample frames used by the audio input and output hardware.

The buffer size refers to the number of samples which are output to the DAC in one write operation and input to the ADC in one read operation. Both input and output buffers are enforced to be the same.

Parameters:
framesSets the number of frames (channel independent) in the hardware buffer, if possible.
Returns:
Returns YES if able to change the hardware, NO if unable to change.
- (BOOL) setHardwareBufferSize: (unsigned int)  frames

Sets the number of sample frames used by the audio input and output hardware.

The buffer size refers to the number of samples which are output to the DAC in one write operation and input to the ADC in one read operation. Both input and output buffers are enforced to be the same.

Parameters:
framesSets the number of frames (channel independent) in the hardware buffer, if possible.
Returns:
Returns YES if able to change the hardware, NO if unable to change.
- (void) startStreaming

Starts streaming.

You should never need to call this. Streaming is started automatically when the first client connects to the manager.

- (void) startStreaming

Starts streaming.

You should never need to call this. Streaming is started automatically when the first client connects to the manager.

- (void) stopStreaming

Stops streaming.

You should never need to call this. Streaming is stopped automatically when the last client disconnects from the manager.

- (void) stopStreaming

Stops streaming.

You should never need to call this. Streaming is stopped automatically when the last client disconnects from the manager.

+ (id) streamManagerOnDeviceForInput: (NSString *)  inputDeviceName
deviceForOutput: (NSString *)  outputDeviceName 

Creates and returns an autoreleased instance with the specified devices for output and input.

The input and output device names must match those in the arrays returned by +driverNamesForOutput:.

Parameters:
inputDeviceNameName of the device to stream audio from.
outputDeviceNameName of the device to stream audio to.
+ (id) streamManagerOnDeviceForInput: (NSString *)  inputDeviceName
deviceForOutput: (NSString *)  outputDeviceName 

Creates and returns an autoreleased instance with the specified devices for output and input.

The input and output device names must match those in the arrays returned by +driverNamesForOutput:.

Parameters:
inputDeviceNameName of the device to stream audio from.
outputDeviceNameName of the device to stream audio to.

Member Data Documentation

- (BOOL) active [protected]

active Stores the streaming state of the manager.

- (BOOL) bg_active [protected]

bg_active Whether or not the backgroup stream stopping/starting thread has been created.

- (char) bg_sem [protected]

bg_sem Semaphore to the background thread to start/stop streaming.

- (NSConditionLock *) bg_threadLock [protected]

bg_threadLock used for signalling to background thread to start streaming, stop streaming, or abort itself.

- (char) bgdm_sem [protected]

bgdm_sem Semaphore to the background delegate messaging thread to notify it of data being ready for it.

- (NSConditionLock *) bgdm_threadLock [protected]

bgdm_threadLock used for controlling access to back ground delegate messaging code.

- (SndFormat) inputFormat [protected]

inputFormat SndFormat containing stream format information for input.

- (BOOL) isStopping [protected]

isStopping Indicates the SndStreamManager is in the process of stopping.

- (SndStreamMixer *) mixer [protected]

mixer A stream client mixer.

- (double) nowTime [protected]

nowTime Manager's conception of time, in seconds.

- (SndFormat) outputFormat [protected]

outputFormat SndFormat containing stream format information for output.


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