Pulse (Realtime)
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.