Class

AVCaptureDevice

A device that provides input (such as audio or video) for capture sessions and offers controls for hardware-specific capture features.

Overview

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.

You use the methods of the AVCaptureDevice class to enumerate the available devices, query their capabilities, and be informed about when devices come and go. Before you attempt to set properties of a capture device (its focus mode, exposure mode, and so on), you must first acquire a lock on the device using the lockForConfiguration() method. You should also query the device’s capabilities to ensure that the new modes you intend to set are valid for that device. You can then set the properties and release the lock using the unlockForConfiguration() method. You may hold the lock if you want all settable device properties to remain unchanged. However, holding the device lock unnecessarily may degrade capture quality in other applications sharing the device and is not recommended.

Most common configurations of capture settings are available through the AVCaptureSession object and its available presets. However, on iOS devices, some specialized options (such as high frame rate) require directly setting a capture format on an AVCaptureDevice instance. The following code example illustrates how to select an iOS device’s highest possible frame rate:

- (void)configureCameraForHighestFrameRate:(AVCaptureDevice *)device
{
    AVCaptureDeviceFormat *bestFormat = nil;
    AVFrameRateRange *bestFrameRateRange = nil;
    for ( AVCaptureDeviceFormat *format in [device formats] ) {
        for ( AVFrameRateRange *range in format.videoSupportedFrameRateRanges ) {
            if ( range.maxFrameRate > bestFrameRateRange.maxFrameRate ) {
                bestFormat = format;
                bestFrameRateRange = range;
            }
        }
    }
    if ( bestFormat ) {
        if ( [device lockForConfiguration:NULL] == YES ) {
            device.activeFormat = bestFormat;
            device.activeVideoMinFrameDuration = bestFrameRateRange.minFrameDuration;
            device.activeVideoMaxFrameDuration = bestFrameRateRange.minFrameDuration;
            [device unlockForConfiguration];
        }
    }
}

Topics

Discovering Devices

class AVCaptureDevice.DiscoverySession

A query for finding and monitoring available capture devices.

class func `default`(AVCaptureDevice.DeviceType, for: AVMediaType?, position: AVCaptureDevice.Position)

Returns the default device for the specified device type, media type, and position.

class func devices()

Returns an array of the available capture devices on the system.

init?(uniqueID: String)

Returns the device with a given ID.

class func `default`(for: AVMediaType)

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

class func devices(for: AVMediaType)

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

struct AVCaptureDevice.DeviceType

Values identifying the general type of a capture device, used with the default(_:for:position:) method and the AVCaptureDevice.DiscoverySession class.

enum AVCaptureDevice.Position

Constants to specify the position of a capture device.

Verifying Authorization

class func requestAccess(for: AVMediaType, completionHandler: (Bool) -> Void)

Requests the user’s permission, if needed, for recording a specified media type.

class func authorizationStatus(for: AVMediaType)

Returns a constant indicating whether the app has permission for recording a specified media type

enum AVAuthorizationStatus

Constants that provide information regarding permission to use media capture devices.

Managing the Device’s Configuration

func lockForConfiguration()

Requests exclusive access to the device’s hardware properties.

func unlockForConfiguration()

Relinquishes exclusive control over the device’s configuration.

var isInUseByAnotherApplication: Bool

Indicates whether the device is being used exclusively by another application.

var isSuspended: Bool

Indicates whether the device is suspended.

var linkedDevices: [AVCaptureDevice]

An array of AVCaptureDevice objects representing the devices physically linked to the receiver.

var transportType: Int32

The transport type of the receiver.

class AVCaptureDevice.InputSource

A distinct input source on a capture device.

var inputSources: [AVCaptureDevice.InputSource]

An array of AVCaptureDevice.InputSource objects representing the input sources supported by the device.

var activeInputSource: AVCaptureDevice.InputSource?

The currently active input source.

Managing Formats

var formats: [AVCaptureDevice.Format]

The capture formats supported by the device.

var activeFormat: AVCaptureDevice.Format

The currently active media data format of the capture device.

var activeDepthDataFormat: AVCaptureDevice.Format?

The currently active depth data format of the capture device.

Beta
class AVCaptureDevice.Format

A set of media format and capture settings (such as video resolution and frame rate) that can be used to configure a capture device.

Managing Focus Settings

func isFocusModeSupported(AVCaptureDevice.FocusMode)

Returns a Boolean value that indicates whether the given focus mode is supported.

var focusPointOfInterest: CGPoint

The point of interest for focusing.

var isFocusPointOfInterestSupported: Bool

Indicates whether the device supports a point of interest for focus.

var isAdjustingFocus: Bool

Indicates whether the device is currently adjusting its focus setting.

var isSmoothAutoFocusEnabled: Bool

A Boolean value that determines whether smooth autofocus is enabled.

var isSmoothAutoFocusSupported: Bool

A Boolean value that indicates whether the device supports smooth autofocus.

