demo: Face blur example

.github/workflows/build-android.yml

@@ -96,8 +96,8 @@ jobs:
         run: yarn install --frozen-lockfile
       - name: Install node_modules for example/
         run: yarn install --frozen-lockfile --cwd example
-      - name: Remove react-native-worklets-core
-        run: yarn remove react-native-worklets-core --cwd example
+      - name: Remove worklets, skia and reanimated
+        run: yarn remove react-native-worklets-core @shopify/react-native-skia react-native-reanimated --cwd ..
 
       - name: Restore Gradle cache
         uses: actions/cache@v4

.github/workflows/build-ios.yml

@@ -98,8 +98,8 @@ jobs:
             ${{ runner.os }}-yarn-
       - name: Install node_modules for example/
         run: yarn install --frozen-lockfile --cwd ..
-      - name: Remove react-native-worklets-core
-        run: yarn remove react-native-worklets-core --cwd ..
+      - name: Remove worklets, skia and reanimated
+        run: yarn remove react-native-worklets-core @shopify/react-native-skia react-native-reanimated --cwd ..
 
       - name: Restore buildcache
         uses: mikehardy/buildcache-action@v2

docs/docs/guides/EXPOSURE.mdx

@@ -16,9 +16,9 @@ Values for the `exposure` prop range from [`device.minExposure`](/docs/api/inter
 
 Instead of manually adjusting ISO and Exposure-Duration, this acts as an "exposure compensation bias", meaning the Camera will still continuously automatically adjust exposure as it goes, but premultiplies the given exposure value to it's ISO and Exposure Duration settings.
 
-### Examples
-
-![Exposure Example (-2, 0, 2)](/img/exposure.jpg)
+|              `exposure={-2}`               |                  `exposure={0}`                 |               `exposure={2}`               |
+|--------------------------------------------|-------------------------------------------------|--------------------------------------------|
+| ![Exposure -2](/img/exposure-negative.jpg) | ![Exposure Neutral](/img/exposure-neutral.jpg)  |   ![Exposure +2](/img/exposure-plus.jpg)   |
 
 ### Animating
 

docs/docs/guides/FORMATS.mdx

@@ -42,7 +42,6 @@ To get all available formats, simply use the `CameraDevice`'s [`formats` propert
 - [`videoHeight`](/docs/api/interfaces/CameraDeviceFormat#videoheight)/[`videoWidth`](/docs/api/interfaces/CameraDeviceFormat#videoWidth): The resolution that will be used for recording videos and streaming into frame processors. This also affects the preview's aspect ratio. Choose a format with your desired resolution.
 - [`minFps`](/docs/api/interfaces/CameraDeviceFormat#minfps)/[`maxFps`](/docs/api/interfaces/CameraDeviceFormat#maxfps): A range of possible values for the `fps` property. For example, if your format has `minFps: 1` and `maxFps: 60`, you can either use `fps={30}`, `fps={60}` or any other value in between for recording videos and streaming into frame processors.
 - [`videoStabilizationModes`](/docs/api/interfaces/CameraDeviceFormat#videostabilizationmodes): All supported Video Stabilization Modes, digital and optical. If this specific format contains your desired [`VideoStabilizationMode`](/docs/api/#videostabilizationmode), you can pass it to your `<Camera>` via the [`videoStabilizationMode` property](/docs/api/interfaces/CameraProps#videoStabilizationMode).
-- [`pixelFormats`](/docs/api/interfaces/CameraDeviceFormat#pixelformats): All supported Pixel Formats. If this specific format contains your desired [`PixelFormat`](/docs/api/#PixelFormat), you can pass it to your `<Camera>` via the [`pixelFormat` property](/docs/api/interfaces/CameraProps#pixelFormat).
 - [`supportsVideoHdr`](/docs/api/interfaces/CameraDeviceFormat#supportsvideohdr): Whether this specific format supports true 10-bit HDR for video capture. If this is `true`, you can enable `videoHdr` on your `<Camera>`.
 - [`supportsPhotoHdr`](/docs/api/interfaces/CameraDeviceFormat#supportsphotohdr): Whether this specific format supports HDR for photo capture. It will use multiple captures to fuse over-exposed and under-exposed Images together to form one HDR photo. If this is `true`, you can enable `photoHdr` on your `<Camera>`.
 - [`supportsDepthCapture`](/docs/api/interfaces/CameraDeviceFormat#supportsdepthcapture): Whether this specific format supports depth data capture. For devices like the TrueDepth/LiDAR cameras, this will always be true.
@@ -213,4 +212,4 @@ Other props that depend on the `format`:
 
 <br />
 
-#### 🚀 Next section: [Taking Photos](./taking-photos)
+#### 🚀 Next section: [Preview](./preview)

docs/docs/guides/FRAME_PROCESSORS.mdx

@@ -245,7 +245,7 @@ Check out [Frame Processor community plugins](/docs/guides/frame-processor-plugi
 When running frame processors, it is often important to choose an appropriate [format](/docs/guides/formats). Here are some general tips to consider:
 
 * If you are running heavy AI/ML calculations in your frame processor, make sure to [select a format](/docs/guides/formats) that has a lower resolution to optimize it's performance. You can also resize the Frame on-demand.
-* Sometimes a frame processor plugin only works with specific [pixel formats](/docs/api/interfaces/CameraDeviceFormat#pixelformats). Some plugins (like Tensorflow Lite Models) don't work with `yuv`, so use a [`pixelFormat`](/docs/api/interfaces/CameraProps#pixelformat) of `rgb` instead.
+* Sometimes a frame processor plugin only works with specific [pixel format](/docs/guides/pixel-formats). Some plugins (like Tensorflow Lite Models) don't work with `yuv`, so use a [`pixelFormat`](/docs/api/interfaces/CameraProps#pixelformat) of `rgb` instead.
 * Some Frame Processor plugins don't work with HDR formats. In this case you need to disable [`videoHdr`](/docs/api/interfaces/CameraProps#videohdr).
 
 ## Benchmarks

docs/docs/guides/FRAME_PROCESSORS_CREATE_OVERVIEW.mdx

@@ -54,7 +54,7 @@ Return values will automatically be converted to JS values, assuming they are re
 ```java
 @Nullable
 @Override
-public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) {
+public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) throws Throwable {
   return "cat";
 }
 ```
@@ -74,7 +74,7 @@ You can also manipulate the buffer and return it (or a copy of it) by returning
 ```java
 @Nullable
 @Override
-public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) {
+public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) throws Throwable {
   Frame resizedFrame = new Frame(/* ... */);
   return resizedFrame;
 }
@@ -112,11 +112,11 @@ To let the user know that something went wrong you can use Exceptions:
 ```java
 @Nullable
 @Override
-public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) {
+public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) throws Throwable {
   if (arguments != null && arguments.get("codeType") instanceof String) {
     // ...
   } else {
-    throw new Exception("codeType property has to be a string!");
+    throw new RuntimeException("codeType property has to be a string!");
   }
 }
 ```
@@ -149,7 +149,7 @@ For example, a realtime video chat application might use WebRTC to send the fram
 ```java
 @Nullable
 @Override
-public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) {
+public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) throws Throwable {
   if (arguments == null) {
     return null;
   }

docs/docs/guides/FRAME_PROCESSOR_CREATE_PLUGIN_ANDROID.mdx

@@ -67,7 +67,7 @@ public class FaceDetectorFrameProcessorPlugin extends FrameProcessorPlugin {
 
   @Nullable
   @Override
-  public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) {
+  public Object callback(@NonNull Frame frame, @Nullable Map<String, Object> arguments) throws Throwable {
 // highlight-next-line
     // code goes here
     return null;

docs/docs/guides/LOCATION.mdx

@@ -0,0 +1,138 @@
+---
+id: location
+title: GPS Location Tags
+sidebar_label: GPS Location Tags
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl'
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+<div class="image-container">
+  <img width="283" src={useBaseUrl("img/location.png")} />
+</div>
+
+## What are GPS Location Tags?
+
+GPS Location Tags are location properties stored in image files (via EXIF tags) or video files (via QuickTime/MP4 tags).
+
+VisionCamera provides an API to easily add such location tags to captured photos or videos.
+
+### Configure Location Permissions
+
+First, you need to add the required permissions to access the user's location:
+
+<Tabs
+  groupId="environment"
+  defaultValue="rn"
+  values={[
+    {label: 'React Native', value: 'rn'},
+    {label: 'Expo', value: 'expo'}
+  ]}>
+<TabItem value="rn">
+
+### iOS
+
+Open your project's `Info.plist` and add the following lines inside the outermost `<dict>` tag:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>$(PRODUCT_NAME) needs access to your location.</string>
+```
+
+### Android
+
+Open your project's `AndroidManifest.xml` and add the following lines inside the `<manifest>` tag:
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+```
+
+</TabItem>
+
+<TabItem value="expo">
+
+### Managed Expo
+
+Enable the `enableLocation` property inside your app's Expo config (`app.json`, `app.config.json` or `app.config.js`):
+
+```json
+{
+  "name": "my app",
+  "plugins": [
+    [
+      "react-native-vision-camera",
+      {
+        // ...
+        "enableLocation": true,
+        "locationPermissionText": "[my app] needs your location."
+      }
+    ]
+  ]
+}
+```
+
+Finally, compile the mods:
+
+```bash
+npx expo prebuild
+```
+
+To apply the changes, build a new binary with EAS:
+
+```bash
+eas build
+```
+
+</TabItem>
+</Tabs>
+
+### Request Location Permissions
+
+After adding the required permissions to your app's manifests, prompt the user to grant location permission at runtime:
+
+<Tabs
+  groupId="component-style"
+  defaultValue="hooks"
+  values={[
+    {label: 'Hooks API', value: 'hooks'},
+    {label: 'Imperative API', value: 'imperative'}
+  ]}>
+<TabItem value="hooks">
+
+Get or request permissions using the [`useLocationPermission`](/docs/api/#uselocationpermission) hook:
+
+```tsx
+const { hasPermission, requestPermission } = useLocationPermission()
+```
+
+</TabItem>
+<TabItem value="imperative">
+
+Get the current permission status:
+
+```ts
+const permissionStatus = Camera.getLocationPermissionStatus()
+```
+
+And if it is not `granted`, request permission:
+
+```ts
+const newPermissionStatus = await Camera.requestLocationPermission()
+```
+
+</TabItem>
+</Tabs>
+
+### Enable GPS Location Tags
+
+Use the [`enableLocation`](/docs/api/interfaces/CameraProps#enablelocation) property to start streaming location updates and automatically add GPS Location Tags to images (EXIF tags) and videos:
+
+```tsx
+<Camera {...props} enableLocation={true} />
+```
+
+Once enabled, all captured photos (see ["Taking Photos"](taking-photos)) and videos (see ["Recording Videos"](recording-videos)) will contain location tags.
+
+
+#### 🚀 Next section: [Performance](performance)

docs/docs/guides/PERFORMANCE.mdx

@@ -98,11 +98,19 @@ The [`isActive`](/docs/api/interfaces/CameraProps#isactive) prop controls whethe
 
 ### Fast Photos
 
-If you need to take photos as fast as possible, use a [`qualityPrioritization`](/docs/api/interfaces/TakePhotoOptions#qualityprioritization) of `'speed'` to speed up the photo pipeline:
+If you need to take photos as fast as possible, use a [`qualityBalance`](/docs/api/interfaces/CameraProps#qualitybalance) of `'speed'` to speed up the photo pipeline:
+
+```jsx
+return <Camera {...props} qualityBalance="speed" />
+```
+
+### Snapshot Capture
+
+If photo capture is still too slow for your use-case, consider [taking snapshots](/docs/guides/taking-photos#taking-snapshots) instead:
 
 ```ts
-camera.current.takePhoto({
-  qualityPrioritization: 'speed'
+const snapshot = await camera.current.takeSnapshot({
+  quality: 85
 })
 ```
 

docs/docs/guides/PIXEL_FORMATS.mdx

@@ -12,7 +12,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'
 
 A Camera's video pipeline operates in a specific pixel format which specifies how the pixels are laid out in a memory buffer.
 
-If you are simply recording videos (`video={true}`), the most efficient pixel format (`native`) will be automatically chosen for you, and [buffer compression](/docs/guides/performance#buffer-compression) will be enabled if available.
+If you are simply recording videos (`video={true}`), the most efficient pixel format will be automatically chosen for you, and [buffer compression](/docs/guides/performance#buffer-compression) will be enabled if available.
 
 If you are using Frame Processors, it is important to understand what pixel format you are using.
 
@@ -26,46 +26,31 @@ Cameras however don't operate in RGB, they use YUV instead. Instead of storing a
 YYYYUVYYYYUVYYYYUV
 ```
 
-In VisionCamera, pixel formats are abstracted under a simple [`PixelFormat`](/docs/api/#pixelformat) API with three possible values:
+In VisionCamera, pixel formats are abstracted under a simple [`PixelFormat`](/docs/api/#pixelformat) API with two possible values:
 
 - `yuv`: The YUV (often 4:2:0, 8-bit per channel) pixel format.
-- `native`: Whatever native format is most efficient, likely the same as YUV on iOS, but some PRIVATE format on Android.
 - `rgb`: An RGB (often BGRA, 8-bit per channel) pixel format.
 
-A [`CameraFormat`](/docs/api/interfaces/CameraDeviceFormat) specifies which pixel formats it can use for this specific configuration. For example, let's inspect the 4k Video format on an iPhone:
-
-```json
-// ...
-"pixelFormats": [
-  "yuv",
-  "rgb"
-]
-```
-
-This Format supports both YUV and RGB streaming, so we can configure the Camera to stream in RGB if we want:
+Every Camera device can either stream in `yuv` or `rgb`, but `rgb` comes with an additional overhead and sometimes even needs to be converted from `yuv` first.
 
 ```tsx
 function App() {
-  // ...
-  const format = ...
-  const pixelFormat = format.pixelFormats.includes("rgb") ? "rgb" : "native"
+  const frameProcessor = useFrameProcessor((frame) => {
+    'worklet'
+    console.log(frame.pixelFormat) // <-- "rgb"
+  }, [])
 
   return (
     <Camera
       style={StyleSheet.absoluteFill}
-      device={device}
-      format={format}
-      pixelFormat={pixelFormat}
+      pixelFormat="rgb"
+      frameProcessor={frameProcessor}
     />
   )
 }
 ```
 
-However this is not recommended, as YUV is much more efficient.
-
-On Android, only YUV and NATIVE (PRIVATE) are supported, as RGB requires explicit conversion.
-
-As a general tip, try to always use YUV, and stay away from RGB. If you have some specific models (e.g. Face Detectors), try converting them to YUV (4:2:0) instead of trying to run your Camera in RGB, as the conversion beforehand will be worth the effort.
+As a general tip, try to always use YUV if possible. If you have some specific models (e.g. Face Detectors), try converting them to YUV (4:2:0) instead of trying to run your Camera in RGB, as the conversion beforehand will be worth the effort.
 
 ### HDR
 

docs/docs/guides/PREVIEW.mdx

@@ -0,0 +1,53 @@
+---
+id: preview
+title: Preview
+sidebar_label: Preview
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
+<div class="image-container">
+  <svg xmlns="http://www.w3.org/2000/svg" width="283" height="535">
+    <image href={useBaseUrl("img/demo_capture.gif")} x="18" y="33" width="247" height="469" />
+    <image href={useBaseUrl("img/frame.png")} width="283" height="535" />
+  </svg>
+</div>
+
+## The Preview View
+
+The `<Camera>` React component renders a Preview view for the Camera.
+
+### FPS
+
+The Preview view is running at the same frame rate as the Video stream, configured by the [`fps`](/docs/api/interfaces/CameraProps#fps) prop, or 30 FPS by default.
+
+```tsx
+<Camera {...props} fps={60} />
+```
+
+### Resolution
+
+On iOS, the Video resolution also determines the Preview resolution, so if you Camera format has a low Video resolution, your Preview will also be in low resolution:
+
+```ts
+const lowResolutionFormat = useCameraFormat(device, [
+  { videoResolution: { width: 640, height: 480 } },
+])
+```
+
+On Android, the Preview will always be in full HD, or the Preview View's size, whichever is smaller.
+
+### Overlays and Masks
+
+On Android, the Preview View supports two implementation modes which are controllable through the [`androidPreviewViewType`](/docs/api/interfaces/CameraProps#androidpreviewviewtype) prop:
+
+- `"surface-view"`: Uses a [`SurfaceView`](https://developer.android.com/reference/android/view/SurfaceView) for rendering. This is more efficient and supports HDR rendering, but doesn't support masks, transparency, rotations or clipping.
+- `"texture-view"`: Uses a [`TextureView`](https://developer.android.com/reference/android/view/TextureView) for rendering. This is less efficient and doesn't support HDR rendering, but supports masks, transparency, rotations and clipping.
+
+```tsx
+<Camera {...props} androidPreviewViewType="texture-view" />
+```
+
+<br />
+
+#### 🚀 Next section: [Taking Photos](./taking-photos)