iOS Developer Library

Developer

AudioToolbox Framework Reference System Sound Services Reference

Options
Deployment Target:

On This Page
Language:

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

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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Plays a system sound object.

    Declaration

    Swift

    func AudioServicesPlaySystemSound(_ inSystemSoundID: SystemSoundID)

    Objective-C

    void AudioServicesPlaySystemSound ( SystemSoundID inSystemSoundID );

    Parameters

    inSystemSoundID

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

    Discussion

    This function plays a short sound (30 seconds or less in duration). Because sound might play for several seconds, this function is executed asynchronously. To know when a sound has finished playing, call the AudioServicesAddSystemSoundCompletion function to register a callback function.

    On some iOS devices, you can pass the kSystemSoundID_Vibrate constant to invoke vibration. On other iOS devices, calling this function with that constant does nothing.

    Sound files that you play using this function must be:

    • No longer than 30 seconds in duration

    • In linear PCM or IMA4 (IMA/ADPCM) format

    • Packaged in a .caf, .aif, or .wav file

    In addition, when you use the AudioServicesPlaySystemSound function:

    • Sounds play at the current system audio volume, with no programmatic volume control available

    • Sounds play immediately

    • Looping and stereo positioning are unavailable

    • Simultaneous playback is unavailable: You can play only one sound at a time

    • The sound is played locally on the device speakers; it does not use audio routing.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Gets information about a System Sound Services property.

    Declaration

    Swift

    func AudioServicesGetPropertyInfo(_ inPropertyID: AudioServicesPropertyID, _ inSpecifierSize: UInt32, _ inSpecifier: UnsafePointer<Void>, _ outPropertyDataSize: UnsafeMutablePointer<UInt32>, _ outWritable: UnsafeMutablePointer<Boolean>) -> 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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Gets a specified System Sound Services property value.

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Sets the value for a specified System Sound Services property.

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

Callbacks

Data Types

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

  • 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

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

    Declaration

    Swift

    var kSystemSoundID_Vibrate: Int { 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.

  • Property identifiers used when playing alerts with System Sound Services.

    Declaration

    Swift

    var kAudioServicesPropertyIsUISound: Int { get } var kAudioServicesPropertyCompletePlaybackIfAppDies: Int { 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.