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/COMPARISON.md
+++ b/server/COMPARISON.md
@@ -0,0 +1,308 @@
+# Multi-User Server Comparison
+
+## TL;DR: Which Should You Use?
+
+| Situation | Recommended Solution |
+|-----------|---------------------|
+| **Shared hosting (cPanel, etc.)** | **PHP Polling** (display-polling.php) |
+| **VPS or cloud server** | **Node.js** (best performance) |
+| **Quick test/demo** | **PHP Polling** (easiest) |
+| **Production with many users** | **Node.js** (most reliable) |
+| **No server access** | Use local-only mode |
+
+## Detailed Comparison
+
+### 1. PHP with SSE (Original - server.php + display.php)
+
+**Status:** ⚠️ **PROBLEMATIC** - Not recommended
+
+**Problems:**
+- PHP-FPM buffers output (SSE doesn't work)
+- Apache/Nginx proxy timeouts
+- Shared hosting often blocks long connections
+- High resource usage (one PHP process per viewer)
+
+**When it might work:**
+- Only with specific Apache configurations
+- Not on shared hosting with PHP-FPM
+- Requires `ProxyTimeout` settings
+
+**Verdict:** ❌ Avoid unless you have full server control and can configure Apache properly
+
+---
+
+### 2. PHP with Polling (NEW - display-polling.php)
+
+**Status:** ✅ **RECOMMENDED for PHP**
+
+**Pros:**
+- ✅ Works on ANY shared hosting
+- ✅ No buffering issues
+- ✅ No special configuration needed
+- ✅ Simple to deploy (just upload files)
+- ✅ Uses standard HTTP requests
+
+**Cons:**
+- ❌ Higher latency (1-2 seconds)
+- ❌ More server requests (polls every second)
+- ❌ Slightly higher bandwidth
+
+**Performance:**
+- Latency: 1-2 seconds
+- Max users: 20-30 concurrent viewers
+- Resource usage: Moderate
+
+**Best for:**
+- Shared hosting (cPanel, Bluehost, etc.)
+- Quick deployment
+- Small to medium groups
+
+**Setup:**
+```bash
+# Just upload these files:
+server.php
+display-polling.php  # ← Use this instead of display.php
+config.php
+```
+
+**OBS URL:**
+```
+https://your-site.com/transcription/display-polling.php?room=ROOM&fade=10
+```
+
+---
+
+### 3. Node.js Server (NEW - server/nodejs/)
+
+**Status:** ⭐ **BEST PERFORMANCE**
+
+**Pros:**
+- ✅ Native WebSocket support
+- ✅ Real-time updates (< 100ms latency)
+- ✅ Handles 100+ concurrent connections easily
+- ✅ Lower resource usage
+- ✅ No buffering issues
+- ✅ Event-driven architecture
+
+**Cons:**
+- ❌ Requires VPS or cloud server
+- ❌ Need to install Node.js
+- ❌ More setup than PHP
+
+**Performance:**
+- Latency: < 100ms
+- Max users: 500+ concurrent
+- Resource usage: Very low (~50MB RAM)
+
+**Best for:**
+- Production deployments
+- Large groups (10+ streamers)
+- Professional use
+- Anyone with a VPS
+
+**Setup:**
+```bash
+cd server/nodejs
+npm install
+npm start
+```
+
+**Free hosting options:**
+- Railway.app (free tier)
+- Heroku (free tier)
+- Fly.io (free tier)
+- Any $5/month VPS (DigitalOcean, Linode)
+
+**OBS URL:**
+```
+http://your-server.com:3000/display?room=ROOM&fade=10
+```
+
+---
+
+## Feature Comparison Matrix
+
+| Feature | PHP SSE | PHP Polling | Node.js |
+|---------|---------|-------------|---------|
+| **Real-time** | ⚠️ Should be, but breaks | ⚠️ 1-2s delay | ✅ < 100ms |
+| **Reliability** | ❌ Buffering issues | ✅ Very reliable | ✅ Very reliable |
+| **Shared Hosting** | ❌ Usually fails | ✅ Works everywhere | ❌ Needs VPS |
+| **Setup Difficulty** | 🟡 Medium | 🟢 Easy | 🟡 Medium |
+| **Max Users** | 10 | 30 | 500+ |
+| **Resource Usage** | High | Medium | Low |
+| **Latency** | Should be instant, but... | 1-2 seconds | < 100ms |
+| **Cost** | $5-10/month hosting | $5-10/month hosting | Free - $5/month |
+
+---
+
+## Migration Guide
+
+### From PHP SSE to PHP Polling
+
+**Super easy - just change the URL:**
+
+Old:
+```
+https://your-site.com/transcription/display.php?room=ROOM
+```
+
+New:
+```
+https://your-site.com/transcription/display-polling.php?room=ROOM
+```
+
+Everything else stays the same! The desktop app doesn't need changes.
+
+---
+
+### From PHP to Node.js
+
+**1. Deploy Node.js server** (see server/nodejs/README.md)
+
+**2. Update desktop app settings:**
+
+Old (PHP):
+```
+Server URL: https://your-site.com/transcription/server.php
+```
+
+New (Node.js):
+```
+Server URL: http://your-server.com:3000/api/send
+```
+
+**3. Update OBS browser source:**
+
+Old (PHP):
+```
+https://your-site.com/transcription/display.php?room=ROOM
+```
+
+New (Node.js):
+```
+http://your-server.com:3000/display?room=ROOM&fade=10
+```
+
+---
+
+## Testing Your Setup
+
+### Test PHP Polling
+
+1. Upload files to server
+2. Visit: `https://your-site.com/transcription/server.php`
+   - Should see JSON response
+3. Visit: `https://your-site.com/transcription/display-polling.php?room=test`
+   - Should see "🟡 Waiting for data..."
+4. Send a test message:
+   ```bash
+   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"
+     }'
+   ```
+5. Display should show "Hello World" within 1-2 seconds
+
+### Test Node.js
+
+1. Start server: `npm start`
+2. Visit: `http://localhost:3000`
+   - Should see JSON response
+3. Visit: `http://localhost:3000/display?room=test`
+   - Should see "⚫ Connecting..." then "🟢 Connected"
+4. Send test message (same curl as above, but to `http://localhost:3000/api/send`)
+5. Display should show message instantly
+
+---
+
+## Troubleshooting
+
+### PHP Polling Issues
+
+**"Status stays yellow"**
+- Room doesn't exist yet
+- Send a message from desktop app first
+
+**"Gets 500 error"**
+- Check PHP error logs
+- Verify `data/` directory is writable
+
+**"Slow updates (5+ seconds)"**
+- Increase poll interval: `?poll=500` (500ms)
+- Check server load
+
+### Node.js Issues
+
+**"Cannot connect"**
+- Check firewall allows port 3000
+- Verify server is running: `curl http://localhost:3000`
+
+**"WebSocket failed"**
+- Check browser console for errors
+- Try different port
+- Check reverse proxy settings if using Nginx
+
+---
+
+## Recommendations by Use Case
+
+### Solo Streamer (Local Only)
+**Use:** Built-in web server (no multi-user server needed)
+- Just run the desktop app
+- OBS: `http://localhost:8080`
+
+### 2-3 Friends on Shared Hosting
+**Use:** PHP Polling
+- Upload to your existing web hosting
+- Cost: $0 (use existing hosting)
+- Setup time: 5 minutes
+
+### 5+ Streamers, Want Best Quality
+**Use:** Node.js on VPS
+- Deploy to Railway.app (free) or DigitalOcean ($5/month)
+- Real-time updates
+- Professional quality
+
+### Large Event/Convention
+**Use:** Node.js on cloud
+- Deploy to AWS/Azure/GCP
+- Use load balancer for redundancy
+- Can handle hundreds of users
+
+---
+
+## Cost Breakdown
+
+### PHP Polling
+- **Shared hosting:** $5-10/month (or free if you already have hosting)
+- **Total:** $5-10/month
+
+### Node.js
+- **Free options:**
+  - Railway.app (500 hours/month free)
+  - Heroku (free dyno)
+  - Fly.io (free tier)
+- **Paid options:**
+  - DigitalOcean Droplet: $5/month
+  - Linode: $5/month
+  - AWS EC2 t2.micro: $8/month (or free tier)
+- **Total:** $0-8/month
+
+### Just Use Local Mode
+- **Cost:** $0
+- **Limitation:** Only shows your own transcriptions (no multi-user sync)
+
+---
+
+## Final Recommendation
+
+**For most users:** Start with **PHP Polling** on shared hosting. It works reliably and is dead simple.
+
+**If you want the best:** Use **Node.js** - it's worth the extra setup for the performance.
+
+**For testing:** Use **local mode** (no server) - built into the desktop app.