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

SndPlayer is the basic sound playing, streaming synthesizer. It simply maintains a queue of to-be-played and playing sounds, and mixes the active sounds down to its output buffer. More...

#import <SndPlayer.h>

Inheritance diagram for SndPlayer:
SndStreamClient SndStreamClient

List of all members.

Public Member Functions

(id) - init
 Initializer.
(void) - dealloc
 Destructor.
(NSString *) - description
 Produces a brief description of the SndPlayer.
(SndPerformance *) - playSnd:
 Begin playing a Snd instance immediately.
(SndPerformance *) - playSnd:withTimeOffset:
 Begin playing a Snd instance at some in point time in the future.
(SndPerformance *) - playSnd:withTimeOffset:beginAtIndex:endAtIndex:
 Begin playing a Snd instance at some time in the future.
(SndPerformance *) - playSnd:atTimeInSeconds:beginAtIndex:endAtIndex:
 Begin playing a Snd instance at some absolute stream time.
(SndPerformance *) - playSnd:atTimeInSeconds:startPositionInSeconds:durationInSeconds:
 Begin playing a Snd instance at some absolute stream time.
(id) - stopSnd:withTimeOffset:
 Stop all performances of the sound, at some point in the future.
(id) - stopSnd:
 Stop all performances of the sound immediately.
(id) - stopPerformance:inFuture:
 Stop the given performance at some time in the future.
(id) - pauseSnd:
 Pause all performances of the sound immediately.
(void) - processBuffers
 Main Snd performance method.
(id) - setRemainConnectedToManager:
 Sets the SndPlayer disconnection behaviour when no sounds remain in the pending or play arrays.
(BOOL) - remainConnectedToManager
 Indicates the current setting if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing.
(id) - addPerformance:
 Adds the performance to the list of those currently being played.
(double) - preemptQueuedStream
 Resets the playIndexes of all currently playing performances back to where the preemption occurs.
(id) - setAutoStartManager:
 Assigns whether to automatically start the SndStreamManager controlling the the synthesis process when a sound is first played.
(BOOL) - autoStartManager
 Returns the current state of whether the SndStreamManager will be automatically started when the SndPlayer is started.
(id) - init
 Initializer.
(void) - dealloc
 Destructor.
(NSString *) - description
 Produces a brief description of the SndPlayer.
(SndPerformance *) - playSnd:
 Begin playing a Snd instance immediately.
(SndPerformance *) - playSnd:withTimeOffset:
 Begin playing a Snd instance at some in point time in the future.
(SndPerformance *) - playSnd:withTimeOffset:beginAtIndex:endAtIndex:
 Begin playing a Snd instance at some time in the future.
(SndPerformance *) - playSnd:atTimeInSeconds:beginAtIndex:endAtIndex:
 Begin playing a Snd instance at some absolute stream time.
(SndPerformance *) - playSnd:atTimeInSeconds:startPositionInSeconds:durationInSeconds:
 Begin playing a Snd instance at some absolute stream time.
(id) - stopSnd:withTimeOffset:
 Stop all performances of the sound, at some point in the future.
(id) - stopSnd:
 Stop all performances of the sound immediately.
(id) - stopPerformance:inFuture:
 Stop the given performance at some time in the future.
(id) - pauseSnd:
 Pause all performances of the sound immediately.
(void) - processBuffers
 Main Snd performance method.
(id) - setRemainConnectedToManager:
 Sets the SndPlayer disconnection behaviour when no sounds remain in the pending or play arrays.
(BOOL) - remainConnectedToManager
 Indicates the current setting if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing.
(id) - addPerformance:
 Adds the performance to the list of those currently being played.
(double) - preemptQueuedStream
 Resets the playIndexes of all currently playing performances back to where the preemption occurs.
(id) - setAutoStartManager:
 Assigns whether to automatically start the SndStreamManager controlling the the synthesis process when a sound is first played.
