AVCaptureDevice Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
AVCaptureDevice.h
Related sample code

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 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, 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 a 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];
        }
    }
}

Tasks

Discovering Devices

Verifying Authorization

Managing the Device’s Configuration

Managing Formats

Managing Focus Settings

Managing Exposure Settings

Managing White Balance Settings

Managing Zoom Settings

Managing Flash Settings

Managing Torch Settings

Managing Low Light Settings

Managing Frame Rate Settings

Monitoring Subject Area Change

Inspecting Device Characteristics

Properties

activeFormat

The currently active format of the receiver.

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

activeVideoMaxFrameDuration

The currently active maximum frame duration

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

activeVideoMinFrameDuration

The currently active minimum frame duration.

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

adjustingExposure

Indicates whether the device is currently adjusting its exposure setting. (read-only)

@property(nonatomic, readonly, getter=isAdjustingExposure) BOOL adjustingExposure
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

adjustingFocus

Indicates whether the device is currently adjusting its focus setting. (read-only)

@property(nonatomic, readonly, getter=isAdjustingFocus) BOOL adjustingFocus
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

adjustingWhiteBalance

Indicates whether the devise is currently adjusting the white balance. (read-only)

@property(nonatomic, readonly, getter=isAdjustingWhiteBalance) BOOL adjustingWhiteBalance
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

autoFocusRangeRestriction

A value controlling the allowable range for automatic focusing.

@property(nonatomic) AVCaptureAutoFocusRangeRestriction autoFocusRangeRestriction
Discussion

By default, a device capable of hardware focusing attempts to focus on objects at any distance. If you expect to focus primarily on near or far objects, set a range restriction to increase the speed and reduce the power consumption of automatic focusing, and to reduce the chance of focusing ambiguities.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

autoFocusRangeRestrictionSupported

A Boolean value that indicates whether the device supports focus range restrictions. (read-only)

@property(nonatomic, readonly, getter=isAutoFocusRangeRestrictionSupported) BOOL autoFocusRangeRestrictionSupported
Discussion

Focus range restriction is available only on compatible devices. If this property’s value is NO, setting the value of autoFocusRangeRestriction raises an exception.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

automaticallyEnablesLowLightBoostWhenAvailable

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

@property(nonatomic) BOOL automaticallyEnablesLowLightBoostWhenAvailable
Discussion

On an AVCaptureDevice object where lowLightBoostSupported is YES, a special low light boost mode may be engaged to improve image quality. When the automaticallyEnablesLowLightBoostWhenAvailable property is set to YES, the capture device switches at its discretion to a special boost mode under low light. When the scene becomes sufficiently lit, the device switches back to normal operation. An AVCaptureDevice that supports this feature may only engage boost mode for certain source formats or resolutions.

The default value of this property is NO. Setting this property throws an NSInvalidArgumentException if lowLightBoostSupported is NO. The AVCaptureDevice object must be locked for configuration using lockForConfiguration: before clients can set this method, otherwise an NSGenericException is thrown.

Clients may observe changes to the lowLightBoostEnabled property using Key-value observing to know when the boost mode engages. The switch between normal operation and low light boost mode may drop one or more video frames.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureDevice.h

connected

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

@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 NO for a given instance, however, it will not become YES 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 the value of this property using Key-value observing to be notified when a device is no longer available.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

exposureMode

The exposure mode for the device.

@property(nonatomic) AVCaptureExposureMode exposureMode
Discussion

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.

See “AVCaptureExposureMode” for possible values.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

exposurePointOfInterest

The point of interest for exposure.

@property(nonatomic) CGPoint exposurePointOfInterest
Discussion

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

exposurePointOfInterestSupported

Indicates whether the device supports a point of interest for exposure. (read-only)

@property(nonatomic, readonly, getter=isExposurePointOfInterestSupported) BOOL exposurePointOfInterestSupported
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

flashActive

Indicates whether the flash is currently active. (read-only)

@property(nonatomic, readonly, getter=isFlashActive) BOOL flashActive
Discussion

When the flash is active, it will flash if a still image is captured.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureDevice.h

flashAvailable

Indicates whether the flash is currently available for use. (read-only)

@property(nonatomic, readonly, getter=isFlashAvailable) BOOL flashAvailable
Discussion

The flash may become unavailable if, for example, the device overheats and needs to cool off.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureDevice.h

flashMode

The current flash mode.

@property(nonatomic) AVCaptureFlashMode flashMode
Discussion

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.

