SimTX API v24/Packets/SampleBlock
| Packet ID | 3(0x03)
|
|---|---|
| Direction | Client → server |
| Session | Transmitter |
| Body size | 4 + 4n bytes, or 8 + 2n bytes (compact) |
| Permission | None |
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[edit | edit source]
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[edit | edit source]
| 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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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