v0.61.3
ReferenceClient librariesStream data

Stream data

Get samples as the Core receives them with a streamer in the Python and TypeScript clients: read frames, change channels, slow the stream, and close the streamer.

A streamer gets samples from the Core as the Core receives them. Use it to process live data, to show live values in your own app, or to react to a value in a script. A streamer gets only new samples. To get stored samples, read data. Samples from client.write and from writers in persist mode do not reach streamers, as writer modes says.

Open a streamer and read frames

import synnax as sy

client = sy.Synnax()

with client.open_streamer(["time", "temperature"]) as streamer:
    for frame in streamer:
        print(frame["temperature"].to_numpy())

The loop waits for each frame. The with block closes the streamer, also when the code raises an error.

Each frame holds the samples of one write, as a frame. A frame can hold samples for only some of the channels, so check before you use a channel:

for frame in streamer:
    if "temperature" in frame:
        latest = frame["temperature"][-1]

Read one frame

read waits for the next frame. With a timeout, it returns None when no frame comes in time:

frame = streamer.read(timeout=5)
if frame is None:
    print("No data in 5 seconds")

The timeout is a number of seconds or a TimeSpan.

Stream with asyncio in Python

open_async_streamer gives a streamer for asyncio code:

async with await client.open_async_streamer(["time", "temperature"]) as streamer:
    async for frame in streamer:
        print(frame["temperature"].to_numpy())

The async streamer has no per-call timeout on read, and it cannot change its channels. Both Python streamers detect a lost connection through keep-alive messages. With the default keep_alive of 5 seconds, a read fails after 15 seconds without a message. The TypeScript streamer is always async.

Change the channels

To stream other channels, give the streamer a new list. The list replaces the old channels:

streamer.update_channels(["time", "temperature", "pressure"])

Slow the stream

When your Python code reads more slowly than frames come, the Core drops frames. The TypeScript client keeps unread frames in memory instead. When they pass 256 MB, it closes the streamer, and read throws stream holds more than 268435456 bytes of unread messages. To get all the samples, slow the stream, or read the stored data later. Two options reduce the data:

streamer = client.open_streamer(
    ["time", "temperature"], downsample_factor=10, throttle_rate=10
)
  • downsample_factor -> keep every Nth sample of each channel, counted across writes. The Core drops the other samples and does not average them. When a write holds no sample that the Core keeps, the Core sends nothing for it.
  • throttle_rate -> send at most this many frames each second. The Core joins the samples between two sends into one frame, so the streamer gets all samples in fewer frames.

Close the streamer

streamer.close()

A streamer that you do not close keeps its connection to the Core open.

Streamer options

channelslist[str] | list[int]

The names or keys of the channels to stream.

downsample_factorint = 1

Keep every downsample_factorth sample of each channel, counted across writes.

throttle_ratefloat = 0

The largest number of frames each second, in Hz. With 0, the Core sends each frame when it receives it.

keep_aliveTimeSpan | float = 5 s

How often the Core sends a keep-alive message. A read raises Unreachable after three intervals with no message. Use at least 2 seconds, or 0 to turn off the check. A number is seconds.