<p class="note">
Gain mode can also be set with <em>/set_surface/gainmode gainmode.</em>
</p>
+
+<h2>Querying Ardour for information</h2>
+<p>
+ The control Surface may wish to control the type a frequency of
+ updates it receives. It can do this with querying commands. See: <a
+ href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a>
+</p>
<h2>List of OSC messages</h2>
<p class="note">
<dd>where <em>position</em> is a float ranging from 0 to 1 representing the desired pan position of the track</dd>
<dt><kbd class="osc">/strip/pan_stereo_width <em>ssid</em> <em>width</em></kbd></dt>
<dd>where <em>width</em> is a float ranging from 0 to 1 representing the desired pan width of the track</dd>
- <dt><kbd class="osc">/strip/plugin/parameter <em>ssid</em> <em>piid</em> <em>param</em> <em>value</em></kbd></dt>
- <dd>where <em>piid</em> = nth Plugin, <em>param</em> = nth param, <em>value</em>
- is a float ranging from 0 to 1 representing the desired parameter value</dd>
- <dt><kbd class="osc">/strip/send/gain", <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></dt>
+ <dt><kbd class="osc">/strip/send/gain <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></dt>
<dd>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</dd>
- <dt><kbd class="osc">/strip/send/fader", <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></dt>
+ <dt><kbd class="osc">/strip/send/fader <em>ssid</em> <em>sendid</em> <em>send_gain</em></kbd></dt>
<dd>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</dd>
+ <dt><kbd class="osc">/strip/send/enable <em>ssid</em> <em>sendid</em> <em>state</em></kbd></dt>
+ <dd>where <em>sendid</em> = nth_send, <em>state</em> is 1 for enabled and 0 for disabled</dd>
+ <dt><kbd class="osc">/strip/list </kbd></dt>
+ <dd>see: <a href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a></dd>
+ <dt><kbd class="osc">/strip/sends <em>ssid</em></kbd></dt>
+ <dd>see: <a href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a></dd>
+ <dt><kbd class="osc">/strip/receives <em>ssid</em></kbd></dt>
+ <dd>see: <a href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a></dd>
+ <dt><kbd class="osc">/strip/plugin/list <em>ssid</em></kbd></dt>
+ <dd>see: <a href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a></dd>
+ <dt><kbd class="osc">/strip/plugin/descriptor <em>ssid</em></kbd></dt>
+ <dd>see: <a href="/using-control-surfaces/controlling-ardour-with-osc/querying-ardour-with-osc/">
+ Querying Ardour with OSC.</a></dd>
+ <dt><kbd class="osc">/strip/plugin/reset <em>ssid</em> <em>piid</em> </kbd></dt>
+ <dd>where <em>piid</em> = nth Plugin, will reset all values to the plugin's original values</dd>
+ <dt><kbd class="osc">/strip/plugin/activate <em>ssid</em> <em>piid</em> </kbd></dt>
+ <dd>where <em>piid</em> = nth Plugin, will set the plugin's state to active</dd>
+ <dt><kbd class="osc">/strip/plugin/deactivate <em>ssid</em> <em>piid</em> </kbd></dt>
+ <dd>where <em>piid</em> = nth Plugin, will set the plugin's state to inactive</dd>
+ <dt><kbd class="osc">/strip/plugin/parameter <em>ssid</em> <em>piid</em> <em>param</em> <em>value</em></kbd></dt>
+ <dd>where <em>piid</em> = nth Plugin, <em>param</em> = nth param, <em>value</em>
+ is a float ranging from 0 to 1 representing the desired parameter value</dd>
+ <dt><kbd class="osc">/strip/name <em>ssid</em> <em>name</em></kbd></dt>
+ <dd>where <em>name</em> is a string for the desired name of the track</dd>
</dl>
<h3>Selected Strip Operations</h3>
<p>
Feedback from the Ardour to the the control surface is very useful for
a number of things. Motor faders need to know where the the track
they have been attached to is at before they were assigned otherwise
- they will jump to where the local fader is. Likewise, the buttons on
- each strip need to know what there value is so they can light there LED
- correctly. Transport controls should let you know if they are active
- too. This is what feedback is all about.
+ the DAW fader will jump to where the controller fader is. Likewise,
+ the buttons on each strip need to know what their value is so they can
+ light their LED correctly. Transport controls should let you know if
+ they are active too. This is what feedback is all about.
</p>
<p>
Ardour does feedback by sending the same path back that is used to
<p>
The feedback does not have the same meaning as the control message.
- Rather, the feedback will be:
+ Where the button release sent to Ardour will be ignored and has no
+ meaning. Both states have meaning in feedback to the controller.
+ The feedback will be:
</p>
<dl class="bindings">
That is with pan width at 100% (or -100%) there is no pan position
movement available.
</p>
+<p>
+ It may come as a surprise, but feedback often generates more network
+ traffic than control itself does. Some things are more obvious like
+ head position or meters. But even a simple button push like transport
+ start sends not only a signal to turn on the play LED, but also one to
+ turn off the stop LED, the Rewind LED, the Fast Forward LED and the
+ Loop LED. That is still minor, think instead of a surface refresh
+ such as happens when the surface is first connected and then most of
+ that happens every time the fader strips are banked. This is why
+ feedback is enabled in sections so that as little feedback as is
+ actually needed is sent. This is also a consideration if the surface
+ is connected via wifi.
+</p>
<h2>List of OSC feedback messages</h2>
<h3>Feedback only</h3>
<li>
64 - Monitor.
</li>
+ <li>
+ 128 - Audio Aux.
+ </li>
<li>
256 - Selected.
</li>
on a group or a set of user selected strips. Hidden shows strips the
GUI has hidden.
</p>
+<p class-"note">
+ Audio Aux? say what? I am sure most people will have noticed that they
+ can find no <em>Aux</em> strips in the Ardour mixer. There are none.
+ There are buses that can be used a number of ways. From analog days,
+ in OSC a bus is something that gets used as a sub mix before ending up
+ going to Master. An auxiliary bus is used like a separate mixer and
+ it's output goes outside the program or computer to be used as:
+ a monitor mix, a back up recording, or what have you. In OSC where
+ controller strips may be limited, it may be useful not to use up a
+ strip for an aux that is not really a part of the mix. It is also
+ useful to get a list of only aux buses if the control surface is a
+ phone used to provide talent monitor mix control on stage. Each
+ performer would be able to mix their own monitor. The user is free
+ to enable both buses and auxes if they would prefer.
+</p>
<h3>feedback</h3>
<p>Feedback is an integer made up of bits. The easy way to
</p>
<h2>Dialog settings</h2>
<h3>OSC setup tab</h3>
+<p>
+<img alt="the OSC configuration dialog"
+ src="/images/osc-dialog.png">
+</p>
<h4>Connection:</h4>
<p>
This field is informational only. It shows where Ardour will receive
so having correct defaults allows one "Connect" button rather than 4.
</p>
<h3>Default Strip Types tab</h3>
+<p>
+<img alt="the Default Strip Types tab"
+ src="/images/osc-strip-types.png">
+</p>
<p>
This allows selecting which of Ardour's mixer strips will be available
for control. The Factory default is all strips except master, monitor
controlled by a VCA are hidden, but one of those tracks needs a tweak.
</p>
<h3>Default Feedback tab</h3>
+<p>
+<img alt="the Default Feedback tab"
+ src="/images/osc-feedbackdefault.png">
+</p>
<p>
This allows setting up which controls provide feedback. The Factory
default is none. If the controller is unable to receive feedback, this
--- /dev/null
+---
+layout: default
+title: Querying Ardour with OSC
+---
+
+<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:
+</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>
+
+<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</li>
+ <li>Strip name</li>
+ <li>Number of inputs</li>
+ <li>Number of outputs</li>
+ <li>Muted (bool)</li>
+ <li>Soloed (bool)</li>
+ <li>Ssid (strip number)</li>
+ <li>Record enabled (bool)</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>
+ </ul>
+</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.
+</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 possition</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 conntected 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 possition</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>/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:
+ <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>
+ <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>
+ <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>
+ 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>3 - max unbound</li>
+ <li>4 - min unbound</li>
+ <li>5 - sample rate dependent</li>
+ <li>6 - toggled</li>
+ <li>7 - controllable</li>
+ </ul>
+</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.
+</p>
projects / ardour-manual-diverged / commitdiff
