Streaming and chunks#

The ABR SDK’s streaming pipeline is built on three low-level primitives: Bufferabr_buf_t, EventSetabr_evset_t, and Eventabr_event_t. The push()abr_session_push() and wait_for_completion()abr_session_wait_for_completion() manage these primitives internally, so most callers never interact with them directly. This page explains how they work and how they fit together underneath the high-level API.

The layered model#

The streaming pipeline has two layers, from lowest to highest:

  1. Buffers: FIFO byte queues that carry audio in and text chunks out.

  2. Events and EventSets: a signaling system for blocking efficiently until a buffer reaches a threshold or holds a flush marker.

push()abr_session_push() and push()abr_session_push() manage both layers internally. Most callers never need to interact with them directly.

Buffers#

A Bufferabr_buf_t is a fixed-capacity FIFO byte queue inside the neural network pipeline. The AsrAsr class exposes two:

Property or method

Description

buffer.sizebuffer.size

Total capacity in bytes (fixed for the lifetime of the buffer).

buffer.levelbuffer.level

Bytes that can be pushed, or pulled up to the next flush marker.

buffer.push(data, flush=False)buffer.push(data, flush=False)

Write bytes into the buffer. Returns the number of bytes actually written, which may be less than len(data) if the buffer is full.

buffer.pull(max_n_bytes)buffer.pull(max_n_bytes)

Read up to max_n_bytes bytes from the buffer. Returns the bytes and whether they end at a flush marker.

With flush=True, a flush marker follows the data if all of it fits. It ends a segment of input, such as an utterance, and the output for that segment ends with a flush marker too.

In normal usage you do not call push()buf_push or pull()buf_pull directly. push()abr_session_push() manages both buffers for you.

Events and EventSets#

Polling levelbuf_get_level in a loop would waste CPU cycles. The event system provides a blocking interface: your code waits until a condition is met, then acts.

An EventSetabr_evset_t groups one or more Eventabr_event_t objects into a single poll target. Call evset.poll()evset.poll() to block until at least one event fires or the timeout elapses. A negative timeout waits forever; a timeout of zero returns immediately without blocking.

It returns True if an event fired, False if the timeout expired, and raises InterruptedError if interrupted by a signal.

It returns ABR_OK if an event fired, ABR_ERR_TIMEOUT if the timeout expired, and ABR_ERR_INTERRUPT if interrupted by a signal, in which case it is safe to call again. The tarball’s examples/asr.c is a complete event loop over one input and one output buffer event.

Call evset.interrupt()evset.interrupt() to unblock a poll()evset_poll call that is waiting on another thread.

Create events from an EventSetabr_evset_t using this factory method:

create_buffer_level_event()create_buffer_level_event() fires when at least threshold bytes are available. For an output buffer, “available” means threshold bytes of data ready to read. For an input buffer, “available” means threshold bytes of write space free. Use an output buffer event to know when a chunk is ready; use an input buffer event to know when the buffer has space to accept more audio. An output buffer event also fires when a flush marker is waiting, even below threshold.

After a flush, keep pulling from the output buffer until pull()buf_pull returns True as its second value. That flush marker ends the output for the flushed input.

After a flush, keep pulling from the output buffer until pull()buf_pull sets its flush argument. That flush marker ends the output for the flushed input.

Event flags and state#

Pass EventFlagsabr_event_flags when creating an event to control its initial behavior:

Flag

Effect

EventFlags(auto_disable=True)EventFlags(auto_disable=True)

The event disables itself after firing. Call enable()event_enable to arm it again before the next wait.

EventFlags(disabled=True)EventFlags(disabled=True)

The event starts disabled and will not cause poll()evset_poll to return until you call enable()event_enable.

Call enable()event_enable and disable()event_disable at any time to include or exclude an event from the next poll()evset_poll. is_triggeredevent_is_triggered reflects whether the event’s condition currently holds, independent of whether the event is enabled.

Next steps

  • Transcription stages: how the model produces and revises text, and how to handle chunk overwrites.

  • Overview: TTS overview and the PCM output format.