parameter-automation-documentation.txt (8148B)
1 An Introduction to the ZynAddSubFX Macro System 2 =============================================== 3 :author: Mark McCurry, Spencer Jackson 4 :toc: 5 6 7 Motivation 8 ---------- 9 10 One of the major issues expressed by users around the time of the initial 11 3.0.0 launch was that they were dissatisfied with automations when using 12 ZynAddSubFX within their preferred VST host. This was a combination of: 13 14 1. Hosts providing a poor workflow for sending MIDI CC events compared to VST 15 parameters 16 2. Confusion with the use of MIDI learn within Zyn 17 3. Issues regarding saving/loading parameters exposed through MIDI learn 18 4. Parameter resolution for MIDI CCs 19 5. Some parameters only produce updates on the next note 20 21 This feature attempts to address points 1, 2, & 3. Issue 4 is a large undertaking 22 but is expected to become complete for the 3.1.x release. Issue 5 is being fixed 23 one set of parameters at a time and should be addressed in the 3.0.x series. 24 25 Overview & Terminology 26 ---------------------- 27 28 The Macro System boils down to replacing the existing MIDI learn implementation 29 with a series of 'slots' for parameter automation and automation 30 macros. In its current state it does that and a little more but as it matures it 31 should become a powerful system for automation and live tweaking of sounds. 32 33 What is an automation? 34 ~~~~~~~~~~~~~~~~~~~~~~ 35 image::automation1.png[] 36 37 - A single parameter, e.g. the addsynth base frequency in part 1, kit 1 38 - A gain and offset to adjust the range of values the automation will reach 39 (e.g. -50 cents to +150 cents) 40 - A mapping function (currently only linear, log, custom, etc coming soon) 41 42 What is a macro? 43 ~~~~~~~~~~~~~~~~ 44 45 - A group of automations that get assigned to an automation slot 46 47 All automations in the macro are operated together. Thus turning one knob on 48 your MIDI controller or a single automation lane in a DAW can change up to 49 4 parameters (see <<FAQ>>) 50 at a time. Using the automation mappings allows for all the parameters to be adjusted 51 in different amounts and/or directions, but they are all moved by actuating the macro. 52 53 Macros are assembled by adding automations to a macro slot. 54 55 What is a macro slot? 56 ~~~~~~~~~~~~~~~~~~~~~~ 57 58 - A set of one or more automations (a single macro) 59 - An optional MIDI CC binding or plugin host automation 60 61 In Zynaddsubfx 3.0.2 all macro slots are global. This means that loading new 62 instruments does not switch the automations in any way. Only loading and saving 63 Zyn master files will allow you to quickly switch between macro slot configurations. 64 In future versions there 65 will be global macro slots and instrument macro slots that can be saved 66 and loaded independently. 67 68 The global macro slots are exposed to VST/LV2 hosts. 69 This keeps the total number of parameters exposed to a host somewhat 70 reasonable: 16 slots for automation of up to 64 parameters. 71 72 73 At the level of a Zyn master file (.xmz) the automation slots 74 can be bound to MIDI CCs; loading the file will reload the midi bindings. 75 Zyn MIDI-learn files (.xlz) can store the MIDI CC+Channel linkage to all 76 automation slots. 77 78 The Macros View 79 --------------- 80 81 image::macro_view.png[] 82 83 The Macro view shows: 84 85 . List of Slots 86 .. Slot state (active, inactive) - currently this button is disabled, all slots are always active 87 .. A "clear slot" button (the x) - removes all automations in the slot 88 .. Slot name - click name to edit 89 . Macro selector buttons 90 .. highlighted button is the slot currently selected 91 .. use these when macro learning to select which slot to add to 92 . Macro sliders - (green bars under names) 93 .. indicates current macro value 94 .. slide to adjust through the UI 95 . Learning Mode selectors 96 .. Normal Learn - each learned automation is added to the next available slot 97 .. Macro Learn - learned automations are added to the currently selected slot (if not full) 98 99 image::current_slot.png[] 100 Currently selected slot is selected/indicated with these buttons. 101 102 The selected macro shows: 103 104 . MIDI binding if any e.g. "Chan 2, CC 14" (or "None" or "Learning Queue N") 105 . 4 Automations 106 107 image::automation1.png[] 108 109 Each automation shows 110 111 . Parameter path/name - clicking a section of the path shows a dropdown menu allowing easy switching between parts, voices, engines, etc. 112 . Minimum, maximum, center value of parameter 113 . Graph of map function 114 .. X is the macro value 115 .. Y is value of parameter being automated 116 . Gain knob - adjust to change slope of map function 117 . Offset knob adjust to move map function up or down 118 . Remove button (X) - click to remove the automation 119 120 121 Workflow examples 122 ----------------- 123 124 Automating a parameter in plugin mode 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 126 127 . Learn mode should be set to Normal Learn (this is the default) 128 . Use CTRL or click the [Learn] button to start learning an automation 129 . Click on one or more controls (knobs/sliders/buttons) to assign them to 130 automation slots 131 .. After clicking, each control is allocated to the next free Master 132 automation slot 133 .. the automation slot is put into the unbound state (it can be put into 134 "MIDI learn" mode later. 135 . The automation can be adjusted in the automation view 136 137 Binding parameters to MIDI in standalone mode 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 139 140 . Learn mode should be set to Normal Learn (this is the default) 141 . Use CTRL or click the [Learn] button to start learning an automation 142 . Click on one or more controls (knobs/sliders/buttons) to assign them to 143 automation slots 144 .. After clicking, each control is allocated to the next free Master 145 automation slot 146 .. Each automation slot is then placed into the "MIDI learn" mode, watching for 147 the next unbound MIDI CC that arrives in standalone mode 148 (MIDI CCs are identified by Channel+CC# in Master automation slots) 149 . The user optionally sends CCs to be bound by wiggling the controls on their 150 physical (or virtual) MIDI device 151 . The automation can be adjusted in the automation view 152 153 Setting up a macro 154 ~~~~~~~~~~~~~~~~~~ 155 156 image::macro.png[] 157 A macro with 3 automations 158 159 . Enter the Macro view 160 . Select the Macro Learn button (the Normal Learn button will turn off) 161 . Select the macro slot you would like to add new automations to 162 . Hold CTRL or double click the [Learn] button to enter learn mode 163 . Click the parameter(s) that you wish to add the the macro slot 164 . To add parameters to another macro slot switch the currently selected 165 macro slot in the Macro view 166 167 Adjusting automation ranges 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 169 . Go to the macro view 170 . Find the right macro slot and automation 171 . Adjust gain 172 .. High gain will make the automation's parameter traverse the whole range of travel with just a little movement of the macro. 173 .. Low gain will make the automation's parameter travel less range through the knob than the knob in the UI 174 .. Negative gain makes the macro adjust the parameter down when the macro is turned up 175 . Adjust offset 176 .. This moves the automation's parameter range of travel up or down 177 . If an automation was unintentional the user can use the X button to remove that automation 178 179 Learning/changing MIDI CC bindings after loading an instrument/binding 180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 181 . Go to the [Macro] view 182 . Find the right macro slot and automation 183 . Single click on the MIDI CC widget 184 .. The automation switches to the "learning CC" state 185 . Wiggle some MIDI controller 186 . OR Double click on the MIDI CC widget 187 .. this shows a dialog to manually choose the channel and CC id 188 . The CC has been remapped 189 190 FAQ 191 --- 192 Q: Why only 4 automations to a slot? 193 194 A: Limiting it to only 4 allowed for an easier design in the UI. There is no 195 limitation in the software and if many users request more capability, we will 196 extend it to more. 197 198 199 Q: What happens if a single parameter is in multiple automation slots? 200 201 A: Currently the engine will set the parameter to the value from the macro that 202 was most recently changed. Future versions may allow for macro fusion to combine 203 multiple values in different ways. 204 205 206 Q: Why didn't you add _feature X_ 207 208 A: We love well documented feature requests. Please leave your idea in our bugtracker at https://sourceforge.net/p/zynaddsubfx/feature-requests/