iOS Developer Library

Developer

AudioToolbox Framework Reference System Sound Services Reference

Options
Deployment Target:

On This Page
Language:

System Sound Services Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AudioToolbox

Objective-C

@import AudioToolbox;

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

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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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

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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

  • Unregisters any completion callback functions that were registered for a specified system sound.

    Declaration

    Swift

    func AudioServicesRemoveSystemSoundCompletion(_ inSystemSoundID: SystemSoundID)

    Objective-C

    void AudioServicesRemoveSystemSoundCompletion ( SystemSoundID inSystemSoundID );

    Parameters

    inSystemSoundID

    The system sound for which callback functions should be removed.

    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

  • Invoked when a system sound finishes playing.

    Declaration

    Swift

    typealias AudioServicesSystemSoundCompletionProc = CFunctionPointer<((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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later.

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.