Speech-to-Text Streaming

Real-time Audio Transcription with WebSocket

Use Speechall’s real-time transcription API to send live audio to wss://api.speechall.com/v1/transcribe and receive transcription messages over the same connection. For prerecorded files, use speech-to-text REST transcription instead.

Start with the runnable live captions example

The live captions tutorial explains a local browser microphone client and a Node.js relay. The complete example source keeps your Speechall key in the relay’s environment, uses an AudioWorklet, and sends raw PCM audio. It requires Node.js 22 or newer and a modern browser with microphone and AudioWorklet support.

From a checkout of the website repository:

cd examples/live-captions
npm install
export SPEECHALL_API_KEY='your-key'
npm start

Open http://127.0.0.1:8787, click Start, and grant microphone permission. Audio is transmitted to Speechall and may incur usage charges. Click Stop to release the microphone and close the connection. The relay binds only to loopback and is a local demonstration, not a production deployment.

Endpoint, authentication and model selection

Use a server-side WebSocket client that can set the authorization header:

import WebSocket from 'ws';

const url = new URL('wss://api.speechall.com/v1/transcribe');
url.searchParams.set('model', 'assemblyai.universal-3-5-pro');
url.searchParams.set('language', 'en');
url.searchParams.set('output_format', 'json');
const socket = new WebSocket(url, {
    headers: { Authorization: `Bearer ${process.env.SPEECHALL_API_KEY}` }
});

The API also accepts an api_key query parameter, which the browser playground uses. Browsers cannot attach arbitrary WebSocket authorization headers. For an application serving other users, keep the key on your server and relay audio; keys embedded in browser JavaScript or URLs are visible to clients and can appear in logs. Add your own user authentication, origin checks, session limits and usage controls before exposing a relay publicly.

Choose a model that supports streaming. The model catalogue and the models API’s streamable field help distinguish streaming models from file-only models. Do not assume that every model, language or REST option works over WebSocket. The example selects assemblyai.universal-3-5-pro and English; set SPEECHALL_MODEL in the relay environment to try another streaming-capable model after checking its requirements.

Audio format

This example sends 16,000 Hz, mono, signed 16-bit little-endian PCM in binary WebSocket frames. It requests a 16 kHz AudioContext, checks the actual context rate, and encodes samples explicitly in little-endian order. Each message contains 1,600 samples, or 100 milliseconds of audio. This is the example’s batching choice, not a documented API chunk-size requirement.

A microphone’s native rate can differ; Web Audio converts the input into the context’s rate. Setting a microphone constraint alone does not establish the bytes’ sample rate. The example fails clearly if the browser cannot provide the requested AudioContext rate.

Do not send MediaRecorder WebM/Opus blobs or an entire WAV header as though they were raw PCM. Different streaming models can impose additional requirements; confirm compatibility before changing encoding or sample rate.

Receive captions without inventing event semantics

With output_format=json, the existing Speechall playground reads a text property from each JSON message. The local example uses the same field and replaces the displayed caption with the latest text. Non-JSON messages are displayed as text; JSON messages without text are shown as status information.

The published OpenAPI schema describes REST endpoints and model capabilities, but does not define a WebSocket event schema, an interim/final flag or a client end-of-audio message. Do not assume provider-specific events such as is_final, Finalize or CloseStream pass through Speechall. The example’s ready, transcript and error envelopes are local relay messages, not Speechall protocol events.

Stop, errors and reconnects

Stop disconnects capture, stops every microphone track, closes the AudioContext and closes the WebSocket. The relay closes its upstream connection when the browser disconnects. Unexpected closes and errors also release capture resources. Both sides bound queued audio and stop instead of accumulating an unlimited backlog.

Closing the connection is not a documented flush operation: the remaining worklet samples and the provider’s final pending result may be lost. Use this demo for displaying the latest live caption, not as a guaranteed complete transcript or subtitle export. Use the file transcription endpoint when a durable recording needs a complete transcript.

The demo does not reconnect automatically. Restart explicitly after checking connectivity, key, credit balance and streaming model support. Reconnecting creates a new session; blindly replaying buffered audio can duplicate text and incur additional usage.

Frequently asked questions

Can I use this directly in a browser?

Yes, but a production application should relay through its own authenticated backend so its shared API key stays private. The local example uses a loopback relay with origin checking.

Why am I connected but receiving no captions?

Check microphone permission, whether speech is reaching the input, the actual sample rate, PCM byte order, model streaming support and the account’s available credit. Inspect local errors without logging API keys or sensitive audio. The playground can help compare a model and microphone independently of your integration.

Can I append every message to build a transcript?

Only after verifying the selected model’s message semantics. Messages may contain updated text, and the published schema does not provide a portable final-segment contract. Appending every text value can repeat words.

Where should I start?

Create an API key in the console, read the live captions walkthrough, and try a short session. For integration questions, contact Speechall with the model, audio format and redacted error details.