2 The WebSockets Server is an experimental control surface that allows
3 controlling a running Ardour session via a web browser on any computer
4 in the same local network.
8 The connection between the WebSockets server and a running instance of Ardour
9 is two-way: any changes made in the web-based surface are immediately
10 available in Ardour, and vice versa.
14 The experimental status means that this control surface is not
15 feature-complete and might have bugs.
19 Supported features are currently limited to:
23 <li>Adjusting positions of channel faders and panners in tracks and the master
24 bus, as well as muting and unmuting tracks.</li>
25 <li>Changing settings of LV2 plugins that have already been loaded into
26 tracks or the master bus.</li>
27 <li>Rolling or pausing transport.</li>
30 <h2>Enabling and Accessing the WebSockets Server</h2>
33 To enable the WebSockets Server surface, open the <em>Preferences</em> dialog
34 and go to the <em>Control Surfaces</em> page. Click on the <em>Web Sockets
35 Server (Experimental)</em> to enable it. This will immediately run the server
36 and make it available on port 3818. You can verify that it's running by
37 opening a web browser on the same computer and visiting
38 <a href="http://localhost:3818/">http://localhost:3818/</a>. You should see
39 the home page that looks like this:
43 <img src="/images/websockets-main.png" alt="WebSockets Server main page"
46 WebSockets Server main page
51 To access the server from any device in the same network you need to know the
52 broadcast IP address of the computer running Ardour. Here is how to do that
53 on supported operating systems.
61 <li>Open the <em>Settings</em> application.</li>
62 <li>Go to the <em>Network & internet</em> from the menu on the left, then click Properties along the top.</li>
63 <li>Select the type of network connection (WiFi or Ethernet)</li>
64 <li>Click <em>Network</em> in the center.</li>
65 <li>In the newly opened page, the local IPv4 address be displayed.</li>
68 <p>…or…</p>
71 <li>Open the <em>Start</em> menu and type <tt>cmd</tt>. This will to open the
73 <li>Type <tt>ipconfig</tt> and press <strong>Enter</strong>.</li>
74 <li>In the output, look for IPv4 address.</li>
82 <li>Open the <em>System Preferences</em> dialog.</li>
83 <li>Select <em>Network</em>, then choose connection type (typically WiFi,
84 Ethernet, or USB).</li>
85 <li>The IP address will be displayed on the newly opened page under the
86 connection status.</li>
94 <li>Open a terminal program.</li>
95 <li>Run this command: <tt>$ ip -4 address</tt>.</li>
96 <li>The output will list several network devices. You want the one that has
97 "BROADCAST" rather than "LOOPBACK" in the description.</li>
101 Once you know the address, you can open the control surface web app
102 in a browser by visiting the IP address with appended port number.
103 E.g. if the IP address of the computer running Ardour is <tt>192.168.1.68</tt>,
104 the entire URL will be <tt>http://192.168.1.68:3818/</tt>.
107 <h2>Using the WebSockets Server control surface</h2>
110 Various features available in the control surface are spread across three
111 pages: <em>Mixer</em>, <em>Transport</em>, and <em>Protocol</em>.</p>
116 This is where you can view VU meters for each track and the master bus, as
117 well as make a number of adjustments:
121 <li>Change positions of faders and panners.</li>
122 <li>Enable and disable the <em>Mute</em> status.</li>
123 <li>Adjust settings of LV2 plugins loaded into mixer channels.</li>
127 <img src="/images/websockets-mixer.png" alt="Mixer view in WebSockets Server"
130 Mixer view in WebSockets Server
135 The control surface only supports changing settings for LV2 plugins presently.
136 LADSPA, VST2/VST3, and AU plugins will not be listed. When an LV2 plugin has
137 been loaded into a mixer channel, a button with "f" caption appears on top of
138 the mixer channel. Clicking it opens this kind of an overlay:
142 <img src="/images/websockets-plugins.png"
143 alt="Plugins view in WebSockets Server" width="50%" >
145 Plugins view in WebSockets Server
152 The <em>Transport</em> view displays the timecode of the current playhead
153 position and allows toggling playback.
157 <img src="/images/websockets-transport.png"
158 alt="Transport view in WebSockets Server" width="50%" >
160 Transport view in WebSockets Server
165 The <em>Record</em> toggle is currently non-functional.
171 This page is targeted at developers willing to enhance the WebSockets Server
172 control surface. It displays the data passed between Ardour and the web
177 <img src="/images/websockets-protocol.png"
178 alt="Protocol view in WebSockets Server" width="50%" >
180 Protocol view in WebSockets Server