Быстрый старт
Всё, что нужно для рабочего потока: один HTTP-запрос за узлом и токеном, один WebSocket, сырой PCM наверх и JSON обратно.
Начните с 3 секунд тишины: микрофон, аудиофайл и SDK не нужны. Выберите один язык. Каждый пример сам выполняет запрос connect.
1 — Задайте API Key
export LECSYNC_API_KEY=lk_live_xxxxxxxx2 — Запустите один пример
JavaScript · Node.js 22+
node quickstart.mjs// Node.js 22+ · quickstart.mjsconst key = process.env.LECSYNC_API_KEY;if (!key) throw new Error('Set LECSYNC_API_KEY');const origin = process.env.LECSYNC_API_ORIGIN || 'https://api.lecsync.com';const res = await fetch(origin + '/v1/realtime/connect', { method: 'POST', headers: { Authorization: 'Bearer ' + key, 'Content-Type': 'application/json' }, body: JSON.stringify({ audio: { encoding: 'pcm_s16le', sampleRate: 16000, channels: 1 }, transcribe: { languages: ['en'] }, }), signal: AbortSignal.timeout(10000),});if (!res.ok) throw new Error(await res.text());const { url, token } = await res.json();const ws = new WebSocket(url, ['lecsync.realtime.v1', token]);let timer, frames = 0;const timeout = setTimeout(() => ws.close(), 20000);ws.onmessage = ({ data }) => { const msg = JSON.parse(data); console.log(msg.type, msg); if (msg.type === 'session.ready') { timer = setInterval(() => { // 100 ms of silence; drop this frame if the transport is busy. if (ws.bufferedAmount === 0) ws.send(new Uint8Array(3200)); if (++frames === 30) { clearInterval(timer); ws.send(JSON.stringify({ type: 'session.stop' })); } }, 100); } if (msg.type === 'session.error') { console.error(msg.code, msg.message, msg.retryable); clearInterval(timer); ws.close(); } if (msg.type === 'session.ended') clearInterval(timer);};ws.onerror = () => { clearInterval(timer); console.error('WebSocket error'); ws.close();};ws.onclose = ({ code, reason }) => { clearInterval(timer); clearTimeout(timeout); console.log('close', code, reason);};Python · Python 3.10+
python3 -m pip install websocket-clientpython3 quickstart.py# Python 3.10+ · quickstart.pyimport json, os, threading, urllib.requestimport websocket
key = os.environ['LECSYNC_API_KEY']origin = os.environ.get('LECSYNC_API_ORIGIN', 'https://api.lecsync.com')req = urllib.request.Request( origin + '/v1/realtime/connect', data=json.dumps({ 'audio': {'encoding': 'pcm_s16le', 'sampleRate': 16000, 'channels': 1}, 'transcribe': {'languages': ['en']}, }).encode(), headers={'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json'},)with urllib.request.urlopen(req, timeout=10) as res: body = json.load(res)finished = threading.Event()
def send_silence(ws): try: for _ in range(30): if finished.wait(0.1): return ws.send(bytes(3200), opcode=websocket.ABNF.OPCODE_BINARY) ws.send(json.dumps({'type': 'session.stop'})) except Exception as error: print(error) ws.close()
def on_message(ws, data): msg = json.loads(data) print(msg['type'], msg, flush=True) if msg['type'] == 'session.ready': threading.Thread(target=send_silence, args=(ws,), daemon=True).start() if msg['type'] in ('session.error', 'session.ended'): finished.set() if msg['type'] == 'session.error': ws.close()
ws = websocket.WebSocketApp( body['url'], subprotocols=['lecsync.realtime.v1', body['token']], on_message=on_message, on_error=lambda ws, error: print('WebSocket error', error), on_close=lambda ws, code, reason: (finished.set(), print('close', code, reason)),)timeout = threading.Timer(20, ws.close)timeout.start()try: ws.run_forever()finally: finished.set() timeout.cancel()3 — Проверьте результат
Ожидаются session.ready, usage.update, session.ended и код закрытия 1000. Тишина обычно не даёт текста; для речи читайте transcript.final. При session.error проверьте code и message. retryable означает возможность нового connect, а не возобновление потока.
Полученный url уже содержит путь сессии. Все настройки задаются в connect; без store действует false. После session.ready отправляйте только pcm_s16le, 16 кГц, моно. Сервер отбрасывает аудио сверх бюджета реального времени и сообщает длительность в discardedSeconds. Разрыв завершает поток.
Необязательно: ответ connect через curl
curl -X POST https://api.lecsync.com/v1/realtime/connect \ -H "Authorization: Bearer $LECSYNC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"audio":{"encoding":"pcm_s16le","sampleRate":16000,"channels":1},"transcribe":{"languages":["en"]}}'4 — Готовые клиенты
Для настоящего WAV используйте полный клиент ниже: преобразование 16-битного PCM WAV в моно 16 кГц, равномерная отправка и очередь до 2 секунд. При переполнении удаляются самые старые неотправленные данные. Исходники по умолчанию свёрнуты. Разверните, чтобы скопировать или скачать, и сохраните как stream.mjs или stream.py.
Сохраните как stream.mjs (Node.js 22+, без npm-зависимостей) или stream.py (Python 3.10+, websocket-client). Задайте LECSYNC_API_KEY; необязательный LECSYNC_API_ORIGIN по умолчанию равен https://api.lecsync.com. Можно указать путь WAV; без него отправляются 3 секунды тишины. Исходный WAV загружается в память; ограничена очередь отправки. Запустите один клиент:
node stream.mjs input.wavpython3 stream.py input.wavJavaScript · stream.mjs — Полный код · копировать / скачать
/** * Node.js 22+ (built-in fetch/WebSocket; no npm dependencies). * LECSYNC_API_KEY=lk_live_... node examples/api/js/stream.mjs [input.wav] * No file: stream 3 seconds of silence. Only 16-bit PCM WAV, mono/stereo. * Decode other formats first: ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le input.wav */import { readFileSync } from 'node:fs';
// CONNECT_CONFIG_STARTconst CONNECT_CONFIG = { audio: { encoding: 'pcm_s16le', sampleRate: 16000, channels: 1 }, transcribe: { languages: ['en'] }, store: false,};// CONNECT_CONFIG_END
const SAMPLE_RATE = 16000;const FRAME_MS = 100;const FRAME_BYTES = 3200;const MAX_QUEUE_BYTES = 2 * SAMPLE_RATE * 2; // 2 seconds of pending PCM
function loadAudio(file) { if (!file) return { samples: 3 * SAMPLE_RATE, rate: SAMPLE_RATE, sample: () => 0 }; const wav = readFileSync(file); if (wav.toString('ascii', 0, 4) !== 'RIFF' || wav.toString('ascii', 8, 12) !== 'WAVE') { throw new Error('Expected a 16-bit PCM WAV file'); } const end = wav.readUInt32LE(4) + 8; if (end > wav.length) throw new Error('Truncated WAV'); let format, data; for (let offset = 12; offset + 8 <= end;) { const id = wav.toString('ascii', offset, offset + 4); const size = wav.readUInt32LE(offset + 4); const start = offset + 8; if (start + size > end) throw new Error('Truncated WAV chunk'); if (id === 'fmt ') format = wav.subarray(start, start + size); if (id === 'data') data = wav.subarray(start, start + size); offset = start + size + (size % 2); } if (!format || format.length < 16 || !data || format.readUInt16LE(0) !== 1 || format.readUInt16LE(14) !== 16) { throw new Error('Only uncompressed 16-bit PCM WAV is supported'); } const channels = format.readUInt16LE(2), rate = format.readUInt32LE(4); if (![1, 2].includes(channels) || !rate || format.readUInt16LE(12) !== channels * 2 || data.length % (channels * 2)) { throw new Error('Expected valid mono/stereo PCM'); } const samples = data.length / (channels * 2); if (!samples) throw new Error('Empty WAV'); return { samples, rate, sample: (i) => { const left = data.readInt16LE(i * channels * 2); return channels === 1 ? left : (left + data.readInt16LE(i * 4 + 2)) / 2; } };}
// Resample lazily: the source file is in memory, but pending output is bounded.function makeFrame(audio, index) { const total = Math.ceil(audio.samples * SAMPLE_RATE / audio.rate); const start = index * FRAME_BYTES / 2; const frame = Buffer.alloc(Math.min(FRAME_BYTES / 2, total - start) * 2); for (let i = 0; i < frame.length / 2; i++) { const position = Math.min((start + i) * audio.rate / SAMPLE_RATE, audio.samples - 1); const lo = Math.floor(position), hi = Math.min(lo + 1, audio.samples - 1); const value = audio.sample(lo) + (audio.sample(hi) - audio.sample(lo)) * (position - lo); frame.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(value))), i * 2); } return frame; // Final frame may be shorter than 100 ms; no extra silence.}
async function main() { const key = process.env.LECSYNC_API_KEY; if (!key) throw new Error('Set LECSYNC_API_KEY'); const audio = loadAudio(process.argv[2]); // Validate before reserving a session. const origin = (process.env.LECSYNC_API_ORIGIN || 'https://api.lecsync.com').replace(/\/$/, ''); const res = await fetch(`${origin}/v1/realtime/connect`, { method: 'POST', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' }, body: JSON.stringify(CONNECT_CONFIG), signal: AbortSignal.timeout(10000), }); if (!res.ok) throw new Error(`connect HTTP ${res.status}: ${await res.text()}`); const { url, token } = await res.json(); // url is complete. Configure only in connect; a disconnected stream cannot resume. const ws = new WebSocket(url, ['lecsync.realtime.v1', token]); await new Promise((resolve, reject) => { let timer, startedAt, lastProgressAt, nextFrame = 0, queuedBytes = 0, stopped = false, ended = false, failure; const queue = []; const frameCount = Math.ceil(audio.samples * SAMPLE_RATE / audio.rate / (FRAME_BYTES / 2)); let deadline = setTimeout(() => fail(new Error('Timed out waiting for session.ready')), 10000); function fail(error) { failure = error; stopped = true; clearTimeout(timer); clearTimeout(deadline); ws.close(); reject(error); } function tick() { if (ws.readyState !== WebSocket.OPEN || stopped || ended) return; if (performance.now() - lastProgressAt > 10000) throw new Error('Audio send stalled'); // Capture follows elapsed time; after a stall skip stale source frames, never burst. const due = Math.min(frameCount, Math.floor((performance.now() - startedAt) / FRAME_MS)); let dropped = 0; while (nextFrame < due) { if (due - nextFrame > MAX_QUEUE_BYTES / FRAME_BYTES) { const skip = due - nextFrame - MAX_QUEUE_BYTES / FRAME_BYTES; nextFrame += skip; dropped += skip * FRAME_BYTES; } const frame = makeFrame(audio, nextFrame++); while (queue.length && queuedBytes + frame.length + ws.bufferedAmount > MAX_QUEUE_BYTES) { const old = queue.shift(); queuedBytes -= old.length; dropped += old.length; } queue.push(frame); queuedBytes += frame.length; } while (queue.length && queuedBytes + ws.bufferedAmount > MAX_QUEUE_BYTES) { const old = queue.shift(); queuedBytes -= old.length; dropped += old.length; } if (dropped) console.warn(`Dropped ${(dropped / (SAMPLE_RATE * 2)).toFixed(3)} seconds of local audio`); // At most one frame each tick, and never accumulate an unbounded WebSocket buffer. if (queue.length && ws.bufferedAmount === 0) { const frame = queue.shift(); queuedBytes -= frame.length; ws.send(frame); lastProgressAt = performance.now(); } if (nextFrame === frameCount && !queue.length && ws.bufferedAmount === 0) { stopped = true; clearTimeout(timer); ws.send(JSON.stringify({ type: 'session.stop' })); deadline = setTimeout(() => fail(new Error('Timed out waiting for session.ended/close')), 30000); } } ws.addEventListener('message', (event) => { try { const msg = JSON.parse(String(event.data)); if (msg.type === 'session.ready' && startedAt === undefined && !stopped && !ended) { clearTimeout(deadline); startedAt = lastProgressAt = performance.now(); const pump = () => { try { tick(); if (!stopped && !ended) timer = setTimeout(pump, FRAME_MS); } catch (error) { fail(error); } }; timer = setTimeout(pump, FRAME_MS); } if (['transcript.final', 'translation.final', 'digest.update', 'usage.update', 'session.error', 'session.ended'].includes(msg.type)) { console.log(msg.type, JSON.stringify(msg)); // usage.update includes discardedSeconds. } if (msg.type === 'session.error') { // retryable means a NEW connect may succeed, never resume this stream. console.error('retryable:', msg.retryable, '(new connect only)'); if (msg.scope === 'session') { stopped = true; failure = new Error(msg.message || msg.code); clearTimeout(timer); clearTimeout(deadline); deadline = setTimeout(() => fail(failure), 10000); if (startedAt !== undefined && ws.readyState === WebSocket.OPEN) { ws.send(JSON.stringify({ type: 'session.stop' })); } } } if (msg.type === 'session.ended') { ended = true; clearTimeout(timer); clearTimeout(deadline); deadline = setTimeout(() => fail(new Error('Timed out waiting for close')), 5000); } } catch (error) { fail(error); } }); ws.addEventListener('error', () => fail(new Error('WebSocket transport error; reconnect starts a new stream'))); ws.addEventListener('close', (event) => { clearTimeout(timer); clearTimeout(deadline); console.log('close', event.code, event.reason); if (failure || !ended || event.code !== 1000) reject(failure || new Error('Stream closed; use a new connect')); else resolve(); }); });}
main().catch((error) => { console.error(error.message); process.exitCode = 1; });Python · stream.py — Полный код · копировать / скачать
"""Python 3.10+; pip install websocket-clientLECSYNC_API_KEY=lk_live_... python3 examples/api/python/stream.py [input.wav]No file: stream 3 seconds of silence. Only 16-bit PCM WAV, mono/stereo.Decode other formats: ffmpeg -i input.mp3 -ac 1 -ar 16000 -c:a pcm_s16le input.wav"""import jsonimport mathimport osimport queueimport structimport sysimport threadingimport timeimport urllib.errorimport urllib.requestimport wave
try: import websocketexcept ImportError as exc: raise SystemExit("pip install websocket-client") from exc
# CONNECT_CONFIG_STARTCONNECT_CONFIG = { "audio": {"encoding": "pcm_s16le", "sampleRate": 16000, "channels": 1}, "transcribe": {"languages": ["en"]}, "store": False,}# CONNECT_CONFIG_END
SAMPLE_RATE = 16000FRAME_MS = 100FRAME_BYTES = 3200MAX_QUEUE_FRAMES = 20 # 2 seconds of pending PCM
def load_audio(file): if not file: return 3 * SAMPLE_RATE, SAMPLE_RATE, lambda i: 0 with wave.open(file, "rb") as wav: channels, rate = wav.getnchannels(), wav.getframerate() if wav.getcomptype() != "NONE" or wav.getsampwidth() != 2 or channels not in (1, 2): raise ValueError("Only uncompressed 16-bit mono/stereo PCM WAV is supported") samples = wav.getnframes() data = wav.readframes(samples) if not samples or len(data) != samples * channels * 2: raise ValueError("Empty or truncated WAV")
def sample(i): left = struct.unpack_from("<h", data, i * channels * 2)[0] return left if channels == 1 else (left + struct.unpack_from("<h", data, i * 4 + 2)[0]) / 2 return samples, rate, sample
def make_frame(audio, index): # Source file is in memory; resampled output is generated one frame at a time. samples, rate, sample = audio total = math.ceil(samples * SAMPLE_RATE / rate) start = index * FRAME_BYTES // 2 frame = bytearray(min(FRAME_BYTES // 2, total - start) * 2) for i in range(len(frame) // 2): position = min((start + i) * rate / SAMPLE_RATE, samples - 1) lo = math.floor(position) hi = min(lo + 1, samples - 1) value = sample(lo) + (sample(hi) - sample(lo)) * (position - lo) struct.pack_into("<h", frame, i * 2, max(-32768, min(32767, math.floor(value + 0.5)))) return bytes(frame) # Final frame can be shorter than 100 ms.
def main(): key = os.environ.get("LECSYNC_API_KEY") if not key: raise ValueError("Set LECSYNC_API_KEY") audio = load_audio(sys.argv[1] if len(sys.argv) > 1 else None) origin = os.environ.get("LECSYNC_API_ORIGIN", "https://api.lecsync.com").rstrip("/") req = urllib.request.Request( f"{origin}/v1/realtime/connect", data=json.dumps(CONNECT_CONFIG).encode(), headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"}, method="POST", ) try: with urllib.request.urlopen(req, timeout=10) as res: body = json.load(res) except urllib.error.HTTPError as exc: raise RuntimeError(f"connect HTTP {exc.code}: {exc.read().decode()}") from exc url = body["url"] # Already complete. Configure only in connect; no resume. ws = websocket.create_connection(url, subprotocols=["lecsync.realtime.v1", body["token"]], timeout=10) ws.settimeout(1) pending = queue.Queue(maxsize=MAX_QUEUE_FRAMES) done, halted, cancelled = threading.Event(), threading.Event(), threading.Event() errors = [] stop_sent = threading.Event() workers = []
def produce(): try: frames = math.ceil(audio[0] * SAMPLE_RATE / audio[1] / (FRAME_BYTES // 2)) start, index = time.monotonic(), 0 while index < frames and not halted.is_set(): if halted.wait(max(0, start + (index + 1) * FRAME_MS / 1000 - time.monotonic())): break due = min(frames, math.floor((time.monotonic() - start) * 1000 / FRAME_MS)) dropped = 0 if due - index > MAX_QUEUE_FRAMES: skip = due - index - MAX_QUEUE_FRAMES index += skip dropped += skip * FRAME_BYTES while index < due: frame = make_frame(audio, index) index += 1 while True: try: pending.put_nowait(frame) break except queue.Full: try: dropped += len(pending.get_nowait()) except queue.Empty: pass if dropped: print(f"Dropped {dropped / (SAMPLE_RATE * 2):.3f} seconds of local audio", file=sys.stderr) except Exception as exc: errors.append(exc) halted.set() finally: done.set()
def send(): try: while not cancelled.is_set(): if halted.is_set() or (done.is_set() and pending.empty()): ws.send(json.dumps({"type": "session.stop"})) stop_sent.set() return try: frame = pending.get(timeout=FRAME_MS / 1000) except queue.Empty: continue ws.send_binary(frame) # Blocking send has a 1 s timeout; never retry a partial frame. # Pace even after a blocked send; do not burst the queue on recovery. cancelled.wait(FRAME_MS / 1000) except Exception as exc: errors.append(exc) halted.set() cancelled.set()
ready, ended, closed = False, False, False deadline = time.monotonic() + 10 try: while not cancelled.is_set() or ended: if stop_sent.is_set() and not ended: stop_sent.clear() deadline = time.monotonic() + 30 if deadline is not None and time.monotonic() > deadline: raise TimeoutError("Timed out waiting for ready, session.ended or close") try: opcode, data = ws.recv_data(control_frame=True) except websocket.WebSocketTimeoutException: continue if opcode == websocket.ABNF.OPCODE_CLOSE: code = struct.unpack("!H", data[:2])[0] if len(data) >= 2 else 1005 print("close", code, data[2:].decode("utf-8", errors="replace")) closed = True if not ended or code != 1000: raise RuntimeError("Stream closed; use a new connect") break if opcode != websocket.ABNF.OPCODE_TEXT: continue msg = json.loads(data) kind = msg.get("type") if kind in {"transcript.final", "translation.final", "digest.update", "usage.update", "session.error", "session.ended"}: print(kind, json.dumps(msg, ensure_ascii=False), flush=True) # Includes discardedSeconds. if kind == "session.ready" and not ready and not halted.is_set(): ready, deadline = True, None workers = [threading.Thread(target=produce), threading.Thread(target=send)] for worker in workers: worker.start() if kind == "session.error": # retryable means a NEW connect may succeed, never resume this stream. print("retryable:", msg.get("retryable"), "(new connect only)", file=sys.stderr) if msg.get("scope") == "session": errors.append(RuntimeError(msg.get("message") or msg.get("code"))) halted.set() deadline = time.monotonic() + 10 if kind == "session.ended": ended = True halted.set() cancelled.set() # Keep receiving the server's close frame, without sending more audio. deadline = time.monotonic() + 5 if errors: raise errors[0] finally: halted.set() cancelled.set() for worker in workers: worker.join(timeout=2) ws.close() if not closed: print("close", 1006, "No server close frame received")
if __name__ == "__main__": try: main() except (Exception, KeyboardInterrupt) as exc: sys.exit(str(exc) or "Interrupted")