See “AVCaptureFlashMode” for possible values.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

focusMode

The device’s focus mode.

@property(nonatomic) AVCaptureFocusMode focusMode
Discussion

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.

See “AVCaptureFocusMode” for possible values.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

focusPointOfInterest

The point of interest for focusing.

@property(nonatomic) CGPoint focusPointOfInterest
Discussion

This property represents a CGPoint where {0,0} corresponds to the top left of the picture area, and {1,1} corresponds to the bottom right in landscape mode with the home button on the right—this applies even if the device is in portrait mode.

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

focusPointOfInterestSupported

Indicates whether the device supports a point of interest for focus. (read-only)

@property(nonatomic, readonly, getter=isFocusPointOfInterestSupported) BOOL focusPointOfInterestSupported
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

formats

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

hasFlash

Indicates whether the capture device has a flash. (read-only)

@property(nonatomic, readonly) BOOL hasFlash
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

hasTorch

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

@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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

localizedName

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

@property(nonatomic, readonly) NSString *localizedName
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

lowLightBoostEnabled

A Boolean value that indicates whether the capture device’s low light boost feature is enabled. (read-only)

@property(nonatomic, readonly, getter=isLowLightBoostEnabled) BOOL lowLightBoostEnabled
Discussion

The value of this property indicates whether the AVCaptureDevice object is currently enhancing images to improve quality due to low light conditions. When this property is YES, the capture device has switched into a special mode in which more light can be perceived in images.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureDevice.h

lowLightBoostSupported

A Boolean value that indicates whether the capture device supports boosting images in low light conditions. (read-only)

@property(nonatomic, readonly, getter=isLowLightBoostSupported) BOOL lowLightBoostSupported
Discussion

The AVCaptureDevice object’s automaticallyEnablesLowLightBoostWhenAvailable property can only be set if this property is YES.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureDevice.h

modelID

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

@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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

position

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

@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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

rampingVideoZoom

A Boolean value that indicates whether a zoom transition is in progress. (read-only)

@property(nonatomic, readonly, getter=isRampingVideoZoom) BOOL rampingVideoZoom
Discussion

You can observe changes to the value of this property using Key-value observing to be notified when a zoom transition begins or ends.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

smoothAutoFocusEnabled

A Boolean value that determines whether smooth autofocus is enabled.

@property(nonatomic, getter=isSmoothAutoFocusEnabled) BOOL smoothAutoFocusEnabled
Discussion

On capable devices, you can enable a “smooth” focusing mode in which lens movements are made more slowly. This mode make focus transitions less visually intrusive, a behavior that you may want for video capture.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

smoothAutoFocusSupported

A Boolean value that indicates whether the device supports smooth autofocus. (read-only)

@property(nonatomic, readonly, getter=isSmoothAutoFocusSupported) BOOL smoothAutoFocusSupported
Discussion

The smooth focusing mode is available only on compatible devices. If this property’s value is NO, setting the value of smoothAutoFocusEnabled to YES raises an exception.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

subjectAreaChangeMonitoringEnabled

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

@property(nonatomic, getter=isSubjectAreaChangeMonitoringEnabled) BOOL subjectAreaChangeMonitoringEnabled
Discussion

The value of this property indicates whether the receiver should monitor the video subject area for changes, such as lighting changes, substantial movement, and so on. If subject area change monitoring is enabled, the capture device object sends an AVCaptureDeviceSubjectAreaDidChangeNotification whenever it detects a change to the subject area, at which time an interested client may wish to re-focus, adjust exposure, white balance, etc.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureDevice.h

torchActive

A Boolean value indicating whether the device’s torch is currently active. (read-only)

@property(nonatomic, readonly, getter=isTorchActive) BOOL torchActive
Discussion

A torch must be present on the device and currently available before it can be active.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureDevice.h

torchAvailable

Indicates whether the torch is currently available for use. (read-only)

@property(nonatomic, readonly, getter=isTorchAvailable) BOOL torchAvailable
Discussion

The torch may become unavailable if, for example, the device overheats and needs to cool off.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureDevice.h

torchLevel

The current torch brightness level. (read-only)

@property(nonatomic, readonly) float torchLevel
Discussion

The value of this property is a floating-point number whose value is in the range 0.0 to 1.0. A torch level of 0.0 indicates that the torch is off. A torch level of 1.0 represents the theoretical maximum value, although the actual maximum value may be lower if the device is currently overheated.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
AVCaptureDevice.h

