@vidtreo/recorder 0.0.1 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # @vidtreo/recorder
 
-Video transcoding package using mediabunny. Transcodes videos to MP4 format with configurable settings, optimized for Bun runtime.
+Vidtreo SDK for browser-based video recording and transcoding. Similar to Ziggeo and Addpipe, Vidtreo provides enterprise-grade video processing capabilities for web applications. Features include camera and screen recording, real-time MP4 transcoding, audio level analysis, mute/pause controls, source switching, device selection, and automatic backend uploads.
 
 ## Installation
 
@@ -8,222 +8,709 @@ Video transcoding package using mediabunny. Transcodes videos to MP4 format with
 npm install @vidtreo/recorder
 ```
 
-## Usage
+## Quick Start
 
-### Basic Usage
+```typescript
+import { VidtreoRecorder } from '@vidtreo/recorder';
+
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://your-worker.workers.dev',
+  enableSourceSwitching: true,
+  maxRecordingTime: 300000,
+  onUploadComplete: (result) => {
+    console.log('Recording ID:', result.recordingId);
+    console.log('Video URL:', result.uploadUrl);
+  },
+});
+
+await recorder.startPreview('camera');
+await recorder.startRecording({}, 'camera');
+const result = await recorder.stopRecording();
+recorder.cleanup();
+```
+
+## API Reference
+
+### VidtreoRecorder
+
+The main class for recording video from camera or screen sources.
+
+#### Constructor
 
 ```typescript
