AVCaptureSession Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
AVCaptureSession.h
Related sample code

Overview

You use an AVCaptureSession object to coordinate the flow of data from AV input devices to outputs.

To perform a real-time or offline capture, you instantiate an AVCaptureSession object and add appropriate inputs (such as AVCaptureDeviceInput), and outputs (such as AVCaptureMovieFileOutput). The following code fragment illustrates how to configure a capture device to record audio:

AVCaptureSession *captureSession = [[AVCaptureSession alloc] init];
AVCaptureDevice *audioCaptureDevice = [AVCaptureDevice defaultDeviceWithMediaType:AVMediaTypeAudio];
NSError *error = nil;
AVCaptureDeviceInput *audioInput = [AVCaptureDeviceInput deviceInputWithDevice:audioCaptureDevice error:&error];
if (audioInput) {
    [captureSession addInput:audioInput];
}
else {
    // Handle the failure.
}

You invoke startRunning to start the flow of data from the inputs to the outputs, and invoke stopRunning to stop the flow.

You use the sessionPreset property to customize the quality level, bitrate, or other settings for the output. Most common capture configurations are available through session presets; however, some specialized options (such as high frame rate) require directly setting a capture format on an AVCaptureDevice instance.

Tasks

Managing Inputs and Outputs

Managing Running State

Configuration Change

Managing Session Presets

Sharing the Application’s Audio Session

Synchronizing Multiple Inputs and Outputs

Properties

automaticallyConfiguresApplicationAudioSession

A Boolean value that indicates whether the capture session automatically changes settings in the app’s shared audio session.

@property(nonatomic) BOOL automaticallyConfiguresApplicationAudioSession
Discussion

This property only takes effect if the value of the usesApplicationAudioSession property is YES.

The value of this property defaults to YES, causing the capture session to automatically configure the app’s shared AVAudioSession instance for optimal recording. For example, if the capture session uses a device’s rear-facing camera, the audio session’s microphone and polar pattern will be set for optimal recording of sound from that direction. Note that the audio session’s original state is not restored after capture finishes.

If you set this property’s value to NO, your app is responsible for selecting appropriate audio session settings. Recording may fail if the audio session’s settings are incompatible with the capture session.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureSession.h

inputs

The capture session’s inputs. (read-only)

@property(nonatomic, readonly) NSArray *inputs
Discussion

The array contains instances of subclasses of AVCaptureInput.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

interrupted

Indicates whether the receiver has been interrupted. (read-only)

@property(nonatomic, readonly, getter=isInterrupted) BOOL interrupted
Discussion

You can observe the value of this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

masterClock

A clock object used for output synchronization. (read-only)

@property(nonatomic, readonly) CMClockRef masterClock
Discussion

The returned CMClock object is read-only and provides a timebase for sample buffers in capture output. This can be used in conjunction with the clock from an AVCaptureInputPort object to synchronize timestamps from multiple devices.

You can observe the value of this property using key-value observing.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureSession.h

outputs

The capture session’s outputs. (read-only)

@property(nonatomic, readonly) NSArray *outputs
Discussion

The array contains instances of subclasses of AVCaptureOutput.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

running

Indicates whether the receiver is running. (read-only)

@property(nonatomic, readonly, getter=isRunning) BOOL running
Discussion

You can observe the value of this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

sessionPreset

A constant value indicating the quality level or bitrate of the output.

@property(nonatomic, copy) NSString *sessionPreset
Discussion

You use this property to customize the quality level or bitrate of the output. For possible values of sessionPreset, see “Video Input Presets.” The default value is AVCaptureSessionPresetHigh.

You can set this value while the session is running.

You can only set a preset if canSetSessionPreset: returns YES for that preset.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

usesApplicationAudioSession

Indicates whether the capture session will make use of the app’s shared audio session.

@property(nonatomic) BOOL usesApplicationAudioSession
Discussion

