feat: Add onThumbnailReady callback for photo capture

Add support for generating thumbnails during photo capture with an
asynchronous callback that fires before the full photo is saved. This
enables instant preview functionality and better UX in camera
applications.

**Changes:**
- Add `thumbnailSize` and `onThumbnailReady` options to
  `TakePhotoOptions`
- Add `ThumbnailFile` type for thumbnail metadata
- iOS: Extract embedded thumbnail from AVCapturePhoto using ImageIO for
  maximum performance
- Android: Implement memory-efficient downsampling with
  hardware-accelerated decoding
- Add event bridge `onThumbnailReady` for both platforms
- Update documentation with usage examples and platform implementation
  details
- Add thumbnail display in example app

**Platform implementations:**
- iOS: Uses embedded thumbnail from camera capture if available
- Android: Uses BitmapFactory.Options.inSampleSize for efficient
  downsampling without loading full image into memory

Both implementations are asynchronous and non-blocking.

Tested on iPhone 14, iOS 18.6.2
Android implementation compiles successfully (needs device testing)

Author: MikaelAmborn

bun.lockb

@@ -81,6 +81,40 @@ const photo = await camera.current.takePhoto({
 
 Note that flash is only available on camera devices where [`hasFlash`](/docs/api/interfaces/CameraDevice#hasflash) is `true`; for example most front cameras don't have a flash.
 
+### Thumbnail Generation
+
+For a better user experience, you can generate a low-resolution thumbnail that loads while the full photo is being processed and saved. This is especially useful for displaying a preview in your UI without waiting for the full-resolution image.
+
+To generate a thumbnail, provide the [`thumbnailSize`](/docs/api/interfaces/TakePhotoOptions#thumbnailsize) and [`onThumbnailReady`](/docs/api/interfaces/TakePhotoOptions#onthumbnailready) options:
+
+```tsx
+const photo = await camera.current.takePhoto({
+  thumbnailSize: { width: 200, height: 200 },
+  onThumbnailReady: (thumbnail) => {
+    // Thumbnail is ready! Display it immediately
+    setThumbnailUri(`file://${thumbnail.path}`)
+  }
+})
+
+// Full photo is now ready
+setPhotoUri(`file://${photo.path}`)
+```
+
+The `onThumbnailReady` callback is invoked as soon as the thumbnail is generated, which typically happens before the full photo is saved. This allows you to:
+- Display a preview to the user immediately
+- Show a loading state with the thumbnail while uploading the full image
+- Reduce memory usage by rendering thumbnails in lists instead of full photos
+
+**Platform implementations:**
+- **iOS**: Uses the embedded thumbnail from the camera capture if available for maximum performance
+- **Android**: Uses memory-efficient downsampling with hardware-accelerated decoding (never loads the full image into memory)
+
+Both implementations are optimized for their respective platforms and generate thumbnails asynchronously without blocking photo capture.
+
+:::tip
+The thumbnail is stored in a temporary directory just like the main photo. Remember to clean up temporary files when you're done with them.
+:::
+
 ### Photo Quality Balance
 
 The photo capture pipeline can be configured to prioritize speed over quality, quality over speed or balance both quality and speed using the [`photoQualityBalance`](/docs/api/interfaces/CameraProps#photoQualityBalance) prop.

docs/docs/guides/TAKING_PHOTOS.mdx

@@ -1768,16 +1768,16 @@ PODS:
     - ReactCommon/turbomodule/core
     - Yoga
   - SocketRocket (0.7.0)
-  - VisionCamera (4.6.3):
-    - VisionCamera/Core (= 4.6.3)
-    - VisionCamera/FrameProcessors (= 4.6.3)
-    - VisionCamera/React (= 4.6.3)
-  - VisionCamera/Core (4.6.3)
-  - VisionCamera/FrameProcessors (4.6.3):
+  - VisionCamera (4.8.6):
+    - VisionCamera/Core (= 4.8.6)
+    - VisionCamera/FrameProcessors (= 4.8.6)
+    - VisionCamera/React (= 4.8.6)
+  - VisionCamera/Core (4.8.6)
+  - VisionCamera/FrameProcessors (4.8.6):
     - React
     - React-callinvoker
     - react-native-worklets-core
-  - VisionCamera/React (4.6.3):
+  - VisionCamera/React (4.8.6):
     - React-Core
     - VisionCamera/FrameProcessors
   - Yoga (0.0.0)
@@ -2029,77 +2029,77 @@ SPEC CHECKSUMS:
   hermes-engine: ea92f60f37dba025e293cbe4b4a548fd26b610a0
   MMKV: f7d1d5945c8765f97f39c3d121f353d46735d801
   MMKVCore: c04b296010fcb1d1638f2c69405096aac12f6390
-  RCT-Folly: 4464f4d875961fce86008d45f4ecf6cef6de0740
+  RCT-Folly: 34124ae2e667a0e5f0ea378db071d27548124321
   RCTDeprecation: 726d24248aeab6d7180dac71a936bbca6a994ed1
   RCTRequired: a94e7febda6db0345d207e854323c37e3a31d93b
   RCTTypeSafety: 28e24a6e44f5cbf912c66dde6ab7e07d1059a205
   React: c2830fa483b0334bda284e46a8579ebbe0c5447e
   React-callinvoker: 4aecde929540c26b841a4493f70ebf6016691eb8
-  React-Core: 9c059899f00d46b5cec3ed79251f77d9c469553d
-  React-CoreModules: 9fac2d31803c0ed03e4ddaa17f1481714f8633a5
-  React-cxxreact: a979810a3ca4045ceb09407a17563046a7f71494
+  React-Core: 32a581847d74ce9b5f51d9d11a4e4d132ad61553
+  React-CoreModules: f53e0674e1747fa41c83bc970e82add97b14ad87
+  React-cxxreact: 86f3b1692081fd954a0cb27cc90d14674645b64b
   React-debug: 3d21f69d8def0656f8b8ec25c0f05954f4d862c5
-  React-defaultsnativemodule: 2fa2bdb7bd03ff9764facc04aa8520ebf14febae
-  React-domnativemodule: 986e6fe7569e1383dce452a7b013b6c843a752df
-  React-Fabric: 3bc7be9e3a6b7581fc828dc2aa041e107fc8ffb8
-  React-FabricComponents: 668e0cb02344c2942e4c8921a643648faa6dc364
-  React-FabricImage: 3f44dd25a2b020ed5215d4438a1bb1f3461cd4f1
+  React-defaultsnativemodule: 2ed121c5a1edeab09cff382b8d9b538260f07848
+  React-domnativemodule: 4393dd5dd7e13dbe42e69ebc791064a616990f91
+  React-Fabric: cbf38ceefb1ac6236897abdb538130228e126695
+  React-FabricComponents: dd4b01c4a60920d8dc15f3b5594c6fe9e7648a38
+  React-FabricImage: 8b13aedfbd20f349b9b3314baf993c71c02995d9
   React-featureflags: ee1abd6f71555604a36cda6476e3c502ca9a48e5
-  React-featureflagsnativemodule: 7ccc0cd666c2a6257401dceb7920818ac2b42803
-  React-graphics: d7dd9c8d75cad5af19e19911fa370f78f2febd96
-  React-hermes: 2069b08e965e48b7f8aa2c0ca0a2f383349ed55d
-  React-idlecallbacksnativemodule: e211b2099b6dced97959cb58257bab2b2de4d7ef
-  React-ImageManager: ab7a7d17dd0ff1ef1d4e1e88197d1119da9957ce
-  React-jserrorhandler: d9e867bb83b868472f3f7601883f0403b3e3942d
-  React-jsi: d68f1d516e5120a510afe356647a6a1e1f98f2db
-  React-jsiexecutor: 6366a08a0fc01c9b65736f8deacd47c4a397912a
-  React-jsinspector: 0ac947411f0c73b34908800cc7a6a31d8f93e1a8
-  React-jsitracing: 0e8c0aadb1fcec6b1e4f2a66ee3b0da80f0f8615
-  React-logger: d79b704bf215af194f5213a6b7deec50ba8e6a9b
-  React-Mapbuffer: b982d5bba94a8bc073bda48f0d27c9b28417fae3
-  React-microtasksnativemodule: 2b73e68f0462f3175f98782db08896f8501afd20
-  react-native-blur: a1bf334589f44658a58a859b1f3defe28e367fcf
-  react-native-cameraroll: b3395629565d1663b4f340c7314e7c04e88c9b3c
-  react-native-mmkv: 7d0b6c2a79e73100b933f2947a9c8741d664e18b
-  react-native-safe-area-context: 5141f11858b033636f1788b14f32eaba92cee810
-  react-native-skia: 8cbbeae25285ade497b646696103832e67ffd64b
-  react-native-video: 155a792d16b64f1fb68b1795d805808f34e60488
-  react-native-worklets-core: f51430dd07bf5343d4918d28a4bb00fe8f98b982
+  React-featureflagsnativemodule: 87b58caf3cd8eca1e53179453789def019af2a65
+  React-graphics: f5c4cf3abc5aa083e28fe7a866bd95fb3bbbc1e0
+  React-hermes: cad69ee9a53870cc38e5386889aa7ea81c75b6a1
+  React-idlecallbacksnativemodule: 445390be0f533797ace18c419eb57110dbfe90d6
+  React-ImageManager: cb78d7a24f45f8f9a5a1640b52fce4c9f637f98d
+  React-jserrorhandler: dfe9b96e99a93d4f4858bad66d5bc4813a87a21a
+  React-jsi: bc1f6073e203fb540edd6d26f926ad041809b443
+  React-jsiexecutor: 1e8fc70dd9614c3e9d5c3c876b2ea3cd1d931ee4
+  React-jsinspector: 7544a20e9beac390f1b65d9f0040d97cd55dc198
+  React-jsitracing: cac972ccc097db399df8044e49add8e5b25cb34a
+  React-logger: 80d87daf2f98bf95ab668b79062c1e0c3f0c2f8a
+  React-Mapbuffer: acffb35a53a5f474ede09f082ac609b41aafab2e
+  React-microtasksnativemodule: 71ca9282bce93b319218d75362c0d646b376eb43
+  react-native-blur: 3d5dd1ed2dd810b304ac3bcee9cf7d460757c89b
+  react-native-cameraroll: 418588be23947285410dd3fc72f0fd07271d87a3
+  react-native-mmkv: f84bf6f48c906911695f9cd16d39d4fb78fcd5a4
+  react-native-safe-area-context: 17a482f540310e2209f884fd49472d9e1c0e73d6
+  react-native-skia: 08ff502bcedd2ff2a5f5896debc3d7b4c773d312
+  react-native-video: f93e7e72f773181440d1acaf6186b369447ff30a
+  react-native-worklets-core: f730c01db8ea3d580e322617f4a631206f1905fb
   React-nativeconfig: 8c83d992b9cc7d75b5abe262069eaeea4349f794
-  React-NativeModulesApple: 9f7920224a3b0c7d04d77990067ded14cee3c614
+  React-NativeModulesApple: 97f606f09fd9840b3868333984d6a0e7bcc425b5
   React-perflogger: 59e1a3182dca2cee7b9f1f7aab204018d46d1914
-  React-performancetimeline: a9d05533ff834c6aa1f532e05e571f3fd2e3c1ed
+  React-performancetimeline: 3e3f5c5576fe1cc2dd5fcfb1ae2046d5dceda3d7
   React-RCTActionSheet: d80e68d3baa163e4012a47c1f42ddd8bcd9672cc
-  React-RCTAnimation: bde981f6bd7f8493696564da9b3bd05721d3b3cc
-  React-RCTAppDelegate: 0176615c51476c88212bf3edbafb840d39ea7631
-  React-RCTBlob: 520a0382bf8e89b9153d60e3c6293e51615834e9
-  React-RCTFabric: c9da097b19b30017a99498b8c66a69c72f3ce689
-  React-RCTImage: 90448d2882464af6015ed57c98f463f8748be465
-  React-RCTLinking: 1bd95d0a704c271d21d758e0f0388cced768d77d
-  React-RCTNetwork: 218af6e63eb9b47935cc5a775b7a1396cf10ff91
-  React-RCTSettings: e10b8e42b0fce8a70fbf169de32a2ae03243ef6b
-  React-RCTText: e7bf9f4997a1a0b45c052d4ad9a0fe653061cf29
-  React-RCTVibration: 5b70b7f11e48d1c57e0d4832c2097478adbabe93
+  React-RCTAnimation: 051f0781709c5ed80ba8aa2b421dfb1d72a03162
+  React-RCTAppDelegate: 106d225d076988b06aa4834e68d1ab754f40cacf
+  React-RCTBlob: 895eaf8bca2e76ee1c95b479235c6ccebe586fc6
+  React-RCTFabric: 8d01df202ee9e933f9b5dd44b72ec89a7ac6ee01
+  React-RCTImage: b73149c0cd54b641dba2d6250aaf168fee784d9f
+  React-RCTLinking: 23e519712285427e50372fbc6e0265d422abf462
+  React-RCTNetwork: a5d06d122588031989115f293654b13353753630
+  React-RCTSettings: 87d03b5d94e6eadd1e8c1d16a62f790751aafb55
+  React-RCTText: 75e9dd39684f4bcd1836134ac2348efaca7437b3
+  React-RCTVibration: 033c161fe875e6fa096d0d9733c2e2501682e3d4
   React-rendererconsistency: f620c6e003e3c4593e6349d8242b8aeb3d4633f0
-  React-rendererdebug: e697680f4dd117becc5daf9ea9800067abcee91c
+  React-rendererdebug: 5be7b834677b2a7a263f4d2545f0d4966cafad82
   React-rncore: c22bd84cc2f38947f0414fab6646db22ff4f80cd
-  React-RuntimeApple: de0976836b90b484305638616898cbc665c67c13
-  React-RuntimeCore: 3c4a5aa63d9e7a3c17b7fb23f32a72a8bcfccf57
+  React-RuntimeApple: 71160e6c02efa07d198b84ef5c3a52a7d9d0399d
+  React-RuntimeCore: f88f79ec995c12af56a265d7505c7630733d9d82
   React-runtimeexecutor: ea90d8e3a9e0f4326939858dafc6ab17c031a5d3
-  React-RuntimeHermes: c6b0afdf1f493621214eeb6517fb859ce7b21b81
-  React-runtimescheduler: 84f0d876d254bce6917a277b3930eb9bc29df6c7
-  React-utils: cbe8b8b3d7b2ac282e018e46f0e7b25cdc87c5a0
-  ReactCodegen: d81fb52765155a5a3c41465e71ee547ce2bc1b7a
-  ReactCommon: 6a952e50c2a4b694731d7682aaa6c79bc156e4ad
-  RNGestureHandler: 6dfe7692a191ee224748964127114edf057a1475
-  RNReanimated: 5281007b55b4a8e6772de98803a9c925587e9c64
-  RNScreens: 19719a9c326e925498ac3b2d35c4e50fe87afc06
-  RNStaticSafeAreaInsets: 055ddbf5e476321720457cdaeec0ff2ba40ec1b8
-  RNVectorIcons: 6382277afab3c54658e9d555ee0faa7a37827136
+  React-RuntimeHermes: 49f86328914021f50fd5a5b9756685f5f6d8b4da
+  React-runtimescheduler: fed70991b942c6df752a59a22081e45fc811b11c
+  React-utils: 02526ea15628a768b8db9517b6017a1785c734d2
+  ReactCodegen: 9f910fe2030dfaf3803d227988f56fb60f6cd0e0
+  ReactCommon: 36d48f542b4010786d6b2bcee615fe5f906b7105
+  RNGestureHandler: d21c9c1cc8b1bb19336d2e1bc48e56882bd13bc6
+  RNReanimated: b900d6a958fe030855e80c3e6df7d9dab60975a4
+  RNScreens: 28fbd73104cc9719371da9d9aaa3c70d876a8c6b
+  RNStaticSafeAreaInsets: 4696b82d3a11ba6f3a790159ddb7290f04abd275
+  RNVectorIcons: 182892e7d1a2f27b52d3c627eca5d2665a22ee28
   SocketRocket: abac6f5de4d4d62d24e11868d7a2f427e0ef940d
-  VisionCamera: 88df4dae7196c93ecd331f105f0e5d7d95702cb3
-  Yoga: aa3df615739504eebb91925fc9c58b4922ea9a08
+  VisionCamera: 49ac44838511c7db34fcd654f191a542534e07ae
+  Yoga: 055f92ad73f8c8600a93f0e25ac0b2344c3b07e6
 
 PODFILE CHECKSUM: 2ad84241179871ca890f7c65c855d117862f1a68
 
-COCOAPODS: 1.15.2
+COCOAPODS: 1.16.2

example/ios/Podfile.lock

@@ -4,7 +4,7 @@ import type { GestureResponderEvent } from 'react-native'
 import { StyleSheet, Text, View } from 'react-native'
 import type { PinchGestureHandlerGestureEvent } from 'react-native-gesture-handler'
 import { PinchGestureHandler, TapGestureHandler } from 'react-native-gesture-handler'
-import type { CameraProps, CameraRuntimeError, PhotoFile, VideoFile } from 'react-native-vision-camera'
+import type { CameraProps, CameraRuntimeError, PhotoFile, ThumbnailFile, VideoFile } from 'react-native-vision-camera'
 import {
   runAtTargetFps,
   useCameraDevice,
@@ -55,6 +55,7 @@ export function CameraPage({ navigation }: Props): React.ReactElement {
   const [enableHdr, setEnableHdr] = useState(false)
   const [flash, setFlash] = useState<'off' | 'on'>('off')
   const [enableNightMode, setEnableNightMode] = useState(false)
+  const [thumbnail, setThumbnail] = useState<ThumbnailFile | null>(null)
 
   // camera device settings
   const [preferredDevice] = usePreferredCameraDevice()
@@ -112,12 +113,15 @@ export function CameraPage({ navigation }: Props): React.ReactElement {
   const onMediaCaptured = useCallback(
     (media: PhotoFile | VideoFile, type: 'photo' | 'video') => {
       console.log(`Media captured! ${JSON.stringify(media)}`)
+      console.log(`Thumbnail: ${JSON.stringify(thumbnail)}`)
+      console.log(new Date())
       navigation.navigate('MediaPage', {
         path: media.path,
         type: type,
+        thumbnail: thumbnail,
       })
     },
-    [navigation],
+    [navigation, thumbnail],
   )
   const onFlipCameraPressed = useCallback(() => {
     setCameraPosition((p) => (p === 'back' ? 'front' : 'back'))
@@ -178,6 +182,15 @@ export function CameraPage({ navigation }: Props): React.ReactElement {
     location.requestPermission()
   }, [location])
 
+  const onThumbnailReady = useCallback(
+    (t: ThumbnailFile) => {
+      console.log(`=============thumbnail Ready=============\n${t.width}x${t.height}`)
+      console.log(new Date())
+      setThumbnail(t)
+    },
+    [setThumbnail],
+  )
+
   const frameProcessor = useFrameProcessor((frame) => {
     'worklet'
 
@@ -248,6 +261,7 @@ export function CameraPage({ navigation }: Props): React.ReactElement {
         flash={supportsFlash ? flash : 'off'}
         enabled={isCameraInitialized && isActive}
         setIsPressingButton={setIsPressingButton}
+        onThumbnailReady={onThumbnailReady}
       />
 
       <StatusBarBlurBackground />

example/src/CameraPage.tsx

@@ -33,7 +33,7 @@ const isVideoOnLoadEvent = (event: OnLoadData | OnLoadImage): event is OnLoadDat
 
 type Props = NativeStackScreenProps<Routes, 'MediaPage'>
 export function MediaPage({ navigation, route }: Props): React.ReactElement {
-  const { path, type } = route.params
+  const { path, type, thumbnail } = route.params
   const [hasMediaLoaded, setHasMediaLoaded] = useState(false)
   const isForeground = useIsForeground()
   const isScreenFocused = useIsFocused()
@@ -85,7 +85,10 @@ export function MediaPage({ navigation, route }: Props): React.ReactElement {
   return (
     <View style={[styles.container, screenStyle]}>
       {type === 'photo' && (
-        <Image source={source} style={StyleSheet.absoluteFill} resizeMode="cover" onLoadEnd={onMediaLoadEnd} onLoad={onMediaLoad} />
+        <>
+          <Image source={source} style={StyleSheet.absoluteFill} resizeMode="cover" onLoadEnd={onMediaLoadEnd} onLoad={onMediaLoad} />
+          {thumbnail !== null && <Image source={{ uri: `file://${thumbnail.path}` }} style={styles.thumbnail} resizeMode="cover" />}
+        </>
       )}
       {type === 'video' && (
         <Video
@@ -152,4 +155,14 @@ const styles = StyleSheet.create({
     },
     textShadowRadius: 1,
   },
+  thumbnail: {
+    position: 'absolute',
+    right: SAFE_AREA_PADDING.paddingLeft,
+    bottom: SAFE_AREA_PADDING.paddingBottom,
+    width: 75,
+    height: 120,
+    borderRadius: 8,
+    borderWidth: 2,
+    borderColor: 'white',
+  },
 })

