commit 9a7548d2a5055d49784c36aedb37d3a351177e1c
parent 0722f70b03c306ea4d3ca0c7acd02f7b37cfe6d5
Author: ssj71 <ssjackson71@gmail.com>
Date: Mon, 17 Jul 2017 16:01:05 -0600
first draft of macro documentation
Diffstat:
1 file changed, 216 insertions(+), 0 deletions(-)
diff --git a/doc/automation-proposal/parameter-automation-documentation.txt b/doc/automation-proposal/parameter-automation-documentation.txt
@@ -0,0 +1,216 @@
+An Introduction to a Revised MIDI Learn/Automation System Within ZynAddSubFX
+============================================================================
+:author: Mark McCurry (diagrams by unfa)
+:toc:
+
+
+Motivation
+----------
+
+One of the major issues expressed by users around the time of the initial
+3.0.0 launch was that they were dissatisfied with automations when using
+ZynAddSubFX within their preferred VST host. This was a combination of:
+
+1. Hosts providing a poor workflow for sending MIDI CC events compared to VST
+ parameters
+2. Confusion with the use of MIDI learn within Zyn
+3. Issues regarding saving/loading parameters exposed through MIDI learn
+4. Parameter resolution for MIDI CCs
+5. Some parameters only produce updates on the next note
+
+This feature attempts to address points 1, 2, & 3. Issue 4 is a large undertaking
+but is expected to become complete for the 3.1.x release. Issue 5 is being fixed
+one set of parameters at a time and should be addressed in the 3.0.x series.
+
+Overview & Terminology
+----------------------
+
+The Macro System boils down to replacing the existing MIDI learn implementation
+with a series of 'slots' for parameter automation and automation
+macros.
+
+What is an automation?
+~~~~~~~~~~~~~~~~~~~~~~
+
+- A single parameter, e.g. the addsynth base frequency in part 1, kit 1
+- A gain and offset to adjust the range of values the automation will reach
+(e.g. -50 cents to +150 cents)
+- A mapping function (currently only linear, log, custom, etc coming soon)
+
+What is a macro?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A group of automations that get assigned to an automation slot
+
+All automations in the macro are operated together. Thus turning one knob on
+your MIDI controller or a single automation lane in a DAW can change up to 4.footnote[see <<FAQ>>] parameters
+at a time. Using the automation mappings allows for all the parameters to be adjusted
+in different amounts and/or directions, but they are all moved by actuating the macro.
+
+Macros are assembled by adding automations to an automation slot.
+
+What is an automation slot?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A set of one or more automations (a single macro)
+- An optional MIDI CC binding or plugin host automation
+
+There are global automation slots and instrument automation slots that can be saved
+and loaded independently. The automation slots which are exposed to VST/LV2 plugin
+hosts are:
+
+- Master Automation Slot 1..32
+- Instrument 1..4 Automation Slot 1..4
+
+NOTE:Instrument 5..16 have the same slots, but they are *NOT*
+exposed to LV2/VST hosts. They are only available for MIDI bindings.
+
+All global automation slots (and some instrument slots) will always be exposed to VST/LV2 hosts.
+This keeps the total number of parameters exposed to a host somewhat
+reasonable: 48 slots for automation of up to 192 parameters.
+
+image::automation.png[]
+
+At the level of a Zyn master file (.xmz) the automation slots
+can be bound to MIDI CCs; loading the file will reload the midi bindings.
+
+At the level of Zyn instrument files (.xiz) the automation slots can be saved
+without a MIDI binding; loading the instrument will reload the instrument macros,
+but the MIDI bindings (if any) will remain in the same instrument slots.
+
+Zyn MIDI-learn files (.xlz) can store the MIDI CC+Channel linkage to all
+automation (and macro) slots.
+
+image::automation-slot.png[]
+image::automation-slot2.png[]
+
+Automation Slots User Interface
+-------------------------------
+
+TODO: There are new buttons and stuff. Show me pictures
+
+.. The automation view is made up of two sub-views [Master Automation], &
+ [Part Automation]
+.. The [Part Automation] sub-view can be navigated via setting the active part in the
+ sidebar of zyn-fusion like other similar views
+.. The automation view shows:
+... MIDI binding if any e.g. "Chan 2, CC 14" (or "None" or "Learning...")
+... Parameter path + name (see unfa's convention) (perhaps the OSC address
+ via a hover over tooltip)
+... Minimum value*
+... Maximum value*
+... Log/Linear switch*
+... * => (optional until more floating point parameters are exposed)
+... Possible display of the current value with a horizontal slider to
+ control
+
+
+Workflow examples
+-----------------
+
+Automating a parameter in plugin mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+. Use CTRL or click the [Learn] button to start learning an automation
+. Click on one or more controls (knobs/sliders/buttons) to assign them to
+ automation slots
+.. After clicking, each control is allocated to the next free Master
+ automation slot
+.. the automation slot is put into the unbound state (it can be put into
+ "MIDI learn" mode later.
+. The automation can be adjusted in the automation view
+
+Binding parameters to MIDI in standalone mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The workflow is streamlined for using a global automation slot:
+
+. Use CTRL or click the [Learn] button to start learning an automation
+. Click on one or more controls (knobs/sliders/buttons) to assign them to
+ automation slots
+.. After clicking, each control is allocated to the next free Master
+ automation slot
+.. Each automation slot is then placed into the "MIDI learn" mode, watching for
+ the next unbound MIDI CC that arrives in standalone mode
+ (MIDI CCs are identified by Channel+CC# in Master automation slots)
+. The user optionally sends CCs to be bound by wiggling the controls on their
+ physical (or virtual) MIDI device
+. The automation can be adjusted in the automation view
+
+Learning a Macro Automation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+. Use double tap CTRL or double click the [Learn] button to start learning
+ an automation
+. Repeat the automation learning process, but all new parameters will be
+ applied to the same automation slot
+
+
+Adjusting automation ranges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+. Go to the [Automation] view
+. If the automation slot is an instrument slot, the instrument subview can be selected
+ with the numbers in the left column, just as when navigating between parts
+. Find the right automation slot and automation
+. Adjust gain
+.. High gain will make the macro traverse the whole range of travel with just a little movement of the knob.
+.. Low gain will make the macro travel less range than the knob in the UI
+.. Negative gain makes the macro adjust the parameter down when the macro is turned up
+. Adjust offset
+.. This moves the macro's range of travel for the parameter up or down
+. If an automation was unintentional the user can use a handle widget on
+ the left side of the automation to delete it, or drag it to another
+ slot
+
+Learning/changing MIDI CC bindings after loading an instrument/binding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+. Go to the [Automation] view
+. Go to the [Master Automation] or [Part Automation] subview
+. Find the right automation slot and automation
+. Single click on the MIDI CC widget
+.. The automation switches to the "learning CC" state
+. Wiggle some MIDI controller
+. OR Double click on the MIDI CC widget
+.. this shows a dialog to manually choose the channel and CC id
+. The CC has been remapped
+. If binding is undesired a slot in learning state can be clicked on to
+ disable learning a MIDI mapping (good option for VST/LV2 use)
+
+How does this differ from the 3.0.0 workflow?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The MIDI CC mapping cannot be remapped without learning and unlearning
+currently.
+
+
+Making Slight Changes to an Automation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It may make sense as an advanced functionality to allow changing what a
+parameter has been bound to (e.g. voice 1 volume vs voice 3 volume) with a
+dropdown.
+
+image::automation-changes.png[]
+
+Organizing Macro Slots
+~~~~~~~~~~~~~~~~~~~~~~
+TODO
+
+Adding Onto An Existing Macro Automation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+TODO
+
+FAQ
+---
+Q: Why only 4 automations to a slot?
+A: Limiting it to only 4 allowed for an easier design in the UI. There is no
+limitation in the software and if many users request more capability, we will
+extend it to more.
+
+Q: What happens if a single parameter is in multiple automation slots?
+A: Currently the engine will set the parameter to the value from the macro that
+was most recently changed. Future versions may allow for macro fusion to combine
+multiple values in different ways.
+
+Q: Why didn't you add _feature X_
+A: We love well documented feature requests. Please leave your idea in our bugtracker at https://sourceforge.net/p/zynaddsubfx/feature-requests/
