AVAudioRecorder Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 3.0 and later.
Declared in
AVAudioRecorder.h

Overview

An instance of the AVAudioRecorder class, called an audio recorder, provides audio recording capability in your application. Using an audio recorder you can:

In iOS, the audio being recorded comes from the device connected by the user—built-in microphone or headset microphone, for example. In OS X, the audio comes from the system’s default audio input device as set by a user in System Preferences.

You can implement a delegate object for an audio recorder to respond to audio interruptions and audio decoding errors, and to the completion of a recording.

To configure a recording, including options such as bit depth, bit rate, and sample rate conversion quality, configure the audio recorder’s settings dictionary. Use the settings keys described in AV Foundation Audio Settings Constants.

To configure an appropriate audio session for recording, refer to AVAudioSession Class Reference and AVAudioSessionDelegate Protocol Reference.

The AVAudioRecorder class is intended to allow you to make audio recordings with very little programming overhead. Other classes that can be used for recording audio in iOS and OS X include AVCaptureAudioDataOutput and the Audio Queue services described in the Audio Queue Services Programming Guide.

In OS X, you can also use the AVCaptureAudioFileOutput class to record audio.

Tasks

Initializing an AVAudioRecorder Object

Configuring and Controlling Recording

Managing Information About a Recording

Using Audio Level Metering

Properties

channelAssignments

An array of AVAudioSessionChannelDescription objects associated with the recorder.

@property(nonatomic, copy) NSArray* channelAssignments
Discussion

The default value of this property is nil. When non-nil, this array must have the same number of elements as designated by the AVNumberOfChannelsKey in the settings property. You can use this property to help record specific channels.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioRecorder.h

currentTime

The time, in seconds, since the beginning of the recording. (read-only)

@property (readonly) NSTimeInterval currentTime;
Discussion

When the audio recorder is stopped, calling this method returns a value of 0.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

delegate

The delegate object for the audio recorder.

@property (assign) id <AVAudioRecorderDelegate> delegate;
Discussion

For a description of the audio recorder delegate, see AVAudioRecorderDelegate Protocol Reference.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

deviceCurrentTime

The time, in seconds, of the host device where the audio recorder is located. (read-only)

@property(readonly) NSTimeInterval deviceCurrentTime
Discussion

The value of this property is never 0. The value of this property is provided as a convenience to allow for time-relative scheduling of audio recording using the recordAtTime: and recordAtTime:forDuration: methods.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioRecorder.h

meteringEnabled

A Boolean value that indicates whether audio-level metering is enabled (YES), or not (NO).

@property (getter=isMeteringEnabled) BOOL meteringEnabled;
Discussion

By default, audio level metering is off for an audio recorder. Because metering uses computing resources, turn it on only if you intend to use it.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

recording

A Boolean value that indicates whether the audio recorder is recording (YES), or not (NO). (read-only)

@property (readonly, getter=isRecording) BOOL recording;
Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

settings

The audio settings for the audio recorder. (read-only)

@property (readonly) NSDictionary *settings;
Discussion

Audio recorder settings are in effect only after you explicitly call the prepareToRecord method, or after you call it implicitly by starting recording. The audio settings keys are described in AV Foundation Audio Settings Constants.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

url

The URL for the audio file associated with the audio recorder. (read-only)

@property (readonly) NSURL *url;
Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

Instance Methods

averagePowerForChannel:

Returns the average power for a given channel, in decibels, for the sound being recorded.

- (float)averagePowerForChannel:(NSUInteger)channelNumber
Parameters
channelNumber

The number of the channel that you want the average power value for.

Return Value

The current average power, in decibels, for the sound being recorded. 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 recorder exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).

Discussion

To obtain a current average power value, you must call the updateMeters method before calling this method.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
AVAudioRecorder.h

deleteRecording

Deletes a recorded audio file.

- (BOOL)deleteRecording
Return Value

Returns YES on success, or NO on failure.

Discussion

The audio recorder must be stopped before you call this method.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

initWithURL:settings:error:

Initializes and returns an audio recorder.

