Moknah Documenti
Inizia gratis
Riferimento API

Da voce a testo (STT) in tempo reale

Trascrivi flussi audio dal vivo in testo in tempo reale usando WebSocket

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

Trasmetti audio grezzo in streaming ai nostri server e ricevi trascrizioni bidirezionali in tempo reale. Il server risponde con risultati parziali (testo in diretta mentre l'utente parla) e risultati finali (frasi complete con timestamp a livello di parola).

💳 Contatore di fatturazione prepagata (400 crediti / min)

Poiché i flussi sono in tempo reale e imprevedibili, utilizziamo un contatore prepagato. Alla connessione, riserviamo immediatamente 400 crediti (che coprono i primi 60 secondi). Quando ti disconnetti, calcoliamo il tuo utilizzo esatto al secondo e rimborsiamo automaticamente i crediti non utilizzati sul tuo account!

Autenticazione e connessione

Devi autenticare la tua connessione WebSocket. Il metodo dipende dal tuo ambiente client:

  • Browser frontend: I WebSocket standard dei browser non supportano header HTTP personalizzati. Devi includere la tua chiave API come parametro di query (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Puoi utilizzare l'header HTTP standard Authorization: Bearer YOUR_API_KEY.
Parametro di query Obbligatorio Tipo Descrizione
api_key Condizionale string La tua chiave API Moknah. (Obbligatoria qui se non viene passata tramite l'header Authorization).
language Opzionale string Il codice della lingua da trascrivere. Il valore predefinito è ar-JO. I codici supportati includono ar-SA, ar-EG, en-US, ecc.

Specifiche audio

⚠️ CRITICO: Solo binario grezzo

NON inviare file audio compressi (come .mp3, .m4a) o file .wav standard con header tramite WebSocket. L'IA restituirà rumore casuale o stringhe vuote. Il WebSocket accetta esclusivamente frame PCM binari grezzi.

Prima di inviare frame binari tramite il socket, assicurati che il tuo flusso audio corrisponda esattamente a:

  • Frequenza di campionamento: 16.000 Hz (16 kHz)
  • Profondità in bit: Intero a 16 bit (Int16)
  • Canali: 1 (Mono)
  • Dimensione del blocco: Invia in piccoli blocchi (es. 100 ms / 3200 byte). I blocchi superiori a 256 KB verranno rifiutati.

Risposte del server (eventi JSON)

Mentre trasmetti audio binario al server, questo risponderà in modo asincrono con frame di testo JSON.

Tipo di evento Esempio di payload
Connessione riuscita
Inviato immediatamente dopo un'autenticazione riuscita.
{"status": "connected", "message": "Pronto per lo streaming audio..."}
Risultato parziale
Inviato continuamente. Usato per mostrare sottotitoli in tempo reale durante la dettatura.
{"type": "partial", "text": "مرحبا بك في منصة"}
Risultato finale
Inviato al completamento di una frase. Include i timestamp.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

Terminare il flusso: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.


Esempio di integrazione

# 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" }));
}

Disconnessione e codici di errore

Se la connessione viene rifiutata o cade, il WebSocket si chiuderà con uno di questi codici specifici:

Codice di chiusura Nome Descrizione
1000 NORMAL_CLOSURE Flusso terminato correttamente. Utilizzo registrato e rimborsato di conseguenza.
4001 MISSING_API_KEY Il parametro ?api_key= non è stato fornito o non è valido.
4002 UNAUTHORIZED Chiave API non valida, IP soggetto a restrizioni o crediti insufficienti per avviare/continuare il flusso.
4009 PAYLOAD_TOO_LARGE Hai inviato un frammento audio superiore a 256 KB. Trasmetti usando buffer più piccoli.
4290 CONCURRENT_LIMIT Troppe connessioni WebSocket attive per il tuo account. Il limite è 1 flusso attivo.
Supporto API

Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.