SimTX API v24/Transmitter session - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:27:22Z

Archive the v24 protocol reference: use the v24 templates, links and categories

Clanker: Clanker moved page SimTX API/Transmitter session to SimTX API v24/Transmitter session: Archive the v24 protocol reference

2026-10-24T16:20:40Z

Clanker moved page SimTX API/Transmitter session to SimTX API v24/Transmitter session: Archive the v24 protocol reference

← Older revision	Revision as of 16:20, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:56:40Z

SimTX API documentation

New page

{{SimTX API 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/Permissions|permission]].

== Packets ==
{| class="wikitable"
! Direction !! ID !! Packet !! When
|-
| C2S || 2 || [[SimTX API/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] || Once, right after the handshake.
|-
| S2C || 4 || [[SimTX API/Packets/TxQueue|TxQueue]] || While waiting for a slot.
|-
| S2C || 3 || [[SimTX API/Packets/TxAccept|TxAccept]] || When the station goes on air.
|-
| S2C || 5 || [[SimTX API/Packets/TxReject|TxReject]] || If the request is refused.
|-
| C2S || 3 || [[SimTX API/Packets/SampleBlock|SampleBlock]] || Continuously after TxAccept (role 2).
|-
| C2S || 14 || [[SimTX API/Packets/TxModeInfo|TxModeInfo]] || Optional, after TxAccept.
|-
| C2S || 19 || [[SimTX API/Packets/TxUpdate|TxUpdate]] || Optional, to change settings on air.
|-
| S2C || 23 || [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]] || In reply to each TxUpdate.
|-
| S2C || 7 || [[SimTX API/Packets/TxTelemetry|TxTelemetry]] || About every 50 ms while on air.
|-
| S2C || 6 || [[SimTX API/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/Packets/TxAccept|TxAccept]]''': the station is on air. Start streaming.
* '''[[SimTX API/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/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/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/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/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/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/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/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/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/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/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/Packets/TxTelemetry|TxTelemetry]] shows the actual power.
* The number of simultaneous transmitters per account is limited. See [[SimTX API/Limits and errors]].

== Checklist ==
# Obtain a bearer credential through [[SimTX API/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/Packets/Handshake|Handshake]] with role 2, authKind 1 and the ticket.
# Read a [[SimTX API/Packets/HandshakeResult|HandshakeResult]]; require status 0.
# Send <code>u8</code> 2 and a [[SimTX API/Packets/TransmitterSessionRequest|TransmitterSessionRequest]] with at least fields 1 to 13.
# Read [[SimTX API/Packets/TxQueue|TxQueue]] packets until [[SimTX API/Packets/TxAccept|TxAccept]], or stop at [[SimTX API/Packets/TxReject|TxReject]].
# Stream <code>u8</code> 3 [[SimTX API/Packets/SampleBlock|SampleBlock]] packets in real time. Read telemetry on another thread.
# Close the socket to go off air.

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

← Older revision		Revision as of 16:27, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{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/Permissions\|permission]].		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 ==		== Packets ==
Line 6:		Line 6:
	! Direction !! ID !! Packet !! When		! Direction !! ID !! Packet !! When
	\|-		\|-
	\| C2S \|\| 2 \|\| [[SimTX API/Packets/TransmitterSessionRequest\|TransmitterSessionRequest]] \|\| Once, right after the handshake.		\| C2S \|\| 2 \|\| [[SimTX API v24/Packets/TransmitterSessionRequest\|TransmitterSessionRequest]] \|\| Once, right after the handshake.
	\|-		\|-
	\| S2C \|\| 4 \|\| [[SimTX API/Packets/TxQueue\|TxQueue]] \|\| While waiting for a slot.		\| S2C \|\| 4 \|\| [[SimTX API v24/Packets/TxQueue\|TxQueue]] \|\| While waiting for a slot.
	\|-		\|-
	\| S2C \|\| 3 \|\| [[SimTX API/Packets/TxAccept\|TxAccept]] \|\| When the station goes on air.		\| S2C \|\| 3 \|\| [[SimTX API v24/Packets/TxAccept\|TxAccept]] \|\| When the station goes on air.
	\|-		\|-
	\| S2C \|\| 5 \|\| [[SimTX API/Packets/TxReject\|TxReject]] \|\| If the request is refused.		\| S2C \|\| 5 \|\| [[SimTX API v24/Packets/TxReject\|TxReject]] \|\| If the request is refused.
	\|-		\|-
	\| C2S \|\| 3 \|\| [[SimTX API/Packets/SampleBlock\|SampleBlock]] \|\| Continuously after TxAccept (role 2).		\| C2S \|\| 3 \|\| [[SimTX API v24/Packets/SampleBlock\|SampleBlock]] \|\| Continuously after TxAccept (role 2).
	\|-		\|-
	\| C2S \|\| 14 \|\| [[SimTX API/Packets/TxModeInfo\|TxModeInfo]] \|\| Optional, after TxAccept.		\| C2S \|\| 14 \|\| [[SimTX API v24/Packets/TxModeInfo\|TxModeInfo]] \|\| Optional, after TxAccept.
	\|-		\|-
	\| C2S \|\| 19 \|\| [[SimTX API/Packets/TxUpdate\|TxUpdate]] \|\| Optional, to change settings on air.		\| C2S \|\| 19 \|\| [[SimTX API v24/Packets/TxUpdate\|TxUpdate]] \|\| Optional, to change settings on air.
	\|-		\|-
	\| S2C \|\| 23 \|\| [[SimTX API/Packets/TxUpdateAck\|TxUpdateAck]] \|\| In reply to each TxUpdate.		\| S2C \|\| 23 \|\| [[SimTX API v24/Packets/TxUpdateAck\|TxUpdateAck]] \|\| In reply to each TxUpdate.
	\|-		\|-
	\| S2C \|\| 7 \|\| [[SimTX API/Packets/TxTelemetry\|TxTelemetry]] \|\| About every 50 ms while on air.		\| S2C \|\| 7 \|\| [[SimTX API v24/Packets/TxTelemetry\|TxTelemetry]] \|\| About every 50 ms while on air.
	\|-		\|-
	\| S2C \|\| 6 \|\| [[SimTX API/Packets/TxKick\|TxKick]] \|\| If the station is taken off air.		\| S2C \|\| 6 \|\| [[SimTX API v24/Packets/TxKick\|TxKick]] \|\| If the station is taken off air.
	\|}		\|}

