5 - Architecture Files

    5.1  Audio architecture modules
    5.2  UI architecture modules
        5.2.1  Active widgets
        5.2.2  Passive widgets
        5.2.3  Widgets layout
        5.2.4  Metadata
    5.3  OSC architecture modules
        5.3.1  OSC GUI architecture module
        5.3.2  OSC message aliases
        5.3.3  OSC audio architecture

A FAUST program describes a signal processor, a pure computation that maps input signals to output signals. It says nothing about audio drivers or GUI toolkits. This missing information is provided by architecture files.
An architecture file describes how to relate a FAUST program to the external world, in particular the audio drivers and the user interface to be used. This approach allows a single FAUST program to be easily deployed to a large variety of audio standards (Max/MSP externals, PD externals, VST plugins, CoreAudio applications, Jack applications, iPhone, etc.).
The architecture to be used is specified at compile time with the -a options. For example faust -a jack-gtk.cpp foo.dsp indicates to use the Jack GTK architecture when compiling foo.dsp.
File name Description
alchemy-as.cpp Flash - ActionScript plugin
ca-qt.cpp CoreAudio QT4 standalone application
jack-gtk.cpp Jack GTK standalone application
jack-qt.cpp Jack QT4 standalone application
jack-console.cpp Jack command line application
jack-internal.cpp Jack server plugin
alsa-gtk.cpp ALSA GTK standalone application
alsa-qt.cpp ALSA QT4 standalone application
oss-gtk.cpp OSS GTK standalone application
pa-gtk.cpp PortAudio GTK standalone application
pa-qt.cpp PortAudio QT4 standalone application
max-msp.cpp Max/MSP external
vst.cpp VST plugin
vst2p4.cpp VST 2.4 plugin
vsti-mono.cpp VSTi mono instrument
ladspa.cpp LADSPA plugin
q.cpp Q language plugin
supercollider.cpp SuperCollider Unit Generator
snd-rt-gtk.cpp Snd-RT music programming language
csound.cpp CSOUND opcode
puredata.cpp PD external
sndfile.cpp sound file transformation command
bench.cpp speed benchmark
octave.cpp Octave plugin
plot.cpp Command line application
sndfile.cpp Command line application
Table 5.1: Available architectures.
The main available architecture files are listed table 5.1. Since FAUST 0.9.40 some of these architectures are a modular combination of an audio module and one or more user interface modules. Among these user interface modules OSCUI provide supports for Open Sound Control allowing FAUST programs to be controlled by OSC messages.

5.1  Audio architecture modules

