Editing Lua modulation API

{{Documentation navigation}}

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.


== How to use this reference ==
Use this page after declaring a mode with [[Lua extension API#Modulation declaration|simtx.modulation]]. A callback receives one block at a time. Read its required output size from ctx:n(), fill every sample, and keep values finite. The lifecycle snippets below illustrate callbacks; they are not complete working signal generators. Keep default input resampling unless the extension deliberately implements its own conversion.

== 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 mw-collapsible mw-collapsed"
! Method !! Result
|-
| <code>ctx:n()</code> || Number of output samples required in the current block.
|-
| <code>ctx:blockSize()</code> || Alias of <code>n()</code>.
|-
| <code>ctx:rate()</code> || Output and Lua processing sample rate in hertz.
|-
| <code>ctx:sampleRate()</code> || Alias of <code>rate()</code>.
|-
| <code>ctx:audioN()</code> || Number of input audio samples available in the current block.
|-
| <code>ctx:audioBlockSize()</code> || Alias of <code>audioN()</code>.
|-
| <code>ctx:audioSampleRate()</code> || Input audio sample rate in hertz.
|-
| <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 mw-collapsible mw-collapsed"
! Method !! Effect
|-
| <code>ctx:audio(index)</code> || Returns an input mono audio sample at a zero-based input index, 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.

=== Native-rate audio ===
Input audio is resampled to the Lua processing rate by default. In this mode, <code>ctx:audioN()</code> matches <code>ctx:n()</code>, <code>ctx:audioSampleRate()</code> matches <code>ctx:sampleRate()</code>, and the one-to-one helpers can be used normally.

A modulation may set <code>resample_audio = false</code> to receive audio at the source's native rate:

<syntaxhighlight lang="lua">
simtx.modulation {
    name = "Custom resampler",
    sample_rate = 240000,
    resample_audio = false,
    process = function(ctx)
        local outputCount = ctx:n()
        local outputRate = ctx:sampleRate()
        local inputCount = ctx:audioN()
        local inputRate = ctx:audioSampleRate()

        -- Read native input with ctx:audio(index).
        -- Produce outputCount samples with ctx:iq() or ctx:generate().
        -- Keep filter and FIFO state in Lua across calls.
    end,
}
</syntaxhighlight>

The input and output blocks cover the same elapsed duration, subject to sample-count rounding. Their sample counts can differ. During extreme downsampling, an output block can occasionally contain zero samples.

When the input and output rates or block sizes differ, <code>ctx:map()</code>, <code>ctx:passthrough()</code>, <code>ctx:gain()</code>, and <code>ctx:mixTone()</code> raise an error because they require one input sample per output sample. Use <code>ctx:audio()</code> to read the native block and write the resampled result with <code>ctx:iq()</code> or <code>ctx:generate()</code>. The extension is responsible for its resampling filter, FIFO, and state.

The registration fields are documented in [[Lua extension API#Modulation declaration|Lua extension API]].

== Controls and inputs ==
{| class="wikitable mw-collapsible mw-collapsed"
! 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 mw-collapsible mw-collapsed"
! 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 mw-collapsible mw-collapsed"
! 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 mw-collapsible mw-collapsed"
! 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]]