Class

AVCaptureSession

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

Declaration

@interface 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.
AVCaptureSession *captureSession = [[AVCaptureSession alloc] init];

// Lookup the default audio device.
AVCaptureDevice *audioDevice =
    [AVCaptureDevice defaultDeviceWithMediaType:AVMediaTypeAudio];

// Wrap the audio device in a capture device input.
NSError *error = nil;
AVCaptureDeviceInput *audioInput =
    [AVCaptureDeviceInput deviceInputWithDevice:audioDevice error:&error];

if (audioInput) {
    // If the input can be added, add it to the session.
    if ([captureSession canAddInput:audioInput]) {
        [captureSession addInput:audioInput];
    }
} else {
    // 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

inputs

The capture session’s inputs.

- canAddInput:

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

- addInput:

Adds a given input to the session.

- removeInput:

Removes a given input.

outputs

The capture session’s outputs.

- canAddOutput:

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

- addOutput:

Adds a given output to the session.

- removeOutput:

Removes a given output.

Managing Running State

- startRunning

Tells the receiver to start running.

- stopRunning

Tells the receiver to stop running.

running

Indicates whether the receiver is running.

interrupted

Indicates whether the receiver has been interrupted.

AVCaptureSessionRuntimeErrorNotification

Posted if an error occurred during a capture session.

AVCaptureSessionDidStartRunningNotification

Posted when a capture session starts.

AVCaptureSessionDidStopRunningNotification

Posted when a capture session stops.

AVCaptureSessionWasInterruptedNotification

Posted if a capture session is interrupted.

AVCaptureSessionInterruptionEndedNotification

Posted if an interruption to a capture session finishes.

AVCaptureSessionErrorKey

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

AVCaptureSessionInterruptionReasonKey

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

AVCaptureSessionInterruptionSystemPressureStateKey

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

AVCaptureSessionInterruptionReason

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

Configuration Change

- beginConfiguration

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

- commitConfiguration

Commits a set of configuration changes.

Managing Session Presets

AVCaptureSessionPreset

Constants to define capture setting presets using the sessionPreset property.

sessionPreset

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

- canSetSessionPreset:

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

Managing Connections

connections

An array of connections managed by the capture session.

- addConnection:

Adds a given capture connection to the session.

- canAddConnection:

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

- addInputWithNoConnections:

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

- addOutputWithNoConnections:

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

- removeConnection:

Removes a capture connection from the session.

Sharing the Application’s Audio Session

usesApplicationAudioSession

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

automaticallyConfiguresApplicationAudioSession

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

Synchronizing Multiple Inputs and Outputs

masterClock

A clock object used for output synchronization.

Managing Color Spaces

automaticallyConfiguresCaptureDeviceForWideColor

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

Relationships

Inherits From

NSObject