An audio architecture module typically connects a FAUST program to the audio drivers. It is responsible for allocating and releasing the audio channels and for calling the FAUST dsp::compute method to handle incoming audio buffers and/or to produce audio output. It is also responsible for presenting the audio as non-interleaved float data, normalized between -1.0 and 1.0.
A FAUST audio architecture module derives an audio class defined as below:
class audio {
           audio() {}
  virtual ~audio() {}
  virtual bool init(const char*, dsp*) = 0;
  virtual bool start()                 = 0;
  virtual void stop()                  = 0;

The API is simple enough to give a great flexibility to audio architectures implementations. The init method should initialize the audio. At init exit, the system should be in a safe state to recall the dsp object state.
Table 5.2 gives the audio architectures currently available for various operating systems.
Audio system Operating system
Alsa Linux
Core audio Mac OS X, iOS
Jack Linux, Mac OS X, Windows
Portaudio Linux, Mac OS X, Windows
OSC (see 5.3.3) Linux, Mac OS X, Windows
VST Mac OS X, Windows
Max/MSP Mac OS X, Windows
CSound Linux, Mac OS X, Windows
SuperCollider Linux, Mac OS X, Windows
PureData Linux, Mac OS X, Windows
Pure Linux, Mac OS X, Windows
Table 5.2: FAUST audio architectures.

5.2  UI architecture modules

A UI architecture module links user actions (via graphic widgets, command line parameters, OSC messages, etc.) with the FAUST program to control. It is responsible for associating program parameters to user interface elements and to update parameter's values according to user actions. This association is triggered by the dsp::buildUserInterface call, where the dsp asks a UI object to build the DSP module controllers.
Since the interface is basically graphic oriented, the main concepts are widget based: a UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout.
A FAUST UI architecture module derives an UI class (Figure 5.1).
class UI
UI() {}
virtual ~UI() {}
-- active widgets
virtual void addButton(const char* l, float* z)	= 0;
virtual void addToggleButton(const char* l, float* z) = 0;
virtual void addCheckButton(const char* l, float* z) = 0;
virtual void addVerticalSlider(const char* l, float* z,
float init, float min, float max, float step) = 0;
virtual void addHorizontalSlider(const char* l, float* z,
float init, float min, float max, float step) = 0;
virtual void addNumEntry(const char* l, float* z,
float init, float min, float max, float step)	= 0;
-- passive widgets
virtual void addNumDisplay(const char* l, float* z,
int p) = 0;
virtual void addTextDisplay(const char* l, float* z,
const char* names[], float min, float max) = 0;
virtual void addHorizontalBargraph(const char* l,
float* z, float min, float max) = 0;
virtual void addVerticalBargraph(const char* l,
float* z, float min, float max) = 0;
-- widget layouts
virtual void openTabBox(const char* l)	= 0;
virtual void openHorizontalBox(const char* l)	= 0;
virtual void openVerticalBox(const char* l)	= 0;
virtual	void	closeBox ()	=	0;
-- metadata declarations
virtual void declare(float*, const char*, const char* ) {}

Figure 5.1: UI, the root user interface class.

5.2.1  Active widgets

Active widgets are graphical elements that control a parameter value. They are initialized with the widget name and a pointer to the linked value. The widget currently considered are Button, ToggleButton, CheckButton, VerticalSlider, HorizontalSlider and NumEntry.
A GUI architecture must implement a method
addXxx (const char* name, float* zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry: the init value, the min and max values and the step.

5.2.2  Passive widgets

Passive widgets are graphical elements that reflect values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value. The widget currently considered are NumDisplay, TextDisplay, HorizontalBarGraph and VerticalBarGraph.
A UI architecture must implement a method
addxxx (const char* name, float* zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type.

5.2.3  Widgets layout

Generally, a GUI is hierarchically organized into boxes and/or tab boxes. A UI architecture must support the following methods to setup this hierarchy :
  openTabBox (const char* label)
  openHorizontalBox (const char* label)
  openVerticalBox (const char* label)
  closeBox (const char* label)
Note that all the widgets are added to the current box.

5.2.4  Metadata

The FAUST language allows widget labels to contain metadata enclosed in square brackets. These metadata are handled at GUI level by a declare method taking as argument, a pointer to the widget associated zone, the metadata key and value:
  declare(float* zone, const char* key, const char* value)
UI Comment
console a textual command line UI
GTK a GTK-based GUI
Qt a multi-platform Qt-based GUI
FUI a file-based UI to store and recall modules states
OSC OSC control (see 5.3.1)
Table 5.3: Available UI architectures.

5.3  OSC architecture modules

The OSC support opens FAUST application's control to any OSC capable application or programming language. It also transforms a full range of devices embedding sensors (wiimote, smart phones, ...) into physical interfaces for FAUST application's control, allowing a direct use like musical instruments.
The FAUST OSC architecture is twofold: it is declined as a UI architecture and also as an audio architecture, proposing a new and original way to make digital signal computation.

5.3.1  OSC GUI architecture module

The OSC UI architecture transforms each UI active widget addition into an addnode call, ignores the passive widgets and transforms container calls (openXxxBox, closeBox) into opengroup and closegroup calls.

OSC address space and messages

The OSC address space adheres strictly to the hierarchy defined by the addnode and opengroup, closegroup calls. It supports the OSC pattern matching mechanism.
A node expects to receive OSC messages with a single float value as parameter. This policy is strict for the parameters count, but relaxed for the parameter type: OSC int values are accepted and casted to float.
Audio system Environment OSC support
Alsa GTK, Qt yes
Jack GTK, Qt, Console yes
PortAudio GTK, Qt yes
           Mac OS X
CoreAudio Qt yes
Jack Qt, Console yes
PortAudio Qt yes
Jack Qt, Console yes
PortAudio Qt yes
           iOS (iPhone)
CoreAudio Cocoa not yet
Table 5.4: OSC support in FAUST application's architectures.
Two additional messages are defined to provide FAUST applications discovery and address space discoveries:
  • the hello message: accepted by any module root address. The module responds with its root address, followed by its IP address and the UDP port numbers (listening port, output port, error port). See the network management section below for ports numbering scheme.
  • the get message: accepted by any valid OSC address. The get message is propagated to every terminal node that responds with its OSC address and current values (value, min and max).
Consider the noise module provided with the FAUST examples:
  • it sends /noise 5510 5511 5512
    in answer to a hello message,
  • it sends /noise/Volume 0.8 0. 1.
    in answer to a get message.

Network management.

The OSC module makes use of three different UDP port numbers:
  • 5510 is the listening port number: control messages should be addressed to this port.
  • 5511 is the output port number: answers to query messages are sent to this port.
  • 5512 is the error port number: used for asynchronous error notifications.
When the UDP listening port number is busy (for instance in case of multiple FAUST programs running), the system automatically looks for the next available port number. Unless otherwise specified by the command line, the UDP output port numbers are unchanged.
A program sends its name (actually its root address) and allocated port numbers on the OSC output port on startup.
Port numbers can be changed on the command line with the following options:
    [-port | -outport | -errport] number
The default UDP output streams destination is localhost. It can also be changed with the command line option
    -dest address where address is a host name or an IP number.

5.3.2  OSC message aliases

Alias is a metadata-based mechanism allowing to map arbitrary incoming OSC messages to program parameters. Some remote controllers, like TouchOSC on Android, can only transmit predefined messages, for example /1/push1 1.000000 when push button 1 is pressed, /accxyz -0.421380 0.268151 9.232041 for the x, y and z accelerometers, /1/fader1 0.563994 when fader 1 is moved, etc.
Such messages can be used to control a specific program parameter by inserting an OSC metadata [osc:/path/name] in its label. For example vslider("Volume", 0, 0, 1, 0.1) can be controlled by TouchOSC fader 1 by indicating its OSC address : vslider("Volume[osc:/1/fader1]", 0, 0, 1, 0.1) (see table 5.5 for a more complete list of aliases).
By default the incoming value range is assumed to be between 0 and 1. But it is possible to indicate a different range : [osc:/path/name min max]. When incoming messages provide more than one value it is possible to select the right one with an additional suffix (numbered starting form 0) to the pathname. For instance vslider("Volume[osc:/accxyz/1 -10 10]", 0, 0, 1, 0.1) would allow to control the volume using the y accelerometer. Moreover the accelerometer's values are mapped from range [−10..10] to range [0..1].
alias description
[osc:/1/rotary1] top left rotary knob
[osc:/1/rotary2] middle left rotary knob
[osc:/1/rotary3] bottom left rotary knob
[osc:/1/push1] bottom left push button
[osc:/1/push2] bottom center left push button
[osc:/1/toggle1] top center left toggle button
[osc:/1/toggle2] middle center left toggle button
[osc:/1/fader1] center left vertical fader
[osc:/1/toggle3] top center right toggle button
[osc:/1/toggle4] middle center right toggle button
[osc:/1/fader2] center right vertical toggle button
[osc:/1/rotary4] top right rotary knob
[osc:/1/rotary5] middle right rotary knob
[osc:/1/rotary6] bottom right rotary knob
[osc:/1/push3] bottom center right push button
[osc:/1/push4] bottom right push button
[osc:/1/fader3] bottom horizontal fader
[osc:/accxyz/0 -10 10] x accelerometer
[osc:/accxyz/1 -10 10] y accelerometer
[osc:/accxyz/2 -10 10] z accelerometer
Table 5.5: Examples of OSC message aliases for TouchOSC (layout Mix2). Since most of these messages produce values in the default range [0..1] , there is no need to indicate this range. Accelerometers producing values in a different range, this range [−10..10] has to be indicated.

5.3.3  OSC audio architecture

The OSC audio architecture implements an audio architecture where audio inputs and outputs are replaced by OSC messages. Using this architecture, a FAUST module accepts arbitrary data streams on its root OSC address, and handles this input stream as interleaved signals. Thus, each incoming OSC packet addressed to a module root triggers a computation loop, where as many values as the number of incoming frames are computed.
The output of the signal computation is sent to the OSC output port as non-interleaved data to the OSC addresses /root/n where root is the module root address and n is the output number (indexed from 0).
For example:
consider a FAUST program named split and defined by:
     process = _ <: _,_
the message
     /split 0.3
will produce the 2 following messages as output:
    /split/0 0.3
    /split/1 0.3
The OSC audio architecture provides a very convenient way to execute a signal processing at an arbitrary rate, even allowing to make step by step computation. Connecting the output OSC signals to Max/MSP or to a system like INScore, provides a close examination of the computation results.

Go back to "Faust Reference"

Buy cheap web hosting service where fatcow web hosting review will give you advices and please read bluehost review for more hosting information.
Copyright GRAME 2011 - Powered by Joomla!
Free Joomla Templates designed by Web Hosting Top