var autoFocusRangeRestriction: AVCaptureDevice.AutoFocusRangeRestriction

A value controlling the allowable range for automatic focusing.

var isAutoFocusRangeRestrictionSupported: Bool

A Boolean value that indicates whether the device supports focus range restrictions.

enum AVCaptureDevice.FocusMode

Constants to specify the focus mode of a capture device.

enum AVCaptureDevice.AutoFocusRangeRestriction

Constants to specify the autofocus range of a capture device.

Managing Exposure Settings

var isAdjustingExposure: Bool

Indicates whether the device is currently adjusting its exposure setting.

var exposureMode: AVCaptureDevice.ExposureMode

The exposure mode for the device.

func isExposureModeSupported(AVCaptureDevice.ExposureMode)

Returns a Boolean value that indicates whether the given exposure mode is supported.

var exposurePointOfInterest: CGPoint

The point of interest for exposure.

var isExposurePointOfInterestSupported: Bool

Indicates whether the device supports a point of interest for exposure.

enum AVCaptureDevice.ExposureMode

Constants to specify the exposure mode of a capture device.

Managing Zoom Settings

var videoZoomFactor: CGFloat

A value that controls the cropping and enlargement of images captured by the device.

func ramp(toVideoZoomFactor: CGFloat, withRate: Float)

Begins a smooth transition from the current zoom factor to another.

func cancelVideoZoomRamp()

Smoothly ends a zoom transition in progress.

var isRampingVideoZoom: Bool

A Boolean value that indicates whether a zoom transition is in progress.

var minAvailableVideoZoomFactor: CGFloat

The minimum zoom factor allowed in the current capture configuration.

Beta
var maxAvailableVideoZoomFactor: CGFloat

The maximum zoom factor allowed in the current capture configuration.

Beta

Managing Flash Settings

var hasFlash: Bool

Indicates whether the capture device has a flash.

func isFlashModeSupported(AVCaptureDevice.FlashMode)

Returns a Boolean value that indicates whether the given flash mode is supported.

var isFlashActive: Bool

Indicates whether the flash is currently active.

Deprecated
var isFlashAvailable: Bool

Indicates whether the flash is currently available for use.

enum AVCaptureDevice.FlashMode

Constants to specify the flash mode of a capture device.

Managing Torch Settings

var hasTorch: Bool

A Boolean value that specifies whether the capture device has a torch.

var isTorchAvailable: Bool

Indicates whether the torch is currently available for use.

var isTorchActive: Bool

A Boolean value indicating whether the device’s torch is currently active.

var torchLevel: Float

The current torch brightness level.

func isTorchModeSupported(AVCaptureDevice.TorchMode)

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

func setTorchModeOn(level: Float)

Sets the illumination level when in torch mode.

enum AVCaptureDevice.TorchMode

Constants to specify the capture device’s torch mode.

Managing Low Light Settings

var isLowLightBoostSupported: Bool

A Boolean value that indicates whether the capture device supports boosting images in low light conditions.

var isLowLightBoostEnabled: Bool

A Boolean value that indicates whether the capture device’s low light boost feature is enabled.

var automaticallyEnablesLowLightBoostWhenAvailable: Bool

A Boolean value that indicates whether the capture device should automatically switch to low light boost mode when necessary.

Managing Frame Rate Settings

var activeVideoMinFrameDuration: CMTime

The currently active minimum frame duration.

var activeVideoMaxFrameDuration: CMTime

The currently active maximum frame duration

Managing Transport Controls

var transportControlsSupported: Bool

Indicates whether the device supports transport control commands.

enum AVCaptureDevice.TransportControlsPlaybackMode

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

typealias AVCaptureDevice.TransportControlsSpeed

A constant that is used to specify the transport controls’ speed.

Monitoring Subject Area Change

var isSubjectAreaChangeMonitoringEnabled: Bool

Indicates whether the device should monitor the subject area for changes.

Inspecting Device Characteristics

var isConnected: Bool

Indicates whether the device is currently connected.

var position: AVCaptureDevice.Position

Indicates the physical position of the device hardware on the system.

func hasMediaType(AVMediaType)

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

var modelID: String

The model ID of the device.

var localizedName: String

A localized human-readable name for the receiver.

var uniqueID: String

An ID unique to the model of device corresponding to the receiver.

func supportsSessionPreset(AVCaptureSession.Preset)

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

var lensAperture: Float

The size of the lens diaphragm.

var deviceType: AVCaptureDevice.DeviceType

The general type of the device, such as a built-in microphone or wide-angle camera.

var manufacturer: String

A human-readable string describing the manufacturer of the device.

Managing the Lens Position

var lensPosition: Float

Indicates the focus position of the lens.

var isLockingFocusWithCustomLensPositionSupported: Bool

A Boolean value indicating whether the device supports locking focus to a specific lens position.

class let currentLensPosition: Float

This value may be passed as the lensPosition parameter of setFocusModeLocked(lensPosition:completionHandler:) to indicate that no value should be set for the lensPosition property, and that it should instead be set to its current value.

