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