Shape rack performance controls

Use shape-rack-performance to turn an existing rack into a small set of playable controls, preserve a starting macro state and compare variations. For example: “Give this synth rack a Brightness control, store a restrained verse state and a brighter chorus state, then compare them.” The request should identify the rack and authorize any playback.

The workflow uses the all tool profile and an updated bridge. get_rack_performance_context reads visible macros and resolves their mappings to exact descendant device and parameter IDs, including nested racks and rack Return chains. It reports current values, units, automation, available mapping ranges, operation support and variation count/index in one native read. It preserves selection. Duplicate names and display paths are not target identities; unresolved targets and unsupported macro layouts are reported explicitly.

Live may expose mapped macro controls and variation operations while withholding mapping inspection and creation. Check operations and mappingTargetsAvailable. You can perform existing macros within the request while stating that their target effects are hidden. Custom mapping creation is unavailable when operations.mapTargets is false; do not guess from macro names or silently substitute another preset.

Preserve the starting exposed values before editing. For a mapped rack, store_rack_macro_variation appends a starting variation; it does not overwrite an existing one. Retain storedVariationIndex from its receipt. Storage can leave the selected index unchanged, including at -1; selection is not the identity of the newly stored variation. Live does not expose saved variation contents before recall, and the selected index does not establish that the current controls still match that variation. An unmapped rack needs a requested mapping before variation storage is available; adding the mapping can itself change the target value.

When mapping creation is exposed and requested, use observed parameter IDs with map_rack_macro_to_parameter, inspect the resulting range and name the control with rename_rack_macro. One macro can drive multiple parameters. Range editing with set_rack_macro_mapping_edge requires exactly one nonquantized mapping on that macro: configure its range before adding further targets, or choose another supported layout. Native ranges may be reversed; numbers use target parameter units, not an assumed percentage scale. A mapped target can become disabled for direct writes; operate its macro instead.

Set a state through the actual macro parameter IDs with set_device_parameters, inspect every available affected target, then store a new variation. Recall a chosen index with recall_rack_macro_variation and read back the controls. A matching selected index alone is insufficient. Recall changes eligible macro values immediately; it is not beat-scheduled, a crossfade or a guaranteed click-free transition. Automation and Live's exclusions can leave some values unchanged. Randomization is unseeded and should be used only when requested.

After a manual edit or interrupted call, inspect the current rack before continuing. Do not replay a store call blindly or restore stale values over a user's changes. Variations preserve eligible macro values, not mappings, ranges, names, hidden plug-in state or recorded content. Removing a variation cannot recover its saved contents. Retain the chosen state and starting variation unless cleanup is requested, and save only within the user's scope.

Listen together when playback is authorized. Parameter readback establishes control behavior; ask what the user hears before calling the sound better.