@vidtreo/recorder 1.4.0 → 1.5.0

package/README.md

@@ -58,6 +58,7 @@ Creates a new recorder instance with the specified configuration.
 - `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.onAudioWarning` (optional): Callback invoked when an audio issue is detected during recording. Receives an `AudioWarning` object. See [Audio Warnings](#audio-warnings) for details
 - `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
@@ -218,6 +219,7 @@ interface VidtreoRecorderConfig {
   onUploadError?: (error: Error) => void;
   onRecordingStart?: () => void;
   onRecordingStop?: () => void;
+  onAudioWarning?: (warning: AudioWarning) => void;
   onError?: (error: Error) => void;
 }
 ```
@@ -267,6 +269,17 @@ interface AvailableDevices {
 }
 ```
 
+### AudioWarning
+
+```typescript
+type AudioWarning =
+  | { code: 'audio.no-signal'; durationMs: number }
+  | { code: 'audio.no-chunks'; durationMs: number }
+  | { code: 'audio.low-signal'; peak: number; rms: number }
+  | { code: 'audio.track-ended' }
+  | { code: 'audio.track-muted-by-browser' };
+```
+
 ### CameraConstraints
 
 ```typescript
@@ -277,6 +290,112 @@ interface CameraConstraints {
 }
 ```
 
+## User-Facing Messages
+
+The SDK emits structured events for common issues. Your app should listen and display appropriate UX for each.
+
+### Audio Warnings
+
+Set `onAudioWarning` in the constructor config. Each warning fires **once per recording session** (deduped by code). Use these to show real-time feedback to the user.
+
+| Code | Meaning | Suggested UX |
+|------|---------|-------------|
+| `audio.no-signal` | Mic is producing silence for an extended period. `durationMs` indicates how long. | "Microphone not detected. Check your mic is plugged in and selected." |
+| `audio.no-chunks` | No audio data received from the microphone for an extended period. `durationMs` indicates how long. | "No microphone input. Check microphone permissions and connection." |
+| `audio.low-signal` | Audio level is very low. `peak` and `rms` contain measured levels (0–1 range). | "Audio is very quiet. Speak louder or move closer to the microphone." |
+| `audio.track-ended` | The audio track ended unexpectedly (device disconnected or revoked). | "Microphone disconnected. Reconnect and restart recording." |
+| `audio.track-muted-by-browser` | Browser muted the track automatically (e.g., browser-level mute or policy). | "Microphone muted by browser. Check browser mic settings." |
+
+Example:
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  onAudioWarning: (warning) => {
+    switch (warning.code) {
+      case 'audio.no-signal':
+      case 'audio.no-chunks':
+        showToast('No microphone input detected. Check your mic.');
+        break;
+      case 'audio.low-signal':
+        showToast('Audio is very quiet. Speak louder or check your mic.');
+        break;
+      case 'audio.track-ended':
+        showToast('Microphone disconnected. Reconnect and try again.');
+        break;
+      case 'audio.track-muted-by-browser':
+        showToast('Microphone muted by browser. Check browser settings.');
+        break;
+    }
+  },
+});
+```
+
+### No Video Signal
+
+The SDK emits an error via `onError` when no video frames arrive from the camera:
+
+- Error message contains `video-first-frame-timeout`
+- Cause: camera in use by another app, camera permission revoked, or hardware failure
+- Suggested UX: "Camera not responding. Close other apps using the camera and try again."
+
+```typescript
+const recorder = new VidtreoRecorder({
+  apiKey: 'your-api-key',
+  onError: (error) => {
+    if (error.message.includes('video-first-frame-timeout')) {
+      showToast('Camera not responding. Close other apps using the camera.');
+    }
+  },
+});
+```
+
+### Storage Restricted
+
+Storage issues surface in two ways:
+
+1. **Quota exceeded** during upload queue write: error message contains `Storage quota exceeded`. Suggested UX: "Device storage is full. Free up space to save recordings."
+2. **Proactive quota check** via `QuotaManager` (exported from this package):
+
+```typescript
+import { QuotaManager } from '@vidtreo/recorder';
+
+const quotaManager = new QuotaManager();
+const quota = await quotaManager.getQuota();
+
+if (await quotaManager.shouldWarn()) {
+  showToast(`Storage usage at ${Math.round(quota.percentage)}%. Free up space.`);
+}
+
+if (await quotaManager.isCritical()) {
+  showToast('Storage critically low. Recording may fail to save.');
+}
+```
+
+- `shouldWarn()` triggers at 80% usage (configurable threshold)
+- `isCritical()` triggers at 95% usage (configurable threshold)
+
+### Unsupported Browser
+
+Use `validateBrowserSupport()` before initializing the recorder:
+
+```typescript
+import { validateBrowserSupport } from '@vidtreo/recorder';
+
+try {
+  validateBrowserSupport();
+} catch (error) {
+  // error.code === 'browser.unsupported'
+  // error.browserName — detected browser name
+  // error.browserVersion — detected version
+  // error.missingCapabilities — list of missing APIs
+  // error.resolutionStage — 'policy' (known unsupported) or 'feature-preflight' (missing API)
+  showToast('Your browser is not supported. Use Chrome, Edge, or Safari 26+.');
+}
+```
+
+For richer error text, use `getBrowserErrorText()` and `getCameraErrorText()` from `@vidtreo/recorder` with your own translations (see exported types `AudioErrorTranslations`, `BrowserErrorLinkContent`).
+
 ## Usage Examples
 
 ### Basic Recording Workflow
@@ -824,14 +943,12 @@ The following browsers support all features including real-time MP4 transcoding:
 - **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)
 
 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
@@ -851,20 +968,23 @@ The following browsers support core recording features but may have limitations:
 
 ### 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 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Feature | Chrome 94+ | Edge 94+ | Safari 26.0+ | Safari 16.4-25.x |
+|---------|------------|---------|--------------|------------------|
+| Camera Recording | ✅ | ✅ | ✅ | ✅ |
+| Screen Recording | ✅ | ✅ | ✅ | ✅ |
+| Real-time MP4 Transcoding | ✅ | ✅ | ✅ | ⚠️ (Partial) |
+| Audio Level Analysis | ✅ | ✅ | ✅ | ✅ |
+| Source Switching | ✅ | ✅ | ✅ | ✅ |
+| Device Switching | ✅ | ✅ | ✅ | ✅ |
+| Persistent Upload Queue | ✅ | ✅ | ✅ | ✅ |
 
 ### Unsupported Browsers
 
 - Internet Explorer (all versions)
-- Firefox < 76 (missing AudioWorklet)
+- Firefox (all versions)
+- Samsung Internet
+- Android WebView and in-app browsers
+- Google App browser
 - Safari < 14.1 (missing AudioWorklet)
 - Safari < 16.4 (missing OffscreenCanvas and WebCodecs)
 - Edge Legacy (pre-Chromium)
@@ -873,10 +993,13 @@ The following browsers support core recording features but may have limitations:
 ### Mobile Browser Support
 
 - **Chrome Android 94+** - Full support
-- **Samsung Internet 18.0+** - Full support
-- **Firefox Android 130+** - Full support
+- **Edge Android 94+** - Full support
 - **Safari iOS 16.4+** - Partial support (WebCodecs partial)
 - **Safari iOS 26.0+** - Full support
+- **Samsung Internet** - Not supported
+- **Android WebView and in-app browsers** - Not supported
+- **Google App browser** - Not supported
+- **Firefox Android** - Not supported
 
 ### Important Notes