Mac Developer Library

Developer

AppKit Framework Reference NSSound Class Reference

Options
Deployment Target:

On This Page
Language:

NSSound

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSSound class provides a simple interface for loading and playing audio files. This class supports the same audio encodings and file formats that are supported by Core Audio and QuickTime.

To use this class, initialize a new instance with the desired file or audio data. You can configure assorted aspects of the audio playback, including the volume and whether the sound loops before you play it. Depending on the type of the audio data, this class may use either Core Audio or QuickTime to handle the actual playback. (Typically, it uses Core Audio to play files in the AIFF, WAVE, NeXT, SD2, AU, and MP3 formats and may use it for other formats in the future as well.) Playback occurs asynchronously so that your application can continue doing work.

You should retain NSSound objects before initiating playback or make sure you have a strong reference to them in a garbage-collected environment. Upon deallocation, a sound object stops playback of the sound (as needed) so that it can free up the corresponding audio resources. If you want to deallocate a sound object immediately after playback, assign a delegate and use the sound:didFinishPlaying: method to deallocate it.

If you want to play the system beep sound, use the NSBeep function.

  • Indicates whether the receiver can create an instance of itself from the data in a pasteboard.

    Declaration

    Swift

    class func canInitWithPasteboard(_ pasteboard: NSPasteboard) -> Bool

    Objective-C

    + (BOOL)canInitWithPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    Pasteboard containing sound data.

    Return Value

    YEStrue when the receiver can handle the data represented by pasteboard; NOfalse otherwise.

    Discussion

    The soundUnfilteredPasteboardTypes method is used to find out whether the class can handle the data in pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver with the the audio data located at a given filepath.

    Declaration

    Swift

    init?(contentsOfFile filepath: String, byReference byRef: Bool)

    Objective-C

    - (instancetype)initWithContentsOfFile:(NSString *)filepath byReference:(BOOL)byRef

    Parameters

    filepath

    Path to the sound file with which the receiver is to be initialized.

    byRef

    When YEStrue only the name of the sound is stored with the NSSound instance when archived using encodeWithCoder:; otherwise the audio data is archived along with the instance.

    Return Value

    Initialized NSSound instance.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver with the audio data located at a given URL.

    Declaration

    Swift

    init?(contentsOfURL fileUrl: NSURL, byReference byRef: Bool)

    Objective-C

    - (instancetype)initWithContentsOfURL:(NSURL *)fileUrl byReference:(BOOL)byRef

    Parameters

    fileUrl

    URL to the sound file with which the receiver is to be initialized.

    byRef

    When YEStrue only the name of the sound is stored with the NSSound instance when archived using encodeWithCoder:; otherwise the audio data is archived along with the instance.

    Return Value

    Initialized NSSound instance.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver with a given audio data.

    Declaration

    Swift

    init?(data audioData: NSData)

    Objective-C

    - (instancetype)initWithData:(NSData *)audioData

    Parameters

    audioData

    Audio data with which the receiver is to be initialized. The data must have a proper magic number, sound header, and data for the formats the NSSound class supports.

    Return Value

    Initialized NSSound instance.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver with data from a pasteboard. The pasteboard should contain a type returned by soundUnfilteredPasteboardTypes. NSSound expects the data to have a proper magic number, sound header, and data for the formats it supports.

    Declaration

    Swift

    init?(pasteboard pasteboard: NSPasteboard)

    Objective-C

    - (instancetype)initWithPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    The pasteboard containing the audio data with which the receiver is to be initialized. The pasteboard must contain a type returned by soundUnfilteredPasteboardTypes. The contained data must have a proper magic number, sound header, and data for the formats the NSSound class supports.

    Return Value

    Initialized NSSound instance.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the name assigned to the receiver.

    Declaration

    Swift

    var name: String? { get }

    Objective-C

    @property(readonly, copy) NSString *name

    Return Value

    Name assigned to the receiver; nil when no name has been assigned.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setName:

  • Registers the receiver under a given name.

    Declaration

    Swift

    func setName(_ soundName: String?) -> Bool

    Objective-C

    - (BOOL)setName:(NSString *)soundName

    Parameters

    soundName

    Name to assign the receiver. The name must be unused by other NSSound instances.

    Return Value

    YEStrue when successful; NOfalse otherwise.

    Discussion

    If the receiver is already registered under another name, this method first unregisters the prior name.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Provides the volume of the receiver.

    Declaration

    Swift

    var volume: Float

    Objective-C

    @property float volume

    Return Value

    Volume of the receiver.

    Discussion

    The valid range is between 0.0 and 1.0.

    This method does not affect the systemwide volume.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – setVolume:

  • Specifies the volume of the receiver.

    Declaration

    Swift

    var volume: Float

    Objective-C

    @property float volume

    Parameters

    volume

    Volume at which the receiver is to play.

    Discussion

    The valid range is between 0.0 and 1.0.

    This method does not affect the systemwide volume.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – volume

  • Provides the receiver’s playback progress in seconds.

    Declaration

    Swift

    var currentTime: NSTimeInterval

    Objective-C

    @property NSTimeInterval currentTime

    Return Value

    Receiver’s playback progress in seconds.

    Discussion

    Sounds start with currentTime == 0 and end with currentTime == ([<sound> duration] - 1).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receivers playback progress in seconds.

    Declaration

    Swift

    var currentTime: NSTimeInterval

    Objective-C

    @property NSTimeInterval currentTime

    Parameters

    currentTime

    Playback progress for the receiver.

    Discussion

    This property is not archived, copied, or stored on the pasteboard.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – currentTime

  • Indicates whether the receiver restarts playback when it reaches the end of its content. Default: NOfalse.

    Declaration

    Swift

    var loops: Bool

    Objective-C

    @property BOOL loops

    Return Value

    YEStrue when the receiver restarts playback when it finishes, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – setLoops:

  • Specifies whether the receiver restarts playback when it reaches the end of its content.

    Declaration

    Swift

    var loops: Bool

    Objective-C

    @property BOOL loops

    Parameters

    Term

    YEStrue to have the receiver restart playback when it reaches the end of its content.

    NOfalse to have the receiver conclude playback, instead.

    Discussion

    When loops is YEStrue, the receiver does not send sound:didFinishPlaying: to its delegate when it reaches the end of its content and restarts playback.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Identifies the receiver’s output device.

    Declaration

    Swift

    var playbackDeviceIdentifier: String?

    Objective-C

    @property(copy) NSString *playbackDeviceIdentifier

    Return Value

    Unique identifier of a sound output device.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receiver’s output device.

    Declaration

    Swift

    var playbackDeviceIdentifier: String?

    Objective-C

    @property(copy) NSString *playbackDeviceIdentifier

    Parameters

    playbackDeviceIdentifier

    Unique identifier of a sound output device.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Provides the receiver’s channel map.

    Declaration

    Objective-C

    - (NSArray *)channelMapping

    Return Value

    The receiver’s audio-channel–to–device–channel mappings.

    Discussion

    A channel map correlates a sound’s channels to the the output-device’s channels. For example, a two-channel sound being played on a five-channel device should have a channel map to optimize the sound-playing experience. The default map, correlates the first sound channel to the first output channel, the second sound channel to the second output channel, and so on.

    For details about channel maps, see Core Audio Overview > “Common Tasks in OS X.”

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.9.

  • Specifies the receiver’s channel map.

    Declaration

    Objective-C

    - (void)setChannelMapping:(NSArray *)channelMapping

    Parameters

    channelMapping

    Audio-channel—to—device–channel mappings for the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.9.

  • Returns the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSSoundDelegate?

    Objective-C

    @property(assign) id<NSSoundDelegate> delegate

    Return Value

    The receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Set the receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSSoundDelegate?

    Objective-C

    @property(assign) id<NSSoundDelegate> delegate

    Parameters

    delegate

    Object to serve as the receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – delegate

  • Provides the file types the NSSound class understands.

    Declaration

    Swift

    class func soundUnfilteredTypes() -> [AnyObject]

    Objective-C

    + (NSArray *)soundUnfilteredTypes

    Return Value

    Array of UTIs identifying the file types the NSSound class understands.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the NSSound instance associated with a given name.

    Declaration

    Swift

    init?(named soundName: String) -> NSSound

    Objective-C

    + (NSSound *)soundNamed:(NSString *)soundName

    Parameters

    soundName

    Name that identifies sound data.

    Return Value

    NSSound instance initialized with the sound data identified by soundName.

    Discussion

    The returned object can be one of the following:

    • One that’s been assigned a name with setName:

    • One of the named system sounds provided by the Application Kit framework

    If there’s no known NSSound object with soundName, this method tries to create one by searching for sound files in the application’s main bundle (see NSBundle for a description of how the bundle’s contents are searched). If no sound file can be located in the application main bundle, the following directories are searched in order:

    • ~/Library/Sounds

    • /Library/Sounds

    • /Network/Library/Sounds

    • /System/Library/Sounds

    If no data can be found for soundName, no object is created, and nil is returned.

    The preferred way to locate a sound is to pass a name without the file extension. See the class description for a list of the supported sound file extensions.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Provides the duration of the receiver in seconds.

    Declaration

    Swift

    var duration: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval duration

    Return Value

    Duration of the receiver in seconds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • isPlaying - isPlaying Available in OS X v10.0 through OS X v10.9

    Indicates whether the receiver is playing its audio data.

    Declaration

    Objective-C

    - (BOOL)isPlaying

    Return Value

    YEStrue when the receiver is playing its audio data, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • Pauses audio playback.

    Declaration

    Swift

    func pause() -> Bool

    Objective-C

    - (BOOL)pause

    Return Value

    YEStrue when playback is paused successfully, NOfalse when playback is already paused or when an error occurred.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initiates audio playback.

    Declaration

    Swift

    func play() -> Bool

    Objective-C

    - (BOOL)play

    Return Value

    YEStrue when playback is initiated, NOfalse when playback is already in progress or when an error occurred.

    Discussion

    This method initiates playback asynchronously and returns control to your application. Therefore, your application can continue doing work while the audio is playing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Resumes audio playback.

    Declaration

    Swift

    func resume() -> Bool

    Objective-C

    - (BOOL)resume

    Return Value

    YEStrue when playback is resumed, NOfalse when playback is in progress or when an error occurred.

    Discussion

    Assumes the receiver has been previously paused by sending it pause.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Concludes audio playback.

    Declaration

    Swift

    func stop() -> Bool

    Objective-C

    - (BOOL)stop

    Return Value

    YEStrue when playback is concluded successfully or if it’s paused, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – sound:didFinishPlaying: (NSSoundDelegate)

  • Writes the receiver’s data to a pasteboard.

    Declaration

    Swift

    func writeToPasteboard(_ pasteboard: NSPasteboard)

    Objective-C

    - (void)writeToPasteboard:(NSPasteboard *)pasteboard

    Parameters

    pasteboard

    Pasteboard to which the receiver is to write its data.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Provides the list of file types the NSSound class understands.

    Deprecation Statement

    Use soundUnfilteredTypes.

    Declaration

    Objective-C

    + (NSArray *)soundUnfilteredFileTypes

    Return Value

    Array of strings representing the file types the NSSound class understands.

    Discussion

    The returned array may be passed directly to the runModalForTypes: method of the NSOpenPanel class.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

  • Provides a list of the pasteboard types that the NSSound class can accept.

    Deprecation Statement

    Use soundUnfilteredTypes.

    Declaration

    Objective-C

    + (NSArray *)soundUnfilteredPasteboardTypes

    Return Value

    Array of pasteboard types that the NSSound class can accept.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.5.

  • The NSSound class defines this common pasteboard data type.

    Declaration

    Swift

    let NSSoundPboardType: String

    Objective-C

    NSString *NSSoundPboardType;

    Constants

    • NSSoundPboardType

      NSSoundPboardType

      NSSound data

      Available in OS X v10.0 and later.