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

# 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:

   # 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!