Editing SimTX API v24/Transmitter session

{{SimTX API v24 navigation}}
A '''transmitter session''' puts a station on the air. The client describes the station, waits for a transmitter slot, and then streams audio or IQ samples in real time while the server modulates them, models the power amplifier and antenna, and propagates the result to every receiver. Transmitter sessions use role 2 (<code>TX_AUDIO</code>) or role 3 (<code>TX_GENERATED</code>) and require an account with the <code>game.transmit</code> [[SimTX API v24/Permissions|permission]].

== Packets ==
{| class="wikitable"
! Direction !! ID !! Packet !! When
|-
| C2S || 2 || [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] || Once, right after the handshake.
|-
| S2C || 4 || [[SimTX API v24/Packets/TxQueue|TxQueue]] || While waiting for a slot.
|-
| S2C || 3 || [[SimTX API v24/Packets/TxAccept|TxAccept]] || When the station goes on air.
|-
| S2C || 5 || [[SimTX API v24/Packets/TxReject|TxReject]] || If the request is refused.
|-
| C2S || 3 || [[SimTX API v24/Packets/SampleBlock|SampleBlock]] || Continuously after TxAccept (role 2).
|-
| C2S || 14 || [[SimTX API v24/Packets/TxModeInfo|TxModeInfo]] || Optional, after TxAccept.
|-
| C2S || 19 || [[SimTX API v24/Packets/TxUpdate|TxUpdate]] || Optional, to change settings on air.
|-
| S2C || 23 || [[SimTX API v24/Packets/TxUpdateAck|TxUpdateAck]] || In reply to each TxUpdate.
|-
| S2C || 7 || [[SimTX API v24/Packets/TxTelemetry|TxTelemetry]] || About every 50 ms while on air.
|-
| S2C || 6 || [[SimTX API v24/Packets/TxKick|TxKick]] || If the station is taken off air.
|}

== Sequence ==
<syntaxhighlight lang="text">
 client                                                 server
   | POST /api/v1/game-tickets {role: "tx-audio"} (HTTPS)   |
   | -- TLS connect, Handshake (role 2, ticket) ----------> |
   | <------------------------------ [30] HandshakeResult  |
   | -- [2] TransmitterSessionRequest -------------------> |
   | <----------------------------------- [4] TxQueue      |   (only if all slots are busy;
   | <----------------------------------- [4] TxQueue      |    repeats about once a second)
   | <----------------------------------- [3] TxAccept     |
   | -- [3] SampleBlock ---------------------------------> |
   | <----------------------------------- [7] TxTelemetry  |
   | -- [3] SampleBlock ---------------------------------> |
   | -- [19] TxUpdate -----------------------------------> |
   | <----------------------------------- [23] TxUpdateAck |
   |                    ...                                |
   | -- close ------------------------------------------>  |   off air
</syntaxhighlight>

== Admission ==
After the request, the server answers with one of:
* '''[[SimTX API v24/Packets/TxAccept|TxAccept]]''': the station is on air. Start streaming.
* '''[[SimTX API v24/Packets/TxQueue|TxQueue]]''': all transmitter slots on the server are busy and the client is waiting in line. Further TxQueue packets report the position as it changes, at most about once a second, until TxAccept arrives. Keep reading and do not send samples yet.
* '''[[SimTX API v24/Packets/TxReject|TxReject]]''': the request was refused. The reason is a human-readable string, and the connection closes.

An invalid request (a missing required field, an unknown modulation name, a value outside the ranges listed on [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]]) closes the connection without a TxReject.

== Sources ==
The <code>sourceType</code> field decides what the client streams.

{| class="wikitable"
! Source type !! Role !! Client sends !! Server does
|-
| <code>AUDIO_STREAM</code>, <code>MICROPHONE</code>, <code>PIPEWIRE</code> || 2 || Mono audio, one <code>f32</code> per sample at <code>sampleRate</code>, nominal range ±1 || Applies <code>audioGain</code>, the audio low cut and compression, then modulates with the requested modulation.
|-
| <code>GNU_RADIO_IQ</code> || 2 || Complex baseband, I and Q interleaved, at <code>sampleRate</code>, centred on the carrier frequency || Applies <code>audioGain</code>, normalises average power to at most 1.0 (equal to <code>powerWatts</code>), and transmits it as is. Use modulation <code>IQ</code>.
|-
| <code>WHITE_NOISE</code> || 3 || Nothing || Generates the signal itself.
|}

