feat: frameProcessorFps="auto" and automatic performance suggestions (throttle or increase FPS) (#393)

* Add `onFrameProcessorPerformanceSuggestionAvailable` and make `frameProcessorFps` support `auto`

* Implement performance suggestion and auto-adjusting

* Fix FPS setting, evaluate correctly

* Floor suggested FPS

* Remove `console.log` for frame drop warnings.

* Swift format

* Use `30` magic number

* only call if FPS is different

* Update CameraView.swift

* Implement Android 1/2

* Cleanup

* Update `frameProcessorFps` if available

* Optimize `FrameProcessorPerformanceDataCollector` initialization

* Cache call

* Set frameProcessorFps directly (Kotlin setter)

* Don't suggest if same value

* Call suggestion every second

* reset time on set

* Always store 15 last samples

* reset counter too

* Update FrameProcessorPerformanceDataCollector.swift

* Update CameraView+RecordVideo.swift

* Update CameraView.kt

* iOS: Redesign evaluation

* Update CameraView+RecordVideo.swift

* Android: Redesign evaluation

* Update CameraView.kt

* Update REA to latest alpha and install RNScreens

* Fix frameProcessorFps updating

src/Camera.tsx

@@ -8,6 +8,7 @@ import {
   Platform,
   LayoutChangeEvent,
 } from 'react-native';
+import type { FrameProcessorPerformanceSuggestion } from '.';
 import type { CameraDevice } from './CameraDevice';
 import type { ErrorWithCause } from './CameraError';
 import { CameraCaptureError, CameraRuntimeError, tryParseNativeCameraError, isErrorWithCause } from './CameraError';
@@ -27,11 +28,16 @@ interface OnErrorEvent {
   message: string;
   cause?: ErrorWithCause;
 }
-type NativeCameraViewProps = Omit<CameraProps, 'device' | 'onInitialized' | 'onError' | 'frameProcessor'> & {
+type NativeCameraViewProps = Omit<
+  CameraProps,
+  'device' | 'onInitialized' | 'onError' | 'onFrameProcessorPerformanceSuggestionAvailable' | 'frameProcessor' | 'frameProcessorFps'
+> & {
   cameraId: string;
+  frameProcessorFps?: number; // native cannot use number | string, so we use '-1' for 'auto'
   enableFrameProcessor: boolean;
   onInitialized?: (event: NativeSyntheticEvent<void>) => void;
   onError?: (event: NativeSyntheticEvent<OnErrorEvent>) => void;
+  onFrameProcessorPerformanceSuggestionAvailable?: (event: NativeSyntheticEvent<FrameProcessorPerformanceSuggestion>) => void;
 };
 type RefType = React.Component<NativeCameraViewProps> & Readonly<NativeMethods>;
 //#endregion
@@ -86,6 +92,7 @@ export class Camera extends React.PureComponent<CameraProps> {
     super(props);
     this.onInitialized = this.onInitialized.bind(this);
     this.onError = this.onError.bind(this);
+    this.onFrameProcessorPerformanceSuggestionAvailable = this.onFrameProcessorPerformanceSuggestionAvailable.bind(this);
     this.onLayout = this.onLayout.bind(this);
     this.ref = React.createRef<RefType>();
     this.lastFrameProcessor = undefined;
@@ -333,6 +340,11 @@ export class Camera extends React.PureComponent<CameraProps> {
   private onInitialized(): void {
     this.props.onInitialized?.();
   }
+
+  private onFrameProcessorPerformanceSuggestionAvailable(event: NativeSyntheticEvent<FrameProcessorPerformanceSuggestion>): void {
+    if (this.props.onFrameProcessorPerformanceSuggestionAvailable != null)
+      this.props.onFrameProcessorPerformanceSuggestionAvailable(event.nativeEvent);
+  }
   //#endregion
 
   //#region Lifecycle
@@ -396,14 +408,16 @@ export class Camera extends React.PureComponent<CameraProps> {
   /** @internal */
   public render(): React.ReactNode {
     // We remove the big `device` object from the props because we only need to pass `cameraId` to native.
-    const { device, frameProcessor, ...props } = this.props;
+    const { device, frameProcessor, frameProcessorFps, ...props } = this.props;
     return (
       <NativeCameraView
         {...props}
+        frameProcessorFps={frameProcessorFps === 'auto' ? -1 : frameProcessorFps}
         cameraId={device.id}
         ref={this.ref}
         onInitialized={this.onInitialized}
         onError={this.onError}
+        onFrameProcessorPerformanceSuggestionAvailable={this.onFrameProcessorPerformanceSuggestionAvailable}
         enableFrameProcessor={frameProcessor != null}
         onLayout={this.onLayout}
       />

src/CameraProps.ts

@@ -4,6 +4,11 @@ import type { CameraRuntimeError } from './CameraError';
 import type { CameraPreset } from './CameraPreset';
 import type { Frame } from './Frame';
 
+export interface FrameProcessorPerformanceSuggestion {
+  type: 'can-use-higher-fps' | 'should-use-lower-fps';
+  suggestedFrameProcessorFps: number;
+}
+
 export interface CameraProps extends ViewProps {
   /**
    * The Camera Device to use.
@@ -161,6 +166,10 @@ export interface CameraProps extends ViewProps {
    * Called when the camera was successfully initialized.
    */
   onInitialized?: () => void;
+  /**
+   * Called when a new performance suggestion for a Frame Processor is available - either if your Frame Processor is running too fast and frames are being dropped, or because it is able to run faster. Optionally, you can adjust your `frameProcessorFps` accordingly.
+   */
+  onFrameProcessorPerformanceSuggestionAvailable?: (suggestion: FrameProcessorPerformanceSuggestion) => void;
   /**
    * A worklet which will be called for every frame the Camera "sees". Throttle the Frame Processor's frame rate with {@linkcode frameProcessorFps}.
    *
@@ -183,7 +192,8 @@ export interface CameraProps extends ViewProps {
   /**
    * Specifies the maximum frame rate the frame processor can use, independent of the Camera's frame rate (`fps` property).
    *
-   * * A value of `1` (default) indicates that the frame processor gets executed once per second, perfect for code scanning.
+   * * A value of `'auto'` (default) indicates that the frame processor should execute as fast as it can, without dropping frames. This is achieved by collecting historical data for previous frame processor calls and adjusting frame rate accordingly.
+   * * A value of `1` indicates that the frame processor gets executed once per second, perfect for code scanning.
    * * A value of `10` indicates that the frame processor gets executed 10 times per second, perfect for more realtime use-cases.
    * * A value of `25` indicates that the frame processor gets executed 25 times per second, perfect for high-speed realtime use-cases.
    * * ...and so on
@@ -191,8 +201,8 @@ export interface CameraProps extends ViewProps {
    * If you're using higher values, always check your Xcode/Android Studio Logs to make sure your frame processors are executing fast enough
    * without blocking the video recording queue.
    *
-   * @default 1
+   * @default 'auto'
    */
-  frameProcessorFps?: number;
+  frameProcessorFps?: number | 'auto';
   //#endregion
 }