(BOOL) - autoStartManager
 Returns the current state of whether the SndStreamManager will be automatically started when the SndPlayer is started.

Static Public Member Functions

(id) + player
 Factory method.
(SndPlayer *) + defaultSndPlayer
 Factory method.
(id) + player
 Factory method.
(SndPlayer *) + defaultSndPlayer
 Factory method.

Protected Attributes

NSMutableArray * toBePlayed
NSMutableArray * playing
NSRecursiveLock * playingLock
BOOL remainConnectedToManager
NSMutableArray * removalArray
SndAudioBuffernativelyFormattedStreamingBuffer
BOOL autoStartManager
SndPerformancepreemptingPerformance

Detailed Description

SndPlayer is the basic sound playing, streaming synthesizer. It simply maintains a queue of to-be-played and playing sounds, and mixes the active sounds down to its output buffer.

For further info, see the base class: SndStreamClient


Member Function Documentation

- (id) addPerformance: (SndPerformance *)  aPerformance

Adds the performance to the list of those currently being played.

Parameters:
aPerformanceA SndPerformance instance.
- (id) addPerformance: (SndPerformance *)  aPerformance

Adds the performance to the list of those currently being played.

Parameters:
aPerformanceA SndPerformance instance.
- (BOOL) autoStartManager

Returns the current state of whether the SndStreamManager will be automatically started when the SndPlayer is started.

Returns:
Returns YES if the SndStreamManager will be automatically started, NO if not.
- (BOOL) autoStartManager

Returns the current state of whether the SndStreamManager will be automatically started when the SndPlayer is started.

Returns:
Returns YES if the SndStreamManager will be automatically started, NO if not.

Factory method.

To come

Returns:
The default SndPlayer object

Factory method.

To come

Returns:
The default SndPlayer object
- (NSString *) description

Produces a brief description of the SndPlayer.

Returns:
NSString containing a brief description of the object

Reimplemented from SndStreamClient.

- (NSString *) description

Produces a brief description of the SndPlayer.

Returns:
NSString containing a brief description of the object

Reimplemented from SndStreamClient.

- (id) init

Initializer.

Returns:
Self.
- (id) init

Initializer.

Returns:
Self.
- (id) pauseSnd: (Snd *)  s

Pause all performances of the sound immediately.

Will pause PLAYING sound performances at their current position, but any PENDING sound performances will still have their time-to-start decremented by the SndPlayer as usual. Once the pending sound performances are added to the play queue, they will pause at their start position.

Parameters:
sThe sound to pause.
Returns:
Returns self.
- (id) pauseSnd: (Snd *)  s

Pause all performances of the sound immediately.

Will pause PLAYING sound performances at their current position, but any PENDING sound performances will still have their time-to-start decremented by the SndPlayer as usual. Once the pending sound performances are added to the play queue, they will pause at their start position.

Parameters:
sThe sound to pause.
Returns:
Returns self.
+ (id) player

Factory method.

To come

Returns:
A freshly initialized and autoreleased SndPlayer
+ (id) player

Factory method.

To come

Returns:
A freshly initialized and autoreleased SndPlayer
- (SndPerformance *) playSnd: (Snd *)  s

Begin playing a Snd instance immediately.

Parameters:
sThe sound to start playing
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s

Begin playing a Snd instance immediately.

Parameters:
sThe sound to start playing
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
atTimeInSeconds: (double)  playT
beginAtIndex: (unsigned long)  beginAtIndex
endAtIndex: (unsigned long)  endAtIndex 

Begin playing a Snd instance at some absolute stream time.

Parameters:
sThe sound to start playing
playTThe absolute stream time, in seconds, to start play back.
beginAtIndexThe first sample of the sound to play.
endAtIndexThe last sample of the sound to play.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
atTimeInSeconds: (double)  playT
beginAtIndex: (unsigned long)  beginAtIndex
endAtIndex: (unsigned long)  endAtIndex 

Begin playing a Snd instance at some absolute stream time.

Parameters:
sThe sound to start playing
playTThe absolute stream time, in seconds, to start play back.
beginAtIndexThe first sample of the sound to play.
endAtIndexThe last sample of the sound to play.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
atTimeInSeconds: (double)  playT
startPositionInSeconds: (double)  startpos
durationInSeconds: (double)  d 

Begin playing a Snd instance at some absolute stream time.

Parameters:
sThe sound to start playing
playTThe absolute stream time, in seconds, to start play back.
startposThe play start position within the snd
dThe duration of snd playback, in seconds
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
atTimeInSeconds: (double)  playT
startPositionInSeconds: (double)  startpos
durationInSeconds: (double)  d 

Begin playing a Snd instance at some absolute stream time.

Parameters:
sThe sound to start playing
playTThe absolute stream time, in seconds, to start play back.
startposThe play start position within the snd
dThe duration of snd playback, in seconds
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds 

Begin playing a Snd instance at some in point time in the future.

Parameters:
sThe sound to start playing
inSecondsThe future time interval in seconds when to start playing.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds 

Begin playing a Snd instance at some in point time in the future.

Parameters:
sThe sound to start playing
inSecondsThe future time interval in seconds when to start playing.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds
beginAtIndex: (unsigned long)  beginAtIndex
endAtIndex: (unsigned long)  endIndex 

Begin playing a Snd instance at some time in the future.

Parameters:
sThe sound to start playing
inSecondsThe future time interval in seconds when to start playing.
beginAtIndexThe first sample of the sound to play.
endIndexThe last sample of the sound to play.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (SndPerformance *) playSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds
beginAtIndex: (unsigned long)  beginAtIndex
endAtIndex: (unsigned long)  endIndex 

Begin playing a Snd instance at some time in the future.

Parameters:
sThe sound to start playing
inSecondsThe future time interval in seconds when to start playing.
beginAtIndexThe first sample of the sound to play.
endIndexThe last sample of the sound to play.
Returns:
The SndPerformance object assocaited with this instance of the Snd's performance
- (double) preemptQueuedStream

Resets the playIndexes of all currently playing performances back to where the preemption occurs.

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

Reimplemented from SndStreamClient.

- (double) preemptQueuedStream

Resets the playIndexes of all currently playing performances back to where the preemption occurs.

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

Reimplemented from SndStreamClient.

- (void) processBuffers

Main Snd performance method.

The user shouldn't invoke this method - it is the internal synthesis method. Snds are mixed down into the output stream, performance positions updated, playing and tobePlayed arrays updated as required.

Reimplemented from SndStreamClient.

- (void) processBuffers

Main Snd performance method.

The user shouldn't invoke this method - it is the internal synthesis method. Snds are mixed down into the output stream, performance positions updated, playing and tobePlayed arrays updated as required.

Reimplemented from SndStreamClient.

Indicates the current setting if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing.

Returns:
Returns TRUE if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing, FALSE if it will disconnect.

Indicates the current setting if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing.

Returns:
Returns TRUE if the SndPlayer will remain connected to the stream manager when no sounds are pending or playing, FALSE if it will disconnect.
- (id) setAutoStartManager: (BOOL)  yesOrNo

Assigns whether to automatically start the SndStreamManager controlling the the synthesis process when a sound is first played.

Parameters:
yesOrNoIf yesOrNo is YES, the SndStreamManager will be automatically started, if NO, it will not be.
- (id) setAutoStartManager: (BOOL)  yesOrNo

Assigns whether to automatically start the SndStreamManager controlling the the synthesis process when a sound is first played.

Parameters:
yesOrNoIf yesOrNo is YES, the SndStreamManager will be automatically started, if NO, it will not be.
- (id) setRemainConnectedToManager: (BOOL)  b

Sets the SndPlayer disconnection behaviour when no sounds remain in the pending or play arrays.

