JSQSystemSoundPlayer Class Reference

#import <JSQSystemSoundPlayer.h>

Inheritance diagram for JSQSystemSoundPlayer:

Instance Methods
(void)	- toggleSoundPlayerOn:
(void)	- playSoundWithFilename:fileExtension:
(void)	- playSoundWithFilename:fileExtension:completion:
(void)	- playAlertSoundWithFilename:fileExtension:
(void)	- playAlertSoundWithFilename:fileExtension:completion:
(void)	- stopAllSounds
(void)	- stopSoundWithFilename:
(void)	- preloadSoundWithFilename:fileExtension:

Class Methods
(JSQSystemSoundPlayer *)	+ sharedPlayer
(void)	+ jsq_playMessageReceivedSound
(void)	+ jsq_playMessageReceivedAlert
(void)	+ jsq_playMessageSentSound
(void)	+ jsq_playMessageSentAlert

Properties
BOOL	on
NSBundle *	bundle

Detailed Description

The JSQSystemSoundPlayer class enables you to play sound effects, alert sounds, or other short sounds. It lazily loads and caches all SystemSoundID objects and purges them upon receiving the UIApplicationDidReceiveMemoryWarningNotification notification.

Method Documentation

+ (void) jsq_playMessageReceivedAlert

Plays the default sound for received messages as an alert, invoking device vibration if available.

Provided by category JSQSystemSoundPlayer(JSQMessages).

+ (void) jsq_playMessageReceivedSound

Plays the default sound for received messages.

Provided by category JSQSystemSoundPlayer(JSQMessages).

+ (void) jsq_playMessageSentAlert

Plays the default sound for sent messages as an alert, invoking device vibration if available.

Provided by category JSQSystemSoundPlayer(JSQMessages).

+ (void) jsq_playMessageSentSound

Plays the default sound for sent messages.

Provided by category JSQSystemSoundPlayer(JSQMessages).

- (void) playAlertSoundWithFilename:		(NSString *)	filename
fileExtension:		(NSString *)	fileExtension

Plays a system sound object as an alert corresponding to an audio file with the given filename and extension. The system sound player will lazily initialize and load the file before playing it, and then cache its corresponding SystemSoundID. If this file has previously been played, it will be loaded from cache and played immediately.

Parameters

filename	A string containing the base name of the audio file to play.
fileExtension	A string containing the extension of the audio file to play. This parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

Warning

If the system sound object cannot be created, this method does nothing.

This method performs the same functions as playSoundWithName: extension:, with the excepion that, depending on the particular iOS device, this method may invoke vibration.

- (void) playAlertSoundWithFilename:		(NSString *)	filename
fileExtension:		(NSString *)	fileExtension
completion:		(JSQSystemSoundPlayerCompletionBlock)	completionBlock

Plays a system sound object as an alert corresponding to an audio file with the given filename and extension, and and excutes completionBlock when the sound has stopped playing. The system sound player will lazily initialize and load the file before playing it, and then cache its corresponding SystemSoundID. If this file has previously been played, it will be loaded from cache and played immediately.

Parameters

filename	A string containing the base name of the audio file to play.
fileExtension	A string containing the extension of the audio file to play. This parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.
completionBlock	A block called after the sound has stopped playing. This block is retained by JSQSystemSoundPlayer, temporarily cached, and released after its execution.

Warning

If the system sound object cannot be created, this method does nothing.

This method performs the same functions as playSoundWithName: extension: completion:, with the excepion that, depending on the particular iOS device, this method may invoke vibration.

- (void) playSoundWithFilename:		(NSString *)	filename
fileExtension:		(NSString *)	fileExtension

Plays a system sound object corresponding to an audio file with the given filename and extension. The system sound player will lazily initialize and load the file before playing it, and then cache its corresponding SystemSoundID. If this file has previously been played, it will be loaded from cache and played immediately.

Parameters

filename	A string containing the base name of the audio file to play.
fileExtension	A string containing the extension of the audio file to play. This parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

Warning

If the system sound object cannot be created, this method does nothing.

- (void) playSoundWithFilename:		(NSString *)	filename
fileExtension:		(NSString *)	fileExtension
completion:		(JSQSystemSoundPlayerCompletionBlock)	completionBlock

Plays a system sound object corresponding to an audio file with the given filename and extension, and excutes completionBlock when the sound has stopped playing. The system sound player will lazily initialize and load the file before playing it, and then cache its corresponding SystemSoundID. If this file has previously been played, it will be loaded from cache and played immediately.

Parameters

filename	A string containing the base name of the audio file to play.
fileExtension	A string containing the extension of the audio file to play. This parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.
completionBlock	A block called after the sound has stopped playing. This block is retained by JSQSystemSoundPlayer, temporarily cached, and released after its execution.

Warning

If the system sound object cannot be created, this method does nothing.

- (void) preloadSoundWithFilename:		(NSString *)	filename
fileExtension:		(NSString *)	fileExtension

Preloads a system sound object corresponding to an audio file with the given filename and extension. The system sound player will initialize, load, and cache the corresponding SystemSoundID.

Parameters

filename	A string containing the base name of the audio file to play.
fileExtension	A string containing the extension of the audio file to play. This parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

+ (JSQSystemSoundPlayer *) sharedPlayer

Returns the shared JSQSystemSoundPlayer object. This method always returns the same sound system player object.

Returns

An initialized JSQSystemSoundPlayer object if successful, nil otherwise.

- (void) stopAllSounds

Available on iOS only. On some iOS devices, you can call this method to invoke vibration. If this functionaly is not available, then calling this method does nothing. Stops playing all sounds immediately.

Warning

Any completion blocks attached to any currently playing sound will not be executed. Calling this method will purge all SystemSoundID objects from cache, regardless of whether or not they were currently playing.

- (void) stopSoundWithFilename:

(NSString *)

filename

Stops playing the sound with the given filename immediately.

Parameters

filename

The filename of the sound to stop playing.

Warning

If a completion block is attached to the given sound, it will not be executed. Calling this method will purge the SystemSoundID object for this file from cache, regardless of whether or not it was currently playing.

- (void) toggleSoundPlayerOn:

(BOOL)

on

Toggles the sound player on or off by setting the kJSQSystemSoundPlayerUserDefaultsKey key in NSUserDefaults to the given value. This will enable or disable the playing of sounds via JSQSystemSoundPlayer globally. This setting is persisted across application launches.

Parameters

on	A boolean indicating whether or not to enable or disable the sound player settings. Pass YES to turn sounds on, and NO to turn sounds off.

Warning

Disabling the sound player (passing a value of NO) will invoke the stopAllSounds method.

Property Documentation

- (NSBundle*) bundle

readwritenonatomicstrong

The bundle in which the sound player uses to search for sound file resources. You may change this property as needed. The default value is the main bundle. This value must not be nil.

- (BOOL) on

readnonatomicassign

Returns whether or not the sound player is on. That is, whether the sound player is enabled or disabled. If disabled, it will not play sounds.

See also

- toggleSoundPlayerOn:

---

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

• Vendors/JSQSystemSoundPlayer/JSQSystemSoundPlayer.h
• Vendors/JSQSystemSoundPlayer/JSQSystemSoundPlayer.m