Realtime Spraak-naar-tekst (STT)
Transcribeer live audiostreams in realtime naar tekst met behulp van WebSockets
Stream ruwe audio naar onze servers en ontvang bidirectionele, realtime transcripties. De server reageert met tussentijdse resultaten (live tekst terwijl de gebruiker spreekt) en definitieve resultaten (voltooide zinnen met tijdstempels op woordniveau).
Omdat streams live en onvoorspelbaar zijn, gebruiken we een prepaidmeter. Bij het verbinden reserveren we direct 400 credits (voor de eerste 60 seconden). Wanneer je de verbinding verbreekt, berekenen we je exacte verbruik tot op de seconde nauwkeurig en storten we de ongebruikte credits automatisch terug op je account!
Authenticatie & verbinding
Je moet je WebSocket-verbinding authenticeren. De methode hangt af van je clientomgeving:
- Frontend-browsers: Standaard browser-WebSockets ondersteunen geen aangepaste HTTP-headers. Je moet je API-sleutel meesturen als queryparameter (?api_key=YOUR_KEY).
- Backend / Python / Node.js: Je kunt de standaard HTTP-header Authorization: Bearer YOUR_API_KEY gebruiken.
| Queryparameter | Verplicht | Type | Beschrijving |
|---|---|---|---|
| api_key | Voorwaardelijk | string | Je Moknah API-sleutel. (Hier vereist als deze niet via de Authorization-header wordt meegegeven). |
| language | Optioneel | string | De taalcode om te transcriberen. Standaard is ar-JO. Ondersteunde codes zijn onder meer ar-SA, ar-EG, en-US, enz. |
Audiospecificaties
Stuur GEEN gecomprimeerde audiobestanden (zoals .mp3, .m4a) of standaard .wav-bestanden met headers via de WebSocket. De AI geeft dan willekeurige ruis of lege strings terug. De WebSocket accepteert uitsluitend raw binary PCM-frames.
Zorg ervoor dat je audiostream exact overeenkomt met het volgende voordat je binaire frames via de socket verstuurt:
- Samplerate: 16.000 Hz (16 kHz)
- Bitdiepte: 16-bits integer (Int16)
- Kanalen: 1 (Mono)
- Chunk-grootte: Verstuur in kleine chunks (bijv. 100 ms / 3200 bytes). Chunks groter dan 256 KB worden geweigerd.
Serverresponsen (JSON-events)
Terwijl je binaire audio naar de server streamt, antwoordt de server asynchroon met JSON-tekstframes.
| Eventtype | Voorbeeld van payload |
|---|---|
|
Verbinding geslaagd Wordt direct na succesvolle authenticatie verzonden. |
{"status": "connected", "message": "Klaar om audio te streamen..."} |
|
Gedeeltelijk resultaat Wordt continu verzonden. Gebruikt om live meeschrijvende ondertitels weer te geven. |
{"type": "partial", "text": "مرحبا بك في منصة"} |
|
Eindresultaat Wordt verzonden wanneer een zin voltooid is. Bevat tijdstempels. |
{
"type": "final",
"text": "مرحبا بك في منصة مكنة.",
"words": [
{"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
{"word": "بك", "start_time_ms": 460, "duration_ms": 200}
]
}
|
De stream beëindigen: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.
Voorbeeldintegratie
# 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" }));
}
Verbinding verbroken & foutcodes
Als de verbinding wordt geweigerd of verbroken, wordt de WebSocket gesloten met een van deze specifieke codes:
| Sluitcode | Naam | Beschrijving |
|---|---|---|
| 1000 | NORMAL_CLOSURE |
Stream succesvol beëindigd. Gebruik gelogd en naar behoren terugbetaald. |
| 4001 | MISSING_API_KEY |
De parameter ?api_key= ontbreekt of is ongeldig. |
| 4002 | UNAUTHORIZED |
Ongeldige API-sleutel, beperkt IP-adres of onvoldoende credits om de stream te starten/vervolgen. |
| 4009 | PAYLOAD_TOO_LARGE |
Je hebt een audiofragment groter dan 256 KB verzonden. Stream in kleinere buffers. |
| 4290 | CONCURRENT_LIMIT |
Te veel actieve WebSocket-verbindingen voor je account. De limiet is 1 actieve stream. |
Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.