By default, the SndPlayer remains connected to the stream manager, which in turn means that streaming is still active. If you are only playing sounds occassionally, you may not wish to incur this slight overhead. The trade off is that if disconnection is set to be the behaviour, you will have a higher performance cost when starting the play back of a new sound in the future, as new threads are brought into existance, and streaming is started up.

- (id) setRemainConnectedToManager: (BOOL)  b

Sets the SndPlayer disconnection behaviour when no sounds remain in the pending or play arrays.

By default, the SndPlayer remains connected to the stream manager, which in turn means that streaming is still active. If you are only playing sounds occassionally, you may not wish to incur this slight overhead. The trade off is that if disconnection is set to be the behaviour, you will have a higher performance cost when starting the play back of a new sound in the future, as new threads are brought into existance, and streaming is started up.

- (id) stopPerformance: (SndPerformance *)  performance
inFuture: (double)  inSeconds 

Stop the given performance at some time in the future.

Stop the given performance at some time in the future by adjusting it's playback ending (i.e sample accurate stopping for those into buzz-words). When the playback reaches the new endAtTime, the stop delegate message will be fired off then and the performance removed from the playing queue. If the request to stop precedes the start time, the performance is removed from the toBePlayed queue.

Parameters:
performanceThe SndPerformance instance to stop.
inSecondsThe future time interval when to stop playing.
Returns:
- (id) stopPerformance: (SndPerformance *)  performance
inFuture: (double)  inSeconds 

Stop the given performance at some time in the future.

Stop the given performance at some time in the future by adjusting it's playback ending (i.e sample accurate stopping for those into buzz-words). When the playback reaches the new endAtTime, the stop delegate message will be fired off then and the performance removed from the playing queue. If the request to stop precedes the start time, the performance is removed from the toBePlayed queue.

Parameters:
performanceThe SndPerformance instance to stop.
inSecondsThe future time interval when to stop playing.
Returns:
- (id) stopSnd: (Snd *)  s

Stop all performances of the sound immediately.

Parameters:
sThe sound to stop.
Returns:
Self.
- (id) stopSnd: (Snd *)  s

Stop all performances of the sound immediately.

Parameters:
sThe sound to stop.
Returns:
Self.
- (id) stopSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds 

Stop all performances of the sound, at some point in the future.

Parameters:
sThe sound to stop.
inSecondsThe future time interval when to stop playing.
Returns:
Self.
- (id) stopSnd: (Snd *)  s
withTimeOffset: (double)  inSeconds 

Stop all performances of the sound, at some point in the future.

Parameters:
sThe sound to stop.
inSecondsThe future time interval when to stop playing.
Returns:
Self.

Member Data Documentation

- (BOOL) autoStartManager [protected]

Indicates that the SndStreamManager should be automatically started when playing of sounds first begins.

The audio buffer used to hold audio retrieved from a performance. As the name suggests, it will be in the format expected by the streaming hardware.

- (NSMutableArray *) playing [protected]

An array of actively playing SndPerformance objects.

- (NSRecursiveLock *) playingLock [protected]

Provides thread safety on the SndPerformance arrays. It controls access to the toBePlayed and playing arrays.

Holds a performance that is causing preemption in the output queue. This occurs when attempting to perform a sound immediately, causing cancellation of queued streaming buffers. The cancellation of the output queue forces all currently sounding performances to have their playIndexes reset except for the performance that caused the preemption in the first place.

- (BOOL) remainConnectedToManager [protected]

Indicates the SndPlayer disconnection behaviour when no sounds remain in the pending or play arrays.

- (NSMutableArray *) removalArray [protected]

Holds those performances which will be removed after completing playback. TODO I'm guessing this is an ivar rather than just a local variable to save time creating the object, by reusing it? Strikes me it would be efficient to simply release the damn thing than to actually empty it each time. This needs testing.

- (NSMutableArray *) toBePlayed [protected]

An array of pending SndPerformance objects.


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