local-transcription/DEBUG_4_SECOND_LAG.md

# Debugging the 4-Second Server Sync Lag

## The Issue

Transcription appears **instantly** in local app, but takes **4 seconds** to appear on the server display.

## Debug Logging Now Active

I've added timing logs to track exactly where the delay is happening.

### What You'll See

**In Python App Console:**
```
[GUI] Sending to server sync: 'Hello everyone...'
[GUI] Queued for sync in: 0.2ms
[Server Sync] Queue delay: 15ms
[Server Sync] HTTP request: 89ms, Status: 200
```

**In Node.js Server Console:**
```
[2025-12-26T...] Transcription received: "Hello everyone..." (verify: 2ms, add: 5ms, total: 7ms)
[Broadcast] Sent to 1 client(s) in room "test" (0ms)
```

**In Browser Console (display page):**
- Open DevTools → Console
- Watch for WebSocket messages

---

## Step-by-Step Debugging

### Step 1: Restart Everything with Logging

```bash
# Terminal 1: Start Node.js server
cd server/nodejs
npm start

# Terminal 2: Start Python app
cd /path/to/local-transcription
uv run python main.py

# Terminal 3: Open display in browser
# http://localhost:3000/display?room=YOUR_ROOM
# Open DevTools (F12) → Console tab
```

### Step 2: Speak and Watch Timestamps

1. Start transcription in Python app
2. Say something: "Testing one two three"
3. **Note the time** it appears in the Python app
4. **Note the time** it appears in the browser
5. Check all three consoles for logs

---

## Possible Causes & Solutions

### Cause 1: WebSocket Not Connected

**Symptom in Node.js console:**
```
[Broadcast] Sent to 0 client(s) in room "test" (0ms)  ← No clients!
```

**Solution:** Refresh the browser display page.

---

### Cause 2: Wrong Room Name

**Symptom:**
- Python app sends to room "my-room"
- Browser opens room "my-room-123"

**Solution:** Make sure room names match exactly (case-sensitive!)

---

### Cause 3: Browser Tab Backgrounded (Tab Throttling)

**Symptom:**
- WebSocket receives messages immediately
- But browser delays rendering (check console timestamps)

**Solution:**
- Keep display tab **in foreground**
- Or disable tab throttling in Chrome:
  1. chrome://flags/#calculate-native-win-occlusion
  2. Set to "Disabled"
  3. Restart Chrome

---

### Cause 4: PassphraseHash Caching Delay

**Symptom in Node.js console:**
```
(verify: 3000ms, add: 5ms, total: 3005ms)  ← 3 seconds in verify!
```

**Cause:** bcrypt password hashing is slow

**Solution:** The first request creates the room and hashes the passphrase (slow). Subsequent requests should be fast (<10ms). If EVERY request is slow:

```javascript
// In server.js, change bcrypt to faster hashing
// Find this line:
const hash = await bcrypt.hash(passphrase, 10);  // 10 rounds = slow!

// Change to:
const hash = await bcrypt.hash(passphrase, 4);   // 4 rounds = faster
```

Or use crypto.createHash for even faster (but less secure):
```javascript
const crypto = require('crypto');
const hash = crypto.createHash('sha256').update(passphrase).digest('hex');
```

---

### Cause 5: File I/O Blocking

**Symptom in Node.js console:**
```
(verify: 5ms, add: 3000ms, total: 3005ms)  ← 3 seconds in add!
```

**Cause:** Writing to disk is slow

**Solution:** Use in-memory only (faster, but loses data on restart):

```javascript
// Comment out these lines in addTranscription():
// await saveRoom(room, roomData);  // Skip disk writes

// Room data stays in memory (rooms Map)
```

---

### Cause 6: Network Latency

**Symptom in Python console:**
```
[Server Sync] HTTP request: 3000ms, Status: 200  ← 3 seconds!
```

**Possible causes:**
- Server on remote network
- VPN enabled
- Firewall/antivirus scanning traffic
- DNS resolution slow

