[camera] Add framesPerSecond parameter to CameraImageStreamOptions #176148

The CameraImageStreamOptions class in camera_platform_interface currently lacks a mechanism to specify the desired frames per second (FPS) for the camera image stream. This limitation prevents developers from controlling the frame rate of the image data received from the camera, which is crucial for various use cases requiring specific performance or resource management.

Proposed Solution:
Introduce a framesPerSecond parameter (e.g., an int or double) to the CameraImageStreamOptions class. This parameter would allow clients to request a specific frame rate for the image stream.

// ... existing code ...
@immutable
class CameraImageStreamOptions {
  /// Creates a new instance with the given frame rate.
  ///
  /// The [framesPerSecond] parameter specifies the desired frame rate for the
  /// camera image stream. The platform will attempt to achieve this rate,
  /// but it is not guaranteed. A value of null indicates that the platform
  /// should use its default frame rate.
  const CameraImageStreamOptions({this.framesPerSecond});

  /// The desired frames per second for the camera image stream.
  ///
  /// If null, the platform will use its default frame rate.
  final double? framesPerSecond;
}
// ... existing code ...

Use Cases in camera packages:

• @camera/camera_web:

  • Browser API Integration: This parameter would allow camera_web to pass the desired FPS, providing more control over the streaming of image frames.
  • Video Conferencing: For web-based video conferencing applications, controlling the frame rate can optimize bandwidth usage and improve performance in varying network conditions.

• @camera/camera_avfoundation (iOS/macOS):

  • AVFoundation Control: AVCaptureDevice on iOS/macOS allows setting activeVideoMinFrameDuration and activeVideoMaxFrameDuration to control the capture frame rate. Implementing framesPerSecond would enable camera_avfoundation to configure these properties, providing fine-grained control over camera input.
  • High-Speed Video: Applications requiring high-speed video capture or specific cinematic effects could leverage precise FPS control.

• @camera/camera_android_camerax (Android CameraX):

  • CameraX Use Cases: CameraX's Preview, ImageCapture, and ImageAnalysis use cases can be configured with target frame rates. This parameter would allow camera_android_camerax to set appropriate frame rate hints for CameraX, leading to optimized camera performance and power consumption.
  • Computer Vision: For AI/ML applications performing real-time image analysis, a consistent and controlled frame rate is essential for predictable model inference.

• @camera/camera_windows (Windows):

  • Windows Media Foundation: The Windows camera APIs (e.g., via Windows Media Foundation) allow configuring frame rates for video streams. camera_windows could map framesPerSecond to the appropriate Windows API calls, ensuring proper frame rate negotiation with the camera hardware.
  • Custom Applications: Windows applications requiring specific frame rates for recording or streaming could benefit from this control.

• @camera/camera_android (Android Camera1/2):

  • Legacy API Support: Even older Android Camera1 and Camera2 APIs offer ways to set preview or capture frame rates (e.g., setPreviewFpsRange in Camera1, CONTROL_AE_TARGET_FPS_RANGE in Camera2). The framesPerSecond parameter would enable camera_android to configure these settings, supporting a wider range of Android devices and API levels.
  • Resource Management: On resource-constrained Android devices, lowering the frame rate can reduce CPU and power consumption.

Considerations:

• Platform Support: Not all platforms or camera devices may support arbitrary frame rates. The implementation should gracefully handle unsupported requests, potentially by clamping the requested FPS to an available range or falling back to a default.
• Negotiation: The actual frame rate achieved might differ from the requested one due to hardware limitations or other active camera streams. The platform implementation should aim for the closest possible match.
• Default Behavior: If framesPerSecond is not provided, the platform should use its default or preferred frame rate.