Editing SimTX API/Packets/IqStreamDescriptor

{{SimTX API navigation}}
{{SimTX packet
| name = IqStreamDescriptor
| frame = ServerFrame
| field = 11
| member = iq_descriptor
| direction = s2c
| session = [[SimTX API/Receiver session|Receiver]]
| roles = <code>ROLE_RECEIVER</code>.
| permission = None
| answers = [[SimTX API/Packets/ReceiverStart|ReceiverStart]]
| group = receiver
| file = session.proto
}}
'''IqStreamDescriptor''' states the parameters of the IQ stream a receiver is about to get. The server sends it once, after [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code> and before the first [[SimTX API/Packets/IqBlock|IqBlock]]. Its values are authoritative and may differ from the request.

== Definition ==
<syntaxhighlight lang="protobuf">
message IqStreamDescriptor {
  int32 sample_rate = 1;           // complex samples per second
  double center_frequency_hz = 2;
  int32 chunk_samples = 3;         // complex samples per IqBlock
  SampleFormat sample_format = 4;
  bool timestamped = 5;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>sample_rate</code> || <code>int32</code> || Negotiated sample rate, complex samples per second.
|-
| 2 || <code>center_frequency_hz</code> || <code>double</code> || Centre frequency in Hz.
|-
| 3 || <code>chunk_samples</code> || <code>int32</code> || Complex samples in every following [[SimTX API/Packets/IqBlock|IqBlock]].
|-
| 4 || <code>sample_format</code> || [[SimTX API/Data types#SampleFormat|SampleFormat]] || Format of <code>IqBlock.samples</code>.
|-
| 5 || <code>timestamped</code> || <code>bool</code> || True when every IqBlock carries a first-sample timestamp.
|}

== Usage ==
* Size buffers from <code>chunk_samples</code> and <code>sample_format</code>: each [[SimTX API/Packets/IqBlock|IqBlock]] carries exactly <code>chunk_samples × 2 × bytesPerComponent</code> sample bytes, where <code>bytesPerComponent</code> is 2 for <code>INT16</code> and 1 for <code>INT8</code>.
* No second descriptor is sent after a [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]]. Track the frequency from the retune confirmations.

== Example ==
Complete frames, including the varint length prefix.

'''<code>iq_descriptor_timestamped</code>''' (server to client, 21 bytes):

<syntaxhighlight lang="text">
14                            frame length 20
5A 12                         iq_descriptor (IqStreamDescriptor), 18 bytes
  08 80 F7 02                 sample_rate = 48000
  11 00 00 00 00 34 FC 5A 41  center_frequency_hz = 7074000.0
  18 80 20                    chunk_samples = 4096
  28 01                       timestamped = true
</syntaxhighlight>

== See also ==
* [[SimTX API/Receiver session#Negotiation|Negotiation]]

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