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

simtx.require_api(1)

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

Registration functions

Function	Purpose	Alias
simtx.modulation{...}	Registers a modulation or media mode.	simtx.register{...}
simtx.addon{...}	Registers an audio add-on.	simtx.processor{...}
simtx.action{...}	Registers a user-invoked tool.	simtx.tool{...}
simtx.theme{...}	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

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

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",
  }),
}

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

Control	Fields and defaults	Lua value
Slider	min=0, max=1, step=0, default=min, optional unit and precision	Number
Checkbox	default=false	Boolean
Text	default=""	String
Choice	Non-empty options; default is the first option	String value

All controls accept label, help, and default. 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, max must exceed min, 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.

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"}}),
}

Each input accepts id, type, label, help, required, and a filename-extension list named either accept or extensions. required defaults to true. Canonical types are audio, image, video, and file. Audio aliases are sound and microphone. Image aliases are picture and photo. movie is a video alias. File aliases are bytes, data, and binary. 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

Function	Result
simtx.dsp.db(decibels)	Converts a voltage or amplitude ratio in decibels to a linear value using 10dB/20.
simtx.dsp.to_db(linear)	Converts an absolute linear amplitude to decibels. Zero returns negative infinity.
simtx.dsp.clamp(value, minimum, maximum)	Restricts a value to the inclusive range. The maximum must not be below the minimum.
simtx.dsp.lerp(from, to, amount)	Returns from + (to - from) * amount.

Standard Lua facilities

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