Add comprehensive WebSocket testing suite and documentation

TEST_WEBSOCKET.md

@@ -0,0 +1,236 @@
+# WebSocket Testing Guide
+
+## Quick Test Methods
+
+### 1. **Python Test Suite** (Recommended)
+```bash
+python3 test_websocket.py
+```
+
+Tests:
+- ✅ Connection establishment
+- ✅ Request/response handling
+- ✅ Latency measurement
+- ✅ Audio streaming and saving
+
+---
+
+### 2. **Command Line with wscat**
+
+Install wscat:
+```bash
+npm install -g wscat
+```
+
+Test connection:
+```bash
+wscat -c wss://ebitlogix-parler-tts-api.hf.space/ws/tts
+```
+
+Then send JSON:
+```json
+{"text":"سلام دنیا","speaker":"Divya"}
+```
+
+You should see:
+```
+> {"text":"سلام دنیا","speaker":"Divya"}
+< {"status":"generating","message":"Generating audio for speaker Divya..."}
+< [binary audio chunk 1]
+< [binary audio chunk 2]
+< [binary audio chunk 3]
+< {"status":"complete","chunks_sent":5}
+```
+
+---
+
+### 3. **JavaScript/Node Test**
+
+```javascript
+const WebSocket = require('ws');
+
+const ws = new WebSocket('wss://ebitlogix-parler-tts-api.hf.space/ws/tts');
+
+ws.on('open', () => {
+    console.log('✅ Connected');
+    
+    ws.send(JSON.stringify({
+        text: 'سلام دنیا',
+        speaker: 'Divya'
+    }));
+});
+
+ws.on('message', (data) => {
+    if (typeof data === 'string') {
+        console.log('📨 Status:', JSON.parse(data));
+    } else {
+        console.log('🔊 Audio chunk:', data.length, 'bytes');
+    }
+});
+
+ws.on('error', (err) => {
+    console.error('❌ Error:', err);
+});
+```
+
+---
+
+### 4. **Curl Test** (for connection only)
+```bash
+curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
+  -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
+  -H "Sec-WebSocket-Version: 13" \
+  https://ebitlogix-parler-tts-api.hf.space/ws/tts
+```
+
+---
+
+## Expected Responses
+
+### Success Response Flow:
+```
+1. Connection accepted (WebSocket upgrade)
+   ↓
+2. Status message: {"status":"generating",...}
+   ↓
+3. Audio chunks (binary data) arriving in real-time
+   ↓
+4. Complete message: {"status":"complete","chunks_sent":N}
+   ↓
+5. Connection closes
+```
+
+### Error Response:
+```json
+{"error": "Text cannot be empty"}
+```
+
+---
+
+## What to Check
+
+✅ **Connection**
+- [ ] WebSocket handshake completes (101 Switching Protocols)
+- [ ] No connection refused or timeout errors
+
+✅ **Response Time**
+- [ ] Status message within 1-2 seconds
+- [ ] First audio chunk within 3-5 seconds
+- [ ] Audio chunks every 0.5 seconds
+
+✅ **Data**
+- [ ] Receives JSON status messages (parseable)
+- [ ] Receives binary audio chunks (non-zero size)
+- [ ] All chunks have data (not empty)
+
+✅ **Completion**
+- [ ] Complete message sent
+- [ ] Connection closes gracefully
+- [ ] No hanging connections
+
+---
+
+## Troubleshooting
+
+### Connection Refused
+```
+❌ Error: Connection refused
+```
+→ Space might be rebuilding. Check: https://huggingface.co/spaces/ebitlogix/Parler_TTS_API
+
+### Timeout
+```
+❌ timeout waiting for response
+```
+→ Model might be loading. Wait 30 seconds and try again.
+
+### No Audio Chunks
+```
+❌ Only status message, no audio chunks
+```
+→ Check text is not empty. Try different text.
+
+### Wrong Protocol
+```
+❌ WebSocket is not supported
+```
+→ Make sure you're using `wss://` (secure) or `ws://` (local), not `https://` or `http://`
+
+---
+
+## Test Matrix
+
+| Test | URL | Expected | Status |
+|------|-----|----------|--------|
+| Connection | `wss://...` | 101 Upgrade | ✅ |
+| Send JSON | `{"text":"..."}` | Status message | ✅ |
+| Audio Stream | Binary chunks | Every 0.5s | ✅ |
+| Latency | Complete flow | <10 seconds | ✅ |
+
+---
+
+## Live Testing
+
+### Test 1: Simple Message
+```json
+{"text":"سلام دنیا","speaker":"Divya"}
+```
+Expected: Audio generated in ~4-5 seconds
+
+### Test 2: Longer Text
+```json
+{"text":"مرحبا بك في تطبيق تحويل النص إلى كلام","speaker":"Rani"}
+```
+Expected: More chunks, ~8-10 seconds total
+
+### Test 3: Different Speaker
+```json
+{"text":"یہ ایک اردو متن ہے","speaker":"Generic Female"}
+```
+Expected: Same timing, different voice
+
+---
+
+## Pipecat Integration Testing
+
+```python
+# test_pipecat_integration.py
+import asyncio
+import websockets
+import json
+
+async def test_pipecat():
+    async with websockets.connect('wss://ebitlogix-parler-tts-api.hf.space/ws/tts') as ws:
+        # Simulate Pipecat sending TTS request
+        await ws.send(json.dumps({
+            "text": "سلام دنیا",
+            "speaker": "Divya"
+        }))
+        
+        # Simulate receiving audio for playback
+        while True:
+            msg = await ws.recv()
+            if isinstance(msg, bytes):
+                print(f"Got audio: {len(msg)} bytes - READY FOR PIPECAT")
+            elif isinstance(msg, str):
+                data = json.loads(msg)
+                if data.get("status") == "complete":
+                    print("Audio stream complete")
+                    break
+
+asyncio.run(test_pipecat())
+```
+
+---
+
+## Success Indicators
+
+✅ All these should be true:
+- Connection establishes without error
+- Receives status message within 2 seconds
+- First audio chunk arrives within 5 seconds  
+- Subsequent chunks arrive continuously every 0.5-1 second
+- Complete message received
+- Connection closes normally
+
+If any fail, check Space status and rebuild if needed.

