System Sound Services Reference

System Sound Services provides a C interface for playing short sounds and for invoking vibration on iOS devices that support vibration.

You can use System Sound Services to play short (30 seconds or shorter) sounds. The interface does not provide level, positioning, looping, or timing control, and does not support simultaneous playback: You can play only one sound at a time. You can use System Sound Services to provide audible alerts. On some iOS devices, alerts can include vibration.

For usage information for iOS, refer to Using Audio in Multimedia Programming Guide.

Functions

Creating and Disposing of System Sound Objects

AudioServicesCreateSystemSoundID(_:_:) AudioServicesCreateSystemSoundID

Creates a system sound object.

Declaration

Swift

func AudioServicesCreateSystemSoundID(_ inFileURL: CFURL, _ outSystemSoundID: UnsafeMutablePointer<SystemSoundID>) -> OSStatus

Objective-C

OSStatus AudioServicesCreateSystemSoundID ( CFURLRef inFileURL, SystemSoundID *outSystemSoundID );

Parameters

inFileURL

The URL of the audio file to play.

outSystemSoundID

On output, a system sound object associated with the specified audio file.

Return Value

A result code.

Availability

Available in iOS 2.0 and later.

See Also

AudioServicesDisposeSystemSoundID
AudioServicesDisposeSystemSoundID(_:) AudioServicesDisposeSystemSoundID

Disposes of a system sound object and associated resources.

Declaration

Swift

func AudioServicesDisposeSystemSoundID(_ inSystemSoundID: SystemSoundID) -> OSStatus

Objective-C

OSStatus AudioServicesDisposeSystemSoundID ( SystemSoundID inSystemSoundID );

Parameters

inSystemSoundID

The system sound object to dispose of.

Return Value

A result code.

Availability

Available in iOS 2.0 and later.

See Also

AudioServicesCreateSystemSoundID

Playing Sounds


    
      
           AudioServicesPlayAlertSound(_:)
      
      
           AudioServicesPlayAlertSound

Plays a system sound as an alert.

Declaration

Swift

func AudioServicesPlayAlertSound(_ inSystemSoundID: SystemSoundID)

Objective-C

void AudioServicesPlayAlertSound ( SystemSoundID inSystemSoundID );

Parameters


  inSystemSoundID

The system sound object to play as an alert.

Before using this function, call the AudioServicesCreateSystemSoundID function to obtain a system sound.

Discussion

Depending on the particular iOS device, this function plays a short sound and may invoke vibration. Calling this function does the following on various iOS devices:

iPhone—plays the specified sound. If the user has configured the Settings application for vibration on ring, also invokes vibration. However, the device does not vibrate if your app’s audio session is configured with the AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryRecord audio session category. This ensures that vibration doesn’t interfere with audio recording. For an explanation of audio session categories, see Categories Express Audio Roles.
iPod touch, original—plays a short alert melody.
iPod touch, 2nd generation and newer—plays the specified sound.

In iOS, the duration of the sound to be played must not be more than 30 seconds.

In OS X, when a user has configured System Preferences to flash the screen for alerts, or if sound cannot be rendered, calling this function will result in the screen flashing. In OS X, pass the constant kSystemSoundID_UserPreferredAlert to play the alert sound selected by the user in System Preferences. In iOS there is no preferred user alert sound.

To play a short sound not used as an alert, use AudioServicesPlaySystemSound.

Availability

Available in iOS 2.0 and later.

Adding and Removing System Sound Callbacks


    
      
           AudioServicesAddSystemSoundCompletion(_:_:_:_:_:)
      
      
           AudioServicesAddSystemSoundCompletion

Registers a callback function that is invoked when a specified system sound finishes playing.

Declaration

Swift

func AudioServicesAddSystemSoundCompletion(_ inSystemSoundID: SystemSoundID, _ inRunLoop: CFRunLoop?, _ inRunLoopMode: CFString?, _ inCompletionRoutine: AudioServicesSystemSoundCompletionProc, _ inClientData: UnsafeMutablePointer<Void>) -> OSStatus

Objective-C

OSStatus AudioServicesAddSystemSoundCompletion ( SystemSoundID inSystemSoundID, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode, AudioServicesSystemSoundCompletionProc inCompletionRoutine, void *inClientData );

Parameters

`inSystemSoundID`	The system sound that your callback function is to respond to.
`inRunLoop`	The run loop in which the callback function should run. Pass `NULL` to use the main run loop.
`inRunLoopMode`	The mode for the run loop in which the callback functions should run. Pass `NULL` to use the default run loop mode.
`inCompletionRoutine`	The callback function to be invoked when the specified system sound has finished playing.
`inClientData`	Application data to be passed to your callback function when it is invoked. Can be `NULL`.

Return Value

A result code.

Discussion

Because a system sound may play for several seconds, you might want to know when it has finished playing. For example, you may want to wait until a system sound has finished playing before you play another sound.

Availability

Available in iOS 2.0 and later.

Managing System Sound Services Properties


    
      
           AudioServicesGetPropertyInfo(_:_:_:_:_:)
      
      
           AudioServicesGetPropertyInfo

