AVCaptureSession Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AVFoundation.framework |
| Availability | Available in OS X v10.7 and later. |
| Declared in | AVCaptureSession.h |
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 stopRunning to stop the flow. You use the sessionPreset property to customize the quality level or bitrate of the output.
Tasks
Managing Inputs and Outputs
-
inputsproperty -
– canAddInput: -
– addInput: -
– removeInput: -
outputsproperty -
– canAddOutput: -
– addOutput: -
– removeOutput:
Managing Running State
-
– startRunning -
– stopRunning -
runningproperty
Configuration Change
Managing Session Presets
-
sessionPresetproperty -
– canSetSessionPreset:
Managing Connections
Properties
inputs
The capture session’s inputs. (read-only)
Discussion
The array contains instances of subclasses of AVCaptureInput.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.houtputs
The capture session’s outputs. (read-only)
Discussion
The array contains instances of subclasses of AVCaptureOutput.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hrunning
Indicates whether the receiver is running. (read-only)
Discussion
You can observe the value of this property using key-value observing
Availability
- Available in OS X v10.7 and later.
Declared In
AVCaptureSession.hsessionPreset
A constant value indicating the quality level or bitrate of the output.
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 OS X v10.7 and later.
Declared In
AVCaptureSession.hInstance Methods
addConnection:
Adds a given capture connection to the session.
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 YES.
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.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.haddInput:
Adds a given input to the session.
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 OS X v10.7 and later.
Declared In
AVCaptureSession.haddInputWithNoConnections:
Adds an capture input to the session without forming any connections.
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.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.haddOutput:
Adds a given output to the session.
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 OS X v10.7 and later.
Declared In
AVCaptureSession.haddOutputWithNoConnections:
Adds an capture output to the session without forming any connections.
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.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hbeginConfiguration
Indicates the start of a set of configuration changes to be made atomically.
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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hcanAddConnection:
Returns a Boolean value that indicates whether a given connection can be added to the receiver.
Parameters
- connection
An
AVCaptureConnectioninstance.
Return Value
YES if connection can be added to the receiver, otherwise NO.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hcanAddInput:
Returns a Boolean value that indicates whether a given input can be added to the session.
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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hcanAddOutput:
Returns a Boolean value that indicates whether a given output can be added to the session.
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 OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hcanSetSessionPreset:
Returns a Boolean value that indicates whether the receiver can use the given 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 OS X v10.7 and later.
Declared In
AVCaptureSession.hcommitConfiguration
Commits a set of configuration changes.
Discussion
For discussion, see beginConfiguration.
Availability
- Available in OS X v10.7 and later.
Declared In
AVCaptureSession.hremoveConnection:
Removes a capture connection from the session.
Parameters
- connection
The capture connection to remove from the session.
Discussion
You can invoke this method while the session is running.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hremoveInput:
Removes a given input.
Parameters
- input
An input to remove from the receiver.
Discussion
You can invoke this method while the session is running.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hremoveOutput:
Removes a given output.
Parameters
- output
An output to remove from the receiver.
Discussion
You can invoke this method while the session is running.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hstartRunning
Tells the receiver to start running.
Discussion
startRunning and stopRunning are asynchronous operations. If an error occurs occur during a capture session, you receive an AVCaptureSessionRuntimeErrorNotification.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hstopRunning
Tells the receiver to stop running.
Discussion
startRunning and stopRunning are asynchronous operations. If an error occurs occur during a capture session, you receive an AVCaptureSessionRuntimeErrorNotification.
Availability
- Available in OS X v10.7 and later.
See Also
Declared In
AVCaptureSession.hConstants
AVCaptureVideoOrientation
Constants to specify the device orientation during video capture.
enum {
AVCaptureVideoOrientationPortrait = 1,
AVCaptureVideoOrientationPortraitUpsideDown,
AVCaptureVideoOrientationLandscapeLeft,
AVCaptureVideoOrientationLandscapeRight,
};
typedef NSInteger AVCaptureVideoOrientation;
Constants
AVCaptureVideoOrientationPortraitIndicates that the video input is oriented vertically, with the device’s home button on the bottom.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureVideoOrientationPortraitUpsideDownIndicates that the video input is oriented vertically, with the device’s home button on the top.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureVideoOrientationLandscapeLeftIndicates that the video input is oriented vertically, with the device’s home button on the right.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureVideoOrientationLandscapeRightIndicates that the video input is oriented vertically, with the device’s home button on the left.
Available in OS X v10.7 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
AVCaptureSessionErrorKeyKey to retrieve the error object from the user info dictionary of an
AVCaptureSessionRuntimeErrorNotification.Available in OS X v10.7 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 AVCaptureSessionPreset320x240; NSString *const AVCaptureSessionPreset352x288; NSString *const AVCaptureSessionPreset640x480; NSString *const AVCaptureSessionPreset960x540; NSString *const AVCaptureSessionPreset1280x720;
Constants
AVCaptureSessionPresetPhotoSpecifies capture settings suitable for high resolution photo quality output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPresetHighSpecifies capture settings suitable for high quality video and audio output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPresetMediumSpecifies capture settings suitable for output video and audio bitrates suitable for sharing over WiFi.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPresetLowSpecifies capture settings suitable for output video and audio bitrates suitable for sharing over 3G.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPreset320x240Specifies capture settings suitable for 320x240 pixel video output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPreset352x288Specifies capture settings suitable for CIF quality (352x288 pixel) video output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPreset640x480Specifies capture settings suitable for VGA quality (640x480 pixel) video output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPreset960x540Specifies capture settings suitable for quarter HD quality (960x540 pixel) video output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.AVCaptureSessionPreset1280x720Specifies capture settings suitable for 720p quality (1280x720pixel) video output.
Available in OS X v10.7 and later.
Declared in
AVCaptureSession.h.
Notifications
AVCaptureSessionRuntimeErrorNotification
You retrieve the underlying error from the notification’s user info dictionary using the key AVCaptureSessionErrorKey.
Availability
- Available in OS X v10.7 and later.
Declared In
AVCaptureSession.hAVCaptureSessionDidStartRunningNotification
Availability
- Available in OS X v10.7 and later.
Declared In
AVCaptureSession.hAVCaptureSessionDidStopRunningNotification
Availability
- Available in OS X v10.7 and later.
Declared In
AVCaptureSession.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-05-10)