Lua extensions

Home · Start here · All guides · Solve a problem · Radio terms · Developer API

A Lua extension adds user-defined features to the SimTX Transmitter. An extension may provide modulation modes, audio add-ons, tools, themes, reusable libraries, or several of these features in one package. Extensions are stored as folders and can be created, edited, and reloaded without restarting the application.

Install and use an extension without programming

An extension is an optional feature package. You do not need to understand Lua to use one.

Connect to a server and open Catalog in the footer.
Find a package for the feature you want and choose Preview Selected to inspect it.
Choose Install Selected, review any dependencies and files, then select Install.
Open Extensions and check that the package appears under Installed. If it does not load, read Problems.
Use the feature in the appropriate place: Modulation for signal modes, Add-ons for audio processing, Theme for appearance, or Extensions > Tools for actions.

Extensions window with Installed, Tools, and Problems tabs and package management buttons. — Installed packages and the features they provide. The Problems tab is the first place to check a loading error.

To try a theme, choose one from Theme and return to System to restore the default appearance.

Enable an audio processor

Select a supported mono audio source, such as an audio file or microphone.
Open Add-ons and tick the processor's Enabled checkbox.
Select its row and choose Configure to adjust its controls.
Use Move up or Move down to change processing order. Listen to the result with a short transmission.

Audio add-ons window showing Enabled checkboxes, Configure, Move up, Move down, and Disable all. — Enabled processors run from top to bottom. Installing an add-on and enabling it are separate steps.

Direct IQ, white noise, and PipeWire Stereo do not pass through this mono-audio add-on chain. Details are in Lua audio add-on API.

To write your own package, continue to Creating Lua extensions. The type and environment reference below is available when needed.

Extension types

Type	Purpose	Where it appears
Modulation	Produces complex IQ or mono audio for a transmission. A mode may use ordinary audio, generate a signal, or consume an image, video, or data file.	Modulation list in the RF Signal section
Audio add-on	Processes mono audio before RF modulation. Examples include gain control, filtering, CTCSS, and identification tones.	Add-ons button in the footer
Tool or action	Reads or changes documented transmitter settings and may start or stop transmissions.	Extensions > Tools
Theme	Changes the application colors and fonts.	Theme list in the footer
Library	Provides Lua modules to other installed extension packages.	Used by declared dependent packages

One package may register several items and may combine several types.

Managing installed extensions

The Extensions button opens three tabs:

Installed lists each package, its version, and the items it provides.
Tools lists user-invoked actions and provides a button for running the selected action.
Problems lists packages that could not be loaded and gives the reason.

The same window provides Create extension, Edit package, Open user folder, and Reload now. Changes made in the built-in editor or in the extension folder take effect after reloading. The application also detects ordinary file changes and reloads extensions automatically.

The first creation of the extension folder includes editable example packages. These demonstrate modulation, generated CW, image input, audio add-ons, actions, themes, multi-type packages, libraries, and dependencies.

Using extension features

Extension modulation modes are selected in the normal Modulation list. Their controls and required media pickers appear below the standard transmission fields. Audio-output modes also provide an RF modulation selector. IQ-output modes bypass the built-in modulator.

Audio add-ons are enabled and ordered through the Add-ons window. Enabled add-ons run from top to bottom. Their order, enabled state, and control values are retained between application runs. Add-ons require a mono audio source or an audio-producing Lua modulation.

Themes are selected from the Theme list. Tools are run from the Tools tab of the Extensions window.

Obtaining extensions

The Extension catalog is the normal way to preview and install shared packages. Installed extensions are ready to use immediately. Required library packages can be installed as part of the same operation.

Creating extensions

Creating Lua extensions describes the package structure and a minimal example. The public interface is divided among these references:

Execution environment

Extensions run in a restricted Lua environment intended for computation. Standard Lua base, table, string, coroutine, bit32, and mathematical facilities are available. Direct file access, operating-system commands, network access, Java access, the debug library, dofile, and loadfile are not available. Files selected through declared inputs are exposed as read-only objects described in Lua modulation API.

Extension callbacks have execution limits. Signal processing should use the block operations supplied by the API where possible. An extension that exceeds a limit, returns an invalid value, or raises an error is stopped with a diagnostic.