OSC: plugin descriptors are now sent in multiple messages.

[ardour-manual] / include / osc58-querying-ardour.html

diff --git a/include/osc58-querying-ardour.html b/include/osc58-querying-ardour.html
index 20de95d449402823fa67d2c8b609a67d52b4c123..fa2a6f9dd02df26f167b86a44f392acdaf131f8c 100644 (file)
--- a/include/osc58-querying-ardour.html
+++ b/include/osc58-querying-ardour.html
@@ -12,18 +12,20 @@
   Here are the commands used to query Ardour: (added in Ardour 5.5)
 </p>
 
-<dl class="bindings">
-  <dt><kbd class="osc">/strip/list</kbd></dt>
-  <dd>Ask for a list of strips</dd>
-  <dt><kbd class="osc">/strip/sends <em>ssid</em></kbd></dt>
-  <dd>Asks for a list of sends on the strip <em>ssid</em></dd>
-  <dt><kbd class="osc">/strip/receives <em>ssid</em></kbd></dt>
-  <dd>Asks for a list of tracks that have sends to the strip <em>ssid</em> points to</dd>
-  <dt><kbd class="osc">/strip/plugin/list <em>ssid</em></kbd></dt>
-  <dd>Asks for a list of plug-ins for strip <em>ssid.</em></dd>
-  <dt><kbd class="osc">/plugin/descriptor <em>ssid</em> <em>piid</em></kbd></dt>
-  <dd>Asks for a list of descriptors for plug-in <em>piid</em> on strip <em>ssid</em></dd>
-</dl>
+<table class="dl">
+  <tr><th><kbd class="osc">/strip/list</kbd></th>
+  <td>Ask for a list of strips</td></tr>
+  <tr><th><kbd class="osc">/strip/sends <em>ssid</em></kbd></th>
+  <td>Asks for a list of sends on the strip <em>ssid</em></td></tr>
+  <tr><th><kbd class="osc">/strip/receives <em>ssid</em></kbd></th>
+  <td>Asks for a list of tracks that have sends to the strip <em>ssid</em> points to</td></tr>
+  <tr><th><kbd class="osc">/strip/plugin/list <em>ssid</em></kbd></th>
+  <td>Asks for a list of plug-ins for strip <em>ssid.</em></td></tr>
+  <tr><th><kbd class="osc">/strip/plugin/descriptor <em>ssid</em> <em>piid</em></kbd></th>
+  <td>Asks for a list of descriptors for plug-in <em>piid</em> on strip <em>ssid</em></td></tr>
+  <tr><th><kbd class="osc">/set_surface</kbd></th>
+  <td>Ask for the current surface setting. Reply is in the same form as setting the surface would be.</td></tr>
+</table>
 
 <h3>A list of strips</h3>
 
@@ -32,14 +34,22 @@
   current session has. Ardour replies with a message for each
   strip with the following information:
   <ul>
-    <li>Strip type</li>
+    <li>Strip type - One of:</li>
+    <ul>
+               <li>AT - Audio Track</li>
+               <li>MT - MIDI Track</li>
+               <li>B - Audio Bus</li>
+               <li>MB - MIDI bus</li>
+               <li>AX - Aux bus</li>
+               <li>V - VCA</li>
+    </ul>
     <li>Strip name</li>
     <li>Number of inputs</li>
     <li>Number of outputs</li>
-    <li>Muted (bool)</li>
-    <li>Soloed (bool)</li>
+    <li>Muted</li>
+    <li>Soloed</li>
     <li>Ssid (strip number)</li>
-    <li>Record enabled (bool)</li>
+    <li>Record enabled</li>
   </ul>
   After all the strip messages have been sent, one final message is
   sent with:
@@ -47,8 +57,21 @@
     <li>The text <code>end_route_list</code></li>
     <li>The session frame rate</li>
     <li>The last frame number of the session</li>
+    <li>Monitor section present</li>
   </ul>
 </p>
+<p class="note">
+       The <code>/set_surface</code> should be set before this is called. That way
+       The right set of strips will be sent in return (though the default is good
+       for most uses) and feedback will start correctly.
+</p>
+<p>
+  If the surface is using <code>/strip/list</code>, the surface needs to know
+  if the strips have changed. This would be true if a strip gets moved, created or
+  deleted. When this happens Ardour sends <code>/strip/list</code> to the surfaces
+  that have previously requested a <code>/strip/list</code>. This lets the
+  surface know that it's list of strips is no longer valid.
+</p>
 <p class="note">A bus will not have a record enable and so a bus message
   will have one less parameter than a track. It is the controllers
   responsability to deal with this.
@@ -109,17 +132,17 @@
 
 <h3>A list of a plug-in's parameters</h3>
 <p>
-  <code>/plugin/descriptor <em>ssid</em> <em>piid</em></code> will
+  <code>/strip/plugin/descriptor <em>ssid</em> <em>piid</em></code> will
   return the plug-in parameters for ppid plug-in on the ssid strip. The
-  reply will contain the following information:
+  reply will be sent as a number of messages, one for each parameter.
+  Each message will contain the following information:
   <ul>
     <li>Ssid of the strip the plug-in is in</li>
     <li>The plug-in id for the plug-in</li>
-    <li>The plug-in's name</li>
-    <li>Information about each parameter</li>
+    <li>The plug-in parameter id for the plug-in</li>
+    <li>The plug-in parameter's name</li>
+    <li>Information about that parameter:</li>
     <ul>
-      <li>The parameter id</li>
-      <li>The parameter's name</li>
       <li>A bitset of flags (see below)</li>
       <li>Data type</li>
       <li>Minimum value</li>
@@ -130,21 +153,32 @@
     </ul>
   </ul>
 </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:
+       <ul>
+         <li>Ssid of the strip the pulgin is in</li>
+         <li>The plug-in id for the plug-in</li>
+       </ul>
+</p>
 <p>
   The flag bitset above has been defined as (from lsb):
   <ul>
     <li>0&mdash;enumeration</li>
     <li>1&mdash;integer step</li>
     <li>2&mdash;logarithmic</li>
-    <li>3&mdash;max unbound</li>
-    <li>4&mdash;min unbound</li>
     <li>5&mdash;sample rate dependent</li>
     <li>6&mdash;toggled</li>
     <li>7&mdash;controllable</li>
+    <li>8&mdash;hidden</li>
   </ul>
+  Bits 3 and 4 are not used, they were max unbound and min unbound in
+  previous versions and always zero.
 </p>
 <p>
        While this seems complex, it is really not that bad. Minimum,
-       maximum and value will in most cases give you all you need.
+       maximum and value will in most cases give you all you need. For simpler
+       access to plug-ins, the /select/plugin/ set of commands will handle most
+       needs.
 </p>