Editing 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 ==
<syntaxhighlight lang="lua">
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,
}
</syntaxhighlight>

<code>simtx.processor</code> is an alias of <code>simtx.addon</code>. The <code>name</code> and <code>process</code> fields are required. <code>description</code>, <code>controls</code>, <code>start</code>, and <code>stop</code> 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.

{| class="wikitable"
! Method !! Effect or result
|-
| <code>audio:size()</code> || Number of samples in the block.
|-
| <code>audio:sampleRate()</code> || Sample rate in hertz.
|-
| <code>audio:sessionTime()</code> || Time in seconds at the start of the block.
|-
| <code>audio:samplePosition()</code> || Absolute sample position at the start of the block.
|-
| <code>audio:get(index)</code> || Reads one sample.
|-
| <code>audio:set(index, value)</code> || Replaces one sample.
|-
| <code>audio:map(function(sample, index, time) ... end)</code> || Replaces every sample with the callback result.
|-
| <code>audio:gain(amount)</code> || Applies a constant linear gain.
|-
| <code>audio:limit(peak)</code> || Limits samples to the symmetric positive peak.
|-
| <code>audio:mixTone(frequencyHz, level)</code> || Adds a sine tone and reserves headroom.
|-
| <code>audio:mixTone(frequencyHz, level, reserveHeadroom)</code> || Adds a tone with optional headroom reservation.
|-
| <code>audio:fill(value)</code> || Replaces the block with a constant value.
|-
| <code>audio:peak()</code> || Absolute peak of the current block.
|-
| <code>audio:rms()</code> || 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 <code>limit</code> must be positive.

== Context ==
The second callback argument supplies stream information and live controls.

{| class="wikitable"
! Method !! Result
|-
| <code>ctx:blockSize()</code> || Number of samples in the block.
|-
| <code>ctx:sampleRate()</code> || Sample rate in hertz.
|-
| <code>ctx:sessionTime()</code> || Time in seconds at the start of the block.
|-
| <code>ctx:samplePosition()</code> || Absolute sample position at the start of the block.
|-
| <code>ctx:control(id)</code> || Current value of one control, or <code>nil</code>.
|-
| <code>ctx:controls()</code> || Snapshot table of all current control values.
|}

[[Category:Lua extensions]]