ardour
/
manual
13
0
Fork 0
Code Pull Requests Releases Activity

NO-OP: whitespace

This commit is contained in:
Len Ovens 2018-02-18 14:06:12 -08:00
parent cd424ba51a
commit f8e8f8db2f
5 changed files with 150 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
STYLE_GUIDE
View File

@ -50,6 +50,9 @@ Watch out for the ampersand "&" and angle brackets "<" and ">". They will
render your XHTML invalid, and must be replaced by their named entities
"&amp;", "&lt;", and "&gt;".
Keep line lengths within 108 characters so that additions or changes are easy to view in github pull requests.
Code examples that are supposed to be all one line are an exception in which case the <pre></pre> tag should be
used to to tell the browser to display the code as one line.
3. Custom classes
=================

116
include/lua-scripting.html
View File

@ -10,11 +10,12 @@ This Documentation is Work in Progress and far from complete. Also the documente
<h2 id="Preface">Preface</h2>
<p>
There are cases that Ardour cannot reasonably cater to with core functionality alone, either because they're session specific or user specific edge cases.
There are cases that Ardour cannot reasonably cater to with core functionality alone, either because they're session specific
or user specific edge cases.
</p><p>
Examples for these include voice-activate (record-arm specific tracks and roll transport depending on signal levels),
rename all regions after a specific timecode, launch an external application when a certain track is soloed, generate automation curves
or simply provide a quick shortcut for a custom batch operation.
rename all regions after a specific timecode, launch an external application when a certain track is soloed, generate
automation curves or simply provide a quick shortcut for a custom batch operation.
</p><p>
Cases like this call for means to extend the DAW without actually changing the DAW itself. This is where scripting comes in.
</p><p>
@ -24,15 +25,16 @@ Lua is a tiny and simple language which is easy to learn, yet allows for compreh
Lua is also a glue language it allows to tie existing component in Ardour together in unprecedented ways,
and most importantly Lua is one of the few scripting-languages which can be safely used in a real-time environment.
</p><p>
A good introduction to Lua is the book <a href="http://www.lua.org/pil/">Programming in Lua</a>. The first edition is available online,
but if you have the means buy a copy of the book, it not only helps to support the Lua project,
but provides for a much nicer reading and learning experience.
A good introduction to Lua is the book <a href="http://www.lua.org/pil/">Programming in Lua</a>. The first edition is
available online, but if you have the means buy a copy of the book, it not only helps to support the Lua project, but provides
for a much nicer reading and learning experience.
</p>
<h2 id="Overview">Overview</h2>
<p>
The core of Ardour is a real-time audio engine that runs and processes audio. One interfaces with an engine by sending it commands.
Scripting can be used to interact with or modify the active Ardour session, just like a user uses the Editor/Mixer GUI to modify the state or parameters of the session.
The core of Ardour is a real-time audio engine that runs and processes audio. One interfaces with an engine by sending it
commands. Scripting can be used to interact with or modify the active Ardour session, just like a user uses the Editor/Mixer
GUI to modify the state or parameters of the session.
</p><p>
Doing this programmatically requires some knowledge about the objects used internally.
Most Ardour C++ objects and their methods are directly exposed to Lua and one can call functions or modify variables:
@ -56,19 +58,22 @@ Most Ardour C++ objects and their methods are directly exposed to Lua and one ca
<p>
You may notice that there is only a small syntactic difference in this case.
While C++ requires recompiling the application for every change, Lua script can be loaded, written or modified while the application is running.
Lua also abstracts away many of the C++ complexities such as object lifetime, type conversion and null-pointer checks.
While C++ requires recompiling the application for every change, Lua script can be loaded, written or modified while the
application is running. Lua also abstracts away many of the C++ complexities such as object lifetime, type conversion and
null-pointer checks.
</p><p>
Close ties with the underlying C++ components is where the power of scripting comes from.
A script can orchestrate interaction of lower-level components which take the bulk of the CPU time of the final program.
</p>
</p><p>
At the time of writing Ardour integrates Lua 5.3.2: <a href="http://www.lua.org/manual/5.3/manual.html">Lua 5.3 reference manual</a>.
At the time of writing Ardour integrates Lua 5.3.2: <a href="http://www.lua.org/manual/5.3/manual.html">Lua 5.3 reference
manual</a>.
</p>
<h2 id="Integration">Integration</h2>
<p>
Like Control surfaces and the GUI, Lua Scripts are confined to certain aspects of the program. Ardour provides the framework and runs Lua (not the other way around).
Like Control surfaces and the GUI, Lua Scripts are confined to certain aspects of the program. Ardour provides the framework
and runs Lua (not the other way around).
</p>
<p>
In Ardour's case Lua is available:
@ -86,7 +91,8 @@ In Ardour's case Lua is available:
There are is also a special mode:
</p>
<table class="dl">
<tr><th>Commandline Tool</th><td>Replaces the complete Editor GUI, direct access to libardour (no GUI) from the commandline.<br/>
<tr><th>Commandline Tool</th><td>Replaces the complete Editor GUI, direct access to libardour (no GUI) from the
commandline.<br/>
<em>Be aware that the vast majority of complex functionality is provided by the Editor UI.</em></td></tr>
</table>
@ -115,9 +121,11 @@ Apart from scripts included directly with Ardour, this includes</p>
<h2 id="Script Layout">Script Layout</h2>
<ul>
<li>Every script must include an <code>ardour</code> descriptor table. Required fields are "Name" and "Type".</li>
<li>A script must provide a <em>Factory method</em>: A function with optional instantiation parameters which returns the actual script.</li>
<li>A script must provide a <em>Factory method</em>: A function with optional instantiation parameters which returns the
actual script.</li>
<li>[optional]: list of parameters for the "factory".</li>
<li>in case of DSP scripts, an optional list of automatable parameters and possible audio/midi port configurations, and a <code>dsp_run</code> function, more on that later.</li>
<li>in case of DSP scripts, an optional list of automatable parameters and possible audio/midi port configurations, and a
<code>dsp_run</code> function, more on that later.</li>
</ul>
@ -138,10 +146,12 @@ Apart from scripts included directly with Ardour, this includes</p>
</div>
<p>
The common part for all scripts is the "Descriptor". It's a Lua function which returns a table (key/values) with the following keys (the keys are case-sensitive):
The common part for all scripts is the "Descriptor". It's a Lua function which returns a table (key/values) with the following
keys (the keys are case-sensitive):
</p>
<table class="dl">
<tr><th>type [required]</th><td>one of "<code>DSP</code>", "<code>Session</code>", "<code>EditorHook</code>", "<code>EditorAction</code>" (the type is not case-sensitive)</td></tr>
<tr><th>type [required]</th><td>one of "<code>DSP</code>", "<code>Session</code>", "<code>EditorHook</code>",
"<code>EditorAction</code>" (the type is not case-sensitive)</td></tr>
<tr><th>name [required]</th><td>Name/Title of the script</td></tr>
<tr><th>author</th><td>Your Name</td></tr>
<tr><th>license</th><td>The license of the script (e.g. "GPL" or "MIT")</td></tr>
@ -149,12 +159,15 @@ The common part for all scripts is the "Descriptor". It's a Lua function which r
</table>
<p class="note">
Scripts that come with Ardour (currently mostly examples) can be found in the <a href="https://github.com/Ardour/ardour/tree/master/scripts">Source Tree</a>.
Scripts that come with Ardour (currently mostly examples) can be found in the
<a href="https://github.com/Ardour/ardour/tree/master/scripts">Source Tree</a>.
</p>
<h3 id="Action Scripts">Action Scripts</h3>
<p>Action scripts are the simplest form. An anonymous Lua function is called whenever the action is triggered. A simple action script is shown above.</p>
<p>There are 10 action script slots available, each of which is a standard GUI action available from the menu and hence can be bound to a keyboard shortcut.</p>
<p>Action scripts are the simplest form. An anonymous Lua function is called whenever the action is triggered. A simple action
script is shown above.</p>
<p>There are 10 action script slots available, each of which is a standard GUI action available from the menu and hence can be
bound to a keyboard shortcut.</p>
<h3 id="Session Scripts">Session Scripts</h3>
<p>Session scripts similar to Actions Scripts, except the anonymous function is called periodically every process cycle.
@ -199,7 +212,8 @@ end
</div>
<h3 id="Action Hooks">Action Hooks</h3>
<p>Action hook scripts must define an additional function which returns a <em>Set</em> of Signal that which trigger the callback (documenting available slots and their parameters remains to be done).</p>
<p>Action hook scripts must define an additional function which returns a <em>Set</em> of Signal that which trigger the
callback (documenting available slots and their parameters remains to be done).</p>
<div>
<pre><code class="lua">
ardour {
@ -247,53 +261,72 @@ end
<p>See the scripts folder for examples for now.</p>
<p>Some notes for further doc:</p>
<ul>
<li>required function: <code>dsp_ioconfig ()</code>: return a list of possible audio I/O configurations - follows Audio Unit conventions.</li>
<li>required function: <code>dsp_ioconfig ()</code>: return a list of possible audio I/O configurations - follows Audio
Unit conventions.</li>
<li>optional function: <code>dsp_dsp_midi_input ()</code>: return true if the plugin can receive midi input</li>
<li>optional function: <code>dsp_params ()</code>: return a table of possible parameters (automatable)</li>
<li>optional function: <code>dsp_init (samplerate)</code>: called when instantiation the plugin with given samplerate.</li>
<li>optional function: <code>dsp_configure (in, out)</code>: called after instantiation with configured plugin i/o.</li>
<li>required function: <code>dsp_run (ins, outs, n_samples)</code> OR <code>dsp_runmap (bufs, in_map, out_map, n_samples, offset)</code>: DSP process callback. The former is a convenient abstraction that passes mapped buffers (as table). The latter is a direct pass-through matching Ardour's internal <code>::connect_and_run()</code> API, which requires the caller to map and offset raw buffers.</li>
<li>required function: <code>dsp_run (ins, outs, n_samples)</code> OR <code>dsp_runmap (bufs, in_map, out_map, n_samples,
offset)</code>: DSP process callback. The former is a convenient abstraction that passes mapped buffers (as table). The
latter is a direct pass-through matching Ardour's internal <code>::connect_and_run()</code> API, which requires the caller
to map and offset raw buffers.</li>
<li>plugin parameters are handled via the global variable <code>CtrlPorts</code>.</li>
<li>midi data is passed via the global variable <code>mididata</code> which is valid during <code>dsp_run</code> only. (dsp_runmap requires the script to pass raw data from the buffers according to in_map)</li>
<li>The script has access to the current session via the global variable Session, but access to the session methods are limited to realtime safe functions</li>
<li>midi data is passed via the global variable <code>mididata</code> which is valid during <code>dsp_run</code> only.
(dsp_runmap requires the script to pass raw data from the buffers according to in_map)</li>
<li>The script has access to the current session via the global variable Session, but access to the session methods are
limited to realtime safe functions</li>
</ul>
<h2 id="Accessing Ardour Objects">Accessing Ardour Objects</h2>
<p>
The top most object in Ardour is the <code>ARDOUR::Session</code>.
Fundamentally, a Session is just a collection of other things:
Routes (tracks, busses), Sources (Audio/Midi), Regions, Playlists, Locations, Tempo map, Undo/Redo history, Ports, Transport state and controls, etc.
Routes (tracks, busses), Sources (Audio/Midi), Regions, Playlists, Locations, Tempo map, Undo/Redo history, Ports, Transport
state and controls, etc.
</p><p>
Every Lua interpreter can access it via the global variable <code>Session</code>.
</p><p>
GUI context interpreters also have an additional object in the global environment: The Ardour <code>Editor</code>. The Editor provides access to high level functionality which is otherwise triggered via GUI interaction such as undo/redo, open/close windows, select objects, drag/move regions. It also holds the current UI state: snap-mode, zoom-range, etc.
The Editor also provides complex operations such as "import audio" which under the hood, creates a new Track, adds a new Source Objects (for every channel) with optional resampling, creates both playlist and regions and loads the region onto the Track all the while displaying a progress information to the user.
GUI context interpreters also have an additional object in the global environment: The Ardour <code>Editor</code>. The Editor
provides access to high level functionality which is otherwise triggered via GUI interaction such as undo/redo, open/close
windows, select objects, drag/move regions. It also holds the current UI state: snap-mode, zoom-range, etc.
The Editor also provides complex operations such as "import audio" which under the hood, creates a new Track, adds a new
Source Objects (for every channel) with optional resampling, creates both playlist and regions and loads the region onto the
Track all the while displaying a progress information to the user.
</p>
<p class="note">
Documenting the bound C++ methods and class hierarchy is somewhere on the ToDo list.
Meanwhile <a href="https://github.com/Ardour/ardour/blob/master/libs/ardour/luabindings.cc">luabindings.cc</a> is the best we can offer.
Meanwhile <a href="https://github.com/Ardour/ardour/blob/master/libs/ardour/luabindings.cc">luabindings.cc</a> is the best we
can offer.
</p>
<h2 id="Concepts">Concepts</h2>
<ul>
<li>There are no bound constructors: Lua asks Ardour to create objects (e.g. add a new track), then receives a reference to the object to modify it.</li>
<li>Scripts, once loaded, are saved with the Session (no reference to external files). This provides for portable Sessions.</li>
<li>Lua Scripts are never executed directly. They provide a "factory" method which can have optional instantiation parameters, which returns a Lua closure.</li>
<li>No external Lua modules/libraries can be used, scripts need to be self contained (portable across different systems (libs written in Lua can be used, and important c-libs/functions can be included with Ardour if needed).</li>
<li>There are no bound constructors: Lua asks Ardour to create objects (e.g. add a new track), then receives a reference
to the object to modify it.</li>
<li>Scripts, once loaded, are saved with the Session (no reference to external files). This provides for portable
Sessions.</li>
<li>Lua Scripts are never executed directly. They provide a "factory" method which can have optional instantiation
parameters, which returns a Lua closure.</li>
<li>No external Lua modules/libraries can be used, scripts need to be self contained (portable across different systems
(libs written in Lua can be used, and important c-libs/functions can be included with Ardour if needed).</li>
</ul>
<p>
Ardour is a highly multithreaded application and interaction between the different threads, particularly real-time threads, needs to to be done with care.
This part has been abstracted away by providing separate Lua interpreters in different contexts and restricting available interaction:
Ardour is a highly multithreaded application and interaction between the different threads, particularly real-time threads,
needs to to be done with care. This part has been abstracted away by providing separate Lua interpreters in different contexts
and restricting available interaction:
</p>
<ul>
<li>Editor Actions run in a single instance interpreter in the GUI thread.</li>
<li>Editor Hooks connect to libardour signals. Every Callback uses a dedicated Lua interpreter which is in the GUI thread context.</li>
<li>Editor Hooks connect to libardour signals. Every Callback uses a dedicated Lua interpreter which is in the GUI thread
context.</li>
<li>All Session scripts run in a single instance in the main real-time thread (audio callback)</li>
<li>DSP scripts have a separate instance per script and run in one of the DSP threads.</li>
</ul>
<p>
The available interfaces differ between contexts. For example, it is not possible to create new tracks or import audio from real-time context; while it is not possible to modify audio buffers from the GUI thread.
The available interfaces differ between contexts. For example, it is not possible to create new tracks or import audio from
real-time context; while it is not possible to modify audio buffers from the GUI thread.
</p>
<h2 id="Current State">Current State</h2>
@ -305,7 +338,8 @@ Fully functional, yet still in a prototyping stage:
<li>Further planned work includes:
<ul>
<li>Built-in Script editor (customize/modify Scripts in-place)</li>
<li>convenience methods (wrap more complex Ardour actions into a library). e.g set plugin parameters, write automation lists from a Lua table</li>
<li>convenience methods (wrap more complex Ardour actions into a library). e.g set plugin parameters, write
automation lists from a Lua table</li>
<li>Add some useful scripts and more examples</li>
<li>Documentation (Ardour API), also usable for tab-exansion, syntax highlighting</li>
<li>bindings for GUI Widgets (plugin UIs, message boxes, etc)</li>
@ -315,7 +349,8 @@ Fully functional, yet still in a prototyping stage:
<h2 id="Examples">Examples</h2>
<p>Apart from the <a href="https://github.com/Ardour/ardour/tree/master/scripts">scripts included with the source-code</a> here are a few examples without further comments...
<p>Apart from the <a href="https://github.com/Ardour/ardour/tree/master/scripts">scripts included with the source-code</a>
here are a few examples without further comments...
<h3 id="Editor Console Examples">Editor Console Examples</h3>
<div>
@ -385,7 +420,8 @@ ARDOUR.LuaAPI.set_processor_param (proc, 2, 1.0)
<p>The standalone tool <code>luasession</code> allows one to access an Ardour session directly from the commandline.
Interaction is limited by the fact that most actions in Ardour are provided by the Editor GUI.
</p><p>
<code>luasession</code> provides only two special functions <code>load_session</code> and <code>close_session</code> and exposes the <code>AudioEngine</code> instance as global variable.
<code>luasession</code> provides only two special functions <code>load_session</code> and <code>close_session</code> and
exposes the <code>AudioEngine</code> instance as global variable.
</p>
<div>

3
include/midi-list-editor.html
View File

@ -29,7 +29,8 @@
<tr><th>Num</th><td>The <a href="@@midi-notes-ref">MIDI number</a> of the note</td></tr>
<tr><th>Name</th><td>The MIDI name of the note, made of its English name and octave (e.g. "C4")</td></tr>
<tr><th>Vel</th><td>the velocity of the note (i.e. its intensity, between 0 and 127)</td></tr>
<tr><th>Length</th><td>duration of the note, either expressed as a number (in ticks, related to the tempo) or as a text (fraction of a beat, also related to the tempo)</td></tr>
<tr><th>Length</th><td>duration of the note, either expressed as a number (in ticks, related to the tempo) or as a text
(fraction of a beat, also related to the tempo)</td></tr>
</table>
<p>

40
include/processor-box.html
View File

@ -5,19 +5,27 @@
</figure>
<p>
In Ardour terminology, a <dfn>processor</dfn> is anything which treats the signal in some way and gets plugged into a mixer strip. Ardour provides several builtin processors such as the fader or panners. Processors can also be <dfn>plugins</dfn> used for effects or as instruments, as well as sends or inserts which affect <a href="@@signal-routing">signal routing</a>.
In Ardour terminology, a <dfn>processor</dfn> is anything which treats the signal in some way and gets plugged into a mixer
strip. Ardour provides several builtin processors such as the fader or panners. Processors can also be <dfn>plugins</dfn>
used for effects or as instruments, as well as sends or inserts which affect <a href="@@signal-routing">signal routing</a>.
</p>
<p>
The arrangement of processors is arbitrary, and there is no limit to how many there can be. The Processor Box will automagically add a scrollbar to itself if there are more processors in it than can be shown in the given space.
The arrangement of processors is arbitrary, and there is no limit to how many there can be. The Processor Box will
automagically add a scrollbar to itself if there are more processors in it than can be shown in the given space.
</p>
<p>
The main box in the top half of a mixer strip shows the <dfn>processor box</dfn>. Processors are shown as colored rectangles, with a small LED beside them that lights up when the processor is enabled. The color of the processor depends on its location in the sequence; processors that are <dfn>pre-fader</dfn> are colored in red, and <dfn>post-fader</dfn> processors are colored green (in the default theme).
The main box in the top half of a mixer strip shows the <dfn>processor box</dfn>. Processors are shown as colored rectangles,
with a small LED beside them that lights up when the processor is enabled. The color of the processor depends on its location
in the sequence; processors that are <dfn>pre-fader</dfn> are colored in red, and <dfn>post-fader</dfn> processors are
colored green (in the default theme).
</p>
<p>
The <dfn>processor box</dfn> will always contain a blue <dfn>Fader</dfn> processor. This indicates where in the processor chain the main channel fader is located; this is the fader shown in the lower half of the strip. It can be enabled and disabled like any other processor.
The <dfn>processor box</dfn> will always contain a blue <dfn>Fader</dfn> processor. This indicates where in the processor
chain the main channel fader is located; this is the fader shown in the lower half of the strip. It can be enabled and
disabled like any other processor.
</p>
<h2>Adding Processors</h2>
@ -37,17 +45,20 @@
</p>
<p>
Processors can also be dragged and dropped from the <a href="@@plugin-manager"><dfn>Favorite Plugins</dfn> window</a> to an appropriate spot in the Processor Box.
Processors can also be dragged and dropped from the <a href="@@plugin-manager"><dfn>Favorite Plugins</dfn> window</a> to an
appropriate spot in the Processor Box.
</p>
<p class="note">
The <dfn>Favorite Plugins</dfn> window can be populated via the <a href="@@plugin-manager">Plugin Manager</a>, or by dragging and dropping an existing processor from the <dfn>processor box</dfn> to the <dfn>Favorite Plugins</dfn> window.
The <dfn>Favorite Plugins</dfn> window can be populated via the <a href="@@plugin-manager">Plugin Manager</a>, or by dragging
and dropping an existing processor from the <dfn>processor box</dfn> to the <dfn>Favorite Plugins</dfn> window.
</p>
<h2>To Reorder (Move) Processors</h2>
<p>
Processors can be re-ordered using drag and drop. Dragging a processor allows it to be moved around within the chain, or copied to another processor list on another track or bus.
Processors can be re-ordered using drag and drop. Dragging a processor allows it to be moved around within the chain, or
copied to another processor list on another track or bus.
</p>
<h2>To Enable/Disable a Processor</h2>
@ -58,22 +69,29 @@
</figure>
<p>
To the left of the name of each processor is a small LED symbol; if this is lit-up, the processor is active. Clicking on it will deactivate the processor and effectively bypass it.
To the left of the name of each processor is a small LED symbol; if this is lit-up, the processor is active. Clicking on it
will deactivate the processor and effectively bypass it.
</p>
<p class="note">
Some processors have their own bypass controls that are independent of the one that Ardour provides; this can make it appear that the plugin is non-responsive when its independent bypass control is active.
Some processors have their own bypass controls that are independent of the one that Ardour provides; this can make it appear
that the plugin is non-responsive when its independent bypass control is active.
</p>
<h2>Selecting Processors</h2>
<p>
A processor in the <dfn>processor box</dfn> can be selected with a <kbd class=mouse>Left</kbd>-click on it; it will be highlighed in red. Other processors can be selected at the same time by <kbd class=mouse>Left</kbd>-clicking on them while holding down the <kbd class=mod1n></kbd> key, and ranges can be selected by <kbd class=mouse>Left</kbd>-clicking on them while holding down the <kbd class=mod3n></kbd> key.
A processor in the <dfn>processor box</dfn> can be selected with a <kbd class=mouse>Left</kbd>-click on it; it will be
highlighed in red. Other processors can be selected at the same time by <kbd class=mouse>Left</kbd>-clicking on them while
holding down the <kbd class=mod1n></kbd> key, and ranges can be selected by <kbd class=mouse>Left</kbd>-clicking on them
while holding down the <kbd class=mod3n></kbd> key.
</p>
<h2>Removing Processors</h2>
<p>
Context-click on the processor to be removed, and select <kbd class="menu">Delete</kbd>; or <kbd class=mod3n></kbd><kbd class=mouse>Right</kbd>-click on it; or <kbd class=mouse>Left</kbd>-click on it and press the <kbd>Delete</kbd> key. If multiple processors are selected, they will all be deleted at the same time.
Context-click on the processor to be removed, and select <kbd class="menu">Delete</kbd>; or
<kbd class=mod3n></kbd><kbd class=mouse>Right</kbd>-click on it; or <kbd class=mouse>Left</kbd>-click on it and press the
<kbd>Delete</kbd> key. If multiple processors are selected, they will all be deleted at the same time.
</p>

53
include/sidechaining.html
View File

@ -1,24 +1,36 @@
<p>
Dynamic Processors&mdash;such as compressors&mdash;in general use the the original input signal for analysis and operate on the same signal. Side-chaining uses the signal level of <em>another input</em> to control the compression level of the original signal.
Dynamic Processors&mdash;such as compressors&mdash;in general use the the original input signal for analysis and operate on
the same signal. Side-chaining uses the signal level of <em>another input</em> to control the compression level of the
original signal.
</p>
<p>
Effect Processors which have a side-chain input (sometimes also called <em>key input</em>) have an additional input pin to receive a signal from an external input. In Ardour that extra input can be connected in the plugin's <kbd class="menu">Pin Configuration</kbd> dialog: the signal from one track can be tapped off and used as an input to a plugin on a different track. This dialog is accessed via the plugin's context-menu &gt; <kbd class="menu">Pin Connections&hellip;</kbd>.
Effect Processors which have a side-chain input (sometimes also called <em>key input</em>) have an additional input pin to
receive a signal from an external input. In Ardour that extra input can be connected in the plugin's <kbd class="menu">Pin
Configuration</kbd> dialog: the signal from one track can be tapped off and used as an input to a plugin on a different
track. This dialog is accessed via the plugin's context-menu &gt; <kbd class="menu">Pin Connections&hellip;</kbd>.
</p>
<p>
In case a plugin has a dedicated sidechain input, Ardour automatically creates a port for the input. This is a normal I/O port which can be fed by any external signal. The <kbd class="menu">Pin Configuration</kbd> dialog is not limited to processors with a dedicated sidechain input, it also allows to manually create (or remove) a sidechain input port and provides for flexible connection of the signal to plugin pins.
In case a plugin has a dedicated sidechain input, Ardour automatically creates a port for the input. This is a normal I/O
port which can be fed by any external signal. The <kbd class="menu">Pin Configuration</kbd> dialog is not limited to
processors with a dedicated sidechain input, it also allows to manually create (or remove) a sidechain input port and
provides for flexible connection of the signal to plugin pins.
</p>
<p>
The operational flow in the Ardour GUI starts at the processor which is to receive the signal: a sidechain source is selected, and Ardour creates a dedicated send-processor in the source processor box, the level of which can be adjusted either in the Pin Configuration window or directly on the source's send.
The operational flow in the Ardour GUI starts at the processor which is to receive the signal: a sidechain source is
selected, and Ardour creates a dedicated send-processor in the source processor box, the level of which can be adjusted
either in the Pin Configuration window or directly on the source's send.
</p>
<h2>A simple example: Sidechain compression</h2>
<p>
One example is the use of a bassdrum track to trigger the compression on a bass track. The sidechain compressor (a-Compressor) will be placed on the bass track, and will need to receive the signal from the bassdrum track as a way to trigger the compression.
One example is the use of a bassdrum track to trigger the compression on a bass track. The sidechain compressor
(a-Compressor) will be placed on the bass track, and will need to receive the signal from the bassdrum track as a way to
trigger the compression.
</p>
<figure>
@ -31,21 +43,29 @@
</figure>
<p>
Here, on the bass track, an <em>a-Compressor</em> has been added, and the Drum track has been set as the sidechain source. The mixer reflects this by showing an <em>SC</em>-send processor in the drum track, very similar to a <a href="@@aux-sends">send</a>. The bass track also shows an arrow as one of the a-compressor input.
Here, on the bass track, an <em>a-Compressor</em> has been added, and the Drum track has been set as the sidechain source.
The mixer reflects this by showing an <em>SC</em>-send processor in the drum track, very similar to a
<a href="@@aux-sends">send</a>. The bass track also shows an arrow as one of the a-compressor input.
</p>
<p>
As a result, in the editor, each peak in the kick drum track triggers the compression on the bass track and the resulting track shows the compression kicking in on each kick drum peak, hence reducing the gain. The compression is applied to the bass, but only based on the level of the drum track.
As a result, in the editor, each peak in the kick drum track triggers the compression on the bass track and the resulting
track shows the compression kicking in on each kick drum peak, hence reducing the gain. The compression is applied to the
bass, but only based on the level of the drum track.
</p>
<p>
This is commonly used for <em>ducking</em> effect, when e.g. a radio speaker's voice triggers the compression on the audio playing.
This is commonly used for <em>ducking</em> effect, when e.g. a radio speaker's voice triggers the compression on the audio
playing.
</p>
<h2>MIDI Sidechaining</h2>
<p>
Ardour allows the sidechain sources to be either audio or MIDI tracks/busses. This is particularly useful when a MIDI signal is used to control an audio effect, like a vocoder or an auto-tuner, like <a href="https://github.com/x42/fat1.lv2">fat1</a>, the LV2 port of Fons Adriaensen's <a href="http://kokkinizita.linuxaudio.org/linuxaudio/zita-at1-doc/quickguide.html">Zita AT1</a> by Robin Gareus:
Ardour allows the sidechain sources to be either audio or MIDI tracks/busses. This is particularly useful when a MIDI signal
is used to control an audio effect, like a vocoder or an auto-tuner, like <a href="https://github.com/x42/fat1.lv2">fat1</a>,
the LV2 port of Fons Adriaensen's <a href="http://kokkinizita.linuxaudio.org/linuxaudio/zita-at1-doc/quickguide.html">Zita
AT1</a> by Robin Gareus:
</p>
<figure>
@ -56,11 +76,14 @@
</figure>
<p>
Here, the MIDI track is inputed to the plugin's MIDI IN pin through a sidechain, indicating to the plugin what note should the source audio be corrected to.
Here, the MIDI track is inputed to the plugin's MIDI IN pin through a sidechain, indicating to the plugin what note should
the source audio be corrected to.
</p>
<p class="note">
Notice that in the example above, the output of the "Vocals" track is connected to the input of the "Corrected" track. We could have chosen to insert the "Vocals" track content as an audio sidechain too, totally disconnecting the input from the plugin, and connecting the plugin's input pin to the audio sidechain port.
Notice that in the example above, the output of the "Vocals" track is connected to the input of the "Corrected" track. We
could have chosen to insert the "Vocals" track content as an audio sidechain too, totally disconnecting the input from the
plugin, and connecting the plugin's input pin to the audio sidechain port.
</p>
<h2>Pre-processing the sidechained signal</h2>
@ -70,10 +93,14 @@
</p>
<p>
In the first example above, if the entire drum part is on one track, then compressing with this signal as a sidechain will result in every peak triggering the compression, be they bass drum kicks or snare, cymbals, etc.
In the first example above, if the entire drum part is on one track, then compressing with this signal as a sidechain will
result in every peak triggering the compression, be they bass drum kicks or snare, cymbals, etc.
</p>
<p>
In this case, adding an EQ to the drum track with a low pass filter would filter out the peaks created by the high pitched instruments of the drum kit, and allow for a better triggering, though to avoid damaging the original drum track, a send to an intermediary track would be better suited to place the EQ on. This track won't be connected to the Master, as its content is of no musical interest except for its use as a trigger, allowing for some extreme EQ.
In this case, adding an EQ to the drum track with a low pass filter would filter out the peaks created by the high pitched
instruments of the drum kit, and allow for a better triggering, though to avoid damaging the original drum track, a send to
an intermediary track would be better suited to place the EQ on. This track won't be connected to the Master, as its content
is of no musical interest except for its use as a trigger, allowing for some extreme EQ.
</p>