From d1c6c313f3458fa97785f0a8493129c6b81d5b66 Mon Sep 17 00:00:00 2001 From: Matthijs Kooijman Date: Tue, 2 Jul 2024 09:13:07 +0200 Subject: [PATCH] OSC: Make plugin documentation complete (#266) * 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). --- .../osc58-controlling-ardour-with-osc.html | 80 ++++++++++++++++--- ...osc58-feedback-and-strip-types-values.html | 3 +- include/osc58-feedback.html | 28 ++++++- include/osc58-querying-ardour.html | 6 ++ 4 files changed, 103 insertions(+), 14 deletions(-) diff --git a/include/osc58-controlling-ardour-with-osc.html b/include/osc58-controlling-ardour-with-osc.html index 514cd83b..08d126e3 100644 --- a/include/osc58-controlling-ardour-with-osc.html +++ b/include/osc58-controlling-ardour-with-osc.html @@ -44,6 +44,9 @@
  • Selected Strip Operations
    • +
  • + Selected Plugin Operations +
  • Menu actions
    • @@ -113,7 +116,7 @@ here"/>
  • Feedback: 0 — All off.
  • Fader Mode: 0 — gain in dB (not relevant with feedback off)
  • Send Page Size: 0 — No Send Paging.
    • -
  • Plugin Page Size: 0 — No Plugin Paging.
    • +
  • Plugin Page Size: 0 — No Plugin (parameter) Paging.
  • reply port: 8000 — control surface will receive feedback on port 8000
  • Link set: 0 — no linking for this control surface
  • Link ID: 0 — no link ID
    • @@ -306,6 +309,14 @@ here"/> href="@@osc58-parameter-types"> Parameter Types in OSC.

    +

    + 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: Feedback + for more information. +

    Master or Global messages

    Transport Control

    @@ -706,22 +717,16 @@ here"/> where position is a float ranging from 0 to 1 representing the desired front to back position of the track /select/pan_lfe_control value where value is a float ranging from 0 to 1 representing the desired LFE control value for the track - /select/send_gain, sendid send_gain + /select/send_gain sendid send_gain where sendid = nth_send, send_gain is a float ranging from -193 to +6 representing the desired gain in dB for the send - /select/send_fader, sendid send_gain + /select/send_fader sendid send_gain where sendid = nth_send, send_gain is a float ranging from 0 to 1 representing the desired position for the send as a fader - /select/send_enable, sendid state + /select/send_enable sendid state where sendid = nth_send, state is 1 for enabled and 0 for disabled - /select/send_page, delta + /select/send_page delta where delta is an int or float selecting another send as a delta from the current send. - /select/plugin_page, delta - where delta is an int or float selecting another plugin parameter as a delta from the current parameter. - /select/plugin/activate, state - where state is an int or float with the desired state of the current plugin activation.(new Ardour 6.0) - /select/plugin/parameter, plugin parameter value - where plugin = nth plugin, parameter = nth parameter and value is a float from 0 to 1

    /select/send_page and /select/plugin_page may be used @@ -729,6 +734,56 @@ here"/> for page up and a switch with a value of -1 for page down. An encoder can be used as well. (these commands were added in Ardour version 5.10)

    + +

    Selected Plugin Operations

    +

    + 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 /set_surface. +

    +

    + 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. +

    + + + + + + + + + +
    /select/plugin deltawhere delta is an int or float selecting another plugin as a delta from the currently selected plugin index.
    /select/plug_page up_or_downwhere up_or_down is 1 for page up or -1 for page down (0 is ignored).
    /select/plugin/activate y/nwhere y/n is 1 for activating and 0 for deactivating the selected plugin. (new Ardour 6.0)
    + /select/plugin/parameter piid paid value
    + /select/plugin/parameter paid value
    + /select/plugin/parameter/piid/paid value
    + /select/plugin/parameter/paid value +     		+ where piid = nth plugin, paid = nth + parameter and value is a float from 0 to 1. If + piid is omitted, the currently selected plugin is used. + Otherwise, the specified plugin is made the selected plugin and its + parameter modified.
    + Feedback messages omit the piid argument. The paid + 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 + Calculating Feedback and Strip-types Values. +
    +

    + The paid argument is specified as a 1-based index into the list + of controllable parameters only (as specified by the + controllable flag in the + /strip/plugin/descriptor query message, + skipping non-controllable-only parameters). +

    +

    Using groups with strip and select (new for Ardour 6.0)

    No grouping will occur unless use_group is set either @@ -806,6 +861,9 @@ here"/> option is to reselect the custom set of strips with /strip/custom/mode mode.

    +

    Controlling plugins

    +

    +

    Menu actions

    diff --git a/include/osc58-feedback-and-strip-types-values.html b/include/osc58-feedback-and-strip-types-values.html index f1a44555..7e8e012c 100644 --- a/include/osc58-feedback-and-strip-types-values.html +++ b/include/osc58-feedback-and-strip-types-values.html @@ -156,7 +156,8 @@ 2: Variable control values for strips.

  • - 4: Send SSID as path extension. + 4: Send SSID (or for `/select/*` messages the send or + plugin parameter id) as path extension.
  • 8: heartbeat to surface. diff --git a/include/osc58-feedback.html b/include/osc58-feedback.html index cf741ed9..1b69d5b2 100644 --- a/include/osc58-feedback.html +++ b/include/osc58-feedback.html @@ -236,10 +236,10 @@ where invert is a bool/int representing the actual polarity of the track /select/pan_stereo_width width where width is a float ranging from 0 to 1 representing the actual pan width of the track - /select/send_gain", sendid send_gain + /select/send_gain sendid send_gain where sendid = nth_send, send_gainis a float ranging from -193 to +6 representing the actual gain in dB for the send - /select/send_fader", sendid send_gain + /select/send_fader sendid send_gain where sendid = nth_send, send_gainis a float ranging from 0 to 1 representing the actual position for the send as a fader /select/send_name sendid send_name @@ -289,6 +289,30 @@ state 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) + +

    Selected Plugin

    +

    +Feedback about plugin parameters is sent only for a single, selected +plugin (parameters for other plugins and other strips can be changed +with /select/plugin/parameter and /strip/plugin/parameter, 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. +

    + + + + + + + + +
    /select/plugin/name namewhere name is a string with the name of the selected + plugin
    /select/plugin/parameter/name paid namewhere name is a string with the name of the specified + parameter.
    /select/plugin/parameter paid valuewhere value is a float ranging from 0 to 1 representing + the current parameter value.
    +

    Menu actions

    There is no feedback for Menu actions. diff --git a/include/osc58-querying-ardour.html b/include/osc58-querying-ardour.html index c94ec100..c9ad1aec 100644 --- a/include/osc58-querying-ardour.html +++ b/include/osc58-querying-ardour.html @@ -155,6 +155,12 @@

    +

    +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 controllable +parameters only (as specified by the controllable flag, see below). +

    After all the parameters have been sent this way, one final message" /strip/plugin/descriptor_end is sent with these parameters: