Zamiana mowy na tekst (STT) w czasie rzeczywistym
Transkrybuj strumieniowane na żywo audio na tekst w czasie rzeczywistym za pomocą WebSockets
Przesyłaj strumieniowo surowe audio do naszych serwerów i otrzymuj dwukierunkowe transkrypcje w czasie rzeczywistym. Serwer odpowiada wynikami częściowymi (tekst na żywo w trakcie mówienia) oraz wynikami końcowymi (pełne zdania ze znacznikami czasu dla poszczególnych słów).
Ponieważ strumienie są transmitowane na żywo i nieprzewidywalne, stosujemy licznik przedpłacony. Po nawiązaniu połączenia natychmiast rezerwujemy 400 kredytów (opłata za pierwsze 60 sekund). Po rozłączeniu obliczamy dokładne zużycie co do sekundy i automatycznie zwracamy niewykorzystane kredyty na Twoje konto!
Uwierzytelnianie i połączenie
Musisz uwierzytelnić połączenie WebSocket. Metoda zależy od środowiska klienta:
- Przeglądarki (frontend): Standardowe połączenia WebSocket w przeglądarkach nie obsługują niestandardowych nagłówków HTTP. Musisz przekazać klucz API jako parametr zapytania (?api_key=YOUR_KEY).
- Backend / Python / Node.js: Możesz użyć standardowego nagłówka HTTP Authorization: Bearer YOUR_API_KEY.
| Parametr zapytania | Wymagane | Typ | Opis |
|---|---|---|---|
| api_key | Warunkowy | string | Twój klucz API Moknah. (Wymagany tutaj, jeśli nie został przekazany w nagłówku Authorization). |
| language | Opcjonalny | string | Kod języka do transkrypcji. Domyślnie ar-JO. Obsługiwane kody to m.in. ar-SA, ar-EG, en-US itp. |
Specyfikacja audio
NIE wysyłaj skompresowanych plików audio (takich jak .mp3, .m4a) ani standardowych plików .wav z nagłówkami przez WebSocket. AI wygeneruje losowy szum lub puste ciągi znaków. WebSocket akceptuje wyłącznie surowe binarne ramki PCM.
Przed wysłaniem ramek binarnych przez gniazdo upewnij się, że strumień audio dokładnie odpowiada poniższym parametrom:
- Częstotliwość próbkowania: 16 000 Hz (16 kHz)
- Głębia bitowa: 16-bitowa liczba całkowita (Int16)
- Kanały: 1 (Mono)
- Rozmiar fragmentu: Wysyłaj w małych fragmentach (np. 100 ms / 3200 bajtów). Fragmenty większe niż 256 KB zostaną odrzucone.
Odpowiedzi serwera (zdarzenia JSON)
Podczas przesyłania binarnego strumienia audio do serwera, serwer będzie odpowiadać asynchronicznie ramkami tekstowymi JSON.
| Typ zdarzenia | Przykładowy ładunek (payload) |
|---|---|
|
Połączenie udane Wysyłane natychmiast po pomyślnym uwierzytelnieniu. |
{"status": "connected", "message": "Gotowość do przesyłania strumienia audio..."} |
|
Wynik częściowy Wysyłane w sposób ciągły. Służy do wyświetlania napisów na żywo w trakcie mówienia. |
{"type": "partial", "text": "مرحبا بك في منصة"} |
|
Wynik końcowy Wysyłane po zakończeniu zdania. Zawiera znaczniki czasu. |
{
"type": "final",
"text": "مرحبا بك في منصة مكنة.",
"words": [
{"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300},
{"word": "بك", "start_time_ms": 460, "duration_ms": 200}
]
}
|
Kończenie strumienia: When the user stops speaking, send a JSON text frame: {"command": "stop"} to safely close the connection and calculate the final refund.
Przykładowa integracja
# 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" }));
}
Rozłączenie i kody błędów
Jeśli połączenie zostanie odrzucone lub przerwane, WebSocket zamknie się z jednym z poniższych kodów:
| Kod zamknięcia | Nazwa | Opis |
|---|---|---|
| 1000 | NORMAL_CLOSURE |
Strumień zakończony pomyślnie. Użycie zostało zarejestrowane i odpowiednio zwrócone. |
| 4001 | MISSING_API_KEY |
Parametr ?api_key= nie został podany lub jest nieprawidłowy. |
| 4002 | UNAUTHORIZED |
Nieprawidłowy klucz API, ograniczony adres IP lub niewystarczająca liczba kredytów, aby rozpocząć/kontynuować strumień. |
| 4009 | PAYLOAD_TOO_LARGE |
Wysłano fragment audio większy niż 256 KB. Przesyłaj strumieniowo w mniejszych buforach. |
| 4290 | CONCURRENT_LIMIT |
Zbyt wiele aktywnych połączeń WebSocket dla Twojego konta. Limit wynosi 1 aktywny strumień. |
W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.