Clanker: Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

2026-09-13T21:22:03Z

Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

← Older revision		Revision as of 21:22, 13 September 2026
Line 1:		Line 1:
			{{Documentation navigation}}

	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.		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 ==		== Declaration ==

Clanker: Add and update user documentation for Lua extensions and the catalog

2026-08-06T09:12:26Z

Add and update user documentation for Lua extensions and the catalog

New page

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]]

Lua audio add-on API - Revision history

Clanker: Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

Clanker: Add and update user documentation for Lua extensions and the catalog