- (id)initWithURL:(NSURL *)url settings:(NSDictionary *)settings error:(NSError **)outError
Parameters
url

The file system location to record to. The file type to record to is inferred from the file extension included in this parameter’s value.

settings

Settings for the recording session. For information on the settings available for an audio recorder, see AV Foundation Audio Settings Constants.

outError

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.

Return Value

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

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

pause

Pauses a recording.

- (void)pause
Discussion

Call record to resume recording.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

peakPowerForChannel:

Returns the peak power for a given channel, in decibels, for the sound being recorded.

- (float)peakPowerForChannel:(NSUInteger)channelNumber
Parameters
channelNumber

The number of the channel that you want the peak power value for.

Return Value

The current peak power, in decibels, for the sound being recorded. 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 recorder exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).

Discussion

To obtain a current peak power value, call the updateMeters method immediately before calling this method.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
AVAudioRecorder.h

prepareToRecord

Creates an audio file and prepares the system for recording.

- (BOOL)prepareToRecord
Return Value

Returns YES on success, or NO on failure.

Discussion

Creates an audio file at the location specified by the url parameter in the initWithURL:settings:error: method. If a file already exists at that location, this method overwrites it.

The preparation invoked by this method takes place automatically when you call record. Use prepareToRecord when you want recording to start as quickly as possible upon calling record.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

record

Starts or resumes recording.

- (BOOL)record
Return Value

Returns YES on success, or NO on failure.

Discussion

Calling this method implicitly calls prepareToRecord, which creates (or erases) an audio file and prepares the system for recording.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

recordAtTime:

Starts recording at a specific time.

- (BOOL)recordAtTime:(NSTimeInterval)time
Parameters
time

The number of seconds to delay the recording. For example, to start recording three seconds into the future from when you call this method, use code like this:

NSTimeInterval recordDelay = 3.0;                 //must be ≥ 0
[myAudioRecorder recordAtTime:(myAudioRecorder.deviceCurrentTime + recordDelay)];

Important: The value that you provide for the time parameter must be greater than or equal to the audio recorder’s deviceCurrentTime property.

Return Value

YES if the recording succeeds; otherwise NO.

Discussion

Calling this method implicitly calls prepareToRecord, which creates (or erases) an audio file and prepares the system for recording. You can use this method to produce synchronized audio recordings. This method can also be used for exactly periodic recordings or recordings that happen with exact offsets relative to each other.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioRecorder.h

recordAtTime:forDuration:

Starts recording at a specified time for a specified duration of time.

- (BOOL)recordAtTime:(NSTimeInterval)time forDuration:(NSTimeInterval)duration
Parameters
time

The number of seconds to delay the recording, relative to the deviceCurrentTime property.

Important: The value that you provide for the time parameter must be greater than or equal to the audio recorder’s deviceCurrentTime property.

duration

The maximum duration, in seconds, for the recording.

Return Value

YES if the recording succeeds; otherwise NO.

Discussion

Calling this method implicitly calls prepareToRecord, which creates (or erases) an audio file and prepares the system for recording. You can use this method to produce synchronized audio recordings of a specific length. The recorder will stop when the duration of recorded audio reaches the value in the duration parameter.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioRecorder.h

recordForDuration:

Records for a specified duration of time.

- (BOOL)recordForDuration:(NSTimeInterval)duration
Parameters
duration

The maximum duration, in seconds, for the recording.

Return Value

Returns YES on success, or NO on failure.

Discussion

The recorder stops when the duration of recorded audio reaches the value in the duration parameter.

Calling this method implicitly calls prepareToRecord, which creates (or erases) an audio file and prepares the system for recording.

Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

stop

Stops recording and closes the audio file.

- (void)stop
Availability
  • Available in iOS 3.0 and later.
Declared In
AVAudioRecorder.h

updateMeters

Refreshes the average and peak power values for all channels of an audio recorder.

- (void)updateMeters
Discussion

To obtain current audio power values, you must call this method before you call averagePowerForChannel: or peakPowerForChannel:.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
AVAudioRecorder.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...