-import { transcodeVideo } from '@vidtreo/recorder';
+new VidtreoRecorder(config: VidtreoRecorderConfig)
+```
 
-// Transcode from a Blob
-const videoBlob = new Blob([videoData], { type: 'video/mp4' });
-const result = await transcodeVideo(videoBlob);
-console.log(result.buffer); // ArrayBuffer with transcoded video
-console.log(result.blob); // Blob with transcoded video
+Creates a new recorder instance with the specified configuration.
+
+**Parameters:**
+
+- `config.apiKey` (required): Your API key for backend authentication
+- `config.apiUrl` (required): Your backend API URL endpoint
+- `config.enableSourceSwitching` (optional): Enable switching between camera and screen during recording. Default: `false`
+- `config.enableMute` (optional): Enable mute/unmute functionality. When disabled, `muteAudio()`, `unmuteAudio()`, and `toggleMute()` will throw errors. Default: `true`
+- `config.enablePause` (optional): Enable pause/resume functionality. When disabled, `pauseRecording()` and `resumeRecording()` will throw errors. Default: `true`
+- `config.enableDeviceChange` (optional): Enable device selection functionality. When disabled, `getAvailableDevices()` will throw an error. Default: `true`
+- `config.maxRecordingTime` (optional): Maximum recording duration in milliseconds. When the maximum time is reached, recording automatically stops. If not set, recording can continue indefinitely until manually stopped. Examples: `300000` (5 minutes), `600000` (10 minutes), `1800000` (30 minutes)
+- `config.countdownDuration` (optional): Countdown duration in milliseconds before recording starts. Default: `0` (no countdown)
+- `config.userMetadata` (optional): Custom metadata object to include with uploads
+- `config.onUploadComplete` (optional): Callback invoked when upload completes successfully
+- `config.onUploadProgress` (optional): Callback invoked during upload with progress value (0-1)
+- `config.onUploadError` (optional): Callback invoked when upload fails
+- `config.onRecordingStart` (optional): Callback invoked when recording starts
+- `config.onRecordingStop` (optional): Callback invoked when recording stops
+- `config.onError` (optional): Callback invoked when a stream error occurs
+
+**Throws:** `Error` if `apiKey` or `apiUrl` are missing
+
+#### Methods
+
+##### `initialize(): Promise<void>`
+
+Initializes the recorder with the provided configuration. Called automatically when needed, but can be called explicitly for early initialization.
+
+**Returns:** `Promise<void>`
+
+##### `startPreview(sourceType?: SourceType): Promise<MediaStream>`
+
+Starts a preview stream from the specified source without recording.
+
+**Parameters:**
+
+- `sourceType` (optional): Source type to preview. Either `'camera'` or `'screen'`. Default: `'camera'`
+
+**Returns:** `Promise<MediaStream>` - The preview media stream
+
+**Throws:** `Error` if stream initialization fails
+
+##### `startRecording(options?: RecordingStartOptions, sourceType?: SourceType): Promise<void>`
+
+Starts recording from the specified source. If no preview is active, automatically starts one.
+
+**Parameters:**
+
+- `options` (optional): Recording options object
+  - `options.video`: Video constraints (boolean or `CameraConstraints` object)
+  - `options.audio`: Audio constraints (boolean or `MediaTrackConstraints` object)
+- `sourceType` (optional): Source type to record from. Either `'camera'` or `'screen'`. Default: `'camera'`
+
+**Returns:** `Promise<void>`
+
+**Throws:** `Error` if recording cannot be started
+
+##### `stopRecording(): Promise<RecordingStopResult>`
+
+Stops the current recording, transcodes the video, and uploads it to the backend.
+
+**Returns:** `Promise<RecordingStopResult>` - Object containing:
+- `recordingId`: Unique identifier for the uploaded recording
+- `uploadUrl`: URL where the video can be accessed
+- `blob`: The recorded video as a Blob
+
+**Throws:** `Error` if recording is not active or upload fails
+
+##### `switchSource(sourceType: SourceType): Promise<void>`
+
+Switches the recording source between camera and screen during an active recording.
+
+**Parameters:**
+
+- `sourceType`: Target source type. Either `'camera'` or `'screen'`
+
+**Returns:** `Promise<void>`
+
+**Throws:** `Error` if source switching is not enabled or if not currently recording
+
+##### `getAvailableDevices(): Promise<AvailableDevices>`
+
+Retrieves the list of available camera and microphone devices.
+
+**Returns:** `Promise<AvailableDevices>` - Object containing:
+- `video`: Array of available video input devices
+- `audio`: Array of available audio input devices
+
+**Throws:** `Error` if device change functionality is disabled (`enableDeviceChange === false`)
+
+##### `muteAudio(): void`
+
+Mutes the audio track during recording.
+
+**Throws:** `Error` if mute functionality is disabled (`enableMute === false`)
+
+##### `unmuteAudio(): void`
+
+Unmutes the audio track during recording.
 
-// Transcode from a File
-const fileInput = document.querySelector('input[type="file"]');
-const file = fileInput.files[0];
-const result = await transcodeVideo(file);
+**Throws:** `Error` if mute functionality is disabled (`enableMute === false`)
 
-// Transcode from a file path (Bun only)
-const result = await transcodeVideo('/path/to/video.mp4');
+##### `toggleMute(): void`
+
+Toggles the mute state of the audio track.
+
+**Throws:** `Error` if mute functionality is disabled (`enableMute === false`)
+
+##### `isMuted(): boolean`
+
+Returns the current mute state.
+
+**Returns:** `true` if audio is muted, `false` otherwise
+
+##### `pauseRecording(): void`
+
+Pauses the current recording. Video frames are not captured while paused.
+
+**Throws:** `Error` if pause functionality is disabled (`enablePause === false`)
+
+##### `resumeRecording(): void`
+
+Resumes a paused recording.
+
+**Throws:** `Error` if pause functionality is disabled (`enablePause === false`)
+
+##### `isPaused(): boolean`
+
+Returns the current pause state.
+
+**Returns:** `true` if recording is paused, `false` otherwise
+
+##### `getRecordingState(): RecordingState`
+
+Returns the current recording state.
+
+**Returns:** One of:
+- `'idle'`: Not recording
+- `'countdown'`: Countdown in progress before recording
+- `'recording'`: Actively recording
+
+##### `getStream(): MediaStream | null`
+
+Returns the current media stream, or `null` if no stream is active.
+
+**Returns:** `MediaStream | null`
+
+##### `cleanup(): void`
+
+Cleans up all resources, stops active streams, and cancels any pending operations. Should be called when the recorder is no longer needed.
+
+## Type Definitions
+
+### VidtreoRecorderConfig
+
+```typescript
+interface VidtreoRecorderConfig {
+  apiKey: string;
+  apiUrl: string;
+  enableSourceSwitching?: boolean;
+  enableMute?: boolean;
+  enablePause?: boolean;
+  enableDeviceChange?: boolean;
+  maxRecordingTime?: number;
+  countdownDuration?: number;
+  userMetadata?: Record<string, unknown>;
+  onUploadComplete?: (result: {
+    recordingId: string;
+    uploadUrl: string;
+  }) => void;
+  onUploadProgress?: (progress: number) => void;
+  onUploadError?: (error: Error) => void;
+  onRecordingStart?: () => void;
+  onRecordingStop?: () => void;
+  onError?: (error: Error) => void;
+}
 ```
 
-### Custom Configuration
+**Note:** For web component usage, see the [@vidtreo/recorder-wc](../recorder-wc/README.md) package. Use the `max-recording-time` attribute instead of `maxRecordingTime`. The attribute accepts a numeric value in milliseconds as a string (e.g., `max-recording-time="300000"` for 5 minutes).
+
+### RecordingStartOptions
 
 ```typescript
