Echtzeit-Sprache-zu-Text (STT)
Transkribieren Sie Live-Audiostreams in Echtzeit über WebSockets in Text
Streamen Sie Roh-Audio an unsere Server und erhalten Sie bidirektionale Echtzeit-Transkriptionen. Der Server antwortet mit Teilergebnissen (Live-Text während der Benutzer spricht) und Endergebnissen (vollständige Sätze mit Zeitstempeln auf Wortebene).
Da Streams live und unvorhersehbar sind, verwenden wir einen Prepaid-Zähler. Bei Verbindungsaufbau reservieren wir sofort 400 Credits (für die ersten 60 Sekunden). Wenn Sie die Verbindung trennen, berechnen wir Ihre genaue Nutzung sekundengenau und erstatten die ungenutzten Credits automatisch auf Ihr Konto zurück!
Authentifizierung & Verbindung
Sie müssen Ihre WebSocket-Verbindung authentifizieren. Die Methode hängt von Ihrer Client-Umgebung ab:
- Frontend-Browser: Standard-Browser-WebSockets unterstützen keine benutzerdefinierten HTTP-Header. Sie müssen Ihren API-Schlüssel als Abfrageparameter übergeben (?api_key=YOUR_KEY).
- Backend / Python / Node.js: Sie können den Standard-HTTP-Header Authorization: Bearer YOUR_API_KEY verwenden.
| Abfrageparameter | Erforderlich | Typ | Beschreibung |
|---|---|---|---|
| api_key | Bedingt | string | Ihr Moknah-API-Schlüssel. (Hier erforderlich, falls nicht über den Authorization-Header übergeben). |
| language | Optional | string | Der Sprachcode für die Transkription. Standard ist ar-JO. Unterstützte Codes sind u. a. ar-SA, ar-EG, en-US usw. |
Audiospezifikationen
Senden Sie KEINE komprimierten Audiodateien (wie .mp3, .m4a) oder Standard-.wav-Dateien mit Headern über das WebSocket. Die KI gibt sonst zufälliges Rauschen oder leere Zeichenfolgen aus. Das WebSocket akzeptiert ausschließlich Raw-Binary-PCM-Frames.
Bevor Sie Binär-Frames über den Socket senden, stellen Sie sicher, dass Ihr Audiostream genau folgenden Vorgaben entspricht:
- Abtastrate: 16.000 Hz (16 kHz)
- Bittiefe: 16-Bit-Ganzzahl (Int16)
- Kanäle: 1 (Mono)
- Chunk-Größe: In kleinen Chunks senden (z. B. 100 ms / 3200 Byte). Chunks über 256 KB werden abgelehnt.
Serverantworten (JSON-Ereignisse)
Während Sie Binär-Audio an den Server streamen, antwortet der Server asynchron mit JSON-Text-Frames.
| Ereignistyp | Payload-Beispiel |
|---|---|
|
Verbindung erfolgreich Wird sofort nach erfolgreicher Authentifizierung gesendet. |
{"status": "connected", "message": "Bereit zum Streamen von Audio..."} |
|
Teilergebnis Wird kontinuierlich gesendet. Dient zur Anzeige von Live-Untertiteln in Echtzeit. |
{"type": "partial", "text": "مرحبا بك في منصة"} |
|
Endergebnis Wird gesendet, wenn ein Satz abgeschlossen ist. Enthält Zeitstempel. |
{
"type": "final",
"text": "مرحبا بك في منصة مكنة.",
"words": [
{"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
{"word": "بك", "start_time_ms": 460, "duration_ms": 200}
]
}
|
Stream beenden: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.
Beispielintegration
# pip install websockets pyaudio
import asyncio
import websockets
import json
import pyaudio
import sys
API_KEY = "YOUR_API_KEY"
URL = "wss://moknah.io/api/v1/stt/ws/?language=ar-SA"
# 16kHz, 16-bit, Mono (100ms chunks)
CHUNK = 1600
async def stream_live_microphone(ws):
audio = pyaudio.PyAudio()
stream = audio.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=CHUNK)
print("🎤 Microphone is LIVE. Start speaking!")
loop = asyncio.get_running_loop()
try:
while True:
data = await loop.run_in_executor(None, stream.read, CHUNK, False)
await ws.send(data)
await asyncio.sleep(0.001)
except asyncio.CancelledError:
await ws.send(json.dumps({"command": "stop"}))
finally:
stream.stop_stream()
stream.close()
audio.terminate()
async def receive_transcriptions(ws):
async for message in ws:
data = json.loads(message)
if data.get('type') == 'partial':
sys.stdout.write(f"\r⏳ {data['text']}")
sys.stdout.flush()
elif data.get('type') == 'final':
sys.stdout.write(f"\r✅ {data['text']}\n")
sys.stdout.flush()
async def main():
headers = {"Authorization": f"Bearer {API_KEY}"}
async with websockets.connect(URL, additional_headers=headers) as ws:
await asyncio.gather(
asyncio.create_task(stream_live_microphone(ws)),
asyncio.create_task(receive_transcriptions(ws))
)
asyncio.run(main())
// 1. Connect to WebSocket
const ws = new WebSocket('wss://moknah.io/api/v1/stt/ws/?api_key=YOUR_API_KEY&language=ar-SA');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'partial') {
console.log("Live:", data.text);
} else if (data.type === 'final') {
console.log("Final:", data.text);
}
};
// 2. Capture Microphone Audio on Connection
ws.onopen = async () => {
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
// Force 16kHz sample rate for the AudioContext
const audioCtx = new AudioContext({ sampleRate: 16000 });
const source = audioCtx.createMediaStreamSource(stream);
const processor = audioCtx.createScriptProcessor(4096, 1, 1);
processor.onaudioprocess = (e) => {
if (ws.readyState === WebSocket.OPEN) {
const float32Data = e.inputBuffer.getChannelData(0);
// Convert Browser Float32 to Int16 PCM (Required by Server)
const pcm16 = new Int16Array(float32Data.length);
for (let i = 0; i < float32Data.length; i++) {
pcm16[i] = Math.max(-1, Math.min(1, float32Data[i])) * 0x7FFF;
}
// Send binary PCM audio chunk to server
ws.send(pcm16.buffer);
}
};
source.connect(processor);
processor.connect(audioCtx.destination);
};
// 3. Handle graceful shutdown
function stopRecording() {
ws.send(JSON.stringify({ command: "stop" }));
}
Trennungs- & Fehlercodes
Wenn die Verbindung abgelehnt oder unterbrochen wird, schließt der WebSocket mit einem dieser spezifischen Codes:
| Schließcode | Name | Beschreibung |
|---|---|---|
| 1000 | NORMAL_CLOSURE |
Stream erfolgreich beendet. Nutzung protokolliert und entsprechend erstattet. |
| 4001 | MISSING_API_KEY |
Der Parameter ?api_key= wurde nicht angegeben oder ist ungültig. |
| 4002 | UNAUTHORIZED |
Ungültiger API-Schlüssel, eingeschränkte IP oder unzureichende Credits zum Starten/Fortsetzen des Streams. |
| 4009 | PAYLOAD_TOO_LARGE |
Sie haben ein Audio-Segment gesendet, das größer als 256 KB ist. Streamen Sie in kleineren Puffern. |
| 4290 | CONCURRENT_LIMIT |
Zu viele aktive WebSocket-Verbindungen für Ihr Konto. Das Limit liegt bei 1 aktiven Stream. |
Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.