With an IQ source, the client is the modulator. Anything that can be expressed as complex baseband, including digital modes the server has never heard of, can be transmitted this way.

=== Sample rates ===
The server processes each transmitter at a rate equal to the declared <code>sampleRate</code>, raised to at least 240,000 for <code>WFM</code> and limited to 10,000,000. Audio is resampled to that rate, by a factor of at most 128; a lower audio rate is rejected with ''Source sample rate is too low for this modulation''. Raw IQ above 10,000,000 samples per second is rejected.

== Streaming ==
Samples are sent in [[SimTX API v24/Packets/SampleBlock|SampleBlock]] packets of up to 65,536 values. IQ sources may use the compact 16-bit form, which halves the bandwidth.

=== Pacing ===
The client must send samples '''in real time''', at the rate it declared.
* The server keeps about 0.5 s of samples as a playout buffer. When its ring buffer is 90 % full, it stops reading from the socket, and TCP flow control slows the client down. Sending slightly ahead is therefore safe.
* Input arriving faster than 1.05 times the declared rate, beyond a burst allowance of about two seconds of samples, is '''discarded''' block by block without notice.
* The <code>bufferSeconds</code> field of [[SimTX API v24/Packets/TxTelemetry|TxTelemetry]] reports the server's buffer. It is the best pacing signal available: keep it above zero and below about two seconds.

=== Keying ===
There is no push-to-talk packet. A station is on air from TxAccept until the connection closes. To go quiet without disconnecting, send silence, or set the power to 0 with [[SimTX API v24/Packets/TxUpdate|TxUpdate]].

An audio source that delivers no samples for 15 seconds is disconnected. An IQ source is not disconnected for being idle, but it is still on air, transmitting nothing, and still occupies a transmitter slot.

To leave cleanly, shut down the sending side of the socket (half-close) and then close it.

== Live updates ==
[[SimTX API v24/Packets/TxUpdate|TxUpdate]] changes frequency, power, bandwidth, audio low cut, drive, headroom and compression while on air. The server answers each update with a [[SimTX API v24/Packets/TxUpdateAck|TxUpdateAck]] that reports, for every field, whether it was applied and the value now in effect. At most one update is applied per 250 ms, and the frequency at most once per second; updates sent faster are refused in the ack, not queued.

Other settings, such as the modulation, sample rate, location or antenna, cannot be changed on air. Close the session and open a new one.

== Telemetry ==
While on air the server sends [[SimTX API v24/Packets/TxTelemetry|TxTelemetry]] about every 50 ms. It reports forward, delivered and reflected power, SWR, amplifier compression and temperature, thermal foldback, and the playout buffer level, the same values the official transmitter shows on its meters. Telemetry is coalesced: a slow reader gets the newest values, not a backlog.

The client must keep reading. A client that stops reading for 5 seconds is disconnected.

== Taken off air ==
The server can end a session with [[SimTX API v24/Packets/TxKick|TxKick]], when a moderator or the server operator removes the station, or the address is banned. The default reason is ''Disconnected by the server administrator''. The reason is a human-readable string, and the connection closes immediately after. When the account lease expires or the account changes, the connection is closed without a TxKick. See [[SimTX API v24/Connection and handshake#Accounts on the connection|Accounts on the connection]].

== Limits ==
* The account's <code>tx.pa_limit.N</code> capability caps the power in watts. Requests above it are reduced to the limit; [[SimTX API v24/Packets/TxTelemetry|TxTelemetry]] shows the actual power.
* The number of simultaneous transmitters per account is limited. See [[SimTX API v24/Limits and errors]].

== Checklist ==
# Obtain a bearer credential through [[SimTX API v24/Device login|device login]] or a personal credential.
# <code>POST /api/v1/game-tickets</code> with <code>{"serverId": …, "role": "tx-audio"}</code>.
# Connect with TLS. Send a [[SimTX API v24/Packets/Handshake|Handshake]] with role 2, authKind 1 and the ticket.
# Read a [[SimTX API v24/Packets/HandshakeResult|HandshakeResult]]; require status 0.
# Send <code>u8</code> 2 and a [[SimTX API v24/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] with at least fields 1 to 13.
# Read [[SimTX API v24/Packets/TxQueue|TxQueue]] packets until [[SimTX API v24/Packets/TxAccept|TxAccept]], or stop at [[SimTX API v24/Packets/TxReject|TxReject]].
# Stream <code>u8</code> 3 [[SimTX API v24/Packets/SampleBlock|SampleBlock]] packets in real time. Read telemetry on another thread.
# Close the socket to go off air.

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