Shamusworld >> Repos - ardour-manual-diverged/blob - include/querying-ardour-with-osc.html

   1 ---
   2 layout: default
   3 title: OSC&#58; Querying Ardour
   4 ---
   5
   6 <p>
   7   In order to make a custom controller that knows what strips Ardour
   8   has, the controller needs to be able to query Ardour for that
   9   information. These set of commands are for smarter control surfaces
  10   That have the logic to figure out what to do with the information.
  11   These are not of value for mapped controllers like touchOSC and
  12   friends. The controller will need to send these queries to ardour
  13   as often as it needs this information. It may well make sense to use
  14   regular feedback for things that need to be updated often such as
  15   position or metering.
  16   Here are the commands used to query Ardour:
  17 </p>
  18
  19 <dl class="bindings">
  20   <dt><kbd class="osc">/strip/list</kbd></dt>
  21   <dd>Ask for a list of strips</dd>
  22   <dt><kbd class="osc">/strip/sends <em>ssid</em></kbd></dt>
  23   <dd>Asks for a list of sends on the strip <em>ssid</em></dd>
  24   <dt><kbd class="osc">/strip/receives <em>ssid</em></kbd></dt>
  25   <dd>Asks for a list of tracks that have sends to the strip <em>ssid</em> points to</dd>
  26   <dt><kbd class="osc">/strip/plugin/list <em>ssid</em></kbd></dt>
  27   <dd>Asks for a list of plug-ins for strip <em>ssid.</em></dd>
  28   <dt><kbd class="osc">/plugin/descriptor <em>ssid</em> <em>piid</em></kbd></dt>
  29   <dd>Asks for a list of descriptors for plug-in <em>piid</em> on strip <em>ssid</em></dd>
  30 </dl>
  31
  32 <h3>A list of strips</h3>
  33
  34 <p>
  35   <code>/strip/list</code> asks Ardour for a list of strips that the
  36   current session has. Ardour replies with a message for each
  37   strip with the following information:
  38   <ul>
  39     <li>Strip type</li>
  40     <li>Strip name</li>
  41     <li>Number of inputs</li>
  42     <li>Number of outputs</li>
  43     <li>Muted (bool)</li>
  44     <li>Soloed (bool)</li>
  45     <li>Ssid (strip number)</li>
  46     <li>Record enabled (bool)</li>
  47   </ul>
  48   After all the strip messages have been sent, one final message is
  49   sent with:
  50   <ul>
  51     <li>The text <code>end_route_list</code></li>
  52     <li>The session frame rate</li>
  53     <li>The last frame number of the session</li>
  54   </ul>
  55 </p>
  56 <p class="note">A bus will not have a record enable and so a bus message
  57   will have one less parameter than a track. It is the controllers
  58   responsability to deal with this.
  59 </p>
  60
  61 <h3>A list of sends</h3>
  62 <p>
  63   <code>/strip/sends <em>ssid</em></code> asks Ardour for a list of
  64   sends for strip number ssid. The reply is sent back to the
  65   controller as one message with the following information:
  66   <ul>
  67     <li>Ssid that information is for</li>
  68     <li>Each send's information:</li>
  69     <ul>
  70       <li>The send's target bus ssid</li>
  71       <li>The send's target bus name</li>
  72       <li>The send id for this strip</li>
  73       <li>The send gain as a fader possition</li>
  74       <li>The Send's enable state</li>
  75     </ul>
  76   </ul>
  77 </p>
  78 <p>
  79   The controller can tell how many sends there are from the number of
  80   parameters as each send has 5 parameters and there is one extra for
  81   ssid.
  82 </p>
  83
  84 <h3>A list if tracks that send audio to a bus</h3>
  85 <p>
  86   <code>/strip/receives <em>ssid</em></code> will return a list of
  87   tracks that have sends to the bus at the ssid. The reply will
  88   contain the following information for each track conntected to this
  89   bus:
  90   <ul>
  91     <li>The ssid of the track sending</li>
  92     <li>The name of the sending track</li>
  93     <li>The id of the send at that track</li>
  94     <li>It's gain in fader possition</li>
  95     <li>The send's enable state</li>
  96   </ul>
  97 </p>
  98
  99 <h3>A list of plug-ins for strip</h3>
 100 <p>
 101   <code>/strip/plugin/list <em>ssid</em></code> will return a list of
 102   plug-ins that strip ssid has. The reply will contain the following
 103   information:
 104   <ul>
 105     <li>Ssid that information is for</li>
 106     <li>Each plugin's information:</li>
 107     <ul>
 108       <li>The plug-in's id</li>
 109       <li>The plug-in's name</li>
 110     </ul>
 111   </ul>
 112 </p>
 113
 114 <h3>A list of a plug-in's parameters</h3>
 115 <p>
 116   <code>/plugin/descriptor <em>ssid</em> <em>piid</em></code> will
 117   return the plug-in parameters for ppid plug-in on the ssid strip. The
 118   reply will contain the following information:
 119   <ul>
 120     <li>Ssid of the strip the plug-in is in</li>
 121     <li>The plug-in id for the plug-in</li>
 122     <li>The plug-in's name</li>
 123     <li>Information about each parameter</li>
 124     <ul>
 125       <li>The parameter id</li>
 126       <li>The parameter's name</li>
 127       <li>A bitset of flags (see below)</li>
 128       <li>Data type</li>
 129       <li>Minimum value</li>
 130       <li>Maximum value</li>
 131       <li>The number of scale points</li>
 132       <li>zero or more scale points of one value and one string each</li>
 133       <li>The current parameter value</li>
 134     </ul>
 135   </ul>
 136 </p>
 137 <p>
 138   The flag bitset above has been defined as (from lsb):
 139   <ul>
 140     <li>0 - enumeration</li>
 141     <li>1 - integer step</li>
 142     <li>2 - logarithmic</li>
 143     <li>3 - max unbound</li>
 144     <li>4 - min unbound</li>
 145     <li>5 - sample rate dependent</li>
 146     <li>6 - toggled</li>
 147     <li>7 - controllable</li>
 148   </ul>
 149 </p>
 150 <p>
 151         While this seems complex, it is really not that bad. Minimum,
 152         maximum and value will in most cases give you all you need.
 153 </p>