Mac Developer Library

Developer

AVFoundation Framework Reference AVCaptureDevice Class Reference

Options
Deployment Target:

On This Page
Language:

AVCaptureDevice

An AVCaptureDevice object represents a physical capture device and the properties associated with that device. You use a capture device to configure the properties of the underlying hardware. A capture device also provides input data (such as audio or video) to an AVCaptureSession object. More...

Inheritance


Conforms To


Import Statement


import AVFoundation @import AVFoundation;

Availability


Available in OS X v10.7 and later.
  • Returns an array of the available capture devices on the system.

    Declaration

    Swift

    class func devices() -> [AnyObject]!

    Objective-C

    + (NSArray *)devices

    Return Value

    An array containing the available capture devices on the system

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Returns the device with a given ID.

    Declaration

    Swift

    init!(uniqueID deviceUniqueID: String!) -> AVCaptureDevice

    Objective-C

    + (AVCaptureDevice *)deviceWithUniqueID:(NSString *)deviceUniqueID

    Parameters

    deviceUniqueID

    The ID of a capture device.

    Return Value

    The device with ID deviceUniqueID.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Returns the default device used to capture data of a given media type.

    Declaration

    Swift

    class func defaultDeviceWithMediaType(_ mediaType: String!) -> AVCaptureDevice!

    Objective-C

    + (AVCaptureDevice *)defaultDeviceWithMediaType:(NSString *)mediaType

    Parameters

    mediaType

    A media type identifier.

    For possible values, see AV Foundation Constants Reference.

    Return Value

    The default device used to capture data of the type indicated by mediaType.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Returns an array of the devices able to capture data of a given media type.

    Declaration

    Swift

    class func devicesWithMediaType(_ mediaType: String!) -> [AnyObject]!

    Objective-C

    + (NSArray *)devicesWithMediaType:(NSString *)mediaType

    Parameters

    mediaType

    A media type identifier.

    For possible values, see AV Foundation Constants Reference.

    Return Value

    An array containing the devices able to capture data of the type indicated by mediaType.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Requests exclusive access to the device’s hardware properties.

    Declaration

    Swift

    func lockForConfiguration(_ outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)lockForConfiguration:(NSError **)outError

    Parameters

    outError

    On input, specify a pointer to an error object. If a lock cannot be acquired, this pointer contains an NSError object that describes the problem. You may specify nil for this property.

    Return Value

    YEStrue if a lock was acquired or NOfalse if it was not.

    Discussion

    You must call this method before attempting to configure the hardware related properties of the device. This method returns YEStrue when it successfully locks the device for configuration by your code. After configuring the device properties, call unlockForConfiguration to release the configuration lock and allow other apps to make changes.

    You may hold onto a lock (instead of releasing it) if you require the device properties to remain unchanged. However, holding the device lock unnecessarily may degrade capture quality in other apps sharing the device.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Relinquishes exclusive control over the device’s configuration.

    Declaration

    Swift

    func unlockForConfiguration()

    Objective-C

    - (void)unlockForConfiguration

    Discussion

    Call this method to release the lock acquired using the lockForConfiguration: method when you are done configuring the device.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • suspended suspended Property

    Indicates whether the device is suspended. (read-only)

    Declaration

    Swift

    var suspended: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isSuspended) BOOL suspended

    Discussion

    Some devices disallow data capture due to a feature on the device.

    For example, isSuspended returns YEStrue for an external iSight camera when its privacy iris is closed, or for the internal iSight camera on a notebook when the notebook’s display is closed.

    You can observe changes to the value of this property using Key-value observing.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Indicates whether the device is in use by another application. (read-only)

    Declaration

    Swift

    var inUseByAnotherApplication: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isInUseByAnotherApplication) BOOL inUseByAnotherApplication

    Discussion

    You can observe changes to the value of this property using Key-value observing.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • An array of AVCaptureDeviceInputSource objects representing the input sources supported by the device. (read-only)

    Declaration

    Swift

    var inputSources: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *inputSources

    Discussion

    Some devices can capture data from one of multiple data sources (different input jacks on the same audio device, for example). For devices with multiple possible data sources, you can use this property to enumerate the possible choices.

    You can observe changes to the value of this property using Key-value observing.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The currently active input source.

    Declaration

    Swift

    var activeInputSource: AVCaptureDeviceInputSource!

    Objective-C

    @property(nonatomic, retain) AVCaptureDeviceInputSource *activeInputSource

    Discussion

    You use this property to get or set the currently active input source.

    To set the format, you must first obtain exclusive access to the receiver using lockForConfiguration:. If you do not obtain exclusive access, setActiveInputSource: throws an NSGenericException.

    The set method, setActiveInputSource:, throws an NSInvalidArgumentException if you pass a format not present in the formats array.

    You can observe changes to the value of this property using Key-value observing.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • An array of AVCaptureDevice objects representing the devices physically linked to the receiver. (read-only)

    Declaration

    Swift

    var linkedDevices: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *linkedDevices

    Discussion

    The value of this property is an array of AVCaptureDevice objects that are a part of the same physical device as the receiver. For example, for an external iSight camera, the array contains an AVCaptureDevice instance representing the external iSight microphone.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The transport type of the receiver. (read-only)

    Declaration

    Swift

    var transportType: Int32 { get }

    Objective-C

    @property(nonatomic, readonly) int32_t transportType

    Discussion

    The value of this property represents the transport type of the device (USB, PCI, etc). Transport types are defined in <IOKit/audio/IOAudioTypes.h> as kIOAudioDeviceTransportType*.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • formats formats Property

    An array of AVCaptureDeviceFormat objects representing the formats supported by the device (read-only)

    Declaration

    Swift

    var formats: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *formats

    Discussion

    You can use this property to enumerate the formats natively supported by the receiver.

    You can set activeFormat to any of the formats in this array.

    You can observe changes to the value of this property using Key-value observing.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    activeFormat

  • The currently active format of the receiver.

    Declaration

    Swift

    var activeFormat: AVCaptureDeviceFormat!

    Objective-C

    @property(nonatomic, retain) AVCaptureDeviceFormat *activeFormat

    Discussion

    You use this property to get or set the currently active device format.

    On iOS, you should generally set the session preset on an AVCaptureSession object to configure image or video capture and use the shared AVAudioSession object to configure audio capture. When using a session preset, the session automatically controls the capture device’s active format. However, some specialized capture options (such as high frame rate) are not available in session presets. For these options, you can set the capture device’s active format instead. Doing so changes the associated capture session’s preset to AVCaptureSessionPresetInputPriority.

    Attempting to set the active format to one not present in the formats array throws an NSInvalidArgumentException.

    Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. Otherwise, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings. You must also call lockForConfiguration: before calling the AVCaptureSession method startRunning, or the session's preset will override the selected active format on the capture device.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • hasTorch hasTorch Property

    A Boolean value that specifies whether the capture device has a torch. (read-only)

    Declaration

    Swift

    var hasTorch: Bool { get }

    Objective-C

    @property(nonatomic, readonly) BOOL hasTorch

    Discussion

    A torch is a light source, such as an LED flash, that is available on the device and used for illuminating captured content or providing general illumination. This property reflects whether the current device has such illumination hardware built-in.

    Even if the device has a torch, that torch might not be available for use. Thus, you should also check the value of the torchAvailable property before using it.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    torchMode

  • Returns a Boolean value that indicates whether the device supports the specified torch mode.

    Declaration

    Swift

    func isTorchModeSupported(_ torchMode: AVCaptureTorchMode) -> Bool

    Objective-C

    - (BOOL)isTorchModeSupported:(AVCaptureTorchMode)torchMode

    Parameters

    torchMode

    The desired torch mode. For a list of possible values, see AVCaptureTorchMode.

    Return Value

    YEStrue if torchMode is supported, otherwise NOfalse.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    torchMode

  • torchMode torchMode Property

    The current torch mode.

    Declaration

    Swift

    var torchMode: AVCaptureTorchMode

    Objective-C

    @property(nonatomic) AVCaptureTorchMode torchMode

    Discussion

    Setting the value of this property also sets the torch level to its maximum current value.

    Before setting the value of this property, call the isTorchModeSupported: method to make sure the device supports the desired mode. Setting the device to an unsupported torch mode results in the raising of an exception. For a list of possible values for this property, see AVCaptureTorchMode.

    Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. Otherwise, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The currently active minimum frame duration.

    Declaration

    Swift

    var activeVideoMinFrameDuration: CMTime

    Objective-C

    @property(nonatomic) CMTime activeVideoMinFrameDuration

    Discussion

    A device’s minimum frame duration is the reciprocal of its maximum frame rate. You can set the value of this property to limit the maximum frame rate during a capture session. The capture device automatically chooses a default minimum frame duration based on its active format. After changing the value of this property, you can return to the default minimum frame duration by setting this property’s value to kCMTimeInvalid. Choosing a new preset for the capture session also resets this property to its default value.

    Attempting to set this property to a value not found in the active format’s videoSupportedFrameRateRanges array raises an exception (NSInvalidArgumentException).

    Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. Otherwise, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    activeFormat

  • The currently active maximum frame duration

    Declaration

    Swift

    var activeVideoMaxFrameDuration: CMTime

    Objective-C

    @property(nonatomic) CMTime activeVideoMaxFrameDuration

    Discussion

    A device’s maximum frame duration is the reciprocal of its minimum frame rate. You can set the value of this property to limit the minimum frame rate during a capture session. The capture device automatically chooses a default maximum frame duration based on its active format. After changing the value of this property, you can return to the default maximum frame duration by setting this property’s value to kCMTimeInvalid. Choosing a new preset for the capture session also resets this property to its default value.

    Attempting to set this property to a value not found in the active format’s videoSupportedFrameRateRanges array raises an exception (NSInvalidArgumentException).

    Before changing the value of this property, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. Otherwise, setting the value of this property raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.9 and later.

    See Also

    activeFormat

  • connected connected Property

    Indicates whether the device is currently connected. (read-only)

    Declaration

    Swift

    var connected: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isConnected) BOOL connected

    Discussion

    The value of this property indicates whether the device represented by the receiver is connected and available for use as a capture device. When the value of this property becomes NOfalse for a given instance, however, it will not become YEStrue again. If the same physical device again becomes available to the system, it will be represented using a new instance of AVCaptureDevice.

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

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • position position Property

    Indicates the physical position of the device hardware on the system. (read-only)

    Declaration

    Swift

    var position: AVCaptureDevicePosition { get }

    Objective-C

    @property(nonatomic, readonly) AVCaptureDevicePosition position

    Discussion

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

    See AVCaptureDevicePosition for possible values.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Returns a Boolean value that indicates whether the device provides media with a given type.

    Declaration

    Swift

    func hasMediaType(_ mediaType: String!) -> Bool

    Objective-C

    - (BOOL)hasMediaType:(NSString *)mediaType

    Parameters

    mediaType

    A media type, such as AVMediaTypeVideo, AVMediaTypeAudio, or AVMediaTypeMuxed. For a complete list of supported media type constants, see AV Foundation Constants Reference.

    Return Value

    YES if the device provides media of type mediaType, otherwise NOfalse.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • modelID modelID Property

    The model ID of the device. (read-only)

    Declaration

    Swift

    var modelID: String! { get }

    Objective-C

    @property(nonatomic, readonly) NSString *modelID

    Discussion

    The value of this property is an identifier unique to all devices of the same model. The value is persistent across device connections and disconnections, and across different systems. For example, the model ID of the camera built in to two identical iPhone models will be the same even though they are different physical devices.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • A localized human-readable name for the receiver. (read-only)

    Declaration

    Swift

    var localizedName: String! { get }

    Objective-C

    @property(nonatomic, readonly) NSString *localizedName

    Discussion

    You can use this property to display the name of a capture device in a user interface.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • uniqueID uniqueID Property

    An ID unique to the model of device corresponding to the receiver. (read-only)

    Declaration

    Swift

    var uniqueID: String! { get }

    Objective-C

    @property(nonatomic, readonly) NSString *uniqueID

    Discussion

    Every available capture device has a unique ID that persists on one system across device connections and disconnections, application restarts, and reboots of the system itself. You can store the value returned by this property to recall or track the status of a specific device in the future.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

    See Also

    hasTorch

  • Returns a Boolean value that indicates whether the receiver can be used in an capture session configured with the given preset.

    Declaration

    Swift

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

    Objective-C

    - (BOOL)supportsAVCaptureSessionPreset:(NSString *)preset

    Parameters

    preset

    A capture session preset.

    Return Value

    YEStrue if the receiver can be used with preset, otherwise NOfalse.

    Discussion

    An AVCaptureSession instance can be associated with a preset that configures its inputs and outputs to fulfill common use cases. You can use this method to determine if the receiver can be used in a capture session with the given preset. For a list of preset constants, see AVCaptureSession Class Reference.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

