Moknah Documents
Commencez gratuitement
Référence de l’API

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

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

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

💳 Compteur de facturation prépayée (400 crédits / min)

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

⚠️ CRITIQUE : Binaire brut uniquement

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

Pour toute question ou tout problème concernant l’API, contactez-nous à l’adresse api@moknah.io.