biometry-react-components/README.md

React UI component library for capturing high-quality biometric data (voice, face, documents, video) to facilitate integration with Biometry services

# biometry-react-components

React UI component library with tools to work with camera and microphone for easier integration of Biometry services. This library could be used in combination with [Biometry SDK](https://www.npmjs.com/package/biometry-sdk)

## Installation

```bash
npm install biometry-react-components
```

### Peer Dependencies

This library requires React 16.8.0 or higher (supports React Hooks):

```json
{
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}
```

## Components

### DocScan

Captures ID documents, driver license and etc. Suitable component for Biometry's [DocAuth](https://developer.biometrysolutions.com/api/doc-auth/).

```tsx
import { DocScan } from 'biometry-react-components';

function DocumentCapture() {
  const handleCapture = (file: File) => {
    console.log('Captured document:', file);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.checkDocAuth(file, userFullName, { sessionId });
  };

  return <DocScan onCapture={handleCapture} />;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onCapture` | `(file: File) => void` | **required** | Callback with captured image file |
| `rectWidth` | `number` | `640` | Width of camera area |
| `rectHeight` | `number` | `400` | Height of camera area |
| `className` | `string` | - | Custom CSS class |
| `style` | `React.CSSProperties` | - | Custom inline styles |
| `noShadow` | `boolean` | `false` | Remove shadow and border radius |

### FaceCapture

Captures facial images with an oval guidance overlay. Ideal for [Face Match](https://developer.biometrysolutions.com/api/facematch/) and [Face Enrollment](https://developer.biometrysolutions.com/api/face-enrollment/).

```tsx
import { FaceCapture } from 'biometry-react-components';

function FaceCapture() {
  const handleCapture = (file: File) => {
    console.log('Captured face:', file);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.enrollFace(file, 'John Doe');
  };

  return <FaceCapture onCapture={handleCapture} />;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onCapture` | `(file: File) => void` | **required** | Callback with captured image file |
| `rectWidth` | `number` | `360` | Width of camera area |
| `rectHeight` | `number` | `576` | Height of camera area |
| `className` | `string` | - | Custom CSS class |
| `style` | `React.CSSProperties` | - | Custom inline styles |
| `noShadow` | `boolean` | `false` | Remove shadow and border radius |

### FaceRecorder

Records video with facial guidance overlay and displays 10 random numbers (0-9) for the user to read aloud. Automatically extracts audio from the recorded video. This component could be used for [Process Video](https://developer.biometrysolutions.com/api/process-video/) and [Voice Enrollment](https://developer.biometrysolutions.com/api/voice-enrollment/)

```tsx
import { FaceRecorder } from 'biometry-react-components';

function FaceRecorder() {
  const handleCapture = (video: File, audio: File, phrase: string) => {
    console.log('Captured video:', video);
    console.log('Captured audio:', audio);
    console.log('Phrase:', phrase);
    // Send files to your endpoint that will process the biometric data
    // or
    // const response = await sdk.processVideo(video, phrase, userFullName);
    // const voiceResponse = await sdk.enrollVoice(audio, userFullName);
  };

  return <FaceRecorder onCapture={handleCapture} />;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onCapture` | `(video: File, audio: File, phrase: string) => void` | **required** | Callback with captured video file, audio file, and phrase |
| `rectWidth` | `number` | `360` | Width of camera area |
| `rectHeight` | `number` | `576` | Height of camera area |
| `className` | `string` | - | Custom CSS class |
| `style` | `React.CSSProperties` | - | Custom inline styles |
| `noShadow` | `boolean` | `false` | Remove shadow and border radius |

### VoiceRecorder

Records audio with real-time waveform visualization and adaptive quality settings. Use this for [Voice Enrollment](https://developer.biometrysolutions.com/api/voice-enrollment/)

```tsx
import { VoiceRecorder } from 'biometry-react-components';

function VoiceRecorder() {
  const handleCapture = (file: File, phrase: string) => {
    console.log('Captured audio:', file);
    console.log('Phrase:', phrase);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.enrollVoice(file, 'John Doe');
  };

  return <VoiceRecorder onCapture={handleCapture} />;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onCapture` | `(file: File, phrase: string) => void` | **required** | Callback with captured audio file and phrase |
| `rectWidth` | `number` | `360` | Width of component area |
| `rectHeight` | `number` | `undefined` | Height of component area (optional) |
| `className` | `string` | - | Custom CSS class |
| `style` | `React.CSSProperties` | - | Custom inline styles |
| `noShadow` | `boolean` | `false` | Remove shadow and border radius |


## Custom Hooks

### useRecorder

A powerful hook for recording audio and video with adaptive quality settings and automatic format detection.

```tsx
import { useRecorder } from 'biometry-react-components';

function CustomRecorder() {
  const mediaStream = // ... your media stream
  
  const { 
    isRecording, 
    startRecording, 
    stopRecording, 
    cancelRecording 
  } = useRecorder(mediaStream, "video", (blob) => {
    console.log('Recording completed:', blob);
  });

  return (
    ...
  );
}
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `stream` | `MediaStream \| null` | Media stream to record from |
| `type` | `"audio" \| "video"` | Type of media to record |
| `onStopRecording` | `(blob: Blob) => void` | Callback when recording stops |

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `isRecording` | `boolean` | Current recording state |
| `startRecording` | `() => void` | Start recording function |
| `stopRecording` | `() => void` | Stop recording function |
| `cancelRecording` | `() => void` | Cancel recording function |

### usePermissions

Hook for managing camera and microphone permissions with adaptive quality constraints.

```tsx
import usePermissions from 'biometry-react-components';

function PermissionManager() {
  const { 
    permission, 
    stream, 
    stopStreamTracks, 
    requestPermissions, 
    isLoading 
  } = usePermissions({ rectWidth: 1280, rectHeight: 720 });

  if (isLoading) return <div>Loading...</div>;
  
  if (!permission) {
    return <button onClick={requestPermissions}>Grant Permissions</button>;
  }

  return <div>Camera and microphone access granted!</div>;
}
```

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `rectWidth` | `number` | `1920` | Desired video width |
| `rectHeight` | `number` | `1080` | Desired video height |

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `permission` | `boolean` | Permission granted status |
| `stream` | `MediaStream \| null` | Active media stream |
| `stopStreamTracks` | `() => void` | Stop all media tracks |
| `requestPermissions` | `() => Promise<void>` | Request camera/microphone permissions |
| `isLoading` | `boolean` | Loading state during permission request |

### useAudioPermissions

Specialized hook for audio-only permissions with optimized audio constraints.

```tsx
import useAudioPermissions from 'biometry-react-components';

function AudioPermissionManager() {
  const { 
    permission, 
    stream, 
    stopStreamTracks, 
    requestPermissions, 
    isLoading 
  } = useAudioPermissions();

  if (isLoading) return <div>Loading...</div>;
  
  if (!permission) {
    return <button onClick={requestPermissions}>Grant Microphone Access</button>;
  }

  return <div>Microphone access granted!</div>;
}
```

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `permission` | `boolean` | Audio permission granted status |
| `stream` | `MediaStream \| null` | Active audio stream |
| `stopStreamTracks` | `() => void` | Stop all audio tracks |
| `requestPermissions` | `() => Promise<void>` | Request microphone permissions |
| `isLoading` | `boolean` | Loading state during permission request |

## License

MIT License - see the [LICENSE](LICENSE) file for details.