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 real-time capture, you instantiate an AVCaptureSession object and add appropriate inputs and outputs. The following code fragment illustrates how to configure a capture device to record audio.

// Create the capture session.
let captureSession = AVCaptureSession()

// Find the default audio device.
guard let audioDevice = AVCaptureDevice.default(for: .audio) else { return }

do {
    // Wrap the audio device in a capture device input.
    let audioInput = try AVCaptureDeviceInput(device: audioDevice)
    // If the input can be added, add it to the session.
    if captureSession.canAddInput(audioInput) {
        captureSession.addInput(audioInput)
    }
} catch {
    // Configuration failed. Handle error.
}

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

struct AVCaptureSession.Preset

Constants to define capture setting presets using the sessionPreset property.

var sessionPreset: AVCaptureSession.Preset

A constant value indicating the quality level or bit rate of the output.

func canSetSessionPreset(AVCaptureSession.Preset) -> Bool

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

Managing Connections

var connections: [AVCaptureConnection]

An array of connections managed by the capture session.

Beta
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

Capture Sessions

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.

AVMultiCamPiP: Capturing from Multiple Cameras

Simultaneously record the output from the front and back cameras into a single movie file by using a multi-camera capture session.

class AVCaptureMultiCamSession

A subclass of AVCaptureSession that supports simultaneous capture from multiple inputs of the same media type.

Beta

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software