example/src/MediaPage.tsx

@@ -1,10 +1,13 @@
+import type { ThumbnailFile } from 'react-native-vision-camera'
+
 export type Routes = {
   PermissionsPage: undefined
   CameraPage: undefined
   CodeScannerPage: undefined
   MediaPage: {
     path: string
     type: 'video' | 'photo'
+    thumbnail: ThumbnailFile | null
   }
   Devices: undefined
 }

example/src/Routes.ts

@@ -15,7 +15,7 @@ import Reanimated, {
   useSharedValue,
   withRepeat,
 } from 'react-native-reanimated'
-import type { Camera, PhotoFile, VideoFile } from 'react-native-vision-camera'
+import type { Camera, PhotoFile, ThumbnailFile, VideoFile } from 'react-native-vision-camera'
 import { CAPTURE_BUTTON_SIZE, SCREEN_HEIGHT, SCREEN_WIDTH } from './../Constants'
 
 const START_RECORDING_DELAY = 200
@@ -24,7 +24,7 @@ const BORDER_WIDTH = CAPTURE_BUTTON_SIZE * 0.1
 interface Props extends ViewProps {
   camera: React.RefObject<Camera>
   onMediaCaptured: (media: PhotoFile | VideoFile, type: 'photo' | 'video') => void
-
+  onThumbnailReady: (thumbnail: ThumbnailFile) => void
   minZoom: number
   maxZoom: number
   cameraZoom: Reanimated.SharedValue<number>
@@ -46,6 +46,7 @@ const _CaptureButton: React.FC<Props> = ({
   enabled,
   setIsPressingButton,
   style,
+  onThumbnailReady,
   ...props
 }): React.ReactElement => {
   const pressDownDate = useRef<Date | undefined>(undefined)
@@ -59,15 +60,21 @@ const _CaptureButton: React.FC<Props> = ({
       if (camera.current == null) throw new Error('Camera ref is null!')
 
       console.log('Taking photo...')
+      console.log(new Date());
       const photo = await camera.current.takePhoto({
         flash: flash,
         enableShutterSound: false,
+        thumbnailSize: {
+          width: 300,
+          height: 300,
+        },
+        onThumbnailReady,
       })
       onMediaCaptured(photo, 'photo')
     } catch (e) {
       console.error('Failed to take photo!', e)
     }
-  }, [camera, flash, onMediaCaptured])
+  }, [camera, flash, onMediaCaptured, onThumbnailReady])
 
   const onStoppedRecording = useCallback(() => {
     isRecording.current = false