Phausto's fluid API does not live on the UGen classes. It lives in twenty-two traits composed
across the hierarchy — which is why browsing a class tells you almost nothing about how to use
it.
1. Why the classes look empty
Open SineOsc in the System Browser and you will find one method:
initialize. Yet this works:
osc := SineOsc new freq: 200; uLevel: 0.5.
freq: arrives from the PhFrequencySetter trait, composed into the
oscillator hierarchy. The same pattern holds throughout: period: comes from
PhPeriodSetter, trigger: from PhTriggerSetter,
cutoff: from PhFilterSetter. A large catch-all,
PhParamsSetter, supplies thirty-five more.
The benefit is consistency — freq: means the same thing on an oscillator, a
filter and a physical model. The cost is discoverability, and this page exists to pay it
back.
1.1 Every setter takes three kinds of argument
Almost every selector below is declared as taking
aNumberOrABoxOrASymbol. That signature is a promise:
Argument
Effect
A number
Compiled in as a constant; cannot be changed at runtime
A UGen or box
Modulation — the value comes from the signal graph
The authoritative answer for any given UGen is always the same three lines:
dsp := SomeUGen new asDsp.
dsp init.
dsp traceAllParams.
This lists the parameters that UGen actually exposes, under the names the DSP knows them
by. The tables below tell you what to send; traceAllParams tells you
what came out.
2. Pitch and time
trait PhFrequencySetter
Selector
Sets
freq:
Frequency in hertz
frequency:
Synonym of freq:
pitch:
Pitch, where the module expresses it as such
reset:
Reset the oscillator phase
trait PhPeriodSetter
Selector
Sets
period:
Repetition interval in seconds — the inverse of frequency
trait PhTempoSetter
Selector
Sets
tempo:
Tempo, in beats per minute
trait PhSpeedSetter
Selector
Sets
speed:
Playback or traversal rate
trait PhTriggerSetter
Selector
Sets
trigger:
The trigger input
trig:
Synonym of trigger:
gate:
The gate input — held open rather than momentary
max:
Upper bound on the trigger value
Trigger or gate
A trigger is an instant; a gate has duration. Percussion models care only that something
happened, so either works. Sustaining instruments and ADSR envelopes need the gate, because
the sustain stage lasts exactly as long as it is held.
3. Envelope traits
trait PhADSRSetter
Selector
Sets
attack:
Time to reach peak level, in seconds
release:
Time to fall to zero after the gate closes
sustain:
The level held while gated — not a duration
ar:
Attack and release together, for two-stage envelopes
level1: … level4:
Per-stage target levels
release1: … release4:
Per-stage release times
Decay lives elsewheredecay: is not in PhADSRSetter — it comes from the general
PhParamsSetter trait in §8. The selector works as expected; it is simply
declared in a different place.
trait PhBiasSetter
Selector
Sets
biasAttack:
Curvature of the attack segment
biasDecay:
Curvature of the decay segment
biasRelease:
Curvature of the release segment
The bias setters apply to the …EnvBias envelopes, and are what let you shape a
segment between linear and strongly exponential. See
Envelopes & Modulation §2.
4. Filter and gain traits
trait PhFilterSetter
Selector
Sets
freq: / frequency: / fr:
Corner or centre frequency
cutoff: / cutoffFreq:
Cutoff frequency, where the module names it so
q:
Quality factor — resonance sharpness
res:
Resonance expressed as an amount rather than a Q
gain:
Output or band gain
aN:
Filter coefficient, on the primitive sections
trait PhGainSetter
Selector
Sets
gain:
Output gain
trait PhCombFilterSetter
Selector
Sets
del:
Delay length
intDel:
Integer delay length in samples
b0:
Feed-forward coefficient at the input tap
b:
General coefficient
bM:
Coefficient at the delayed tap
trait PhWetAmountSetter
Selector
Sets
wetAmount:
Balance between the processed and untreated signal
5. Modulation traits
trait PhModulationSetter
Selector
Sets
modFreq:
Modulation frequency
modDepth:
Modulation depth
trait PhFMSetter
Selector
Sets
modIndex:
FM modulation index — how much the carrier is deviated
modRatio:
Ratio between modulator and carrier frequency
Index and ratio
In FM, the ratio decides which partials appear and the index decides how
strong they are. Integer ratios sound harmonic; raising the index at a fixed ratio brightens
without changing pitch. See Synthesis §5.
6. Physical modelling traits
trait PhPhysModelSetter
Selector
Sets
pressure:
Breath or bow pressure
breathGain:
Amount of breath noise
bowPressure:
How hard the bow presses
bowVelocity:
How fast the bow moves
bowPosition:
Where along the string the bow contacts
stiffness:
Material stiffness — governs inharmonicity
strikeSHarpness:
Sharpness of the strike; mallet hardness
tubeLength:
Physical tube length
bellOpening:
How open a brass bell is
length:
Generic physical length
excitation:
The excitation signal
trait PhPMSSetter
Selector
Sets
pluckPosition:
Where along the string it is plucked
strikePosition:
Where the object is struck
stringLength:
Physical string length
Note the capital H in strikeSHarpness: — it is a typo in the
package, but it is the selector that exists, so it is the one to send. See
Physical Modelling §8.
7. Input, size and interpolation
trait PhInputSetter
Selector
Sets
input:
The input signal
input1: / input2:
First and second inputs on two-input modules
inputL: / inputR:
Left and right channel inputs
trait PhMaxMinSetter
Selector
Sets
min:
Lower bound
max:
Upper bound
trait PhSizeSetter · PhNSetter
Selector
Sets
size:
Buffer or structure size
n:
Order, count or number of stages
trait PhInterpSetter
Selector
Sets
v0: / v1:
The two values to interpolate between
dv:
Interpolation delta
interpControl:
The interpolation control signal
trait PhTSLSetter
Selector
Sets
trig:
Trigger input
step:
Step size
length:
Length in steps
duration:
Duration in seconds
8. The general parameter trait
PhParamsSetter is the largest trait, carrying thirty-five selectors that did not
warrant a trait of their own. If a selector is not in any table above, look here first.
Because the traits wrap FAUST modules that named things independently, several concepts have
more than one selector. Any of these may be the right one depending on the class:
That trait is not composed into that particular class. The tables say what each trait
provides, not that every UGen has every trait. Try a synonym from §9.
The setter is accepted but nothing appears in traceAllParams
You passed a number, so the value was compiled in as a constant. Pass a symbol to expose it —
§1.1.
decay: is missing from the ADSR trait
It is in PhParamsSetter instead. The selector works — see §3 and §8.
strikeSharpness: is not understood
The selector is strikeSHarpness:, with a capital H. See §6.
I set sustain: to 2 expecting two seconds
Sustain is a level, not a time — a value of 2 is twice full scale. The duration of the
sustain stage is however long the gate is held. §3.
How do I know which traits a class has?
Inspect the class in Pharo, or take the practical route: traceAllParams on an
initialised DSP shows every parameter the class really exposes — §1.2.