railbird/react-native-vision-camera
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move Guides to docs/guides directory (#96)

Browse Source 
* Move Guides to docs/guides directory

* Rename sidebar

* Fix api/ links

* Update SETUP.mdx
This commit is contained in:
Marc Rousavy
2021-03-23 15:25:27 +01:00
committed by GitHub
parent a17d6a53d3
commit 48821d50ca
18 changed files with 62 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/docs/guides/ANIMATED.mdx Normal file
View File

@@ -0,0 +1,85 @@
---
id: animated
title: Zooming with Reanimated
sidebar_label: Zooming with Reanimated
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<svg xmlns="http://www.w3.org/2000/svg" width="283" height="535" style={{ float: 'right' }}>
<image href={useBaseUrl("img/demo.gif")} x="18" y="33" width="247" height="469" />
<image href={useBaseUrl("img/frame.png")} width="283" height="535" />
</svg>
</div>
## Animations
Often you'd want to animate specific props in the Camera. For example, if you'd want to create a custom zoom gesture, you can smoothly animate the Camera's `zoom` property.
Note: The `<Camera>` component does provide a natively implemented zoom gesture which you can enable with the `enableZoomGesture={true}` prop. This does not require any additional work, but if you want to setup a custom gesture, such as the one in Snapchat or Instagram where you move up your finger while recording, continue reading.
### Installing reanimated
The following example uses [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) (v2) to animate the `zoom` property. Head over to their [Installation guide](https://docs.swmansion.com/react-native-reanimated/docs/installation) to install Reanimated if you haven't already.
### Implementation
```tsx
import Reanimated, {
useAnimatedProps,
useSharedValue,
withSpring,
} from "react-native-reanimated"
const ReanimatedCamera = Reanimated.createAnimatedComponent(Camera)
Reanimated.addWhitelistedNativeProps({
zoom: true,
})
export function App() {
const devices = useCameraDevices()
const device = devices.back
const zoom = useSharedValue(0)
const onRandomZoomPress = useCallback(() => {
zoom.value = withSpring(Math.random())
}, [])
const animatedProps = useAnimatedProps<Partial<CameraProps>>(
() => ({ zoom: zoom.value }),
[zoom]
)
if (device == null) return <LoadingView />
return (
<>
<ReanimatedCamera
style={StyleSheet.absoluteFill}
device={device}
isActive={true}
animatedProps={animatedProps}
/>
<TouchableOpacity
style={styles.zoomButton}
onPress={onRandomZoomPress}>
<Text>Zoom randomly!</Text>
</TouchableOpacity>
</>
)
}
```
### Explanation
1. The `Camera` is converted to a reanimated Camera using `Reanimated.createAnimatedComponent`
2. The `zoom` property is added to the whitelisted native props to make it animatable.
> Note that this might not be needed in the future, see: [reanimated#1409](https://github.com/software-mansion/react-native-reanimated/pull/1409)
3. Using [`useSharedValue`](https://docs.swmansion.com/react-native-reanimated/docs/api/useSharedValue), we're creating a shared value that holds the `zoom` property.
4. Using the [`useAnimatedProps`](https://docs.swmansion.com/react-native-reanimated/docs/api/useAnimatedProps) hook, we apply the shared value to the animated props.
5. We apply the animated props to the `ReanimatedCamera` component's `animatedProps` property.
<br />
#### 🚀 Next section: [Camera Errors](errors)

116
docs/docs/guides/CAPTURING.mdx Normal file
View File

@@ -0,0 +1,116 @@
---
id: capturing
title: Taking Photos/Recording Videos
sidebar_label: Taking Photos/Recording Videos
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<svg xmlns="http://www.w3.org/2000/svg" width="283" height="535" style={{ float: 'right' }}>
<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>
## Camera Actions
The Camera provides certain actions using member functions which are available by using a [ref object](https://reactjs.org/docs/refs-and-the-dom.html):
```tsx
function App() {
const camera = useRef<Camera>(null)
// ...
return (
<Camera
ref={camera}
{...cameraProps}
/>
)
}
```
The most important actions are:
* [Taking Photos](#taking-photos)
- [Taking Snapshots](#taking-snapshots)
* [Recording Videos](#recording-videos)
* [Focussing](#focussing)
## Taking Photos
To take a photo, simply use the Camera's [`takePhoto(...)`](../api/classes/camera.camera-1#takephoto) function:
```ts
const photo = await camera.current.takePhoto({
flash: 'on'
})
```
You can customize capture options such as [automatic red-eye reduction](../api/interfaces/photofile.takephotooptions#enableautoredeyereduction), [automatic image stabilization](../api/interfaces/photofile.takephotooptions#enableautostabilization), [combining images from constituent physical camera devices](../api/interfaces/photofile.takephotooptions#enablevirtualdevicefusion) to create a single high quality fused image, [enable flash](../api/interfaces/photofile.takephotooptions#flash), [prioritize speed over quality](../api/interfaces/photofile.takephotooptions#qualityprioritization) and more using the `options` parameter. (See [`TakePhotoOptions`](../api/interfaces/photofile.takephotooptions))
This function returns a [`PhotoFile`](../api/interfaces/photofile.photofile-1) which contains a [`path`](../api/interfaces/photofile.photofile-1#path) property you can display in your App using an `<Image>` or `<FastImage>`.
:::note
This will change with the upcoming React Native Re-Architecture, so that instead of writing a temporary file which you have to read again, this function will immediately return an Image HostObject on which you can directly interop with the underlying `UIImage`/`Bitmap` for faster image capture. See [issue #69](https://github.com/cuvent/react-native-vision-camera/issues/69)
:::
### Taking Snapshots
Compared to iOS, Cameras on Android tend to be slower in image capture. If you care about speed, you can use the Camera's [`takeSnapshot(...)`](../api/classes/camera.camera-1#takesnapshot) function (Android only) which simply takes a snapshot of the Camera View instead of actually taking a photo through the Camera lens.
```ts
const snapshot = await camera.current.takeSnapshot({
quality: 85,
skipMetadata: true
})
```
:::note
While taking Snapshots is faster than taking Photos, the resulting image has way lower quality. You can combine both functions to create a Snapshot for presenting to the User at first, then deliver the actual Photo afterwards.
:::
## Recording Videos
To start a video recording, use the Camera's [`startRecording(...)`](../api/classes/camera.camera-1#startrecording) function:
```ts
camera.current.startRecording({
flash: 'on',
onRecordingFinished: (video) => console.log(video),
onRecordingError: (error) => console.error(error),
})
```
For any error that occured _while recording the video_, the `onRecordingError` callback will be invoked with a [`CaptureError`](../api/classes/cameraerror.cameracaptureerror) and the recording is therefore cancelled.
:::note
Due to limitations of the React Native Bridge, this function can not be awaited. This means, any errors thrown while trying to start the recording (e.g. `capture/recording-in-progress`) can only be caught synchronously (`isBlockingSynchronousMethod`). This will change with the upcoming React Native Re-Architecture.
:::
To stop the video recording, you can call [`stopRecording(...)`](../api/classes/camera.camera-1#stoprecording):
```ts
await camera.current.stopRecording()
```
Once a recording has been stopped, the `onRecordingFinished` callback passed to the `startRecording` function will be invoked with a [`VideoFile`](../api/interfaces/videofile.videofile-1) which you can then use to display in a [`<Video>`](https://github.com/react-native-video/react-native-video) component.
## Focussing
To focus the camera to a specific point, simply use the Camera's [`focus(...)`](../api/classes/camera.camera-1#focus) function:
```ts
await camera.current.focus({ x: tapEvent.x, y: tapEvent.y })
```
The focus function expects a [`Point`](../api/interfaces/point.point-1) parameter which represents the location relative to the Camera View where you want to focus the Camera to. If you use react-native-gesture-handler, this will consist of the [`x`](https://docs.swmansion.com/react-native-gesture-handler/docs/api/gesture-handlers/tap-gh#x) and [`y`](https://docs.swmansion.com/react-native-gesture-handler/docs/api/gesture-handlers/tap-gh#y) properties of the tap event payload.
So for example, `{ x: 0, y: 0 }` will focus to the upper left corner, while `{ x: CAM_WIDTH, y: CAM_HEIGHT }` will focus to the bottom right corner.
Focussing adjusts auto-focus (AF) and auto-exposure (AE).
<br />
#### 🚀 Next section: [Frame Processors](frame-processors)

134
docs/docs/guides/DEVICES.mdx Normal file
View File

@@ -0,0 +1,134 @@
---
id: devices
title: Camera Devices
sidebar_label: Camera Devices
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<svg xmlns="http://www.w3.org/2000/svg" width="283" height="535" style={{ float: 'right' }}>
<image href={useBaseUrl("img/demo.gif")} x="18" y="33" width="247" height="469" />
<image href={useBaseUrl("img/frame.png")} width="283" height="535" />
</svg>
</div>
### What are camera devices?
Camera devices are the physical (or "virtual") devices that can be used to record videos or capture photos.
* **Physical**: A physical camera device is a **camera lens on your phone**. Different physical camera devices have different specifications, such as different capture formats, field of views, focal lengths, and more. Some phones have multiple physical camera devices.
> Examples: _"Backside Wide-Angle Camera"_, _"Frontside Wide-Angle Camera (FaceTime HD)"_, _"Ultra-Wide-Angle back camera"_.
* **Virtual**: A virtual camera device is a **combination of one or more physical camera devices**, and provides features such as _virtual-device-switchover_ while zooming or _combined photo delivery_ from all physiscal cameras to produce higher quality images.
> Examples: _"Triple-Camera"_, _"Dual-Wide-Angle Camera"_
### Get available camera devices
To get a list of all available camera devices, use the `getAvailableCameraDevices` function:
```ts
const devices = await Camera.getAvailableCameraDevices()
```
:::note
See the [`CameraDevice` type](https://github.com/cuvent/react-native-vision-camera/blob/main/src/CameraDevice.ts) for more information about a Camera Device
:::
A camera device (`CameraDevice`) contains a list of physical device types this camera device consists of.
Example:
* For a single Wide-Angle camera, this would be `["wide-angle-camera"]`
* For a Triple-Camera, this would be `["wide-angle-camera", "ultra-wide-angle-camera", "telephoto-camera"]`
You can use the helper function `parsePhysicalDeviceTypes` to convert a list of physical devices to a single device descriptor type which can also describe virtual devices:
```ts
console.log(device.devices)
// --> ["wide-angle-camera", "ultra-wide-angle-camera", "telephoto-camera"]
const deviceType = parsePhysicalDeviceTypes(device.devices)
console.log(deviceType)
// --> "triple-camera"
```
The `CameraDevice` type also contains other useful information describing a camera device, such as `position` ("front", "back", ...), `hasFlash`, it's `formats` (See [Camera Formats](formats)), and more.
:::caution
Make sure to be careful when filtering out unneeded camera devices, since not every phone supports all camera device types. Some phones don't even have front-cameras. You always want to have a camera device, even when it's not the one that has the best features.
:::
### `useCameraDevices` hook
The react-native-vision-camera library provides a hook to make camera device selection a lot easier.
You can specify a device type to only find devices with the given type:
```tsx
function App() {
const devices = useCameraDevices('wide-angle-camera')
const device = devices.back
if (device == null) return <LoadingView />
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
/>
)
}
```
Or just return the "best matching camera device". This function prefers camera devices with more physical cameras, and always ranks "wide-angle" physical camera devices first.
> Example: `triple-camera` > `dual-wide-camera` > `dual-camera` > `wide-angle-camera` > `ultra-wide-angle-camera` > `telephoto-camera` > ...
```tsx
function App() {
const devices = useCameraDevices()
const device = devices.back
if (device == null) return <LoadingView />
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
/>
)
}
```
### The `isActive` prop
The Camera's `isActive` property can be used to _pause_ the session (`isActive={false}`) while still keeping the session "warm". This is more desirable than completely unmounting the camera, since _resuming_ the session (`isActive={true}`) will be **much faster** than re-mounting the camera view.
For example, you want to **pause the camera** when the user **navigates to another page** or **minimizes the app** since otherwise the camera continues to run in the background without the user seeing it, causing **siginificant battery drain**. Also, on iOS a green dot indicates the user that the camera is still active, possibly causing the user to raise privacy concerns. (🔗 See ["About the orange and green indicators in your iPhone status bar"](https://support.apple.com/en-us/HT211876))
This example demonstrates how you could pause the camera stream once the app goes into background using a custom `useIsAppForeground` hook:
```tsx
function App() {
const devices = useCameraDevices()
const device = devices.back
const isAppForeground = useIsAppForeground()
if (device == null) return <LoadingView />
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
isActive={isAppForeground}
/>
)
}
```
:::info
Note: If you don't care about fast resume times you can also fully unmount the `<Camera>` view instead, which will use a lot less memory (RAM).
:::
<br />
#### 🚀 Next section: [Camera Formats](formats)

100
docs/docs/guides/ERRORS.mdx Normal file
View File

@@ -0,0 +1,100 @@
---
id: errors
title: Camera Errors
sidebar_label: Camera Errors
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<img align="right" width="283" src={useBaseUrl("img/example_error.png")} />
</div>
## Why?
Since the Camera library is quite big, there is a lot that can "go wrong". The VisionCamera library provides thoroughly typed errors to help you quickly identify the cause and fix the problem.
```ts
switch (error.code) {
case "device/configuration-error":
// promt user
break
case "device/microphone-unavailable":
// ask for permission
break
case "capture/recording-in-progress":
// stop recording
break
default:
console.error(error)
break
}
```
## Troubleshooting
See [Troubleshooting](troubleshooting) if you're having "weird issues".
## The Error types
The `CameraError` type is a baseclass type for all other errors and provides the following properties:
* `code`: A typed code in the form of `{domain}/{code}` that can be used to quickly identify and group errors
* `message`: A non-localized message text that provides a more information and context about the error and possibly problematic values.
* `cause?`: An `ErrorWithCause` instance that provides information about the cause of the error. (Optional)
* `cause.message`: The message of the error that caused the camera error. This is localized on iOS.
* `cause.code?`: The native error's error-code. (iOS only)
* `cause.domain?`: The native error's domain. (iOS only)
* `cause.details?`: More dictionary-style information about the cause. (iOS only)
* `cause.stacktrace?`: A native Java stacktrace for the cause. (Android only)
* `cause.cause?`: The cause that caused this cause. (Recursive) (Optional)
:::note
See [the `CameraError.ts` file](https://github.com/cuvent/react-native-vision-camera/blob/main/src/CameraError.ts) for a list of all possible error codes
:::
### Runtime Errors
The `CameraRuntimeError` represents any kind of error that occured while mounting the Camera view, or an error that occured during the runtime.
The `<Camera />` UI Component provides an `onError` function that will be invoked every time an unexpected runtime error occured.
```tsx
function App() {
const onError = useCallback((error: CameraRuntimeError) => {
console.error(error)
}, [])
return <Camera onError={onError} {...cameraProps} />
}
```
### Capture Errors
The `CameraCaptureError` represents any kind of error that occured only while capturing a photo or recording a video.
```tsx
function App() {
const camera = useRef<Camera>(null)
// called when the user presses a "capture" button
const onPress = useCallback(() => {
try {
const photo = await camera.current.takePhoto()
} catch (e) {
if (e instanceof CameraCaptureError) {
switch (e.code) {
case "capture/file-io-error":
console.error("Failed to write photo to disk!")
break
default:
console.error(e)
break
}
}
}
}, [camera]);
return <Camera ref={camera} {...cameraProps} />
}
```

163
docs/docs/guides/FORMATS.mdx Normal file
View File

@@ -0,0 +1,163 @@
---
id: formats
title: Camera Formats
sidebar_label: Camera Formats
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<img align="right" width="283" src={useBaseUrl("img/example.png")} />
</div>
### What are camera formats?
Each camera device (see [Camera Devices](devices)) provides a number of capture formats that have different specifications. There are formats specifically designed for high-resolution photo capture, which have very high photo output quality but in return only support frame-rates of up to 30 FPS. On the other side, there might be formats that are designed for slow-motion video capture which have frame-rates up to 240 FPS.
### What if I don't want to choose a format?
If you don't want to specify the best format for your camera device, you don't have to. The Camera _automatically chooses the best matching format_ for the current camera device. This is why the Camera's `format` property is _optional_.
If you don't want to do a lot of filtering, but still want to let the camera know what your intentions are, you can use the Camera's `preset` property.
For example, use the `'medium'` preset if you want to create a video-chat application that shouldn't excessively use mobile data:
```tsx
function App() {
const devices = useCameraDevices()
const device = devices.back
if (device == null) return <LoadingView />
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
preset="medium"
/>
)
}
```
:::note
See the [CameraPreset.ts](https://github.com/cuvent/react-native-vision-camera/blob/main/src/CameraPreset.ts) type for more information about presets
:::
:::warning
You cannot set `preset` and `format` at the same time; if `format` is set, `preset` must be `undefined` and vice versa!
:::
### What you need to know about cameras
To understand a bit more about camera formats, you first need to understand a few "general camera basics":
* Each camera device is built differently, e.g. _Telephoto devices_ often don't provide frame-rates as high as _Wide-Angle devices_.
* Formats are designed for specific use-cases, so formats with high resolution photo output don't support frame-rates as high as formats with lower resolution.
* Different formats provide different field-of-views (FOV), maximum zoom factors, color spaces (iOS only), resolutions, frame rate ranges, and systems to assist with capture (auto-focus systems, video stabilization systems, ...)
### Get started
Each application has different needs, so the format filtering is up to you.
To get all available formats, simply use the `CameraDevice`'s `.formats` property. See how to get a camera device in the [Camera Devices guide](devices).
:::note
You can also manually get all camera devices and decide which device to use based on the available `formats`. In fact, this is how we do it in the [Cuvent](https://cuvent.com) app.
:::
This example shows how you would pick the format with the _highest frame rate_:
```tsx
function getMaxFps(format: CameraDeviceFormat): number {
return format.frameRateRanges.reduce((prev, curr) => {
if (curr.maxFrameRate > prev) return curr.maxFrameRate;
else return prev;
}, 0);
}
function App() {
const devices = useCameraDevices('wide-angle-camera')
const device = devices.back
const format = useMemo(() => {
return device?.formats.reduce((prev, curr) => {
if (prev == null) return curr;
if (getMaxFps(curr) > getMaxFps(prev)) return curr;
else return prev;
}, undefined);
}, [device?.formats]);
if (device == null) return <LoadingView />
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
format={format}
/>
)
}
```
Note that you don't want to simply pick the highest frame rate, as those formats often have incredibly low resolutions. You want to find a balance between high frame rate and high resolution, so instead you might want to use the `.sort` function.
### Sort
To sort your formats, create a custom comparator function which will be used as the `.sort` function's argument. The custom comparator then compares formats, preferring ones with higher frame rate AND higher resolution.
Implement this however you want, I personally use a "point-based system":
```ts
export const sortFormatsByResolution = (left: CameraDeviceFormat, right: CameraDeviceFormat): number => {
// in this case, points aren't "normalized" (e.g. higher resolution = 1 point, lower resolution = -1 points)
let leftPoints = left.photoHeight * left.photoWidth;
let rightPoints = right.photoHeight * right.photoWidth;
if (left.videoHeight != null && left.videoWidth != null && right.videoHeight != null && right.videoWidth != null) {
leftPoints += left.videoWidth * left.videoHeight;
rightPoints += right.videoWidth * right.videoHeight;
}
// you can also add points for FPS, etc
return rightPoints - leftPoints;
};
// and then call it:
const formats = useMemo(() => device?.formats.sort(sortFormatsByResolution), [device?.formats])
```
:::caution
Be careful that you don't `filter` out a lot of formats since you might end up having no format to use at all. (_Remember; not all devices support e.g. 240 FPS._) Always carefully sort instead of filter, and pick the best available format - that way you are guaranteed to have a format available, even if your desired specifications aren't fully met.
:::
### Props
The `Camera` View provides a few props that depend on the specified `format`. For example, you can only set the `fps` prop to a value that is supported by the current `format`. So if you have a format that supports 240 FPS, you can set the `fps` to `240`:
```tsx
function App() {
// ...
return (
<Camera
style={StyleSheet.absoluteFill}
device={device}
format={format}
fps={240}
/>
)
}
```
:::note
You should always verify that the format supports the desired FPS, and fall back to `undefined` (or a value that is supported, like `30`) if it doesn't.
:::
Other props that depend on the `format`:
* `hdr`: Enables HDR photo or video capture and preview
* `lowLightBoost`: Enables a night-mode/low-light-boost for photo or video capture and preview
* `colorSpace`: Uses the specified color-space for photo or video capture and preview (iOS only since Android only uses `YUV`)
<br />
#### 🚀 Next section: [Taking Photos/Recording Videos](./capturing)

68
docs/docs/guides/FRAME_PROCESSORS.mdx Normal file
View File

@@ -0,0 +1,68 @@
---
id: frame-processors
title: Frame Processors
sidebar_label: Frame Processors
---
import useBaseUrl from '@docusaurus/useBaseUrl';
:::warning
FRAME PROCESSORS ARE STILL WORK IN PROGRESS - SEE [#2](https://github.com/cuvent/react-native-vision-camera/pull/2)
:::
<!-- TODO: Demo of QR code scanning or smth -->
<div>
<svg xmlns="http://www.w3.org/2000/svg" width="283" height="535" style={{ float: 'right' }}>
<image href={useBaseUrl("img/demo.gif")} x="18" y="33" width="247" height="469" />
<image href={useBaseUrl("img/frame.png")} width="283" height="535" />
</svg>
</div>
### What are frame processors?
Frame processors are functions that are written in JavaScript (or TypeScript) which can be used to **process frames the camera "sees"**.
For example, you might want to create a QR code scanner _without ever writing native code while still achieving almost-native performance_. Since you can write the scanning part yourself, you can implement a custom QR code system like the one Snapchat uses for Snap-codes.
<div align="center">
<img src={useBaseUrl("img/snap-code.png")} width="15%" />
</div>
<br />
Frame processors are by far not limited to QR code detection, other examples include:
* **AI** for **facial recognition**
* **AI** for **object detection**
* Using **Tensorflow**, **MLKit Vision** or other libraries (if they provide React Native JSI bindings in the form of "react-native-vision-camera plugins")
* Creating **realtime video-chats** since you can directly send the camera frames over the network
* Creating **snapchat-like filters**, e.g. draw a dog-mask filter over the user's face (WIP)
* Creating **color filters** with depth-detection
* Using **custom C++ processors** exposed to JS for maximum performance
### Technical
Frame processors are JS functions that will be **workletized** using [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated). They are created on a **separate thread** using a separate Hermes/JSC Runtime and are **invoked synchronously** (using JSI) without ever going over the bridge.
### Example
```tsx
function App() {
const frameProcessor = useFrameProcessor((frame) => {
const qrCodes = scanQrCodes(frame)
console.log(qrCodes)
}, [])
return (
<Camera frameProcessor={frameProcessor} {...cameraProps} />
)
}
```
### Plugins
> TODO
<br />
#### 🚀 Next section: [Zooming with Reanimated](animated)

120
docs/docs/guides/SETUP.mdx Normal file
View File

@@ -0,0 +1,120 @@
---
id: setup
title: Getting Started
sidebar_label: Getting Started
slug: /guides
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<img align="right" width="283" src={useBaseUrl("img/example_intro.png")} />
</div>
## Installing the library
Install react-native-vision-camera through npm:
```sh
npm i react-native-vision-camera
npx pod-install
```
## Updating manifests
To use a Camera or Microphone you must first specify that your app requires camera and microphone permissions.
### iOS
Open your project's `Info.plist` and add the following lines inside the outermost `<dict>` tag:
```xml
<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) needs access to your Camera to record videos and capture photos.</string>
<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) needs access to your Microphone to record videos with audio.</string>
```
#### Compatibility
VisionCamera is written in Swift. If your project is written in Objective-C, you have to create a Bridging Header first:
1. Open your project (`.xcworkspace`) in Xcode
2. Press **File** > **New** > **File** (<kbd>⌘</kbd>+<kbd>N</kbd>)
3. Select **Swift File** and press **Next**
4. Choose whatever name you want, e.g. `File.swift` and press **Create**
5. Press **Create Bridging Header** when promted.
Also, make sure you're using Swift 5.2 or above:
1. Open `project.pbxproj` in a Text Editor
2. If the `LIBRARY_SEARCH_PATH` value is set, make sure there is no explicit reference to Swift-5.0. If there is, remove it. See [this StackOverflow answer](https://stackoverflow.com/a/66281846/1123156).
3. If the `SWIFT_VERSION` value is set, make sure it is set to `5.2` or higher.
> See [Troubleshooting](guides/troubleshooting) if you're having problems
### Android
Open your project's `AndroidManifest.xml` and add the following lines inside the `<manifest>` tag:
```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```
#### Compatibility
VisionCamera requires a minimum Android SDK version of **21 or higher**, and a target SDK version of **30 or higher**. See [the example app's `build.gradle`](https://github.com/cuvent/react-native-vision-camera/blob/main/example/android/build.gradle#L6-L9) for reference.
Open your project's `build.gradle`, and set the following values:
```
buildToolsVersion = "30.0.0"
minSdkVersion = 21
compileSdkVersion = 30
targetSdkVersion = 30
```
> See [Troubleshooting](guides/troubleshooting) if you're having problems
## Permissions
VisionCamera also provides functions to easily get and request Microphone and Camera permissions.
### Getting Permissions
Simply use the **get** functions to find out if a user has granted or denied permission before:
```ts
const cameraPermission = await Camera.getCameraPermissionStatus()
const microphonePermission = await Camera.getMicrophonePermissionStatus()
```
A permission status can have the following values:
* `authorized`: Your app is authorized to use said permission. Continue with mounting the `<Camera>` view.
* `not-determined`: Your app has not yet requested permission from the user. [Continue by calling the **request** functions.](#requesting-permissions)
* `denied`: Your app has already requested permissions from the user, but was explicitly denied. You cannot use the **request** functions again, but you can use the [`Linking` API](https://reactnative.dev/docs/linking#opensettings) to redirect the user to the Settings App where he can manually grant the permission.
* `restricted`: (iOS only) Your app cannot use the Camera or Microphone because that functionality has been restricted, possibly due to active restrictions such as parental controls being in place.
### Requesting Permissions
Use the **request** functions to prompt the user to give your app permission to use the Camera or Microphone.
:::caution
Note: You can only use **request** functions if the current permission status is `not-determined`.
:::
```ts
const newCameraPermission = await Camera.requestCameraPermission()
const newMicrophonePermission = await Camera.requestMicrophonePermission()
```
The permission request status can have the following values:
* `authorized`: Your app is authorized to use said permission. Continue with mounting the `<Camera>` view.
* `denied`: Your app has already requested permissions from the user, but was explicitly denied. You cannot use the **request** functions again, but you can use the [`Linking` API](https://reactnative.dev/docs/linking#opensettings) to redirect the user to the Settings App where he can manually grant the permission.
<br />
#### 🎉 Hooray! You're ready to learn about [Camera Devices](guides/devices)!

10
docs/docs/guides/TODO.md Normal file
View File

@@ -0,0 +1,10 @@
# TODO
This is an internal TODO list which I am using to keep track of some of the features that are still missing.
* [ ] Mirror images from selfie cameras (iOS Done, Android WIP)
* [ ] Allow camera switching (front <-> back) while recording and stich videos together
* [ ] Make `startRecording()` async. Due to NativeModules limitations, we can only have either one callback or one promise in a native function. For `startRecording()` we need both, since you probably also want to catch any errors that occured during a `startRecording()` call (or wait until the recording has actually started, since this can also take some time)
* [ ] Return a `jsi::Value` reference for images (`UIImage`/`Bitmap`) on `takePhoto()` and `takeSnapshot()`. This way, we skip the entire file writing and reading, making image capture _a lot_ faster.
* [ ] Implement frame processors. The idea here is that the user passes a small JS function (reanimated worklet) to the `Camera::frameProcessor` prop which will then get called on every frame the camera previews. (I'd say we cap it to 30 times per second, even if the camera fps is higher) This can then be used to scan QR codes, detect faces, detect depth, render something ontop of the camera such as color filters, QR code boundaries or even dog filters, possibly even use AR - all from a single, small, and highly flexible JS function!
* [ ] Create a custom MPEG4 encoder to allow for more customizability in `recordVideo()` (`bitRate`, `priority`, `minQuantizationParameter`, `allowFrameReordering`, `expectedFrameRate`, `realTime`, `minimizeMemoryUsage`)

66
docs/docs/guides/TROUBLESHOOTING.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
id: troubleshooting
title: Troubleshooting
sidebar_label: Troubleshooting
---
import useBaseUrl from '@docusaurus/useBaseUrl';
<div>
<img align="right" width="283" src={useBaseUrl("img/11_back.png")} />
</div>
Before opening an issue, make sure you try the following:
## iOS
1. Try cleaning and rebuilding **everything**:
```sh
rm -rf package-lock.json && rm -rf yarn.lock && rm -rf node_modules && rm -rf ios/Podfile.lock && rm -rf ios/Pods
npm i # or "yarn"
cd ios && pod repo update && pod update && pod install
```
2. Check your minimum iOS version. VisionCamera requires a minimum iOS version of **11.0**.
1. Open your `Podfile`
2. Make sure `platform :ios` is set to `11.0` or higher
3. Check your Swift version. VisionCamera requires a minimum Swift version of **5.2**.
1. Open `project.pbxproj` in a Text Editor
2. If the `LIBRARY_SEARCH_PATH` value is set, make sure there is no explicit reference to Swift-5.0. If there is, remove it. See [this StackOverflow answer](https://stackoverflow.com/a/66281846/1123156).
3. If the `SWIFT_VERSION` value is set, make sure it is set to `5.2` or higher.
4. Make sure you have created a Swift bridging header in your project.
1. Open your project (`.xcworkspace`) in Xcode
2. Press **File** > **New** > **File** (<kbd>⌘</kbd>+<kbd>N</kbd>)
3. Select **Swift File** and press **Next**
4. Choose whatever name you want, e.g. `File.swift` and press **Create**
5. Press **Create Bridging Header** when promted.
5. If you're experiencing weird behaviour, check the logs in Xcode to find out more.
## Android
1. Try cleaning and rebuilding **everything**:
```sh
./android/gradlew clean
rm -rf package-lock.json && rm -rf yarn.lock && rm -rf node_modules
npm i # or "yarn"
```
2. Since the Android implementation uses the not-yet fully stable **CameraX** API, make sure you've browsed the [CameraX issue tracker](https://issuetracker.google.com/issues?q=componentid:618491%20status:open) to find out if your issue is a limitation by the **CameraX** library even I cannot get around.
3. Make sure your minimum SDK version is **21 or higher**, and target SDK version is **30 or higher**. See [the example's `build.gradle`](https://github.com/cuvent/react-native-vision-camera/blob/main/example/android/build.gradle#L5-L9) for reference.
1. Open your `build.gradle`
2. Set `buildToolsVersion` to `30.0.0` or higher
3. Set `compileSdkVersion` to `30` or higher
4. Set `targetSdkVersion` to `30` or higher
5. Set `minSdkVersion` to `21` or higher
6. Update the Gradle Build-Tools version to `4.1.2` or higher:
```
classpath("com.android.tools.build:gradle:4.1.2")
```
4. Make sure your Gradle Wrapper version is 6.5 or higher. In `gradle-wrapper.properties`, set:
```
distributionUrl=https\://services.gradle.org/distributions/gradle-6.5-all.zip
```
5. If you're experiencing weird behaviour, check the logs in Android Studio/Logcat (<kbd>⌘</kbd>+<kbd>6</kbd>) to find out more.
6. If a camera device is not being returned by `getAvailableCameraDevices()`, make sure it meets the minimum requirements - that is minum supported harwdware level of `LIMITED` and above. See [this section in the Android docs](https://developer.android.com/reference/android/hardware/camera2/CameraDevice) for more information.
## Issues
If nothing has helped so far, try browsing the [GitHub issues](https://github.com/cuvent/react-native-vision-camera/issues?q=is%3Aissue). If your issue doesn't exist, [create a new one](https://github.com/cuvent/react-native-vision-camera/issues/new/choose). Make sure to fill out the template and include as many details as possible. Also try to reproduce the issue in the [example app](https://github.com/cuvent/react-native-vision-camera/blob/main/example).