-import { transcodeVideo, DEFAULT_TRANSCODE_CONFIG } from '@vidtreo/recorder';
+interface RecordingStartOptions {
+  video?: boolean | CameraConstraints;
+  audio?: boolean | MediaTrackConstraints;
+}
+```
 
-// Use custom configuration
-const result = await transcodeVideo(videoBlob, {
-  width: 1920,
-  height: 1080,
-  fps: 60,
-  bitrate: 2000000, // 2Mbps
-  packetCount: 2000,
-});
+### RecordingStopResult
 
-// Partial configuration (merges with defaults)
-const result = await transcodeVideo(videoBlob, {
-  width: 640,
-  height: 480,
-});
+```typescript
+interface RecordingStopResult {
+  recordingId: string;
+  uploadUrl: string;
+  blob: Blob;
+}
 ```
 
-## Configuration
+### SourceType
+
+```typescript
+type SourceType = 'camera' | 'screen';
+```
 
-The default configuration is:
+### RecordingState
 
 ```typescript
-{
-  format: 'mp4',        // Always MP4 output
-  fps: 30,              // 30 frames per second
-  width: 1280,          // 1280 pixels
-  height: 720,          // 720 pixels
-  bitrate: 500000,      // 500kbps
-  audioCodec: 'aac',    // AAC audio codec
-  preset: 'medium',     // Medium quality preset
-  packetCount: 1200,    // Maximum packet count for video track
+type RecordingState = 'idle' | 'countdown' | 'recording';
+```
+
+### AvailableDevices
+
+```typescript
+interface AvailableDevices {
+  video: MediaDeviceInfo[];
+  audio: MediaDeviceInfo[];
 }
 ```
 
-### Configuration Options
+### CameraConstraints
 
-- `format`: Output format (always `'mp4'`)
-- `fps`: Target frame rate in frames per second
-- `width`: Target video width in pixels
-- `height`: Target video height in pixels
-- `bitrate`: Target video bitrate in bits per second
-- `audioCodec`: Audio codec to use (always `'aac'`)
-- `preset`: Quality preset (always `'medium'`)
-- `packetCount`: Maximum packet count for video track metadata (optimization hint)
+```typescript
+interface CameraConstraints {
+  width?: number | { ideal?: number; min?: number; max?: number };
+  height?: number | { ideal?: number; min?: number; max?: number };
+  frameRate?: number | { ideal?: number; min?: number; max?: number };
+}
+```
 
-## API Reference
+## Usage Examples
 
-### `transcodeVideo(input, config?)`
+### Basic Recording Workflow
 
-Transcodes a video file to MP4 format.
+```typescript
+import { VidtreoRecorder } from '@vidtreo/recorder';
+
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  onUploadComplete: (result) => {
+    console.log('Uploaded:', result.uploadUrl);
+  },
+});
 
-**Parameters:**
-- `input`: `Blob | File | string` - Input video source (Blob, File, or file path string)
-- `config`: `Partial<TranscodeConfig>` - Optional configuration object (merges with defaults)
+try {
+  await recorder.startPreview('camera');
+  await recorder.startRecording({}, 'camera');
+
+  setTimeout(async () => {
+    const result = await recorder.stopRecording();
+    console.log('Recording ID:', result.recordingId);
+    recorder.cleanup();
+  }, 10000);
+} catch (error) {
+  console.error('Recording failed:', error);
+  recorder.cleanup();
+}
+```
 
-**Returns:** `Promise<TranscodeResult>`
+### Recording with Maximum Time Limit
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  maxRecordingTime: 300000,
+  onRecordingStop: () => {
+    console.log('Recording stopped automatically after 5 minutes');
+  },
+});
 
-**Throws:** `Error` if transcoding fails or input is invalid
+await recorder.startRecording({}, 'camera');
+```
 
