Skip to content
Introducing STTv6See what's new
Speech-to-TextReal-time API

Stream reconnect

Reconnect to a real-time stream when its connection drops, and continue where it left off.

Overview

Networks are flaky. A phone switches from Wi-Fi to mobile data, a laptop moves to another router, and the connection drops in the middle of a stream.

With stream reconnect, the stream doesn't end there. You connect again and continue where you left off:

  • Nothing is lost or repeated. You get the responses you missed and send only the audio the server didn't get.
  • It stays one stream, with one transcript, the same speakers and one bill.

Your client does part of the work: it notices the drop, keeps what it sent and reconnects. The client checklist lists every step.


How it works

Turn it on. Send the API key with the connection, and add "enable_reconnect": true to the start request.

Save the token and URL. The server first sends a reconnect message with reconnect_token and reconnect_url.

Track what you send and receive. Remember the seq of the last response. Buffer your messages until a pong confirms them.

Reconnect. When the connection drops, connect to reconnect_url and send reconnect with the token and last_seq. The server answers reconnected with a new token and last_request.

Resend and carry on. Resend your messages after last_request, then keep streaming.


Turn it on

Add enable_reconnect to the start request:

{
  "model": "stt-rt-v6",
  "audio_format": "auto",
  "enable_reconnect": true
}

Send the API key with the connection, as described in WebSocket authentication. A reconnect connection has no start request, so it must send the API key with the connection.

Before any transcription response, the server sends a reconnect message:

{
  "type": "reconnect",
  "reconnect_token": "q9ZkT3vLm8XwR2pN...",
  "reconnect_url": "wss://stt-rt.soniox.com/transcribe-websocket?reconnect=true&r=Qx7mT2kV9pLwZ4nB"
}

Both are opaque. Store them and use them exactly as given.

If you don't get this message, you can't reconnect to this stream.


Track messages

With reconnect on, every response has a seq: 1, 2, 3, and so on. Remember the last one you received. That is all you need to get the responses you missed.

To also resend the audio the server missed, keep the messages you send in a buffer, numbered from 1. Buffer every message except pings. Use ping and pong to know when to drop them: a pong means the server has every message you sent before its ping.

If you don't buffer, the stream still continues after a reconnect, but the audio sent around the drop is missing from the transcript.


Detect a lost connection

A dropped connection is often silent, so use ping to notice it. Ping every quarter of the idle timeout (even when you send audio), and reconnect when:

  • a pong takes longer than that
  • a socket error occurs
  • the connection closes without a finished or error response

Pings and reconnect

  • Pongs don't count for seq. A pong has no seq, so it doesn't change your last_seq. Pongs lost in a drop are not sent again after a reconnect.
  • Start timing pongs after the reconnect message arrives. Pings sent right after the start request are answered only once the stream starts.

Reconnect

When the connection drops (a late pong tells you), open a new one to reconnect_url, with the API key sent with the connection. Send this first, and nothing else, not even a ping, until the server answers:

{
  "type": "reconnect",
  "reconnect_token": "q9ZkT3vLm8XwR2pN...",
  "last_seq": 3
}

Use the token and URL you saved, and the seq of the last response you received, or 0 if none.

Don't close the old connection with status 1000. If that close reaches the server, it ends the stream. Leave the old connection, or close it with another status, such as 4000.

The server answers with a new token and how many of your messages it received:

{
  "type": "reconnected",
  "reconnect_token": "h4JsW7cYb1KfE6uD...",
  "last_request": 4
}

Every reconnect gives you a new token, so save it each time. The reconnect_url stays the same.

Retry a failed attempt

A reconnect can fail before reconnected arrives: the new connection doesn't open, or drops too. Retry with the same token.

  • Give each attempt about a quarter of the idle timeout, counted from when you start connecting. If reconnected hasn't arrived by then, drop the connection and try again. Don't close it with 1000: the server may have accepted the attempt even if its answer never reached you, and the close would end the stream.
  • An older token keeps working until you reconnect with a newer one.
  • An attempt that never reached the server, or was refused, doesn't use up the token.

One connection per stream

