SimTX API v24/Transmitter session

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 (TX_AUDIO) or role 3 (TX_GENERATED) and require an account with the game.transmit permission.

Packets

Direction	ID	Packet	When
C2S	2	TransmitterSessionRequest	Once, right after the handshake.
S2C	4	TxQueue	While waiting for a slot.
S2C	3	TxAccept	When the station goes on air.
S2C	5	TxReject	If the request is refused.
C2S	3	SampleBlock	Continuously after TxAccept (role 2).
C2S	14	TxModeInfo	Optional, after TxAccept.
C2S	19	TxUpdate	Optional, to change settings on air.
S2C	23	TxUpdateAck	In reply to each TxUpdate.
S2C	7	TxTelemetry	About every 50 ms while on air.
S2C	6	TxKick	If the station is taken off air.

Sequence

 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

Admission

After the request, the server answers with one of:

• TxAccept: the station is on air. Start streaming.
• 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.
• 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 TransmitterSessionRequest) closes the connection without a TxReject.

Sources

The sourceType field decides what the client streams.

Source type	Role	Client sends	Server does
AUDIO_STREAM, MICROPHONE, PIPEWIRE	2	Mono audio, one f32 per sample at sampleRate, nominal range ±1	Applies audioGain, the audio low cut and compression, then modulates with the requested modulation.
GNU_RADIO_IQ	2	Complex baseband, I and Q interleaved, at sampleRate, centred on the carrier frequency	Applies audioGain, normalises average power to at most 1.0 (equal to powerWatts), and transmits it as is. Use modulation IQ.
WHITE_NOISE	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 sampleRate, raised to at least 240,000 for WFM 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 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 bufferSeconds field of 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 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

TxUpdate changes frequency, power, bandwidth, audio low cut, drive, headroom and compression while on air. The server answers each update with a 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 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 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 Accounts on the connection.

Limits

• The account's tx.pa_limit.N capability caps the power in watts. Requests above it are reduced to the limit; TxTelemetry shows the actual power.
• The number of simultaneous transmitters per account is limited. See SimTX API/Limits and errors.

Checklist

1. Obtain a bearer credential through device login or a personal credential.
2. POST /api/v1/game-tickets with {"serverId": …, "role": "tx-audio"}.
3. Connect with TLS. Send a Handshake with role 2, authKind 1 and the ticket.
4. Read a HandshakeResult; require status 0.
5. Send u8 2 and a TransmitterSessionRequest with at least fields 1 to 13.
6. Read TxQueue packets until TxAccept, or stop at TxReject.
7. Stream u8 3 SampleBlock packets in real time. Read telemetry on another thread.
8. Close the socket to go off air.