HTTP Support

Similarly to OSC, several Faust architectures also provide HTTP support. This allows Faust applications to be remotely controlled from any Web browser using specific URLs. Moreover, OSC and HTTP can be freely combined.

While OSC support is installed by default when Faust is built, this is not the case for HTTP. That's because it depends on the GNU libmicrohttpd library, which is usually not installed by default on the system. An additional make httpd step is therefore required when compiling and installing Faust:

make httpd
make
sudo make install

Note that make httpd will fail if libmicrohttpd is not available on the system.

HTTP support can be added to any Faust program (as long as the target architecture supports it; see tables below) simply by adding the [http:on] metadata to the standard option metadata:

declare options "[http:on]";

The following tables list Faust's architectures providing HTTP support:

Linux Faust Architectures with HTTP Support

Audio System Environment
Alsa GTK, Qt, Console
Jack GTK, Qt, Console
Netjack GTK, Qt, Console
PortAudio GTK, Qt

OSX Faust Architectures with HTTP Support

Audio System Environment
CoreAudio Qt
Jack Qt, Console
Netjack Qt, Console
PortAudio Qt

Windows Faust Architectures with HTTP Support

Audio System Environment
Jack Qt, Console
PortAudio Qt

A Simple Example

To illustrate how HTTP support works, let's reuse our previous example, a simple monophonic audio mixer with four inputs and one output. For each input we have a mute button and a level slider:


This example can be compiled as a standalone Jack QT application with HTTP support using the command:

faust2jaqt -httpd mix4.dsp

The -httpd option embeds a small Web server into the generated application. Its purpose is to serve an HTML page implementing the interface of the app. This page makes use of JavaScript and SVG, and is quite similar to the native QT interface.

When the application is started from the command line:

./mix4

various pieces of information are printed on the standard output, including:

Faust httpd server version 0.73 is running on TCP port 5510

As we can see, the embedded Web server runs by default on TCP port 5510. The entry point is http://localhost:5510. It can be opened from any recent browser and it produces the page presented in the figure below:

JSON Description of the User Interface

The communication between the application and the Web browser is based on several underlying URLs. The first one is http://localhost:5510/JSON, which returns a JSON description of the user interface of the application. This JSON description is used internally by the JavaScript code to build the graphical user interface. Here is (part of) the JSON returned by mix4:

{
  "name": "mix4",
  "address": "YannAir.local",
  "port": "5511",
  "ui": [
    {
      "type": "hgroup",
      "label": "mixer",
      "items": [
        {
          "type": "vgroup",
          "label": "input_0",
          "items": [
            {
              "type": "vslider",
              "label": "level",
              "address": "/mixer/input_0/level",
              "init": "0", "min": "0", "max": "1", 
              "step": "0.01"
            },
            {
              "type": "checkbox",
              "label": "mute",
              "address": "/mixer/input_0/mute",
              "init": "0", "min": "0", "max": "0", 
              "step": "0"
            }
          ]
        },

        ...

      ]
    }
  ]
}

Querying the State of the Application

Each widget has a unique "address" field that can be used to query its value. In our example, the level of input 0 has the address /mixer/input_0/level. The address can be used to create a URL to get the value of the widget: http://localhost:5510/mixer/input_0/level, resulting in:

/mixer/input_0/level 0.00000

Multiple widgets can be queried at once by using an address higher in the hierarchy. For example, to get the values of the level and the mute state of input 0 we use http://localhost:5510/mixer/input_0, resulting in:

/mixer/input_0/level 0.00000 
/mixer/input_0/mute  0.00000

To get all the values at once we simply use http://localhost:5510/mixer, resulting in:

/mixer/input_0/level 0.00000 
/mixer/input_0/mute  0.00000 
/mixer/input_1/level 0.00000 
/mixer/input_1/mute  0.00000 
/mixer/input_2/level 0.00000 
/mixer/input_2/mute  0.00000 
/mixer/input_3/level 0.00000 
/mixer/input_3/mute  0.00000

Changing the Value of a Widget

Suppose that we want to mute input 1 of our mixer. For that purpose, we can use the URL http://localhost:5510/mixer/input_1/mute?value=1, obtained by appending ?value=1 to the end of the widget URL.

All widgets can be controlled in a similar way. For example http://localhost:5510/mixer/input_3/level?value=0.7 will set the input 3 level to 0.7.

Proxy Control Access to the Web Server

A control application may want to access and control the running DSP using its Web server, but without using the delivered HTML page in a browser. Since the complete JSON can be retrieved, control applications can be developed purely in C/C++. A proxy version of the user interface can then be built, and parameters can be set and queried using HTTP requests.

This mode can be started dynamically using the -server URL parameter. Assuming an application with HTTP support is running remotely at the given URL, the control application will fetch its JSON description, use it to dynamically build the user interface, and allow access to the remote parameters.

HTTP Cheat Sheet

Here is a summary of the various URLs used to interact with the application's Web server.

Default Ports

Port Description
5510 default TCP port used by the application's Web server
5511... alternative TCP ports

Command Line Options

Option Description
-port n set the TCP port number used by the application's Web server
-server URL start a proxy control application accessing the remote application running on the given URL

URLs

URL Description
http://host:port the base URL to be used in proxy control access mode
http://host:port/JSON get a json description of the user interface
http://host:port/address get the value of a widget or a group of widgets
http://host:port/address?value=v set the value of a widget to v

JSON

Top Level

The JSON describes the name, host, and port of the application and a hierarchy of user interface items:

{
  "name": <name>,
  "address": <host>,
  "port": <port>,
  "ui": [ <item> ]
}

An <item> is either a group (of items) or a widget.

Groups

A group is essentially a list of items with a specific layout: 

{
    "type": <type>,
    "label": <label>,
    "items": [ <item>, <item>,...]
}

The <type> defines the layout. It can be either "vgroup", "hgroup" or "tgroup"

Widgets

{
    "type": <type>,
    "label": <label>,
    "address": <address>,
    "meta": [ { "key": "value"},... ],
    "init": <num>,
    "min": <num>,
    "max": <num>,
    "step": <num>
},

Widgets are the basic items of the user interface. They can be of different <type>: "button", "checkbox", "nentry", "vslider", "hslider", "vbargraph" or "hbargraph".