The complete protocol of the DSP object — the thing that actually makes sound —
together with the parameter classes that describe what can be changed inside it.
1. What a DSP is
DSP is an opaque handle on a compiled FAUST program. It is not a Pharo object in
the ordinary sense — it wraps memory owned by the FAUST engine, reached over uFFI. That has
two practical consequences: it must be initialised before it can do anything, and it must be
destroyed to release its memory.
Everything else on this page is a message you can send to that handle. A UGen chain is the description of a sound; the DSP is the running instance of it.
2. Creating a DSP
2.1 From a UGen
The usual route — send one of these to any UGen:
| Message | Produces |
|---|---|
| asDsp | A mono DSP |
| asDspWithName: | A named DSP — useful when several run at once |
| asDspMIDI | A MIDI-enabled DSP |
| asDspMIDIWithName: | A named MIDI-enabled DSP |
Send stereo to the UGen first for two-channel output.
2.2 From FAUST source
A DSP can also be built from a FAUST program as a string, bypassing the UGen layer entirely:
| Class-side message | Effect |
|---|---|
| DSP create: aString | Compile a FAUST program |
| DSP create: aString withName: aName | The same, named |
| DSP defaultName | The name used when none is given |
x1 := DSP create: 'import("stdfaust.lib"); process = os.osc(400);'.
x1 init.
x1 start.See Raw FAUST & the Box API for when this is worth doing.
2.3 The registry
Phausto keeps track of the DSPs it has created, which is how you find one you have lost the variable for:
| Class-side message | Returns |
|---|---|
| DSP initializedDSPs | Every DSP currently initialised |
| DSP initializedDSP | The most recently initialised DSP |
| DSP register: aDsp | Add a DSP to the registry |
| DSP unregister: aDsp | Remove one |
| DSP rendererType | The audio renderer in use on this platform |
DSP initializedDSPs do: [ :d | d stop ] will silence everything.
3. Lifecycle
| Message | Effect |
|---|---|
| init | Compile to native code and allocate buffers. Required once before start |
| start | Begin audio output on the audio thread |
| stop | Halt output; the DSP stays initialised and can be restarted |
| destroy | Release native memory and unregister |
| play | Convenience: init then start |
| playFor: aDuration | Start, wait, then stop |
| isInitialized | Whether init has run |
| name / name: | The DSP's name |
| source / source: | The UGen this DSP was built from |
| isMIDI / isMIDI: | Whether MIDI support was compiled in |
stop then destroy before rebuilding. See
First Sounds §2.2.
4. Parameter access
4.1 Setting
| Message | Effect |
|---|---|
| setValue: aNumber parameter: aString | Set a parameter by name |
| setValue: aNumber parameterIndex: anInteger | Set by index — skips the name lookup |
| sweepToValue: aTarget parameter: aString in: seconds | Move gradually to a value |
| sweepToMfValue: aTarget parameter: aString in: seconds | The same, for multiplication-factor parameters |
4.2 Reading and discovery
| Message | Returns |
|---|---|
| traceAllParams | Prints every parameter and value to the Transcript |
| allParameters | All parameters as objects |
| parameters | The parameter collection |
| parameterStore | The DSPParameterStore — see §8 |
| getParamCount | How many parameters exist |
| getParamValue: aString | Current value, by name |
| getParamValueIndex: anInteger | Current value, by index |
| getParamAddress: anInteger | The name at a given index |
| getParamIndex: aString | The index of a given name |
| includesParameter: aString | Whether a name exists |
'Freeverb/0x00/RoomSize'. Copy them verbatim from
traceAllParams rather than reconstructing them.
5. Triggering and performance
| Message | Effect |
|---|---|
| trig: aString | Fire a named trigger |
| trig: aString for: seconds | Hold a gate open for a duration, then release |
| playNote: aMidiNN prefix: aString dur: seconds | Play a MIDI note on a prefixed instrument |
| syncTrigReset | Reset synchronised triggers to a common origin |
| startSubBeat | Start the sub-beat clock |
6. Interface
| Message | Opens |
|---|---|
| displayUI | The complete generated interface |
| sliderFor: aString | A slider presenter for one parameter |
| buttonFor: aString | A button presenter for one trigger |
| openSliderFor: aString | Build and open a slider in one step |
| openButtonFor: aString | Build and open a button in one step |
| keyBoardFor: aSynthName | A piano keyboard bound to an instrument |
| requirePianoKeyboard | Ensure the keyboard component is loaded |
s := dsp sliderFor: 'SineOscFreq'.
s openInWindow.7. Introspection
The FAUST engine can describe its own interface, which is how displayUI is built
and how the exporters know what controls to generate:
| Message | Returns |
|---|---|
| getJSON | The full FAUST UI description as JSON |
| getUIfromJSON | The parsed UI structure |
| getUIItems | Every UI item |
| getUIItemsLabeledDictionary | UI items keyed by label |
| getUIButtons | Just the buttons |
| getUIKnobs | Just the continuous controls |
| getNumInput | Number of audio inputs |
| getNumOutput | Number of audio outputs |
| generatedCode | The FAUST source that was compiled |
| soundfiles | Sound files referenced by the DSP |
dsp generatedCode returns the FAUST program Phausto built from your UGen chain.
It is the single best way to understand what an operator actually compiled to — and useful
when a patch does not behave as expected.
8. DSPParameter and DSPParameterStore
Beyond raw name-and-value access, Phausto models parameters as objects. This is the layer presets, automation and plugin exports are built on.
Represents a single adjustable value: its current value and its valid range. It knows nothing about the UI, the DSP code, or presets — only what the parameter is.
| Accessor | Meaning |
|---|---|
| label / label: | Display label |
| shortName / shortName: | Abbreviated name |
| address / address: | Full FAUST path |
| initValue / initValue: | Default value |
| minValue / minValue: | Lower bound |
| maxValue / maxValue: | Upper bound |
| stepValue / stepValue: | Increment |
| type / type: | Widget type — slider, button, entry |
| DSPParameter fromDictionary: | Build one from a parsed JSON description |
Holds all parameters of a DSP in one place. UI, presets, automation and the DSP itself read from the store, but the store depends on none of them.
| Message | Effect |
|---|---|
| DSPParameterStore from: aDSP | Build a store for a DSP |
| parameters | The stored parameters |
| dsp / dsp: | The DSP it belongs to |
DSPParameter (what a parameter is) and
DSPParameterStore (where values live) is deliberate. It is what makes it
possible to export a patch as a JUCE plugin with a full parameter tree — see
Exporting.
9. Exceptions
| Exception | Raised when |
|---|---|
| DSP uninitializedException | A DSP is used before init |
| DSP invalidException | The DSP could not be compiled or is otherwise unusable |
| DSP paramException | A parameter operation failed |
| PhBox nullBoxException | A box expression produced nothing — usually a connection error |
getLastError on PhaustoDynamicEngine returns the FAUST compiler's
own message, which is usually more specific than the Pharo-side exception. See
Architecture & Internals.
11. Troubleshooting
An exception says the DSP is not initialised
init must run once before start or any parameter access — §3.
Sound is playing and I have lost the reference
DSP initializedDSPs do: [ :d | d stop ] — §2.3.
getParamValue: returns nothing useful
The name does not exist. Check with includesParameter: first, or list them with
traceAllParams — §4.2.
The patch compiles but sounds wrong, and I cannot see why
Read dsp generatedCode. The FAUST source shows exactly what the operators
produced — §7.
A null box exception when building the DSP
A connection failed, usually a channel-count mismatch. See
Connecting §7, and check
PhaustoDynamicEngine getLastError — §9.
The image slows down the longer I work
DSPs are accumulating. Destroy them — §3.