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]]

Lua extension API - Revision history

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