Lua extension API - Revision history

Clanker: Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

2026-09-13T21:22:03Z

Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

← Older revision		Revision as of 21:22, 13 September 2026
Line 1:		Line 1:
			{{Documentation navigation}}

	The '''SimTX Lua extension API''' is the public interface available to extension entry files and modules. API version 1 provides registration functions, declarative controls and inputs, digital signal processing helpers, and type-specific callback objects.		The '''SimTX Lua extension API''' is the public interface available to extension entry files and modules. API version 1 provides registration functions, declarative controls and inputs, digital signal processing helpers, and type-specific callback objects.


			== How to use this reference ==
			This is a developer reference, not an installation guide. Start with [[Creating Lua extensions]] for a complete package. Use the registration table to choose a feature type, Controls to add widgets, and Inputs to request media. Then follow the link to the callback API for that type.

	== Version check ==		== Version check ==
Line 9:		Line 15:

	== Registration functions ==		== Registration functions ==
	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Function !! Purpose !! Alias		! Function !! Purpose !! Alias
	\|-		\|-
Line 24:		Line 30:

	== Modulation declaration ==		== Modulation declaration ==
	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Field !! Default !! Meaning		! Field !! Default !! Meaning
	\|-		\|-
Line 99:		Line 105:
	The equivalent long form is a table with an <code>id</code> and <code>type</code>. The slider aliases are <code>range</code> and <code>number</code>. Checkbox aliases are <code>check</code>, <code>bool</code>, <code>boolean</code>, and <code>toggle</code>. <code>string</code> is a text alias. Choice aliases are <code>select</code>, <code>dropdown</code>, and <code>combo</code>.		The equivalent long form is a table with an <code>id</code> and <code>type</code>. The slider aliases are <code>range</code> and <code>number</code>. Checkbox aliases are <code>check</code>, <code>bool</code>, <code>boolean</code>, and <code>toggle</code>. <code>string</code> is a text alias. Choice aliases are <code>select</code>, <code>dropdown</code>, and <code>combo</code>.

	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Control !! Fields and defaults !! Lua value		! Control !! Fields and defaults !! Lua value
	\|-		\|-
Line 133:		Line 139:

	== DSP helpers ==		== DSP helpers ==
	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Function !! Result		! Function !! Result
	\|-		\|-

Clanker: Document sample_rate and optional extension-owned audio resampling

2026-08-14T13:48:19Z

Document sample_rate and optional extension-owned audio resampling

@@ Line 31: / Line 31: @@
 | <code>description</code> || Empty || User-facing description.
 |-
-| <code>bandwidth</code> || 3000 for IQ, usual width for audio output || Suggested initial transmit bandwidth in hertz. The operator may change it.
+| <code>bandwidth</code> || 3000 for IQ, usual width for audio output || Intended occupied RF bandwidth in hertz and the suggested initial value shown to the operator. For IQ output, it also sets the minimum processing and output sample rate.
 |-
 | <code>controls</code> || Empty || List of controls described below.
@@ Line 47: / Line 51: @@
 | <code>stop</code> || None || Optional <code>function(ctx)</code> called once when the session closes.
 |}
 An IQ-output mode produces complex baseband directly. An audio-output mode produces mono audio and then uses a built-in RF modulation selected by the operator. The default built-in modulation is USB. Any built-in mode other than IQ may be used.
 The callback object is documented in [[Lua modulation API]].

Clanker: Add and update user documentation for Lua extensions and the catalog

2026-08-06T09:12:24Z

Add and update user documentation for Lua extensions and the catalog

New page

The '''SimTX Lua extension API''' is the public interface available to extension entry files and modules. API version 1 provides registration functions, declarative controls and inputs, digital signal processing helpers, and type-specific callback objects.

== Version check ==
<syntaxhighlight lang="lua">
simtx.require_api(1)
</syntaxhighlight>

<code>simtx.api_version</code> contains the available API version. <code>simtx.require_api(version)</code> returns <code>true</code> when the requested positive version is available and raises an error otherwise.

== Registration functions ==
{| class="wikitable"
! Function !! Purpose !! Alias
|-
| <code>simtx.modulation{...}</code> || Registers a modulation or media mode. || <code>simtx.register{...}</code>
|-
| <code>simtx.addon{...}</code> || Registers an audio add-on. || <code>simtx.processor{...}</code>
|-
| <code>simtx.action{...}</code> || Registers a user-invoked tool. || <code>simtx.tool{...}</code>
|-
| <code>simtx.theme{...}</code> || Registers an application theme. || None
|}

Names must be 1 to 64 printable characters and must be unique within their type in one package. A package may call a registration function more than once.

