Transcription de la parole en texte en temps réel (STT)
Transcrire de l’audio en direct en texte en temps réel à l’aide de WebSockets
Diffusez de l’audio brut vers nos serveurs et recevez des transcriptions bidirectionnelles en temps réel. Le serveur renvoie des résultats partiels (texte en direct au fur et à mesure que l’utilisateur parle) ainsi que des résultats finaux (phrases complètes avec horodatage au niveau du mot).
Comme les flux sont diffusés en direct et sont imprévisibles, nous utilisons un système de décompte prépayé. Dès la connexion, nous réservons immédiatement 400 crédits (couvrant les 60 premières secondes). Lorsque vous vous déconnectez, nous calculons votre consommation exacte à la seconde près et recréditons automatiquement les crédits inutilisés sur votre compte !
Authentification et connexion
Vous devez authentifier votre connexion WebSocket. La méthode dépend de votre environnement client :
- Navigateurs frontend : Les WebSockets standard des navigateurs ne prennent pas en charge les en-têtes HTTP personnalisés. Vous devez inclure votre clé API en tant que paramètre de requête (?api_key=VOTRE_CLÉ).
- Backend / Python / Node.js : Vous pouvez utiliser l’en-tête HTTP standard Authorization : Bearer YOUR_API_KEY.
| Paramètre de requête | Obligatoire | Type | Description |
|---|---|---|---|
| api_key | Conditionnel | chaîne | Votre clé API Moknah. (Requise ici si elle n’est pas transmise via l’en-tête Authorization). |
| language | Facultatif | chaîne | Le code de langue à transcrire. La valeur par défaut est ar-JO. Les codes pris en charge incluent ar-SA, ar-EG, en-US, etc. |
Spécifications audio
N’envoyez pas de fichiers audio compressés (tels que .mp3 ou .m4a) ni de fichiers .wav standard avec en-tête via le WebSocket. L’IA produirait du bruit aléatoire ou des chaînes vides. Le WebSocket accepte exclusivement des trames PCM binaires brutes.
Avant d’envoyer des trames binaires via le socket, assurez-vous que votre flux audio correspond exactement à :
- Fréquence d’échantillonnage : 16 000 Hz (16 kHz)
- Profondeur de bits : Entier 16 bits (Int16)
- Chaînes : 1 (Mono)
- Taille du bloc : Envoyez par petits segments (par ex. 100 ms / 3200 octets). Les segments supérieurs à 256 Ko seront rejetés.
Réponses du serveur (événements JSON)
À mesure que vous diffusez de l’audio binaire vers le serveur, celui-ci répondra de manière asynchrone par des trames de texte JSON.
| Type d’événement | Exemple de charge utile |
|---|---|
|
Connexion réussie Envoyé immédiatement après une authentification réussie. |
{"status": "connected", "message": "Prêt à diffuser l’audio..."} |
|
Résultat partiel Envoyé en continu. Utilisé pour afficher des sous-titres en temps réel, au fur et à mesure de la saisie. |
{"type": "partial", "text": "Bienvenue sur la plateforme"} |
|
Résultat final Envoyé lorsqu’une phrase est terminée. Inclut des horodatages. |
{
"type": "final",
"text": "Bienvenue sur la plateforme Makana.",
"words": [
{"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
{"word": "بك", "start_time_ms": 460, "duration_ms": 200}
]
}
|
Fin du flux : When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.
Exemple d’intégration
# 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" }));
}
Déconnexion et codes d’erreur
Si la connexion est rejetée ou interrompue, le WebSocket se fermera avec l’un de ces codes spécifiques :
| Fermer le code | Nom | Description |
|---|---|---|
| 1000 | NORMAL_CLOSURE |
Le flux s’est terminé avec succès. L’utilisation a été enregistrée et remboursée comme il se doit. |
| 4001 | MISSING_API_KEY |
Le paramètre ?api_key= n’a pas été fourni ou est invalide. |
| 4002 | UNAUTHORIZED |
Clé API invalide, IP restreinte ou crédits insuffisants pour démarrer ou poursuivre le flux. |
| 4009 | PAYLOAD_TOO_LARGE |
Vous avez envoyé un segment audio supérieur à 256 Ko. Diffusez le flux en utilisant des tampons plus petits. |
| 4290 | CONCURRENT_LIMIT |
Trop de connexions WebSocket actives pour votre compte. La limite est de 1 flux actif. |
Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.