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

2026-08-06T09:12:25Z

Add and update user documentation for Lua extensions and the catalog

New page

A modulation registration receives a context object named <code>ctx</code>. The same object is passed to the optional <code>start</code> and <code>stop</code> callbacks and to every <code>process</code> callback. Indices are zero-based.

== Lifecycle ==
<syntaxhighlight lang="lua">
simtx.modulation {
name = "Example",
start = function(ctx)
-- Prepare state for this transmission.
end,
process = function(ctx)
-- Produce one complete output block.
end,
stop = function(ctx)
-- Release script state if necessary.
end,
}
</syntaxhighlight>

Each transmission receives an isolated copy of the script state. Control values remain live and may change between blocks. Every output sample must be finite.

== Stream information ==
{| class="wikitable"
! Method !! Result
|-
| <code>ctx:n()</code> || Number of samples in the current block.
|-
| <code>ctx:blockSize()</code> || Alias of <code>n()</code>.
|-
| <code>ctx:rate()</code> || Stream sample rate in hertz.
|-
| <code>ctx:sampleRate()</code> || Alias of <code>rate()</code>.
|-
| <code>ctx:time()</code> || Time in seconds at the start of the block.
|-
| <code>ctx:sessionTime()</code> || Alias of <code>time()</code>.
|-
| <code>ctx:samplePosition()</code> || Absolute sample position at the start of the block.
|}

== Reading audio and writing output ==
{| class="wikitable"
! Method !! Effect
|-
| <code>ctx:audio(index)</code> || Returns an incoming mono audio sample, normally in the range -1 to 1.
|-
| <code>ctx:iq(index, i, q)</code> || Writes one complex output sample.
|-
| <code>ctx:map(function(audio, index, time) ... end)</code> || Maps every input audio sample. The callback returns I and optional Q.
|-
| <code>ctx:generate(function(index, time) ... end)</code> || Generates every sample without using audio. The callback returns I and optional Q.
|-
| <code>ctx:passthrough()</code> || Copies incoming mono audio to the output.
|-
| <code>ctx:gain(amount)</code> || Copies incoming audio to the output with a constant linear gain.
|-
| <code>ctx:limit(peak)</code> || Limits both output components to the symmetric positive peak.
|-
| <code>ctx:mixTone(frequencyHz, level)</code> || Mixes a sine tone with incoming audio and reserves headroom for it.
|-
| <code>ctx:mixTone(frequencyHz, level, reserveHeadroom)</code> || Mixes a sine tone and selects whether the input is reduced by the tone level.
|-
| <code>ctx:fill(value)</code> || Fills an audio block, or the I component of an IQ block, with a constant value.
|-
| <code>ctx:fill(i, q)</code> || Fills the block with a constant complex sample.
|-
| <code>ctx:silence()</code> || Fills the block with zeroes.
|}

<code>map</code> and <code>generate</code> callbacks receive absolute sample time, not merely time within the current block. This permits phase-continuous generators. Omitting the Q return value sets Q to zero.

<syntaxhighlight lang="lua">
process = function(ctx)
local gain = ctx:control("gain")
ctx:map(function(audio)
return audio * gain
end)
ctx:limit(1)
end
</syntaxhighlight>

Block operations such as <code>gain</code>, <code>mixTone</code>, and <code>fill</code> are preferable when they express the required operation because they avoid a Lua callback for every sample.

== Controls and inputs ==
{| class="wikitable"
! Method !! Result
|-
| <code>ctx:control(id)</code> || Current value of one control, or <code>nil</code> for an unknown ID.
|-
| <code>ctx:controls()</code> || Snapshot table containing all current control values.
|-
| <code>ctx:input(id)</code> || Decoded image, video, or file input, or <code>nil</code>.
|-
| <code>ctx:inputs()</code> || Snapshot table containing all supplied non-audio inputs.
|-
| <code>ctx:hasInput(id)</code> || Whether a non-audio input was supplied.
|-
| <code>ctx:finish()</code> || Requests a clean end after the current block.
|}

Audio is accessed through <code>audio</code>, <code>map</code>, and the block operations rather than through <code>input</code>.

== Image objects ==
Image coordinates are zero-based. Channel and luminance values are normalized from 0 to 1.

{| class="wikitable"
! Method !! Result
|-
| <code>image:name()</code> || Original filename.
|-
| <code>image:width()</code>, <code>image:height()</code> || Dimensions in pixels.
|-
| <code>image:red(x,y)</code>, <code>green</code>, <code>blue</code>, <code>alpha</code> || One normalized channel.
|-
| <code>image:luma(x,y)</code> || Rec. 709 luminance.
|-
| <code>image:pixel(x,y)</code> || Table with <code>r</code>, <code>g</code>, <code>b</code>, <code>a</code>, and <code>luma</code> fields.
|-
| <code>image:argb(x,y)</code> || Packed ARGB integer.
|-
| <code>image:resize(width,height)</code> || High-quality resized image object.
|}

An image side may contain at most 8,192 pixels, and an image may contain at most 16,777,216 pixels.

== Video objects ==
Video frame indices are zero-based.

{| class="wikitable"
! Method !! Result
|-
| <code>video:name()</code> || Original filename.
|-
| <code>video:width()</code>, <code>video:height()</code> || Frame dimensions.
|-
| <code>video:frames()</code> || Number of frames.
|-
| <code>video:duration()</code> || Duration in seconds.
|-
| <code>video:frameRate()</code> || Average frames per second.
|-
| <code>video:frame(index)</code> || Decoded frame as an image object.
|-
| <code>video:frameAt(seconds)</code> || Frame at the requested time as an image object. Times outside the duration are clamped.
|}

Video decoding supports MP4 and MOV-family files accepted by the picker. A script should normally obtain one frame per logical video frame and reuse it while producing the corresponding samples.

== File objects ==
{| class="wikitable"
! Method !! Result
|-
| <code>file:name()</code> || Original filename.
|-
| <code>file:size()</code> || Size in bytes.
|-
| <code>file:byteAt(index)</code> || Unsigned byte from 0 to 255 at a zero-based index.
|-
| <code>file:text()</code> || Entire payload decoded as UTF-8 text.
|}

A generic file input may contain at most 64 MiB.

[[Category:Lua extensions]]

Lua modulation API - Revision history

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