SimTX API/Packets/SampleBlock

SampleBlock

Frame	ClientFrame, field 13
Member	samples
Direction	Client → server
Session	Transmitter
Roles	ROLE_TX_AUDIO, after TxAccept.
Permission	None
Answered by
Answers
Defined in	session.proto

SampleBlock carries samples for the server to transmit. After TxAccept, a ROLE_TX_AUDIO client streams these continuously, in real time, at the sample_rate it declared. A block holds audio, IQ as floats, or IQ in a compact 16-bit form.

Definition

message SampleBlock {
  message CompactIq {
    float scale = 1;
    bytes samples = 2;
  }
  oneof data {
    PackedFloats audio = 1;
    PackedFloats iq = 2;
    CompactIq compact_iq = 3;
  }
}

Fields

#	Field	Type	Description
1	audio	PackedFloats	Member of oneof data. Audio sources: mono samples, one float per sample, nominal range ±1.
2	iq	PackedFloats	Member of oneof data. GNU_RADIO_IQ: I and Q interleaved as floats.
3	compact_iq	CompactIq	Member of oneof data. GNU_RADIO_IQ: I and Q as big-endian int16 pairs with a block scale.

CompactIq

#	Field	Type	Description
1	scale	float	Block scale, finite and ≥ 0.
2	samples	bytes	Interleaved I, Q as big-endian int16; value = q × scale / 32767. An even number of values (a multiple of 4 bytes), at most 65,536 values.

PackedFloats

message PackedFloats {
  repeated float values = 1;
}

#	Field	Type	Description
1	values	repeated float	Sample values, packed encoding. 1 to 65,536 values per block.

Sample content

Source type	Member	Content	Processing
AUDIO_STREAM, MICROPHONE, PIPEWIRE	audio	Mono, one value per sample, nominal range ±1.	Multiplied by audio_gain, clipped to ±100, then modulated.
GNU_RADIO_IQ (modulation IQ)	iq or compact_iq	Complex baseband, I and Q interleaved, centred on the carrier.	Multiplied by audio_gain and clipped to ±2.0. Average power is normalised to at most 1.0, which corresponds to power_watts.

A block may hold up to 65,536 values. Blocks of 10 to 50 ms are a good compromise between overhead and latency. compact_iq halves the uplink.

Errors

An empty block, more than 65,536 values, IQ data on an audio source, an odd value count on an IQ source, or a negative or non-finite compact scale ends the session.

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 buffer_seconds in TxTelemetry.

Examples

Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

sample_block_audio (client to server, 23 bytes):

16                                                  frame length 22
6A 14                                               samples (SampleBlock), 20 bytes
  0A 12                                             audio (PackedFloats), 18 bytes
    0A 10 00 00 00 00 00 00 00 3F 00 00 80 BE 00 00 80 3F
                                                    values = [0, 0.5, -0.25, 1] (packed, 4 values)

sample_block_iq_float (client to server, 23 bytes):

16                                                  frame length 22
6A 14                                               samples (SampleBlock), 20 bytes
  12 12                                             iq (PackedFloats), 18 bytes
    0A 10 00 00 00 3E 00 00 00 BE 00 00 40 3F 00 00 40 BF
                                                    values = [0.125, -0.125, 0.75, -0.75] (packed, 4 values)

sample_block_compact_iq (client to server, 20 bytes):

13                                 frame length 19
6A 11                              samples (SampleBlock), 17 bytes
  1A 0F                            compact_iq (CompactIq), 15 bytes
    0D 00 00 00 3F                 scale = 0.5
    12 08 7F FF 80 01 40 00 C0 01  samples, 8 bytes

See also

• Streaming