manual/include/control-surfaces-websockets-server.html

183 lines
5.1 KiB
HTML

<p>
The WebSockets Server is an experimental control surface that allows
controlling a running Ardour session via a web browser on any computer
in the same local network.
</p>
<p>
The connection between the WebSockets server and a running instance of Ardour
is two-way: any changes made in the web-based surface are immediately
available in Ardour, and vice versa.
</p>
<p>
The experimental status means that this control surface is not
feature-complete and might have bugs.
</p>
<p>
Supported features are currently limited to:
</p>
<ul>
<li>Adjusting positions of channel faders and panners in tracks and the master
bus, as well as muting and unmuting tracks.</li>
<li>Changing settings of LV2 plugins that have already been loaded into
tracks or the master bus.</li>
<li>Rolling or pausing transport.</li>
</ul>
<h2>Enabling and Accessing the WebSockets Server</h2>
<p>
To enable the WebSockets Server surface, open the <em>Preferences</em> dialog
and go to the <em>Control Surfaces</em> page. Click on the <em>Web Sockets
Server (Experimental)</em> to enable it. This will immediately run the server
and make it available on port 3818. You can verify that it's running by
opening a web browser on the same computer and visiting
<a href="http://localhost:3818/">http://localhost:3818/</a>. You should see
the home page that looks like this:
</p>
<figure>
<img src="/images/websockets-main.png" alt="WebSockets Server main page"
width="50%" >
<figcaption>
WebSockets Server main page
</figcaption>
</figure>
<p>
To access the server from any device in the same network you need to know the
broadcast IP address of the computer running Ardour. Here is how to do that
on supported operating systems.
</p>
<p>
Windows 10:
</p>
<ol>
<li>Open the <em>Settings</em> application.</li>
<li>Go to the <em>Network &amp; internet</em> from the menu on the left, then click Properties along the top.</li>
<li>Select the type of network connection (WiFi or Ethernet)</li>
<li>Click <em>Network</em> in the center.</li>
<li>In the newly opened page, the local IPv4 address be displayed.</li>
</ol>
<p>&hellip;or&hellip;</p>
<ol>
<li>Open the <em>Start</em> menu and type <tt>cmd</tt>. This will to open the
command prompt.</li>
<li>Type <tt>ipconfig</tt> and press <strong>Enter</strong>.</li>
<li>In the output, look for IPv4 address.</li>
</ol>
<p>
macOS:
</p>
<ol>
<li>Open the <em>System Preferences</em> dialog.</li>
<li>Select <em>Network</em>, then choose connection type (typically WiFi,
Ethernet, or USB).</li>
<li>The IP address will be displayed on the newly opened page under the
connection status.</li>
</ol>
<p>
Linux:
</p>
<ol>
<li>Open a terminal program.</li>
<li>Run this command: <tt>$ ip -4 address</tt>.</li>
<li>The output will list several network devices. You want the one that has
"BROADCAST" rather than "LOOPBACK" in the description.</li>
</ol>
<p>
Once you know the address, you can open the control surface web app
in a browser by visiting the IP address with appended port number.
E.g. if the IP address of the computer running Ardour is <tt>192.168.1.68</tt>,
the entire URL will be <tt>http://192.168.1.68:3818/</tt>.
</p>
<h2>Using the WebSockets Server control surface</h2>
<p>
Various features available in the control surface are spread across three
pages: <em>Mixer</em>, <em>Transport</em>, and <em>Protocol</em>.</p>
<h3>Mixer</h3>
<p>
This is where you can view VU meters for each track and the master bus, as
well as make a number of adjustments:
</p>
<ul>
<li>Change positions of faders and panners.</li>
<li>Enable and disable the <em>Mute</em> status.</li>
<li>Adjust settings of LV2 plugins loaded into mixer channels.</li>
</ul>
<figure>
<img src="/images/websockets-mixer.png" alt="Mixer view in WebSockets Server"
width="50%" >
<figcaption>
Mixer view in WebSockets Server
</figcaption>
</figure>
<p>
The control surface only supports changing settings for LV2 plugins presently.
LADSPA, VST2/VST3, and AU plugins will not be listed. When an LV2 plugin has
been loaded into a mixer channel, a button with "f" caption appears on top of
the mixer channel. Clicking it opens this kind of an overlay:
</p>
<figure>
<img src="/images/websockets-plugins.png"
alt="Plugins view in WebSockets Server" width="50%" >
<figcaption>
Plugins view in WebSockets Server
</figcaption>
</figure>
<h3>Transport</h3>
<p>
The <em>Transport</em> view displays the timecode of the current playhead
position and allows toggling playback.
</p>
<figure>
<img src="/images/websockets-transport.png"
alt="Transport view in WebSockets Server" width="50%" >
<figcaption>
Transport view in WebSockets Server
</figcaption>
</figure>
<p>
The <em>Record</em> toggle is currently non-functional.
</p>
<h3>Protocol</h3>
<p>
This page is targeted at developers willing to enhance the WebSockets Server
control surface. It displays the data passed between Ardour and the web
browser.
</p>
<figure>
<img src="/images/websockets-protocol.png"
alt="Protocol view in WebSockets Server" width="50%" >
<figcaption>
Protocol view in WebSockets Server
</figcaption>
</figure>