If the value of this property is NO, the capture session makes use of a private AVAudioSession instance for audio recording, which may cause interruption if your app uses its own audio session for playback.

For apps linked against iOS 7.0 or newer, this property defaults to YES, allowing simultaneous playback and recording.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureSession.h

Instance Methods

addInput:

Adds a given input to the session.

- (void)addInput:(AVCaptureInput *)input
Parameters
input

An input to add to the session.

Discussion

You can only add an input to a session using this method if canAddInput: returns YES.

You can invoke this method while the session is running.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

addOutput:

Adds a given output to the session.

- (void)addOutput:(AVCaptureOutput *)output
Parameters
output

An output to add to the session.

Discussion

You can only add an output to a session using this method if canAddOutput: returns YES.

You can invoke this method while the session is running.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

beginConfiguration

Indicates the start of a set of configuration changes to be made atomically.

- (void)beginConfiguration
Discussion

You use beginConfiguration and commitConfiguration to batch multiple configuration operations on a running session into an atomic update.

After calling beginConfiguration, you can for example add or remove outputs, alter the sessionPreset, or configure individual capture input or output properties. No changes are actually made until you invoke commitConfiguration, at which time they are applied together.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureSession.h

canAddInput:

Returns a Boolean value that indicates whether a given input can be added to the session.

- (BOOL)canAddInput:(AVCaptureInput *)input
Parameters
input

An input that you want to add to the session.

Return Value

YES if input can be added to the session, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

canAddOutput:

Returns a Boolean value that indicates whether a given output can be added to the session.

- (BOOL)canAddOutput:(AVCaptureOutput *)output
Parameters
output

An output that you want to add to the session.

Return Value

YES if output can be added to the session, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

canSetSessionPreset:

Returns a Boolean value that indicates whether the receiver can use the given preset.

- (BOOL)canSetSessionPreset:(NSString *)preset
Parameters
preset

A preset you would like to set for the receiver. For possible values, see “Video Input Presets.”

Return Value

YES if the receiver can use preset, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

commitConfiguration

Commits a set of configuration changes.

- (void)commitConfiguration
Discussion

For discussion, see beginConfiguration.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureSession.h

removeInput:

Removes a given input.

- (void)removeInput:(AVCaptureInput *)input
Parameters
input

An input to remove from the receiver.

Discussion

You can invoke this method while the session is running.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureSession.h

removeOutput:

Removes a given output.

- (void)removeOutput:(AVCaptureOutput *)output
Parameters
output

An output to remove from the receiver.

Discussion

You can invoke this method while the session is running.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

startRunning

Tells the receiver to start running.

- (void)startRunning
Discussion

This method is used to start the flow of data from the inputs to the outputs connected to the AVCaptureSession instance that is the receiver. This method is synchronous and blocks until the receiver has either completely started running or failed to start running. If an error occurs during this process and the receiver fails to start running, you receive an AVCaptureSessionRuntimeErrorNotification.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

stopRunning

Tells the receiver to stop running.

- (void)stopRunning
Discussion

This method is used to stop the flow of data from the inputs to the outputs connected to the AVCaptureSession instance that is the receiver. This method is synchronous and blocks until the receiver has completely stopped running.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureSession.h

Constants

AVCaptureVideoOrientation

Constants to specify the device orientation during video capture.

enum {
   AVCaptureVideoOrientationPortrait                = 1,
   AVCaptureVideoOrientationPortraitUpsideDown,
   AVCaptureVideoOrientationLandscapeLeft,
   AVCaptureVideoOrientationLandscapeRight,
};
typedef NSInteger AVCaptureVideoOrientation;
Constants
AVCaptureVideoOrientationPortrait

Indicates that video should be oriented vertically, with the device home button on the bottom.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationPortraitUpsideDown

Indicates that video should be oriented vertically, with the device home button on the top.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeLeft

