feat: Add Templates API for choosing Camera Formats (#1844)

* docs: New V3 docs for new API

* fix: Prefer Wide-Angle unless explicitly opted-out

* docs: Update DEVICES

* Finish Devices docs

* Switch links

* Revert "Switch links"

This reverts commit 06f196ae0e67787cbd5768e125be6d0a3cb5bbc9.

* docs: New LIFECYCLE

* docs: New CAPTURING docs

* Update Worklets links

* docs: Update TROUBLESHOOTING and ZOOMING

* fix: Update `getAvailableCameraDevices()` usages

* docs: Update FORMATS

* Update Errors.kt

* docs: Fix broken links

* docs: Update references to old hooks

* docs: Create Frame Processor Tips

* docs: Auto-dark mode

* fix: Fix FPS filter

* feat: Add `'max'` flag to format filter

* fix: Use loop

* fix: Fix bug in `getCameraFormat`

* fix: Find best aspect ratio as well

* fix: Switch between formats on FPS change

* Update FRAME_PROCESSOR_PLUGIN_LIST.mdx

* Add FPS graph explanation

* feat: Add `Templates` API for choosing Camera Formats

package/src/devices/Templates.ts

@@ -0,0 +1,72 @@
+import { Dimensions } from 'react-native';
+import { FormatFilter } from './getCameraFormat';
+
+type TTemplates = {
+  [key: string]: FormatFilter[];
+};
+
+const SnapchatResolution = { width: 1920, height: 1080 };
+const InstagramResolution = { width: 3840, height: 2160 };
+const ScreenAspectRatio = Dimensions.get('window').height / Dimensions.get('window').width;
+
+/**
+ * Predefined templates for use in `useCameraFormat`/`getCameraFormat`.
+ * @example
+ * ```ts
+ * const format = useCameraFormat(device, Templates.Snapchat)
+ * ```
+ */
+export const Templates: TTemplates = {
+  /**
+   * Highest resolution video recordings (e.g. 4k)
+   */
+  Video: [{ videoResolution: 'max' }],
+  /**
+   * High resolution 60 FPS video recordings (e.g. 1080@60 FPS)
+   */
+  Video60Fps: [{ fps: 60 }, { videoResolution: 'max' }],
+  /**
+   * High-FPS video recordings (e.g. 720@240 FPS)
+   */
+  VideoSlowMotion: [{ fps: 240 }, { videoResolution: 'max' }],
+  /**
+   * High resolution video recordings with cinematic video stabilization
+   */
+  VideoStabilized: [{ videoResolution: 'max' }, { videoStabilizationMode: 'cinematic-extended' }],
+  /**
+   * Highest resolution photo capture (e.g. 4k)
+   */
+  Photo: [{ photoResolution: 'max' }],
+  /**
+   * Highest resolution photo capture with portrait screen aspect ratio (e.g. 4k)
+   */
+  PhotoPortrait: [{ photoResolution: 'max' }, { photoAspectRatio: ScreenAspectRatio }],
+  /**
+   * HD-quality for faster Frame Processing in YUV pixelFormat (e.g. 720p)
+   */
+  FrameProcessingYUV: [{ videoResolution: { width: 1080, height: 720 } }, { pixelFormat: 'yuv' }],
+  /**
+   * HD-quality for faster Frame Processing in RGB pixelFormat (e.g. 720p)
+   */
+  FrameProcessingRGB: [{ videoResolution: { width: 1080, height: 720 } }, { pixelFormat: 'rgb' }],
+  /**
+   * Snapchat-style video recordings and photo capture
+   * Targets Full HD-quality for lower file sizes and portrait screen aspect ratio.
+   */
+  Snapchat: [
+    { videoAspectRatio: ScreenAspectRatio },
+    { videoResolution: SnapchatResolution },
+    { photoAspectRatio: ScreenAspectRatio },
+    { photoResolution: SnapchatResolution },
+  ],
+  /**
+   * Instagram-style video recordings and photo capture.
+   * Targets 4k-quality and portrait screen aspect ratio.
+   */
+  Instagram: [
+    { videoAspectRatio: ScreenAspectRatio },
+    { videoResolution: InstagramResolution },
+    { photoAspectRatio: ScreenAspectRatio },
+    { photoResolution: InstagramResolution },
+  ],
+};

package/src/devices/getCameraFormat.ts

@@ -20,18 +20,20 @@ export interface FormatFilter {
   photoResolution?: Size | 'max';
   /**
    * The target aspect ratio of the video (and preview) output, expressed as a factor: `width / height`.
+   * (Note: Cameras are in landscape orientation)
    *
    * In most cases, you want this to be as close to the screen's aspect ratio as possible (usually ~9:16).
    *
    * @example
    * ```ts
    * const screen = Dimensions.get('screen')
-   * targetVideoAspectRatio: screen.width / screen.height
+   * targetVideoAspectRatio: screen.height / screen.width
    * ```
    */
   videoAspectRatio?: number;
   /**
    * The target aspect ratio of the photo output, expressed as a factor: `width / height`.
+   * (Note: Cameras are in landscape orientation)
    *
    * In most cases, you want this to be the same as `targetVideoAspectRatio`, which you often want
    * to be as close to the screen's aspect ratio as possible (usually ~9:16)
@@ -39,7 +41,7 @@ export interface FormatFilter {
    * @example
    * ```ts
    * const screen = Dimensions.get('screen')
-   * targetPhotoAspectRatio: screen.width / screen.height
+   * targetPhotoAspectRatio: screen.height / screen.width
    * ```
    */
   photoAspectRatio?: number;

package/src/index.ts

@@ -12,6 +12,7 @@ export * from './VideoFile';
 
 export * from './devices/getCameraFormat';
 export * from './devices/getCameraDevice';
+export * from './devices/Templates';
 
 export * from './hooks/useCameraDevice';
 export * from './hooks/useCameraDevices';