Class

AVCaptureSession

An object that manages capture activity and coordinates the flow of data from input devices to capture outputs.

Declaration

class AVCaptureSession : NSObject

Overview

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.

Topics

Managing Inputs and Outputs

var inputs: [AVCaptureInput]

The capture session’s inputs.

func canAddInput(AVCaptureInput) -> Bool

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

func addInput(AVCaptureInput)

Adds a given input to the session.

func removeInput(AVCaptureInput)

Removes a given input.

var outputs: [AVCaptureOutput]

The capture session’s outputs.

func canAddOutput(AVCaptureOutput) -> Bool

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

func addOutput(AVCaptureOutput)

Adds a given output to the session.

func removeOutput(AVCaptureOutput)

Removes a given output.

Managing Running State

func startRunning()

Tells the receiver to start running.

func stopRunning()

Tells the receiver to stop running.

var isRunning: Bool

Indicates whether the receiver is running.

var isInterrupted: Bool

Indicates whether the receiver has been interrupted.

static let AVCaptureSessionRuntimeError: NSNotification.Name

Posted if an error occurred during a capture session.

static let AVCaptureSessionWasInterrupted: NSNotification.Name

Posted if a capture session is interrupted.

static let AVCaptureSessionInterruptionEnded: NSNotification.Name

Posted if an interruption to a capture session finishes.

let AVCaptureSessionErrorKey: String

Key to retrieve the error object from a AVCaptureSessionRuntimeError user info dictionary.

let AVCaptureSessionInterruptionReasonKey: String

Key to retrieve information about a capture interruption from a AVCaptureSessionWasInterrupted user info dictionary.

let AVCaptureSessionInterruptionSystemPressureStateKey: String

The key for retrieving information about system pressure factors that caused a capture session interruption.

enum AVCaptureSession.InterruptionReason

Constants identifying the reason a capture session was interrupted, found in a AVCaptureSessionWasInterrupted user info dictionary.

Configuration Change

func beginConfiguration()

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

func commitConfiguration()

Commits a set of configuration changes.

Managing Session Presets

var sessionPreset: AVCaptureSession.Preset

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

struct AVCaptureSession.Preset

Constants to define capture setting presets using the sessionPreset property.

func canSetSessionPreset(AVCaptureSession.Preset) -> Bool

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

Managing Connections

func addConnection(AVCaptureConnection)

Adds a given capture connection to the session.

func canAddConnection(AVCaptureConnection) -> Bool

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

func addInputWithNoConnections(AVCaptureInput)

Adds a capture input to the session without forming any connections.

func addOutputWithNoConnections(AVCaptureOutput)

Adds a capture output to the session without forming any connections.

func removeConnection(AVCaptureConnection)

Removes a capture connection from the session.

Sharing the Application’s Audio Session

var usesApplicationAudioSession: Bool

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

var automaticallyConfiguresApplicationAudioSession: Bool

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

Synchronizing Multiple Inputs and Outputs

var masterClock: CMClock?

A clock object used for output synchronization.

Managing Color Spaces

var automaticallyConfiguresCaptureDeviceForWideColor: Bool

A Boolean value that specifies whether the session should automatically use wide-gamut color where available.

Relationships

Inherits From

Conforms To

See Also

First Steps

Requesting Authorization for Media Capture on iOS

Respect user privacy by seeking permission to capture and store photos, audio, and video.

Requesting Authorization for Media Capture on macOS

Prompt the user to authorize access to the camera and microphone on macOS 10.14 and later.

Setting Up a Capture Session

Configure input devices, output media, preview views, and basic settings before capturing photos or video.

AVCam: Building a Camera App

Capture photos with depth data and record video using the front and rear iPhone and iPad cameras.