Преобразование речи в текст (STT) в реальном времени
Преобразуйте потоковый аудиосигнал в текст в реальном времени с помощью WebSockets.
Передавайте потоковый необработанный аудиосигнал на наши серверы и получайте результаты транскрибации в реальном времени. Сервер возвращает как промежуточные результаты (текст, отображаемый по мере речи пользователя), так и итоговые (полные предложения с временными метками для каждого слова).
Поскольку потоковые трансляции проходят в реальном времени и их ход непредсказуем, мы используем систему предоплаты. При подключении мы сразу резервируем 400 кредитов (оплата за первые 60 секунд). Когда вы завершаете сеанс, мы рассчитываем точное время использования (с точностью до секунды) и автоматически возвращаем неиспользованные кредиты на ваш счет!
Аутентификация и подключение
Вам необходимо аутентифицировать WebSocket-соединение. Метод зависит от среды клиента:
- Браузеры для фронтенда: Стандартные браузерные WebSockets не поддерживают пользовательские HTTP-заголовки. Вам необходимо передавать API-ключ в качестве параметра запроса (?api_key=YOUR_KEY).
- Бэкенд / Python / Node.js: Вы можете использовать стандартный HTTP-заголовок Authorization: Bearer YOUR_API_KEY.
| Параметр запроса | Обязательно | Тип | Описание |
|---|---|---|---|
| api_key | Условное наклонение | строка | Ваш API-ключ Moknah. (Обязателен здесь, если не передан в заголовке Authorization). |
| language | Необязательно | строка | Код языка для транскрибирования. По умолчанию используется ar-JO. Поддерживаемые коды: ar-SA, ar-EG, en-US и т. д. |
Характеристики аудио
Не отправляйте через WebSocket сжатые аудиофайлы (например, .mp3, .m4a) или стандартные файлы .wav с заголовками. В противном случае ИИ будет выдавать случайный шум или пустые строки. WebSocket принимает исключительно необработанные (raw) бинарные PCM-фреймы.
Перед отправкой бинарных кадров через сокет убедитесь, что ваш аудиопоток точно соответствует:
- Частота дискретизации: 16 000 Гц (16 кГц)
- Глубина цвета: 16-битное целое число (Int16)
- Каналы: 1 (Моно)
- Размер фрагмента: Отправляйте данные небольшими фрагментами (например, 100 мс / 3200 байт). Фрагменты размером более 256 КБ будут отклонены.
Ответы сервера (JSON-события)
По мере передачи потока бинарных аудиоданных на сервер, сервер будет асинхронно отвечать текстовыми кадрами в формате 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 |
Вы отправили фрагмент аудио размером более 256 КБ. Передавайте данные в буферах меньшего размера. |
| 4290 | CONCURRENT_LIMIT |
Для вашей учетной записи открыто слишком много активных WebSocket-соединений. Лимит — 1 активный поток. |
По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.