Skip to content
KugelAudioDocs

Turn lifecycle

How a streaming text-to-speech turn starts and ends: flush, idle auto-flush and close, final versus session_closed, session reuse and per-session usage.

On this page

On /ws/tts/stream (and via every SDK streaming session), one turn = one assistant utterance = one backend voice session. The WebSocket connection itself persists across turns; the turn is the unit that begins, produces audio, and gets billed. A graceful turn ends with session_closed; a cancelled turn ends with interrupted instead.

Getting the turn boundary right is the difference between a smooth agent and one that pauses mid-sentence or splits a reply in two.

What a turn is

ConceptLifetimeCreated byEnded by
WebSocket connectionMinutes–hours; reusedconnect() / first request{"close_socket": true} or disconnect
Turn (session)One assistant utteranceFirst text after connect or after session_closed / interruptedflush, idle auto-flush, or close (graceful); cancel or disconnect (abandoned)

The first text message after the connection opens (or after the previous turn ends) starts a new turn on a fresh backend voice session. The configuration (voice_id, sample rate, etc.) is sticky from the previous turn unless you send a new config message.

What triggers synthesis

You do not control when audio generation starts: the server does. It buffers the text you send and hands a chunk to the model at natural sentence boundaries. Inside one turn, model state (KV cache, voice conditioning) carries across chunks, so prosody stays natural.

This is why you send LLM tokens directly without flushing: the buffer reassembles them and the model only ever sees sentence-sized work.

How a turn ends

A turn ends gracefully in one of three ways. A cancel abandons it with an interrupted frame instead, while a disconnect abandons it without an ack.

JSON
{"flush": true}

Emits any trailing buffered text and streams its audio. Once the turn's last audio frame has been delivered, the server sends {"final": true} (the end-of-audio signal), followed by session_closed. The socket stays open for the next turn. End every turn with an explicit flush: it's the lowest latency path and the only one that's deterministic.

2. Idle auto-flush: the 5-second timeout

If you stream text but never flush, the server ends the turn for you after 5 seconds without new text. You'll receive:

  1. a warning frame: "Turn ended after 5s of inactivity. Send {\"flush\": true} to end a turn explicitly — it lowers latency and avoids this auto-flush."
  2. the remaining buffered text synthesized and streamed,
  3. final, then session_closed.

3. close: graceful end

JSON
{"close": true}

Like flush, but explicit about intent: flush buffered text, drain audio, end the session. {"end_session": true} is an alias. The WebSocket stays open. (To also close the connection, send {"close_socket": true}.)

To abandon a turn instead of finishing it (user interrupted, drop the buffered text), that's barge-in, not close.

final vs session_closed

Every gracefully ended turn closes with two frames, in order:

  1. final: end of audio (the ElevenLabs isFinal equivalent). Sent right after the turn's last audio frame. Once you receive it, no further audio for the turn will arrive: key your "audio is done" logic (stop waiting, end playback, hang up the call) on this frame.
JSON
{
  "final": true,
  "total_audio_seconds": 5.4,
  "total_text_chunks": 3,
  "total_audio_chunks": 15
}
  1. session_closed: end of turn, carrying the usage block for billing:
JSON
{
  "session_closed": true,
  "total_audio_seconds": 5.4,
  "total_text_chunks": 3,
  "total_audio_chunks": 15,
  "usage": { "audio_seconds": 5.4, "characters": 142, "cost_cents": 0.49, "currency": "eur", "model_id": "kugel-3.5" }
}

final is sent on every graceful turn end (flush, idle auto-flush, or close) but not after a cancel: a barge-in acknowledges with interrupted instead. Note that on the single-request /ws/tts endpoint, final is the request-complete message and carries the usage itself. See the Stream Speech reference. Full streaming message reference: Stream Input API.

The warning frame

{"warning": "..."} is a non-fatal advisory; the socket stays open. Today it is emitted in one case: the turn was auto-ended by the idle timeout because no flush was sent. Log it: in a correctly built integration it should never appear.

Who is responsible for what

You are responsible forThe server is responsible for
Sending text as it becomes available (no client-side sentence buffering)Buffering text and choosing sentence-boundary chunks
Sending flush exactly once, at the end of each turnStarting synthesis and preserving prosody across chunks within the turn
Not leaving a turn idle >5 s mid-utteranceEnding idle turns (after a warning) so sessions can't leak
Keying "audio done" on final and billing on session_closedEmitting final after the last audio frame, then session_closed with usage, on every graceful turn end
Playback, buffering, and barge-in decisionsCancelling generation when you barge in

Session reuse

WebSocket connections are reused across turns, so consecutive turns skip the connection handshake entirely (see Latency for what that saves). After session_closed, just send the next turn's text: the config (voice_id, audio format, etc.) is sticky. Send a new config message only to change something (e.g. a different voice):

async with client.tts.streaming_session(voice_id=1071) as session:
    # Turn 1
    async for chunk in session.send("Hello from voice one."):
        play_audio(chunk.audio)
    async for chunk in session.flush():
        play_audio(chunk.audio)

    # Change voice for turn 2 after flush ended turn 1 (no new WebSocket needed)
    session.update_config(voice_id=1072)
    async for chunk in session.send("Hello from voice two."):
        play_audio(chunk.audio)
    # End turn 2 with a flush too: close() below discards undrained audio
    async for chunk in session.flush():
        play_audio(chunk.audio)

# The context manager calls close(), which ends the session and closes the
# WebSocket. Audio still in flight at that point is dropped, so always
# flush (or iterate session.drain()) before leaving the block.

Per-session usage

Every session_closed frame carries a usage object summarising what the turn consumed and what it was charged, useful for per-conversation billing of your own customers:

FieldDescription
audio_secondsTotal audio generated this turn (the unit we bill on)
charactersTotal input characters submitted this turn
cost_centsActual amount charged, in EUR cents. null if the charge could not be determined (see below)
currencyCurrency of cost_cents ("eur"); present only when cost_cents is set
model_idModel that produced the audio

If the charge cannot be determined at turn end (e.g. a transient billing error, or billing taking longer than about two seconds to confirm), cost_cents is null and the object carries "cost_unavailable": true instead of a misleading 0. The frame is not held back waiting for billing, and the request is still billed once. audio_seconds is always reported, so you can still reconcile usage from the audio you received.

On /ws/tts/multi, usage is reported per synthesized, billable context: the usage object is attached to that context's context_closed frame, with the same audio_seconds, characters, cost_cents, currency, and model_id fields. A context closed before synthesis starts has no usage block. The multi session_closed frame is a connection-wide end signal with total_audio_seconds; it has no context_id and does not carry a usage block. See Multi-context streaming.

The single-request /ws/tts endpoint carries the same usage object on its final message (per request rather than per turn). See the Stream Speech API reference.

Troubleshooting

The reply stops early, at a sentence boundary

Almost always the idle auto-flush. Look for the warning frame in your message log: if it's there, your client streamed part of the text, then went >5 s without sending more or flushing, so the server ended the turn. The most common causes: a slow LLM/tool call mid-turn, or a missing final flush. Note the turn split also splits billing: you'll see two session_closed frames, each with its own usage.

My client hangs waiting for the end of the stream

Check what you're waiting for: a graceful turn ends with final (end of audio) followed by session_closed (turn end + usage). A turn ended by cancel (barge-in) emits neither: it acknowledges with interrupted. If you only handle final, a barge-in path will hang.

I send pings but the turn still ends after 5 s

By design: WebSocket ping/keep-alive frames don't reset the idle timer. Only a JSON message does. The timer exists to reap abandoned turns; a ping proves the socket is alive, not that the turn is still being written.