Parameter Mapping Explained

When writing a .kuiml file for a script, we often use names like custom_param0, custom_param1, custom_param2, etc. to access the parameters we added in the DSP section. But here’s the catch: these custom parameters are not the actual DSP parameters. Let’s break down why they exist, and why they sometimes cause issues.

Dynamic Script Loading

The real DSP parameters exposed to the GUI by the PnS engine are named like dsp.input0, dsp.input1, dsp.input2, and so on. This naming system is consistent across all Blue Cat Audio plugins.

However, Plug’n Script is different because it needs to load different scripts on the fly, each with its own parameter set. The problem is: a plugin inside a DAW can’t just change its parameter list on the fly — most DAWs don’t allow that.

So, Plug’n Script uses a workaround:

• To the DAW, it exposes a fixed set of generic parameters, with ranges from 0 to 1, named like Param 0, Param 1, etc.
• Inside the GUI, these generic parameters get linked to custom_params defined in the skin.
• These custom_params are flexible — their names, ranges, default values, and other properties can change depending on the currently loaded script.
• But since they only exist inside the skin, they are not exposed to the DAW.

Seeing It in Action

To understand this better, open the “LetiMix Debug” skin (included in LM Skin). It clearly shows how the mapping between the generic parameters and the custom ones works in practice.

I've loaded a simple "Gain" script that adds a single input parameter called "Gain" with ranges from -20 to 20 dB. 

As you can see it's linked to a dsp.input8 parameter, which is a "real" dsp parameter. And as already said "custom_param0" is an "alias" or "proxy" parameter that is created inside the skin.

When we change the value of "custom_param0" it changes the value of dsp.input8 and vice versa. The value of dsp.input8 param changes from 0 to 1, but is displayed as 0..100% by default.

These two parameters are linked in the skin using PARAM_LINK, something like this (slighly simplified):

The links are "normalized" meaning the ranges of the parameters are matched. So if one parameter has range from 0 to 1, another from 0 to 10, when we set first parameter to 0.5 another is set to 5.

But how does "custom_param" gets information about it's current name and range from the script? Well, it's also exposed to the GUI using hidden dsp.private_output params and dsp.output_strings. 

Here I've loaded another script that exposes 4 input and 2 output parameters. Current number of input/output parameters is exposed using dsp.private_output1/2, and several more hidden parameters and strings are used. They transfer information to the GUI about "custom_param" attributes (min, max and default values, number of "steps", name, units, list of enumerated_values and value format).

So for providing each "custom_param" attributes Plug'n Script actually uses 8 additional parameters and strings.

Later in the skin all this information is linked to every "custom_param" like this:

If you want to see how it's done really (not slightly simplified like here), you can open the default skin folder and find files "mapping.inc" and "mapping_utils.inc". The same principles are used in LetiMix skin (mappings are in the file "common.inc")

This "trick" allows Plug'n Script to create individual script parameters on the fly, without the need to reload the plugin or restart the DAW. For the DAW the number of DSP parameters and their properties remain the same. And for the script-writer the parameter name and range ("custom_param0") stays the same after exporting.

Accessing parameters after export

We really don't need "custom_params" trick when our plugin is exported. But it stays there for the compatibility reasons, so that we can have the same simple .kuiml with same parameter names and it would work fine. However "custom_param" becomes a "rudiment", and after export it is wiser to use "dsp.input" params directly. 

Something like this would work fine. If you want to make it even easier to manage parameter names in KUIML, you can do it like this (works in LM Skin):

This would work fine both in PnS and after export.

Changing custom_param value from the script

Many of us struggle, when we try for the first time to write a GUI script that changes input parameter. Suddenly we find out that though the knob in the GUI turns, the parameter in the DSP is not updated. Don't give up!

Take a look at the last line in the parameter linking example that says: 

It enables the "link back" from the "custom_param0" to "dsp.input8" only when custom_param0 is "capturing". Meaning its value is changed by user via mouse or keyboard. Why is this done that way? Why not just always keep custom_param and dsp.input param linked both ways? Blue Cat Audio explains that otherwise there is a possibility of a bad linking "loop" when you load a preset or change parameter via MIDI.

So how to do we do this then? For example, this script would only change the parameter in the GUI (custom_param0), but not the input value in the DSP (dsp.input8).

To make it work we have to add "BeginCapture" and "EndCapture" calls like this:

Now this parameter is marked as "capturing" and its value is updated in the dsp.input parameter as well. These BeginCapture/EndCapture calls are also required for some DAWs to update parameter value or write automation. If you omit them, in some DAWs it may work, in some it will not.

Note: if you have popup errors trying to use "BeginCapture", try to explicitly add them as "REQUIRED_OBJECTS" to the main skin (XML file you're using), like this:

Or, if you're modifying dsp.input8 directly from the .kuiml you may need this

Compare the numbers

Just for fun, here's the same script in Plug'n Script (on the left) and as an exported plugin (on the right).

Compare the number of exposed parameters. 

The exported plugin has only the input parameters we've added in the script (4 parameters + default bypass), and their names, ranges and units are specified.  Plug'n Script has 48 generic params (by default) + 7 for internal purposes.

The exported plugin dsp.inputX parameters already have correct ranges, names and units, so mapping them to "custom_params" is unnecessary and done just for backward compatibility.

Conclusion

Now you know that "custom_params" are just aliases created in the skin, so you should use them wisely! The good decision would be to use "dsp.input" params directly after export (just be aware that their names change after export - like dsp.input8 becomes dsp.input1), as shown in the examples above.

Good luck with your scripting!

P.S. Take a look at article "How to add params more conveniently".