CaptureDevice class

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

A CaptureDevice 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 CaptureSession object.

You use the methods of the CaptureDevice 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 CaptureSession 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 CaptureDevice instance. The following code example illustrates how to select an iOS device’s highest possible frame rate:

NOTE: Example code below is yet supported.

void 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.
      }
  }
}

In iOS, directly configuring a capture device’s setActiveFormat]changes the capture session’s preset to CaptureSessionPreset.inputPriority. Upon making this change, the capture session no longer automatically configures the capture format when you call the CaptureSession.startRunning method or call the CaptureSession.commitConfiguration method after changing the session topology.

In macOS, a capture session can still automatically configure the capture format after you make changes. To prevent automatic changes to the capture format in macOS, follow the advice listed under the lockForConfiguration method.

Annotations

@Reference('av_foundation/av_foundation/CaptureDevice')

Constructors

CaptureDevice({required String uniqueId, required int position, required bool isSmoothAutoFocusSupported, required bool hasFlash, required bool hasTorch, required double maxAvailableTorchLevel}): Construct a CaptureDevice.

Properties

hasFlash → bool: Indicates whether the capture device has a flash.
final
hashCode → int: The hash code for this object.
no setterinherited
hasTorch → bool: A Boolean value that specifies whether the capture device has a torch.
final
isSmoothAutoFocusSupported → bool: A Boolean value that indicates whether the device supports smooth autofocus.
final
maxAvailableTorchLevel → double: This constant always represents the maximum available torch level, independent of the actual maximum value currently supported by the device.
final
position → int: Indicates the physical position of the device hardware on the system.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
uniqueId → String: An ID unique to the model of device corresponding to the receiver.
final

Methods

cancelVideoZoomRamp() → Future<void>: Smoothly ends a zoom transition in progress.
exposureModesSupported(List<int> modes) → Future<List<int>>: Returns a subset of values that indicates whether the given exposure modes are supported.
focusModesSupported(List<int> modes) → Future<List<int>>: Returns a subset of values that indicates whether the given focus modes are supported.
isAdjustingExposure() → Future<bool>: Indicates whether the device is currently adjusting its exposure setting.
isAdjustingFocus() → Future<bool>: A Boolean value that indicates whether the device is currently adjusting its focus setting.
isFlashAvailable() → Future<bool>: Indicates whether the flash is currently available for use.
isRampingVideoZoom() → Future<bool>: A Boolean value that indicates whether a zoom transition is in progress.
isTorchActive() → Future<bool>: A Boolean value indicating whether the device’s torch is currently active.
isTorchAvailable() → Future<bool>: Indicates whether the torch is currently available for use.
lockForConfiguration() → Future<bool>: Requests exclusive access to the device’s hardware properties.
maxAvailableVideoZoomFactor() → Future<double>: The maximum zoom factor allowed in the current capture configuration.
minAvailableVideoZoomFactor() → Future<double>: The minimum zoom factor allowed in the current capture configuration.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
rampToVideoZoomFactor(double factor, double rate) → Future<void>: Begins a smooth transition from the current zoom factor to another.
setExposureMode(int mode) → Future<void>: The exposure mode for the device.
setFocusMode(int mode) → Future<void>: The capture device’s focus mode.
setSmoothAutoFocusEnabled({required bool enabled}) → Future<void>: A Boolean value that determines whether smooth autofocus is in an enabled state on the device.
setTorchMode(int mode) → Future<void>: Sets the current torch mode.
setTorchModeOnWithLevel(double torchLevel) → Future<void>: Sets the illumination level when in torch mode.
setVideoZoomFactor(double factor) → Future<void>: A value that controls the cropping and enlargement of images captured by the device.
supportsCaptureSessionPresets(List<String> presets) → Future<List<String>>: Returns a subset of preset values that indicate whether the receiver can be used in a capture session configured with the given presets.
torchLevel() → Future<double>: The current torch brightness level.
torchModesSupported(List<int> modes) → Future<List<int>>: Returns a subset of values that indicate whether the device supports the specified torch modes.
toString() → String: A string representation of this object.
override
unlockForConfiguration() → Future<void>: Relinquishes exclusive control over the device’s configuration.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

defaultDeviceWithMediaType(String mediaType) → Future<CaptureDevice?>: Returns the default device used to capture data of a given media type.