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
Python
TypeScript
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.
const streamer = await client.openStreamer(["time", "temperature"]);
try {
for await (const frame of streamer) {
console.log(Array.from(frame.get("temperature")));
}
} finally {
streamer.close();
}The loop waits for each frame. The finally block closes the streamer, also when the
code throws 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:
Python
TypeScript
for frame in streamer:
if "temperature" in frame:
latest = frame["temperature"][-1]for await (const frame of streamer) {
const temperature = frame.get("temperature");
if (temperature.length > 0) {
const latest = temperature.at(-1);
}
}Read one frame
Python
TypeScript
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.
read waits for the next frame:
const frame = await streamer.read();read has no timeout. When the Core sends nothing for 15 seconds, read throws, so a
lost connection does not stop your code.
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:
Python
TypeScript
streamer.update_channels(["time", "temperature", "pressure"])await streamer.update(["time", "temperature", "pressure"]);update returns before the Core streams the new channels. To wait until it does, pass
{ waitForAck: true } as the second argument. Read frames at the same time, or the
update does not return.
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:
Python
TypeScript
streamer = client.open_streamer(
["time", "temperature"], downsample_factor=10, throttle_rate=10
)import { Rate } from "@synnaxlabs/client";
const streamer = await client.openStreamer({
channels: ["time", "temperature"],
downsampleFactor: 10,
throttleRate: Rate.hz(10),
});downsample_factor-> keep everyNth 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
Python
TypeScript
streamer.close()streamer.close();A streamer that you do not close keeps its connection to the Core open.
Streamer options
Python
TypeScript
channelslist[str] | list[int]The names or keys of the channels to stream.
downsample_factorint = 1Keep every
downsample_factorth sample of each channel, counted across writes.throttle_ratefloat = 0The largest number of frames each second, in Hz. With 0, the Core sends each frame when it receives it.
keep_aliveTimeSpan | float = 5 sHow often the Core sends a keep-alive message. A read raises
Unreachableafter three intervals with no message. Use at least 2 seconds, or 0 to turn off the check. A number is seconds.
channelsstring[] | number[]The names or keys of the channels to stream.
downsampleFactornumber = 1Keep every
downsampleFactorth sample of each channel, counted across writes.throttleRateRate = 0The largest number of frames each second. With 0, the Core sends each frame when it receives it.
keepAliveTimeSpan = 5 sHow often the Core tells the streamer that the connection is alive. When three intervals pass with no message,
readthrows. The value must be at least 2 s. WithTimeSpan.ZERO,readwaits with no limit.