iPhone OS Reference Library Apple Developer Connection spyglass button

AVAudioRecorder Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iPhone OS 3.0 and later.
Declared in
AVAudioRecorder.h
AVAudioSettings.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:

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.

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

Tasks

Initializing an AVAudioRecorder Object

Configuring and Controlling Recording

Managing Information About a Recording

Using Audio Level Metering

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

currentTime

The time, in seconds, since the beginning of the recording.

@property (readonly) NSTimeInterval currentTime;
Discussion

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

Availability
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
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
Declared In
AVAudioRecorder.h

recording

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

@property (readonly, getter=isRecording) BOOL recording;
Availability
Declared In
AVAudioRecorder.h

settings

The audio settings for the audio recorder.

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

Availability
See Also
Declared In
AVAudioRecorder.h

url

The URL for the audio file associated with the audio recorder.

@property (readonly) NSURL *url;
Availability
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 iPhone OS 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 iPhone OS 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 “General Audio Format Settings,” “Linear PCM Format Settings,” “Encoder Settings,” and “Sample Rate Conversion Settings.”

outError

On success, contains nil. On failure, contains an error code.

Return Value

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

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

pause

Pauses a recording.

- (void)pause

Discussion

Call record to resume recording.

Availability
  • Available in iPhone OS 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 iPhone OS 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 iPhone OS 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 iPhone OS 3.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 iPhone OS 3.0 and later.
Declared In
AVAudioRecorder.h

stop

Stops recording and closes the audio file.

- (void)stop

Availability
  • Available in iPhone OS 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 iPhone OS 3.0 and later.
See Also
Declared In
AVAudioRecorder.h

Constants

General Audio Format Settings

Audio settings that apply to all audio formats handled by the AV Foundation framework.

NSString *const AVFormatIDKey;
NSString *const AVSampleRateKey;
NSString *const AVNumberOfChannelsKey;
Constants
AVFormatIDKey

A format identifier. See the “Audio Data Format Identifers” enumeration in Core Audio Data Types Reference.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVSampleRateKey

A sample rate, in hertz, expressed as an NSNumber floating point value.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVNumberOfChannelsKey

The number of channels expressed as an NSNumber integer value.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

Linear PCM Format Settings

Audio settings that apply to linear PCM audio formats.

NSString *const AVLinearPCMBitDepthKey;
NSString *const AVLinearPCMIsBigEndianKey;
NSString *const AVLinearPCMIsFloatKey;
Constants
AVLinearPCMBitDepthKey

An NSNumber integer that indicates the bit depth for a linear PCM audio format—one of 8, 16, 24, or 32.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVLinearPCMIsBigEndianKey

A Boolean value that indicates whether the audio format is big endian (YES) or little endian (NO).

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVLinearPCMIsFloatKey

A Boolean value that indicates that the audio format is floating point (YES) or fixed point (NO).

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

Encoder Settings

Audio encoder settings.

NSString *const AVEncoderAudioQualityKey;
NSString *const AVEncoderBitRateKey;
NSString *const AVEncoderBitDepthHintKey;
Constants
AVEncoderAudioQualityKey

A constant from “Audio Quality Flags.”

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVEncoderBitRateKey

An integer that identifies the bit rate, in hertz.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVEncoderBitDepthHintKey

An integer ranging from 8 through 32.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

Sample Rate Conversion Settings

Sample rate conversion settings.

NSString *const AVSampleRateConverterAudioQualityKey;
Constants
AVSampleRateConverterAudioQualityKey

An NSNumber integer value. See “Audio Quality Flags.”

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

Audio Quality Flags

Keys that specify sample rate conversion quality, used for the AVSampleRateConverterAudioQualityKey property.

enum {
   AVAudioQualityMin       = 0,
   AVAudioQualityLow       = 0x20,
   AVAudioQualityMedium    = 0x40,
   AVAudioQualityHigh      = 0x60,
   AVAudioQualityMax       = 0x7F
};
typedef NSInteger AVAudioQuality;
Constants
AVAudioQualityMin

The minimum quality for sample rate conversion.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVAudioQualityLow

Low quality rate conversion.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVAudioQualityMedium

Medium quality sample rate conversion.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVAudioQualityHigh

High quality sample rate conversion.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.

AVAudioQualityMax

Maximum quality sample rate conversion.

Available in iPhone OS 3.0 and later.

Declared in AVAudioSettings.h.



Last updated: 2009-10-19

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