pediatric-ai-scribe-v3/BROWSER_WHISPER_TROUBLESHOOTING.md

# Browser Whisper Troubleshooting

## 🎙️ What is Browser Whisper?

Browser Whisper is an **optional** client-side transcription feature that runs entirely in your browser using WebAssembly. It provides:
- ✅ Zero network transmission (HIPAA-safe)
- ✅ No API costs
- ✅ Works offline
- ✅ Privacy-first (audio never leaves device)

**However**, it requires downloading AI models from CDN servers.

---

## ⚠️ Common Issue: CDN Blocked

### Error Message:
```
NetworkError: Failed to execute 'importScripts' on 'WorkerGlobalScope':
The script at 'https://cdn.jsdelivr.net/npm/@xenova/transformers@2.17.2' failed to load.
```

### What This Means:
Your network/firewall is blocking access to:
- `cdn.jsdelivr.net` (JavaScript library CDN)
- `cdn-lfs.huggingface.co` (AI model files)

### Why It Happens:
1. **Corporate firewall** - Many organizations block CDN domains
2. **Browser extensions** - Ad blockers, privacy tools may block CDN
3. **Network proxy** - Company proxy might filter JavaScript CDN
4. **CSP restrictions** - Very strict Content Security Policy

---

## ✅ Solutions

### Option 1: Use Server Transcription (Recommended)

**Browser Whisper is optional!** The app works perfectly fine with server-side transcription.

**Server transcription providers:**
- Google Gemini (via Vertex AI) - HIPAA-eligible
- AWS Transcribe - HIPAA-eligible
- OpenAI Whisper - Fast, accurate
- LiteLLM - Routes to any provider

**To use server transcription:**
1. Go to Settings → Browser Transcription
2. **Leave it disabled** (or if stuck, disable it)
3. Record audio normally - will use server

**Advantages:**
- More accurate (larger models)
- No download needed
- Works immediately
- Professional grade

### Option 2: Whitelist CDN Domains

If you control your network/firewall, whitelist these domains:

```
cdn.jsdelivr.net
cdn-lfs.huggingface.co
cdn-lfs-us-1.huggingface.co
cdn-lfs-us-2.huggingface.co
huggingface.co
```

**For corporate IT:**
- These are legitimate AI/JavaScript CDNs
- Used by major companies worldwide
- No security risk (public CDN content)
- Required only for browser-based AI features

### Option 3: Disable Browser Extensions

Try disabling:
- Ad blockers (uBlock Origin, AdBlock Plus)
- Privacy extensions (Privacy Badger, Ghostery)
- Script blockers (NoScript, ScriptSafe)

Then refresh and try again.

### Option 4: Try Different Browser

Some browsers have stricter security:
- ✅ **Chrome** - Best compatibility
- ✅ **Edge** - Works well
- ⚠️ **Firefox** - May block CDN
- ❌ **Safari** - Limited WebAssembly support

---

## 🧪 How to Test If It's Working

### Test 1: Check CDN Access
```bash
# From your computer, run:
curl -I https://cdn.jsdelivr.net/npm/@xenova/transformers@2.17.2

# Should return: HTTP/2 200
# If 403 or timeout: CDN is blocked
```

### Test 2: Browser Console
1. Open DevTools (F12)
2. Go to Console tab
3. Settings → Browser Transcription
4. Click "Pre-download model"
5. Watch for:
   ```
   ✅ [WhisperWorker] Transformers library loaded successfully
   OR
   ❌ NetworkError: Failed to load
   ```

### Test 3: Network Tab
1. Open DevTools (F12)
2. Go to Network tab
3. Click "Pre-download model"
4. Look for requests to:
   - `cdn.jsdelivr.net` (should be 200 OK)
   - `cdn-lfs.huggingface.co` (should be 200 OK)
5. If blocked: Status will show "failed" or "blocked"

---

## 📊 When to Use Each Option

| Scenario | Recommendation | Why |
|----------|---------------|-----|
| Corporate network | **Server transcription** | CDN likely blocked |
| Home network | **Browser Whisper** | Fast, free, private |
| Mobile device | **Server transcription** | Limited storage/memory |
| Offline use needed | **Browser Whisper** | Works without internet (after initial download) |
| High accuracy needed | **Server transcription** | Larger models available |
| Maximum privacy | **Browser Whisper** | Audio never leaves device |
| Can't access CDN | **Server transcription** | No choice - CDN blocked |

---

## 🔧 Technical Details

### What Gets Downloaded (First Time Only):

**Tiny model** (~39 MB):
- onnx-runtime.wasm (~10 MB)
- whisper-tiny.en model files (~29 MB)
- Cached in browser IndexedDB (permanent)

**Base model** (~74 MB):
- Larger model, better accuracy

**Small model** (~244 MB):
- Best quality, slower processing

### Where It's Stored:
- **Location:** Browser IndexedDB
- **Persistence:** Permanent (until you clear browser data)
- **Shared:** Across all tabs/windows for this domain
- **Size:** Selected model size (39/74/244 MB)

### Performance:
- **Tiny:** 2-3 seconds per 30-second clip
- **Base:** 3-5 seconds per 30-second clip
- **Small:** 6-10 seconds per 30-second clip

---

## ❓ FAQ

**Q: Is Browser Whisper required?**
A: No! It's completely optional. Server transcription works great.

**Q: Why doesn't it work on my corporate network?**
A: Most corporate firewalls block CDN domains for security. Use server transcription instead.

**Q: Can I download the models manually?**
A: Not easily - they're optimized for CDN delivery. Use server transcription if CDN is blocked.

**Q: Will server transcription cost money?**
A: Depends on your provider:
- Google Vertex AI: ~$0.005 per minute
- AWS Transcribe: ~$0.024 per minute
- OpenAI: $0.006 per minute
- Very affordable for typical use

**Q: Is server transcription HIPAA-safe?**
A: Yes, if using:
- Google Vertex AI (with BAA)
- AWS Transcribe (with BAA)
- Azure OpenAI (with BAA)

OpenAI Whisper direct is NOT HIPAA-eligible.

**Q: Can I use both?**
A: Yes! Enable Browser Whisper in Settings. If it fails (CDN blocked), it automatically falls back to server transcription.

**Q: How do I know which one is being used?**
A: Check the toast notification after recording:
- "Transcribed locally" = Browser Whisper
- "Transcribed via google-gemini/aws/openai" = Server

---

## 🚀 Recommended Setup

### For Maximum Privacy (Home Network):
1. Enable Browser Whisper
2. Choose "Tiny" model (fast, good enough for dictation)
3. Pre-download model
4. Use offline

### For Corporate/Clinical Use:
1. Keep Browser Whisper **disabled**
2. Configure server transcription:
   ```bash
   # In .env:
   TRANSCRIBE_PROVIDER=google
   GOOGLE_VERTEX_PROJECT=your-project
   ```
3. Use with BAA for HIPAA compliance

### For Best Accuracy:
1. Use server transcription
2. Configure Google Gemini 2.0 Flash or AWS Transcribe Medical
3. Audio quality + large models = best results

---

## 🛠️ Still Having Issues?

1. **Check console logs:** DevTools → Console → Look for `[BrowserWhisper]` errors
2. **Check network logs:** DevTools → Network → Filter by `jsdelivr` or `huggingface`
3. **Verify server transcription works:** Just disable Browser Whisper and record
4. **Contact IT:** Ask to whitelist CDN domains (if you need Browser Whisper)

**Remember:** Browser Whisper is a nice-to-have feature. Server transcription is the primary, production-ready method that works everywhere!