react-native-vision-camera/docs/DEVICES.md
2021-03-01 12:41:49 +01:00

5.0 KiB

README SETUP DEVICES FORMATS FRAME_PROCESSORS ANIMATED ERRORS

Devices

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:

const devices = await Camera.getAvailableCameraDevices()

🔗 See the CameraDevice type

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:

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 FORMATS.md), and more.

Make sure to carefully filter out unneeded camera devices, since not every phone supports all camera device types. Some phones don't even have front-cameras.

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:

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 > ...

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")

This example demonstrates how you could pause the camera stream once the app goes into background using a custom useIsAppForeground hook:

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}
    />
  )
}

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).


🚀 Next section: FORMATS