Pulse (Realtime)

Transcribe audio in real time over a persistent WebSocket. The fit-for-purpose path for live captioning, voice agents, and any flow where you need partial transcripts as the user is still speaking. ## When to use this - **Use this** for live audio: microphone input, voice-agent turns, simultaneous interpretation, low-latency captioning. Partial results stream back while audio is still arriving. - **Use the pre-recorded REST endpoint** (`POST /waves/v1/pulse/get_text`) when you have a complete file. Single request, single response, less plumbing. ## How it works 1. Open a WebSocket to `wss://api.smallest.ai/waves/v1/pulse/get_text` with `Authorization: Bearer <key>` and the session params (`language`, `sample_rate`, `encoding`, etc.) as query string. 2. Stream raw PCM (or your chosen `encoding`) over the socket as binary frames. 3. The server pushes back JSON `transcriptionResponse` messages — partial results (`is_final: false`) as you speak, finalized text (`is_final: true`) when an utterance closes. 4. Send a `finalize` message to force end-of-utterance, or `close_stream` to end the session. ## Examples **Python** (real-time mic input) ```python import asyncio, json, websockets, pyaudio URL = "wss://api.smallest.ai/waves/v1/pulse/get_text?language=en&sample_rate=16000&encoding=linear16&word_timestamps=true" HEADERS = {"Authorization": f"Bearer {API_KEY}"} async def stream_mic(): pa = pyaudio.PyAudio() stream = pa.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=320) async with websockets.connect(URL, additional_headers=HEADERS) as ws: async def send_audio(): while True: await ws.send(stream.read(320)) async def recv_transcripts(): async for msg in ws: data = json.loads(msg) tag = "FINAL " if data.get("is_final") else "partial" print(f"[{tag}] {data.get('transcript')}") await asyncio.gather(send_audio(), recv_transcripts()) asyncio.run(stream_mic()) ``` **JavaScript / TypeScript** (using `ws`) ```typescript import WebSocket from "ws"; import { readFileSync } from "node:fs"; const params = new URLSearchParams({ language: "en", sample_rate: "16000", encoding: "linear16", word_timestamps: "true", }); const ws = new WebSocket(`wss://api.smallest.ai/waves/v1/pulse/get_text?${params}`, { headers: { Authorization: `Bearer ${process.env.SMALLEST_API_KEY}` }, }); ws.on("open", () => { const audio = readFileSync("./call.pcm"); // 16-bit mono PCM at 16 kHz for (let i = 0; i < audio.length; i += 3200) { ws.send(audio.subarray(i, i + 3200)); } ws.send(JSON.stringify({ type: "finalize" })); }); ws.on("message", (raw) => { const data = JSON.parse(raw.toString()); const tag = data.is_final ? "FINAL " : "partial"; console.log(`[${tag}] ${data.transcript}`); if (data.is_last) ws.close(); }); ``` ## Common gotchas - **Match `sample_rate` to your audio.** The server will not resample for you — sending 44.1 kHz audio with `sample_rate=16000` produces garbage transcripts. - **`finalize` vs `close_stream`**: `finalize` ends the current utterance and triggers a final transcript without closing the session. `close_stream` ends the session entirely. - **`keywords` is WebSocket-only.** Pass them on connect for proper-noun / jargon boosting; not available on the REST endpoint. - **`format`/`punctuate`/`capitalize`** are accepted at the wire level today. They currently return the same transcript regardless of value — pass them in your integration so it works as the behavior changes. - **PII/PCI redaction (`redact_pii`, `redact_pci`)** runs server-side on finalized transcripts only — partials may show the unredacted text briefly before being replaced. - **JavaScript / TypeScript**: the official `smallestai` npm package predates the Pulse model, so connect with the `ws` library directly as shown above.