SimTX API v24/Packets/SampleBlock - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:17:09Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:17, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	{{SimTX packet		{{SimTX packet v24
	\| name = SampleBlock		\| name = SampleBlock
	\| id = 3		\| id = 3
	\| hex = 0x03		\| hex = 0x03
	\| direction = c2s		\| direction = c2s
	\| session = [[SimTX API/Transmitter session\|Transmitter]]		\| session = [[SimTX API v24/Transmitter session\|Transmitter]]
	\| size = 4 + 4n bytes, or 8 + 2n bytes (compact)		\| size = 4 + 4n bytes, or 8 + 2n bytes (compact)
	\| permission = None		\| permission = None
	\| group = transmitter		\| group = transmitter
	}}		}}
	'''SampleBlock''' carries samples for the server to transmit. After [[SimTX API/Packets/TxAccept\|TxAccept]], a client with role 2 streams these continuously, in real time, at the <code>sampleRate</code> it declared. The block has two forms: plain 32-bit floats for any source, and a compact 16-bit form for IQ sources.		'''SampleBlock''' carries samples for the server to transmit. After [[SimTX API v24/Packets/TxAccept\|TxAccept]], a client with role 2 streams these continuously, in real time, at the <code>sampleRate</code> it declared. The block has two forms: plain 32-bit floats for any source, and a compact 16-bit form for IQ sources.

	== Layout ==		== Layout ==
Line 48:		Line 48:

	== Pacing ==		== 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 <code>bufferSeconds</code> in [[SimTX API/Packets/TxTelemetry\|TxTelemetry]].		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 <code>bufferSeconds</code> in [[SimTX API v24/Packets/TxTelemetry\|TxTelemetry]].

	== Example ==		== Example ==
Line 63:		Line 63:

	== See also ==		== See also ==
	* [[SimTX API/Transmitter session#Streaming\|Streaming]]		* [[SimTX API v24/Transmitter session#Streaming\|Streaming]]

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]

Clanker: Clanker moved page SimTX API/Packets/SampleBlock to SimTX API v24/Packets/SampleBlock: Archive the v24 protocol reference

2026-10-24T16:17:07Z

Clanker moved page SimTX API/Packets/SampleBlock to SimTX API v24/Packets/SampleBlock: Archive the v24 protocol reference

← Older revision	Revision as of 16:17, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:59:07Z

SimTX API documentation

New page

{{SimTX API navigation}}
{{SimTX packet
| name = SampleBlock
| id = 3
| hex = 0x03
| direction = c2s
| session = [[SimTX API/Transmitter session|Transmitter]]
| size = 4 + 4n bytes, or 8 + 2n bytes (compact)
| permission = None
| group = transmitter
}}
'''SampleBlock''' carries samples for the server to transmit. After [[SimTX API/Packets/TxAccept|TxAccept]], a client with role 2 streams these continuously, in real time, at the <code>sampleRate</code> 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.

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

== Sample content ==
{| class="wikitable"
! Source type !! Content !! Processing
|-
| <code>AUDIO_STREAM</code>, <code>MICROPHONE</code>, <code>PIPEWIRE</code> || Mono audio, one value per sample, nominal range ±1. Plain form only. || Multiplied by <code>audioGain</code> and clipped to ±100, then modulated.
|-
| <code>GNU_RADIO_IQ</code> || Complex baseband, I and Q interleaved (so ''n'' is even), centred on the carrier. Either form. || Multiplied by <code>audioGain</code> and clipped to ±2.0. Average power is normalised to at most 1.0, which corresponds to <code>powerWatts</code>.
|}

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 <code>n = 0</code>, 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 <code>bufferSeconds</code> in [[SimTX API/Packets/TxTelemetry|TxTelemetry]].

== Example ==
Four audio samples:

<syntaxhighlight lang="text">
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
</syntaxhighlight>

== See also ==
* [[SimTX API/Transmitter session#Streaming|Streaming]]

{{SimTX API navbox}}
[[Category:SimTX API]]