Moknah Dokumen
Mulai gratis
Referensi API

Ucapan ke Teks (STT) Real-time

Transkripsikan streaming audio langsung ke teks secara real-time menggunakan WebSocket

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

Alirkan audio mentah ke server kami dan terima transkripsi dua arah secara real-time. Server merespons dengan hasil parsial (teks langsung saat pengguna berbicara) dan hasil akhir (kalimat lengkap dengan stempel waktu tingkat kata).

💳 Meteran Penagihan Prabayar (400 Kredit / Menit)

Karena streaming bersifat langsung dan tidak dapat diprediksi, kami menggunakan meteran prabayar. Saat terhubung, kami langsung mencadangkan 400 kredit (untuk membayar 60 detik pertama). Saat koneksi terputus, kami menghitung penggunaan Anda secara akurat hingga hitungan detik dan secara otomatis mengembalikan kredit yang tidak terpakai ke akun Anda!

Autentikasi & Koneksi

Anda harus mengautentikasi koneksi WebSocket Anda. Metodenya bergantung pada lingkungan klien Anda:

  • Browser Frontend: WebSocket browser standar tidak mendukung header HTTP khusus. Anda harus menyertakan kunci API Anda sebagai parameter kueri (?api_key=YOUR_KEY).
  • Backend / Python / Node.js: Anda dapat menggunakan header HTTP standar Authorization: Bearer YOUR_API_KEY.
Parameter Kueri Wajib Jenis Deskripsi
api_key Kondisional string Kunci API Moknah Anda. (Wajib diisi di sini jika tidak dikirim melalui header Authorization).
language Opsional string Kode bahasa yang akan ditranskripsi. Default-nya adalah ar-JO. Kode yang didukung meliputi ar-SA, ar-EG, en-US, dll.

Spesifikasi Audio

⚠️ PENTING: Hanya Biner Mentah (Raw Binary)

JANGAN mengirim file audio terkompresi (seperti .mp3, .m4a) atau file .wav standar dengan header melalui WebSocket. AI akan menghasilkan derau acak atau string kosong. WebSocket hanya menerima frame PCM Biner Mentah.

Sebelum mengirim frame biner melalui soket, pastikan aliran audio Anda sesuai persis dengan:

  • Sample Rate: 16.000 Hz (16 kHz)
  • Kedalaman Bit: Integer 16-bit (Int16)
  • Saluran: 1 (Mono)
  • Ukuran Potongan (Chunk): Kirim dalam potongan kecil (mis., 100 mdtk / 3200 byte). Potongan yang lebih besar dari 256 KB akan ditolak.

Respons Server (Event JSON)

Saat Anda mengalirkan audio biner ke server, server akan membalas secara asinkron dengan frame teks JSON.

Jenis Event Contoh Payload
Koneksi Berhasil
Dikirim segera setelah autentikasi berhasil.
{"status": "connected", "message": "Siap mengalirkan audio..."}
Hasil Parsial
Dikirim secara terus-menerus. Digunakan untuk menampilkan subtitle langsung secara real-time.
{"type": "partial", "text": "مرحبا بك في منصة"}
Hasil Akhir
Dikirim saat satu kalimat selesai. Mencakup stempel waktu.
{
  "type": "final",
  "text": "مرحبا بك في منصة مكنة.",
  "words": [
    {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
    {"word": "بك", "start_time_ms": 460, "duration_ms": 200}
  ]
}

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


Contoh Integrasi

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

Kode Pemutusan & Kesalahan

Jika koneksi ditolak atau terputus, WebSocket akan ditutup dengan salah satu kode spesifik berikut:

Kode Penutupan Nama Deskripsi
1000 NORMAL_CLOSURE Streaming berhasil diakhiri. Penggunaan dicatat dan dikembalikan sebagaimana mestinya.
4001 MISSING_API_KEY Parameter ?api_key= tidak diberikan atau tidak valid.
4002 UNAUTHORIZED Kunci API tidak valid, IP dibatasi, atau kredit tidak mencukupi untuk memulai/melanjutkan streaming.
4009 PAYLOAD_TOO_LARGE Anda mengirim potongan audio yang lebih besar dari 256KB. Lakukan streaming dalam buffer yang lebih kecil.
4290 CONCURRENT_LIMIT Terlalu banyak koneksi WebSocket aktif untuk akun Anda. Batasnya adalah 1 streaming aktif.
Dukungan API

Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.