Editing Lua extension API (section)

== Modulation declaration ==
{| class="wikitable mw-collapsible mw-collapsed"
! Field !! Default !! Meaning
|-
| <code>name</code> || Required || Display name.
|-
| <code>description</code> || Empty || User-facing description.
|-
| <code>bandwidth</code> || 3000 for IQ, usual width for audio output || Intended occupied RF bandwidth in hertz and the suggested initial value shown to the operator. For IQ output, it also sets the minimum processing and output sample rate.
|-
| <code>sample_rate</code> || Automatic || Requests the Lua processing and output sample rate in hertz. It is supported by both IQ-output and audio-output modes.
|-
| <code>resample_audio</code> || <code>true</code> || When <code>true</code>, SimTX resamples input audio to the processing rate before calling Lua. When <code>false</code>, Lua receives native-rate input audio and must perform any required resampling.
|-
| <code>controls</code> || Empty || List of controls described below.
|-
| <code>input</code> || <code>"audio"</code> || Shorthand for one input. <code>"none"</code> and <code>"generator"</code> declare a source-free mode.
|-
| <code>inputs</code> || One required audio input || List of declared inputs. It cannot be combined with <code>input</code>.
|-
| <code>output</code> || <code>"iq"</code> || <code>"iq"</code>, <code>"audio"</code>, or <code>{type="audio", modulation="USB"}</code>.
|-
| <code>start</code> || None || Optional <code>function(ctx)</code> called once when a session starts.
|-
| <code>process</code> || Required || <code>function(ctx)</code> called for each output block. <code>modulate</code> is an alias.
|-
| <code>stop</code> || None || Optional <code>function(ctx)</code> called once when the session closes.
|}

<code>bandwidth</code> and <code>sample_rate</code> describe different things. Bandwidth describes the intended RF spectrum, while sample rate describes the Lua processing clock. For IQ output, the effective sample rate is at least the selected bandwidth. Requested rates are capped at 10,000,000 samples per second.

For example, a broadcast FM extension that also generates RDS can request a wider processing clock while keeping the occupied bandwidth explicit:

<syntaxhighlight lang="lua">
simtx.modulation {
    name = "FM with RDS",
    bandwidth = 192000,
    sample_rate = 240000,
    resample_audio = true,
    process = function(ctx)
        -- Generate the composite signal here.
    end,
}
</syntaxhighlight>

An IQ-output mode produces complex baseband directly. An audio-output mode produces mono audio and then uses a built-in RF modulation selected by the operator. The default built-in modulation is USB. Any built-in mode other than IQ may be used.

Set <code>resample_audio = false</code> only when the extension needs the source samples at their native rate and will handle rate conversion, buffering, and filtering itself. The relevant native-input methods and block rules are documented in [[Lua modulation API#Native-rate audio|Lua modulation API]].

The callback object is documented in [[Lua modulation API]].