CameraDevice

interface CameraDevice extends HybridObject

The CameraDevice represents a physical- or virtual Camera Device.

Examples:

• Physical: The 0.5x ultra-wide-angle Camera
• Virtual: The Triple-Camera consisting of the 0.5x, the 1x, and the 3x Camera
• TrueDepth Face ID: A virtual Camera consisting of a color, and a depth Camera

Properties

companionDeskViewCamera?

readonly optional companionDeskViewCamera: CameraDevice

The matching Desk View camera for this Continuity Camera, if available.

focalLength?

readonly optional focalLength: number

Returns the Camera Device's nominal focal length in 35mm film format.

hasFlash

readonly hasFlash: boolean

Whether this CameraDevice has a physical flash unit, or not.

For front-facing devices, hasFlash may be false, but you might still be able to use a screen- flash for photo capture.

See

CapturePhotoSettings.flashMode

hasTorch

readonly hasTorch: boolean

Whether this CameraDevice supports using its flash (hasFlash) as a continuous light ("torch") while the session is running.

In almost all cases, hasTorch is the same as hasFlash.

See

setTorchMode(...)

id

readonly id: string

A unique identifier for this camera device.

isContinuityCamera

readonly isContinuityCamera: boolean

Returns true if this camera is a Continuity Camera. On non iOS platforms this is always false.

isVirtualDevice

readonly isVirtualDevice: boolean

Gets whether this CameraDevice is a virtual device, which consists of two or more physical CameraDevices.

Devices like the "Triple-Camera" (0.5x + 1x + 3x) or the "FaceID Camera" (color + depth) are virtual devices.

To access the individual physical devices a virtual device consists of, use physicalDevices.

lensAperture

readonly lensAperture: number

The size (ƒ number) of the lens diaphragm.

localizedName

readonly localizedName: string

A user friendly camera name shown by the system.

manufacturer

readonly manufacturer: string

The hardware manufacturer name for this device.

maxExposureBias

readonly maxExposureBias: number

Gets the maximum supported value for the exposure bias (in EV units), or 0 if supportsExposureBias is false.

maxWhiteBalanceGain

readonly maxWhiteBalanceGain: number

The maximum value a single color-channel can be set to in WhiteBalanceGains, or 0 if supportsWhiteBalanceLocking is false.

maxZoom

readonly maxZoom: number

The maximum individually supported zoom value of this device.

mediaTypes

readonly mediaTypes: MediaType[]

Represents all MediaTypes this CameraDevice can capture.

Most Cameras return ['video']. Virtual Cameras that also support Depth Capture return ['video', 'depth'].

minExposureBias

readonly minExposureBias: number

Gets the minimum supported value for the exposure bias (in EV units), or 0 if supportsExposureBias is false.

minZoom

readonly minZoom: number

The minimum individually supported zoom value of this device.

modelID

readonly modelID: string

The model identifier for this camera device.

physicalDevices

readonly physicalDevices: CameraDevice[]

If this CameraDevice is a virtual device (see isVirtualDevice), this property contains a list of all constituent physical devices this virtual device is made of.

For physical devices, this returns an empty array.

position

readonly position: CameraPosition

The position of this camera on the device.

supportedFPSRanges

readonly supportedFPSRanges: Range[]

Gets all available Frame Rate Ranges this CameraDevice supports individually.

Frame Rates are expressed in FPS (Frames per Second), for example 60 refers to 60 FPS (= 16.666ms per Frame).

Discussion

Use supportsFPS(...) as a convenience method to find out if a given fixed frame rate is supported individually.

Discussion

