Creating Lua extensions

A SimTX Lua extension is a folder containing an extension.properties manifest and one or more Lua files. The graphical creator is the usual starting point because it produces a valid manifest and an editable example.

Start with one small audio add-on

You need a working transmitter installation and basic Lua knowledge. If you only want to install a feature, use Lua extensions instead.

An extension has two essential parts: extension.properties describes the package, and init.lua registers the feature. The complete gain example below can be used as a first package.

After creating it, reload, confirm there is no Problems entry, and enable Gain in Add-ons. Use a short audio file and a low gain setting for the first test. Increasing the control should increase the input level; the limiter caps the samples. Disable the add-on to compare.

Create the package, select it to edit, then reload and check Problems.

Read the manifest reference when changing package fields and the audio add-on API when adding processing. The minimal example remains small enough to inspect in full.

Creating a package

1. Open Extensions in the transmitter footer.
2. Select Create extension.
3. Enter a stable package ID, display name, semantic version, API version, entry file, types, and description.
4. Add dependencies or exported modules when the package uses them.
5. Select Create.
6. Select the package in the Installed tab and use Edit package, or open the user folder in an external text editor.
7. Select Reload now after saving changes. Loading errors appear in the Problems tab.

The stable package ID cannot be changed in the built-in editor after creation. A new package should therefore use an identifier controlled by its author, such as net.example.voice-tools.

Minimal audio add-on

The following package supplies one gain control and processes the selected audio source.

extension.properties:

id=net.example.gain
name=Gain Example
version=1.0.0
api=1
entry=init.lua
types=audio-addon
description=Applies adjustable gain to mono audio.

init.lua:

simtx.require_api(1)

simtx.addon {
  name = "Gain",
  description = "Applies adjustable gain to mono audio.",
  controls = {
    simtx.controls.slider("gain", {
      label = "Gain", unit = "x",
      min = 0, max = 2, step = 0.01, default = 1,
    }),
  },
  process = function(audio, ctx)
    audio:gain(ctx:control("gain"))
    audio:limit(1)
  end,
}

Package layout

Only the file named by entry is run as the package entry point. Other Lua files are modules and are loaded with require.

gain-package/
  extension.properties
  init.lua
  filters.lua
  codec/
    tone.lua

Within the same package, require("filters") loads filters.lua, and require("codec.tone") loads codec/tone.lua. A module should return its public value. A module that returns no value is treated as returning true.

Development cycle

The entry file registers features when the package is loaded. Each running modulation or audio add-on session receives an isolated copy of the script state. Values declared as controls remain live, so an operator may adjust them during transmission.

A practical development cycle is:

1. Begin with one of the supplied examples or the generated template.
2. Keep the manifest types list consistent with the registrations in the entry file.
3. Reload the package and inspect the Problems tab.
4. Test controls and required inputs before transmitting.
5. Use Catalog > Preview Selected to review the exact shared files before or after publication.

Publishing

The package can be shared with Catalog > Share Extension Folder.... Publishing requires the signed-in SimTX account to have catalog publication permission. Extension catalog describes publication, categories, revisions, and updates.

Further reference

• Lua extension manifest lists every manifest field and version range.
• Lua extension API lists registration tables, controls, inputs, helper functions, and aliases.
• Lua modulation API, Lua audio add-on API, Lua action API, and Lua theme API describe each extension type.