== Modulation declaration ==
{| class="wikitable"
! Field !! Default !! Meaning
|-
| <code>name</code> || Required || Display name.
|-
| <code>description</code> || Empty || User-facing description.
|-
| <code>bandwidth</code> || 3000 for IQ, usual width for audio output || Suggested initial transmit bandwidth in hertz. The operator may change it.
|-
| <code>controls</code> || Empty || List of controls described below.
|-
| <code>input</code> || <code>"audio"</code> || Shorthand for one input. <code>"none"</code> and <code>"generator"</code> declare a source-free mode.
|-
| <code>inputs</code> || One required audio input || List of declared inputs. It cannot be combined with <code>input</code>.
|-
| <code>output</code> || <code>"iq"</code> || <code>"iq"</code>, <code>"audio"</code>, or <code>{type="audio", modulation="USB"}</code>.
|-
| <code>start</code> || None || Optional <code>function(ctx)</code> called once when a session starts.
|-
| <code>process</code> || Required || <code>function(ctx)</code> called for each output block. <code>modulate</code> is an alias.
|-
| <code>stop</code> || None || Optional <code>function(ctx)</code> called once when the session closes.
|}

An IQ-output mode produces complex baseband directly. An audio-output mode produces mono audio and then uses a built-in RF modulation selected by the operator. The default built-in modulation is USB. Any built-in mode other than IQ may be used.

The callback object is documented in [[Lua modulation API]].

== Controls ==
Controls create ordinary transmitter widgets and provide live values to callbacks. An ID must start with a letter or underscore, contain only letters, digits, and underscores, and contain at most 64 characters. Control and input IDs in one modulation must be unique.

The helper form is recommended:
<syntaxhighlight lang="lua">
controls = {
simtx.controls.slider("gain", {
label = "Gain", help = "Linear input gain.", unit = "x",
precision = 2, min = 0, max = 2, step = 0.01, default = 1,
}),
simtx.controls.toggle("enabled", {label = "Enabled", default = true}),
simtx.controls.text("message", {label = "Message", default = "CQ"}),
simtx.controls.choice("shape", {
label = "Shape",
options = {
"soft",
{value = "hard", label = "Hard edges"},
},
default = "soft",
}),
}
</syntaxhighlight>

The equivalent long form is a table with an <code>id</code> and <code>type</code>. The slider aliases are <code>range</code> and <code>number</code>. Checkbox aliases are <code>check</code>, <code>bool</code>, <code>boolean</code>, and <code>toggle</code>. <code>string</code> is a text alias. Choice aliases are <code>select</code>, <code>dropdown</code>, and <code>combo</code>.

{| class="wikitable"
! Control !! Fields and defaults !! Lua value
|-
| Slider || <code>min=0</code>, <code>max=1</code>, <code>step=0</code>, <code>default=min</code>, optional <code>unit</code> and <code>precision</code> || Number
|-
| Checkbox || <code>default=false</code> || Boolean
|-
| Text || <code>default=""</code> || String
|-
| Choice || Non-empty <code>options</code>; <code>default</code> is the first option || String value
|}

All controls accept <code>label</code>, <code>help</code>, and <code>default</code>. A label defaults to the ID. Help text may contain at most 300 characters. Slider units may contain at most 16 characters. Slider precision may be 0 to 8, or may be omitted so the interface derives it from the step. Slider values and bounds must be finite, <code>max</code> must exceed <code>min</code>, and the default must be within the range.

== Inputs ==
Inputs ask the operator for data needed by a modulation. Audio uses the normal '''Transmission Source''' section. Other types create file pickers below the modulation controls.

<syntaxhighlight lang="lua">
inputs = {
simtx.inputs.audio("audio", {label = "Programme audio"}),
simtx.inputs.image("picture", {
label = "Picture", required = true,
accept = {"png", "jpg", "jpeg"},
}),
simtx.inputs.video("clip", {required = false}),
simtx.inputs.file("data", {extensions = {"txt", "bin"}}),
}
</syntaxhighlight>

Each input accepts <code>id</code>, <code>type</code>, <code>label</code>, <code>help</code>, <code>required</code>, and a filename-extension list named either <code>accept</code> or <code>extensions</code>. <code>required</code> defaults to <code>true</code>. Canonical types are <code>audio</code>, <code>image</code>, <code>video</code>, and <code>file</code>. Audio aliases are <code>sound</code> and <code>microphone</code>. Image aliases are <code>picture</code> and <code>photo</code>. <code>movie</code> is a video alias. File aliases are <code>bytes</code>, <code>data</code>, and <code>binary</code>. The default file filters are WAV, MP3, AIFF, AIF, and AU for audio; PNG, JPEG, GIF, and BMP for images; and MP4, MOV, and M4V for video. A generic file input has no default filter.

The objects supplied for image, video, and file inputs are documented in [[Lua modulation API]].

== DSP helpers ==
{| class="wikitable"
! Function !! Result
|-
| <code>simtx.dsp.db(decibels)</code> || Converts a voltage or amplitude ratio in decibels to a linear value using 10<sup>dB/20</sup>.
|-
| <code>simtx.dsp.to_db(linear)</code> || Converts an absolute linear amplitude to decibels. Zero returns negative infinity.
|-
| <code>simtx.dsp.clamp(value, minimum, maximum)</code> || Restricts a value to the inclusive range. The maximum must not be below the minimum.
|-
| <code>simtx.dsp.lerp(from, to, amount)</code> || Returns <code>from + (to - from) * amount</code>.
|}

== Standard Lua facilities ==
The computation-oriented base, string, table, math, bit32, and coroutine functions are available. Package modules use the restricted <code>require</code> described in [[Lua extension manifest]]. File, network, operating-system, Java, package-loader, and debug access are not available.

[[Category:Lua extensions]]