Class: AVAudioPlayer

Inherits:
NSObject show all

Overview

An instance of the AVAudioPlayer class, called an audio player, provides playback of audio data from a file or memory.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Array) channelAssignments

An array of AVAudioSessionChannelDescription objects associated with the audio player The default value for this property is nil. When non-nil, this array must have the same number of elements as returned by the numberOfChannels property. You can use this property to help you assign output to play to different channels.

Returns:

- (NSTimeInterval) currentTime

The playback point, in seconds, within the timeline of the sound associated with the audio player. If the sound is playing, currentTime is the offset of the current playback position, measured in seconds from the start of the sound. If the sound is not playing, currentTime is the offset of where playing starts upon calling the play method, measured in seconds from the start of the sound.By setting this property you can seek to a specific point in a sound file or implement audio fast-forward and rewind functions.

Returns:

  • (NSTimeInterval)

- (NSData) data (readonly)

The data object containing the sound associated with the audio player. (read-only) Returns nil if the audio player has no data (that is, if it was not initialized with an NSData object).

Returns:

- (Object) delegate

The delegate object for the audio player. The object that you assign to be an audio player’s delegate becomes the target of the notifications described in AVAudioPlayerDelegate Protocol Reference. These notifications let you respond to decoding errors, audio interruptions (such as an incoming phone call), and playback completion.

Returns:

- (NSTimeInterval) deviceCurrentTime (readonly)

The time value, in seconds, of the audio output device. (read-only) The value of this property increases monotonically while an audio player is playing or paused.If more than one audio player is connected to the audio output device, device time continues incrementing as long as at least one of the players is playing or paused.If the audio output device has no connected audio players that are either playing or paused, device time reverts to 0.Use this property to indicate “now” when calling the playAtTime: instance method. By configuring multiple audio players to play at a specified offset from deviceCurrentTime, you can perform precise synchronization—as described in the discussion for that method.

Returns:

  • (NSTimeInterval)

- (NSTimeInterval) duration (readonly)

Returns the total duration, in seconds, of the sound associated with the audio player. (read-only)

Returns:

  • (NSTimeInterval)

- (Boolean) enableRate

A Boolean value that specifies whether playback rate adjustment is enabled for an audio player. To enable adjustable playback rate for an audio player, set this property to YES after you initialize the player and before you call the prepareToPlay instance method for the player.

Returns:

  • (Boolean)

- (Boolean) meteringEnabled

A Boolean value that specifies the audio-level metering on/off state for the audio player. The default value for the meteringEnabled property is off (Boolean NO). Before using metering for an audio player, you need to enable it by setting this property to YES. If player is an audio player instance variable of your controller class, you enable metering as shown here:

Returns:

  • (Boolean)

- (Integer) numberOfChannels (readonly)

The number of audio channels in the sound associated with the audio player. (read-only)

Returns:

- (Integer) numberOfLoops

The number of times a sound will return to the beginning, upon reaching the end, to repeat playback. A value of 0, which is the default, means to play the sound once. Set a positive integer value to specify the number of times to return to the start and play again. For example, specifying a value of 1 results in a total of two plays of the sound. Set any negative integer value to loop the sound indefinitely until you call the stop method.

Returns:

- (Float) pan

The audio player’s stereo pan position. By setting this property you can position a sound in the stereo field. A value of –1.0 is full left, 0.0 is center, and 1.0 is full right.

Returns:

- (Boolean) playing (readonly)

A Boolean value that indicates whether the audio player is playing (YES) or not (NO). (read-only) To find out when playback has stopped, use the audioPlayerDidFinishPlaying:successfully: delegate method.Important: Do not poll this property (that is, do not use it inside of a loop) in an attempt to discover when playback has stopped.

Returns:

  • (Boolean)

- (Float) rate

The audio player’s playback rate. This property’s default value of 1.0 provides normal playback rate. The available range is from 0.5 for half-speed playback through 2.0 for double-speed playback.To set an audio player’s playback rate, you must first enable rate adjustment as described in the enableRate property description.

Returns:

- (Hash) settings (readonly)

The audio player’s settings dictionary, containing information about the sound associated with the player. (read-only) An audio player’s settings dictionary contains keys for the following information about the player’s associated sound:Channel layout (AVChannelLayoutKey)Encoder bit rate (AVEncoderBitRateKey)Audio data format (AVFormatIDKey)Channel count (AVNumberOfChannelsKey)Sample rate (AVSampleRateKey)The settings keys are described in AV Foundation Audio Settings Constants.

