Update to support sync captions

2025-12-26 16:15:52 -08:00
parent 2870d45bdc
commit c28679acb6
12 changed files with 4513 additions and 0 deletions
--- a/server/QUICK_FIX.md
+++ b/server/QUICK_FIX.md
@@ -0,0 +1,218 @@
+# Quick Fix for Multi-User Display Issues
+
+## The Problem
+
+Your PHP SSE (Server-Sent Events) setup isn't working because:
+1. **PHP-FPM buffers output** - Shared hosting uses PHP-FPM which buffers everything
+2. **Apache/Nginx timeouts** - Proxy kills long connections
+3. **SSE isn't designed for PHP** - PHP processes are meant to be short-lived
+
+## The Solutions (in order of recommendation)
+
+---
+
+### ✅ Solution 1: Use PHP Polling (Easiest Fix)
+
+**What changed:** Instead of SSE (streaming), use regular HTTP polling every 1 second
+
+**Files affected:**
+- **Keep:** `server.php`, `config.php` (no changes needed)
+- **Replace:** Use `display-polling.php` instead of `display.php`
+
+**Setup:**
+1. Upload `display-polling.php` to your server
+2. Change your OBS Browser Source URL from:
+   ```
+   OLD: https://your-site.com/transcription/display.php?room=ROOM
+   NEW: https://your-site.com/transcription/display-polling.php?room=ROOM
+   ```
+3. Done! No other changes needed.
+
+**Pros:**
+- ✅ Works on ANY shared hosting
+- ✅ No server configuration needed
+- ✅ Uses your existing setup
+- ✅ 5-minute fix
+
+**Cons:**
+- ⚠️ 1-2 second latency (vs instant with WebSocket)
+- ⚠️ More server requests (but minimal impact)
+
+**Performance:** Good for 2-20 concurrent users
+
+---
+
+### ⭐ Solution 2: Use Node.js Server (Best Performance)
+
+**What changed:** Switch from PHP to Node.js - designed for real-time
+
+**Setup:**
+1. Get a VPS (or use free hosting like Railway.app)
+2. Install Node.js:
+   ```bash
+   cd server/nodejs
+   npm install
+   npm start
+   ```
+3. Update desktop app Server URL to:
+   ```
+   http://your-server.com:3000/api/send
+   ```
+4. Update OBS URL to:
+   ```
+   http://your-server.com:3000/display?room=ROOM
+   ```
+
+**Pros:**
+- ✅ Real-time (< 100ms latency)
+- ✅ Handles 100+ users easily
+- ✅ Native WebSocket support
+- ✅ Lower resource usage
+- ✅ Can use free hosting (Railway, Heroku, Fly.io)
+
+**Cons:**
+- ❌ Requires VPS or cloud hosting (can't use shared hosting)
+- ❌ More setup than PHP
+
+**Performance:** Excellent for any number of users
+
+**Free Hosting Options:**
+- Railway.app (easiest - just connect GitHub)
+- Heroku (free tier)
+- Fly.io (free tier)
+
+---
+
+### 🔧 Solution 3: Fix PHP SSE (Advanced - Not Recommended)
+
+**Only if you have full server control and really want SSE**
+
+This requires:
+1. Apache configuration changes
+2. Disabling output buffering
+3. Increasing timeouts
+
+See `apache-sse-config.conf` for details.
+
+**Not recommended because:** It's complex, fragile, and PHP polling is easier and more reliable.
+
+---
+
+## Quick Comparison
+
+| Solution | Setup Time | Reliability | Latency | Works on Shared Hosting? |
+|----------|-----------|-------------|---------|-------------------------|
+| **PHP Polling** | 5 min | ⭐⭐⭐⭐⭐ | 1-2s | ✅ Yes |
+| **Node.js** | 30 min | ⭐⭐⭐⭐⭐ | < 100ms | ❌ No (needs VPS) |
+| **PHP SSE** | 2 hours | ⭐⭐ | Should be instant | ❌ Rarely |
+
+---
+
+## Testing Your Fix
+
+### Test PHP Polling
+
+1. Run the test script:
+   ```bash
+   cd server
+   ./test-server.sh
+   ```
+
+2. Or manually:
+   ```bash
+   # Send a test message
+   curl -X POST "https://your-site.com/transcription/server.php?action=send" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "room": "test",
+       "passphrase": "testpass",
+       "user_name": "TestUser",
+       "text": "Hello World",
+       "timestamp": "12:34:56"
+     }'
+
+   # Open in browser:
+   https://your-site.com/transcription/display-polling.php?room=test
+
+   # Should see "Hello World" appear within 1-2 seconds
+   ```
+
+### Test Node.js
+
+1. Start server:
+   ```bash
+   cd server/nodejs
+   npm install
+   npm start
+   ```
+
+2. Open browser:
+   ```
+   http://localhost:3000/display?room=test
+   ```
+
+3. Send test message:
+   ```bash
+   curl -X POST "http://localhost:3000/api/send" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "room": "test",
+       "passphrase": "testpass",
+       "user_name": "TestUser",
+       "text": "Hello World",
+       "timestamp": "12:34:56"
+     }'
+   ```
+
+4. Should see message appear **instantly**
+
+---
+
+## My Recommendation
+
+**Start with PHP Polling** (Solution 1):
+- Upload `display-polling.php`
+- Change OBS URL
+- Test it out
+
+**If you like it and want better performance**, migrate to Node.js (Solution 2):
+- Takes 30 minutes
+- Much better performance
+- Can use free hosting
+
+**Forget about PHP SSE** (Solution 3):
+- Too much work
+- Unreliable
+- Not worth it
+
+---
+
+## Files You Need
+
+### For PHP Polling
+- ✅ `server.php` (already have)
+- ✅ `config.php` (already have)
+- ✅ `display-polling.php` (NEW - just created)
+- ❌ `display.php` (don't use anymore)
+
+### For Node.js
+- ✅ `server/nodejs/server.js` (NEW)
+- ✅ `server/nodejs/package.json` (NEW)
+- ✅ `server/nodejs/README.md` (NEW)
+
+---
+
+## Need Help?
+
+1. Read [COMPARISON.md](COMPARISON.md) for detailed comparison
+2. Read [server/nodejs/README.md](nodejs/README.md) for Node.js setup
+3. Run `./test-server.sh` to diagnose issues
+4. Check browser console for errors
+
+---
+
+## Bottom Line
+
+**Your SSE display doesn't work because PHP + shared hosting + SSE = bad combo.**
+
+**Use PHP Polling (1-2s delay) or Node.js (instant).** Both work reliably.