Ucapan ke Teks (STT) Real-time
Transkripsikan streaming audio langsung ke teks secara real-time menggunakan WebSocket
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).
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
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. |
Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.