torchMode

The current torch mode.

@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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

uniqueID

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

@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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

videoZoomFactor

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

@property(nonatomic) CGFloat videoZoomFactor
Discussion

This value is a multiplier. For example, a value of 2.0 doubles the size of an image’s subject (and halves the field of view). Allowed values range from 1.0 (full field of view) to the value of the active format’s videoMaxZoomFactor property. Setting the value of this property jumps immediately to the new zoom factor. For a smooth transition, use the rampToVideoZoomFactor:withRate: method.

The device achieves a zoom effect by cropping around the center of the image captured by the sensor. At low zoom factors, the cropped images is equal to or larger than the output size. At higher zoom factors, the device must scale the cropped image up to the output size, resulting in a loss of image quality. The active format’s videoZoomFactorUpscaleThreshold property indicates the factors at which upscaling will occur.

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.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

whiteBalanceMode

The current white balance mode.

@property(nonatomic) AVCaptureWhiteBalanceMode whiteBalanceMode
Discussion

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.

See “AVCaptureWhiteBalanceMode” for possible values.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

Class Methods

authorizationStatusForMediaType:

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

+ (AVAuthorizationStatus)authorizationStatusForMediaType:(NSString *)mediaType
Parameters
mediaType

A media type constant, either AVMediaTypeVideo or AVMediaTypeAudio.

Return Value

A constant indicating authorization status.

Discussion

Recording audio always requires explicit permission from the user; recording video also requires user permission on devices sold in certain regions. The first time you create any AVCaptureDeviceInput objects for a media type that requires permission, the system automatically displays an alert to request recording permission.

After the user grants recording permission, the system remembers the choice for future use in the same app, but the user can change this choice at any time using the Settings app. If the user has denied your app recoding permission or has not yet responded to the permission prompt, any audio recordings will contain only silence and any video recordings will contain only black frames.

If this method returns AVAuthorizationStatusNotDetermined, you can call requestAccessForMediaType:completionHandler: to prompt the user for recording permission.

Calling this method with any media type other than AVMediaTypeVideo or AVMediaTypeAudio raises an exception.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

defaultDeviceWithMediaType:

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

