d1c6c313f3
* 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).
210 lines
7.6 KiB
HTML
210 lines
7.6 KiB
HTML
|
|
<p>
|
|
In order to make a custom controller that knows what strips Ardour
|
|
has, the controller needs to be able to query Ardour for that
|
|
information. These set of commands are for smarter control surfaces
|
|
That have the logic to figure out what to do with the information.
|
|
These are not of value for mapped controllers like touchOSC and
|
|
friends. The controller will need to send these queries to Ardour
|
|
as often as it needs this information. It may well make sense to use
|
|
regular feedback for things that need to be updated often such as
|
|
position or metering.
|
|
Here are the commands used to query Ardour: (added in Ardour 5.5)
|
|
</p>
|
|
|
|
<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>
|
|
<tr><th><kbd class="osc">/surface/list</kbd></th>
|
|
<td>Print a list of known surfaces and Link Sets to the log window.</td></tr>
|
|
</table>
|
|
|
|
<h3>A list of strips</h3>
|
|
|
|
<p>
|
|
<code>/strip/list</code> asks Ardour for a list of strips that the
|
|
current session has. Ardour replies with a message for each
|
|
strip with the following information:
|
|
<ul>
|
|
<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>FB - Foldback bus</li>
|
|
<li>V - VCA</li>
|
|
</ul>
|
|
<li>Strip name</li>
|
|
<li>Number of inputs</li>
|
|
<li>Number of outputs</li>
|
|
<li>Muted</li>
|
|
<li>Soloed</li>
|
|
<li>Ssid (strip number)</li>
|
|
<li>Record enabled</li>
|
|
</ul>
|
|
After all the strip messages have been sent, one final message is
|
|
sent with:
|
|
<ul>
|
|
<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 its 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
|
|
responsibility to deal with this.
|
|
</p>
|
|
|
|
<h3>A list of sends</h3>
|
|
<p>
|
|
<code>/strip/sends <em>ssid</em></code> asks Ardour for a list of
|
|
sends for strip number ssid. The reply is sent back to the
|
|
controller as one message with the following information:
|
|
<ul>
|
|
<li>Ssid that information is for</li>
|
|
<li>Each send's information:</li>
|
|
<ul>
|
|
<li>The send's target bus ssid</li>
|
|
<li>The send's target bus name</li>
|
|
<li>The send id for this strip</li>
|
|
<li>The send gain as a fader position</li>
|
|
<li>The Send's enable state</li>
|
|
</ul>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
The controller can tell how many sends there are from the number of
|
|
parameters as each send has 5 parameters and there is one extra for
|
|
ssid.
|
|
</p>
|
|
|
|
<h3>A list if tracks that send audio to a bus</h3>
|
|
<p>
|
|
<code>/strip/receives <em>ssid</em></code> will return a list of
|
|
tracks that have sends to the bus at the ssid. The reply will
|
|
contain the following information for each track connected to this
|
|
bus:
|
|
<ul>
|
|
<li>The ssid of the track sending</li>
|
|
<li>The name of the sending track</li>
|
|
<li>The id of the send at that track</li>
|
|
<li>It's gain in fader position</li>
|
|
<li>The send's enable state</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<h3>A list of plug-ins for strip</h3>
|
|
<p>
|
|
<code>/strip/plugin/list <em>ssid</em></code> will return a list of
|
|
plug-ins that strip ssid has. The reply will contain the following
|
|
information:
|
|
<ul>
|
|
<li>Ssid that information is for</li>
|
|
<li>Each plugin's information:</li>
|
|
<ul>
|
|
<li>The plug-in's id</li>
|
|
<li>The plug-in's name</li>
|
|
</ul>
|
|
</ul>
|
|
</p>
|
|
|
|
<h3>A list of a plug-in's parameters</h3>
|
|
<p>
|
|
<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 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 parameter id for the plug-in</li>
|
|
<li>The plug-in parameter's name</li>
|
|
<li>Information about that parameter:</li>
|
|
<ul>
|
|
<li>A bitset of flags (see below)</li>
|
|
<li>Data type</li>
|
|
<li>Minimum value</li>
|
|
<li>Maximum value</li>
|
|
<li>The number of scale points</li>
|
|
<li>zero or more scale points of one value and one string each</li>
|
|
<li>The current parameter value</li>
|
|
</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:
|
|
<ul>
|
|
<li>Ssid of the strip the plugin 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—enumeration</li>
|
|
<li>1—integer step</li>
|
|
<li>2—logarithmic</li>
|
|
<li>5—sample rate dependent</li>
|
|
<li>6—toggled</li>
|
|
<li>7—controllable</li>
|
|
<li>8—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. For simpler
|
|
access to plug-ins, the /select/plugin/ set of commands will handle most
|
|
needs.
|
|
</p>
|
|
<h3>Obtaining a list of surfaces Ardour knows about</h3>
|
|
<p>
|
|
Ardour can work with more than one OSC control surface at a time.
|
|
Sometimes it is useful to know the information stored about all
|
|
surfaces. Sending <code>/surface/list</code> from any surface or selecting:
|
|
<kbd class="menu">Print surface information to Log window</kbd> from
|
|
the <kbd class="menu">Debug</kbd> dropdown in the OSC setup dialog,
|
|
will list all the information Ardour uses to calculate the feedback
|
|
it sends. The Log window can be opened from the menu with
|
|
<kbd class="option">Window > Log</kbd>.
|
|
This would be useful information to include with any OSC
|
|
related Bug report. The output is printed in this format:
|
|
</p>
|
|
<p>
|
|
<img alt="Surface Output"
|
|
src="/images/osc-surface-log.png">
|
|
</p>
|
|
|