-### `TranscodeResult`
+### Recording with Source Switching
 
 ```typescript
-interface TranscodeResult {
-  buffer: ArrayBuffer;  // Transcoded video as ArrayBuffer
-  blob: Blob;          // Transcoded video as Blob
-}
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  enableSourceSwitching: true,
+  maxRecordingTime: 600000,
+});
+
+await recorder.startRecording({}, 'camera');
+
+setTimeout(async () => {
+  await recorder.switchSource('screen');
+}, 5000);
+
+setTimeout(async () => {
+  await recorder.switchSource('camera');
+}, 10000);
+
+setTimeout(async () => {
+  const result = await recorder.stopRecording();
+  recorder.cleanup();
+}, 15000);
 ```
 
-### `DEFAULT_TRANSCODE_CONFIG`
+**Note:** When `maxRecordingTime` is set, the recording will automatically stop when the time limit is reached, even if the timeout callbacks are still pending. The `onRecordingStop` callback will be invoked when the maximum time is reached.
 
-Default configuration object. Can be imported and used as a base for custom configurations.
+### Recording with Mute Control
 
-## Supported Input Formats
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+});
 
-The package supports all formats supported by mediabunny:
-- MP4 (.mp4, .m4v)
-- WebM (.webm)
-- QuickTime (.mov)
-- Matroska (.mkv)
-- OGG (.ogv)
-- And more...
+await recorder.startRecording({}, 'camera');
 
-## Bun Optimizations
+recorder.muteAudio();
+setTimeout(() => recorder.unmuteAudio(), 5000);
+setTimeout(() => recorder.toggleMute(), 10000);
+
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 15000);
+```
 
-This package leverages Bun's native capabilities:
-- Uses `Bun.file()` for efficient file reading when file paths are provided
-- Optimized for Bun's runtime and test runner
-- Native ArrayBuffer handling
+### Recording with Pause and Resume
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+});
 
-## Examples
+await recorder.startRecording({}, 'camera');
 
-### Transcode and Save to File (Bun)
+setTimeout(() => recorder.pauseRecording(), 3000);
+setTimeout(() => recorder.resumeRecording(), 6000);
+
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 10000);
+```
+
+### Recording with Upload Progress
 
 ```typescript
-import { transcodeVideo } from '@vidtreo/recorder';
-import { writeFile } from 'fs/promises';
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  onUploadProgress: (progress) => {
+    const percentage = Math.round(progress * 100);
+    console.log(`Upload: ${percentage}%`);
+  },
+  onUploadComplete: (result) => {
+    console.log('Upload complete:', result.uploadUrl);
+  },
+  onUploadError: (error) => {
+    console.error('Upload failed:', error.message);
+  },
+});
 
-const result = await transcodeVideo('/path/to/input.mp4');
-await Bun.write('/path/to/output.mp4', result.buffer);
+await recorder.startRecording({}, 'camera');
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 5000);
 ```
 
-### Transcode with Progress Tracking
+### Recording with Custom Metadata
 
 ```typescript
-import { transcodeVideo } from '@vidtreo/recorder';
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  userMetadata: {
+    userId: 'user-123',
+    sessionId: 'session-456',
+    projectId: 'project-789',
+  },
+});
 
-console.log('Starting transcoding...');
-const result = await transcodeVideo(videoBlob);
-console.log('Transcoding complete!');
-console.log(`Output size: ${result.buffer.byteLength} bytes`);
+await recorder.startRecording({}, 'camera');
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 5000);
 ```
 
-## Web Component
+### Recording with Countdown
 
-This package also includes a standalone web component (`<vidtreo-recorder>`) that can be used in any HTML page without requiring a build step or framework.
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  countdownDuration: 3000,
+});
 
-### Building the Web Component
+await recorder.startPreview('camera');
+await recorder.startRecording({}, 'camera');
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 10000);
+```
 
-To build the web component, run:
+### Device Selection
 
-```bash
-bun run build:wc
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+});
+
+const devices = await recorder.getAvailableDevices();
+console.log('Cameras:', devices.video.map(d => d.label));
+console.log('Microphones:', devices.audio.map(d => d.label));
+
+await recorder.startRecording({}, 'camera');
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 5000);
+```
+
+### Recording State Monitoring
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  onRecordingStart: () => {
+    console.log('Recording started');
+  },
+  onRecordingStop: () => {
+    console.log('Recording stopped');
+  },
+});
+
+await recorder.startRecording({}, 'camera');
+
+const checkState = setInterval(() => {
+  const state = recorder.getRecordingState();
+  const isPaused = recorder.isPaused();
+  const isMuted = recorder.isMuted();
+  console.log(`State: ${state}, Paused: ${isPaused}, Muted: ${isMuted}`);
+}, 1000);
+
+setTimeout(async () => {
+  clearInterval(checkState);
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 10000);
 ```
 
