set_parameter_display
Idempotent
Set a device parameter by the display reading you want (e.g. -26 dB, 8 kHz) instead of a raw value. It probes the device's display curve, writes the matching value, and verifies the result.
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:
The inverse of ``set_parameter``, and 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)``, so writing 10 at a parameter that displays
milliseconds lands at 316 ms, a factor of 30, and reports success.
The taper is sampled, not computed: one batch of probes asks 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 that last step. Probing with real
writes 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. They also stay strictly
inside the range and never ask at ``min`` or ``max``, where a plug-in's own
formatting code has crashed Live in 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), so a display-driven search there would walk the
control to its end stop and call it a result. Use ``set_parameter`` with a
normalised value for those 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 | |||