Class

AVCaptureDevice

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

Declaration

@interface AVCaptureDevice : NSObject

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:

func configureCameraForHighestFrameRate(device: AVCaptureDevice) {
    
    var bestFormat: AVCaptureDevice.Format?
    var bestFrameRateRange: AVFrameRateRange?

    for format in device.formats {
        for range in format.videoSupportedFrameRateRanges {
            if range.maxFrameRate > bestFrameRateRange?.maxFrameRate ?? 0 {
                bestFormat = format
                bestFrameRateRange = range
            }
        }
    }
    
    if let bestFormat = bestFormat, 
       let bestFrameRateRange = bestFrameRateRange {
        do {
            try device.lockForConfiguration()
            
            // Set the device's active format.
            device.activeFormat = bestFormat
            
            // Set the device's min/max frame duration.
            let duration = bestFrameRateRange.minFrameDuration
            device.activeVideoMinFrameDuration = duration
            device.activeVideoMaxFrameDuration = duration
            
            device.unlockForConfiguration()
        } catch {
            // Handle error.
        }
    }
}

Topics

Discovering Devices

+ deviceWithUniqueID:

Returns the device with a given ID.

+ defaultDeviceWithMediaType:

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

+ defaultDeviceWithDeviceType:mediaType:position:

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

AVCaptureDevicePosition

Constants to specify the position of a capture device.

AVCaptureDeviceType

Values identifying the capture device’s type.

AVCaptureDeviceDiscoverySession

A query for finding and monitoring available capture devices.

AVCaptureDeviceWasConnectedNotification

Posted when a new device becomes available.

AVCaptureDeviceWasDisconnectedNotification

Posted when an existing device becomes unavailable.

+ devices

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

Deprecated
+ devicesWithMediaType:

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

Deprecated

Verifying Authorization

+ requestAccessForMediaType:completionHandler:

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

+ authorizationStatusForMediaType:

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

AVAuthorizationStatus

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

Configuring the Device

- lockForConfiguration:

Requests exclusive access to the device’s hardware properties.

- unlockForConfiguration

Relinquishes exclusive control over the device’s configuration.

inUseByAnotherApplication

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

suspended

Indicates whether the device is suspended.

linkedDevices

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

transportType

The transport type of the receiver.

AVCaptureDeviceInputSource

A distinct input source on a capture device.

inputSources

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

activeInputSource

The currently active input source.

Inspecting Device Characteristics

uniqueID

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

modelID

The model ID of the device.

manufacturer

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

localizedName

A localized, human-readable name for the receiver.

connected

Indicates whether the device is currently connected.

virtualDevice

A Boolean value that indicates whether the device is a virtual device consisting of two or more physical devices.

Beta
deviceType

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

constituentDevices

An array of physical devices comprising a virtual device.

Beta
lensAperture

The size of the lens diaphragm.

position

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

- hasMediaType:

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

- supportsAVCaptureSessionPreset:

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

Managing Formats

formats

The capture formats supported by the device.

activeFormat

The currently active media data format of the capture device.

activeDepthDataFormat

The currently active depth data format of the capture device.

AVCaptureDeviceFormat

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

Managing Image Exposure

exposureDuration

The length of time over which exposure takes place.

- setExposureModeCustomWithDuration:ISO:completionHandler:

Locks the exposure duration and ISO at the specified values.

exposureTargetOffset

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

exposureTargetBias

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

minExposureTargetBias

The minimum supported exposure bias, in EV units.

maxExposureTargetBias

The maximum supported exposure bias, in EV units.

activeMaxExposureDuration

The maximum exposure duration, in seconds, defined in the auto-exposure algorithm.

- setExposureTargetBias:completionHandler:

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

AVCaptureExposureTargetBiasCurrent

A special constant representing the current exposure bias value.

AVCaptureExposureDurationCurrent

A special constant representing the current exposure duration setting.

Managing Exposure Settings

adjustingExposure

Indicates whether the device is currently adjusting its exposure setting.

exposureMode

The exposure mode for the device.

- isExposureModeSupported:

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

exposurePointOfInterest

The point of interest for exposure.

exposurePointOfInterestSupported

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

AVCaptureExposureMode

Constants to specify the exposure mode of a capture device.

Managing Zoom Settings

videoZoomFactor

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

minAvailableVideoZoomFactor

The minimum zoom factor allowed in the current capture configuration.

maxAvailableVideoZoomFactor

The maximum zoom factor allowed in the current capture configuration.

- rampToVideoZoomFactor:withRate:

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

rampingVideoZoom

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

- cancelVideoZoomRamp

Smoothly ends a zoom transition in progress.

virtualDeviceSwitchOverVideoZoomFactors

An array of video zoom factors at or above which a virtual device, such as the dual camera, may switch to its next constituent device.

Beta
dualCameraSwitchOverVideoZoomFactor

The video zoom factor at which a dual camera device can automatically switch between cameras.

Deprecated

Managing Focus Settings

focusMode

The capture device’s focus mode.

- isFocusModeSupported:

Returns a Boolean value that indicates whether the device supports the given focus mode.

focusPointOfInterest

The point of interest for focusing.

focusPointOfInterestSupported

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

adjustingFocus