Data Types

  • Constants to specify the position of a capture device.

    Declaration

    Swift

    enum AVCaptureDevicePosition : Int { case Unspecified case Back case Front }

    Objective-C

    enum { AVCaptureDevicePositionUnspecified = 0, AVCaptureDevicePositionBack = 1, AVCaptureDevicePositionFront = 2 }; typedef NSInteger AVCaptureDevicePosition;

    Constants

    • Unspecified

      AVCaptureDevicePositionUnspecified

      The capture device’s position relative to the system hardware is unspecified.

      Available in OS X v10.7 and later.

    • Back

      AVCaptureDevicePositionBack

      The capture device is on the back of the unit.

      Available in OS X v10.7 and later.

    • Front

      AVCaptureDevicePositionFront

      The capture device is on the front of the unit.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Constants to specify the flash mode of a capture device.

    Declaration

    Swift

    enum AVCaptureFlashMode : Int { case Off case On case Auto }

    Objective-C

    typedef enum : NSInteger { AVCaptureFlashModeOff = 0, AVCaptureFlashModeOn = 1, AVCaptureFlashModeAuto = 2 } AVCaptureFlashMode;

    Constants

    • Off

      AVCaptureFlashModeOff

      The capture device flash is always off.

      Available in OS X v10.7 and later.

    • On

      AVCaptureFlashModeOn

      The capture device flash is always on.

      Available in OS X v10.7 and later.

    • Auto

      AVCaptureFlashModeAuto

      The capture device continuously monitors light levels and uses the flash when necessary.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Constants to specify the capture device’s torch mode.

    Declaration

    Swift

    enum AVCaptureTorchMode : Int { case Off case On case Auto }

    Objective-C

    typedef enum : NSInteger { AVCaptureTorchModeOff = 0, AVCaptureTorchModeOn = 1, AVCaptureTorchModeAuto = 2 } AVCaptureTorchMode;

    Constants

    • Off

      AVCaptureTorchModeOff

      The capture device torch is always off.

      Available in OS X v10.7 and later.

    • On

      AVCaptureTorchModeOn

      The capture device torch is always on.

      Available in OS X v10.7 and later.

    • Auto

      AVCaptureTorchModeAuto

      The capture device continuously monitors light levels and uses the torch when necessary.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • The maximum torch level.

    Declaration

    Swift

    let AVCaptureMaxAvailableTorchLevel: Float

    Objective-C

    const float AVCaptureMaxAvailableTorchLevel;

    Constants

    • AVCaptureMaxAvailableTorchLevel

      AVCaptureMaxAvailableTorchLevel

      This constant always represents the maximum available torch level, independent of the actual maximum value currently supported by the device. Thus, pass this constant to the setTorchModeOnWithLevel:error: in situations where you want to specify the maximum torch level without having to worry about whether the device is overheating and might not accept a value of 1.0 as the maximum.

      Available in OS X v10.9 and later.

    Import Statement

  • Constants to specify the focus mode of a capture device.

    Declaration

    Swift

    enum AVCaptureFocusMode : Int { case Locked case AutoFocus case ContinuousAutoFocus }

    Objective-C

    typedef enum : NSInteger { AVCaptureFocusModeLocked = 0, AVCaptureFocusModeAutoFocus = 1, AVCaptureFocusModeContinuousAutoFocus = 2, } AVCaptureFocusMode;

    Constants

    • Locked

      AVCaptureFocusModeLocked

      The focus is locked.

      Available in OS X v10.7 and later.

    • AutoFocus

      AVCaptureFocusModeAutoFocus

      The capture device performs an autofocus operation now.

      Available in OS X v10.7 and later.

    • ContinuousAutoFocus

      AVCaptureFocusModeContinuousAutoFocus

      The capture device continuously monitors focus and auto focuses when necessary.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Constants to specify the exposure mode of a capture device.

    Declaration

    Swift

    enum AVCaptureExposureMode : Int { case Locked case AutoExpose case ContinuousAutoExposure }

    Objective-C

    typedef enum : NSInteger { AVCaptureExposureModeLocked = 0, AVCaptureExposureModeAutoExpose = 1, AVCaptureExposureModeContinuousAutoExposure = 2, } AVCaptureExposureMode;

    Constants

    • Locked

      AVCaptureExposureModeLocked

      The exposure setting is locked.

      Available in OS X v10.7 and later.

    • AutoExpose

      AVCaptureExposureModeAutoExpose

      The device automatically adjusts the exposure once and then changes the exposure mode to AVCaptureExposureModeLocked.

      Available in OS X v10.7 and later.

    • ContinuousAutoExposure

      AVCaptureExposureModeContinuousAutoExposure

      The device continuously monitors exposure levels and auto exposes when necessary.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Constants to specify the white balance mode of a capture device.

    Declaration

    Swift

    enum AVCaptureWhiteBalanceMode : Int { case Locked case AutoWhiteBalance case ContinuousAutoWhiteBalance }

    Objective-C

    typedef enum : NSInteger { AVCaptureWhiteBalanceModeLocked = 0, AVCaptureWhiteBalanceModeAutoWhiteBalance = 1, AVCaptureWhiteBalanceModeContinuousAutoWhiteBalance = 2, } AVCaptureWhiteBalanceMode;

    Constants

    • Locked

      AVCaptureWhiteBalanceModeLocked

      The white balance setting is locked.

      Available in OS X v10.7 and later.

    • AutoWhiteBalance

      AVCaptureWhiteBalanceModeAutoWhiteBalance

      The device performs an auto white balance operation now.

      Available in OS X v10.7 and later.

    • ContinuousAutoWhiteBalance

      AVCaptureWhiteBalanceModeContinuousAutoWhiteBalance

      The device continuously monitors white balance and adjusts when necessary.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.

  • Constants that indicate the transport controls’ current mode of playback, if it has one.

    Declaration

    Swift

    enum AVCaptureDeviceTransportControlsPlaybackMode : Int { case NotPlayingMode case PlayingMode }

    Objective-C

    typedef enum : NSInteger { AVCaptureDeviceTransportControlsNotPlayingMode = 0, AVCaptureDeviceTransportControlsPlayingMode = 1 } AVCaptureDeviceTransportControlsPlaybackMode;

    Constants

    • NotPlayingMode

      AVCaptureDeviceTransportControlsNotPlayingMode

      Indicates that the tape transport is not threaded through the play head.

      Available in OS X v10.7 and later.

    • PlayingMode

      AVCaptureDeviceTransportControlsPlayingMode

      Indicates that the tape transport is threaded through the play head.

      Available in OS X v10.7 and later.

    Import Statement

    import AVFoundation

    Availability

    Available in OS X v10.7 and later.