set_parameter_display
Idempotent
Set a device parameter by the reading it should show, not raw value. Probes the parameter's response curve, then writes the exact value that yields your target display, without altering sound during search.
Instructions
Set a device parameter by the reading it should show, not by its raw value.
Returns:
Dictionary reporting the value written, the display it produced, the residual
error against the target, the unit, and how many probes and round trips it
took. On refusal, why - including the case where the device reports no units.
Note:
This is the inverse of ``set_parameter``, and it exists because there is no
formula to invert. The curve from the raw range onto the displayed unit
differs per parameter and is rarely linear: on one measured third-party
compressor Attack is ``v^4 * 1000 ms``, Ratio is ``20^v`` and Threshold about
``40 * log10(v)``. Writing "10" at a parameter that displays milliseconds
lands at 316 ms there, a factor of 30, and reports success.
So the taper is sampled rather than computed: one batch of probes asks the
device what each raw value *would* read as, the answers are bracketed around
the target, a second batch refines inside that bracket, and only then is a
single value written and read back. Two round trips, and nothing in the set
moves until the last step.
That last point is the reason not to bisect with real writes instead. A
probing bisection that does not restore what it touched has been measured
leaving Delay Feedback at 100 % - self-oscillation - and Saturator Drive at
100 % across 20 parameters (catalog row return_device.str_for_value). The
probes here write nothing at all.
The probes stay strictly inside the range and never ask at ``min`` or
``max``: an endpoint has crashed Live inside a plugin's own formatting code,
which is native code no try/except reaches (docs/limits.md, 'Asking for a
display string at an endpoint (Live)').
Where the device reports no unit this refuses instead of aiming. Every VST2
reports a bare number (0 of 36 measured), which is formally a number and
physically meaningless, so a display-driven search there would walk the
control to its end stop and call it a result. For those, use ``set_parameter``
with a normalised value and calibrate by ear once.
The result is the stored value and its display, which is not audibility: a
parameter on a device that is switched off reads back exactly the same.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Which collection the track index counts in: 'track' for song.tracks, 'return' for song.return_tracks, 'master' for the master track, where the track index is ignored. | track |
| unit | No | Which unit the target is in: 'dB', 'Hz', 'ms', '%', 'ratio', 'st', 'cents' or 'x'. Give kHz as Hz and seconds as ms. Optional: when omitted the unit the device reports is used, and a device reporting a different unit than you expected is a refusal, not a guess. | |
| track | Yes | Track index in song.tracks, counted from 0. | |
| device | Yes | Device index in that track chain, counted from 0. get_devices lists the chain with its indices. | |
| target | Yes | The reading you want, as a bare number in the base unit: -26 for -26 dB, 8000 for 8 kHz, 150 for 150 ms, 4 for a 4:1 ratio. Not the normalised value - that is set_parameter. | |
| parameter | Yes | Which parameter, either its index as a string ('1') or its name, which may be a glob ('Attack*'). A name that matches more than one parameter is refused rather than guessed at. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||