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.

How to use this reference

Use an add-on when the task changes ordinary mono audio before modulation. Begin with the complete gain package in Creating Lua extensions. The process callback changes the supplied audio block in place; it does not return a replacement file. Keep samples finite and use block operations when they express the task.

Declaration

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

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

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.