Gets information about a System Sound Services property.

Declaration

Swift

func AudioServicesGetPropertyInfo(_ inPropertyID: AudioServicesPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ outPropertyDataSize: UnsafeMutablePointer<UInt32>, _ outWritable: UnsafeMutablePointer<DarwinBoolean>) -> OSStatus

Objective-C

OSStatus AudioServicesGetPropertyInfo ( AudioServicesPropertyID inPropertyID, UInt32 inSpecifierSize, const void *inSpecifier, UInt32 *outPropertyDataSize, Boolean *outWritable );

Parameters

`inPropertyID`	The property you want information about.
`inSpecifierSize`	The size of the buffer pointed to by the `inSpecifier` parameter. Pass `0` if no specifier buffer is required.
`inSpecifier`	A pointer to a specifier buffer, if such a buffer is required by the property about which you want information. Pass `NULL` if no specifier is required.
`outPropertyDataSize`	On output, the size, in bytes, of the property value. To get the property value, you need a buffer of at least this size.
`outWritable`	On output, `true` if the property is writable, or `false` if the property is read only.

Return Value

A result code.

Discussion

System Sound Services properties are listed and described in System Sound Services Property Identifiers.

Availability

Available in iOS 2.0 and later.

Declaration

Swift

func AudioServicesGetProperty(_ inPropertyID: AudioServicesPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ ioPropertyDataSize: UnsafeMutablePointer<UInt32>, _ outPropertyData: UnsafeMutablePointer<Void>) -> OSStatus

Objective-C

OSStatus AudioServicesGetProperty ( AudioServicesPropertyID inPropertyID, UInt32 inSpecifierSize, const void *inSpecifier, UInt32 *ioPropertyDataSize, void *outPropertyData );

Parameters

`inPropertyID`	The property whose value you want.
`inSpecifierSize`	The size of the buffer pointed to by the `inSpecifier` parameter. Pass `0` if no specifier buffer is required.
`inSpecifier`	A pointer to a specifier buffer, if such a buffer is required by the property about which you want information. Pass `NULL` if no specifier is required.
`ioPropertyDataSize`	On input, the size, in bytes, of the buffer pointed to by the `outPropertyData` parameter. Call the `AudioServicesGetPropertyInfo` function to find out the size required for this buffer. On output, the number of bytes written to the buffer.
`outPropertyData`	On output, the property value.

Return Value

A result code.

Discussion

System Sound Services properties are listed and described in System Sound Services Property Identifiers.

Special Considerations

Some Core Audio property values are C types and others are Core Foundation objects.

If you call this function to retrieve a value that is a Core Foundation object, then this function—despite the use of “Get” in its name—duplicates the object. You are responsible for releasing the object, as described in The Create Rule in Memory Management Programming Guide for Core Foundation.

Availability

Available in iOS 2.0 and later.

Declaration

Swift

func AudioServicesSetProperty(_ inPropertyID: AudioServicesPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ inPropertyDataSize: UInt32, _ inPropertyData: UnsafePointer<Void>) -> OSStatus

Objective-C

OSStatus AudioServicesSetProperty ( AudioServicesPropertyID inPropertyID, UInt32 inSpecifierSize, const void *inSpecifier, UInt32 inPropertyDataSize, const void *inPropertyData );

Parameters

`inPropertyID`	The property whose value you want to set.
`inSpecifierSize`	The size of the buffer pointed to by the `inSpecifier` parameter. Pass `0` if no specifier buffer is required.
`inSpecifier`	A pointer to a specifier buffer, if such a buffer is required by the property about which you want information. Pass `NULL` if no specifier is required.
`inPropertyDataSize`	The size, in bytes, of the buffer pointed to by the `inPropertyData` parameter.
`inPropertyData`	The property value you want to set.

Return Value

A result code.

Discussion

System Sound Services properties are listed and described in System Sound Services Property Identifiers.

Availability

Available in iOS 2.0 and later.

Callbacks

System Sound Services Callbacks

AudioServicesSystemSoundCompletionProc AudioServicesSystemSoundCompletionProc

Invoked when a system sound finishes playing.

Declaration

Swift

typealias AudioServicesSystemSoundCompletionProc = (SystemSoundID, UnsafeMutablePointer<Void>) -> Void

Objective-C

typedef void (*AudioServicesSystemSoundCompletionProc) ( SystemSoundID ssID, void *clientData );

Parameters

ssID

The system sound that has finished playing.

clientData

Application data that you specified when registering the callback function.

Discussion

Because a system sound may play for up to 30 seconds, the AudioServicesPlaySystemSound function executes asynchronously (that is, it returns immediately). This callback gets invoked when a specified system sound has finished playing. You can use this callback, for example, to help you avoid playing a second sound while a first sound is still playing.

Availability

Available in iOS 2.0 and later.

See Also

AudioServicesCreateSystemSoundID
AudioServicesAddSystemSoundCompletion
AudioServicesRemoveSystemSoundCompletion
AudioServicesPlaySystemSound

Data Types

AudioServicesPropertyID AudioServicesPropertyID

