Moknah دستاویزات
مفت شروع کریں
API ریفرنس

ریئل ٹائم اسپیچ ٹو ٹیکسٹ (STT)

WebSockets کا استعمال کرتے ہوئے لائیو اسٹریمنگ آڈیو کو ریئل ٹائم میں متن میں ٹرانسکرائب کریں

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

ہمارے سرورز پر خام آڈیو اسٹریم کریں اور دو طرفہ، ریئل ٹائم ٹرانسکرپشن حاصل کریں۔ سرور جزوی نتائج (صارف کے بولتے وقت لائیو متن) اور حتمی نتائج (لفظ کی سطح کے ٹائم اسٹیمپس کے ساتھ مکمل جملے) کے ساتھ جواب دیتا ہے۔

💳 پری پیڈ بلنگ میٹر (400 کریڈٹس / منٹ)

چونکہ اسٹریمز لائیو اور غیر متوقع ہوتی ہیں، اس لیے ہم پری پیڈ میٹر استعمال کرتے ہیں۔ کنکشن بنتے ہی ہم فوری طور پر 400 کریڈٹس ریزرو کر لیتے ہیں (پہلے 60 سیکنڈز کی ادائیگی کے لیے)۔ جب آپ منقطع ہوتے ہیں، تو ہم سیکنڈ کے حساب سے آپ کے درست استعمال کا حساب لگاتے ہیں اور غیر استعمال شدہ کریڈٹس خودکار طور پر آپ کے اکاؤنٹ میں واپس کر دیتے ہیں!

تصدیق اور کنکشن

آپ کو اپنے WebSocket کنکشن کی تصدیق کرنی ہوگی۔ طریقہ کار آپ کے کلائنٹ کے ماحول پر منحصر ہے:

  • فرنٹ اینڈ براؤزرز: معیاری براؤزر WebSockets کسٹم HTTP ہیڈرز کو سپورٹ نہیں کرتے۔ آپ کو اپنی API کلید بطور کوئری پیرامیٹر (?api_key=YOUR_KEY) شامل کرنی ہوگی۔
  • بیک اینڈ / Python / Node.js: آپ معیاری HTTP ہیڈر Authorization: Bearer YOUR_API_KEY استعمال کر سکتے ہیں۔
کوئری پیرامیٹر لازمی قسم تفصیل
api_key مشروط اسٹرنگ (string) آپ کی Moknah API کلید۔ (اگر Authorization ہیڈر کے ذریعے پاس نہیں کی گئی تو یہاں لازمی ہے)۔
language اختیاری اسٹرنگ (string) ٹرانسکرائب کرنے کے لیے زبان کا کوڈ۔ ڈیفالٹ ar-JO ہے۔ سپورٹ کردہ کوڈز میں ar-SA، ar-EG، en-US وغیرہ شامل ہیں۔

آڈیو کی تفصیلات

⚠️ انتہائی اہم: صرف را بائنری (Raw Binary)

WebSocket پر کمپریسڈ آڈیو فائلیں (جیسے .mp3، .m4a) یا ہیڈرز والی معیاری .wav فائلیں ہرگز نہ بھیجیں۔ ورنہ AI بے ترتیب شور یا خالی اسٹرنگز آؤٹ پٹ کرے گا۔ WebSocket صرف اور صرف Raw Binary PCM فریمز قبول کرتا ہے۔

ساکٹ پر بائنری فریمز بھیجنے سے پہلے، یقینی بنائیں کہ آپ کی آڈیو اسٹریم ان تفصیلات کے عین مطابق ہے:

  • سیمپل ریٹ: 16,000 Hz (16 kHz)
  • بٹ ڈیپتھ: 16-بٹ انٹیجر (Int16)
  • چینلز: 1 (مونو)
  • چنک سائز: چھوٹے ٹکڑوں میں بھیجیں (مثلاً 100ms / 3200 بائٹس)۔ 256KB سے بڑے ٹکڑے مسترد کر دیے جائیں گے۔

سرور کے جوابات (JSON ایونٹس)

جیسے جیسے آپ سرور پر بائنری آڈیو اسٹریم کرتے ہیں، سرور غیر ہم وقت ساز (asynchronously) طور پر JSON ٹیکسٹ فریمز کے ساتھ جواب دے گا۔

ایونٹ کی قسم پے لوڈ کی مثال
کنکشن کامیاب
کامیاب تصدیق کے فوراً بعد بھیجا جاتا ہے۔
{"status": "connected", "message": "آڈیو اسٹریم کرنے کے لیے تیار..."}
جزوی نتیجہ
مسلسل بھیجا جاتا ہے۔ لائیو ٹائپ ہونے والے سب ٹائٹلز دکھانے کے لیے استعمال ہوتا ہے۔
{"type": "partial", "text": "مرحبا بك في منصة"}
حتمی نتیجہ
جملہ مکمل ہونے پر بھیجا جاتا ہے۔ اس میں ٹائم اسٹیمپس شامل ہوتے ہیں۔
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

اسٹریم ختم کرنا: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.


انٹیگریشن کی مثال

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

ڈس کنیکٹ اور ایرر کوڈز

اگر کنکشن مسترد ہو جائے یا منقطع ہو جائے، تو WebSocket ان مخصوص کوڈز میں سے کسی ایک کے ساتھ بند ہو جائے گا:

کلوز کوڈ نام تفصیل
1000 NORMAL_CLOSURE اسٹریم کامیابی سے ختم ہو گئی۔ استعمال ریکارڈ کر لیا گیا اور مناسب طریقے سے ریفنڈ کر دیا گیا۔
4001 MISSING_API_KEY ?api_key= پیرامیٹر فراہم نہیں کیا گیا یا غلط ہے۔
4002 UNAUTHORIZED غلط API کلید، محدود IP، یا اسٹریم شروع/جاری رکھنے کے لیے ناکافی کریڈٹس۔
4009 PAYLOAD_TOO_LARGE آپ نے 256KB سے بڑا آڈیو ٹکڑا بھیجا ہے۔ چھوٹے بفرز میں اسٹریم کریں۔
4290 CONCURRENT_LIMIT آپ کے اکاؤنٹ کے لیے بہت زیادہ فعال WebSocket کنکشنز ہیں۔ حد 1 فعال اسٹریم ہے۔
API سپورٹ

API سے متعلق سوالات یا مسائل کے لیے، ہم سے یہاں رابطہ کریں api@moknah.io.