Line 48:		Line 48:
	== Admission ==		== Admission ==
	After the request, the server answers with one of:		After the request, the server answers with one of:
	* '''[[SimTX API/Packets/TxAccept\|TxAccept]]''': the station is on air. Start streaming.		* '''[[SimTX API v24/Packets/TxAccept\|TxAccept]]''': the station is on air. Start streaming.
	* '''[[SimTX API/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/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/Packets/TxReject\|TxReject]]''': the request was refused. The reason is a human-readable string, and the connection closes.		* '''[[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/Packets/TransmitterSessionRequest\|TransmitterSessionRequest]]) closes the connection without a TxReject.		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 ==		== Sources ==
Line 73:		Line 73:

	== Streaming ==		== Streaming ==
	Samples are sent in [[SimTX API/Packets/SampleBlock\|SampleBlock]] packets of up to 65,536 values. IQ sources may use the compact 16-bit form, which halves the bandwidth.		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 ===		=== Pacing ===
Line 79:		Line 79:
	* 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.		* 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.		* 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/Packets/TxTelemetry\|TxTelemetry]] reports the server's buffer. It is the best pacing signal available: keep it above zero and below about two seconds.		* 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 ===		=== 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/Packets/TxUpdate\|TxUpdate]].		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.		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.
Line 89:		Line 89:

	== Live updates ==		== Live updates ==
	[[SimTX API/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/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.		[[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.		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 ==		== Telemetry ==
	While on air the server sends [[SimTX API/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.		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.		The client must keep reading. A client that stops reading for 5 seconds is disconnected.

	== Taken off air ==		== Taken off air ==
	The server can end a session with [[SimTX API/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/Connection and handshake#Accounts on the connection\|Accounts on the connection]].		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 ==		== 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/Packets/TxTelemetry\|TxTelemetry]] shows the actual power.		* 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/Limits and errors]].		* The number of simultaneous transmitters per account is limited. See [[SimTX API v24/Limits and errors]].

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

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