The data type for a system sound property identifier.

Declaration

Swift

typealias AudioServicesPropertyID = UInt32

Objective-C

typedef UInt32 AudioServicesPropertyID;

Discussion

System Audio Services properties are listed in System Sound Services Property Identifiers.

Import Statement

Objective-C

@import AudioToolbox;

Swift

import AudioToolbox

Availability

Available in iOS 2.0 and later.
SystemSoundID SystemSoundID

A system sound object, identified with a sound file you want to play.

Declaration

Swift

typealias SystemSoundID = UInt32

Objective-C

typedef UInt32 SystemSoundID;

Discussion

Call the AudioServicesCreateSystemSoundID function to obtain a system sound object.

Import Statement

Objective-C

@import AudioToolbox;

Swift

import AudioToolbox

Availability

Available in iOS 2.0 and later.

Constants

Alert Sound Identifiers
Identifiers for alert sounds and alternatives to sounds, for use with the AudioServicesPlayAlertSound function.

Declaration

Swift

var kSystemSoundID_Vibrate: SystemSoundID { get }

Objective-C

enum { kSystemSoundID_Vibrate = 0x00000FFF };

Constants
- kSystemSoundID_Vibrate
  
  kSystemSoundID_Vibrate
  
  On the iPhone, use this constant with the AudioServicesPlayAlertSound function to invoke a brief vibration. On the iPod touch, does nothing.
  
  Available in iOS 2.0 and later.
System Sound Services Property Identifiers
Property identifiers used when playing alerts with System Sound Services.

Declaration

Swift

var kAudioServicesPropertyIsUISound: AudioServicesPropertyID { get } var kAudioServicesPropertyCompletePlaybackIfAppDies: AudioServicesPropertyID { get }

Objective-C

enum { kAudioServicesPropertyIsUISound = 'isui', kAudioServicesPropertyCompletePlaybackIfAppDies = 'ifdi' };

Constants
- kAudioServicesPropertyIsUISound
  
  kAudioServicesPropertyIsUISound
  
  A UInt32 value, where 1 means that, for the audio file specified by a system sound passed in the inSpecifier parameter, the System Sound server respects the user setting in the Sound Effects preference and is silent when the user turns off sound effects.
  
  This property is set to 1 by default. Set it to 0 for the system sound to always play when passed to AudioServicesPlaySystemSound, regardless of the user's setting in sound preferences.
  
  Available in iOS 2.0 and later.
- kAudioServicesPropertyCompletePlaybackIfAppDies
  
  kAudioServicesPropertyCompletePlaybackIfAppDies
  
  A UInt32 value, where 1 means that the audio file specified by a system sound passed in the inSpecifier parameter should finish playing even if the client application terminates. This could happen, for example, if the user quits or the application terminates unexpectedly while the sound is playing. The default is 0. That is, you must explicitly set this property’s value to 1 if you want the sound to complete playing even if the application terminates.
  
  Available in iOS 2.0 and later.

Result Codes

This table lists the result codes defined for System Sound Services.

kAudioServicesNoError

No error has occurred.

Value

0

Description

No error has occurred.

Available in iOS 2.0 and later.
kAudioServicesUnsupportedPropertyError

The property is not supported.

Value

'pty?'

Description

The property is not supported.

Available in iOS 2.0 and later.
kAudioServicesBadPropertySizeError

The size of the property data was not correct.

Value

'!siz'

Description

The size of the property data was not correct.

Available in iOS 2.0 and later.
kAudioServicesBadSpecifierSizeError

The size of the specifier data was not correct.

Value

'!spc'

Description

The size of the specifier data was not correct.

Available in iOS 2.0 and later.
kAudioServicesSystemSoundUnspecifiedError

An unspecified error has occurred.

Value

-1500

Description

An unspecified error has occurred.

Available in iOS 2.0 and later.
kAudioServicesSystemSoundClientTimedOutError

System sound client message timed out.

Value

-1501

Description

System sound client message timed out.

Available in iOS 2.0 and later.

`inFileURL`	The URL of the audio file to play.
`outSystemSoundID`	On output, a system sound object associated with the specified audio file.

`ssID`	The system sound that has finished playing.
`clientData`	Application data that you specified when registering the callback function.

System Sound Services Reference

Functions

Creating and Disposing of System Sound Objects

Declaration

Parameters

Return Value

Availability

See Also

Declaration

Parameters

Return Value

Availability

See Also

Playing Sounds

Declaration

Parameters

Discussion

Availability

See Also

Declaration

Parameters

Discussion

Availability

See Also

Adding and Removing System Sound Callbacks

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Availability

See Also

Managing System Sound Services Properties

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Special Considerations

Availability

See Also

Declaration

Parameters

Return Value

Discussion

Availability

See Also

Callbacks

System Sound Services Callbacks

Declaration

Parameters

Discussion

Availability

See Also

Data Types

Declaration

Discussion

Import Statement

Availability

Declaration

Discussion

Import Statement

Availability

Constants

Declaration

Constants

Declaration

Constants

Result Codes

Value

Description

Value