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

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

// 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):

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

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

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

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

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:

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