pgits commited on
Commit
c3b0862
ยท
verified ยท
1 Parent(s): 0d732a6

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +193 -10
README.md CHANGED
@@ -1,10 +1,193 @@
1
- ---
2
- title: Stt Gpu Service Python V4
3
- emoji: ๐Ÿ“‰
4
- colorFrom: purple
5
- colorTo: red
6
- sdk: docker
7
- pinned: false
8
- ---
9
-
10
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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