While a device may support a given FPS Range individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically FPSConstraint) internally negotiates the target fps with other enabled features (such as VideoStabilizationModeConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.

supportedPixelFormats

readonly supportedPixelFormats: PixelFormat[]

Get a list of all supported PixelFormats this CameraDevice can stream in.

supportedVideoDynamicRanges

readonly supportedVideoDynamicRanges: DynamicRange[]

Get a list of all DynamicRanges this CameraDevice supports streaming at, often affecting both Video recordings and Preview.

Discussion

Unlike Photo HDR, Video Dynamic Ranges are not only extra processing, but often entirely different sensor readouts. While Photo HDR might capture multiple bracketed Photos to fuse them together to expose more colors, Video Dynamic Ranges sometimes stream in an entirely different Pixel Format (e.g. 10-bit instead of 8-bit), and use a different YUV Transfer Matrix to compose pixels from sensor data.

Discussion

While a device may support a given DynamicRange individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically VideoDynamicRangeConstraint) internally negotiates the target Dynamic Range with other enabled features (such as ResolutionBiasConstraint or FPSConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.

See

• VideoDynamicRangeConstraint.videoDynamicRange
• CameraVideoOutput

supportsDistortionCorrection

readonly supportsDistortionCorrection: boolean

Whether the CameraDevice supports distortion correction to correct stretched edges in wide-angle Cameras during Photo capture.

See

CapturePhotoSettings.enableDistortionCorrection

supportsExposureBias

readonly supportsExposureBias: boolean

Gets whether this CameraDevice supports biasing auto-exposure via setExposureBias(...).

supportsExposureLocking

readonly supportsExposureLocking: boolean

Gets whether this CameraDevice supports manual exposure via setExposureLocked(...).

supportsExposureMetering

readonly supportsExposureMetering: boolean

Gets whether this CameraDevice supports metering auto-exposure ('AE') via focusTo(...).

supportsFocusLocking

readonly supportsFocusLocking: boolean

Gets whether this CameraDevice supports manual focus via setFocusLocked(...).

supportsFocusMetering

readonly supportsFocusMetering: boolean

Gets whether this CameraDevice supports metering auto-focus ('AF') via focusTo(...).

supportsLowLightBoost

readonly supportsLowLightBoost: boolean

Whether this CameraDevice supports enabling low-light boost to improve exposure in dark scenes via CameraControllerConfiguration.enableLowLightBoost.

Example

await controller.configure({
  enableLowLightBoost: device.supportsLowLightBoost
})

supportsPhotoHDR

readonly supportsPhotoHDR: boolean

Gets whether this CameraDevice supports capturing Photos in High Dynamic Range (HDR).

Discussion

Photo HDR captures multiple images in various exposure settings (often one under-exposed, one over-exposed and one perfectly exposed), and fuses the images together into a single image with a wider range of colors, which results in darker blacks and brighter whites.

Discussion

While a device may support Photo HDR individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically PhotoHDRConstraint) internally negotiates the target Photo HDR preference with other enabled features (such as ResolutionBiasConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.

See

• PhotoHDRConstraint.photoHDR
• CameraPhotoOutput

supportsPreviewImage

readonly supportsPreviewImage: boolean

Returns true if this CameraDevice supports delivering preview Image instances before the actual Photo is available.

On iOS, this is always true.

See

• PhotoOutputOptions.previewImageTargetSize
• CapturePhotoCallbacks.onPreviewImageAvailable

supportsSmoothAutoFocus

readonly supportsSmoothAutoFocus: boolean

Gets whether this CameraDevice supports smoothly adjusting focus via CameraControllerConfiguration.enableSmoothAutoFocus.

Example

await controller.configure({
  enableSmoothAutoFocus: device.supportsSmoothAutoFocus
})

supportsSpeedQualityPrioritization

readonly supportsSpeedQualityPrioritization: boolean

Returns true if this CameraDevice supports capturing photos with the 'speed' QualityPrioritization.

See

PhotoOutputOptions.qualityPrioritization

supportsWhiteBalanceLocking

readonly supportsWhiteBalanceLocking: boolean

Gets whether this CameraDevice supports manual white-balance via setWhiteBalanceLocked(...).

See

maxWhiteBalanceGain

supportsWhiteBalanceMetering

readonly supportsWhiteBalanceMetering: boolean

Gets whether this CameraDevice supports metering auto-white-balance ('AWB') via focusTo(...).

type

readonly type: DeviceType

The camera hardware type, for example 'wide-angle'.

zoomLensSwitchFactors

readonly zoomLensSwitchFactors: number[]

If this CameraDevice is a virtual device, this returns a list of zoom factors at which the virtual device may switch to another physical camera.

For physical devices, this returns an empty array.

Example

const camera = ...           // Triple-Camera (0.5x, 1x, 3x)
camera.zoomLensSwitchFactors // [1, 3]

Methods

getSupportedResolutions()

getSupportedResolutions(outputStreamType: OutputStreamType): Size[]

Get a list of all supported resolutions this CameraDevice can produce for outputs of the given OutputStreamType.

If a given OutputStreamType can not be streamed to at all, an empty array ([]) will be returned.

Discussion

While a CameraDevice may be able to stream in the given output resolutions individually, it is not guaranteed that all resolutions are available when streaming to multiple CameraOutput with multiple Constraints enabled.

The CameraSession internally negotiates available output resolutions based on Constraints, and potentially downgrades (or upgrades) target resolutions if needed.

See

• VideoOutputOptions.targetResolution
• PhotoOutputOptions.targetResolution
• FrameOutputOptions.targetResolution
• DepthFrameOutputOptions.targetResolution
• ResolutionBiasConstraint

Example

Get all resolutions for Photo capture:

const device = ...
const resolutions = device.getSupportedResolutions('photo')

isSessionConfigSupported()

isSessionConfigSupported(config: CameraSessionConfig): boolean

Returns whether the given CameraSessionConfig is supported by this CameraDevice, or not.

If this method returns false, configuring a CameraSession with this CameraSessionConfig will fail.

supportsFPS()

supportsFPS(fps: number): boolean

Gets whether the given fps is individually supported by any of the supportedFPSRanges on this CameraDevice.

Discussion

While a device may support a given FPS Range individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically FPSConstraint) internally negotiates the target fps with other enabled features (such as VideoStabilizationModeConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.

See

supportedFPSRanges

supportsOutput()

supportsOutput(output: CameraOutput): boolean

Returns whether this CameraDevice supports streaming to the given output.

Discussion

Usually, a CameraDevice can stream to all CameraOutputs, with very rare exceptions.

For example, Depth Frame Outputs (CameraDepthFrameOutput) may not be supported on all CameraDevices - see mediaTypes.

supportsPreviewStabilizationMode()

supportsPreviewStabilizationMode(previewStabilizationMode: TargetStabilizationMode): boolean

Returns whether this CameraDevice supports the given StabilizationMode for preview streams (e.g. CameraPreviewOutput).

Discussion

While a device may support a given StabilizationMode individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically PreviewStabilizationModeConstraint) internally negotiates the target previewStabilizationMode with other enabled features (such as FPSConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.

supportsVideoStabilizationMode()

supportsVideoStabilizationMode(videoStabilizationMode: TargetStabilizationMode): boolean

Returns whether this CameraDevice supports the given StabilizationMode for video streams (e.g. CameraVideoOutput).

Discussion

While a device may support a given StabilizationMode individually, it is not guaranteed to be supported with all possible feature and output combinations.

The Constraint API (specifically VideoStabilizationModeConstraint) internally negotiates the target videoStabilizationMode with other enabled features (such as FPSConstraint) and all connected CameraOutputs to find a best-matching supported combination on this device.

Alternatively, to find out if a specific combination is supported upfront, use the isSessionConfigSupported(...) method with your desired outputs and constraints applied.