Moknah Docs
Gratis starten
API-referentie

Realtime Spraak-naar-tekst (STT)

Transcribeer live audiostreams in realtime naar tekst met behulp van WebSockets

WSS wss://moknah.io/api/v1/stt/ws/

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).

💳 Prepaid-facturatiemeter (400 credits / min)

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

⚠️ BELANGRIJK: Alleen raw binary

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.
API-ondersteuning

Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.