tur/params
stdlib/params.tur
defn
warp-value
(warp-value [spec value])
Map a user-space value to OSC range using the spec's warp type.
Parameters
| spec | A ParamSpec map containing at least :warp. | |
| value | Input value in user space. |
Example
Warped value suitable for sending to scsynth. (warp-value PARAM_FREQ 440.0) ; => 440.0 (exp warp applies octave formula)
defn
unwarp-value
(unwarp-value [spec value])
Map an OSC value back to user space using the spec's warp type.
Parameters
| spec | A ParamSpec map containing at least :warp. | |
| value | Value received from scsynth in OSC space. |
Example
Value in user space (inverse warp of warp-value). (unwarp-value PARAM_FREQ (warp-value PARAM_FREQ 440.0)) ; => 440.0
defn
clamp-value
(clamp-value [spec value])
Clamp a value to the min/max range specified in a ParamSpec.
Parameters
| spec | A ParamSpec map with :min and :max fields. | |
| value | Value to clamp. |
Example
The value clamped to [spec.min, spec.max]. (clamp-value PARAM_AMP 1.5) ; => 1.0
defn
param->osc
(param->osc [spec value])
Clamp and warp a user-space value ready for scsynth.
Parameters
| spec | A ParamSpec map. | |
| value | User-space value. |
Example
OSC-ready float (clamped first, then warped). (param->osc PARAM_AMP 0.8) ; => 0.8
defn
osc->param
(osc->param [spec value])
Unwarp and clamp an OSC value back to user space.
Parameters
| spec | A ParamSpec map. | |
| value | OSC value from scsynth. |
Example
User-space float clamped to the spec's original range. (osc->param PARAM_AMP 0.8) ; => 0.8
defn
param-spec
(param-spec [name default & [min 0.0 max 1.0 unit "" warp :linear])
Create a parameter specification with common defaults.
Parameters
| name | Parameter name string (must match the SynthDef control name). | |
| default | Default value. | |
| min | Minimum value (default: 0.0). | |
| max | Maximum value (default: 1.0). | |
| unit | Unit label string, e.g. "Hz", "dB", "sec" (default: ""). | |
| warp | Warp type keyword: :linear, :exp, :log, :db, :db2 (default: :linear). |
Example
A ParamSpec map. (param-spec "freq" 440.0 20.0 20000.0 "Hz" :exp)
defn
synthdef-spec
(synthdef-spec [synthdef_name param-specs])
Assemble a SynthDef specification from a list of ParamSpecs.
Parameters
| synthdef_name | SynthDef name (currently unused; reserved for future metadata). | |
| param-specs | Vector of ParamSpec maps describing each control. |
Example
SynthDefSpec (currently just the param-specs vector). (synthdef-spec "mySynth" [PARAM_FREQ PARAM_AMP])
defn
find-param
(find-param [spec param_name])
Find a ParamSpec by name within a SynthDefSpec.
Parameters
| spec | SynthDefSpec (vector of ParamSpec maps). | |
| param_name | Parameter name to search for. |
Example
The matching ParamSpec map, or nil if not found. (find-param SIN_SYNTH_SPEC "freq")
defn
find-param-index
(find-param-index [spec param_name])
Get the zero-based index of a parameter by name.
Parameters
| spec | SynthDefSpec (vector of ParamSpec maps). | |
| param_name | Parameter name to search for. |
Example
Integer index of the parameter, or nil if not found. (find-param-index SIN_SYNTH_SPEC "amp") ; => 1
defstruct
SynthController
(defstruct SynthController [])
defn
synth-controller-new
(synth-controller-new [session synthdef-name synthdef-spec & [params {}])
Create a synth and wrap it in a typed controller.
Parameters
| session | Parent ScscmSession. | |
| synthdef-name | Name of the SynthDef to instantiate. | |
| synthdef-spec | SynthDefSpec listing this SynthDef's parameters. | |
| params | Optional initial values as a name -> value map. |
Example
A SynthController map. Panics if the synth cannot be created.
(synth-controller-new sess "mySynth" SIN_SYNTH_SPEC {"freq" 880.0})
defn
synth-controller-free
(synth-controller-free [ctrl])
Free the synth node owned by a controller.
Parameters
| ctrl | A SynthController map. |
defn
ctrl-set
(ctrl-set [ctrl param_name value])
Set a named parameter on a synth controller (with warping).
Parameters
| ctrl | A SynthController map. | |
| param_name | Name of the parameter to set. | |
| value | User-space value (will be clamped and warped before sending). |
Example
true if the parameter was found and set, false otherwise. (ctrl-set ctrl "freq" 880.0)
defn
ctrl-set-multi
(ctrl-set-multi [ctrl param-map])
Set multiple named parameters on a controller.
Parameters
| ctrl | A SynthController map. | |
| param-map | Map of parameter name -> user-space value. |
Example
Number of parameters successfully set.
(ctrl-set-multi ctrl {"freq" 880.0 "amp" 0.6}) ; => 2
defn
ctrl-get
(ctrl-get [ctrl param_name])
Get the current value for a named parameter (returns spec default).
Parameters
| ctrl | A SynthController map. | |
| param_name | Parameter name to look up. |
Example
Default value from the ParamSpec, or nil if the parameter is not found. (ctrl-get ctrl "freq") ; => 440.0 (spec default)
defn
midi->hz
(midi->hz [note])
Convert a MIDI note number to frequency in Hz.
Parameters
| note | MIDI note number (69 = A4 = 440 Hz). |
Example
Frequency in Hz as a float. (midi->hz 69) ; => 440.0
defn
vel->amp
(vel->amp [vel])
Convert a MIDI velocity to linear amplitude.
Parameters
| vel | MIDI velocity (0-127). |
Example
Amplitude in [0.0, 1.0]. (vel->amp 64) ; => ~0.504
defn
db->amp
(db->amp [db])
Convert a decibel level to linear amplitude.
Parameters
| db | Level in decibels. |
Example
Linear amplitude as a float. (db->amp -6.0) ; => ~0.501
defn
amp->db
(amp->db [amp])
Convert linear amplitude to decibels.
Parameters
| amp | Linear amplitude (0.0 or below returns -90.0). |
Example
Level in decibels. (amp->db 0.5) ; => ~-6.02