Indicates whether the device is currently adjusting its focus setting.

smoothAutoFocusEnabled

A Boolean value that determines whether the device has smooth autofocus enabled.

smoothAutoFocusSupported

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

autoFocusRangeRestriction

A value controlling the allowable range for automatic focusing.

autoFocusRangeRestrictionSupported

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

AVCaptureFocusMode

Constants to specify the focus mode of a capture device.

AVCaptureAutoFocusRangeRestriction

Constants to specify the autofocus range of a capture device.

Managing Flash Settings

hasFlash

Indicates whether the capture device has a flash.

flashAvailable

Indicates whether the flash is currently available for use.

AVCaptureFlashMode

Constants to specify the flash mode of a capture device.

flashMode

The device’s current flash mode.

- isFlashModeSupported:

Returns a Boolean value that indicates whether the device supports the given flash mode.

flashActive

Indicates whether the flash is currently active.

Deprecated

Managing Torch Settings

hasTorch

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

torchAvailable

Indicates whether the torch is currently available for use.

torchActive

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

torchLevel

The current torch brightness level.

AVCaptureTorchMode

Constants to specify the capture device’s torch mode.

torchMode

The current torch mode.

- isTorchModeSupported:

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

- setTorchModeOnWithLevel:error:

Sets the illumination level when in torch mode.

Managing Low Light Settings

lowLightBoostSupported

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

lowLightBoostEnabled

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

automaticallyEnablesLowLightBoostWhenAvailable

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

Managing Frame Rate Settings

activeVideoMinFrameDuration

The currently active minimum frame duration.

activeVideoMaxFrameDuration

The currently active maximum frame duration

Managing Transport Controls

transportControlsSupported

Indicates whether the device supports transport control commands.

transportControlsPlaybackMode

The current playback mode.

transportControlsSpeed

The current playback speed.

- setTransportControlsPlaybackMode:speed:

Sets the transport control’s playback mode and speed.

AVCaptureDeviceTransportControlsPlaybackMode

Constants that indicate the transport control's current mode of playback, if it has one.

Monitoring Subject Area Change

subjectAreaChangeMonitoringEnabled

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

AVCaptureDeviceSubjectAreaDidChangeNotification

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

Managing the Lens Position

lensPosition

Indicates the focus position of the lens.

- setFocusModeLockedWithLensPosition:completionHandler:

Locks the lens position at the specified value.

lockingFocusWithCustomLensPositionSupported

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

AVCaptureLensPositionCurrent

A special constant representing the current lens position.

Managing the White Balance

- isWhiteBalanceModeSupported:

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

whiteBalanceMode

The current white balance mode.

adjustingWhiteBalance

Indicates whether the devise is currently adjusting the white balance.

- chromaticityValuesForDeviceWhiteBalanceGains:

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

deviceWhiteBalanceGains

The current device-specific RGB white balance gain values.

maxWhiteBalanceGain

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

- deviceWhiteBalanceGainsForChromaticityValues:

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

- deviceWhiteBalanceGainsForTemperatureAndTintValues:

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

grayWorldDeviceWhiteBalanceGains

The current device-specific white balance values required for a neutral gray white point.

- setWhiteBalanceModeLockedWithDeviceWhiteBalanceGains:completionHandler:

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

- temperatureAndTintValuesForDeviceWhiteBalanceGains:

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

lockingWhiteBalanceWithCustomDeviceGainsSupported

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

AVCaptureWhiteBalanceGainsCurrent

A special constant representing the current white balance setting.

AVCaptureWhiteBalanceGains

Structure containing RGB white balance gain values.

AVCaptureWhiteBalanceChromaticityValues

Structure containing CIE 1931 xy chromaticity values.

AVCaptureWhiteBalanceTemperatureAndTintValues

Structure containing temperature and tint values correlated to a white-balance color.

AVCaptureWhiteBalanceMode

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

Managing the ISO

ISO

The current exposure ISO value.

AVCaptureISOCurrent

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

automaticallyAdjustsVideoHDREnabled

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

videoHDREnabled

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

Managing Color Spaces

activeColorSpace

The currently active color space for capture.

AVCaptureColorSpace

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

Managing Geometric Distortion

geometricDistortionCorrectionSupported

A Boolean value that indicates whether this device supports geometric distortion correction.

Beta
geometricDistortionCorrectionEnabled

A Boolean value that indicates whether geometric distortion correction is enabled for this device.

Beta

Managing Device Calibration

+ extrinsicMatrixFromDevice:toDevice:

The relative extrinsic matrix from one capture device to another.

Beta

Managing System Pressure Changes

systemPressureState

The current of OS and hardware status affecting capture system performance and availability.

AVCaptureSystemPressureState

Information about OS and hardware status affecting capture system performance and availability.

AVCaptureSessionInterruptionSystemPressureStateKey

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

Managing Tone Mapping

globalToneMappingEnabled

A Boolean value that indicates whether the device should use global tone mapping.

Beta

Relationships

Inherits From

See Also

Capture Devices

Choosing a Capture Device

Select the front or back camera, or use advanced features like the TrueDepth camera or dual camera.

AVCaptureDeviceInput

A capture input that provides media from a capture device to a capture session.

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