SimTX API v24/Packets/SampleBlock

SampleBlock

Frame	{{{frame}}}, field {{{field}}}
Member	{{{member}}}
Direction	Client → server
Session	Transmitter
Roles
Permission	None
Answered by
Answers
Defined in

SampleBlock carries samples for the server to transmit. After TxAccept, a client with role 2 streams these continuously, in real time, at the sampleRate it declared. The block has two forms: plain 32-bit floats for any source, and a compact 16-bit form for IQ sources.

Layout

The sign of the first field selects the form.

Field	Type	Description
packetId	u8	Always 3.
n	i32	Positive: plain form with n values. Negative: compact form with −n values. Zero is invalid.
plain form
samples	n × f32	Sample values. 1 ≤ n ≤ 65,536.
compact form
scale	f32	Finite and ≥ 0.
samples	(−n) × i16	Value = q × scale / 32767. −n must be even and at most 65,536.

Sample content

Source type	Content	Processing
AUDIO_STREAM, MICROPHONE, PIPEWIRE	Mono audio, one value per sample, nominal range ±1. Plain form only.	Multiplied by audioGain and clipped to ±100, then modulated.
GNU_RADIO_IQ	Complex baseband, I and Q interleaved (so n is even), centred on the carrier. Either form.	Multiplied by audioGain and clipped to ±2.0. Average power is normalised to at most 1.0, which corresponds to powerWatts.

A block may contain any number of samples up to the limit; blocks of 10–50 ms are a good compromise between overhead and latency.

Errors

The connection is closed without a message for n = 0, more than 65,536 values, a compact block on an audio source, an odd value count on an IQ source, or a negative or non-finite compact scale.

Pacing

Send samples at the declared rate. Input faster than 1.05 × that rate, after a burst allowance of about 2 seconds, is discarded a whole block at a time. When the server's buffer is 90 % full, it stops reading the socket and TCP flow control holds the client back. Watch bufferSeconds in TxTelemetry.

Example

Four audio samples:

03               packetId 3
00 00 00 04      n = 4
00 00 00 00      0.0
3F 00 00 00      0.5
3F 80 00 00      1.0
BF 00 00 00      -0.5

See also

• Streaming