Editing SimTX API/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.

'''<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]]