Editing SimTX API v24/Packets/SampleBlock

{{SimTX API v24 navigation}}
{{SimTX packet v24
| name = SampleBlock
| id = 3
| hex = 0x03
| direction = c2s
| session = [[SimTX API v24/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 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 ==
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 v24/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 v24/Transmitter session#Streaming|Streaming]]

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