
\documentclass[a4paper]{article}
\usepackage{pslatex}
\usepackage[T1]{fontenc}
\usepackage[utf8x]{inputenc}
\setlength\parskip{\medskipamount}
\setlength\parindent{0pt}
\usepackage{graphicx}
\usepackage{amssymb}
%\usepackage{hyperref}

\makeatletter

\providecommand{\boldsymbol}[1]{\mbox{\boldmath $#1$}}
\newcommand{\ASL}			{ASL}
\newcommand{\OSC}[1]		{\texttt{#1}}
\newcommand{\lra}			{$\leftrightarrow$}
\newcommand{\seg}[1]		{Seg(#1)}

\setlength{\parskip}{1mm}

\makeatother

\begin{document}

\title{FaustLive - User Manual \\ v.2.44}

\author{Grame, Centre National de Création Musicale\\
{\small <research@grame.fr>} \\
\vspace{2mm}
[ANR-12-CORD- 0009] and [ANR-13-BS02-0008]
}

\maketitle

\topskip0pt

\vspace{\fill}

FaustLive is an advanced self-contained prototyping environment for the Faust programming language with an ultra-short edit-compile-run cycle. Thanks to its fully embedded compilation chain, FaustLive is simple to install and doesn't require any external compiler, development toolchain or SDK to run. \\

FaustLive is the ideal tool for fast prototyping. Faust programs can be compiled and run on the fly by simple drag and drop. They can even be edited and recompiled while running without sound interruption or JACK disconnection.
\vspace{\fill}
%==================================================================================================
\newpage
\tableofcontents

\newpage
\section{Dynamic Compilation}
FaustLive embeds a full compilation chain to provide an ultra-short edit-compile-run cycle.
The ensuing features are :

\subsection{Open a DSP}
The Faust file you choose to open is compiled and runs into FaustLive.
\begin{itemize}
\item Open ... : you can open a file saved on your disk
\item Open Example : you can open an example from the list
\item Open Recent File : the recently closed DSP are saved in this list
%\item Open Remote DSP : FaustLive can scan the DSPs published by another user (c.f. publish DSP) and allows you to get an instance of them. If the owner of the DSP shut his connection or unpublishes his DSP, yours will be closed too. 
\end{itemize}


\subsection{Drag and Drop}
On a running application, you can drop Faust code as :
\begin{itemize}
\item A string \\process=+;
\item A .dsp file \\/Users/you/Desktop/plus.dsp
\item A URL \\http://faust.grame.fr/www/vumeter.dsp
\item A .wav file \\/Users/you/Desktop/myBird.wav
\end{itemize}
The dropped code is compiled and the new application replaces the previous one.

\subsection{Paste} 
You can also paste Faust code with the same result as Drag and Drop.

\subsection{Dynamic source edition}
You can choose to edit your Faust code. The file is opened in the default application for .dsp files (Don't forget to configure file association : c.f README). Everytime you will save your code in the editor, your running DSP will be updated. \\

Three cases exist, depending on the origin of your application. In case the origin of your application is
	\begin{itemize}
		\item A file :  it is opened
		\item Not a file (string, url, example, ...) : you are asked to save your Faust content in a new file.
		\begin{itemize}
		\item If you choose to save it, your new file is opened and becomes the new origin of your DSP.
		\item If you don't want to save it on disk, a temporary file is created and opened. The origin of your DSP remains a string.
	\end{itemize}

	\end{itemize}

\section{Window-specific actions}

\subsection{Crossfade Characteristics}

When the DSP is modified or switched within a window (drag and drop, source edition, ...), the two applications are crossfaded to avoid brutal interruption in the sound. If you are using JACK as audio driver, the connection remain for the common ports. If there are new ports, it is left to the user to connect them. 

\subsection{Reversed Drag and Drop}
You can drag your Faust code from your window to another window or another application like your Desktop, Browser, Text editor, ...

\subsection{View SVG Diagram}
You can view your SVG Diagram in the default application for .svg (Don't forget to configure file association : c.f README). Everytime your DSP is modified, the SVG diagram is updated.

\subsection{Duplicate Window}
A Window can be duplicated with all it's parameters (graphical params, audio connections, compilation options, etc)

\subsection{Export}
Thanks to the remote compilation service, FaustWeb, you can export your Faust code into any kind of available application or plugin. 

\subsection{Control Interfaces}
You can duplicate the control interface of your application. The local and remote interfaces are synchronized.

\subsubsection{HTTP Interface}
	You can control your application on a browser through an HTTP interface. To enable this feature, you have two possibilities :
	\begin{itemize}
	\item In "Parameters", in the "HTTP Interface" tab, check "Enable Interface"
	\item In "Preferences", in the  "Network" tab, check "Enable HTTP Interface automatically" (any new window will be enabled for HTTP control)
	\end{itemize}
	
The port it starts on is updated in the parameters. The default port is 5510.\\
	To access the interface, you can enter the address in your browser : http://yourIPaddress:port.	
	Or, you can choose view QrCode then scan the code with your device to access the page directly. 

\subsubsection{OSC Interface}
	You can control your application remotely with the OSC protocol. 
	To enable this feature, you have two possibilities :
	\begin{itemize}
	\item In "Parameters", in the "OSC Interface" tab, check "Enable Interface"
	\item In "Preferences", in the "Network" tab, check "Enable OSC Interface automatically" (any new window will be enabled for OSC control)
	\end{itemize}
	You can choose the port for incoming/outcoming and error messages. The destination IP for outcoming messages will be automatically set when the first message is received. 

\subsubsection{MIDI Interface}
	You can control your application with a MIDI controller. To enable this feature, you have the following possibility :
	\begin{itemize}
	\item In "Parameters", in the "MIDI Interface" tab, check "Enable Interface"
	\end{itemize}

%\subsection{Remote Control}
%You can control your application remotly with a native application for iOS, android that you can download from Faust directory on sourceforge.  To enable this feature, go to "Parameters", in the tab "Remote Control", check "Enable". The destination IP will be automatically set when the first message is received. \\

%With this feature, you can choose whether the sound is rendered on FaustLive's machine or on the remote device. 

%\subsection{Publish DSP}
%You can publish your DSP for any FaustLive user to see. This way, another user can get an instance of your application from his own machine (c.f Open Remote DSP...). The local and remote instance are totally independent. Both have an independent access to the interface and audio rendering.

%\subsection{Remote Processing}
%You can choose to send your code to another machine, presenting the remote server service. A discovery shows you the available machines. Once you have switched, your Faust processing will be done on the remote machine. The control interface and sound rendering stay on the local machine.

\subsection{Polyphonic support}

By convention Faust architecture files with polyphonic MIDI capabilities expect to find a \textit{freq}, a \textit{gain} and a \textit{gate} user interface parameter :
{\small 
\begin{verbatim} 

midigate	= button ("gate");                             			// MIDI keyon-keyoff
midifreq	= hslider("freq[unit:Hz]", 440, 20, 20000, 1); 	// MIDI keyon key
midigain	= hslider("gain", 0.5, 0, 10, 0.01);	      	 	  // MIDI keyon velocity

\end{verbatim} 
}

The polyphonic architecture will automatically allocates voice for the instrument and takes care of dynamic voice allocations and control MIDI messages decoding and mapping.  By convention all allocated voices are grouped in a global “tabgroup”, so that a user interface builder may display them separately. 

Then this dsp object can be used as usual and connected with the wanted audio driver and possibly other UI control objects like OSC, HTTP interfaces, etc. Having this UI hierarchical view allows for instance complete OSC control of each single voice and its control parameters. 

The number of voices for the polyphonic instrument can be chosen in "Parameters", in the "Polyphony support". Voices are globally controllable with a "All Voices" tab, and this tab can possibly be made the only visible UI. 

The polyphonic instrument can then be controlled with MIDI messages by checking the  "Enable Interface" in the "MIDI Interface" tab.

\subsection{Compilation Options}

\begin{itemize}

\item Code Generation Options : In the parameters, you can change the compilation options of your running DSP. Faust compilation options are available in Faust documentation. LLVM optimization level is a number contained between 0 and 3. 

\item Additional Compilation Step : a new call to the Faust compiler is executed with new output feature (for example : -lang ajs -o filename.js). This call will be added to any compilation/recompilation within the window.

\item Post-Compilation Script : after all the compilation steps, you can add an arbitrary command line.

\end{itemize}

\section{General Actions}

\subsection{Take Snapshot}
 When you take a snapshot, the state of your application is saved : all the windows, their parameters (graphical parameters, connections, position on screen, compilation options, etc, ...). The created archive is a .tar (platform-independent) that you can then reload on any FaustLive. 

\subsection{Recall/Import Snapshot}
You have two different ways to reload a snapshot into FaustLive : 
\begin{itemize}
\item Recall Snapshot : closes all the current windows to restore the exact state that you saved in your snapshot.
\item Import Snapshot : adds the content of your snapshot to the current state of the application. 
\end{itemize}

In case your source files were modified or deleted outside of FaustLive's execution, an internal copy of your files will be used to restore the state. 

\subsection{Open Component Creator}
The component creator is a tool to combine your DSPs. The columns represent parallel composition and the rows sequential composition. You can add as many rows and columns as you like. You can also have a feedback DSP. The resulting DSP is a sequence of parallel components. \\

The parallel composition is "stereoized" before being put it sequence. And the recursive composition with the feedback DSP is "recursivized". This way, the resulting DSP always has 2 inputs and 2 outputs. To know the detail of the functions stereoize and recursivize, see music.lib. 


\subsection{Close All Windows}
You can close every window without quitting FaustLive and without saving them.

\subsection{Quit FaustLive}

When you quit FaustLive, the state of the application is saved, so that it can be recalled at the next execution of FaustLive.

\subsection{General preferences}
\subsubsection{Compilation Options}
Any changes in the compilation options will be taken into account for all the new windows created. The one already running keep their parameters.
\subsubsection{Audio}
 
Depending on your operating system and on your version of FaustLive, certain drivers are or not available.
The default drivers are :
\begin{itemize}
\item CoreAudio on OSX
\item JACK on Linux
\item PortAudio on Windows
\end{itemize}

When you switch the audio architecture or its parameters, every running window is switching. The audio clients stop, the architecture is switched and the audio clients are restarted. If the update is not successfull, the previous architecture is restored. If it cannot be restored, the windows are closed. 

\subsubsection{Network}
\begin{itemize}
\item Enable HTTP interface automatically
\item Enable OSC interface automatically
\item Remote Compilation service : by default, FaustLive uses faustservice.grame.fr as compilation service but you can choose any another FaustWeb service.
\item Remote Dropping Port : port used to start the internal server, taking care of drops on html remote interfaces.

\end{itemize}

\subsubsection{Style}
The style is automatically changed when you click the style button. You don't have to save the changes to keep the style preference. 

%\subsection{DNS OSC}
%
%\subsection{DNS HTTP}

\end{document}




