OSC: Document missing feedback configuration bits (#267)

* OSC: Clarify control messages are also sent as feedback

This is already mentioned on the feedback page, but mentioning it above
the list of control messages helps interpreting that list.

* OSC: Remove errant commas in addresses

The rest of the docs do not use commas to separate the address from
arguments, so remove them here. These commas seem to have been
introduced first in commit 1138f1d (OSC: update OSC docs.) and were
probably copy-pasted into docs added after that.

* OSC: Fix and complete plugin operations and feedback

This makes the documentation complete by adding missing messages,
clarifying some existind documenation and fixing `/select/plug_page`
(address and parameter description were incorrect).

include/osc58-controlling-ardour-with-osc.html

@@ -44,6 +44,9 @@
   <li>
     <a href="#osc_select">Selected Strip Operations</a>
   </li>
+  <li>
+    <a href="#osc_plugins">Selected Plugin Operations</a>
+  </li>
   <li>
     <a href="#osc_menu">Menu actions</a>
   </li>
@@ -113,7 +116,7 @@ here</em>"/&gt;</kbd>
 	  <li><em>Feedback</em>: 0 &mdash; All off.</li>
 	  <li><em>Fader Mode</em>: 0 &mdash; gain in dB (not relevant with feedback off)</li>
 	  <li><em>Send Page Size</em>: 0 &mdash; No Send Paging.</li>
-	  <li><em>Plugin Page Size</em>: 0 &mdash; No Plugin Paging.</li>
+	  <li><em>Plugin Page Size</em>: 0 &mdash; No Plugin (parameter) Paging.</li>
 	  <li><em>reply port</em>: 8000 &mdash; control surface will receive feedback on port 8000</li>
 	  <li><em>Link set</em>: 0 &mdash; no linking for this control surface</li>
 	  <li><em>Link ID</em>: 0 &mdash; no link ID</li>
@@ -306,6 +309,14 @@ here</em>"/&gt;</kbd>
 	href="@@osc58-parameter-types">
 	Parameter Types in OSC.</a>
 </p>
+<p>
+	This list shows all messages that can be sent to Ardour to
+        control it. Most of these messages are also sent back as
+        feedback when the corresponding value changes. There exist
+        additional feedback-only messages, see: <a
+        href="@@osc58-feedback">Feedback</a>
+        for more information.
+</p>
 <h3 id="osc_global">Master or Global messages</h3>
 
 <h4  id="osc_transport">Transport Control</h4>
@@ -706,22 +717,16 @@ here</em>"/&gt;</kbd>
   <td>where <em>position</em> is a float ranging from 0 to 1 representing the desired front to back position of the track</td></tr>
   <tr><th><kbd class="osc">/select/pan_lfe_control <em>value</em></kbd></th>
   <td>where <em>value</em> is a float ranging from 0 to 1 representing the desired LFE control value for the track</td></tr>
-  <tr><th><kbd class="osc">/select/send_gain, <em>sendid</em> <em>send_gain</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_gain <em>sendid</em> <em>send_gain</em></kbd></th>
   <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
   ranging from -193 to +6 representing the desired gain in dB for the send</td></tr>
-  <tr><th><kbd class="osc">/select/send_fader, <em>sendid</em> <em>send_gain</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_fader <em>sendid</em> <em>send_gain</em></kbd></th>
   <td>where <em>sendid</em> = nth_send, <em>send_gain</em> is a float
   ranging from 0 to 1 representing the desired position for the send as a fader</td></tr>
-  <tr><th><kbd class="osc">/select/send_enable, <em>sendid</em> <em>state</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_enable <em>sendid</em> <em>state</em></kbd></th>
   <td>where <em>sendid</em> = nth_send, <em>state</em> is 1 for enabled and 0 for disabled</td></tr>
-  <tr><th><kbd class="osc">/select/send_page, <em>delta</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_page <em>delta</em></kbd></th>
   <td>where <em>delta</em> is an int or float selecting another send as a delta from the current send.</td></tr>
-  <tr><th><kbd class="osc">/select/plugin_page, <em>delta</em></kbd></th>
-  <td>where <em>delta</em> is an int or float selecting another plugin parameter as a delta from the current parameter.</td></tr>
-  <tr><th><kbd class="osc">/select/plugin/activate, <em>state</em></kbd></th>
-  <td>where <em>state</em> is an int or float with the desired state of the current plugin activation.(new Ardour 6.0)</td></tr>
-  <tr><th><kbd class="osc">/select/plugin/parameter, <em>plugin</em> <em>parameter</em> <em>value</em></kbd></th>
-  <td>where <em>plugin</em> = nth plugin, <em>parameter</em> = nth parameter and <em>value</em> is a float from 0 to 1</td></tr>
 </table>
 <p class="note">
 	<code>/select/send_page</code> and <code>/select/plugin_page</code> may be used
@@ -729,6 +734,56 @@ here</em>"/&gt;</kbd>
 	for page up and a switch with a value of <code>-1</code> for page down. An encoder
 	can be used as well. (these commands were added in Ardour version 5.10)
 </p>
+
+<h3 id="osc_plugins">Selected Plugin Operations</h3>
+<p>
+  These operations control the selected plugin on the selected strip.
+  Plugins and parameters are specified by their position in the list of
+  plugins and controllable parameters. Parameters are paged to allow accessing
+  all parameters on a surface with limited inputs, the plugin
+  (parameter) page size is configured with <kbd class="osc">/set_surface</kbd>.
+</p>
+<p>
+  When the selected strip is changed, the plugin in the same position in
+  the newly selected strip is made the selected plugin (even if it is
+  a different type of plugin). If the new strip has fewer plugins, the
+  last plugin is selected. If the new strip has no plugins, no plugin is
+  selected.
+</p>
+
+<table class="dl">
+  <tr><th><kbd class="osc">/select/plugin <em>delta</em></kbd></th>
+  <td>where <em>delta</em> is an int or float selecting another plugin as a delta from the currently selected plugin index.</td></tr>
+  <tr><th><kbd class="osc">/select/plug_page <em>up_or_down</em></kbd></th>
+  <td>where <em>up_or_down</em> is 1 for page up or -1 for page down (0 is ignored).</td></tr>
+  <tr><th><kbd class="osc">/select/plugin/activate <em>y/n</em></kbd></th>
+  <td>where <em>y/n</em> is 1 for activating and 0 for deactivating the selected plugin. (new Ardour 6.0)</td></tr>
+  <tr><th>
+      <kbd class="osc">/select/plugin/parameter <em>piid</em> <em>paid</em> <em>value</em></kbd><br/>
+      <kbd class="osc">/select/plugin/parameter <em>paid</em> <em>value</em></kbd><br/>
+      <kbd class="osc">/select/plugin/parameter/<em>piid</em>/<em>paid</em> <em>value</em></kbd><br/>
+      <kbd class="osc">/select/plugin/parameter/<em>paid</em> <em>value</em></kbd>
+  </th><td>
+    where <em>piid</em> = nth plugin, <em>paid</em> = nth
+    parameter and <em>value</em> is a float from 0 to 1. If
+    <em>piid</em> is omitted, the currently selected plugin is used.
+    Otherwise, the specified plugin is made the selected plugin and its
+    parameter modified.<br/>
+    Feedback messages omit the <em>piid</em> argument. The <em>paid</em>
+    is normally passed as an argument (second form) but can be put in
+    the path (last form) using the /set_surface/feedback state command.
+    See <a href="@@osc58-feedback-and-strip-types-values#feedback">
+    Calculating Feedback and Strip-types Values.</a>
+  </td></tr>
+</table>
+<p class="note">
+  The <em>paid</em> argument is specified as a 1-based index into the list
+  of <em>controllable</em> parameters only (as specified by the
+  controllable flag in the <a href="@@osc58-querying-ardour">
+  <kbd class="osc">/strip/plugin/descriptor</kbd> query message</a>,
+  skipping non-controllable-only parameters).
+</p>
+
 <h4 id="osc_groups">Using groups with strip and select (new for Ardour 6.0)</h4>
 <p class="note">
 	No grouping will occur unless <code>use_group</code> is set either
@@ -806,6 +861,9 @@ here</em>"/&gt;</kbd>
 	option is to reselect the custom set of strips with
 	<kbd class="osc">/strip/custom/mode <em>mode</em></kbd>.
 </p>
+<h4 id="osc_plugins_details">Controlling plugins</h4>
+<p>
+</p>
 
 <h3 id="osc_menu">Menu actions</h3>
 <p>

include/osc58-feedback-and-strip-types-values.html

@@ -156,7 +156,8 @@
 		2: Variable control values for strips.
 	</li>
 	<li>
-		4: Send SSID as path extension.
+		4: Send SSID (or for `/select/*` messages the send or
+		   plugin parameter id) as path extension.
 	</li>
 	<li>
 		8: heartbeat to surface.
@@ -193,6 +194,12 @@
  	<li>
 		16384: Use OSC 1.0 /reply instead of #reply
 	</li>
+	<li>
+		32768: Report 8x8 Trigger Grid status
+	</li>
+	<li>
+		65536: Report Mixer Scene status
+	</li>
   </ul>
 <p>
   So using a value of 19 (1 + 2 + 16) would turn on feedback for strip

include/osc58-feedback.html

@@ -236,10 +236,10 @@
   <td>where <em>invert</em> is a bool/int representing the actual polarity of the track</td></tr>
   <tr><th><kbd class="osc">/select/pan_stereo_width <em>width</em></kbd></th>
   <td>where <em>width</em> is a float ranging from 0 to 1 representing the actual pan width of the track</td></tr>
-  <tr><th><kbd class="osc">/select/send_gain", <em>sendid</em> <em>send_gain</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_gain <em>sendid</em> <em>send_gain</em></kbd></th>
   <td>where <em>sendid</em> = nth_send, <em>send_gain</em>is a float
   ranging from -193 to +6 representing the actual gain in dB for the send</td></tr>
-  <tr><th><kbd class="osc">/select/send_fader", <em>sendid</em> <em>send_gain</em></kbd></th>
+  <tr><th><kbd class="osc">/select/send_fader <em>sendid</em> <em>send_gain</em></kbd></th>
   <td>where <em>sendid</em> = nth_send, <em>send_gain</em>is a float
   ranging from 0 to 1 representing the actual position for the send as a fader</td></tr>
   <tr><th><kbd class="osc">/select/send_name <em>sendid</em> <em>send_name</em></kbd></th>
@@ -289,6 +289,30 @@
   <em>state</em> is an int that determines if the named VCA will control
   this strip. Note that this lists all VCAs in a session. (Ardour 6.0)</td></tr>
 </table>
+
+<h3>Selected Plugin</h3>
+<p>
+Feedback about plugin parameters is sent only for a single, selected
+plugin (parameters for other plugins and other strips can be changed
+with <kbd class="osc">/select/plugin/parameter</kbd> and <kbd
+class="osc">/strip/plugin/parameter</kbd>, but without feedback).
+Whenever the plugin (or strip) changes, the name and activation of the
+plugin and name and value of a number of its parameters (determined by
+the plugin page size) is sent as feedback.
+</p>
+
+<table class="dl">
+  <tr><th><kbd class="osc">/select/plugin/name <em>name</em></kbd></th>
+  <td>where <em>name</em> is a string with the name of the selected
+    plugin</td></tr>
+  <tr><th><kbd class="osc">/select/plugin/parameter/name <em>paid</em> <em>name</em></kbd></th>
+  <td>where <em>name</em> is a string with the name of the specified
+    parameter.</td></tr>
+  <tr><th><kbd class="osc">/select/plugin/parameter <em>paid</em> <em>value</em></kbd></th>
+  <td>where <em>value</em> is a float ranging from 0 to 1 representing
+    the current parameter value.</td></tr>
+</table>
+
 <h3>Menu actions</h3>
 <p class="note">
 	There is no feedback for Menu actions.

include/osc58-querying-ardour.html

@@ -155,6 +155,12 @@
     </ul>
   </ul>
 </p>
+<p class="note">
+The plug-in parameter id is the position in the full list of plugin
+paramaters, but messages for controlling parameter values and their
+feedback use the position in the list of <em>controllable</em>
+parameters only (as specified by the controllable flag, see below).
+</p>
 <p>
 	After all the parameters have been sent this way, one final message"
 	<code>/strip/plugin/descriptor_end</code> is sent with these parameters: