--- description: "How the ABR SDK's streaming pipeline works: Buffers, Events, and EventSets." --- # Streaming and chunks The ABR SDK's streaming pipeline is built on three low-level primitives: {api}`Buffer`, {api}`EventSet`, and {api}`Event`. The {api}`Asr.push` and {api}`Asr.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. {api}`Asr.push` and {api}`Tts.push` manage both layers internally. Most callers never need to interact with them directly. ## Buffers A {api}`Buffer` is a fixed-capacity FIFO byte queue inside the neural network pipeline. The {api}`Asr` class exposes two: - **{api}`Asr.input_buffer`:** receives raw PCM audio bytes that you write in. - **{api}`Asr.text_chunk_output_buffer`:** emits serialized {api}`AsrChunk` structs as the model produces them. | Property or method | Description | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | {api}`buffer.size ` | Total capacity in bytes (fixed for the lifetime of the buffer). | | {api}`buffer.level ` | Bytes that can be pushed, or pulled up to the next flush marker. | | {api}`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. | | {api}`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 {api}`Buffer.push` or {api}`Buffer.pull` directly. {api}`Asr.push` manages both buffers for you. ## Events and EventSets Polling {api}`Buffer.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 {api}`EventSet` groups one or more {api}`Event` objects into a single poll target. Call {api}`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. ::::{lang-set} :::{lang} python It returns `True` if an event fired, `False` if the timeout expired, and raises `InterruptedError` if interrupted by a signal. ::: :::{lang} c 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 {api}`evset.interrupt() ` to unblock a {api}`EventSet.poll` call that is waiting on another thread. Create events from an {api}`EventSet` using this factory method: **{api}`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`. ::::{lang-set} :::{lang} python After a flush, keep pulling from the output buffer until {api}`Buffer.pull` returns `True` as its second value. That flush marker ends the output for the flushed input. ::: :::{lang} c After a flush, keep pulling from the output buffer until {api}`Buffer.pull` sets its `flush` argument. That flush marker ends the output for the flushed input. ::: :::: ### Event flags and state Pass {api}`EventFlags` when creating an event to control its initial behavior: | Flag | Effect | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | {api}`EventFlags(auto_disable=True) ` | The event disables itself after firing. Call {api}`Event.enable` to arm it again before the next wait. | | {api}`EventFlags(disabled=True) ` | The event starts disabled and will not cause {api}`EventSet.poll` to return until you call {api}`Event.enable`. | Call {api}`Event.enable` and {api}`Event.disable` at any time to include or exclude an event from the next {api}`EventSet.poll`. {api}`Event.is_triggered` reflects whether the event's condition currently holds, independent of whether the event is enabled. :::{admonition} Next steps :class: hint - {doc}`/sdk/asr/transcription-stages`: how the model produces and revises text, and how to handle chunk overwrites. - {doc}`/sdk/tts/overview`: TTS overview and the PCM output format. :::