use-simple-camera
Version:
Production-ready React Hooks for Camera, Video Recording, QR/Barcode Scanning, Motion Detection, and Audio Analysis. Zero dependencies, fully typed, and easy to use.
174 lines (122 loc) • 7.05 kB
Markdown
# 🎥 **Use Simple Camera**
[](https://www.npmjs.com/package/use-simple-camera)
[](https://github.com/ketanip/use-simple-camera/actions)
[](https://bundlephobia.com/package/use-simple-camera)
[](https://packagephobia.com/result?p/use-simple-camera)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://biomejs.dev/)
[](https://socket.dev/npm/package/use-simple-camera)
[](https://www.npmjs.com/package/use-simple-camera)
[](http://makeapullrequest.com)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fketanip%2Fuse-simple-camera?ref=badge_shield)
[](https://snyk.io/test/github/ketanip/use-simple-camera)
[](https://gitpod.io/#https://github.com/ketanip/use-simple-camera)
[](https://github.com/semantic-release/semantic-release)
[](CODE_OF_CONDUCT.md)
**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**
```bash
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.
```tsx
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.
```tsx
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).
```tsx
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.
```tsx
import { useCameraControls } from "use-simple-camera";
const { zoom, setZoom, flash, setFlash, supports } = useCameraControls(stream);
```
### 5. `useBarcodeScanner`
Detects QR codes and Barcodes in real-time.
```tsx
const { barcodes, isScanning } = useBarcodeScanner(stream, { formats: ['qr_code'] });
```
### 6. `useMotionDetection`
Detects movement in the video feed using pixel differencing.
```tsx
const { motionDetected } = useMotionDetection(stream, { threshold: 10 });
```
### 7. `useAudioLevel`
Monitors real-time microphone volume.
```tsx
const { volume } = useAudioLevel(stream); // 0-100
```
### 8. `useOrientation`
Tracks device screen orientation.
```tsx
const { orientation, angle } = useOrientation(); // 'portrait' | 'landscape'
```
### 9. `useMediaDevices`
Enumerates available audio and video inputs.
```tsx
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.