JSQSystemSoundPlayer Class Reference

on

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

toggleSoundPlayerOn:

Declaration

Objective-C

@property (readonly, assign, nonatomic) BOOL on;

Swift

var on: Bool { get }


                    
                    
                    bundle

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.

Declaration

Objective-C

@property (readwrite, strong, nonatomic) NSBundle *_Nonnull bundle;

Swift

var bundle: Bundle { get set }


                    
                    
                    +sharedPlayer

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

Declaration

Objective-C

+ (nonnull JSQSystemSoundPlayer *)sharedPlayer;

Swift

class func shared() -> JSQSystemSoundPlayer

Return Value

A shared instance of JSQSystemSoundPlayer.


                    
                    
                    -initWithBundle:

Returns a new JSQSystemSoundPlayer instance with the specified bundle.

Warning

Completion blocks are only called for sounds played with the shared player.

Declaration

Objective-C

- (nonnull instancetype)initWithBundle:(nonnull NSBundle *)bundle;

Swift

init(bundle: Bundle)

Parameters


                                bundle

The bundle in which the sound player uses to search for sound file resources.

Return Value

An initialized JSQSystemSoundPlayer object.


                    
                    
                    -init

Returns a new JSQSystemSoundPlayer instance using the main bundle.

Warning

Completion blocks are only called for sounds played with the shared player.

Declaration

Objective-C

- (nonnull instancetype)init;

Swift

init()

Return Value

An initialized JSQSystemSoundPlayer object.


                    
                    
                    -toggleSoundPlayerOn:

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.

Warning

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

Declaration

Objective-C

- (void)toggleSoundPlayerOn:(BOOL)on;

Swift

func toggle(on: Bool)

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.


                    
                    
                    -playSoundWithFilename:fileExtension:completion:

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.

Note

The fileExtension parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

Warning

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

Declaration

Objective-C

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

Swift

func playSound(withFilename filename: String, fileExtension: String, completion completionBlock: JSQSystemSoundPlayerCompletionBlock? = nil)

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.
`completionBlock`	A block called after the sound has stopped playing. This block is retained by `JSQSystemSoundPlayer`, temporarily cached, and released after its execution.


                    
                    
                    -playAlertSoundWithFilename:fileExtension:completion:

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.

Note

The fileExtension parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

Warning

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

Warning

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.

Declaration

Objective-C

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

Swift

func playAlertSound(withFilename filename: String, fileExtension: String, completion completionBlock: JSQSystemSoundPlayerCompletionBlock? = nil)

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.
`completionBlock`	A block called after the sound has stopped playing. This block is retained by `JSQSystemSoundPlayer`, temporarily cached, and released after its execution.


                    
                    
                    -playSoundWithSoundID:asAlert:completion:

Plays the sound that corresponds to the specified SystemSoundID, optionally as an alert.

Declaration

Objective-C

- (void)playSoundWithSoundID:(SystemSoundID)soundID
                     asAlert:(BOOL)asAlert
                  completion:(nullable JSQSystemSoundPlayerCompletionBlock)
                                 completionBlock;

Swift

func playSound(withSoundID soundID: SystemSoundID, asAlert: Bool, completion completionBlock: JSQSystemSoundPlayerCompletionBlock? = nil)

Parameters

`soundID`	The SystemSoundID to play.
`asAlert`	Specifies whether or not the sound should be played as an alert.
`completionBlock`	A block called after the sound has stopped playing. This block is retained by `JSQSystemSoundPlayer`, temporarily cached, and released after its execution.


                    
                    
                    -stopAllSounds

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.

Declaration

Objective-C

- (void)stopAllSounds;

Swift

func stopAllSounds()


                    
                    
                    -stopSoundWithFilename:

Stops playing the sound with the given filename immediately.

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.

Declaration

Objective-C

- (void)stopSoundWithFilename:(nonnull NSString *)filename;

Swift

func stopSound(withFilename filename: String)

Parameters


                                filename

The filename of the sound to stop playing.


                    
                    
                    -preloadSoundWithFilename: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.

Note

The fileExtension parameter must be one of kJSQSystemSoundTypeCAF, kJSQSystemSoundTypeAIF, kJSQSystemSoundTypeAIFF, or kJSQSystemSoundTypeWAV.

Declaration

Objective-C

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

Swift

func preloadSound(withFilename filename: String, fileExtension: String)

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.