**Test:**
```bash
# Test direct connection speed
time curl -X POST http://localhost:3000/api/send \
  -H "Content-Type: application/json" \
  -d '{"room":"test","passphrase":"test","user_name":"CLI","text":"test","timestamp":"12:34:56"}'

# Should complete in < 100ms for localhost
```

**Solution:**
- Use localhost (not 127.0.0.1 or hostname)
- Disable VPN temporarily
- Add firewall exception

---

### Cause 7: Python GIL / Thread Starvation

**Symptom in Python console:**
```
[GUI] Queued for sync in: 0.2ms
[Server Sync] Queue delay: 4000ms  ← 4 seconds between queue and send!
```

**Cause:** Background thread not getting CPU time

**Unlikely** but possible if:
- CPU usage is 100%
- Many other Python threads running
- Running on single-core system

**Solution:**
- Close other applications
- Use `tiny` model (less CPU)
- Increase thread priority (advanced)

---

### Cause 8: Browser Rendering Delay

**Symptom:**
- WebSocket message received instantly (check console)
- But visual update delayed

**Debugging:**
Add to display page JavaScript:
```javascript
ws.onmessage = (event) => {
    console.log('WS received at:', new Date().toISOString(), event.data);
    const data = JSON.parse(event.data);
    addTranscription(data);
};
```

**Solution:**
- Use simpler CSS (remove animations)
- Disable fade effects (`fade=0` in URL)
- Use Chrome instead of Firefox

---

## Quick Test Commands

### Test 1: Direct Server Test
```bash
cd server
./test-server-timing.sh http://localhost:3000/api/send test test
```

**Expected:** All messages ~50-100ms

### Test 2: Python Client Test
With Python app running and transcribing, check console output for timing.

### Test 3: WebSocket Test
Open browser console on display page:
```javascript
// Check WebSocket state
console.log('WebSocket state:', ws.readyState);
// 0 = CONNECTING, 1 = OPEN, 2 = CLOSING, 3 = CLOSED

// Check if messages received
ws.onmessage = (e) => console.log('Received:', new Date().toISOString(), e.data);
```

---

## Collecting Debug Info

Run your Python app and speak a sentence, then collect:

**1. Python Console Output:**
```
[GUI] Sending to server sync: 'Hello...'
[GUI] Queued for sync in: 0.2ms
[Server Sync] Queue delay: ???ms
[Server Sync] HTTP request: ???ms, Status: ???
```

**2. Node.js Console Output:**
```
[2025-12-26...] Transcription received: "..." (verify: ???ms, add: ???ms, total: ???ms)
[Broadcast] Sent to ??? client(s) in room "..." (???ms)
```

**3. Browser Console:**
- Any WebSocket errors?
- Any JavaScript errors?

**4. Network Tab (Browser DevTools):**
- Is WebSocket connected? (should show "101 Switching Protocols")
- Any pending/failed requests?

---

## Expected Timings

**Good (< 200ms total):**
```
Python:  Queue delay: 10ms, HTTP: 80ms
Node.js: verify: 2ms, add: 3ms, total: 5ms
Browser: Instant display
```

**Bad (> 1000ms):**
```
Python:  Queue delay: 3000ms, HTTP: 80ms  ← Problem in Python thread!
Node.js: verify: 2ms, add: 3ms, total: 5ms
```

or

```
Python:  Queue delay: 10ms, HTTP: 3000ms  ← Network problem!
Node.js: verify: 2ms, add: 3ms, total: 5ms
```

or

```
Python:  Queue delay: 10ms, HTTP: 80ms
Node.js: verify: 3000ms, add: 3ms, total: 3003ms  ← bcrypt too slow!
```

---

## Most Likely Cause

Based on "4 seconds exactly", I suspect:

### **Browser Tab Throttling**

Chrome/Firefox throttle background tabs:
- Timers delayed to 1-second intervals
- WebSocket messages buffered
- Rendering paused

**Test:**
1. Put display tab in **separate window**
2. Keep it **visible** (not minimized)
3. Try again

**Or:**
Open in OBS (OBS doesn't throttle browser sources)

---

## If Still 4 Seconds After Debugging

Collect the debug output and we'll analyze it to find the exact bottleneck!