Indicates that video should be oriented horizontally, with the device home button on the right.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureVideoOrientationLandscapeRight

Indicates that video should be oriented horizontally, with the device home button on the left.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

Notification User Info Key

Key to retrieve information from a notification from a capture session.

NSString *const AVCaptureSessionErrorKey;
Constants
AVCaptureSessionErrorKey

Key to retrieve the error object from the user info dictionary of an AVCaptureSessionRuntimeErrorNotification.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

Video Input Presets

Constants to define capture setting presets using the sessionPreset property.

NSString *const AVCaptureSessionPresetPhoto;
NSString *const AVCaptureSessionPresetHigh;
NSString *const AVCaptureSessionPresetMedium;
NSString *const AVCaptureSessionPresetLow;
NSString *const AVCaptureSessionPreset352x288;
NSString *const AVCaptureSessionPreset640x480;
NSString *const AVCaptureSessionPreset1280x720;
NSString *const AVCaptureSessionPreset1920x1080;
NSString *const AVCaptureSessionPresetiFrame960x540;
NSString *const AVCaptureSessionPresetiFrame1280x720;
NSString *const AVCaptureSessionPresetInputPriority;
Constants
AVCaptureSessionPresetPhoto

Specifies capture settings suitable for high resolution photo quality output.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetHigh

Specifies capture settings suitable for high quality video and audio output.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetMedium

Specifies capture settings suitable for output video and audio bitrates suitable for sharing over WiFi.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetLow

Specifies capture settings suitable for output video and audio bitrates suitable for sharing over 3G.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPreset352x288

Specifies capture settings suitable for CIF quality (352x288 pixel) video output.

Available in iOS 5.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPreset640x480

Specifies capture settings suitable for VGA quality (640x480 pixel) video output.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPreset1280x720

Specifies capture settings suitable for 720p quality (1280x720 pixel) video output.

Available in iOS 4.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPreset1920x1080

Specifies capture settings suitable for 1080p quality (1920x1080 pixel) video output.

Available in iOS 5.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetiFrame960x540

Specifies capture settings to achieve 960x540 quality iFrame H.264 video at about 30 Mbits/sec with AAC audio.

QuickTime movies captured in iFrame format are optimal for editing applications.

Available in iOS 5.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetiFrame1280x720

Specifies capture settings to achieve 1280x720 quality iFrame H.264 video at about 40 Mbits/sec with AAC audio.

QuickTime movies captured in iFrame format are optimal for editing applications.

Available in iOS 5.0 and later.

Declared in AVCaptureSession.h.

AVCaptureSessionPresetInputPriority

Specifies that the capture session does not control audio and video output settings.

To enable capture settings not supported by any session presets (such as high frame rate), change the value of the activeFormat property on the appropriate capture device. When you change the device’s format, the session preset automatically changes to this value, indicating that the AVCaptureSession object has relinquished responsibility for configuring its inputs and outputs. (Instead, the capture device’s active format dictates the quality of service level provided at the outputs.) To return to automatic configuration, use the session’s sessionPreset property to choose another preset.

Available in iOS 7.0 and later.

Declared in AVCaptureSession.h.

Notifications

AVCaptureSessionRuntimeErrorNotification

Posted if an error occurred during a capture session.

You retrieve the underlying error from the notification’s user info dictionary using the key AVCaptureSessionErrorKey.

Availability
Declared In
AVCaptureSession.h

AVCaptureSessionDidStartRunningNotification

Posted when a capture session starts.
Availability
Declared In
AVCaptureSession.h

AVCaptureSessionDidStopRunningNotification

Posted when a capture session stops.
Availability
Declared In
AVCaptureSession.h

AVCaptureSessionWasInterruptedNotification

Posted if a capture session is interrupted.
Availability
Declared In
AVCaptureSession.h

AVCaptureSessionInterruptionEndedNotification

Posted if an interruption to a capture session finishes.
Availability
Declared In
AVCaptureSession.h