Quickstart

Everything a working stream needs: one HTTP request for a node and a token, one WebSocket, raw PCM going up and JSON coming back.

Start with 3 seconds of silence. No microphone, audio file or SDK required. Choose one language below; each example makes its own connect request.

1 — Set your API key

bash

export LECSYNC_API_KEY=lk_live_xxxxxxxx

2 — Run one example

JavaScript · Node.js 22+

bash

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+

bash

python3 -m pip install websocket-clientpython3 quickstart.py

python

# Python 3.10+ · quickstart.pyimport json, os, threading, urllib.requestimport websocketkey = 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 — Check the output

You should see session.ready, usage.update, session.ended and a close code of 1000. Silence normally produces no transcript. With speech, read transcript.final. If you receive session.error, check its code and message; retryable allows a new connect, never resuming this stream.

The returned url already includes the session path. Configure only in connect; omitted store means false. Send only pcm_s16le, 16 kHz, mono, after session.ready. The server can discard audio over its realtime budget; see discardedSeconds in usage.update. A disconnect ends the stream.

Optional: inspect connect with curl

bash

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 — Complete runnable clients

For real WAV audio, use a complete client below. It converts 16-bit PCM WAV to 16 kHz mono, paces frames and limits the local queue to 2 seconds, dropping the oldest unsent audio when full. Source code is collapsed by default. Expand to copy or download, then save as stream.mjs or stream.py.

Save as stream.mjs (Node.js 22+, no npm dependencies) or stream.py (Python 3.10+, websocket-client). Set LECSYNC_API_KEY; optional LECSYNC_API_ORIGIN defaults to https://api.lecsync.com. An optional WAV path sends that file; omit it to send 3 seconds of silence. The source WAV is read into memory; only the pending send queue is bounded. Run one client, not both:

bash

node stream.mjs input.wavpython3 stream.py input.wav

JavaScript · stream.mjs — View full source · copy / download

/** * 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_ENDconst SAMPLE_RATE = 16000;const FRAME_MS = 100;const FRAME_BYTES = 3200;const MAX_QUEUE_BYTES = 2 * SAMPLE_RATE * 2; // 2 seconds of pending PCMfunction 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 — View full source · copy / download

python

"""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 wavetry:    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_ENDSAMPLE_RATE = 16000FRAME_MS = 100FRAME_BYTES = 3200MAX_QUEUE_FRAMES = 20  # 2 seconds of pending PCMdef 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, sampledef 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")