Returns:

- (NSURL) url (readonly)

The URL for the sound associated with the audio player. (read-only) Returns nil if the audio player was not initialized with a URL.

Returns:

- (Float) volume

The playback gain for the audio player, ranging from 0.0 through 1.0.

Returns:

Instance Method Details

- (Float) averagePowerForChannel(channelNumber)

Returns the average power for a given channel, in decibels, for the sound being played. To obtain a current average power value, you must call the updateMeters method before calling this method.

Parameters:

  • channelNumber (Integer)

    The audio channel whose average power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.

Returns:

  • (Float)

    A floating-point representation, in decibels, of a given audio channel’s current average power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence). If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).

- (Object) initWithContentsOfURL(url, error:outError)

Initializes and returns an audio player for playing a designated sound file.

Parameters:

  • url (NSURL)

    A URL identifying the sound file to play. The audio data must be in a format supported by Core Audio. See “Using Sound in iOS” in iOS App Programming Guide.

  • outError (Pointer)

    Pass in the address of a nil-initialized NSError object. If an error occurs, upon return the NSError object describes the error. If you do not want error information, pass in NULL.

Returns:

  • (Object)

    On success, an initialized AVAudioPlayer object. If nil, the outError parameter contains a code that describes the problem.

- (Object) initWithData(data, error:outError)

Initializes and returns an audio player for playing a designated memory buffer.

Parameters:

  • data (NSData)

    A block of data containing a sound to play. The audio data must be in a format supported by Core Audio. See “Using Sound in iOS” in iOS App Programming Guide.

  • outError (Pointer)

    Pass in the address of a nil-initialized NSError object. If an error occurs, upon return the NSError object describes the error. If you do not want error information, pass in NULL.

Returns:

  • (Object)

    On success, an initialized AVAudioPlayer object. If nil, the outError parameter contains a code that describes the problem.

- (Object) pause

Pauses playback; sound remains ready to resume playback from where it left off. Calling pause leaves the audio player prepared to play; it does not release the audio hardware that was acquired upon calling play or prepareToPlay.

Returns:

- (Float) peakPowerForChannel(channelNumber)

Returns the peak power for a given channel, in decibels, for the sound being played. To obtain a current peak power value, you must call the updateMeters method before calling this method.

Parameters:

  • channelNumber (Integer)

    The audio channel whose peak power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.

Returns:

  • (Float)

    A floating-point representation, in decibels, of a given audio channel’s current peak power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence).If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).

- (Boolean) play

Plays a sound asynchronously. Calling this method implicitly calls the prepareToPlay method if the audio player is not already prepared to play.

Returns:

  • (Boolean)

    Returns YES on success, or NO on failure.

- (Boolean) playAtTime(time)

Plays a sound asynchronously, starting at a specified point in the audio output device’s timeline. Use this method to precisely synchronize the playback of two or more AVAudioPlayer objects. This code snippet shows the recommended way to do this:To learn about the virtual audio output device’s timeline, read the description for the deviceCurrentTime property.Calling this method implicitly calls the prepareToPlay method if the audio player is not already prepared to play.

Parameters:

  • time (NSTimeInterval)

    The number of seconds to delay playback, relative to the audio output device’s current time. For example, to start playback three seconds into the future from the time you call this method, use code like this:NSTimeInterval playbackDelay = 3.0; // must be ≥ 0[myAudioPlayer playAtTime: myAudioPlayer.deviceCurrentTime + playbackDelay];Important: The value that you provide to the time parameter must be greater than or equal to the value of the audio player’s deviceCurrentTime property.

Returns:

  • (Boolean)

    YES on success, or NO on failure.

- (Boolean) prepareToPlay

Prepares the audio player for playback by preloading its buffers. Calling this method preloads buffers and acquires the audio hardware needed for playback, which minimizes the lag between calling the play method and the start of sound output.Calling the stop method, or allowing a sound to finish playing, undoes this setup.

Returns:

  • (Boolean)

    Returns YES on success, or NO on failure.

- (Object) stop

Stops playback and undoes the setup needed for playback. Calling this method, or allowing a sound to finish playing, undoes the setup performed upon calling the play or prepareToPlay methods.The stop method does not reset the value of the currentTime property to 0. In other words, if you call stop during playback and then call play, playback resumes at the point where it left off.

Returns:

- (Object) updateMeters

Refreshes the average and peak power values for all channels of an audio player. To obtain current audio power values, you must call this method before calling averagePowerForChannel: or peakPowerForChannel:.

Returns: