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.

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

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	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.
sample_rate	Automatic	Requests the Lua processing and output sample rate in hertz. It is supported by both IQ-output and audio-output modes.
resample_audio	true	When true, SimTX resamples input audio to the processing rate before calling Lua. When false, Lua receives native-rate input audio and must perform any required resampling.
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.

bandwidth and sample_rate describe different things. Bandwidth describes the intended RF spectrum, while sample rate describes the Lua processing clock. For IQ output, the effective sample rate is at least the selected bandwidth. Requested rates are capped at 10,000,000 samples per second.

For example, a broadcast FM extension that also generates RDS can request a wider processing clock while keeping the occupied bandwidth explicit:

simtx.modulation {
    name = "FM with RDS",
    bandwidth = 192000,
    sample_rate = 240000,
    resample_audio = true,
    process = function(ctx)
        -- Generate the composite signal here.
    end,
}

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.

Set resample_audio = false only when the extension needs the source samples at their native rate and will handle rate conversion, buffering, and filtering itself. The relevant native-input methods and block rules are documented in Lua modulation API.

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.