iOS Developer Library — Pre-Release

Developer

AVFoundation Framework Reference AVCaptureSession Class Reference

Options
Deployment Target:

On This Page
Language:

AVCaptureSession

Inheritance


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.

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.

  • inputs inputs Property

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

    Declaration

    Swift

    var inputs: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *inputs

    Discussion

    The array contains instances of subclasses of AVCaptureInput.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func canAddInput(_ input: AVCaptureInput!) -> Bool

    Objective-C

    - (BOOL)canAddInput:(AVCaptureInput *)input

    Parameters

    input

    An input that you want to add to the session.

    Return Value

    YEStrue if input can be added to the session, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    – addInput:

  • Adds a given input to the session.

    Declaration

    Swift

    func addInput(_ input: AVCaptureInput!)

    Objective-C

    - (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 YEStrue.

    You can invoke this method while the session is running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Removes a given input.

    Declaration

    Swift

    func removeInput(_ input: AVCaptureInput!)

    Objective-C

    - (void)removeInput:(AVCaptureInput *)input

    Parameters

    input

    An input to remove from the receiver.

    Discussion

    You can invoke this method while the session is running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    – addInput:

  • outputs outputs Property

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

    Declaration

    Swift

    var outputs: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *outputs

    Discussion

    The array contains instances of subclasses of AVCaptureOutput.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func canAddOutput(_ output: AVCaptureOutput!) -> Bool

    Objective-C

    - (BOOL)canAddOutput:(AVCaptureOutput *)output

    Parameters

    output

    An output that you want to add to the session.

    Return Value

    YEStrue if output can be added to the session, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    – addOutput:

  • Adds a given output to the session.

    Declaration

    Swift

    func addOutput(_ output: AVCaptureOutput!)

    Objective-C

    - (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 YEStrue.

    You can invoke this method while the session is running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Removes a given output.

    Declaration

    Swift

    func removeOutput(_ output: AVCaptureOutput!)

    Objective-C

    - (void)removeOutput:(AVCaptureOutput *)output

    Parameters

    output

    An output to remove from the receiver.

    Discussion

    You can invoke this method while the session is running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    – addOutput:

  • Tells the receiver to start running.

    Declaration

    Swift

    func startRunning()

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    – stopRunning

  • Tells the receiver to stop running.

    Declaration

    Swift

    func stopRunning()

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • running running Property

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

    Declaration

    Swift

    var running: Bool { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var interrupted: Bool { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func beginConfiguration()

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Commits a set of configuration changes.

    Declaration

    Swift

    func commitConfiguration()

    Objective-C

    - (void)commitConfiguration

    Discussion

    For discussion, see beginConfiguration.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var sessionPreset: String!

    Objective-C

    @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 YEStrue for that preset.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func canSetSessionPreset(_ preset: String!) -> Bool

    Objective-C

    - (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

    YEStrue if the receiver can use preset, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Adds a given capture connection to the session.

    Declaration

    Swift

    func addConnection(_ connection: AVCaptureConnection!)

    Objective-C

    - (void)addConnection:(AVCaptureConnection *)connection

    Parameters

    connection

    The capture connection to add to the session.

    Discussion

    You can only add an AVCaptureConnection instance to a session using this method if canAddConnection: returns YEStrue.

    When using addInput: or addOutput:, connections are formed automatically between all compatible inputs and outputs. Manually adding connections is only necessary when adding an input or output with no connections.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • Returns a Boolean value that indicates whether a given connection can be added to the receiver.

    Declaration

    Swift

    func canAddConnection(_ connection: AVCaptureConnection!) -> Bool

    Objective-C

    - (BOOL)canAddConnection:(AVCaptureConnection *)connection

    Parameters

    connection

    An AVCaptureConnection instance.

    Return Value

    YEStrue if connection can be added to the receiver, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • Adds an capture input to the session without forming any connections.

    Declaration

    Swift

    func addInputWithNoConnections(_ input: AVCaptureInput!)

    Objective-C

    - (void)addInputWithNoConnections:(AVCaptureInput *)input

    Parameters

    input

    The capture input to add to the session.

    Discussion

    You can invoke this method while the session is running.

    Typically you should use addInput: to add an input to a session. You use this method if you need fine-grained control over which inputs are connected to which outputs.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • Adds an capture output to the session without forming any connections.

    Declaration

    Swift

    func addOutputWithNoConnections(_ output: AVCaptureOutput!)

    Objective-C

    - (void)addOutputWithNoConnections:(AVCaptureOutput *)output

    Parameters

    output

    The capture output to add to the session.

    Discussion

    You can invoke this method while the session is running.

    Typically you should use addOutput: to add an output to a session. You use this method if you need fine-grained control over which inputs are connected to which outputs.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • Removes a capture connection from the session.

    Declaration

    Swift

    func removeConnection(_ connection: AVCaptureConnection!)

    Objective-C

    - (void)removeConnection:(AVCaptureConnection *)connection

    Parameters

    connection

    The capture connection to remove from the session.

    Discussion

    You can invoke this method while the session is running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var usesApplicationAudioSession: Bool

    Objective-C

    @property(nonatomic) BOOL usesApplicationAudioSession

    Discussion

    If the value of this property is NOfalse, 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 YEStrue, allowing simultaneous playback and recording.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var automaticallyConfiguresApplicationAudioSession: Bool

    Objective-C

    @property(nonatomic) BOOL automaticallyConfiguresApplicationAudioSession

    Discussion

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

    The value of this property defaults to YEStrue, 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 NOfalse, 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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var masterClock: CMClock! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Constants to specify the device orientation during video capture.

    Declaration

    Swift

    enum AVCaptureVideoOrientation : Int { case Portrait case PortraitUpsideDown case LandscapeRight case LandscapeLeft }

    Objective-C

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

    Constants

    • Portrait

      AVCaptureVideoOrientationPortrait

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

      Available in iOS 4.0 and later.

    • PortraitUpsideDown

      AVCaptureVideoOrientationPortraitUpsideDown

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

      Available in iOS 4.0 and later.

    • LandscapeLeft

      AVCaptureVideoOrientationLandscapeLeft

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

      Available in iOS 4.0 and later.

    • LandscapeRight

      AVCaptureVideoOrientationLandscapeRight

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

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    let AVCaptureSessionErrorKey: String

    Objective-C

    NSString *const AVCaptureSessionErrorKey;

    Constants

  • Constants to define capture setting presets using the sessionPreset property.

    Declaration

    Swift

    let AVCaptureSessionPresetPhoto: String let AVCaptureSessionPresetHigh: String let AVCaptureSessionPresetMedium: String let AVCaptureSessionPresetLow: String let AVCaptureSessionPreset352x288: String let AVCaptureSessionPreset640x480: String let AVCaptureSessionPreset1280x720: String let AVCaptureSessionPreset1920x1080: String let AVCaptureSessionPresetiFrame960x540: String let AVCaptureSessionPresetiFrame1280x720: String let AVCaptureSessionPresetInputPriority: String

    Objective-C

    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

      AVCaptureSessionPresetPhoto

      Specifies capture settings suitable for high resolution photo quality output.

      Available in iOS 4.0 and later.

    • AVCaptureSessionPresetHigh

      AVCaptureSessionPresetHigh

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

      Available in iOS 4.0 and later.

    • AVCaptureSessionPresetMedium

      AVCaptureSessionPresetMedium

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

      Available in iOS 4.0 and later.

    • AVCaptureSessionPresetLow

      AVCaptureSessionPresetLow

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

      Available in iOS 4.0 and later.

    • AVCaptureSessionPreset352x288

      AVCaptureSessionPreset352x288

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

      Available in iOS 5.0 and later.

    • AVCaptureSessionPreset640x480

      AVCaptureSessionPreset640x480

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

      Available in iOS 4.0 and later.

    • AVCaptureSessionPreset1280x720

      AVCaptureSessionPreset1280x720

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

      Available in iOS 4.0 and later.

    • AVCaptureSessionPreset1920x1080

      AVCaptureSessionPreset1920x1080

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

      Available in iOS 5.0 and later.

    • AVCaptureSessionPresetiFrame960x540

      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.

    • AVCaptureSessionPresetiFrame1280x720

      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.

    • AVCaptureSessionPresetInputPriority

      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.