Managing Image Exposure

var exposureDuration: CMTime

The length of time over which exposure takes place.

var exposureTargetOffset: Float

The metered exposure level's offset from the target exposure value, in EV units.

var exposureTargetBias: Float

Bias applied to the target exposure value, in EV units.

var maxExposureTargetBias: Float

The maximum supported exposure bias, in EV units.

var minExposureTargetBias: Float

The minimum supported exposure bias, in EV units.

func setExposureTargetBias(Float, completionHandler: ((CMTime) -> Void)? = nil)

Sets the bias to be applied to the target exposure value.

class let currentExposureTargetBias: Float

This value indicates that the caller does not wish to specify a value for the exposureTargetBias property, and that it should instead be set to its current value.

class let currentExposureDuration: CMTime

This value indicates that the caller does not wish to specify a value for the exposureDuration property, and that it should instead be set to its current value.

Managing the White Balance

func isWhiteBalanceModeSupported(AVCaptureDevice.WhiteBalanceMode)

Returns a Boolean value that indicates whether the given white balance mode is supported.

var isAdjustingWhiteBalance: Bool

Indicates whether the devise is currently adjusting the white balance.

func chromaticityValues(for: AVCaptureDevice.WhiteBalanceGains)

Converts device-specific white balance RGB gain values to device-independent chromaticity values.

var deviceWhiteBalanceGains: AVCaptureDevice.WhiteBalanceGains

The current device-specific RGB white balance gain values.

var maxWhiteBalanceGain: Float

The maximum supported value to which a channel in the AVCaptureWhiteBalanceGains may be set.

func deviceWhiteBalanceGains(for: AVCaptureDevice.WhiteBalanceChromaticityValues)

Converts device-independent chromaticity values to device-specific white balance RGB gain values.

func deviceWhiteBalanceGains(for: AVCaptureDevice.WhiteBalanceTemperatureAndTintValues)

Converts device-independent temperature and tint values to device-specific white balance RGB gain values.

var grayWorldDeviceWhiteBalanceGains: AVCaptureDevice.WhiteBalanceGains

The current device-specific gray world RGB white balance gain values.

func setWhiteBalanceModeLocked(with: AVCaptureDevice.WhiteBalanceGains, completionHandler: ((CMTime) -> Void)? = nil)

Sets white balance to locked mode with the specified deviceWhiteBalanceGains values.

func temperatureAndTintValues(for: AVCaptureDevice.WhiteBalanceGains)

Converts device-specific white balance RGB gain values to device-independent temperature and tint values.

var isLockingWhiteBalanceWithCustomDeviceGainsSupported: Bool

A Boolean value indicating whether the device supports locking white balance to specific gain values.

class let currentWhiteBalanceGains: AVCaptureDevice.WhiteBalanceGains

This value may be passed as the deviceWhiteBalanceGains parameter of setWhiteBalanceModeLocked(with:completionHandler:) to indicate that the caller does not wish to specify a value for deviceWhiteBalanceGains, and that gains should instead be locked at their value at the moment that white balance is locked.

struct AVCaptureDevice.WhiteBalanceGains

Structure containing RGB white balance gain values.

struct AVCaptureDevice.WhiteBalanceChromaticityValues

Structure containing CIE 1931 xy chromaticity values.

struct AVCaptureDevice.WhiteBalanceTemperatureAndTintValues

Structure containing a white balance color correlated temperature and tint.

enum AVCaptureDevice.WhiteBalanceMode

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

Managing the ISO

var iso: Float

The current exposure ISO value.

class let currentISO: Float

This value indicates that the caller does not wish to specify a value for the iso property, and that it should instead be set to its current value.

Managing High Dynamic Range Video

var automaticallyAdjustsVideoHDREnabled: Bool

A Boolean value that indicates whether the capture device is allowed to turn high dynamic range streaming on or off.

var isVideoHDREnabled: Bool

A Boolean value that indicates whether the receiver is allowed to turn high dynamic range streaming on or off.

Managing Color Spaces

var activeColorSpace: AVCaptureColorSpace

The currently active color space for capture.

enum AVCaptureColorSpace

Constants to specify the color gamut and format for image and video capture, used with the activeColorSpace property.

Notifications

static let AVCaptureDeviceWasConnected: NSNotification.Name

Posted when a new device becomes available.

static let AVCaptureDeviceWasDisconnected: NSNotification.Name

Posted when an existing device becomes unavailable.

static let AVCaptureDeviceSubjectAreaDidChange: NSNotification.Name

Posted when the instance of AVCaptureDevice has detected a substantial change to the video subject area.

Enumerations

enum AVCaptureDevice.LensStabilizationStatus

Constants that indicate the status of lens stabilization (optical image stabilization) hardware during a bracketed photo capture.

Beta

Relationships

Inherits From

Conforms To

See Also

First Steps

class AVCaptureSession

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

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