-This will create two files in `dist/wc/`:
-- `vidtreo-recorder.js` - The web component JavaScript bundle
-- `vidtreo-recorder.css` - The Tailwind CSS stylesheet
+### Screen Recording
 
-### Web Component Usage
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  enableSourceSwitching: true,
+});
 
-#### Basic Usage
+await recorder.startPreview('screen');
+await recorder.startRecording({}, 'screen');
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 30000);
+```
 
-Include both the CSS and JS files in your HTML:
+### Error Handling
 
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>My App</title>
-    <!-- Include the CSS file -->
-    <link rel="stylesheet" href="./dist/wc/vidtreo-recorder.css">
-  </head>
-  <body>
-    <!-- Use the web component -->
-    <vidtreo-recorder></vidtreo-recorder>
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  onError: (error) => {
+    console.error('Stream error:', error.message);
+  },
+  onUploadError: (error) => {
+    console.error('Upload error:', error.message);
+  },
+});
 
-    <!-- Include the JS file -->
-    <script src="./dist/wc/vidtreo-recorder.js"></script>
-  </body>
-</html>
+try {
+  await recorder.startRecording({}, 'camera');
+  const result = await recorder.stopRecording();
+  console.log('Success:', result.uploadUrl);
+} catch (error) {
+  console.error('Recording error:', error);
+} finally {
+  recorder.cleanup();
+}
 ```
 
-#### CDN Usage
+### Recording with Disabled Features
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.example.com',
+  enableMute: false,
+  enablePause: false,
+  enableSourceSwitching: false,
+  enableDeviceChange: false,
+});
 
-After uploading the files to your CDN, reference them:
+await recorder.startRecording({}, 'camera');
 
-```html
-<link rel="stylesheet" href="https://your-cdn.com/vidtreo-recorder.css">
-<script src="https://your-cdn.com/vidtreo-recorder.js"></script>
+try {
+  recorder.muteAudio();
+} catch (error) {
+  console.error('Mute is disabled:', error.message);
+}
 
-<vidtreo-recorder></vidtreo-recorder>
+try {
+  recorder.pauseRecording();
+} catch (error) {
+  console.error('Pause is disabled:', error.message);
+}
+
+setTimeout(async () => {
+  await recorder.stopRecording();
+  recorder.cleanup();
+}, 10000);
 ```
 
-### Web Component Features
+## Web Component Usage
 
-- Drag and drop video file upload
-- Click to upload video files
-- Real-time transcoding progress
-- Download transcoded MP4 files
-- Play transcoded videos in a new window
-- Error handling and validation
+The web component is available in a separate package: [@vidtreo/recorder-wc](../recorder-wc/README.md)
 
-### Web Component Development
+For web component installation, usage, and examples, please refer to the [@vidtreo/recorder-wc documentation](../recorder-wc/README.md).
 
-To develop the web component with hot reload:
+## Advanced Usage
 
