Clanker: Remove development history and server internals

2026-10-24T17:16:35Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 80:		Line 80:

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>sample_block_audio</code>''' (client to server, 23 bytes):		'''<code>sample_block_audio</code>''' (client to server, 23 bytes):

Clanker: Protocol v25 reference: SampleBlock

2026-10-24T17:00:12Z

Protocol v25 reference: SampleBlock

← Older revision		Revision as of 17:00, 24 October 2026
Line 1:		Line 1:
	#~~REDIRECT~~ [[SimTX API ~~v24~~/Packets/SampleBlock]]		{{SimTX API navigation}}
			{{SimTX packet
			\| name = SampleBlock
			\| frame = ClientFrame
			\| field = 13
			\| member = samples
			\| direction = c2s
			\| session = [[SimTX API/Transmitter session\|Transmitter]]
			\| roles = <code>ROLE_TX_AUDIO</code>, after [[SimTX API/Packets/TxAccept\|TxAccept]].
			\| permission = None
			\| group = transmitter
			\| file = session.proto
			}}
			'''SampleBlock''' carries samples for the server to transmit. After [[SimTX API/Packets/TxAccept\|TxAccept]], a <code>ROLE_TX_AUDIO</code> client streams these continuously, in real time, at the <code>sample_rate</code> it declared. A block holds audio, IQ as floats, or IQ in a compact 16-bit form.

			== Definition ==
			<syntaxhighlight lang="protobuf">
			message SampleBlock {
			message CompactIq {
			float scale = 1;
			bytes samples = 2;
			}
			oneof data {
			PackedFloats audio = 1;
			PackedFloats iq = 2;
			CompactIq compact_iq = 3;
			}
			}
			</syntaxhighlight>

			== Fields ==
			{\| class="wikitable"
			! # !! Field !! Type !! Description
			\|-
			\| 1 \|\| <code>audio</code> \|\| [[#PackedFloats\|PackedFloats]] \|\| Member of <code>oneof data</code>. Audio sources: mono samples, one float per sample, nominal range ±1.
			\|-
			\| 2 \|\| <code>iq</code> \|\| [[#PackedFloats\|PackedFloats]] \|\| Member of <code>oneof data</code>. <code>GNU_RADIO_IQ</code>: I and Q interleaved as floats.
			\|-
			\| 3 \|\| <code>compact_iq</code> \|\| [[#SampleBlockCompactIq\|CompactIq]] \|\| Member of <code>oneof data</code>. <code>GNU_RADIO_IQ</code>: I and Q as big-endian <code>int16</code> pairs with a block scale.
			\|}

			<span id="SampleBlockCompactIq"></span>
			=== CompactIq ===
			{\| class="wikitable"
			! # !! Field !! Type !! Description
			\|-
			\| 1 \|\| <code>scale</code> \|\| <code>float</code> \|\| Block scale, finite and ≥ 0.
			\|-
			\| 2 \|\| <code>samples</code> \|\| <code>bytes</code> \|\| Interleaved I, Q as big-endian <code>int16</code>; value = <code>q × scale / 32767</code>. An even number of values (a multiple of 4 bytes), at most 65,536 values.
			\|}

			=== PackedFloats ===
			<syntaxhighlight lang="protobuf">
			message PackedFloats {
			repeated float values = 1;
			}
			</syntaxhighlight>
			{\| class="wikitable"
			! # !! Field !! Type !! Description
			\|-
			\| 1 \|\| <code>values</code> \|\| <code>repeated float</code> \|\| Sample values, packed encoding. 1 to 65,536 values per block.
			\|}

			== Sample content ==
			{\| class="wikitable"
			! Source type !! Member !! Content !! Processing
			\|-
			\| <code>AUDIO_STREAM</code>, <code>MICROPHONE</code>, <code>PIPEWIRE</code> \|\| <code>audio</code> \|\| Mono, one value per sample, nominal range ±1. \|\| Multiplied by <code>audio_gain</code>, clipped to ±100, then modulated.
			\|-
			\| <code>GNU_RADIO_IQ</code> (modulation <code>IQ</code>) \|\| <code>iq</code> or <code>compact_iq</code> \|\| Complex baseband, I and Q interleaved, centred on the carrier. \|\| Multiplied by <code>audio_gain</code> and clipped to ±2.0. Average power is normalised to at most 1.0, which corresponds to <code>power_watts</code>.
			\|}

			A block may hold up to 65,536 values. Blocks of 10 to 50 ms are a good compromise between overhead and latency. <code>compact_iq</code> 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 <code>buffer_seconds</code> in [[SimTX API/Packets/TxTelemetry\|TxTelemetry]].

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

			'''<code>sample_block_audio</code>''' (client to server, 23 bytes):

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

			'''<code>sample_block_iq_float</code>''' (client to server, 23 bytes):

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

			'''<code>sample_block_compact_iq</code>''' (client to server, 20 bytes):

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

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

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

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

New page

#REDIRECT [[SimTX API v24/Packets/SampleBlock]]

SimTX API/Packets/SampleBlock - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference: SampleBlock

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