Da voce a testo (STT) in tempo reale
Trascrivi flussi audio dal vivo in testo in tempo reale usando WebSocket
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).
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
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. |
Per domande o problemi relativi all'API, contattaci all'indirizzo api@moknah.io.