+ (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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

devices

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

+ (NSArray *)devices
Return Value

An array containing the available capture devices on the system

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

devicesWithMediaType:

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

+ (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.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVCaptureDevice.h

deviceWithUniqueID:

Returns the device with a given ID.

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

The ID of a capture device.

Return Value

The device with ID deviceUniqueID.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

requestAccessForMediaType:completionHandler:

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

+ (void)requestAccessForMediaType:(NSString *)mediaType completionHandler:(void (^)(BOOL granted))handler
Parameters
mediaType

A media type constant, either AVMediaTypeVideo or AVMediaTypeAudio. If any media type is supplied, an NSInvalidArgumentException will be thrown.

handler

A block to be called once permission is granted or denied.

The completion handler is called on an arbitrary dispatch queue. Is it the client's responsibility to ensure that any UIKit-related updates are called on the main queue or main thread as a result.

The block receives the following parameter:

granted

If the user grants permission to use the hardware YES is returned; otherwise NO. The block will return immediately.

Discussion

Recording audio always requires explicit permission from the user; recording video also requires user permission on devices sold in certain regions. The first time you create any AVCaptureDeviceInput objects for a media type that requires permission, the system automatically displays an alert to request recording permission. Alternatively, you can can call this method to prompt the user at a time of your choosing.

This call will not block while the user is being asked for access, allowing the client to continue running. Until access has been granted, any AVCaptureDevices for the media type will vend silent audio samples or black video frames. The user is only asked for permission the first time the client requests access. Later calls use the permission granted by the user.

After the user grants recording permission, the system remembers the choice for future use in the same app, but the user can change this choice at any time using the Settings app. If the user has denied your app recoding permission or has not yet responded to the permission prompt, any audio recordings will contain only silence and any video recordings will contain only black frames.

The response parameter is a block whose sole parameter indicates whether the user granted or denied permission to record. This method always returns immediately. If the user has previously granted or denied recording permission, it executes the block when called; otherwise, it displays an alert and executes the block only after the user has responded to the alert.

Invoking this method with AVMediaTypeAudio is equivalent to calling the AVAudioSession method requestRecordPermission:.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

Instance Methods

cancelVideoZoomRamp

Smoothly ends a zoom transition in progress.

- (void)cancelVideoZoomRamp
Discussion

Calling this method is equivalent to calling rampToVideoZoomFactor:withRate: with a rate of zero. If a zoom transition is in progress, the transition slows to a stop (instead of stopping abruptly).

Before calling this method, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, calling this method raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

hasMediaType:

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

- (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 NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

isExposureModeSupported:

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

- (BOOL)isExposureModeSupported:(AVCaptureExposureMode)exposureMode
Parameters
exposureMode

An exposure mode. See “AVCaptureExposureMode” for possible values.

Return Value

YES if exposureMode is supported, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

isFlashModeSupported:

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

- (BOOL)isFlashModeSupported:(AVCaptureFlashMode)flashMode
Parameters
flashMode

A flash mode. See “AVCaptureFlashMode” for possible values.

Return Value

YES if flashMode is supported, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

isFocusModeSupported:

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

- (BOOL)isFocusModeSupported:(AVCaptureFocusMode)focusMode
Parameters
focusMode

A focus mode. See “AVCaptureFocusMode” for possible values.

Return Value

YES if focusMode is supported, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

isTorchModeSupported:

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

- (BOOL)isTorchModeSupported:(AVCaptureTorchMode)torchMode
Parameters
torchMode

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

Return Value

YES if torchMode is supported, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

isWhiteBalanceModeSupported:

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

- (BOOL)isWhiteBalanceModeSupported:(AVCaptureWhiteBalanceMode)whiteBalanceMode
Parameters
whiteBalanceMode

A focus mode. See “AVCaptureWhiteBalanceMode” for possible values.

Return Value

YES if whiteBalanceMode is supported, otherwise NO.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

lockForConfiguration:

Requests exclusive access to the device’s hardware properties.

- (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

YES if a lock was acquired or NO if it was not.

Discussion

You must call this method before attempting to configure the hardware related properties of the device. This method returns YES 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

rampToVideoZoomFactor:withRate:

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

- (void)rampToVideoZoomFactor:(CGFloat)factor withRate:(float)rate
Parameters
factor

The new magnification factor.

rate

The rate at which to transition to the new magnification factor, specified in powers of two per second.

Discussion

Allowed values for factor range from 1.0 (full field of view) to the videoMaxZoomFactor specified by the active capture format.

During a ramp, the zoom factor changes at an exponential rate, but this yields a visually linear transition. The rate parameter controls the speed of this transition independent of direction; for example, a value of 1.0 causes zoom factor to double every second if zooming in (that is, if the specified factor is greater than the current videoZoomFactor) or halve every second if zooming out.

Before calling this method, you must call lockForConfiguration: to acquire exclusive access to the device’s configuration properties. If you do not, calling this method raises an exception. When you are done configuring the device, call unlockForConfiguration to release the lock and allow other devices to configure the settings.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVCaptureDevice.h

setTorchModeOnWithLevel:error:

Sets the illumination level when in torch mode.

- (BOOL)setTorchModeOnWithLevel:(float)torchLevel error:(NSError **)outError
Parameters
torchLevel

The new torch mode level. This value must be a floating-point number between 0.0 and 1.0. To set the torch mode level to the currently available maximum, specify the constant AVCaptureMaxAvailableTorchLevel for this parameter.

outError

On input, a pointer to an error object. If an error occurs, this method assigns an error object to the pointer with information about what happened.

Return Value

YES if the torch mode level was set or NO if it was not.

Discussion

This method sets the torch mode to AVCaptureTorchModeOn and sets the level to the specified value. If the device does not support the AVCaptureTorchModeOn torch mode or if you specify a value for torchLevel that is outside the accepted range, this method raises an exception. If the torch value in is within the accepted range but greater than the currently supported maximum—perhaps because the device is overheating—this method simply returns NO.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
AVCaptureDevice.h

supportsAVCaptureSessionPreset:

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

- (BOOL)supportsAVCaptureSessionPreset:(NSString *)preset
Parameters
preset

A capture session preset.

Return Value

YES if the receiver can be used with preset, otherwise NO.

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

unlockForConfiguration

Relinquishes exclusive control over the device’s configuration.

- (void)unlockForConfiguration
Discussion

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

Availability
  • Available in iOS 4.0 and later.
Declared In
AVCaptureDevice.h

Constants

AVCaptureDevicePosition

Constants to specify the position of a capture device.

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

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

Available in iOS 6.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureDevicePositionBack

The capture device is on the back of the unit.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureDevicePositionFront

The capture device is on the front of the unit.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFlashMode

Constants to specify the flash mode of a capture device.

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

The capture device flash is always off.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFlashModeOn

The capture device flash is always on.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFlashModeAuto

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

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureTorchMode

Constants to specify the capture device’s torch mode.

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

The capture device torch is always off.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureTorchModeOn

The capture device torch is always on.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureTorchModeAuto

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

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

Torch Level Constant

The maximum torch level.

const float AVCaptureMaxAvailableTorchLevel;
Constants
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 iOS 6.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFocusMode

Constants to specify the focus mode of a capture device.

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

The focus is locked.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFocusModeAutoFocus

The capture device performs an autofocus operation now.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureFocusModeContinuousAutoFocus

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

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureExposureMode

Constants to specify the exposure mode of a capture device.

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

The exposure setting is locked.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureExposureModeAutoExpose

The device performs an auto-expose operation now.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureExposureModeContinuousAutoExposure

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

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureWhiteBalanceMode

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

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

The white balance setting is locked.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureWhiteBalanceModeAutoWhiteBalance

The device performs an auto white balance operation now.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureWhiteBalanceModeContinuousAutoWhiteBalance

The device continuously monitors white balance and adjusts when necessary.

Available in iOS 4.0 and later.

Declared in AVCaptureDevice.h.

AVAuthorizationStatus

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

typedef enum : NSInteger {
   AVAuthorizationStatusNotDetermined = 0,
   AVAuthorizationStatusRestricted,
   AVAuthorizationStatusDenied,
   AVAuthorizationStatusAuthorized
} AVAuthorizationStatus;
Constants
AVAuthorizationStatusNotDetermined

Explicit user permission is required for media capture, but the user has not yet granted or denied such permission.

Call requestAccessForMediaType:completionHandler: to prompt the user for permission, or create an AVCaptureDeviceInput for the media type and the user will be automatically prompted.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVAuthorizationStatusRestricted

The user is not allowed to access media capture devices.

This status is normally not visible—the AVCaptureDevice class methods for discovering devices do not return devices the user is restricted from accessing.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVAuthorizationStatusDenied

The user has explicitly denied permission for media capture.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVAuthorizationStatusAuthorized

The user has explicitly granted permission for media capture, or explicit user permission is not necessary for the media type in question.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureAutoFocusRangeRestriction

Constants to specify the autofocus range of a capture device.

enum {
   AVCaptureAutoFocusRangeRestrictionNone = 0,
   AVCaptureAutoFocusRangeRestrictionNear = 1,
   AVCaptureAutoFocusRangeRestrictionFar  = 2,
};
typedef NSInteger AVCaptureAutoFocusRangeRestriction;
Constants
AVCaptureAutoFocusRangeRestrictionNone

The device attempts to focus on objects at any range.

This value is the default, and the only value allowed on devices that do not support focus range restriction.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureAutoFocusRangeRestrictionNear

The device primarily attempts to focus on subjects near the camera.

This value is recommended for applications that use AVCaptureMetadataOutput to recognize machine-readable codes.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

AVCaptureAutoFocusRangeRestrictionFar

The device primarily attempts to focus on subjects far away from the camera.

Available in iOS 7.0 and later.

Declared in AVCaptureDevice.h.

Discussion

If you expect to focus primarily on near or far objects, you can use the autoFocusRangeRestriction property to provide a hint to the focusing system. This approach makes autofocus faster, more power efficient, and less error prone. A restriction prioritizes focusing at distances in the specified range, but does not prevent focusing elsewhere if the device finds no focus point within that range.

Notifications

AVCaptureDeviceWasConnectedNotification

Posted when a new device becomes available.

The notification object is an AVCaptureDevice instance representing the device that became available.

Availability
Declared In
AVCaptureDevice.h

AVCaptureDeviceWasDisconnectedNotification

Posted when an existing device becomes unavailable.

The notification object is an AVCaptureDevice instance representing the device that became unavailable.

Availability
Declared In
AVCaptureDevice.h

AVCaptureDeviceSubjectAreaDidChangeNotification

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

Clients may observe the AVCaptureDeviceSubjectAreaDidChangeNotification to know when an instance of AVCaptureDevice has detected a substantial change to the video subject area.

This notification is sent only if subjectAreaChangeMonitoringEnabled is YES.

Availability
Declared In
AVCaptureDevice.h