A stream has one connection at a time. When a reconnect takes over, the old connection gets a connection_replaced error and is closed.

  • The stream hasn't ended. It continues on the new connection.
  • Don't reconnect from a replaced connection. Its close may look abnormal to your WebSocket library. Ignore it, and anything else that arrives on it.
  • Open one reconnect connection at a time. If you open several, the newest one keeps the stream and the others are told they were replaced.
  • Keep one last_seq and one list of messages per stream, not per connection.

Resend

After reconnected, the responses you missed arrive, in order, and then live ones.

Resend your messages from number last_request + 1, in their original order, then keep streaming.

For example, you sent messages 1 to 6, and the last response you got was seq 3:

reconnect:     last_seq 3
reconnected:   last_request 4    the server got messages 1 to 4
you receive:   seq 4, 5, ...     the responses you missed, then live ones
you resend:    5, 6              then send 7, 8, ...

If last_request is 6, the server has everything. Resend nothing and carry on with 7.

  • last_request counts your messages over every connection of the stream.
  • A message last_request doesn't count was never used, even if it left your client. Resending it doesn't duplicate audio.
  • The empty frame that ends the stream counts as a message too.
  • The server keeps only the recent responses. If last_seq is too old, it refuses the reconnect.

The connection can drop again, so keep going as before. Keep numbering and buffering your messages, and tracking seq. The numbers never restart.


Reconnect window

After a drop, the stream waits one idle timeout for you. That's your reconnect window.

The server often can't see the drop, so the window may already be running from the last message it got. If you ping every quarter of the idle timeout and give each pong as long, you notice the drop within the first half of the window. Reconnect right away: you have the other half.

If you don't make it, the stream ends.

Choosing idle_timeout_ms

With reconnect, leave idle_timeout_ms at the default, or set it to 10000 or more. A lower value frees an abandoned stream sooner, but leaves you less time to reconnect. At 10000, you have about 5 seconds.


Final results after a drop

To end a stream, send the empty frame and keep reading until the finished response arrives. If you close earlier, you can lose the last responses.

If the connection drops before the finished response, reconnect as usual. What you get depends on the stream:

The stream isThe reconnect
Still finishingTakes the stream over. The rest arrives on the new connection, ending with the finished response. Resend the empty frame if last_request doesn't include it.
FinishedGets the missed responses, including the finished response. Nothing to resend.

The same goes for a stream that ends on its own while you are away, for example at the stream duration limit.

Keep pinging until the finished response

Keep pinging after the empty frame, and reconnect as soon as a pong is late. The final responses wait for you only until the reconnect window closes.


Rules and limits

  • Use the same API key, sent with the connection. It must be the key that started the stream.
  • Temporary API keys keep working. A temporary API key can reconnect to the stream it started, even after it expires or was used. Its max_session_duration_seconds still limits the stream.
  • Use the reconnect URL only to reconnect. It can't start a new stream.
  • A reconnect takes no extra concurrent requests slot. It works even at the concurrency limit.
  • Reconnect doesn't reset the stream duration limit. It counts from the start of the stream.

You are charged for the full stream duration, including the time the stream waited for a reconnect.


When a reconnect is refused

The server answers with a reconnect_failed error and closes the new connection. The stream itself is not affected. The error_message tells you whether to reconnect again, for example with the newest token, or to start a new stream. The errors reference lists every case.

A new stream started right after a refusal can get a 429 for a short time if you are near the concurrent requests limit, because the old stream holds its slot until its idle timeout. See Connection lost without a close frame.


Client checklist

  1. Send the API key with the connection, and start the stream with enable_reconnect. Store the token and URL from the reconnect message.
  2. Number your messages from 1 and keep them until a pong confirms them. Track the last seq you received.
  3. Ping every quarter of the idle timeout (5 seconds at the default). A pong that takes longer, a socket error or an unexpected close means the connection is lost.
  4. Don't close the lost connection with 1000. Open one connection to reconnect_url.
  5. Send the reconnect message first, with the newest token and the last seq.
  6. No reconnected within a quarter of the idle timeout? Drop that connection and retry with the same token.
  7. On reconnected, keep the new token, resend from last_request + 1, and carry on.
  8. On connection_replaced, drop that connection quietly.
  9. On reconnect_failed, follow the error_message. Usually that means a new stream.
  10. To end the stream, send the empty frame and read until the finished response, or close with 1000.

On this page