use-simple-camera - NFHN Reader

🎥 Use Simple Camera

Use Simple Camera is a production-ready, zero-dependency React hook library for comprehensive camera and media handling. It provides a robust set of hooks for video recording, local/remote storage, computer vision (barcodes, motion detection), and hardware controls (zoom, flash, pan, tilt).

✨ Features

📸 Easy Camera Access: Simple API to get camera stream, switch cameras, and capture images.
🎥 Video Recording: Record video/audio blobs with MediaRecorder API.
💾 Storage: Save recordings to IndexedDB or upload via XHR/S3.
🔍 Computer Vision: Built-in hooks for Barcode detection and Motion detection.
🛠 Hardware Controls: Control Zoom, Flash, Pan, and Tilt if supported.
🎙 Audio Utilities: Monitor microphone volume levels in real-time.
📱 Orientation: Detect device orientation for responsive UI.
🌲 Tree Shakeable: Import only the hooks you need.

📦 Installation

npm install /use-simple-camera
# or
pnpm add /use-simple-camera
# or
yarn add /use-simple-camera

⚡ Quick Start

The useSimpleCamera hook is the entry point that composes most features, but you can use individual hooks as standalone primitives.

import { useSimpleCamera } from "/use-simple-camera";

const App = () => {
  const { stream, ref, error, startCamera, captureImage } = useSimpleCamera();
  
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
       <video ref={ref} autoPlay muted playsInline />
       <button onClick={() => captureImage()}>Take Photo</button>
    </div>
  );
};

📚 API Documentation

1. `useSimpleCamera`

The main hook for managing camera lifecycle, permissions, and stream state.

Property	Type	Description
`stream`	`MediaStream \| null`	The active camera stream.
`startCamera`	`(constraints?) => Promise`	Manually starts the camera.
`stopCamera`	`() => void`	Stops all tracks and releases camera.
`captureImage`	`(options?) => string`	Captures a base64 image.
`error`	`CameraError \| null`	Typed error object if something fails.
`isCameraActive`	`boolean`	True if stream is active.
`switchCamera`	`() => void`	Toggles between front and back cameras.

2. `useRecorder`

Handles video and audio recording with support for separate streams and callbacks.

import { useRecorder } from "use-simple-camera";
const { startRecording, stopRecording, isRecording } = useRecorder(stream);

Property	Type	Description
`startRecording`	`(options?) => void`	Starts recording media. Options: `mode`, `onComplete`.
`stopRecording`	`() => void`	Stops recording and triggers `onComplete` with blob.
`takeSnapshot`	`() => Promise<Blob>`	Captures a high-res still photo.

3. `useStorage`

Manage local persistence (IndexedDB) and remote uploads (S3/XHR).

import { useStorage } from "use-simple-camera";
const { saveToLocal, uploadToRemote } = useStorage();

Property	Type	Description
`saveToLocal`	`(blob, name, opts) => Promise`	Save blob to IndexedDB with optional retention.
`getFromLocal`	`(name) => Promise<Blob>`	Retrieve blob from IndexedDB.
`uploadToRemote`	`(blob, opts) => Promise`	Upload to signed URL. Options: headers, timeout, etc.

4. `useCameraControls`

Control hardware features like Zoom, Flash, Pan, and Tilt.

import { useCameraControls } from "use-simple-camera";
const { zoom, setZoom, flash, setFlash, supports } = useCameraControls(stream);

5. `useBarcodeScanner`

Detects QR codes and Barcodes in real-time.

const { barcodes, isScanning } = useBarcodeScanner(stream, { formats: ['qr_code'] });

6. `useMotionDetection`

Detects movement in the video feed using pixel differencing.

const { motionDetected } = useMotionDetection(stream, { threshold: 10 });

7. `useAudioLevel`

Monitors real-time microphone volume.

const { volume } = useAudioLevel(stream); // 0-100

8. `useOrientation`

Tracks device screen orientation.

const { orientation, angle } = useOrientation(); // 'portrait' | 'landscape'

9. `useMediaDevices`

Enumerates available audio and video inputs.

const { videoDevices, audioDevices } = useMediaDevices();

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.