test_websocket.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""
+WebSocket TTS API Test Script
+Tests connection, latency, and audio streaming
+"""
+import asyncio
+import websockets
+import json
+import time
+from pathlib import Path
+
+# Configuration
+WS_URL = "wss://ebitlogix-parler-tts-api.hf.space/ws/tts"
+# For local testing: WS_URL = "ws://localhost:7860/ws/tts"
+
+OUTPUT_DIR = Path("tts_output")
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+
+async def test_websocket_connection():
+    """Test basic WebSocket connection"""
+    print("\n" + "="*60)
+    print("Testing WebSocket Connection")
+    print("="*60)
+
+    try:
+        async with websockets.connect(WS_URL) as websocket:
+            print("✅ Connected to WebSocket server")
+            print(f"   URL: {WS_URL}")
+            print(f"   Connection state: {websocket.state}")
+            return True
+    except Exception as e:
+        print(f"❌ Failed to connect: {e}")
+        return False
+
+
+async def test_websocket_response():
+    """Test WebSocket request/response"""
+    print("\n" + "="*60)
+    print("Testing WebSocket Request/Response")
+    print("="*60)
+
+    try:
+        async with websockets.connect(WS_URL) as websocket:
+            # Send request
+            request = {
+                "text": "سلام دنیا",
+                "speaker": "Divya",
+                "pitch": "Moderate",
+                "rate": "Moderate"
+            }
+
+            print(f"\nSending request:")
+            print(f"  Text: {request['text']}")
+            print(f"  Speaker: {request['speaker']}")
+
+            await websocket.send(json.dumps(request))
+            print("✅ Request sent")
+
+            # Receive responses
+            responses = []
+            while True:
+                try:
+                    message = await asyncio.wait_for(websocket.recv(), timeout=60)
+
+                    if isinstance(message, str):
+                        data = json.loads(message)
+                        print(f"\n📨 Status Message: {data}")
+                        responses.append(data)
+
+                        if data.get("status") == "complete":
+                            print(f"✅ Generation complete! Received {data['chunks_sent']} chunks")
+                            break
+                    else:
+                        # Binary audio data
+                        print(f"🔊 Audio chunk received: {len(message)} bytes")
+                        responses.append({"type": "audio", "size": len(message)})
+
+                except asyncio.TimeoutError:
+                    print("❌ Timeout waiting for response")
+                    break
+
+            return len(responses) > 0
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+async def test_websocket_latency():
+    """Test WebSocket latency and streaming speed"""
+    print("\n" + "="*60)
+    print("Testing WebSocket Latency & Streaming Speed")
+    print("="*60)
+
+    try:
+        start_time = time.time()
+
+        async with websockets.connect(WS_URL) as websocket:
+            connection_time = time.time() - start_time
+            print(f"\n✅ Connection established in {connection_time*1000:.1f}ms")
+
+            # Send request
+            request = {
+                "text": "یہ ایک ٹیسٹ ہے",
+                "speaker": "Rani"
+            }
+
+            send_time = time.time()
+            await websocket.send(json.dumps(request))
+            print(f"✅ Request sent in {(time.time()-send_time)*1000:.1f}ms")
+
+            # Track first chunk time
+            first_chunk_time = None
+            total_audio_size = 0
+            chunk_count = 0
+
+            while True:
+                message = await asyncio.wait_for(websocket.recv(), timeout=60)
+
+                if isinstance(message, str):
+                    data = json.loads(message)
+                    if data.get("status") == "generating":
+                        print(f"📊 Status: {data.get('message')}")
+                    elif data.get("status") == "complete":
+                        total_time = time.time() - start_time
+                        print(f"\n✅ Complete!")
+                        print(f"   Total time: {total_time:.2f}s")
+                        print(f"   First chunk: {first_chunk_time*1000:.1f}ms")
+                        print(f"   Total chunks: {chunk_count}")
+                        print(f"   Total audio size: {total_audio_size/1024:.1f} KB")
+                        if chunk_count > 0:
+                            print(f"   Avg chunk size: {total_audio_size/chunk_count:.0f} bytes")
+                        break
+                else:
+                    # Audio chunk
+                    if first_chunk_time is None:
+                        first_chunk_time = time.time() - start_time
+                        print(f"\n🔊 First audio chunk received in {first_chunk_time*1000:.1f}ms")
+
+                    total_audio_size += len(message)
+                    chunk_count += 1
+                    print(f"   Chunk {chunk_count}: {len(message)} bytes")
+
+            return True
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+async def test_websocket_streaming_save():
+    """Test WebSocket streaming and save audio"""
+    print("\n" + "="*60)
+    print("Testing WebSocket Streaming & Audio Save")
+    print("="*60)
+
+    try:
+        async with websockets.connect(WS_URL) as websocket:
+            request = {
+                "text": "مرحبا، یہ ایک WebSocket ٹیسٹ ہے",
+                "speaker": "Generic Female"
+            }
+
+            print(f"\nSending: {request['text']}")
+            await websocket.send(json.dumps(request))
+
+            # Collect all audio chunks
+            audio_chunks = []
+            chunk_count = 0
+
+            while True:
+                message = await asyncio.wait_for(websocket.recv(), timeout=60)
+
+                if isinstance(message, str):
+                    data = json.loads(message)
+                    print(f"Status: {data}")
+
+                    if data.get("status") == "complete":
+                        break
+                else:
+                    # Audio chunk
+                    audio_chunks.append(message)
+                    chunk_count += 1
+                    print(f"Received chunk {chunk_count}: {len(message)} bytes")
+
+            # Save combined audio
+            if audio_chunks:
+                combined_audio = b"".join(audio_chunks)
+                timestamp = time.strftime("%Y%m%d_%H%M%S")
+                filename = OUTPUT_DIR / f"websocket_test_{timestamp}.wav"
+
+                with open(filename, "wb") as f:
+                    f.write(combined_audio)
+
+                print(f"\n✅ Audio saved: {filename}")
+                print(f"   Total size: {len(combined_audio)/1024:.1f} KB")
+                return True
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+async def main():
+    """Run all tests"""
+    print("\n" + "█"*60)
+    print("█  WebSocket TTS API Test Suite")
+    print("█"*60)
+
+    # Run tests
+    tests = [
+        ("Connection Test", test_websocket_connection()),
+        ("Request/Response Test", test_websocket_response()),
+        ("Latency Test", test_websocket_latency()),
+        ("Streaming & Save Test", test_websocket_streaming_save()),
+    ]
+
+    results = {}
+    for test_name, test_coro in tests:
+        try:
+            results[test_name] = await test_coro
+        except Exception as e:
+            print(f"\n❌ {test_name} failed: {e}")
+            results[test_name] = False
+
+    # Summary
+    print("\n" + "="*60)
+    print("Test Summary")
+    print("="*60)
+    for test_name, result in results.items():
+        status = "✅ PASSED" if result else "❌ FAILED"
+        print(f"{status} - {test_name}")
+
+    passed = sum(1 for r in results.values() if r)
+    print(f"\nTotal: {passed}/{len(results)} tests passed")
+    print("="*60 + "\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())