Spaces:
Runtime error
Runtime error
Upload README.md with huggingface_hub
Browse files
README.md
CHANGED
|
@@ -1,10 +1,193 @@
|
|
| 1 |
-
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
|
| 8 |
-
---
|
| 9 |
-
|
| 10 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# ๐๏ธ STT GPU Service Python v4
|
| 2 |
+
|
| 3 |
+
Real-time Speech-to-Text service using Kyutai's Moshi model with ultra-low latency streaming.
|
| 4 |
+
|
| 5 |
+
## Features
|
| 6 |
+
|
| 7 |
+
- **Real-time streaming**: 80ms audio chunk processing with WebSocket interface
|
| 8 |
+
- **Low latency**: ~200ms end-to-end transcription latency
|
| 9 |
+
- **Multi-language**: English and French support via `kyutai/stt-1b-en_fr`
|
| 10 |
+
- **Dual interface**: WebSocket streaming + REST API for testing
|
| 11 |
+
- **Production ready**: Optimized Docker image with pre-cached model
|
| 12 |
+
- **Resource efficient**: Designed for T4 Small GPU with auto-sleep
|
| 13 |
+
|
| 14 |
+
## API Endpoints
|
| 15 |
+
|
| 16 |
+
### ๐ WebSocket Streaming `/ws/stream`
|
| 17 |
+
Primary interface for real-time speech recognition.
|
| 18 |
+
|
| 19 |
+
**Expected format**: 16kHz mono PCM audio in 80ms chunks (2560 bytes per chunk)
|
| 20 |
+
|
| 21 |
+
```javascript
|
| 22 |
+
const ws = new WebSocket('wss://your-space-url/ws/stream');
|
| 23 |
+
|
| 24 |
+
ws.onopen = function() {
|
| 25 |
+
console.log('Connected to STT service');
|
| 26 |
+
};
|
| 27 |
+
|
| 28 |
+
ws.onmessage = function(event) {
|
| 29 |
+
const data = JSON.parse(event.data);
|
| 30 |
+
if (data.type === 'transcription') {
|
| 31 |
+
console.log('Transcription:', data.text);
|
| 32 |
+
console.log('Chunks with timestamps:', data.chunks);
|
| 33 |
+
}
|
| 34 |
+
};
|
| 35 |
+
|
| 36 |
+
// Send 80ms audio chunks
|
| 37 |
+
ws.send(audioChunk); // 2560 bytes of 16-bit PCM data
|
| 38 |
+
```
|
| 39 |
+
|
| 40 |
+
### ๐ก REST API `/transcribe`
|
| 41 |
+
Testing endpoint for complete audio file processing.
|
| 42 |
+
|
| 43 |
+
```bash
|
| 44 |
+
curl -X POST "https://your-space-url/transcribe" \
|
| 45 |
+
-F "audio_file=@audio.wav" \
|
| 46 |
+
-H "Content-Type: multipart/form-data"
|
| 47 |
+
```
|
| 48 |
+
|
| 49 |
+
**Response**:
|
| 50 |
+
```json
|
| 51 |
+
{
|
| 52 |
+
"filename": "audio.wav",
|
| 53 |
+
"transcription": "Hello, this is a test transcription.",
|
| 54 |
+
"chunks": [
|
| 55 |
+
{"text": "Hello,", "timestamp": [0.0, 0.5]},
|
| 56 |
+
{"text": "this is a test", "timestamp": [0.5, 1.2]},
|
| 57 |
+
{"text": "transcription.", "timestamp": [1.2, 2.0]}
|
| 58 |
+
],
|
| 59 |
+
"timestamp": 1703123456.789
|
| 60 |
+
}
|
| 61 |
+
```
|
| 62 |
+
|
| 63 |
+
### ๐ Health Check `/health`
|
| 64 |
+
Service monitoring endpoint.
|
| 65 |
+
|
| 66 |
+
```bash
|
| 67 |
+
curl https://your-space-url/health
|
| 68 |
+
```
|
| 69 |
+
|
| 70 |
+
## Technical Specifications
|
| 71 |
+
|
| 72 |
+
- **Model**: `kyutai/stt-1b-en_fr` (1B parameters)
|
| 73 |
+
- **Languages**: English, French
|
| 74 |
+
- **Latency**: 0.5 second model delay + processing time
|
| 75 |
+
- **Audio format**: 16kHz mono PCM
|
| 76 |
+
- **Chunk size**: 80ms (2560 bytes)
|
| 77 |
+
- **Max connections**: 2 concurrent WebSocket streams
|
| 78 |
+
- **GPU**: Optimized for T4 Small
|
| 79 |
+
- **Auto-sleep**: 30 minutes of inactivity
|
| 80 |
+
|
| 81 |
+
## Usage Examples
|
| 82 |
+
|
| 83 |
+
### Python WebSocket Client
|
| 84 |
+
```python
|
| 85 |
+
import asyncio
|
| 86 |
+
import websockets
|
| 87 |
+
import json
|
| 88 |
+
import wave
|
| 89 |
+
import numpy as np
|
| 90 |
+
|
| 91 |
+
async def stream_audio():
|
| 92 |
+
uri = "wss://your-space-url/ws/stream"
|
| 93 |
+
|
| 94 |
+
async with websockets.connect(uri) as websocket:
|
| 95 |
+
# Load audio file
|
| 96 |
+
with wave.open('audio.wav', 'rb') as wav_file:
|
| 97 |
+
frames = wav_file.readframes(wav_file.getnframes())
|
| 98 |
+
audio_data = np.frombuffer(frames, dtype=np.int16)
|
| 99 |
+
|
| 100 |
+
# Send in 80ms chunks (1280 samples at 16kHz)
|
| 101 |
+
chunk_size = 1280
|
| 102 |
+
for i in range(0, len(audio_data), chunk_size):
|
| 103 |
+
chunk = audio_data[i:i+chunk_size]
|
| 104 |
+
await websocket.send(chunk.tobytes())
|
| 105 |
+
|
| 106 |
+
# Receive transcription
|
| 107 |
+
response = await websocket.recv()
|
| 108 |
+
data = json.loads(response)
|
| 109 |
+
if data.get('type') == 'transcription':
|
| 110 |
+
print(f"Transcription: {data['text']}")
|
| 111 |
+
|
| 112 |
+
asyncio.run(stream_audio())
|
| 113 |
+
```
|
| 114 |
+
|
| 115 |
+
### JavaScript Browser Client
|
| 116 |
+
```html
|
| 117 |
+
<!DOCTYPE html>
|
| 118 |
+
<html>
|
| 119 |
+
<body>
|
| 120 |
+
<button id="startBtn">Start Recording</button>
|
| 121 |
+
<button id="stopBtn">Stop Recording</button>
|
| 122 |
+
<div id="transcription"></div>
|
| 123 |
+
|
| 124 |
+
<script>
|
| 125 |
+
let ws, mediaRecorder, audioContext;
|
| 126 |
+
|
| 127 |
+
document.getElementById('startBtn').onclick = async () => {
|
| 128 |
+
// Connect WebSocket
|
| 129 |
+
ws = new WebSocket('wss://your-space-url/ws/stream');
|
| 130 |
+
|
| 131 |
+
// Get microphone access
|
| 132 |
+
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
|
| 133 |
+
audioContext = new AudioContext({ sampleRate: 16000 });
|
| 134 |
+
const source = audioContext.createMediaStreamSource(stream);
|
| 135 |
+
|
| 136 |
+
// Process audio in 80ms chunks
|
| 137 |
+
const processor = audioContext.createScriptProcessor(1280, 1, 1);
|
| 138 |
+
processor.onaudioprocess = (e) => {
|
| 139 |
+
const inputData = e.inputBuffer.getChannelData(0);
|
| 140 |
+
const pcmData = new Int16Array(inputData.length);
|
| 141 |
+
|
| 142 |
+
for (let i = 0; i < inputData.length; i++) {
|
| 143 |
+
pcmData[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
|
| 144 |
+
}
|
| 145 |
+
|
| 146 |
+
if (ws.readyState === WebSocket.OPEN) {
|
| 147 |
+
ws.send(pcmData.buffer);
|
| 148 |
+
}
|
| 149 |
+
};
|
| 150 |
+
|
| 151 |
+
source.connect(processor);
|
| 152 |
+
processor.connect(audioContext.destination);
|
| 153 |
+
|
| 154 |
+
ws.onmessage = (event) => {
|
| 155 |
+
const data = JSON.parse(event.data);
|
| 156 |
+
if (data.type === 'transcription' && data.text) {
|
| 157 |
+
document.getElementById('transcription').innerHTML += data.text + ' ';
|
| 158 |
+
}
|
| 159 |
+
};
|
| 160 |
+
};
|
| 161 |
+
|
| 162 |
+
document.getElementById('stopBtn').onclick = () => {
|
| 163 |
+
if (ws) ws.close();
|
| 164 |
+
if (audioContext) audioContext.close();
|
| 165 |
+
};
|
| 166 |
+
</script>
|
| 167 |
+
</body>
|
| 168 |
+
</html>
|
| 169 |
+
```
|
| 170 |
+
|
| 171 |
+
## Deployment
|
| 172 |
+
|
| 173 |
+
This Space is configured for:
|
| 174 |
+
- **Hardware**: T4 Small GPU
|
| 175 |
+
- **Sleep timeout**: 30 minutes
|
| 176 |
+
- **Docker**: Single-stage build with pre-cached model
|
| 177 |
+
- **Port**: 7860
|
| 178 |
+
|
| 179 |
+
## Performance Notes
|
| 180 |
+
|
| 181 |
+
- First request after cold start: ~30-60 seconds (model loading)
|
| 182 |
+
- Subsequent requests: ~200ms latency
|
| 183 |
+
- Concurrent connections: Maximum 2 WebSocket streams
|
| 184 |
+
- Memory usage: ~6GB GPU memory, ~4GB RAM
|
| 185 |
+
|
| 186 |
+
## Error Handling
|
| 187 |
+
|
| 188 |
+
The service includes comprehensive error handling:
|
| 189 |
+
- Connection limits (max 2 concurrent)
|
| 190 |
+
- Audio format validation
|
| 191 |
+
- Model loading verification
|
| 192 |
+
- Automatic reconnection support
|
| 193 |
+
- Graceful WebSocket disconnection
|