Editing Lua modulation API (section)

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