-```bash
-bun run dev:wc
+### Low-Level APIs
+
+For advanced use cases, the package exports lower-level APIs that provide more granular control:
+
+#### Transcoding
+
+```typescript
+import { transcodeVideo, DEFAULT_TRANSCODE_CONFIG } from '@vidtreo/recorder';
+
+const videoBlob = new Blob([videoData], { type: 'video/mp4' });
+const result = await transcodeVideo(videoBlob, {
+  width: 1920,
+  height: 1080,
+  fps: 60,
+  bitrate: 2000000,
+});
+
+console.log('Transcoded size:', result.buffer.byteLength);
+```
+
+#### RecorderController
+
+For fine-grained control over the recording process:
+
+```typescript
+import { RecorderController } from '@vidtreo/recorder';
+
+const controller = new RecorderController({
+  recording: {
+    onStateChange: (state) => console.log('State:', state),
+  },
+});
+
+await controller.initialize({
+  apiKey: 'your-api-key',
+  backendUrl: 'https://api.example.com',
+});
+```
+
+#### Stream Management
+
+```typescript
+import { CameraStreamManager } from '@vidtreo/recorder';
+
+const streamManager = new CameraStreamManager();
+await streamManager.startStream();
+const stream = streamManager.getStream();
 ```
 
-### Web Component File Structure
+## Configuration
+
+Video transcoding configuration is managed through your backend API. The recorder fetches configuration using the provided `apiKey` and `apiUrl`. Default transcoding settings include:
+
+- Format: MP4
+- Frame rate: 30 fps
+- Resolution: 1280x720
+- Bitrate: 500 kbps
+- Audio codec: AAC
+- Preset: Medium quality
+
+These defaults are used when backend configuration is unavailable or during initialization.
+
+## Browser Compatibility
+
+This package requires modern browser APIs for full functionality. The most critical requirement is support for the **WebCodecs API**, which enables real-time MP4 transcoding.
+
+### Full Support (All Features)
+
+The following browsers support all features including real-time MP4 transcoding:
+
+- **Chrome 94+** - Full support for all features
+- **Edge (Chromium) 94+** - Full support, same as Chrome
+- **Opera 80+** - Full support, Chromium-based
+- **Brave 1.30+** - Full support, Chromium-based
+- **Vivaldi 5.0+** - Full support, Chromium-based
+- **Firefox 130+** - Full WebCodecs support
+- **Safari (macOS/iOS) 26.0+** - Full WebCodecs support
+
+### Partial Support (Core Features Only)
 
-- `src/components/vidtreo-recorder.wc.ts` - Web component source code
-- `src/styles/tailwind.css` - Tailwind CSS source
-- `vite.wc.config.ts` - Vite configuration for web component build
-- `dist/wc/` - Build output directory
+The following browsers support core recording features but may have limitations:
+
+- **Firefox 76-129** - AudioWorklet supported, but WebCodecs not available. Real-time MP4 transcoding unavailable; falls back to MediaRecorder (WebM format)
+- **Safari (macOS/iOS) 16.4-25.x** - Partial WebCodecs support; some codecs may not be available
+
+### Required Browser APIs
+
+- **WebCodecs API** - Required for real-time MP4 transcoding (via mediabunny)
+- **OffscreenCanvas** - Required for video frame processing
+- **AudioWorklet** - Required for audio processing and level analysis
+- **MediaRecorder API** - Used as fallback recording method
+- **Screen Capture API** (`getDisplayMedia`) - Required for screen recording
+- **MediaDevices API** (`getUserMedia`) - Required for camera/microphone access
+- **IndexedDB** - Required for persistent upload queue
+- **Storage API** - Required for storage quota management
+
+### Feature Support by Browser
+
+| Feature | Chrome 94+ | Edge 94+ | Firefox 130+ | Safari 26.0+ | Firefox 76-129 | Safari 16.4-25.x |
+|---------|------------|---------|--------------|--------------|---------------|------------------|
+| Camera Recording | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Screen Recording | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Real-time MP4 Transcoding | ✅ | ✅ | ✅ | ✅ | ❌ (WebM) | ⚠️ (Partial) |
+| Audio Level Analysis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Source Switching | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Device Switching | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Persistent Upload Queue | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+### Unsupported Browsers
+
+- Internet Explorer (all versions)
+- Firefox < 76 (missing AudioWorklet)
+- Safari < 14.1 (missing AudioWorklet)
+- Safari < 16.4 (missing OffscreenCanvas and WebCodecs)
+- Edge Legacy (pre-Chromium)
+- Chrome < 94 (missing WebCodecs)
+
+### Mobile Browser Support
+
+- **Chrome Android 94+** - Full support
+- **Samsung Internet 18.0+** - Full support
+- **Firefox Android 130+** - Full support
+- **Safari iOS 16.4+** - Partial support (WebCodecs partial)
+- **Safari iOS 26.0+** - Full support
+
+### Important Notes
+
+1. **HTTPS Required**: Media capture APIs require HTTPS (or localhost) in most browsers
+2. **User Permissions**: Camera, microphone, and screen capture require explicit user permission
+3. **Automatic Fallback**: The package automatically falls back to MediaRecorder when WebCodecs is unavailable (produces WebM instead of MP4)
+4. **Feature Detection**: The package includes feature detection and gracefully degrades functionality when APIs are unavailable
+
+For detailed browser compatibility information, API requirements, and known limitations, see [BROWSER_COMPATIBILITY.md](./BROWSER_COMPATIBILITY.md).
 
 ## License
 
 MIT
-