Editing Lua extension API

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