PLUG'N SCRIPT
rapid plugin development
Tutorial
DSP
KUIML
How-to
Scripts
  • Tutorial
  • Element Reference
Language basics
  • SKIN
  • DUMMY
  • INCLUDE
  • INCLUDE_ONCE
  • DEFINE
  • UNDEFINE
  • VARIABLE
  • LOCAL_VARIABLE
  • TEMPLATE
  • TEMPLATE_INNER_CONTENT
  • REPEAT
Data model
  • PARAM
  • ACTION
    • Action types
  • ACTION_TRIGGER
UI Layout and positioning
  • CELL
  • TABLE
UI Widgets
  • TEXT
  • TEXT_FIELD
  • TEXT_EDIT_BOX
  • CANVAS
    • Graphics API
  • svg
Common attrubutes
  • For all elements
  • Widgets
  • Param Widgets
  • Param Controls
  • Param Info Viewers
  • Text Widgets
  • Surface Viewers
  • Curve Viewers
  • 3D Objects
  • Parameters mapping
KUIMLElement ReferencePARAM
December 13, 2022

PARAM

This element can be used to create custom parameters.

Attributes brief detailed show all inherited

Name DescriptionDefault
Exposed: v. 1.6.2minParameter minimum value0
Exposed: v. 1.6.2maxParameter maximum value0
Exposed: v. 1.6.2defaultParameter default value0
typeType of the declared parameter: 'real', 'boolean', 'integer' or 'enumeration'real
Exposed: v. 1.4.3enum_valuesList of text values for an enumeration. When set, this automatically sets the range from 0 to the number of values in the list minus 1Starting with v1.6.2, the start value for the enumeration is not necessarily 0, but the min value specified with the parameter if anyempty
value_formatCustom formatting used by default to display the parameter as textSee the {text_value} field in parameter text widgets' .2'
Exposed: v. 1.9.2unitUnit of the parameterempty
Exposed: v. 1.9.2nameDisplayed named of the parameterempty
commentComment about the parameterempty
exposedMake parameter available for scriptsWhen this property is set to 'true', the parameter will be exposed to the scripting engine. It can be also achieved via "requires" attribute in SCRIPT, ACTION or ACTION_TRIGGER, as well as via EXPOSED_OBJECTS element.false
persistentSets the persistency of the parameterWhen this property is set to 'true', the parameter will be saved when closing the user interface and the value will be restored next time the user interface is openedfalse
persistence_contextSets when the persistency is saved or not ("-Preset", "-Init")If you don't want your parameter to be saved persistently with the preset, set this to "-Preset", not with the default preset: "-Init", if not with both: "-Init;Preset"empty
lockedIf set to true, the associated param is ignored when loading presets.This is a meta attribute that controls the persistency of a persistent model element. When set to 'always', the generated locked attribute is read-only. When set to 'never', no lock attribute is generated. Otherwise, the value of the locked meta attribute can be changed at runtime via `my_param.meta.locked`empty
Read Only Attributes
Exposed: v. 1.9.2capturingtrue if user is changing the valuefalse
Events
Exposed: v. 2.0value_changedthe event is triggered anytime the value of the object has changed
Exposed: v. 2.7.1text_valueThe value of the parameter as text.
Actions
Exposed: v. 2.4BeginCaptureBegin value edition (call when starting to modify the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
Exposed: v. 2.4EndCaptureEnd value edition (call when done with modifying the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
Common attributesRead about `common`
idIdentifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifierempty
Name Value type Default Description Comment
Exposed: v. 1.6.2minreal number0Parameter minimum value
Exposed: v. 1.6.2maxreal number0Parameter maximum value
Exposed: v. 1.6.2defaultreal number0Parameter default value
typeparam typerealType of the declared parameter: 'real', 'boolean', 'integer' or 'enumeration'
Exposed: v. 1.4.3enum_valueslist of strings separated by ';'emptyList of text values for an enumeration. When set, this automatically sets the range from 0 to the number of values in the list minus 1Starting with v1.6.2, the start value for the enumeration is not necessarily 0, but the min value specified with the parameter if any
value_formatparam value formatting' .2'Custom formatting used by default to display the parameter as textSee the {text_value} field in parameter text widgets
Exposed: v. 1.9.2unitstringemptyUnit of the parameter
Exposed: v. 1.9.2namestringemptyDisplayed named of the parameter
commentstringemptyComment about the parameter
exposedbooleanfalseMake parameter available for scriptsWhen this property is set to 'true', the parameter will be exposed to the scripting engine. It can be also achieved via "requires" attribute in SCRIPT, ACTION or ACTION_TRIGGER, as well as via EXPOSED_OBJECTS element.
persistentbooleanfalseSets the persistency of the parameterWhen this property is set to 'true', the parameter will be saved when closing the user interface and the value will be restored next time the user interface is opened
persistence_contextsee descemptySets when the persistency is saved or not ("-Preset", "-Init")If you don't want your parameter to be saved persistently with the preset, set this to "-Preset", not with the default preset: "-Init", if not with both: "-Init;Preset"
lockedtrue, false, always, neveremptyIf set to true, the associated param is ignored when loading presets.This is a meta attribute that controls the persistency of a persistent model element. When set to 'always', the generated locked attribute is read-only. When set to 'never', no lock attribute is generated. Otherwise, the value of the locked meta attribute can be changed at runtime via `my_param.meta.locked`
Read Only Attributes
Exposed: v. 1.9.2capturingbooleanfalsetrue if user is changing the value
Events
Exposed: v. 2.0value_changedeventthe event is triggered anytime the value of the object has changed
Exposed: v. 2.7.1text_valuestringThe value of the parameter as text.
Actions
Exposed: v. 2.4BeginCaptureactionBegin value edition (call when starting to modify the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
Exposed: v. 2.4EndCaptureactionEnd value edition (call when done with modifying the value from scripts, especially for parameters that are exposed to automation)Changes the value of the capturing attribute
Common attributesRead about `common`
ididentifieremptyIdentifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifier

Examples

The following example creates a single parameter and adds a control to change that parameter:

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN>
  3. <PARAM id="gain" max="20" min="-20" default="0" unit="dB" />
  4. <PARAM_TEXT_CONTROL param_id="gain" cursor="system::size_v" />
  5. </SKIN>

Other param types

The default 'real' param type is the most useful: it can keep floating point values (like 0.234, 6124.234 etc). 
However other params types can sometimes be very handy:

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN>
  3. <!-- create different params -->
  4. <PARAM id="modes" type="enumeration" enum_values="Classic;Neutral;Modern" />
  5. <PARAM id="steps" type="integer" min="1" max="8" default="4" value_format=".0" />
  6. <PARAM id="enabled" type="boolean" default="false" />

  7. <!-- dropdown menu for enums -->
  8. <PARAM_TEXT param_id="modes">
  9. <INVISIBLE_PARAM_MENU_BUTTON param_id="modes" width="100%" height="100%" cursor="system::hand" />
  10. </PARAM_TEXT>

  11. <!-- dropdown menu for integer param -->
  12. <PARAM_TEXT param_id="steps">
  13. <INVISIBLE_PARAM_MENU_BUTTON param_id="steps" width="100%" height="100%" cursor="system::hand" />
  14. </PARAM_TEXT>

  15. <!-- on/off switch -->
  16. <PARAM_TEXT param_id="enabled" content="enabled: {value}" value_format=".0">
  17. <INVISIBLE_PARAM_BUTTON param_id="enabled" positions_count="2" width="100%" height="100%" cursor="system::hand" />
  18. </PARAM_TEXT>
  19. </SKIN>

Persistent, exposed, capturing, value_changed

Use "persistent" attribute to make this parameter remember its value even when the skin reloads.
Use "exposed" to expose it for scripting engine — when you need to read or write this parameter in the script.
Here are some examples of using "capturing" and "value_changed" to trigger events.

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN spacing="4">
  3. <!-- the parameter value will be remembered between reloads (persistent) -->
  4. <PARAM id="gain" max="20" min="-20" default="0" unit="dB" persistent="true" />

  5. <ROW spacing="10">
  6. <!-- an indicator showing when param is "capturing" -->
  7. <WIDGET id="indicator" background_color="#00DD00" opacity="0.1" width="20" height="20" />
  8. <PARAM_LINK from="gain.capturing" to="indicator.opacity" formula="0.1+x" />
  9. <!-- param control -->
  10. <PARAM_TEXT_CONTROL param_id="gain" cursor="system::size_v" width="60" />
  11. </ROW>

  12. <ROW>
  13. <!-- trigger capturing events -->
  14. <SCRIPT script="int capturing_fired = 0; " />
  15. <ACTION_TRIGGER event_id="gain.capturing.value_changed" condition_formula="gain.capturing != 0"
  16. script=" 
  17. capturing_fired++;
  18. hint_capturing = &quot;`Capturing` fired: &quot; + capturing_fired;
  19.  " requires="hint_capturing" />
  20. <!-- capturing hint -->
  21. <STRING id="hint_capturing" />
  22. <TEXT string_id="hint_capturing" width="150" />
  23. </ROW>

  24. <ROW>
  25. <!-- trigger gain value changed -->
  26. <ACTION_TRIGGER event_id="gain.value_changed" script=" 
  27. if (gain > 10) {
  28. hint = &quot;Gain is too big!&quot;;
  29. } else {
  30. hint = &quot;&quot;;
  31. }
  32.  " requires="hint;gain" />
  33. <!-- gain too big hint -->
  34. <STRING id="hint" />
  35. <TEXT string_id="hint" width="150" />
  36. </ROW>

  37. </SKIN>

Note that in line 35 we expose required params to scripting engine via requires="hint;gain". We could achieve the same using exposed="true" for the gain param and for the hint string.

Persistence_context and locked

These attributes are related to persistent="true" attribute. When you make a param persistent (meaning its value is kept even when you reload the script) this parameter value is also saved within the preset (and within the default preset, called "Init" internally). If you don't want the preset loading to change your persistent param value, you can either use locked="true" meta-attribute to prevent it (and you can lock or unlock on the fly using param_id.meta.locked), or you can use persistence_context="-Preset;Init" to permanently prevent this param from saving and loading with presets and default preset.

BeginCapture and EndCapture

These actions are needed when you want to change the input parameter value from the GUI via script, If you don't call these actions you may see that param was changed in the GUI, but not in the DSP (as well as in DAW automation).

Let's say you have a GUI script that is automating DSP gain parameter (custom_param0 in our case)

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN spacing="4">

  3. <!-- keep input parameter name in variable -->
  4. <VARIABLE id="GAIN" value="custom_param0" />
  5. <!-- display/control current value -->
  6. <PARAM_TEXT_CONTROL param_id="$GAIN$" />

  7. <!-- timer to trigger auto changes -->
  8. <TIMER refresh_time_ms="100" id="gain_timer" enabled="false" />

  9. <!-- prepare script variables -->
  10. <SCRIPT script=" 
  11. double last_gain = 0;
  12. double delta = 0.5;
  13. bool rising = true;
  14.  " />

  15. <!-- trigger action on timer events -->
  16. <ACTION_TRIGGER event_id="gain_timer.elapsed" script=" 
  17. last_gain = $GAIN$;
  18. if (rising) {
  19. last_gain += delta;
  20. } else {
  21. last_gain -= delta;
  22. }
  23. if (last_gain &gt; 6) rising = false;
  24. if (last_gain &lt; -6) rising = true;

  25. /* update input parameter */
  26. $GAIN$.BeginCapture();
  27. $GAIN$ = last_gain;
  28. $GAIN$.EndCapture();
  29.  " requires="$GAIN$.BeginCapture;$GAIN$.EndCapture" />

  30. <ROW spacing="5">
  31. <!-- indicators showing when timer is "enabled" -->
  32. <LAYER_STACK>
  33. <WIDGET id="indicator_green" background_color="#00DD00" opacity="0" width="20" height="20" />
  34. <WIDGET id="indicator_red" background_color="#DD0000" opacity="0" width="20" height="20" />
  35. <PARAM_LINK from="gain_timer.enabled" to="indicator_green.opacity" formula="x" />
  36. <PARAM_LINK from="gain_timer.enabled" to="indicator_red.opacity" formula="x" reverse="true" />
  37. </LAYER_STACK>

  38. <!-- click to enable/disable timer -->
  39. <PARAM_TEXT param_id="gain_timer.enabled" width="100" content="auto: {text_value}">
  40. <INVISIBLE_PARAM_BUTTON param_id="gain_timer.enabled" positions_count="2" width="100%" height="100%" cursor="system::hand" />
  41. </PARAM_TEXT>
  42. </ROW>
  43. </SKIN>

Works in LM Skin, but not in the default skin

Note, that for this script to work in default skin, you have to add this to "default.xml":

  1. <REQUIRED_OBJECTS object_ids="custom_param0.BeginCapture;custom_param0.EndCapture" />

On the DSP side there's a simple script adding a parameter using "params.as" extension (you can add it in traditional way as well), and printing it's value:

  1. string name="KUIML Test";
  2.  
  3. #include "library/params.as"
  4.  
  5. int GAIN;
  6. void initialize(){
  7. GAIN = ip("Gain", "dB", -40, 40, 0, ".1");
  8. }
  9.  
  10. void updateInputParameters(){
  11. print("Gain: " + IP[GAIN]);
  12. }

2020 © Plug'n Script and KUIML by Blue Cat Audio  |  Site by LetiMix