Add input csv files of examples to track list.
[Faustine.git] / interpreter / preprocessor / faust-0.9.47mr3 / documentation / faust-quick-reference-src / chapters / architectures.tex
1 %---------------------------------------------------
2 \chapter{Architecture files} \label{sec:audio}
3 %---------------------------------------------------
4
5 A \faust program describes a \emph{signal processor}, a pure computation that maps \emph{input signals} to \emph{output signals}. It says nothing about audio drivers or GUI toolkits. This missing information is provided by \emph{architecture files}.
6
7 %The role of \emph{architecture files} is to provide this missing information.
8
9
10 An \emph{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.).
11
12 The architecture to be used is specified at compile time with the \lstinline'-a' options. For example
13 \lstinline'faust -a jack-gtk.cpp foo.dsp' indicates to use the Jack GTK architecture when compiling \code{foo.dsp}.
14
15 \begin{table}[htdp]
16 \begin{center}
17 \begin{tabular}{|l|l|l|}
18 \hline
19 \textbf{File name} & \textbf{Description} \\
20 \hline
21 \texttt{alchemy-as.cpp} & Flash - ActionScript plugin \\
22 \texttt{ca-qt.cpp} & CoreAudio QT4 standalone application \\
23 \texttt{jack-gtk.cpp} & Jack GTK standalone application \\
24 \texttt{jack-qt.cpp} & Jack QT4 standalone application \\
25 \texttt{jack-console.cpp} & Jack command line application \\
26 \texttt{jack-internal.cpp} & Jack server plugin \\
27 %%\texttt{jack-wx.cpp} & Jack wxWindows standalone application \\
28 \texttt{alsa-gtk.cpp} & ALSA GTK standalone application \\
29 \texttt{alsa-qt.cpp} & ALSA QT4 standalone application \\
30 \texttt{oss-gtk.cpp} & OSS GTK standalone application \\
31 %%\texttt{oss-wx.cpp} & OSS wxWindows standalone application \\
32 \texttt{pa-gtk.cpp} & PortAudio GTK standalone application \\
33 \texttt{pa-qt.cpp} & PortAudio QT4 standalone application \\
34 %%\texttt{pa-wx.cpp} & PortAudio wxWindows standalone application \\
35 \hline
36 \texttt{max-msp.cpp} & Max/MSP external \\
37 \texttt{vst.cpp} & VST plugin \\
38 \texttt{vst2p4.cpp} & VST 2.4 plugin \\
39 \texttt{vsti-mono.cpp} & VSTi mono instrument \\
40 \texttt{ladspa.cpp} & LADSPA plugin \\
41 \texttt{q.cpp} & Q language plugin \\
42 \texttt{supercollider.cpp} & SuperCollider Unit Generator \\
43 \texttt{snd-rt-gtk.cpp} & Snd-RT music programming language \\
44 \texttt{csound.cpp} & CSOUND opcode \\
45 \texttt{puredata.cpp} & PD external \\
46 \hline
47 \texttt{sndfile.cpp} & sound file transformation command \\
48 \texttt{bench.cpp} & speed benchmark \\
49 \texttt{octave.cpp} & Octave plugin \\
50 \texttt{plot.cpp} & Command line application \\
51 \texttt{sndfile.cpp} & Command line application \\
52 \hline
53 \end{tabular}
54 \end{center}
55 \caption{Available architectures.}
56 \label{tab:availablearch}
57 \end{table}%
58
59
60 The main available architecture files are listed table \ref{tab:availablearch}. Since \faust 0.9.40 some of these architectures are a modular combination of an \emph{audio module} and one or more \emph{user interface modules}. Among these user interface modules OSCUI provide supports for Open Sound Control allowing \faust programs to be controlled by OSC messages.
61
62 \section{Audio architecture modules}
63 An \emph{audio architecture module} typically connects a \faust program to the audio drivers.
64 It is responsible for allocating and releasing the audio channels and for calling the \faust \code{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.
65
66 A \faust audio architecture module derives an \emph{audio} class defined as below:
67 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
68 class audio {
69 public:
70 audio() {}
71 virtual ~audio() {}
72 virtual bool init(const char*, dsp*) = 0;
73 virtual bool start() = 0;
74 virtual void stop() = 0;
75 };
76 \end{lstlisting}
77
78
79 The API is simple enough to give a great flexibility to audio architectures implementations. The \code{init} method should initialize the audio. At \code{init} exit, the system should be in a safe state to recall the \code{dsp} object state.
80
81 Table \ref{tab:aarch} gives the audio architectures currently available for various operating systems.
82 \begin{table}[htdp]
83 \begin{center}
84 \begin{tabular}{|c|c|}
85 \hline
86 \bf{Audio system} & \bf{Operating system} \\
87 \hline
88 Alsa & Linux \\
89 Core audio & Mac OS X, iOS \\
90 Jack & Linux, Mac OS X, Windows \\
91 Portaudio & Linux, Mac OS X, Windows \\
92 OSC {\footnotesize (see \ref{sec:oscaudio})} & Linux, Mac OS X, Windows \\
93 VST & Mac OS X, Windows \\
94 Max/MSP & Mac OS X, Windows \\
95 CSound & Linux, Mac OS X, Windows \\
96 SuperCollider & Linux, Mac OS X, Windows \\
97 PureData & Linux, Mac OS X, Windows \\
98 Pure \cite{graef09} & Linux, Mac OS X, Windows \\
99 \hline
100 \end{tabular}
101 \end{center}
102 \caption{\faust audio architectures.}
103 \label{tab:aarch}
104 \end{table}%
105
106
107 % \begin{table}[htdp]
108 % \begin{center}
109 % \begin{tabular}{|c|l|}
110 % \hline
111 % Name & System \\
112 % \hline
113 % ladspa & \href{http://www.ladspa.org/}{LADSPA} plugins \\
114 % csound & \href{http://csounds.com/}{CSOUND} opcodes \\
115 % csounddouble & double precision CSOUND opcodes \\
116 % maxmsp & \href{http://cycling74.com/products/maxmspjitter/}{Max/MSP} externals \\
117 % vst & native \href{http://en.wikipedia.org/wiki/Virtual_Studio_Technology}{VST} plugins \\
118 % w32vst & windows VST plugins \\
119 % supercollider & \href{http://www.audiosynth.com/}{Supercollider} plugins \\
120 % puredata & \href{http://puredata.info/}{Puredata} externals \\
121 % Q & \href{http://q-lang.sourceforge.net/}{Q} plugins \\
122 % Pure & \href{http://code.google.com/p/pure-lang/}{Pure} plugins \\
123 % \hline
124 % \end{tabular}
125 % \end{center}
126 % \caption{\faust plugins architectures}
127 % \label{tab:aarch}
128 % \end{table}%
129 %
130
131
132 %---------------------------------------------------
133 \section{UI architecture modules} \label{sec:gui}
134 %---------------------------------------------------
135
136 A UI architecture module links user actions (via graphic widgets, command line parameters, OSC messages, etc.) with the \faust program to control.
137 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 \code{dsp::buildUserInterface} call, where the \code{dsp} asks a UI object to build the DSP module controllers.
138
139 Since the interface is basically graphic oriented, the main concepts are \emph{widget} based: a UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout.
140
141 A \faust UI architecture module derives an \emph{UI} class (Figure \ref{tab:ui}).
142
143 \begin{figure}[htdp]
144 \begin{center}
145 %\begin{lstlisting}[basicstyle=\ttfamily\tiny\color{yotxt}]
146 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
147 class UI
148 {
149 public:
150 UI() {}
151 virtual ~UI() {}
152
153 -- active widgets
154 virtual void addButton(const char* l, float* z) = 0;
155 virtual void addToggleButton(const char* l, float* z) = 0;
156 virtual void addCheckButton(const char* l, float* z) = 0;
157
158 virtual void addVerticalSlider(const char* l, float* z,
159 float init, float min, float max, float step) = 0;
160
161 virtual void addHorizontalSlider(const char* l, float* z,
162 float init, float min, float max, float step) = 0;
163
164 virtual void addNumEntry(const char* l, float* z,
165 float init, float min, float max, float step) = 0;
166
167 -- passive widgets
168 virtual void addNumDisplay(const char* l, float* z,
169 int p) = 0;
170
171 virtual void addTextDisplay(const char* l, float* z,
172 const char* names[], float min, float max) = 0;
173
174 virtual void addHorizontalBargraph(const char* l,
175 float* z, float min, float max) = 0;
176
177 virtual void addVerticalBargraph(const char* l,
178 float* z, float min, float max) = 0;
179
180 -- widget layouts
181 virtual void openTabBox(const char* l) = 0;
182 virtual void openHorizontalBox(const char* l) = 0;
183 virtual void openVerticalBox(const char* l) = 0;
184 virtual void closeBox() = 0;
185
186 -- metadata declarations
187 virtual void declare(float*, const char*, const char* ) {}
188 };
189 \end{lstlisting}
190 \end{center}
191 \caption{UI, the root user interface class.}
192 \label{tab:ui}
193 \end{figure}
194
195 %---------------------------------------------------
196 \subsection{Active widgets}
197 \label{sec:awidget}
198 Active widgets are graphical elements that control a parameter value. They are initialized with the widget name and a pointer to the linked value.
199 The widget currently considered are \code{Button}, \code{ToggleButton}, \code{CheckButton}, \code{VerticalSlider}, \code{HorizontalSlider} and \code{NumEntry}. \\
200 A GUI architecture must implement a method \\
201 \code{addXxx (const char* name, float* zone, ...)} for each active widget.
202 Additional parameters are available for \code{Slider} and \code{NumEntry}: the \code{init} value, the \code{min} and \code{max} values and the \code{step}.
203
204 %---------------------------------------------------
205 \subsection{Passive widgets}
206 \label{sec:pwidget}
207 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.
208 The widget currently considered are \code{NumDisplay}, \code{TextDisplay}, \code{HorizontalBarGraph} and \code{VerticalBarGraph}. \\
209 A UI architecture must implement a method \\
210 \code{addxxx (const char* name, float* zone, ...)} for each passive widget.
211 Additional parameters are available, depending on the passive widget type.
212
213 %---------------------------------------------------
214 \subsection{Widgets layout}
215 \label{sec:wlayout}
216 Generally, a GUI is hierarchically organized into boxes and/or tab boxes.
217 A UI architecture must support the following methods to setup this hierarchy : \\
218 \htab\code{openTabBox (const char* label)} \\
219 \htab\code{openHorizontalBox (const char* label)} \\
220 \htab\code{openVerticalBox (const char* label)} \\
221 \htab\code{closeBox (const char* label)} \\
222 Note that all the widgets are added to the current box.
223
224 %---------------------------------------------------
225 \subsection{Metadata}
226 \label{sec:metadata}
227 The \faust language allows widget labels to contain metadata enclosed in square brackets. These metadata are handled at GUI level by a \code{declare} method taking as argument, a pointer to the widget associated zone, the metadata key and value: \\
228 \htab\code{declare(float* zone, const char* key, const char* value)} \\
229
230
231 %%Table \ref{tab:uiarch} gives the UI architectures currently available.
232 \begin{table}[htdp]
233 \begin{center}
234 \begin{tabular}{|c|l|}
235 \hline
236 \bf{UI} & \bf{Comment} \\
237 \hline
238 console & a textual command line UI \\
239 GTK & a GTK-based GUI \\
240 Qt & a multi-platform Qt-based GUI \\
241 FUI & a file-based UI to store and recall modules states \\
242 OSC & OSC control (see \ref{sec:oscgui}) \\
243 \hline
244 \end{tabular}
245 \end{center}
246 \caption{Available UI architectures.}
247 \label{tab:uiarch}
248 \end{table}%
249
250
251 %---------------------------------------------------
252 \section{OSC architecture modules} \label{sec:osc}
253 %---------------------------------------------------
254
255 The OSC \cite{OSC} support opens \faust application's control to any OSC capable application or programming language.
256 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.
257
258 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.
259
260 %---------------------------------------------------
261 \subsection{OSC GUI architecture module}
262 \label{sec:oscgui}
263
264 The OSC UI architecture transforms each UI active widget addition into an \code{addnode} call, ignores the passive widgets and transforms container calls (\code{openXxxBox, closeBox}) into \code{opengroup} and \code{closegroup} calls.
265
266 \subsubsection{OSC address space and messages}
267 The OSC address space adheres strictly to the hierarchy defined by the \code{addnode} and \code{opengroup, closegroup} calls. It supports the OSC pattern matching mechanism as described in \cite{OSC}.
268
269 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.
270
271 \begin{table}[htdp]
272 \begin{center}
273 \begin{tabular}{|c|c|c|}
274 \hline
275 \bf{Audio system} & \bf{Environment} & \bf{OSC support} \\
276 \hline
277 \OSTab{Linux} \\
278 %\multicolumn{3}{|l|}{Linux} \\
279 \hline
280 Alsa & GTK, Qt & yes\\
281 Jack & GTK, Qt, Console & yes\\
282 PortAudio & GTK, Qt & yes\\
283 \hline
284 \OSTab{Mac OS X} \\
285 \hline
286 CoreAudio & Qt & yes\\
287 Jack & Qt, Console & yes\\
288 PortAudio & Qt & yes\\
289 \hline
290 \OSTab{Windows} \\
291 \hline
292 Jack & Qt, Console & yes\\
293 PortAudio & Qt & yes\\
294 \hline
295 \OSTab{iOS (iPhone)} \\
296 \hline
297 CoreAudio & Cocoa & not yet\\
298 \hline
299 \end{tabular}
300 \end{center}
301 \caption{OSC support in \faust application's architectures.}
302 \label{tab:oscarch}
303 \end{table}
304
305
306 Two additional messages are defined to provide \faust applications discovery and address space discoveries:
307 \begin{itemize}
308 \item the \code{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).
309 See the network management section below for ports numbering scheme.
310 \item the \code{get} message: accepted by any valid OSC address. The \code{get} message is propagated to every terminal node that responds with its OSC address and current values (value, min and max).
311 \end{itemize}
312
313 \textbf{Example:} \\
314 Consider the \emph{noise} module provided with the \faust examples:
315 \begin{itemize}
316 \item it sends \code{/noise 192.168.0.1 5510 5511 5512} \\in answer to a \code{hello} message,
317 \item it sends \code{/noise/Volume 0.8 0. 1.} \\in answer to a \code{get} message.
318 \end{itemize}
319
320
321 \subsubsection{Network management.}
322 The OSC module makes use of three different UDP port numbers:
323 \begin{itemize}
324 \item 5510 is the listening port number: control messages should be addressed to this port.
325 \item 5511 is the output port number: answers to query messages are sent to this port.
326 \item 5512 is the error port number: used for asynchronous error notifications.
327 \end{itemize}
328
329 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.
330
331 A program sends its name (actually its root address) and allocated port numbers on the OSC output port on startup.
332
333 Port numbers can be changed on the command line with the following options: \\
334 \hspace*{6mm}\lstinline'[-port | -outport | -errport] number'
335
336 The default UDP output streams destination is \code{localhost}. It can also be changed with the command line option \\
337 \hspace*{6mm}\code{-dest address} where address is a host name or an IP number.
338
339 %---------------------------------------------------
340 \subsection{OSC message aliases}
341 \label{sec:oscaudio}
342 Alias is a metadata-based mechanism allowing to map arbitrary incoming OSC messages to program parameters.
343 %%This is convenient when one has no control on the OSC messages emitted.
344 Some remote controllers, like TouchOSC on Android, can only transmit predefined messages, for example \lstinline'/1/push1 1.000000' when push button 1 is pressed, \lstinline'/accxyz -0.421380 0.268151 9.232041' for the x, y and z accelerometers, \lstinline'/1/fader1 0.563994' when fader 1 is moved, etc.
345
346 Such messages can be used to control a specific program parameter by inserting an OSC metadata \lstinline'[osc:/path/name]' in its label. For example \lstinline'vslider("Volume", 0, 0, 1, 0.1)' can be controlled by TouchOSC fader 1 by indicating its OSC address : \lstinline'vslider("Volume[osc:/1/fader1]", 0, 0, 1, 0.1)' (see table \ref{tab:oscalias} for a more complete list of aliases).
347
348 By default the incoming value range is assumed to be between 0 and 1. But it is possible to indicate a different range : \lstinline'[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 \lstinline'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]$.
349
350
351 \begin{table}[htdp]
352 \begin{center}
353 \begin{tabular}{|l|l|}
354 \hline
355 \bf{alias} & \bf{description} \\
356 \hline
357 \lstinline'[osc:/1/rotary1]' & top left rotary knob\\
358 \lstinline'[osc:/1/rotary2]' & middle left rotary knob\\
359 \lstinline'[osc:/1/rotary3]' & bottom left rotary knob\\
360 \lstinline'[osc:/1/push1]' & bottom left push button\\
361 \lstinline'[osc:/1/push2]' & bottom center left push button\\
362 \hline
363 \lstinline'[osc:/1/toggle1]' & top center left toggle button\\
364 \lstinline'[osc:/1/toggle2]' & middle center left toggle button\\
365 \lstinline'[osc:/1/fader1]' & center left vertical fader\\
366 \hline
367 \lstinline'[osc:/1/toggle3]' & top center right toggle button\\
368 \lstinline'[osc:/1/toggle4]' & middle center right toggle button\\
369 \lstinline'[osc:/1/fader2]' & center right vertical toggle button\\
370 \hline
371 \lstinline'[osc:/1/rotary4]' & top right rotary knob\\
372 \lstinline'[osc:/1/rotary5]' & middle right rotary knob\\
373 \lstinline'[osc:/1/rotary6]' & bottom right rotary knob\\
374 \lstinline'[osc:/1/push3]' & bottom center right push button\\
375 \lstinline'[osc:/1/push4]' & bottom right push button\\
376 \hline
377 \lstinline'[osc:/1/fader3]' & bottom horizontal fader\\
378 \hline
379 \lstinline'[osc:/accxyz/0 -10 10]' & $x$ accelerometer\\
380 \lstinline'[osc:/accxyz/1 -10 10]' & $y$ accelerometer\\
381 \lstinline'[osc:/accxyz/2 -10 10]' & $z$ accelerometer\\
382 \hline
383 \end{tabular}
384 \end{center}
385 \caption{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. }
386 \label{tab:oscalias}
387 \end{table}
388
389
390 %---------------------------------------------------
391 \subsection{OSC audio architecture}
392 \label{sec:oscaudio}
393
394 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.
395
396 The output of the signal computation is sent to the OSC output port as non-interleaved data to the OSC addresses \code{/root/n} where \code{root} is the module root address and \code{n} is the output number (indexed from 0).
397
398 For example: \\
399 consider a \faust program named \emph{split} and defined by:\\
400 \hspace*{6mm} \lstinline'process = _ <: _,_' \\
401 the message \\
402 \hspace*{6mm} \code{/split 0.3}
403 \\ will produce the 2 following messages as output: \\
404 \hspace*{6mm}\code{/split/0 0.3}\\
405 \hspace*{6mm}\code{/split/1 0.3}
406
407
408 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\footnote{\url{http://inscore.sf.net}}\cite{Fober:10c}, provides a close examination of the computation results.
409