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:

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.
Static Public Member Functions
(id)	+ player
	Factory method.
(SndPlayer *)	+ defaultSndPlayer
	Factory method.
Protected Attributes
NSMutableArray *	toBePlayed
NSMutableArray *	playing
NSRecursiveLock *	playingLock
BOOL	remainConnectedToManager
NSMutableArray *	removalArray
SndAudioBuffer *	nativelyFormattedStreamingBuffer
BOOL	autoStartManager
SndPerformance *	preemptingPerformance

---

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) player

Factory method.

To come

Returns:

A freshly initialized and autoreleased SndPlayer

+ (SndPlayer*) defaultSndPlayer

Factory method.

To come

Returns:

The default SndPlayer object

- (id) init

Initializer.

Returns:

Self.

- (NSString *) description

Produces a brief description of the SndPlayer.

Returns:

NSString containing a brief description of the object

Reimplemented from SndStreamClient.

- (SndPerformance *) playSnd:

(Snd *)

s

Begin playing a Snd instance immediately.

Parameters:

s

The sound 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:

	s	The sound to start playing
	inSeconds	The 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:

	s	The sound to start playing
	inSeconds	The future time interval in seconds when to start playing.
	beginAtIndex	The first sample of the sound to play.
	endIndex	The 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:

	s	The sound to start playing
	playT	The absolute stream time, in seconds, to start play back.
	beginAtIndex	The first sample of the sound to play.
	endAtIndex	The 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:

	s	The sound to start playing
	playT	The absolute stream time, in seconds, to start play back.
	startpos	The play start position within the snd
	d	The duration of snd playback, in seconds

Returns:

The SndPerformance object assocaited with this instance of the Snd's performance

- (id) stopSnd:		(Snd *)	s
withTimeOffset:		(double)	inSeconds

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

Parameters:

	s	The sound to stop.
	inSeconds	The future time interval when to stop playing.

Returns:

Self.

- (id) stopSnd:

(Snd *)

s

Stop all performances of the sound immediately.

Parameters:

s

The sound to stop.

Returns:

Self.

- (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:

	performance	The SndPerformance instance to stop.
	inSeconds	The future time interval when to stop playing.

Returns:

- (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:

s

The sound to pause.

Returns:

Returns self.

- (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.

- (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.

- (BOOL) remainConnectedToManager

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) addPerformance:

(SndPerformance *)

aPerformance

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

Parameters:

aPerformance

A SndPerformance instance.

- (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.

- (id) setAutoStartManager:

(BOOL)

yesOrNo

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

Parameters:

yesOrNo

If yesOrNo is YES, the SndStreamManager will be automatically started, if NO, it will not be.

- (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.

---

Member Data Documentation

- (NSMutableArray*) toBePlayed [protected]

An array of pending SndPerformance objects.

- (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.

- (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.

- (SndAudioBuffer*) nativelyFormattedStreamingBuffer [protected]

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.

- (BOOL) autoStartManager [protected]

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

- (SndPerformance*) preemptingPerformance [protected]

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.

---

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

• SndPlayer.h