Parameters & Control

1. Three kinds of argument

Almost every Phausto setter is declared as taking aNumberOrABoxOrASymbol, and that signature is the single most important thing on this page. The kind of argument you pass decides whether the value is frozen, modulated, or exposed as a control.

osc := SineOsc new freq: 440.

"Vibrato: ±20 Hz at 6 Hz around a 440 Hz centre"
osc := SineOsc new freq: (LFOTri new freq: 6) * 20 asBox + 440 asBox.

osc := SineOsc new freq: #myFreq.

2. How parameters get their names

A parameter's name is its UGen's label followed by the parameter's own label. A PulseOsc whose label is the default class name therefore contributes PulseOscFreq and PulseOscDuty.

Relabel the UGen and every one of its parameters is renamed with it:

"Two oscillators that would otherwise share parameter names"
left  := SineOsc new label: 'Left'.
right := SineOsc new label: 'Right'.

"now LeftFreq and RightFreq, individually addressable"
dsp setValue: 440 parameter: 'LeftFreq'.
dsp setValue: 443 parameter: 'RightFreq'.

The same technique makes an arbitrary instrument work with playNote:prefix:dur:, which looks for a frequency and a gate under a prefix you choose:

synth := ElecGuitar new
  freq:    #ElecGuitarFreq;
  trigger: #ElecGuitarTrigger.

3. Discovering what exists

You should almost never guess a parameter name. After init, the DSP can list everything it exposes:

dsp traceAllParams.
dsp getParamValue: 'PulseOscDuty'.
(dsp includesParameter: 'PulseOscFreq') ifTrue: [ "safe to set" ].

4. Setting values

dsp setValue: 0.2 parameter: 'PulseOscDuty'.
dsp setValue: 120 parameter: 'PulseOscFreq'.

Values are in the parameter's own units — hertz, seconds, decibels, or a normalised 0–1 range, depending on the control. Out-of-range values are clamped to the declared minimum and maximum rather than raising.

The index form, setValue:parameterIndex:, avoids the name lookup and is marginally faster; it is worth using inside a tight control loop, but the name form is clearer everywhere else.

5. Triggering

Envelopes, drums and plucked models do nothing until gated. A button parameter is a signal that is 1 while pressed and 0 otherwise, and trig: presses it from code.

"Strike a drum"
dsp trig: 'DjembeTrigger'.

"Hold a note for a quarter of a second"
dsp trig: 'ADSREnvGate' for: 0.25.

"Play middle C for a quarter of a second"
dsp playNote: 60 prefix: 'ElecGuitar' dur: 0.25.

The difference between trig: and trig:for: matters for sustaining instruments. A percussion model only needs an instant; an ADSR held open by trig: alone will sit in its sustain stage indefinitely.

6. Sweeps and ramps

A parameter can be moved gradually rather than jumped, which is the difference between a filter that clicks and one that sweeps:

"Open the filter over two seconds"
dsp sweepToValue: 8000 parameter: 'MoogVcfFreq' in: 2.

sweepToMfValue:parameter:in: is the variant for parameters expressed as multiplication factors rather than absolute values.

7. Setting many at once

Phausto extends Array so a collection of values can be applied to a DSP in one message — convenient when recalling a preset or stepping a sequence:

For structured state — saving, recalling and interpolating whole parameter sets — Phausto has DSPParameter and DSPParameterStore, described in DSP & Parameter API.

8. Individual widgets

displayUI opens everything at once. When you want one control on screen — during a performance, or to keep a specific knob to hand — open it alone:

s1 := dsp sliderFor: 'tempo'.  s1 openInWindow.
s2 := dsp sliderFor: 'freq'.   s2 openInWindow.

Nested FAUST groups produce path-like names, so a parameter inside a demo module may be addressed as something like 'Freeverb/0x00/RoomSize'. Copy the exact string from traceAllParams.