@onamfc/video-transcoder/README.md

Backend-agnostic video recording and transcoding module with AWS integration

# Video Recorder Studio

A production-ready, backend-agnostic video recording and transcoding library that enables websites to capture webcam video and automatically convert it to HLS format using AWS services.

## Features

- **Universal Recording**: Works across all modern browsers and devices
- **AWS-Powered**: Leverages S3, MediaConvert, and CloudFront for scalable processing
- **Backend Agnostic**: Integrates with any server technology
- **Mobile Optimized**: Responsive design with mobile-specific optimizations
- **Production Ready**: Built-in error handling, retry logic, and monitoring
- **Customizable**: Flexible configuration and styling options
- **Progress Tracking**: Real-time upload and processing progress
- **Secure**: Presigned URLs and proper authentication handling

## Quick Start

### 1. Install the Package

```bash
npm install @onamfc/video-transcoder
```

### 2. Basic Usage

```javascript
import { VideoRecorder } from '@onamfc/video-transcoder';

const recorder = new VideoRecorder({
  apiEndpoint: 'https://your-api.com/api/video',
  maxDuration: 300,
  videoQuality: 'medium'
});

// Initialize camera
await recorder.initialize();

// Start recording
await recorder.startRecording();

// Stop and upload
const recording = await recorder.stopRecording();
const upload = await recorder.uploadRecording(recording.blob);

// Track progress
recorder.onComplete((result) => {
  console.log('HLS URL:', result.hlsUrl);
  console.log('MP4 URL:', result.mp4Url);
});
```

### 3. React Hook

```tsx
import { useVideoRecorder } from '@onamfc/video-transcoder/react';

function VideoRecorderComponent() {
  const {
    initialize,
    startRecording,
    stopRecording,
    isRecording,
    duration,
    status
  } = useVideoRecorder({
    config: {
      apiEndpoint: 'https://your-api.com/api/video',
      maxDuration: 300
    },
    onComplete: (result) => {
      console.log('Video processed:', result.hlsUrl);
    }
  });

  return (
    <div>
      <button onClick={initialize}>Initialize Camera</button>
      <button onClick={startRecording} disabled={!isInitialized || isRecording}>
        Start Recording
      </button>
      <button onClick={stopRecording} disabled={!isRecording}>
        Stop Recording
      </button>
      <p>Status: {status}</p>
      <p>Duration: {duration}s</p>
    </div>
  );
}
```

## API Reference

### VideoRecorder Class

#### Constructor

```typescript
new VideoRecorder(config: RecorderConfig)
```

#### Methods

- `initialize(): Promise<void>` - Initialize camera access
- `startRecording(): Promise<void>` - Start video recording
- `stopRecording(): Promise<RecordingResult>` - Stop recording and get result
- `pauseRecording(): void` - Pause current recording
- `resumeRecording(): void` - Resume paused recording
- `uploadRecording(blob: Blob, metadata?: object): Promise<UploadResult>` - Upload recorded video
- `getUploadStatus(trackingId: string): Promise<StatusResult>` - Check upload status
- `cleanup(): void` - Clean up resources

#### Event Handlers

- `onProgress(callback: (progress: ProgressEvent) => void): void`
- `onComplete(callback: (result: ProcessingResult) => void): void`
- `onError(callback: (error: ErrorEvent) => void): void`

## Configuration

```typescript
interface RecorderConfig {
  // Required
  apiEndpoint: 'https://your-api.com/api/video',
  
  // Recording Settings
  maxDuration: 300, // 5 minutes
  videoQuality: 'medium', // 'low' | 'medium' | 'high' | 'auto'
  audioEnabled: true,
  
  // Upload Settings
  chunkSize: 5 * 1024 * 1024, // 5MB chunks
  maxRetries: 3,
  parallelUploads: 3,
  
  // Output Options
  outputFormats: ['hls', 'mp4'],
  thumbnailCount: 3,
  
  // UI Options
  showPreview: true,
  customStyles: { /* CSS styles */ }
}
```

## Backend Integration

Your backend needs to implement these endpoints:

- `POST /api/video/upload-token` - Generate presigned upload URLs
- `GET /api/video/status/:trackingId` - Get processing status
- `GET /api/video/recordings` - List recordings (optional)

See the [GitHub repository](https://github.com/onamfc/video-transcoder) for complete backend examples and AWS infrastructure setup.

## Browser Support

| Browser | Version | Support Level |
|---------|---------|---------------|
| Chrome | 47+ | ✅ Full |
| Firefox | 29+ | ✅ Full |
| Safari | 14+ | ✅ Full |
| Edge | 79+ | ✅ Full |
| Mobile Safari | 14+ | ✅ Full |
| Chrome Mobile | 47+ | ✅ Full |

## TypeScript Support

This package includes TypeScript definitions out of the box.

## Examples

Check the [GitHub repository](https://github.com/onamfc/video-transcoder) for complete examples:

- Vanilla JavaScript
- React with hooks
- Vue.js composition API
- Angular components
- Backend integrations (Express, Django, Laravel, Serverless)

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

## License

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

## Support

- **GitHub Issues**: [Report bugs and feature requests](https://github.com/onamfc/video-transcoder/issues)
- **Documentation**: [Complete documentation](https://github.com/onamfc/video-transcoder)

---

**Note**: This package requires a backend implementation to handle video uploads and processing. See the GitHub repository for complete setup instructions including AWS infrastructure deployment.


# Run tests
npm test

# Build module
npm run build

# Run examples
npm run dev:examples
```

## License

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

## Support

- **Documentation**: View the Docs directory
- **Issues**: [GitHub Issues](https://github.com/onamfc/video-transcoder/issues)
- **Discussions**: [GitHub Discussions](https://github.com/onamfc/video-transcoder/discussions)

## Acknowledgments

- AWS MediaConvert team for excellent transcoding capabilities
- WebRTC community for browser API standards
- Open source contributors and early adopters
---