Lua audio add-on API

An audio add-on modifies mono audio before RF modulation. Several enabled add-ons form an ordered chain and run from top to bottom for every audio block.

Declaration[edit | edit source]

simtx.addon {
  name = "Limiter",
  description = "Limits audio peaks.",
  controls = {
    simtx.controls.slider("peak", {
      label = "Peak", min = 0.1, max = 1, step = 0.01, default = 0.9,
    }),
  },
  start = function(ctx)
    -- Optional per-session initialization.
  end,
  process = function(audio, ctx)
    audio:limit(ctx:control("peak"))
  end,
  stop = function(ctx)
    -- Optional per-session cleanup.
  end,
}

simtx.processor is an alias of simtx.addon. The name and process fields are required. description, controls, start, and stop are optional. Controls use the declarations in Lua extension API.

Each transmission receives isolated callback state. Add-ons may be used with mono audio sources and with Lua modulation modes that produce audio. They do not apply to direct GNU Radio IQ, PipeWire Stereo, white noise, or an IQ-producing Lua mode.

Audio block[edit | edit source]

Audio samples are normally in the range -1 to 1. Indices are zero-based, and values written by an add-on must be finite.

Method	Effect or result
`audio:size()`	Number of samples in the block.
`audio:sampleRate()`	Sample rate in hertz.
`audio:sessionTime()`	Time in seconds at the start of the block.
`audio:samplePosition()`	Absolute sample position at the start of the block.
`audio:get(index)`	Reads one sample.
`audio:set(index, value)`	Replaces one sample.
`audio:map(function(sample, index, time) ... end)`	Replaces every sample with the callback result.
`audio:gain(amount)`	Applies a constant linear gain.
`audio:limit(peak)`	Limits samples to the symmetric positive peak.
`audio:mixTone(frequencyHz, level)`	Adds a sine tone and reserves headroom.
`audio:mixTone(frequencyHz, level, reserveHeadroom)`	Adds a tone with optional headroom reservation.
`audio:fill(value)`	Replaces the block with a constant value.
`audio:peak()`	Absolute peak of the current block.
`audio:rms()`	Root mean square level of the current block.

The tone frequency must be at least zero and below half the sample rate. The peak supplied to limit must be positive.

Context[edit | edit source]

The second callback argument supplies stream information and live controls.

Method	Result
`ctx:blockSize()`	Number of samples in the block.
`ctx:sampleRate()`	Sample rate in hertz.
`ctx:sessionTime()`	Time in seconds at the start of the block.
`ctx:samplePosition()`	Absolute sample position at the start of the block.
`ctx:control(id)`	Current value of one control, or `nil`.
`ctx:controls()`	Snapshot table of all current control values.