From 54b39ed611b6ac7bd0eed86705fe594dc3d36328 Mon Sep 17 00:00:00 2001
From: Stephane Letz <letz@grame.fr>
Date: Mon, 2 Sep 2024 10:21:18 +0200
Subject: [PATCH] Typos.

---
 docs/index.html                  |   2 +-
 docs/manual/deploying/index.html |   8 ++++----
 docs/search/search_index.json    |   2 +-
 docs/sitemap.xml.gz              | Bin 127 -> 127 bytes
 mkdocs/docs/manual/deploying.md  |   8 ++++----
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 536b18420b..a89eb34477 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -477,5 +477,5 @@ <h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
 
 <!--
 MkDocs version : 1.4.3
-Build Date UTC : 2024-08-26 12:16:02.030884+00:00
+Build Date UTC : 2024-09-02 08:21:05.525978+00:00
 -->
diff --git a/docs/manual/deploying/index.html b/docs/manual/deploying/index.html
index 25ab7b87c7..31d313d69a 100644
--- a/docs/manual/deploying/index.html
+++ b/docs/manual/deploying/index.html
@@ -358,16 +358,16 @@ <h2 id="exporting-for-the-web">Exporting for the Web</h2>
 <p>Web targets can be exported from the <a href="https://fausteditor.grame.fr">Faust Editor</a> or <a href="https://faustide.grame.fr">Faust IDE</a> using the remote compilation service. Choose <code>Platform = web</code>, then <code>Architecture</code> with one of the following target:</p>
 <ul>
 <li>
-<p><code>wasmjs</code> allows you to export a ready to use Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.</p>
+<p><code>wasmjs</code> allows you to export a ready to use Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.</p>
 </li>
 <li>
-<p><code>wasmjs-poly</code> allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.</p>
+<p><code>wasmjs-poly</code> allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.</p>
 </li>
 <li>
-<p><code>webaudiowasm</code> allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a <a href="https://en.wikipedia.org/wiki/Progressive_web_app">Progressive Web Application</a>. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.</p>
+<p><code>webaudiowasm</code> allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a <a href="https://en.wikipedia.org/wiki/Progressive_web_app">Progressive Web Application</a>. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.</p>
 </li>
 <li>
-<p><code>webaudiowasm-poly</code> allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a <a href="https://en.wikipedia.org/wiki/Progressive_web_app">Progressive Web Application</a>. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.</p>
+<p><code>webaudiowasm-poly</code> allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a <a href="https://en.wikipedia.org/wiki/Progressive_web_app">Progressive Web Application</a>. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.</p>
 </li>
 <li>
 <p><code>pwa</code> allows you to export a ready to use <a href="https://en.wikipedia.org/wiki/Progressive_web_app">Progressive Web Application</a> with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code.</p>
diff --git a/docs/search/search_index.json b/docs/search/search_index.json
index a191da084d..8a56b08367 100644
--- a/docs/search/search_index.json
+++ b/docs/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Faust Language Documentation This website centralizes all the documentation of the Faust programming language . It contains tutorials, the Faust manual, various examples, etc. It is meant to be used in tandem with the Faust Web IDE . The main Faust website can be found at the following URL: https://faust.grame.fr What is Faust? Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. Getting Started If You're In a Hurry If you\u2019re in a hurry and just wanna have a look at how Faust programs look like, you can simply check the Faust Examples . If You Wanna Get Started With Faust If you\u2019re looking for a step by step tutorial of approximately 2 hours that will walk you through writing simple Faust programs and give you an overview of what Faust can do, have a look at our Quick Start Tutorial . If You\u2019re Looking For the \"Manual\" Faust\u2019s syntax and features are thoroughly documented in the Faust Manual . This resource contains hundreds of code examples and many short tutorials. If You\u2019re Looking For the Documentation of a Function In the Faust Libraries The documentation of Faust's standard libraries is automatically generated directly from the libraries' source code. If You Prefer Video Tutorials Check out the Faust Kadenze course . If You're Looking For Something in Particular You can use the Search function of this website if you're looking for something specific. Other Resources to learn Faust","title":"Home"},{"location":"#faust-language-documentation","text":"This website centralizes all the documentation of the Faust programming language . It contains tutorials, the Faust manual, various examples, etc. It is meant to be used in tandem with the Faust Web IDE . The main Faust website can be found at the following URL: https://faust.grame.fr","title":"Faust Language Documentation"},{"location":"#what-is-faust","text":"Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc.","title":"What is Faust?"},{"location":"#getting-started","text":"","title":"Getting Started"},{"location":"#if-youre-in-a-hurry","text":"If you\u2019re in a hurry and just wanna have a look at how Faust programs look like, you can simply check the Faust Examples .","title":"If You're In a Hurry"},{"location":"#if-you-wanna-get-started-with-faust","text":"If you\u2019re looking for a step by step tutorial of approximately 2 hours that will walk you through writing simple Faust programs and give you an overview of what Faust can do, have a look at our Quick Start Tutorial .","title":"If You Wanna Get Started With Faust"},{"location":"#if-youre-looking-for-the-manual","text":"Faust\u2019s syntax and features are thoroughly documented in the Faust Manual . This resource contains hundreds of code examples and many short tutorials.","title":"If You\u2019re Looking For the \"Manual\""},{"location":"#if-youre-looking-for-the-documentation-of-a-function-in-the-faust-libraries","text":"The documentation of Faust's standard libraries is automatically generated directly from the libraries' source code.","title":"If You\u2019re Looking For the Documentation of a Function In the Faust Libraries"},{"location":"#if-you-prefer-video-tutorials","text":"Check out the Faust Kadenze course .","title":"If You Prefer Video Tutorials"},{"location":"#if-youre-looking-for-something-in-particular","text":"You can use the Search function of this website if you're looking for something specific.","title":"If You're Looking For Something in Particular"},{"location":"#other-resources-to-learn-faust","text":"","title":"Other Resources to learn Faust"},{"location":"about/","text":"The Faust Project The Faust Project has started in 2002. It is actively developed by the GRAME-CNCM Research Department . Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen, Karim Barkati, J\u00e9r\u00f4me Barth\u00e9lemy, Tim Blechmann, Tiziano Bole, Alain Bonardi, Bart Brouns, Thomas Charbonnel, Raffaele Ciavarella, Ian Clester, Julien Colafrancesco, Damien Cramet, Sarah Denoux, \u00c9tienne Gaudrin, Olivier Guillerminet, Pierre Guillot, Albert Gr\u00e4f, Christoph Hart, Agathe Herrou, Pierre Jouvelot, Stefan Kersten, Victor Lazzarini, Matthieu Leberre, Mathieu Leroi, Fernando Lopez-Lezcano, Kjetil Matheussen, Hermann Meyer, R\u00e9my Muller, Raphael Panis, Eliott Paris, Reza Payami, Laurent Pottier, Dirk Roosenburg, Sampo Savolainen, Nicolas Scaringella, Anne Sedes, Priyanka Shekar, Stephen Sinclair, Travis Skare, Julius Smith, Mike Solomon, Roman Sommer Michael Wilson. as well as our colleagues at GRAME : Dominique Fober Christophe Lebreton St\u00e9phane Letz Romain Michon Yann Orlarey We would like also to thank for their financial support: the French Ministry of Culture , the Auvergne-Rh\u00f4ne-Alpes Region , the City of Lyon , the French National Research Agency (ANR) .","title":"About"},{"location":"about/#the-faust-project","text":"The Faust Project has started in 2002. It is actively developed by the GRAME-CNCM Research Department . Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen, Karim Barkati, J\u00e9r\u00f4me Barth\u00e9lemy, Tim Blechmann, Tiziano Bole, Alain Bonardi, Bart Brouns, Thomas Charbonnel, Raffaele Ciavarella, Ian Clester, Julien Colafrancesco, Damien Cramet, Sarah Denoux, \u00c9tienne Gaudrin, Olivier Guillerminet, Pierre Guillot, Albert Gr\u00e4f, Christoph Hart, Agathe Herrou, Pierre Jouvelot, Stefan Kersten, Victor Lazzarini, Matthieu Leberre, Mathieu Leroi, Fernando Lopez-Lezcano, Kjetil Matheussen, Hermann Meyer, R\u00e9my Muller, Raphael Panis, Eliott Paris, Reza Payami, Laurent Pottier, Dirk Roosenburg, Sampo Savolainen, Nicolas Scaringella, Anne Sedes, Priyanka Shekar, Stephen Sinclair, Travis Skare, Julius Smith, Mike Solomon, Roman Sommer Michael Wilson. as well as our colleagues at GRAME : Dominique Fober Christophe Lebreton St\u00e9phane Letz Romain Michon Yann Orlarey We would like also to thank for their financial support: the French Ministry of Culture , the Auvergne-Rh\u00f4ne-Alpes Region , the City of Lyon , the French National Research Agency (ANR) .","title":"The Faust Project"},{"location":"examples/SAM/","text":"SAM","title":" SAM "},{"location":"examples/SAM/#sam","text":"","title":"SAM"},{"location":"examples/ambisonics/","text":"ambisonics fourSourcesToOcto oneSourceToStereo","title":" ambisonics "},{"location":"examples/ambisonics/#ambisonics","text":"","title":"ambisonics"},{"location":"examples/ambisonics/#foursourcestoocto","text":"","title":"fourSourcesToOcto"},{"location":"examples/ambisonics/#onesourcetostereo","text":"","title":"oneSourceToStereo"},{"location":"examples/analysis/","text":"analysis FFT dbmeter spectralLevel spectralTiltLab vumeter","title":" analysis "},{"location":"examples/analysis/#analysis","text":"","title":"analysis"},{"location":"examples/analysis/#fft","text":"","title":"FFT"},{"location":"examples/analysis/#dbmeter","text":"","title":"dbmeter"},{"location":"examples/analysis/#spectrallevel","text":"","title":"spectralLevel"},{"location":"examples/analysis/#spectraltiltlab","text":"","title":"spectralTiltLab"},{"location":"examples/analysis/#vumeter","text":"","title":"vumeter"},{"location":"examples/autodiff/","text":"autodiff noise noop ramp","title":"autodiff"},{"location":"examples/autodiff/#autodiff","text":"","title":"autodiff"},{"location":"examples/autodiff/#noise","text":"","title":"noise"},{"location":"examples/autodiff/#noop","text":"","title":"noop"},{"location":"examples/autodiff/#ramp","text":"","title":"ramp"},{"location":"examples/bela/","text":"bela AdditiveSynth AdditiveSynth_Analog FMSynth2 FMSynth2_Analog FMSynth2_FX FMSynth2_FX_Analog FXChaine2 GrainGenerator WaveSynth WaveSynth_Analog WaveSynth_FX WaveSynth_FX_Analog crossDelay2 granulator repeater simpleFX simpleFX_Analog simpleSynth simpleSynth_Analog simpleSynth_FX simpleSynth_FX_Analog trill_simple_monophonic_keyboard trill_simple_polyphonic_keyboard","title":" bela "},{"location":"examples/bela/#bela","text":"","title":"bela"},{"location":"examples/bela/#additivesynth","text":"","title":"AdditiveSynth"},{"location":"examples/bela/#additivesynth_analog","text":"","title":"AdditiveSynth_Analog"},{"location":"examples/bela/#fmsynth2","text":"","title":"FMSynth2"},{"location":"examples/bela/#fmsynth2_analog","text":"","title":"FMSynth2_Analog"},{"location":"examples/bela/#fmsynth2_fx","text":"","title":"FMSynth2_FX"},{"location":"examples/bela/#fmsynth2_fx_analog","text":"","title":"FMSynth2_FX_Analog"},{"location":"examples/bela/#fxchaine2","text":"","title":"FXChaine2"},{"location":"examples/bela/#graingenerator","text":"","title":"GrainGenerator"},{"location":"examples/bela/#wavesynth","text":"","title":"WaveSynth"},{"location":"examples/bela/#wavesynth_analog","text":"","title":"WaveSynth_Analog"},{"location":"examples/bela/#wavesynth_fx","text":"","title":"WaveSynth_FX"},{"location":"examples/bela/#wavesynth_fx_analog","text":"","title":"WaveSynth_FX_Analog"},{"location":"examples/bela/#crossdelay2","text":"","title":"crossDelay2"},{"location":"examples/bela/#granulator","text":"","title":"granulator"},{"location":"examples/bela/#repeater","text":"","title":"repeater"},{"location":"examples/bela/#simplefx","text":"","title":"simpleFX"},{"location":"examples/bela/#simplefx_analog","text":"","title":"simpleFX_Analog"},{"location":"examples/bela/#simplesynth","text":"","title":"simpleSynth"},{"location":"examples/bela/#simplesynth_analog","text":"","title":"simpleSynth_Analog"},{"location":"examples/bela/#simplesynth_fx","text":"","title":"simpleSynth_FX"},{"location":"examples/bela/#simplesynth_fx_analog","text":"","title":"simpleSynth_FX_Analog"},{"location":"examples/bela/#trill_simple_monophonic_keyboard","text":"","title":"trill_simple_monophonic_keyboard"},{"location":"examples/bela/#trill_simple_polyphonic_keyboard","text":"","title":"trill_simple_polyphonic_keyboard"},{"location":"examples/delayEcho/","text":"delayEcho echo quadEcho smoothDelay stereoEcho tapiir","title":" delayEcho "},{"location":"examples/delayEcho/#delayecho","text":"","title":"delayEcho"},{"location":"examples/delayEcho/#echo","text":"","title":"echo"},{"location":"examples/delayEcho/#quadecho","text":"","title":"quadEcho"},{"location":"examples/delayEcho/#smoothdelay","text":"","title":"smoothDelay"},{"location":"examples/delayEcho/#stereoecho","text":"","title":"stereoEcho"},{"location":"examples/delayEcho/#tapiir","text":"","title":"tapiir"},{"location":"examples/dynamic/","text":"dynamic compressor distortion gateCompressor noiseGate volume","title":" dynamic "},{"location":"examples/dynamic/#dynamic","text":"","title":"dynamic"},{"location":"examples/dynamic/#compressor","text":"","title":"compressor"},{"location":"examples/dynamic/#distortion","text":"","title":"distortion"},{"location":"examples/dynamic/#gatecompressor","text":"","title":"gateCompressor"},{"location":"examples/dynamic/#noisegate","text":"","title":"noiseGate"},{"location":"examples/dynamic/#volume","text":"","title":"volume"},{"location":"examples/filtering/","text":"filtering APF BPF DNN HPF LPF bandFilter cryBaby diodeLadder filterBank graphicEqLab highShelf korg35HPF korg35LPF lfBoost lowBoost lowCut lowShelf moogHalfLadder moogLadder moogVCF notch oberheim oberheimBPF oberheimBSF oberheimHPF oberheimLPF parametricEqLab parametricEqualizer peakNotch peakingEQ sallenKey2ndOrder sallenKey2ndOrderBPF sallenKey2ndOrderHPF sallenKey2ndOrderLPF sallenKeyOnePole sallenKeyOnePoleHPF sallenKeyOnePoleLPF spectralTilt vcfWahLab vocoder wahPedal","title":" filtering "},{"location":"examples/filtering/#filtering","text":"","title":"filtering"},{"location":"examples/filtering/#apf","text":"","title":"APF"},{"location":"examples/filtering/#bpf","text":"","title":"BPF"},{"location":"examples/filtering/#dnn","text":"","title":"DNN"},{"location":"examples/filtering/#hpf","text":"","title":"HPF"},{"location":"examples/filtering/#lpf","text":"","title":"LPF"},{"location":"examples/filtering/#bandfilter","text":"","title":"bandFilter"},{"location":"examples/filtering/#crybaby","text":"","title":"cryBaby"},{"location":"examples/filtering/#diodeladder","text":"","title":"diodeLadder"},{"location":"examples/filtering/#filterbank","text":"","title":"filterBank"},{"location":"examples/filtering/#graphiceqlab","text":"","title":"graphicEqLab"},{"location":"examples/filtering/#highshelf","text":"","title":"highShelf"},{"location":"examples/filtering/#korg35hpf","text":"","title":"korg35HPF"},{"location":"examples/filtering/#korg35lpf","text":"","title":"korg35LPF"},{"location":"examples/filtering/#lfboost","text":"","title":"lfBoost"},{"location":"examples/filtering/#lowboost","text":"","title":"lowBoost"},{"location":"examples/filtering/#lowcut","text":"","title":"lowCut"},{"location":"examples/filtering/#lowshelf","text":"","title":"lowShelf"},{"location":"examples/filtering/#mooghalfladder","text":"","title":"moogHalfLadder"},{"location":"examples/filtering/#moogladder","text":"","title":"moogLadder"},{"location":"examples/filtering/#moogvcf","text":"","title":"moogVCF"},{"location":"examples/filtering/#notch","text":"","title":"notch"},{"location":"examples/filtering/#oberheim","text":"","title":"oberheim"},{"location":"examples/filtering/#oberheimbpf","text":"","title":"oberheimBPF"},{"location":"examples/filtering/#oberheimbsf","text":"","title":"oberheimBSF"},{"location":"examples/filtering/#oberheimhpf","text":"","title":"oberheimHPF"},{"location":"examples/filtering/#oberheimlpf","text":"","title":"oberheimLPF"},{"location":"examples/filtering/#parametriceqlab","text":"","title":"parametricEqLab"},{"location":"examples/filtering/#parametricequalizer","text":"","title":"parametricEqualizer"},{"location":"examples/filtering/#peaknotch","text":"","title":"peakNotch"},{"location":"examples/filtering/#peakingeq","text":"","title":"peakingEQ"},{"location":"examples/filtering/#sallenkey2ndorder","text":"","title":"sallenKey2ndOrder"},{"location":"examples/filtering/#sallenkey2ndorderbpf","text":"","title":"sallenKey2ndOrderBPF"},{"location":"examples/filtering/#sallenkey2ndorderhpf","text":"","title":"sallenKey2ndOrderHPF"},{"location":"examples/filtering/#sallenkey2ndorderlpf","text":"","title":"sallenKey2ndOrderLPF"},{"location":"examples/filtering/#sallenkeyonepole","text":"","title":"sallenKeyOnePole"},{"location":"examples/filtering/#sallenkeyonepolehpf","text":"","title":"sallenKeyOnePoleHPF"},{"location":"examples/filtering/#sallenkeyonepolelpf","text":"","title":"sallenKeyOnePoleLPF"},{"location":"examples/filtering/#spectraltilt","text":"","title":"spectralTilt"},{"location":"examples/filtering/#vcfwahlab","text":"","title":"vcfWahLab"},{"location":"examples/filtering/#vocoder","text":"","title":"vocoder"},{"location":"examples/filtering/#wahpedal","text":"","title":"wahPedal"},{"location":"examples/gameaudio/","text":"gameaudio bubble complex_rain door fire insects rain thunder wind windchimes","title":" gameaudio "},{"location":"examples/gameaudio/#gameaudio","text":"","title":"gameaudio"},{"location":"examples/gameaudio/#bubble","text":"","title":"bubble"},{"location":"examples/gameaudio/#complex_rain","text":"","title":"complex_rain"},{"location":"examples/gameaudio/#door","text":"","title":"door"},{"location":"examples/gameaudio/#fire","text":"","title":"fire"},{"location":"examples/gameaudio/#insects","text":"","title":"insects"},{"location":"examples/gameaudio/#rain","text":"","title":"rain"},{"location":"examples/gameaudio/#thunder","text":"","title":"thunder"},{"location":"examples/gameaudio/#wind","text":"","title":"wind"},{"location":"examples/gameaudio/#windchimes","text":"","title":"windchimes"},{"location":"examples/generator/","text":"generator churchOrgan filterOsc noise noiseMetadata osc osci sawtoothLab virtualAnalog virtualAnalogLab","title":" generator "},{"location":"examples/generator/#generator","text":"","title":"generator"},{"location":"examples/generator/#churchorgan","text":"","title":"churchOrgan"},{"location":"examples/generator/#filterosc","text":"","title":"filterOsc"},{"location":"examples/generator/#noise","text":"","title":"noise"},{"location":"examples/generator/#noisemetadata","text":"","title":"noiseMetadata"},{"location":"examples/generator/#osc","text":"","title":"osc"},{"location":"examples/generator/#osci","text":"","title":"osci"},{"location":"examples/generator/#sawtoothlab","text":"","title":"sawtoothLab"},{"location":"examples/generator/#virtualanalog","text":"","title":"virtualAnalog"},{"location":"examples/generator/#virtualanaloglab","text":"","title":"virtualAnalogLab"},{"location":"examples/misc/","text":"misc UITester autopan capture drumkit matrix midiTester statespace switcher tester tester2","title":" misc "},{"location":"examples/misc/#misc","text":"","title":"misc"},{"location":"examples/misc/#uitester","text":"","title":"UITester"},{"location":"examples/misc/#autopan","text":"","title":"autopan"},{"location":"examples/misc/#capture","text":"","title":"capture"},{"location":"examples/misc/#drumkit","text":"","title":"drumkit"},{"location":"examples/misc/#matrix","text":"","title":"matrix"},{"location":"examples/misc/#miditester","text":"","title":"midiTester"},{"location":"examples/misc/#statespace","text":"","title":"statespace"},{"location":"examples/misc/#switcher","text":"","title":"switcher"},{"location":"examples/misc/#tester","text":"","title":"tester"},{"location":"examples/misc/#tester2","text":"","title":"tester2"},{"location":"examples/phasing/","text":"phasing flanger phaser phaserFlangerLab","title":" phasing "},{"location":"examples/phasing/#phasing","text":"","title":"phasing"},{"location":"examples/phasing/#flanger","text":"","title":"flanger"},{"location":"examples/phasing/#phaser","text":"","title":"phaser"},{"location":"examples/phasing/#phaserflangerlab","text":"","title":"phaserFlangerLab"},{"location":"examples/physicalModeling/","text":"physicalModeling brass brassMIDI churchBell clarinet clarinetMIDI djembeMIDI elecGuitarMIDI englishBell flute fluteMIDI frenchBell germanBell guitarMIDI karplus marimbaMIDI modularInterpInstrMIDI nylonGuitarMIDI russianBell standardBell violin violinMIDI vocalBP vocalBPMIDI vocalFOF vocalFOFMIDI","title":" physicalModeling "},{"location":"examples/physicalModeling/#physicalmodeling","text":"","title":"physicalModeling"},{"location":"examples/physicalModeling/#brass","text":"","title":"brass"},{"location":"examples/physicalModeling/#brassmidi","text":"","title":"brassMIDI"},{"location":"examples/physicalModeling/#churchbell","text":"","title":"churchBell"},{"location":"examples/physicalModeling/#clarinet","text":"","title":"clarinet"},{"location":"examples/physicalModeling/#clarinetmidi","text":"","title":"clarinetMIDI"},{"location":"examples/physicalModeling/#djembemidi","text":"","title":"djembeMIDI"},{"location":"examples/physicalModeling/#elecguitarmidi","text":"","title":"elecGuitarMIDI"},{"location":"examples/physicalModeling/#englishbell","text":"","title":"englishBell"},{"location":"examples/physicalModeling/#flute","text":"","title":"flute"},{"location":"examples/physicalModeling/#flutemidi","text":"","title":"fluteMIDI"},{"location":"examples/physicalModeling/#frenchbell","text":"","title":"frenchBell"},{"location":"examples/physicalModeling/#germanbell","text":"","title":"germanBell"},{"location":"examples/physicalModeling/#guitarmidi","text":"","title":"guitarMIDI"},{"location":"examples/physicalModeling/#karplus","text":"","title":"karplus"},{"location":"examples/physicalModeling/#marimbamidi","text":"","title":"marimbaMIDI"},{"location":"examples/physicalModeling/#modularinterpinstrmidi","text":"","title":"modularInterpInstrMIDI"},{"location":"examples/physicalModeling/#nylonguitarmidi","text":"","title":"nylonGuitarMIDI"},{"location":"examples/physicalModeling/#russianbell","text":"","title":"russianBell"},{"location":"examples/physicalModeling/#standardbell","text":"","title":"standardBell"},{"location":"examples/physicalModeling/#violin","text":"","title":"violin"},{"location":"examples/physicalModeling/#violinmidi","text":"","title":"violinMIDI"},{"location":"examples/physicalModeling/#vocalbp","text":"","title":"vocalBP"},{"location":"examples/physicalModeling/#vocalbpmidi","text":"","title":"vocalBPMIDI"},{"location":"examples/physicalModeling/#vocalfof","text":"","title":"vocalFOF"},{"location":"examples/physicalModeling/#vocalfofmidi","text":"","title":"vocalFOFMIDI"},{"location":"examples/pitchShifting/","text":"pitchShifting pitchShifter","title":" pitchShifting "},{"location":"examples/pitchShifting/#pitchshifting","text":"","title":"pitchShifting"},{"location":"examples/pitchShifting/#pitchshifter","text":"","title":"pitchShifter"},{"location":"examples/psychoacoustic/","text":"psychoacoustic harmonicExciter","title":" psychoacoustic "},{"location":"examples/psychoacoustic/#psychoacoustic","text":"","title":"psychoacoustic"},{"location":"examples/psychoacoustic/#harmonicexciter","text":"","title":"harmonicExciter"},{"location":"examples/quantizing/","text":"quantizing quantizedChords","title":"quantizing"},{"location":"examples/quantizing/#quantizing","text":"","title":"quantizing"},{"location":"examples/quantizing/#quantizedchords","text":"","title":"quantizedChords"},{"location":"examples/reverb/","text":"reverb dattorro fdnRev freeverb greyhole jprev reverbDesigner reverbTester vital_rev zitaRev zitaRevFDN","title":" reverb "},{"location":"examples/reverb/#reverb","text":"","title":"reverb"},{"location":"examples/reverb/#dattorro","text":"","title":"dattorro"},{"location":"examples/reverb/#fdnrev","text":"","title":"fdnRev"},{"location":"examples/reverb/#freeverb","text":"","title":"freeverb"},{"location":"examples/reverb/#greyhole","text":"","title":"greyhole"},{"location":"examples/reverb/#jprev","text":"","title":"jprev"},{"location":"examples/reverb/#reverbdesigner","text":"","title":"reverbDesigner"},{"location":"examples/reverb/#reverbtester","text":"","title":"reverbTester"},{"location":"examples/reverb/#vital_rev","text":"","title":"vital_rev"},{"location":"examples/reverb/#zitarev","text":"","title":"zitaRev"},{"location":"examples/reverb/#zitarevfdn","text":"","title":"zitaRevFDN"},{"location":"examples/smartKeyboard/","text":"smartKeyboard acGuitar bells bowed brass clarinet crazyGuiro drums dubDub elecGuitar fm frog harp midiOnly multiSynth toy trumpet turenas violin violin2 vocal","title":" smartKeyboard "},{"location":"examples/smartKeyboard/#smartkeyboard","text":"","title":"smartKeyboard"},{"location":"examples/smartKeyboard/#acguitar","text":"","title":"acGuitar"},{"location":"examples/smartKeyboard/#bells","text":"","title":"bells"},{"location":"examples/smartKeyboard/#bowed","text":"","title":"bowed"},{"location":"examples/smartKeyboard/#brass","text":"","title":"brass"},{"location":"examples/smartKeyboard/#clarinet","text":"","title":"clarinet"},{"location":"examples/smartKeyboard/#crazyguiro","text":"","title":"crazyGuiro"},{"location":"examples/smartKeyboard/#drums","text":"","title":"drums"},{"location":"examples/smartKeyboard/#dubdub","text":"","title":"dubDub"},{"location":"examples/smartKeyboard/#elecguitar","text":"","title":"elecGuitar"},{"location":"examples/smartKeyboard/#fm","text":"","title":"fm"},{"location":"examples/smartKeyboard/#frog","text":"","title":"frog"},{"location":"examples/smartKeyboard/#harp","text":"","title":"harp"},{"location":"examples/smartKeyboard/#midionly","text":"","title":"midiOnly"},{"location":"examples/smartKeyboard/#multisynth","text":"","title":"multiSynth"},{"location":"examples/smartKeyboard/#toy","text":"","title":"toy"},{"location":"examples/smartKeyboard/#trumpet","text":"","title":"trumpet"},{"location":"examples/smartKeyboard/#turenas","text":"","title":"turenas"},{"location":"examples/smartKeyboard/#violin","text":"","title":"violin"},{"location":"examples/smartKeyboard/#violin2","text":"","title":"violin2"},{"location":"examples/smartKeyboard/#vocal","text":"","title":"vocal"},{"location":"examples/spat/","text":"spat panpot spat","title":" spat "},{"location":"examples/spat/#spat","text":"","title":"spat"},{"location":"examples/spat/#panpot","text":"","title":"panpot"},{"location":"examples/spat/#spat_1","text":"","title":"spat"},{"location":"manual/architectures/","text":"Architecture Files A Faust program describes a signal processor , a pure DSP computation that maps input signals to output signals . It says nothing about audio drivers or controllers (like GUI, OSC, MIDI, sensors) that are going to control the DSP. This additional 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 controllers interfaces to be used. This approach allows a single Faust program to be easily deployed to a large variety of audio standards (e.g., Max/MSP externals, PD externals, VST plugins, CoreAudio applications, JACK applications, iPhone/Android, etc.): The architecture to be used is specified at compile time with the -a option. For example faust -a jack-gtk.cpp foo.dsp indicates to use the JACK GTK architecture when compiling foo.dsp . Some of these architectures are a modular combination of an audio module and one or more controller modules . Some architecture only combine an audio module with the generated DSP to create an audio engine to be controlled with an additional setParamValue/getParamValue kind of API, so that the controller part can be completeley defined externally. This is the purpose of the faust2api script explained later on. Minimal Structure of an Architecture File Before going into the details of the architecture files provided with Faust distribution, it is important to have an idea of the essential parts that compose an architecture file. Technically, an architecture file is any text file with two placeholders <<includeIntrinsic>> and <<includeclass>> . The first placeholder is currently not used, and the second one is replaced by the code generated by the FAUST compiler. Therefore, the really minimal architecture file, let's call it nullarch.cpp , is the following: <<includeIntrinsic>> <<includeclass>> This nullarch.cpp architecture has the property that faust foo.dsp and faust -a nullarch.cpp foo.dsp produce the same result. Obviously, this is not very useful, moreover the resulting cpp file doesn't compile. Here is miniarch.cpp , a minimal architecture file that contains enough information to produce a cpp file that can be successfully compiled: <<includeIntrinsic>> #define FAUSTFLOAT float class dsp {}; struct Meta { virtual void declare(const char* key, const char* value) {}; }; struct Soundfile {}; struct UI { // -- widget's layouts virtual void openTabBox(const char* label) {} virtual void openHorizontalBox(const char* label) {} virtual void openVerticalBox(const char* label) {} virtual void closeBox() {} // -- active widgets virtual void addButton(const char* label, FAUSTFLOAT* zone) {} virtual void addCheckButton(const char* label, FAUSTFLOAT* zone) {} virtual void addVerticalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addHorizontalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addNumEntry(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} // -- passive widgets virtual void addHorizontalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} virtual void addVerticalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) {} // -- metadata declarations virtual void declare(FAUSTFLOAT* zone, const char* key, const char* val) {} }; <<includeclass>> This architecture is still not very useful, but it gives an idea of what a real-life architecture file has to implement, in addition to the audio part itself. As we will see in the next section, Faust architectures are implemented using a modular approach to avoid code duplication and favor code maintenance and reuse. Audio Architecture Modules A Faust generated program has to connect to a underlying audio layer. Depending if the final program is a application or plugin, the way to connect to this audio layer will differ: applications typically use the OS audio driver API, which will be CoreAudio on macOS, ALSA on Linux, WASAPI on Windows for instance, or any kind of multi-platforms API like PortAudio or JACK . In this case a subclass of the base class audio (see later) has to be written plugins (like VST3 , Audio Unit or JUCE for instance) usually have to follow a more constrained API which imposes a life cyle , something like loading/initializing/starting/running/stopping/unloading sequence of operations. In this case the Faust generated module new/init/compute/delete methods have to be inserted in the plugin API, by calling each module function at the appropriate place. External and internal audio sample formats Audio samples are managed by the underlying audio layer, typically as 32 bits float or 64 bits double values in the [-1..1] interval. Their format is defined with the FAUSTFLOAT macro implemented in the architecture file as float by default. The DSP audio samples format is choosen at compile time, with the -single (= default), -double or -quad compilation option. Control parameters like buttons, sliders... also use the FAUSTFLOAT format. By default, the FAUSTFLOAT macro is written with the following code: #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif which gives it a value ( if not already defined ), and since the default internal format is float , nothing special has to be done in the general case. But when the DSP is compiled using the -double option, the audio inputs/outputs buffers have to be adapted , with a dsp_sample_adapter class, for instance like in the dynamic-jack-gt tool . Note that an architecture may redefine FAUSTFLOAT in double, and have the complete audio chain running in double. This has to be done before including any architecture file that would define FAUSTFLOAT itself (because of the #ifndef logic). Connection to an audio driver API An audio driver architecture typically connects a Faust program to the audio drivers. It is responsible for: allocating and releasing the audio channels and presenting the audio as non-interleaved float/double data (depending of the FAUSTFLOAT macro definition), normalized between -1.0 and 1.0 calling the DSP init method at init time, to setup the ma.SR variable possibly used in the DSP code calling the DSP compute method to handle incoming audio buffers and/or to produce audio outputs. The default compilation model uses separated audio input and output buffers not referring to the same memory locations. The -inpl (--in-place) code generation model allows us to generate code working when input and output buffers are the same (which is typically needed in some embedded devices). This option currently only works in scalar (= default) code generation mode. A Faust audio architecture module derives from an audio class can be defined as below (simplified version, see the real version here) : class audio { public: audio() {} virtual ~audio() {} /** * Init the DSP. * @param name - the DSP name to be given to the audio driven * (could appear as a JACK client for instance) * @param dsp - the dsp that will be initialized with the driver sample rate * * @return true is sucessful, false if case of driver failure. **/ virtual bool init(const char* name, dsp* dsp) = 0; /** * Start audio processing. * @return true is sucessfull, false if case of driver failure. **/ virtual bool start() = 0; /** * Stop audio processing. **/ virtual void stop() = 0; void setShutdownCallback(shutdown_callback cb, void* arg) = 0; // Return buffer size in frames. virtual int getBufferSize() = 0; // Return the driver sample rate in Hz. virtual int getSampleRate() = 0; // Return the driver hardware inputs number. virtual int getNumInputs() = 0; // Return the driver hardware outputs number. virtual int getNumOutputs() = 0; /** * @return Returns the average proportion of available CPU * being spent inside the audio callbacks (between 0.0 and 1.0). **/ virtual float getCPULoad() = 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. Here is the hierarchy of some of the supported audio drivers: Connection to a plugin audio API In the case of plugin, an audio plugin architecture has to be developed, by integrating the Faust DSP new/init/compute/delete methods in the plugin API. Here is a concrete example using the JUCE framework: a FaustPlugInAudioProcessor class, subclass of the juce::AudioProcessor has to be defined. The Faust generated C++ instance will be created in its constructor, either in monophonic of polyphonic mode (see later sections) the Faust DSP instance is initialized in the JUCE prepareToPlay method using the current sample rate value the Faust dsp compute is called in the JUCE process which receives the audio inputs/outputs buffers to be processed additional methods can possibly be implemented to handle MIDI messages or save/restore the plugin parameters state for instance. This methodology obviously has to be adapted for each supported plugin API. MIDI Architecture Modules A MIDI architecture module typically connects a Faust program to the MIDI drivers. MIDI control connects DSP parameters with MIDI messages (in both directions), and can be used to trigger polyphonic instruments. MIDI Messages in the DSP Source Code MIDI control messages are described as metadata in UI elements. They are decoded by a MidiUI class, subclass of UI , which parses incoming MIDI messages and updates the appropriate control parameters, or sends MIDI messages when the UI elements (sliders, buttons...) are moved. Defined Standard MIDI Messages A special [midi:xxx yyy...] metadata needs to be added to the UI element. The full description of supported MIDI messages is part of the Faust documentation . MIDI Classes A midi base class defining MIDI messages decoding/encoding methods has been developed. It will be used to receive and transmit MIDI messages: class midi { public: midi() {} virtual ~midi() {} // Additional timestamped API for MIDI input virtual MapUI* keyOn(double, int channel, int pitch, int velocity) { return keyOn(channel, pitch, velocity); } virtual void keyOff(double, int channel, int pitch, int velocity = 0) { keyOff(channel, pitch, velocity); } virtual void keyPress(double, int channel, int pitch, int press) { keyPress(channel, pitch, press); } virtual void chanPress(double date, int channel, int press) { chanPress(channel, press); } virtual void pitchWheel(double, int channel, int wheel) { pitchWheel(channel, wheel); } virtual void ctrlChange(double, int channel, int ctrl, int value) { ctrlChange(channel, ctrl, value); } virtual void ctrlChange14bits(double, int channel, int ctrl, int value) { ctrlChange14bits(channel, ctrl, value); } virtual void rpn(double, int channel, int ctrl, int value) { rpn(channel, ctrl, value); } virtual void progChange(double, int channel, int pgm) { progChange(channel, pgm); } virtual void sysEx(double, std::vector<unsigned char>& message) { sysEx(message); } // MIDI sync virtual void startSync(double date) {} virtual void stopSync(double date) {} virtual void clock(double date) {} // Standard MIDI API virtual MapUI* keyOn(int channel, int pitch, int velocity) { return nullptr; } virtual void keyOff(int channel, int pitch, int velocity) {} virtual void keyPress(int channel, int pitch, int press) {} virtual void chanPress(int channel, int press) {} virtual void ctrlChange(int channel, int ctrl, int value) {} virtual void ctrlChange14bits(int channel, int ctrl, int value) {} virtual void rpn(int channel, int ctrl, int value) {} virtual void pitchWheel(int channel, int wheel) {} virtual void progChange(int channel, int pgm) {} virtual void sysEx(std::vector<unsigned char>& message) {} enum MidiStatus { // channel voice messages MIDI_NOTE_OFF = 0x80, MIDI_NOTE_ON = 0x90, MIDI_CONTROL_CHANGE = 0xB0, MIDI_PROGRAM_CHANGE = 0xC0, MIDI_PITCH_BEND = 0xE0, MIDI_AFTERTOUCH = 0xD0, // aka channel pressure MIDI_POLY_AFTERTOUCH = 0xA0, // aka key pressure MIDI_CLOCK = 0xF8, MIDI_START = 0xFA, MIDI_CONT = 0xFB, MIDI_STOP = 0xFC, MIDI_SYSEX_START = 0xF0, MIDI_SYSEX_STOP = 0xF7 }; enum MidiCtrl { ALL_NOTES_OFF = 123, ALL_SOUND_OFF = 120 }; enum MidiNPN { PITCH_BEND_RANGE = 0 }; }; A pure interface for MIDI handlers that can send/receive MIDI messages to/from midi objects is defined: struct midi_interface { virtual void addMidiIn(midi* midi_dsp) = 0; virtual void removeMidiIn(midi* midi_dsp) = 0; virtual ~midi_interface() {} }; A midi_hander subclass implements actual MIDI decoding and maintains a list of MIDI aware components (classes inheriting from midi and ready to send and/or receive MIDI events) using the addMidiIn/removeMidiIn methods: class midi_handler : public midi, public midi_interface { protected: std::vector<midi*> fMidiInputs; std::string fName; MidiNRPN fNRPN; public: midi_handler(const std::string& name = \"MIDIHandler\"):fName(name) {} virtual ~midi_handler() {} void addMidiIn(midi* midi_dsp) {...} void removeMidiIn(midi* midi_dsp) {...} ... ... }; Several concrete implementations subclassing midi_handler using native APIs have been written and can be found in the faust/midi folder: Depending on the native MIDI API being used, event timestamps are either expressed in absolute time or in frames. They are converted to offsets expressed in samples relative to the beginning of the audio buffer. Connected with the MidiUI class (a subclass of UI ), they allow a given DSP to be controlled with incoming MIDI messages or possibly send MIDI messages when its internal control state changes. In the following piece of code, a MidiUI object is created and connected to a rt_midi MIDI messages handler (using the RTMidi library), then given as a parameter to the standard buildUserInterface to control DSP parameters: ... rt_midi midi_handler(\"MIDI\"); MidiUI midi_interface(&midi_handler); DSP->buildUserInterface(&midi_interface); ... UI Architecture Modules A UI architecture module links user actions (i.e., 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\u2019s values according to user actions. This association is triggered by the 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: an UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout. A Faust UI architecture module derives the UI base class: template <typename REAL> struct UIReal { UIReal() {} virtual ~UIReal() {} // -- widget's layouts virtual void openTabBox(const char* label) = 0; virtual void openHorizontalBox(const char* label) = 0; virtual void openVerticalBox(const char* label) = 0; virtual void closeBox() = 0; // -- active widgets virtual void addButton(const char* label, REAL* zone) = 0; virtual void addCheckButton(const char* label, REAL* zone) = 0; virtual void addVerticalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addHorizontalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addNumEntry(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; // -- passive widgets virtual void addHorizontalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; virtual void addVerticalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) = 0; // -- metadata declarations virtual void declare(REAL* zone, const char* key, const char* val) {} }; struct UI : public UIReal<FAUSTFLOAT> { UI() {} virtual ~UI() {} }; The FAUSTFLOAT* zone element is the primary connection point between the control interface and the dsp code. The compiled dsp Faust code will give access to all internal control value addresses used by the dsp code by calling the approriate addButton , addVerticalSlider , addNumEntry etc. methods (depending of what is described in the original Faust DSP source code). The control/UI code keeps those addresses, and will typically change their pointed values each time a control value in the dsp code has to be changed. On the dsp side, all control values are sampled once at the beginning of the compute method, so that to keep the same value during the entire audio buffer. Writing and reading the control values is typically done in two different threads: the controller (a GUI, an OSC or MIDI.etc. one) write the values, and the audio real-time thread read them in the audio callback. Since writing/reading the FAUSTFLOAT* zone element is atomic, there is no need (in general) of complex synchronization mechanism between the writer (controller) and the reader (the Faust dsp object). Here is part of the UI classes hierarchy: Active Widgets Active widgets are graphical elements controlling a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double ). Active widgets in Faust are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values. Passive Widgets Passive widgets are graphical elements reflecting values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value. Passive widgets in Faust are HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type. 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. Metadata The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT* zone, const char* key, const char* value); Here is the table of currently supported general medadata: Key Value tooltip actual string content hidden 0 or 1 unit Hz or dB scale log or exp style knob or led or numerical style radio{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} style menu{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Here acc means accelerometer and gyr means gyroscope , both use the same parameters (a mapping description) but are linked to different sensors. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\u2019white noise\u2019:0;\u2019pink noise\u2019:1;\u2019sine\u2019:2}][hidden:0]\", 0, 20, 100, 1) or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) When one or several metadata are added in the same item label, then will appear in the generated code as one or successives declare(FAUSTFLOAT* zone, const char* key, const char* value); lines before the line describing the item itself. Thus the UI managing code has to associate them with the proper item. Look at the MetaDataUI class for an example of this technique. MIDI specific metadata are described here and are decoded the MidiUI class. Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for example) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future and can possibly be adapted for a specific project. They can be decoded using the MetaDataUI class. Graphic-oriented, pure controllers, code generator UI Even if the UI architecture module is graphic-oriented, a given implementation can perfectly choose to ignore all layout information and only keep the controller ones, like the buttons, sliders, nentries, bargraphs. This is typically what is done in the MidiUI or OSCUI architectures. Note that pure code generator can also be written. The JSONUI UI architecture is an example of an architecture generating the DSP JSON description as a text file. DSP JSON Description The full description of a given compiled DSP can be generated as a JSON file, to be used at several places in the architecture system. This JSON describes the DSP with its inputs/outputs number, some metadata (filename, name, used compilation parameters, used libraries etc.) as well as its UI with a hierarchy of groups up to terminal items ( buttons , sliders , nentries , bargraphs ) with all their parameters ( type , label , shortname , address , meta , init , min , max and step values). For the following DSP program: import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq = hslider(\"freq [unit:Hz]\", 600, 20, 2000, 1); process = vgroup(\"Oscillator\", os.osc(freq) * vol) <: (_,_); The generated JSON file is then: { \"name\": \"foo\", \"filename\": \"foo.dsp\", \"version\": \"2.40.8\", \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\", \"library_list\": [], \"include_pathnames\": [\"/usr/local/share/faust\"], \"inputs\": 0, \"outputs\": 2, \"meta\": [ { \"basics.lib/name\": \"Faust Basic Element Library\" }, { \"basics.lib/version\": \"0.6\" }, { \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\" }, { \"filename\": \"foo.dsp\" }, { \"maths.lib/author\": \"GRAME\" }, { \"maths.lib/copyright\": \"GRAME\" }, { \"maths.lib/license\": \"LGPL with exception\" }, { \"maths.lib/name\": \"Faust Math Library\" }, { \"maths.lib/version\": \"2.5\" }, { \"name\": \"tes\" }, { \"oscillators.lib/name\": \"Faust Oscillator Library\" }, { \"oscillators.lib/version\": \"0.3\" }, { \"platform.lib/name\": \"Generic Platform Library\" }, { \"platform.lib/version\": \"0.2\" }, { \"signals.lib/name\": \"Faust Signal Routing Library\" }, { \"signals.lib/version\": \"0.1\" } ], \"ui\": [ { \"type\": \"vgroup\", \"label\": \"Oscillator\", \"items\": [ { \"type\": \"hslider\", \"label\": \"freq\", \"shortname\": \"freq\", \"address\": \"/Oscillator/freq\", \"meta\": [ { \"unit\": \"Hz\" } ], \"init\": 600, \"min\": 20, \"max\": 2000, \"step\": 1 }, { \"type\": \"hslider\", \"label\": \"volume\", \"shortname\": \"volume\", \"address\": \"/Oscillator/volume\", \"meta\": [ { \"unit\": \"dB\" } ], \"init\": 0, \"min\": -96, \"max\": 0, \"step\": 0.1 } ] } ] } The JSON file can be generated with faust -json foo.dsp command, or programmatically using the JSONUI UI architecture (see next Some Useful UI Classes and Tools for Developers section). Here is the description of ready-to-use UI classes, followed by classes to be used in developer code: GUI Builders Here is the description of the main GUI classes: the GTKUI class uses the GTK toolkit to create a Graphical User Interface with a proper group-based layout the QTUI class uses the QT toolkit to create a Graphical User Interface with a proper group based layout the JuceUI class uses the JUCE framework to create a Graphical User Interface with a proper group based layout Non-GUI Controllers Here is the description of the main non-GUI controller classes: the OSCUI class implements OSC remote control in both directions the httpdUI class implements HTTP remote control using the libmicrohttpd library to embed a HTTP server inside the application. Then by opening a browser on a specific URL, the GUI will appear and allow to control the distant application or plugin. The connection works in both directions the MIDIUI class implements MIDI control in both directions, and it explained more deeply later on Some Useful UI Classes and Tools for Developers Some useful UI classes and tools can possibly be reused in developer code: the MapUI class establishes a mapping beween UI items and their labels , shortname or paths , and offers a setParamValue/getParamValue API to set and get their values. It uses an helper PathBuilder class to create complete shortnames and pathnames to the leaves in the UI hierarchy. Note that the item path encodes the UI hierarchy in the form of a /group1/group2/.../label string and is the way to distinguish control that may have the same label, but different localisation in the UI tree. Using shortnames (built so that they never collide) is an alternative way to access items. The setParamValue/getParamValue API takes either labels , shortname or paths as the way to describe the control, but using shortnames or paths is the safer way to use it the extended APIUI offers setParamValue/getParamValue API similar to MapUI , with additional methods to deal with accelerometer/gyroscope kind of metadata the MetaDataUI class decodes all currently supported metadata and can be used to retrieve their values the JSONUI class allows us to generate the JSON description of a given DSP the JSONUIDecoder class is used to decode the DSP JSON description and implement its buildUserInterface and metadata methods the FUI class allows us to save and restore the parameters state as a text file the SoundUI class with the associated Soundfile class is used to implement the soundfile primitive, and load the described audio resources (typically audio files), by using different concrete implementations, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). Paths to sound files can be absolute, but it should be noted that a relative path mechanism can be set up when creating an instance of SoundUI , in order to load sound files with a more flexible strategy. the ControlSequenceUI class with the associated OSCSequenceReader class allow to control parameters change in time, using the OSC time tag format. Changing the control values will have to be mixed with audio rendering. Look at the sndfile.cpp use-case. the ValueConverter file contains several mapping classes used to map user interface values (for example a gui slider delivering values between 0 and 1) to Faust values (for example a vslider between 20 and 2000) using linear/log/exp scales. It also provides classes to handle the [acc:a b c d e] and [gyr:a b c d e] Sensors Control Metadatas . Multi-Controller and Synchronization A given DSP can perfectly be controlled by several UI classes at the same time, and they will all read and write the same DSP control memory zones. Here is an example of code using a GUI using GTKUI architecture, as well as OSC control using OSCUI : ... GTKUI gtk_interface(name, &argc, &argv); DSP->buildUserInterface(&gtk_interface); OSCUI osc_interface(name, argc, argv); DSP->buildUserInterface(&osc_interface); ... Since several controller access the same values, you may have to synchronize them, in order for instance to have the GUI sliders or buttons reflect the state that would have been changed by the OSCUI controller at reception time, of have OSC messages been sent each time UI items like sliders or buttons are moved. This synchronization mecanism is implemented in a generic way in the GUI class. First the uiItemBase class is defined as the basic synchronizable memory zone, then grouped in a list controlling the same zone from different GUI instances. The uiItemBase::modifyZone method is used to change the uiItemBase state at reception time, and uiItemBase::reflectZone will be called to reflect a new value, and can change the Widget layout for instance, or send a message (OSC, MIDI...). All classes needing to use this synchronization mechanism will have to subclass the GUI class, which keeps all of them at runtime in a static class GUI::fGuiList variable. This is the case for the previously used GTKUI and OSCUI classes. Note that when using the GUI class, the 2 following static class variables have to be defined in the code, (once in one .cpp file in the project) like in this code example: // Globals std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; Finally the static GUI::updateAllGuis() synchronization method will have to be called regularly, in the application or plugin event management loop, or in a periodic timer for instance. This is typically implemented in the GUI::run method which has to be called to start event or messages processing. In the following code, the OSCUI::run method is called first to start processing OSC messages, then the blocking GTKUI::run method, which opens the GUI window, to be closed to finally finish the application: ... // Start OSC messages processing osc_interface.run(); // Start GTK GUI as the last one, since it blocks until the opened window is closed gtk_interface.run() ... DSP Architecture Modules The Faust compiler produces a DSP module whose format will depend of the chosen backend: a C++ class with the -lang cpp option, a data structure with associated functions with the -lang c option, an LLVM IR module with the -lang llvm option, a WebAssembly binary module with the -lang wasm option, a bytecode stream with the -lang interp option... and so on. The Base dsp Class In C++, the generated class derives from a base dsp class: class dsp { public: dsp() {} virtual ~dsp() {} /* Return instance number of audio inputs */ virtual int getNumInputs() = 0; /* Return instance number of audio outputs */ virtual int getNumOutputs() = 0; /** * Trigger the ui_interface parameter with instance specific calls * to 'openTabBox', 'addButton', 'addVerticalSlider'... in order to build the UI. * * @param ui_interface - the user interface builder */ virtual void buildUserInterface(UI* ui_interface) = 0; /* Return the sample rate currently used by the instance */ virtual int getSampleRate() = 0; /** * Global init, calls the following methods: * - static class 'classInit': static tables initialization * - 'instanceInit': constants and instance state initialization * * @param sample_rate - the sampling rate in Hz */ virtual void init(int sample_rate) = 0; /** * Init instance state * * @param sample_rate - the sampling rate in Hz */ virtual void instanceInit(int sample_rate) = 0; /** * Init instance constant state * * @param sample_rate - the sampling rate in HZ */ virtual void instanceConstants(int sample_rate) = 0; /* Init default control parameters values */ virtual void instanceResetUserInterface() = 0; /* Init instance state (like delay lines..) but keep the control parameter values */ virtual void instanceClear() = 0; /** * Return a clone of the instance. * * @return a copy of the instance on success, otherwise a null pointer. */ virtual dsp* clone() = 0; /** * Trigger the Meta* parameter with instance specific calls to 'declare' * (key, value) metadata. * * @param m - the Meta* meta user */ virtual void metadata(Meta* m) = 0; /** * DSP instance computation, to be called with successive in/out audio buffers. * * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * */ virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; /** * Alternative DSP instance computation method for use by subclasses, incorporating an additional `date_usec` parameter, * which specifies the timestamp of the first sample in the audio buffers. * * @param date_usec - the timestamp in microsec given by audio driver. By convention timestamp of -1 means 'no timestamp conversion', * events already have a timestamp expressed in frames. * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * */ virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; }; The dsp class is central to the Faust architecture design: the getNumInputs , getNumOutputs methods provides information about the signal processor the buildUserInterface method creates the user interface using a given UI class object (see later) the init method (and some more specialized methods like instanceInit , instanceConstants , etc.) is called to initialize the dsp object with a given sampling rate, typically obtained from the audio architecture the compute method is called by the audio architecture to execute the actual audio processing. It takes a count number of samples to process, and inputs and outputs arrays of non-interleaved float/double samples, to be allocated and handled by the audio driver with the required dsp input and outputs channels (as given by getNumInputs and getNumOutputs ) the clone method can be used to duplicate the instance the metadata(Meta* m) method can be called with a Meta object to decode the instance global metadata (see next section) (note that FAUSTFLOAT label is typically defined to be the actual type of sample: either float or double using #define FAUSTFLOAT float in the code for instance). For a given compiled DSP program, the compiler will generate a mydsp subclass of dsp and fill the different methods (the actual name can be changed using the -cn option). For dynamic code producing backends like the LLVM IR, Cmajor or the Interpreter ones, the actual code (an LLVM module, a Cmajor module or a bytecode stream) is actually wrapped by some additional C++ code glue, to finally produces an llvm_dsp typed object (defined in the llvm-dsp.h file), a cmajorpatch_dsp typed object (defined in the cmajorpatch-dsp.h file) or an interpreter_dsp typed object (defined in interpreter-dsp.h file), ready to be used with the UI and audio C++ classes (like the C++ generated class). See the following class diagram: Global DSP metadata All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler, for instance the Faust program: declare name \"NoiseProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; import(\"stdfaust.lib\"); process = no.noise; will generate the following C++ metadata(Meta* m) method in the dsp class: void metadata(Meta* m) { m->declare(\"author\", \"MySelf\"); m->declare(\"compile_options\", \"-lang cpp -es 1 -scal -ftz 0\"); m->declare(\"copyright\", \"MyCompany\"); m->declare(\"filename\", \"metadata.dsp\"); m->declare(\"license\", \"BSD\"); m->declare(\"name\", \"NoiseProgram\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); m->declare(\"version\", \"1.00\"); } which interacts with an instance of an implementation class of the following virtual Meta class: struct Meta { virtual ~Meta() {}; virtual void declare(const char* key, const char* value) = 0; }; and are part of three different types of global metadata: metadata like compile_options or filename are automatically generated metadata like author of copyright are part of the Global Medata metadata like noises.lib/name are part of the Function Metadata Specialized subclasses of the Meta class can be implemented to decode the needed key/value pairs for a given use-case. Macro Construction of DSP Components The Faust program specification is usually entirely done in the language itself. But in some specific cases it may be useful to develop separated DSP components and combine them in a more complex setup. Since taking advantage of the huge number of already available UI and audio architecture files is important, keeping the same dsp API is preferable, so that more complex DSP can be controlled and audio rendered the usual way. Extended DSP classes will typically subclass the dsp base class and override or complete part of its API. DSP Decorator Pattern A dsp_decorator class, subclass of the root dsp class has first been defined. Following the decorator design pattern, it allows behavior to be added to an individual object, either statically or dynamically. As an example of the decorator pattern, the timed_dsp class allows to decorate a given DSP with sample accurate control capability or the mydsp_poly class for polyphonic DSPs, explained in the next sections. Combining DSP Components A few additional macro construction classes, subclasses of the root dsp class have been defined in the dsp-combiner.h header file with a five operators construction API: the dsp_sequencer class combines two DSP in sequence, assuming that the number of outputs of the first DSP equals the number of input of the second one. It somewhat mimics the sequence (that is : ) operator of the language by combining two separated C++ objects. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSPs can be individually controlled. Its compute method is overloaded to call each DSP compute in sequence, using an intermediate output buffer produced by first DSP as the input one given to the second DSP. the dsp_parallelizer class combines two DSP in parallel. It somewhat mimics the parallel (that is , ) operator of the language by combining two separated C++ objects. Its getNumInputs/getNumOutputs methods are overloaded by correctly reflecting the input/output of the resulting DSP as the sum of the two combined ones. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSP can be individually controlled. Its compute method is overloaded to call each DSP compute, where each DSP consuming and producing its own number of input/output audio buffers taken from the method parameters. This methology is followed to implement the three remaining composition operators ( split , merge , recursion ), which ends up with a C++ API to combine DSPs with the usual five operators: createDSPSequencer , createDSPParallelizer , createDSPSplitter , createDSPMerger , createDSPRecursiver to be used at C++ level to dynamically combine DSPs. And finally the createDSPCrossfader tool allows you to crossfade between two DSP modules. The crossfade parameter (as a slider) controls the mix between the two modules outputs. When Crossfade = 1 , the first DSP only is computed, when Crossfade = 0 , the second DSP only is computed, otherwise both DSPs are computed and mixed. Note that this idea of decorating or combining several C++ dsp objects can perfectly be extended in specific projects, to meet other needs: like muting some part of a graph of several DSPs for instance. But keep in mind that keeping the dsp API then allows to take profit of all already available UI and audio based classes. Sample Accurate Control DSP audio languages usually deal with several timing dimensions when treating control events and generating audio samples. For performance reasons, systems maintain separated audio rate for samples generation and control rate for asynchronous messages handling. The audio stream is most often computed by blocks, and control is updated between blocks. To smooth control parameter changes, some languages chose to interpolate parameter values between blocks. In some cases control may be more finely interleaved with audio rendering, and some languages simply choose to interleave control and sample computation at sample level. Although the Faust language permits the description of sample level algorithms (i.e., like recursive filters, etc.), Faust generated DSP are usually computed by blocks. Underlying audio architectures give a fixed size buffer over and over to the DSP compute method which consumes and produces audio samples. Control to DSP Link In the current version of the Faust generated code, the primary connection point between the control interface and the DSP code is simply a memory zone. For control inputs, the architecture layer continuously write values in this zone, which is then sampled by the DSP code at the beginning of the compute method, and used with the same values throughout the call. Because of this simple control/DSP connexion mechanism, the most recent value is used by the DSP code. Similarly for control outputs , the DSP code inside the compute method possibly writes several values at the same memory zone, and the last value only will be seen by the control architecture layer when the method finishes. Although this behaviour is satisfactory for most use-cases, some specific usages need to handle the complete stream of control values with sample accurate timing. For instance keeping all control messages and handling them at their exact position in time is critical for proper MIDI clock synchronisation. Timestamped Control The first step consists in extending the architecture control mechanism to deal with timestamped control events. Note that this requires the underlying event control layer to support this capability. The native MIDI API for instance is usually able to deliver timestamped MIDI messages. The next step is to keep all timestamped events in a time ordered data structure to be continuously written by the control side, and read by the audio side. Finally the sample computation has to take account of all queued control events, and correctly change the DSP control state at successive points in time. Slices Based DSP Computation With timestamped control messages, changing control values at precise sample indexes on the audio stream becomes possible. A generic slices based DSP rendering strategy has been implemented in the timed_dsp class. A ring-buffer is used to transmit the stream of timestamped events from the control layer to the DSP one. In the case of MIDI control for instance, the ring-buffer is written with a pair containing the timestamp expressed in samples (or microseconds) and the actual MIDI message each time one is received. In the DSP compute method, the ring-buffer will be read to handle all messages received during the previous audio block. Since control values can change several times inside the same audio block, the DSP compute cannot be called only once with the total number of frames and the complete inputs/outputs audio buffers. The following strategy has to be used: several slices are defined with control values changing between consecutive slices all control values having the same timestamp are handled together, and change the DSP control internal state. The slice is computed up to the next control parameters timestamp until the end of the given audio block is reached in the next figure, four slices with the sequence of c1, c2, c3, c4 frames are successively given to the DSP compute method, with the appropriate part of the audio input/output buffers. Control values (appearing here as [v1,v2,v3] , then [v1,v3] , then [v1] , then [v1,v2,v3] sets) are changed between slices Since timestamped control messages from the previous audio block are used in the current block, control messages are aways handled with one audio buffer latency. Note that this slices based computation model can always be directly implemented on top of the underlying audio layer, without relying on the timed_dsp wrapper class. Audio driver timestamping Some audio drivers can get the timestamp of the first sample in the audio buffers, and will typically call the DSP alternative compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) function with the correct timestamp. By convention timestamp of -1 means 'no timestamp conversion', events already have a timestamp expressed in frames (see jackaudio_midi for an example driver using timestamp expressed in frames). The timed_dsp wrapper class is an example of a DSP class actually using the timestamp information. Typical Use-Case A typical Faust program can use the MIDI clock command signal to possibly compute the Beat Per Minutes (BPM) information for any synchronization need it may have. Here is a simple example of a sinusoid generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"stdfaust.lib\"); // square signal (1/0), changing state // at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled // with MIDI start/stop messages play = checkbox(\"On/Off [midi:start][midi:stop]\"); // detect front front(x) = (x-x\u2019) != 0.0; // count number of peaks during one second freq(x) = (x-x@ma.SR) : + ~ _; process = os.osc(8*freq(front(clocker))) * play; Each received group of 24 clocks will move the time position by exactly one beat. Then it is absolutely mandatory to never loose any MIDI clock message and the standard memory zone based model with the use the last received control value semantic is not adapted. The DSP object that needs to be controlled using the sample-accurate machinery can then simply be decorated using the timed_dsp class with the following kind of code: dsp* sample_accurate_dsp = new timed_dsp(DSP); Note that the described sample accurate MIDI clock synchronization model can currently only be used at input level. Because of the simple memory zone based connection point between the control interface and the DSP code, output controls (like bargraph) cannot generate a stream of control values. Thus a reliable MIDI clock generator cannot be implemented with the current approach. Polyphonic Instruments Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping. Polyphonic ready DSP Code By convention Faust architecture files with polyphonic capabilities expect to find control parameters named freq , gain , and gate . The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the freq parameter (which should be a frequency) will be automatically computed from MIDI note numbers, gain (which should be a value between 0 and 1) from velocity and gate from keyon/keyoff events. Thus, gate can be used as a trigger signal for any envelope generator, etc. Using the mydsp_poly Class The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the poly-dsp.h file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp* objects, manage dynamic voice allocation, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold as a subclass of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global Polyphonic tabgroup. The first tab contains a Voices group, a master like component used to change parameters on all voices at the same time, with a Panic button to be used to stop running voices, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI , httpdUI , etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used. The polyphonic instrument allocation takes the DSP to be used for one voice, the desired number of voices, the dynamic voice allocation state, and the group state which controls if separated voices are displayed or not: dsp* poly = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: dsp* poly = new mydsp_poly(dsp, 8, false, true); Polyphonic Instrument With a Global Output Effect Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is generally not a good idea since it would be instantiated for each voice which would be very inefficient. A convention has been defined to use the effect = some effect; line in the DSP source code. The actual effect definition has to be extracted from the DSP code, compiled separately, and then combined using the dsp_sequencer class previously presented to connect the polyphonic DSP in sequence with a unique global effect, with something like: dsp* poly = new dsp_sequencer(new mydsp_poly(dsp, 2, true, true), new effect()); | Some helper classes like the base dsp_poly_factory class, and concrete implementations llvm_dsp_poly_factory when using the LLVM backend or interpreter_dsp_poly_factory when using the Interpreter backend can also be used to automatically handle the voice and effect part of the DSP. Controlling the Polyphonic Instrument The mydsp_poly class is also ready for MIDI control (as a class implementing the midi interface) and can react to keyOn/keyOff and pitchWheel events. Other MIDI control parameters can directly be added in the DSP source code as MIDI metadata. To receive MIDI events, the created polyphonic DSP will be automatically added to the midi_handler object when calling buildUserInterface on a MidiUI object. Deploying the Polyphonic Instrument Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. faustcaqt -midi -noices 12 inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. Polyphonic ready faust2xx scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready-to-use DSP. Custom Memory Manager In C and C++, the Faust compiler produces a class (or a struct in C), to be instantiated to create each DSP instance. The standard generation model produces a flat memory layout, where all fields (scalar and arrays) are simply consecutive in the generated code (following the compilation order). So the DSP is allocated on a single block of memory, either on the stack or the heap depending on the use-case. The following DSP program: import(\"stdfaust.lib\"); gain = hslider(\"gain\", 0.5, 0, 1, 0.01); feedback = hslider(\"feedback\", 0.8, 0, 1, 0.01); echo(del_sec, fb, g) = + ~ de.delay(50000, del_samples) * fb * g with { del_samples = del_sec * ma.SR; }; process = echo(1.6, 0.6, 0.7), echo(0.7, feedback, gain); will have the flat memory layout: int IOTA0; int fSampleRate; int iConst1; float fRec0[65536]; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float fRec1[65536]; So scalar fHslider0 and fHslider1 correspond to the gain and feedback controllers. The iConst1 and iConst2 values are typically computed once at init time using the dynamically given the fSampleRate value, and used in the DSP loop later on. The fRec0 and fRec1 arrays are used for the recursive delays and finally the shared IOTA0 index is used to access them. Here is the generated compute function: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; float fSlow0 = float(fHslider0) * float(fHslider1); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 65535] = float(input0[i0]) + 0.419999987f * fRec0[(IOTA0 - iConst1) & 65535]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 65535]); fRec1[IOTA0 & 65535] = float(input1[i0]) + fSlow0 * fRec1[(IOTA0 - iConst2) & 65535]; output1[i0] = FAUSTFLOAT(fRec1[IOTA0 & 65535]); IOTA0 = IOTA0 + 1; } } The -mem option On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. The first remark is that scalar values will typically stay in the DSP structure, and the point is to move the big array buffers ( fRec0 and fRec1 in the example) into separated memory blocks. The -mem (--memory-manager) option can be used to generate adapted code. On the previous DSP program, we now have the following generated C++ code: int IOTA0; int fSampleRate; int iConst1; float* fRec0; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float* fRec1; The two fRec0 and fRec1 arrays are becoming pointers, and will be allocated elsewhere. An external memory manager is needed to interact with the DSP code. The proposed model does the following: in a first step the generated C++ code will inform the memory allocator about its needs in terms of 1) number of separated memory zones, with 2) their size 3) access characteristics, like number of Read and Write for each frame computation. This is done be generating an additional static memoryInfo method with the complete information available, the memory manager can then define the best strategy to allocate all separated memory zones an additional memoryCreate method is generated to allocate each of the separated zones an additional memoryDestroy method is generated to deallocate each of the separated zones Here is the API for the memory manager: struct dsp_memory_manager { virtual ~dsp_memory_manager() {} /** * Inform the Memory Manager with the number of expected memory zones. * @param count - the number of memory zones */ virtual void begin(size_t count); /** * Give the Memory Manager information on a given memory zone. * @param size - the size in bytes of the memory zone * @param reads - the number of Read access to the zone used to compute one frame * @param writes - the number of Write access to the zone used to compute one frame */ virtual void info(size_t size, size_t reads, size_t writes) {} /** * Inform the Memory Manager that all memory zones have been described, * to possibly start a 'compute the best allocation strategy' step. */ virtual void end(); /** * Allocate a memory zone. * @param size - the memory zone size in bytes */ virtual void* allocate(size_t size) = 0; /** * Destroy a memory zone. * @param ptr - the memory zone pointer to be deallocated */ virtual void destroy(void* ptr) = 0; }; A class static member is added in the mydsp class, to be set with an concrete memory manager later on: dsp_memory_manager* mydsp::fManager = nullptr; The C++ generated code now contains a new memoryInfo method, which interacts with the memory manager: static void memoryInfo() { fManager->begin(3); // mydsp fManager->info(56, 9, 1); // fRec0 fManager->info(262144, 2, 1); // fRec1 fManager->info(262144, 2, 1); fManager->end(); } The begin method is first generated to inform that three separated memory zones will be needed. Then three consecutive calls to the info method are generated, one for the DSP object itself, one for each recursive delay array. The end method is then called to finish the memory layout description, and let the memory manager prepare the actual allocations. Note that the memory layout information is also available in the JSON file generated using the -json option, to possibly be used statically by the architecture machinery (that is at compile time). With the previous program, the memory layout section is: \"memory_layout\": [ { \"name\": \"mydsp\", \"type\": \"kObj_ptr\", \"size\": 0, \"size_bytes\": 56, \"read\": 9, \"write\": 1 }, { \"name\": \"IOTA0\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 7, \"write\": 1 }, { \"name\": \"iConst1\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec0\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 }, { \"name\": \"iConst2\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec1\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 } ] Finally the memoryCreate and memoryDestroy methods are generated. The memoryCreate method asks the memory manager to allocate the fRec0 and fRec1 buffers: void memoryCreate() { fRec0 = static_cast<float*>(fManager->allocate(262144)); fRec1 = static_cast<float*>(fManager->allocate(262144)); } And the memoryDestroy method asks the memory manager to destroy them: virtual memoryDestroy() { fManager->destroy(fRec0); fManager->destroy(fRec1); } Additional static create/destroy methods are generated: static mydsp* create() { mydsp* dsp = new (fManager->allocate(sizeof(mydsp))) mydsp(); dsp->memoryCreate(); return dsp; } static void destroy(dsp* dsp) { static_cast<mydsp*>(dsp)->memoryDestroy(); fManager->destroy(dsp); } Note that the so-called C++ placement new will be used to allocate the DSP object itself. Static tables When rdtable or rwtable primitives are used in the source code, the C++ class will contain a table shared by all instances of the class. By default, this table is generated as a static class array, and so allocated in the application global static memory. Taking the following DSP example: process = (waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable), (waveform {1.1,2.2,3.3,4.4,5.5,6.6,7.7}, %(7)~+(3) : rdtable); Here is the generated code in default mode: ... static int itbl0mydspSIG0[7]; static float ftbl1mydspSIG1[7]; class mydsp : public dsp { ... public: ... static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(); sig0->instanceInitmydspSIG0(sample_rate); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(); sig1->instanceInitmydspSIG1(sample_rate); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0); deletemydspSIG1(sig1); } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are static global arrays. They are filled in the classInit method. The architecture code will typically call the init method (which calls classInit ) on a given DSP, to allocate class related arrays and the DSP itself. If several DSPs are going to be allocated, calling classInit only once then the instanceInit method on each allocated DSP is the way to go. In the -mem mode, the generated C++ code is now: ... static int* itbl0mydspSIG0 = 0; static float* ftbl1mydspSIG1 = 0; class mydsp : public dsp { ... public: ... static dsp_memory_manager* fManager; static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(fManager); sig0->instanceInitmydspSIG0(sample_rate); itbl0mydspSIG0 = static_cast<int*>(fManager->allocate(28)); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(fManager); sig1->instanceInitmydspSIG1(sample_rate); ftbl1mydspSIG1 = static_cast<float*>(fManager->allocate(28)); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0, fManager); deletemydspSIG1(sig1, fManager); } static void classDestroy() { fManager->destroy(itbl0mydspSIG0); fManager->destroy(ftbl1mydspSIG1); } virtual void init(int sample_rate) {} virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are generated as static global pointers. The classInit method uses the fManager object used to allocate tables. A new classDestroy method is generated to deallocate the tables. Finally the init method is now empty, since the architecture file is supposed to use the classInit/classDestroy method once to allocate and deallocate static tables, and the instanceInit method on each allocated DSP. The memoryInfo method now has the following shape, with the two itbl0mydspSIG0 and ftbl1mydspSIG1 tables: static void memoryInfo() { fManager->begin(6); // mydspSIG0 fManager->info(4, 0, 0); // itbl0mydspSIG0 fManager->info(28, 1, 0); // mydspSIG1 fManager->info(4, 0, 0); // ftbl1mydspSIG1 fManager->info(28, 1, 0); // mydsp fManager->info(28, 0, 0); // iRec0 fManager->info(8, 3, 2); fManager->end(); } Defining and using a custom memory manager When compiled with the -mem option, the client code has to define an adapted memory_manager class for its specific needs. A cutom memory manager is implemented by subclassing the dsp_memory_manager abstract base class, and defining the begin , end , \u00ecnfo , allocate and destroy methods. Here is an example of a simple heap allocating manager (implemented in the dummy-mem.cpp architecture file): struct malloc_memory_manager : public dsp_memory_manager { virtual void begin(size_t count) { // TODO: use \u2018count\u2019 } virtual void end() { // TODO: start sorting the list of memory zones, to prepare // for the future allocations done in memoryCreate() } virtual void info(size_t size, size_t reads, size_t writes) { // TODO: use 'size', \u2018reads\u2019 and \u2018writes\u2019 // to prepare memory layout for allocation } virtual void* allocate(size_t size) { // TODO: refine the allocation scheme to take // in account what was collected in info return calloc(1, size); } virtual void destroy(void* ptr) { // TODO: refine the allocation scheme to take // in account what was collected in info free(ptr); } }; The specialized malloc_memory_manager class can now be used the following way: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // \u2018Placement new\u2019 and 'memoryCreate' are used inside the \u2018create\u2019 method dsp* DSP = mydsp::create(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // 'memoryDestroy' and memory manager 'destroy' are used to deallocate memory mydsp::destroy(); // Done once after the last DSP has been destroyed mydsp::classDestroy(); Note that the client code can still choose to allocate/deallocate the DSP instance using the regular C++ new/delete operators: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // Use regular C++ new dsp* DSP = new mydsp(); /// Allocate internal buffers DSP->memoryCreate(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP->memoryDestroy(); // Use regular C++ delete delete DSP; // Done once after the last DSP has been destroyed mydsp::classDestroy(); Or even on the stack with: ... // Allocation on the stack mydsp DSP; // Allocate internal buffers DSP.memoryCreate(); // Init the DSP instance DSP.instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP.memoryDestroy(); ... More complex custom memory allocators can be developed by refining this malloc_memory_manager example, possibly defining real-time memory allocators...etc... The OWL architecture file uses a custom OwlMemoryManager . Allocating several DSP instances In a multiple instances scheme, static data structures shared by all instances have to be allocated once at beginning using mydsp::classInit , and deallocated at the end using mydsp::classDestroy . Individual instances are then allocated with mydsp::create() and deallocated with mydsp::destroy() , possibly directly using regular new/delete , or using stack allocation as explained before. Measuring the DSP CPU The measure_dsp class defined in the faust/dsp/dsp-bench.h file allows to decorate a given DSP object and measure its compute method CPU consumption. Results are given in Megabytes/seconds (higher is better) and DSP CPU at 44,1 kHz. Here is a C++ code example of its use: static void bench(dsp* dsp, const string& name) { // Init the DSP dsp->init(48000); // Wraps it with a 'measure_dsp' decorator measure_dsp mes(dsp, 1024, 5); // Measure the CPU use mes.measure(); // Returns the Megabytes/seconds and relative standard deviation values std::pair<double, double> res = mes.getStats(); // Print the stats cout << name << \" MBytes/sec : \" << res.first << \" \" << \"(DSP CPU % : \" << (mes.getCPULoad() * 100) << \")\" << endl; } Defined in the faust/dsp/dsp-optimizer.h file, the dsp_optimizer class uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU. Here is a C++ code example of its use: static void dynamic_bench(const string& in_filename) { // Init the DSP optimizer with the in_filename to compile dsp_optimizer optimizer(in_filename, 0, nullptr, \"\", 1024); // Discover the best set of parameters tuple<double, double, double, TOption> res = optimizer.findOptimizedParameters(); cout << \"Best value for '\" << in_filename << \"' is : \" << get<0>(res) << \" MBytes/sec with \"; for (size_t i = 0; i < get<3>(res).size(); i++) { cout << get<3>(res)[i] << \" \"; } cout << endl; } This class can typically be used in tools that help developers discover the best Faust compilation parameters for a given DSP program, like the faustbench and faustbench-llvm tools. The Proxy DSP Class In some cases, a DSP may run outside of the application or plugin context, like on another machine. The proxy_dsp class allows to create a proxy DSP that will be finally connected to the real one (using an OSC or HTTP based machinery for instance), and will reflect its behaviour. It uses the previously described JSONUIDecoder class. Then the proxy_dsp can be used in place of the real DSP, and connected with UI controllers using the standard buildUserInterface to control it. The faust-osc-controller tool demonstrates this capability using an OSC connection between the real DSP and its proxy. The proxy_osc_dsp class implements a specialized proxy_dsp using the liblo OSC library to connect to a OSC controllable DSP (which is using the OSCUI class and running in another context or machine). Then the faust-osc-controller program creates a real GUI (using GTKUI in this example) and have it control the remote DSP and reflect its dynamic state (like vumeter values coming back from the real DSP). Embedded Platforms Faust has been targeting an increasing number of embedded platforms for real-time audio signal processing applications in recent years. It can now be used to program microcontrollers (i.e., ESP32 , Teensy , Pico DSP and Daisy ), mobile platforms, embedded Linux systems (i.e., Bela and Elk ), Digital Signal Processors (DSPs), and more. Specialized architecture files and faust2xx scripts have been developed. Metadata Naming Convention A specific question arises when dealing with devices without or limited screen to display any GUI, and a set of physical knobs or buttons to be connected to control parameters. The standard way is then to use metadata in control labels. Since beeing able to use the same DSP file on all devices is always desirable, a common set of metadata has been defined: [switch:N] is used to connect to switch buttons [knob:N] is used to connect to knobs A extended set of metadata will probably have to be progressively defined and standardized. Using the -uim Compiler Option On embedded platforms with limited capabilities, using the -uim option can be helpful. The C/C++ generated code then contains a static description of several caracteristics of the DSP, like the number of audio inputs/outputs , the number of controls inputs/outputs , and macros feed with the controls parameters (label, DSP field name, init, min, max, step) that can be implemented in the architecture file for various needs. For example the following DSP program: process = _*hslider(\"Gain\", 0, 0, 1, 0.01) : hbargraph(\"Vol\", 0, 1); compiled with faust -uim foo.dsp gives this additional section: #ifdef FAUST_UIMACROS #define FAUST_FILE_NAME \"foo.dsp\" #define FAUST_CLASS_NAME \"mydsp\" #define FAUST_INPUTS 1 #define FAUST_OUTPUTS 1 #define FAUST_ACTIVES 1 #define FAUST_PASSIVES 1 FAUST_ADDHORIZONTALSLIDER(\"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f); FAUST_ADDHORIZONTALBARGRAPH(\"Vol\", fHbargraph0, 0.0f, 1.0f); #define FAUST_LIST_ACTIVES(p) \\ p(HORIZONTALSLIDER, Gain, \"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f) \\ #define FAUST_LIST_PASSIVES(p) \\ p(HORIZONTALBARGRAPH, Vol, \"Vol\", fHbargraph0, 0.0, 0.0f, 1.0f, 0.0) \\ #endif The FAUST_ADDHORIZONTALSLIDER or FAUST_ADDHORIZONTALBARGRAPH macros can then be implemented to do whatever is needed with the Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f and \"Vol\", fHbargraph0, 0.0f, 1.0f parameters respectively. The more sophisticated FAUST_LIST_ACTIVES and FAUST_LIST_PASSIVES macros can possibly be used to call any p function (defined elsewhere in the architecture file) on each item. The minimal-static.cpp file demonstrates this feature. Developing a New Architecture File Developing a new architecture file typically means writing a generic file, that will be populated with the actual output of the Faust compiler, in order to produce a complete file, ready-to-be-compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the <<includeIntrinsic>> and <<includeclass>> lines that will be recognized by the Faust compiler, and replaced by the generated code. Here is an example in C++, but the same logic can be used with other languages producing textual outputs, like C, Cmajor, Rust or Dlang. Look at the minimal.cpp example located in the architecture folder: #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #include \"faust/dsp/one-sample-dsp.h\" // To be replaced by the compiler generated C++ class <<includeIntrinsic>> <<includeclass>> int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", static_cast<dsp*>(&DSP)); // Render buffers... audio.start(); audio.stop(); } Calling faust -a minimal.cpp noise.dsp -o noise.cpp will produce a ready to compile noise.cpp file: /* ------------------------------------------------------------ name: \"noise\" Code generated with Faust 2.28.0 (https://faust.grame.fr) Compilation options: -lang cpp -scal -ftz 0 ------------------------------------------------------------ */ #ifndef __mydsp_H__ #define __mydsp_H__ #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #include <algorithm> #include <cmath> #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif #ifdef __APPLE__ #define exp10f __exp10f #define exp10 __exp10 #endif class mydsp : public dsp { private: FAUSTFLOAT fHslider0; int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"filename\", \"noise.dsp\"); m->declare(\"name\", \"noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fHslider0 = FAUSTFLOAT(0.5f); } virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"noise\"); ui_interface->addHorizontalSlider(\"Volume\", &fHslider0, 0.5, 0.0, 1.0, 0.001); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = (4.65661287e-10f * float(fHslider0)); for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((fSlow0 * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); } Generally, several files to connect to the audio layer, controller layer, and possibly other (MIDI, OSC...) have to be used. One of them is the main file and include the others. The -i option can be added to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with faust ) to produce a single self-contained unique file. Then a faust2xxx script has to be written to chain the Faust compilation step and the C++ compilation one (and possibly others). Look at the Developing a faust2xx Script section. Adapting the Generated DSP Developing the adapted C++ file may require aggregating the generated mydsp class (subclass of the dsp base class defined in faust/dsp/dsp.h header) in the specific class, so something like the following would have to be written: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the fDSP 'compute' fDSP.compute(count, inputs, outputs); } // Do something specific }; or subclassing and extending it , so writing something like: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' mydsp::compute(count, inputs, outputs); } // Do something specific }; or decorating a DSP object using the decorator pattern , which is already implemented in this file , and can possibly be sub-classed like: class my_decorator : public decorator_dsp { private: // Do something specific public: my_decorator(dsp* dsp):decorator_dsp(dsp) { // Do something specific } virtual ~my_class() { // Do something specific } // Implementation of some of the methods // Override the 'instanceClear' method void instanceClear() { // Do something specific // Call the inherited 'instanceClear' decorator_dsp::instanceClear(); } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' decorator_dsp::compute(count, inputs, outputs); } // Do something specific }; // Decorates a concrete instance my_decorator DSP = new my_decorator(new mydsp()); ... Developing New UI Architectures For really new architectures, the UI base class, the GenericUI helper class or the GUI class (described before), have to be subclassed. Note that a lot of classes presented in the Some useful UI classes for developers section can also be subclassed or possibly enriched with additional code. Developing New Audio Architectures The audio base class has to be subclassed and each method implemented for the given audio hardware. In some cases the audio driver can adapt to the required number of DSP inputs/outputs (like the JACK audio system for instance which can open any number of virtual audio ports). But in general, the number of hardware audio inputs/outputs may not exactly match the DSP ones. This is the responsability of the audio driver to adapt to this situation. The dsp_adapter dsp decorator can help in this case. Developing a New Soundfile Loader Soundfiles are defined in the DSP program using the soundfile primitive . Here is a simple DSP program which uses a single tango.wav audio file and play it until its end: process = 0,_~+(1):soundfile(\"sound[url:{'tango.wav'}]\",2):!,!, The compiled C++ class has the following structure: class mydsp : public dsp { private: Soundfile* fSoundfile0; int iRec0[2]; int fSampleRate; .... with the Soundfile* fSoundfile0; field and its definition : struct Soundfile { void* fBuffers; // will correspond to a double** or float** pointer chosen at runtime int* fLength; // length of each part (so fLength[P] contains the length in frames of part P) int* fSR; // sample rate of each part (so fSR[P] contains the SR of part P) int* fOffset; // offset of each part in the global buffer (so fOffset[P] contains the offset in frames of part P) int fChannels; // max number of channels of all concatenated files int fParts; // the total number of loaded parts bool fIsDouble; // keep the sample format (float or double) }; The following buildUserInterface method in generated, containing a addSoundfile method called with the appropriate parameters extracted from the soundfile(\"sound[url:{'tango.wav'}]\",2) piece of DSP code, to be used to load the tango.wav audio file and prepare the fSoundfile0 field: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tp0\"); ui_interface->addSoundfile(\"sound\", \"{'tango.wav'}\", &fSoundfile0); ui_interface->closeBox(); } The specialized SoundUI architecture file is then used to load the required soundfiles at DSP init time, by using a SoundfileReader object. It only implements the addSoundfile method which will load all needed audio files, create and fill the fSoundfile0 object. Different concrete implementations are already written, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). A new audio file loader can be written by subclassing the SoundfileReader class. A pure memory reader could be implemented for instance to load wavetables to be used as the soundfile URL list. Look at the template MemoryReader class, as an example to be completed, with the following methods to be implemented: /** * Check the availability of a sound resource. * * @param path_name - the name of the file, or sound resource identified this way * * @return true if the sound resource is available, false otherwise. */ virtual bool checkFile(const std::string& path_name); /** * Get the channels and length values of the given sound resource. * * @param path_name - the name of the file, or sound resource identified this way * @param channels - the channels value to be filled with the sound resource * number of channels * @param length - the length value to be filled with the sound resource length in frames * */ virtual void getParamsFile(const std::string& path_name, int& channels, int& length); /** * Read one sound resource and fill the 'soundfile' structure accordingly * * @param path_name - the name of the file, or sound resource identified this way * @param part - the part number to be filled in the soundfile * @param offset - the offset value to be incremented with the actual * sound resource length in frames * @param max_chan - the maximum number of mono channels to fill * */ virtual void readFile(Soundfile* soundfile, const std::string& path_name, int part, int& offset, int max_chan); Another example to look at is WaveReader . The SoundUI architecture is then used the following way: mydsp DSP; // Here using a compiled time chosen SoundfileReader SoundUI* sound_interface = new SoundUI(); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; The SoundfileReader object can be dynamically choosen by using an alternate version of the SoundUI constructor, possibly choosing the sample format to be double when the DSP code is compiled with the -double option: mydsp DSP; // Here using a dynamically chosen custom MyMemoryReader SoundfileReader* sound_reader = new MyMemoryReader(...); SoundUI* sound_interface = new SoundUI(\"\", false, sound_reader, true); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; Other Languages Than C++ Most of the architecture files have been developed in C++ over the years. Thus they are ready to be used with the C++ backend and the one that generate C++ wrapped modules (like the LLVM, Cmajor and Interpreter backends). For other languages, specific architecture files have to be written. Here is the current situation for other backends: the C backend needs additional CGlue.h and CInterface.h files, with the minimal-c file as a simple console mode example using them the Rust backend can be used with the minimal-rs architecture, the more complex JACK jack.rs used in faust2jackrust script, or the PortAudio portaudio.rs used in faust2portaudiorust script the experimental Dlang backend can be used with the minimal.d or the dplug.d to generate DPlug plugins with the faust2dplug script. the Julia backend can be used with the minimal.jl architecture or the portaudio.jl used in faust2portaudiojulia script. The faust2xx Scripts Using faust2xx Scripts The faust2xx scripts finally combine different architecture files to generate a ready-to-use application or plugin, etc... from a Faust DSP program. They typically combine the generated DSP with an UI architecture file and an audio architecture file. Most of the also have addition options like -midi , -nvoices <num> , -effect <auto|effect.dsp> or -soundfile to generate polyphonic instruments with or without effects, or audio file support. Look at the following page for a more complete description. Developing a faust2xx Script The faust2xx script are mostly written in bash (but any scripting language can be used) and aims to produce a ready-to-use application, plugin, etc... from a DSP program. A faust2minimal template script using the C++ backend, can be used to start the process. The helper scripts, faustpath , faustoptflags , and usage.sh can be used to setup common variables: # Define some common paths . faustpath # Define compilation flags . faustoptflags # Helper file to build the 'help' option . usage.sh CXXFLAGS+=\" $MYGCCFLAGS\" # So that additional CXXFLAGS can be used # The architecture file name ARCHFILE=$FAUSTARCH/minimal.cpp # Global variables OPTIONS=\"\" FILES=\"\" The script arguments then have to be analysed, compiler options are kept in the OPTIONS variable and all DSP files in the FILES one: #------------------------------------------------------------------- # dispatch command arguments #------------------------------------------------------------------- while [ $1 ] do p=$1 if [ $p = \"-help\" ] || [ $p = \"-h\" ]; then usage faust2minimal \"[options] [Faust options] <file.dsp>\" exit fi echo \"dispatch command arguments\" if [ ${p:0:1} = \"-\" ]; then OPTIONS=\"$OPTIONS $p\" elif [[ -f \"$p\" ]] && [ ${p: -4} == \".dsp\" ]; then FILES=\"$FILES $p\" else OPTIONS=\"$OPTIONS $p\" fi shift done Each DSP file is first compiled to C++ using the faust -a command and the appropriate architecture file, then to the final executable program, here using the C++ compiler: #------------------------------------------------------------------- # compile the *.dsp files #------------------------------------------------------------------- for f in $FILES; do # compile the DSP to c++ using the architecture file echo \"compile the DSP to c++ using the architecture file\" faust -i -a $ARCHFILE $OPTIONS \"$f\" -o \"${f%.dsp}.cpp\"|| exit # compile c++ to binary echo \"compile c++ to binary\" ( $CXX $CXXFLAGS \"${f%.dsp}.cpp\" -o \"${f%.dsp}\" ) > /dev/null || exit # remove tempory files rm -f \"${f%.dsp}.cpp\" # collect binary file name for FaustWorks BINARIES=\"$BINARIES${f%.dsp};\" done echo $BINARIES The existing faust2xx scripts can be used as examples. The faust2api Model This model combining the generated DSP the audio and UI architecture components is very convenient to automatically produce ready-to-use standalone application or plugins, since the controller part (GUI, MIDI or OSC...) is directly compiled and deployed. In some cases, developers prefer to control the DSP by creating a completely new GUI (using a toolkit not supported in the standard architecture files), or even without any GUI and using another control layer. A model that only combines the generated DSP with an audio architecture file to produce an audio engine has been developed (thus gluing the blue and red parts of the three color model explained at the beginning). A generic template class DspFaust has been written in the DspFaust.h and DspFaust.cpp files. This code contains conditional compilation sections to add and initialize the appropriate audio driver (written as a subclass of the previously described base audio class), and can produce audio generators , effects , of fully MIDI and sensor controllable pophyphonic instruments . The resulting audio engine contains start and stop methods to control audio processing. It also provides a set of functions like getParamsCount, setParamValue, getParamValue etc. to access all parameters (or the additional setVoiceParamValue method function to access a single voice in a polyphonic case), and let the developer adds his own GUI or any kind of controller. Look at the faust2api script, which uses the previously described architecture files, and provide a tool to easily generate custom APIs based on one or several Faust objects. Using the -inj Option With faust2xx Scripts The compiler -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. Two examples of use are presented next. Using the template-llvm.cpp architecture The first one demonstrates how faust2xx scripts can become more dynamic by loading and compiling an arbitrary DSP at runtime. This is done using the template-llvm.cpp architecture file which uses the libfaust library and the LLVM backend to dynamically compile a foo.dsp file. So instead of producing a static binary based on a given DSP, the resulting program will be able to load and compile a DSP at runtime. This template-llvm.cpp can be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application, ready to be used to load and compile a DSP, and run it with the CoreAudio audio layer and GTK as the GUI freamework. Then faust2cagtk-llvm will ask for a DSP to compile: ./faust2cagtk-llvm <Enter a foo.dsp file> A generic polyphonic (8 voices) and MIDI controllable version can be compiled using: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp (a dummy DSP) Note that the resulting binary keeps its own control options, like: ./faust2cagtk-llvm -h ./faust2cagtk-llvm [--frequency <val>] [--buffer <val>] [--nvoices <val>] [--control <0/1>] [--group <0/1>] [--virtual-midi <0/1>] So now ./faust2cagtk-llvm --nvoices 16 starts the program with 16 voices. The technique has currently be tested with the faust2cagtk , faust2jack , faust2csvplot , and faust2plot tools. Second use-case computing the spectrogram of a set of audio files Here is a second use case where some external C++ code is used to compute the spectrogram of a set of audio files (which is something that cannot be simply done with the current version fo the Faust language) and output the spectrogram as an audio signal. A nentry controller will be used to select the currently playing spectrogram. The Faust compiler will be used to generate a C++ class which is going to be manually edited and enriched with additional code. Writting the DSP code First a fake DSP program spectral.dsp using the soundfile primitive loading two audio files and a nentry control is written: sf = soundfile(\"sound[url:{'sound1.wav';'sound2.wav'}]\",2); process = (hslider(\"Spectro\", 0, 0, 1, 1),0) : sf : !,!,_,_; The point of explicitly using soundfile primitive and a nentry control is to generate a C++ file with a prefilled DSP structure (containing the fSoundfile0 and fHslider0 fields) and code inside the buildUserInterface method. Compiling it manually with the following command: faust spectral.dsp -cn spectral -o spectral.cpp produces the following C++ code containing the spectral class: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectrogram\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); .... } }; Customizing the C++ code Now the spectral class can be manually edited and completed with additional code, to compute the two audio files spectrograms in buildUserInterface , and play them in compute . a new line Spectrogram fSpectro[2]; is added in the DSP structure a createSpectrogram(fSoundfile0, fSpectro); function is added in buildUserInterface and used to compute and fill the two spectrograms, by reading the two loaded audio files in fSoundfile0 part of the generated code in compute is removed and replaced by new code to play one of spectrograms (selected with the fHslider0 control in the GUI) using a playSpectrogram(fSpectro, count, iSlow0, outputs); function: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; Spectrogram fSpectro[2]; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectro\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); // Read 'fSoundfile0' and fill 'fSpectro' createSpectrogram(fSoundfile0, fSpectro); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); // Play 'fSpectro' indexed by 'iSlow0' by writting 'count' samples in 'outputs' playSpectrogram(fSpectro, count, iSlow0, outputs); } }; Here we assume that createSpectrogram and playSpectrogram functions are defined elsewhere and ready to be compiled. Deploying it as a Max/MSP External Using the faust2max6 Script The completed spectral.cpp file is now ready to be deployed as a Max/MSP external using the faust2max6 script and the -inj option with the following line: faust2max6 -inj spectral.cpp -soundfile spectral.dsp The two needed sound1.wav and sound2.wav audio files are embedded in the generated external, loaded at init time (since the buildUserInterface method is automatically called), and the manually added C++ code will be executed to compute the spectrograms and play them. Finally by respecting the naming coherency for the fake spectral.dsp DSP program, the generated spectral.cpp C++ file, the automatically generated spectral.maxpat Max/MSP patch will be able to build the GUI with a ready-to-use slider. Additional Ressources Several external projects are providing tools to arrange the way Faust source code is generated or used, in different languages. Preprocessing tools fpp fpp is a standalone Perl script with no dependencies which allows ANY C/C++ code in a Faust .dsp file as long as you are targeting C/C++ in scalar mode. C++ tools Using and adapting the dsp/UI/audio model in a more sophisticated way, or integrating Faust generated C++ classes in others frameworks (like JUCE). faust2hpp Convert Faust code to a header-only standalone C++ library. A collection of header files is generated as the output. A class is provided from which a DSP object can be built with methods in the style of JUCE DSP objects. faustpp A post-processor for Faust, which allows to generate with more flexibility. This is a source transformation tool based on the Faust compiler. It permits to arrange the way how Faust source is generated with greater flexibility. cookiecutter-dpf-faust A cookiecutter project template for DISTRHO plugin framework audio effect plugins using Faust for the implementation of the DSP pipeline. faustmd Static metadata generator for Faust/C++. This program builds the metadata for a Faust DSP ahead of time, rather than dynamically. The result is a block of C++ code which can be appended to the code generation. FaustCPPConverter Eyal Amir tool to facilitate the use of Faust generated C++ code in JUCE projects. JOSModules and josm_faust Julius Smith projects to facilitate the use of Faust generated C++ code in JUCE projects. Arduino tools An alternative way to use the ESP32 board with Faust, possibly easier and more versatile than the examples mentioned on the esp32 tutorial . Cmajor tools Using Faust in Cmajor A tutorial to show how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. RNBO tools Using Faust in RNBO with codebox~ A tutorial to show how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DLang tools Faust 2 Dplug Guide Explains how to use Faust in a Dplug project. Dplug Faust Example This is an example plugin using Dplug with a Faust backend. It is a stereo reverb plugin using the Freeverb demo from the Faust library. Julia tools Faust.jl Julia wrapper for the Faust compiler. Uses the Faust LLVM C API. Using Faust in Julia A tutorial to show how Faust can be used with Julia , a high-level, general-purpose dynamic programming language with features well suited for numerical analysis and computational science. Python tools FAUSTPy FAUSTPy is a Python wrapper for the FAUST DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust Ctypes A port of Marc Joliet's FaustPy from CFFI to Ctypes. Faust-Ctypes documentation is available online . An SCons Tool for FAUST This is an SCons tool for compiling FAUST programs. It adds various builders to your construction environment: Faust, FaustXML, FaustSVG, FaustSC, and FaustHaskell. Their behaviour can be modified by changing various construction variables (see \"Usage\" below). Faustwatch At the moment there is one tool present, faustwatch.py. Faustwatch is a tool that observes a .dsp file used by the dsp language Faust. faustWidgets Creates interactive widgets inside jupyter notebooks from Faust dsp files and produces a (customizable) plot. Faust Synth This is an example project for controlling a synth, programmed and compiled with Faust, through a Python script. The synth runs as a JACK client on Linux systems and the output is automatically recorded by jack_capture. DawDreamer DawDreamer is an audio-processing Python framework supporting Faust and Faust's Box API. ode2dsp ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Finite difference equations (FDEs) are rendered to Faust code. faustlab A exploratory project to wrap the Faust interpreter for use by python via the following wrapping frameworks using the RtAudio cross-platform audio driver: cyfaust: cython (faust c++ interface) cfaustt: cython (faust c interface) pyfaust: pybind11 (faust c++ interface) nanobind: nanobind (faust c++ interface) cyfaust A cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. Rust tools rust-faust A better integration of Faust for Rust. It allows to build the DSPs via build.rs and has some abstractions to make it much easier to work with params and meta of the DSPs. Faust egui Proof of concept of drawing a UI with egui and rust-faust . RustFaustExperiments Tools to compare C++ and Rust code generated from Faust. fl-tui Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs Another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. lowpass-lr4-faust-nih-plug A work-in-progress project to integrate Faust generated Rust code with NIH-plug . nih-faust-jit A plugin to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project. WebAssembly tools faust-loader Import Faust .dsp files, and get back an AudioWorklet or ScriptProcessor node. faust2cpp2wasm A drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend. Faust Compiler Microservice This is a microservice that serves a single purpose: compiling Faust code that is sent to it into WebAssembly that can then be loaded and run natively from within the web synth application. It is written in go because go is supposed to be good for this sort of thing. mosfez-faust Makes dynamic compilation of Faust on the web a little easier, and has a dev project to run values through dsp offline, and preview dsp live. It's an opinionated version of some parts of Faust for webaudio , mostly just the Web Assembly Faust compiler, wrapped up in a library with additional features. faust-wap2-playground Playground and template for Faust-based web audio experiments. Dart tools flutter_faust_ffi A basic flutter app as a proof of concept utilizing Faust's C API export with Dart's ffi methods to create cross-platform plug-ins.","title":"Architecture Files"},{"location":"manual/architectures/#architecture-files","text":"A Faust program describes a signal processor , a pure DSP computation that maps input signals to output signals . It says nothing about audio drivers or controllers (like GUI, OSC, MIDI, sensors) that are going to control the DSP. This additional 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 controllers interfaces to be used. This approach allows a single Faust program to be easily deployed to a large variety of audio standards (e.g., Max/MSP externals, PD externals, VST plugins, CoreAudio applications, JACK applications, iPhone/Android, etc.): The architecture to be used is specified at compile time with the -a option. For example faust -a jack-gtk.cpp foo.dsp indicates to use the JACK GTK architecture when compiling foo.dsp . Some of these architectures are a modular combination of an audio module and one or more controller modules . Some architecture only combine an audio module with the generated DSP to create an audio engine to be controlled with an additional setParamValue/getParamValue kind of API, so that the controller part can be completeley defined externally. This is the purpose of the faust2api script explained later on.","title":"Architecture Files"},{"location":"manual/architectures/#minimal-structure-of-an-architecture-file","text":"Before going into the details of the architecture files provided with Faust distribution, it is important to have an idea of the essential parts that compose an architecture file. Technically, an architecture file is any text file with two placeholders <<includeIntrinsic>> and <<includeclass>> . The first placeholder is currently not used, and the second one is replaced by the code generated by the FAUST compiler. Therefore, the really minimal architecture file, let's call it nullarch.cpp , is the following: <<includeIntrinsic>> <<includeclass>> This nullarch.cpp architecture has the property that faust foo.dsp and faust -a nullarch.cpp foo.dsp produce the same result. Obviously, this is not very useful, moreover the resulting cpp file doesn't compile. Here is miniarch.cpp , a minimal architecture file that contains enough information to produce a cpp file that can be successfully compiled: <<includeIntrinsic>> #define FAUSTFLOAT float class dsp {}; struct Meta { virtual void declare(const char* key, const char* value) {}; }; struct Soundfile {}; struct UI { // -- widget's layouts virtual void openTabBox(const char* label) {} virtual void openHorizontalBox(const char* label) {} virtual void openVerticalBox(const char* label) {} virtual void closeBox() {} // -- active widgets virtual void addButton(const char* label, FAUSTFLOAT* zone) {} virtual void addCheckButton(const char* label, FAUSTFLOAT* zone) {} virtual void addVerticalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addHorizontalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addNumEntry(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} // -- passive widgets virtual void addHorizontalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} virtual void addVerticalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) {} // -- metadata declarations virtual void declare(FAUSTFLOAT* zone, const char* key, const char* val) {} }; <<includeclass>> This architecture is still not very useful, but it gives an idea of what a real-life architecture file has to implement, in addition to the audio part itself. As we will see in the next section, Faust architectures are implemented using a modular approach to avoid code duplication and favor code maintenance and reuse.","title":"Minimal Structure of an Architecture File"},{"location":"manual/architectures/#audio-architecture-modules","text":"A Faust generated program has to connect to a underlying audio layer. Depending if the final program is a application or plugin, the way to connect to this audio layer will differ: applications typically use the OS audio driver API, which will be CoreAudio on macOS, ALSA on Linux, WASAPI on Windows for instance, or any kind of multi-platforms API like PortAudio or JACK . In this case a subclass of the base class audio (see later) has to be written plugins (like VST3 , Audio Unit or JUCE for instance) usually have to follow a more constrained API which imposes a life cyle , something like loading/initializing/starting/running/stopping/unloading sequence of operations. In this case the Faust generated module new/init/compute/delete methods have to be inserted in the plugin API, by calling each module function at the appropriate place.","title":"Audio Architecture Modules"},{"location":"manual/architectures/#external-and-internal-audio-sample-formats","text":"Audio samples are managed by the underlying audio layer, typically as 32 bits float or 64 bits double values in the [-1..1] interval. Their format is defined with the FAUSTFLOAT macro implemented in the architecture file as float by default. The DSP audio samples format is choosen at compile time, with the -single (= default), -double or -quad compilation option. Control parameters like buttons, sliders... also use the FAUSTFLOAT format. By default, the FAUSTFLOAT macro is written with the following code: #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif which gives it a value ( if not already defined ), and since the default internal format is float , nothing special has to be done in the general case. But when the DSP is compiled using the -double option, the audio inputs/outputs buffers have to be adapted , with a dsp_sample_adapter class, for instance like in the dynamic-jack-gt tool . Note that an architecture may redefine FAUSTFLOAT in double, and have the complete audio chain running in double. This has to be done before including any architecture file that would define FAUSTFLOAT itself (because of the #ifndef logic).","title":"External and internal audio sample formats"},{"location":"manual/architectures/#connection-to-an-audio-driver-api","text":"An audio driver architecture typically connects a Faust program to the audio drivers. It is responsible for: allocating and releasing the audio channels and presenting the audio as non-interleaved float/double data (depending of the FAUSTFLOAT macro definition), normalized between -1.0 and 1.0 calling the DSP init method at init time, to setup the ma.SR variable possibly used in the DSP code calling the DSP compute method to handle incoming audio buffers and/or to produce audio outputs. The default compilation model uses separated audio input and output buffers not referring to the same memory locations. The -inpl (--in-place) code generation model allows us to generate code working when input and output buffers are the same (which is typically needed in some embedded devices). This option currently only works in scalar (= default) code generation mode. A Faust audio architecture module derives from an audio class can be defined as below (simplified version, see the real version here) : class audio { public: audio() {} virtual ~audio() {} /** * Init the DSP. * @param name - the DSP name to be given to the audio driven * (could appear as a JACK client for instance) * @param dsp - the dsp that will be initialized with the driver sample rate * * @return true is sucessful, false if case of driver failure. **/ virtual bool init(const char* name, dsp* dsp) = 0; /** * Start audio processing. * @return true is sucessfull, false if case of driver failure. **/ virtual bool start() = 0; /** * Stop audio processing. **/ virtual void stop() = 0; void setShutdownCallback(shutdown_callback cb, void* arg) = 0; // Return buffer size in frames. virtual int getBufferSize() = 0; // Return the driver sample rate in Hz. virtual int getSampleRate() = 0; // Return the driver hardware inputs number. virtual int getNumInputs() = 0; // Return the driver hardware outputs number. virtual int getNumOutputs() = 0; /** * @return Returns the average proportion of available CPU * being spent inside the audio callbacks (between 0.0 and 1.0). **/ virtual float getCPULoad() = 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. Here is the hierarchy of some of the supported audio drivers:","title":"Connection to an audio driver API"},{"location":"manual/architectures/#connection-to-a-plugin-audio-api","text":"In the case of plugin, an audio plugin architecture has to be developed, by integrating the Faust DSP new/init/compute/delete methods in the plugin API. Here is a concrete example using the JUCE framework: a FaustPlugInAudioProcessor class, subclass of the juce::AudioProcessor has to be defined. The Faust generated C++ instance will be created in its constructor, either in monophonic of polyphonic mode (see later sections) the Faust DSP instance is initialized in the JUCE prepareToPlay method using the current sample rate value the Faust dsp compute is called in the JUCE process which receives the audio inputs/outputs buffers to be processed additional methods can possibly be implemented to handle MIDI messages or save/restore the plugin parameters state for instance. This methodology obviously has to be adapted for each supported plugin API.","title":"Connection to a plugin audio API"},{"location":"manual/architectures/#midi-architecture-modules","text":"A MIDI architecture module typically connects a Faust program to the MIDI drivers. MIDI control connects DSP parameters with MIDI messages (in both directions), and can be used to trigger polyphonic instruments.","title":"MIDI Architecture Modules"},{"location":"manual/architectures/#midi-messages-in-the-dsp-source-code","text":"MIDI control messages are described as metadata in UI elements. They are decoded by a MidiUI class, subclass of UI , which parses incoming MIDI messages and updates the appropriate control parameters, or sends MIDI messages when the UI elements (sliders, buttons...) are moved.","title":"MIDI Messages in the DSP Source Code"},{"location":"manual/architectures/#defined-standard-midi-messages","text":"A special [midi:xxx yyy...] metadata needs to be added to the UI element. The full description of supported MIDI messages is part of the Faust documentation .","title":"Defined Standard MIDI Messages"},{"location":"manual/architectures/#midi-classes","text":"A midi base class defining MIDI messages decoding/encoding methods has been developed. It will be used to receive and transmit MIDI messages: class midi { public: midi() {} virtual ~midi() {} // Additional timestamped API for MIDI input virtual MapUI* keyOn(double, int channel, int pitch, int velocity) { return keyOn(channel, pitch, velocity); } virtual void keyOff(double, int channel, int pitch, int velocity = 0) { keyOff(channel, pitch, velocity); } virtual void keyPress(double, int channel, int pitch, int press) { keyPress(channel, pitch, press); } virtual void chanPress(double date, int channel, int press) { chanPress(channel, press); } virtual void pitchWheel(double, int channel, int wheel) { pitchWheel(channel, wheel); } virtual void ctrlChange(double, int channel, int ctrl, int value) { ctrlChange(channel, ctrl, value); } virtual void ctrlChange14bits(double, int channel, int ctrl, int value) { ctrlChange14bits(channel, ctrl, value); } virtual void rpn(double, int channel, int ctrl, int value) { rpn(channel, ctrl, value); } virtual void progChange(double, int channel, int pgm) { progChange(channel, pgm); } virtual void sysEx(double, std::vector<unsigned char>& message) { sysEx(message); } // MIDI sync virtual void startSync(double date) {} virtual void stopSync(double date) {} virtual void clock(double date) {} // Standard MIDI API virtual MapUI* keyOn(int channel, int pitch, int velocity) { return nullptr; } virtual void keyOff(int channel, int pitch, int velocity) {} virtual void keyPress(int channel, int pitch, int press) {} virtual void chanPress(int channel, int press) {} virtual void ctrlChange(int channel, int ctrl, int value) {} virtual void ctrlChange14bits(int channel, int ctrl, int value) {} virtual void rpn(int channel, int ctrl, int value) {} virtual void pitchWheel(int channel, int wheel) {} virtual void progChange(int channel, int pgm) {} virtual void sysEx(std::vector<unsigned char>& message) {} enum MidiStatus { // channel voice messages MIDI_NOTE_OFF = 0x80, MIDI_NOTE_ON = 0x90, MIDI_CONTROL_CHANGE = 0xB0, MIDI_PROGRAM_CHANGE = 0xC0, MIDI_PITCH_BEND = 0xE0, MIDI_AFTERTOUCH = 0xD0, // aka channel pressure MIDI_POLY_AFTERTOUCH = 0xA0, // aka key pressure MIDI_CLOCK = 0xF8, MIDI_START = 0xFA, MIDI_CONT = 0xFB, MIDI_STOP = 0xFC, MIDI_SYSEX_START = 0xF0, MIDI_SYSEX_STOP = 0xF7 }; enum MidiCtrl { ALL_NOTES_OFF = 123, ALL_SOUND_OFF = 120 }; enum MidiNPN { PITCH_BEND_RANGE = 0 }; }; A pure interface for MIDI handlers that can send/receive MIDI messages to/from midi objects is defined: struct midi_interface { virtual void addMidiIn(midi* midi_dsp) = 0; virtual void removeMidiIn(midi* midi_dsp) = 0; virtual ~midi_interface() {} }; A midi_hander subclass implements actual MIDI decoding and maintains a list of MIDI aware components (classes inheriting from midi and ready to send and/or receive MIDI events) using the addMidiIn/removeMidiIn methods: class midi_handler : public midi, public midi_interface { protected: std::vector<midi*> fMidiInputs; std::string fName; MidiNRPN fNRPN; public: midi_handler(const std::string& name = \"MIDIHandler\"):fName(name) {} virtual ~midi_handler() {} void addMidiIn(midi* midi_dsp) {...} void removeMidiIn(midi* midi_dsp) {...} ... ... }; Several concrete implementations subclassing midi_handler using native APIs have been written and can be found in the faust/midi folder: Depending on the native MIDI API being used, event timestamps are either expressed in absolute time or in frames. They are converted to offsets expressed in samples relative to the beginning of the audio buffer. Connected with the MidiUI class (a subclass of UI ), they allow a given DSP to be controlled with incoming MIDI messages or possibly send MIDI messages when its internal control state changes. In the following piece of code, a MidiUI object is created and connected to a rt_midi MIDI messages handler (using the RTMidi library), then given as a parameter to the standard buildUserInterface to control DSP parameters: ... rt_midi midi_handler(\"MIDI\"); MidiUI midi_interface(&midi_handler); DSP->buildUserInterface(&midi_interface); ...","title":"MIDI Classes"},{"location":"manual/architectures/#ui-architecture-modules","text":"A UI architecture module links user actions (i.e., 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\u2019s values according to user actions. This association is triggered by the 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: an UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout. A Faust UI architecture module derives the UI base class: template <typename REAL> struct UIReal { UIReal() {} virtual ~UIReal() {} // -- widget's layouts virtual void openTabBox(const char* label) = 0; virtual void openHorizontalBox(const char* label) = 0; virtual void openVerticalBox(const char* label) = 0; virtual void closeBox() = 0; // -- active widgets virtual void addButton(const char* label, REAL* zone) = 0; virtual void addCheckButton(const char* label, REAL* zone) = 0; virtual void addVerticalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addHorizontalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addNumEntry(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; // -- passive widgets virtual void addHorizontalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; virtual void addVerticalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) = 0; // -- metadata declarations virtual void declare(REAL* zone, const char* key, const char* val) {} }; struct UI : public UIReal<FAUSTFLOAT> { UI() {} virtual ~UI() {} }; The FAUSTFLOAT* zone element is the primary connection point between the control interface and the dsp code. The compiled dsp Faust code will give access to all internal control value addresses used by the dsp code by calling the approriate addButton , addVerticalSlider , addNumEntry etc. methods (depending of what is described in the original Faust DSP source code). The control/UI code keeps those addresses, and will typically change their pointed values each time a control value in the dsp code has to be changed. On the dsp side, all control values are sampled once at the beginning of the compute method, so that to keep the same value during the entire audio buffer. Writing and reading the control values is typically done in two different threads: the controller (a GUI, an OSC or MIDI.etc. one) write the values, and the audio real-time thread read them in the audio callback. Since writing/reading the FAUSTFLOAT* zone element is atomic, there is no need (in general) of complex synchronization mechanism between the writer (controller) and the reader (the Faust dsp object). Here is part of the UI classes hierarchy:","title":"UI Architecture Modules"},{"location":"manual/architectures/#active-widgets","text":"Active widgets are graphical elements controlling a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double ). Active widgets in Faust are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values.","title":"Active Widgets"},{"location":"manual/architectures/#passive-widgets","text":"Passive widgets are graphical elements reflecting values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value. Passive widgets in Faust are HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type.","title":"Passive Widgets"},{"location":"manual/architectures/#widgets-layout","text":"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.","title":"Widgets Layout"},{"location":"manual/architectures/#metadata","text":"The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT* zone, const char* key, const char* value); Here is the table of currently supported general medadata: Key Value tooltip actual string content hidden 0 or 1 unit Hz or dB scale log or exp style knob or led or numerical style radio{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} style menu{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Here acc means accelerometer and gyr means gyroscope , both use the same parameters (a mapping description) but are linked to different sensors. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\u2019white noise\u2019:0;\u2019pink noise\u2019:1;\u2019sine\u2019:2}][hidden:0]\", 0, 20, 100, 1) or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) When one or several metadata are added in the same item label, then will appear in the generated code as one or successives declare(FAUSTFLOAT* zone, const char* key, const char* value); lines before the line describing the item itself. Thus the UI managing code has to associate them with the proper item. Look at the MetaDataUI class for an example of this technique. MIDI specific metadata are described here and are decoded the MidiUI class. Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for example) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future and can possibly be adapted for a specific project. They can be decoded using the MetaDataUI class.","title":"Metadata"},{"location":"manual/architectures/#graphic-oriented-pure-controllers-code-generator-ui","text":"Even if the UI architecture module is graphic-oriented, a given implementation can perfectly choose to ignore all layout information and only keep the controller ones, like the buttons, sliders, nentries, bargraphs. This is typically what is done in the MidiUI or OSCUI architectures. Note that pure code generator can also be written. The JSONUI UI architecture is an example of an architecture generating the DSP JSON description as a text file.","title":"Graphic-oriented, pure controllers, code generator UI"},{"location":"manual/architectures/#dsp-json-description","text":"The full description of a given compiled DSP can be generated as a JSON file, to be used at several places in the architecture system. This JSON describes the DSP with its inputs/outputs number, some metadata (filename, name, used compilation parameters, used libraries etc.) as well as its UI with a hierarchy of groups up to terminal items ( buttons , sliders , nentries , bargraphs ) with all their parameters ( type , label , shortname , address , meta , init , min , max and step values). For the following DSP program: import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq = hslider(\"freq [unit:Hz]\", 600, 20, 2000, 1); process = vgroup(\"Oscillator\", os.osc(freq) * vol) <: (_,_); The generated JSON file is then: { \"name\": \"foo\", \"filename\": \"foo.dsp\", \"version\": \"2.40.8\", \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\", \"library_list\": [], \"include_pathnames\": [\"/usr/local/share/faust\"], \"inputs\": 0, \"outputs\": 2, \"meta\": [ { \"basics.lib/name\": \"Faust Basic Element Library\" }, { \"basics.lib/version\": \"0.6\" }, { \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\" }, { \"filename\": \"foo.dsp\" }, { \"maths.lib/author\": \"GRAME\" }, { \"maths.lib/copyright\": \"GRAME\" }, { \"maths.lib/license\": \"LGPL with exception\" }, { \"maths.lib/name\": \"Faust Math Library\" }, { \"maths.lib/version\": \"2.5\" }, { \"name\": \"tes\" }, { \"oscillators.lib/name\": \"Faust Oscillator Library\" }, { \"oscillators.lib/version\": \"0.3\" }, { \"platform.lib/name\": \"Generic Platform Library\" }, { \"platform.lib/version\": \"0.2\" }, { \"signals.lib/name\": \"Faust Signal Routing Library\" }, { \"signals.lib/version\": \"0.1\" } ], \"ui\": [ { \"type\": \"vgroup\", \"label\": \"Oscillator\", \"items\": [ { \"type\": \"hslider\", \"label\": \"freq\", \"shortname\": \"freq\", \"address\": \"/Oscillator/freq\", \"meta\": [ { \"unit\": \"Hz\" } ], \"init\": 600, \"min\": 20, \"max\": 2000, \"step\": 1 }, { \"type\": \"hslider\", \"label\": \"volume\", \"shortname\": \"volume\", \"address\": \"/Oscillator/volume\", \"meta\": [ { \"unit\": \"dB\" } ], \"init\": 0, \"min\": -96, \"max\": 0, \"step\": 0.1 } ] } ] } The JSON file can be generated with faust -json foo.dsp command, or programmatically using the JSONUI UI architecture (see next Some Useful UI Classes and Tools for Developers section). Here is the description of ready-to-use UI classes, followed by classes to be used in developer code:","title":"DSP JSON Description"},{"location":"manual/architectures/#gui-builders","text":"Here is the description of the main GUI classes: the GTKUI class uses the GTK toolkit to create a Graphical User Interface with a proper group-based layout the QTUI class uses the QT toolkit to create a Graphical User Interface with a proper group based layout the JuceUI class uses the JUCE framework to create a Graphical User Interface with a proper group based layout","title":"GUI Builders"},{"location":"manual/architectures/#non-gui-controllers","text":"Here is the description of the main non-GUI controller classes: the OSCUI class implements OSC remote control in both directions the httpdUI class implements HTTP remote control using the libmicrohttpd library to embed a HTTP server inside the application. Then by opening a browser on a specific URL, the GUI will appear and allow to control the distant application or plugin. The connection works in both directions the MIDIUI class implements MIDI control in both directions, and it explained more deeply later on","title":"Non-GUI Controllers"},{"location":"manual/architectures/#some-useful-ui-classes-and-tools-for-developers","text":"Some useful UI classes and tools can possibly be reused in developer code: the MapUI class establishes a mapping beween UI items and their labels , shortname or paths , and offers a setParamValue/getParamValue API to set and get their values. It uses an helper PathBuilder class to create complete shortnames and pathnames to the leaves in the UI hierarchy. Note that the item path encodes the UI hierarchy in the form of a /group1/group2/.../label string and is the way to distinguish control that may have the same label, but different localisation in the UI tree. Using shortnames (built so that they never collide) is an alternative way to access items. The setParamValue/getParamValue API takes either labels , shortname or paths as the way to describe the control, but using shortnames or paths is the safer way to use it the extended APIUI offers setParamValue/getParamValue API similar to MapUI , with additional methods to deal with accelerometer/gyroscope kind of metadata the MetaDataUI class decodes all currently supported metadata and can be used to retrieve their values the JSONUI class allows us to generate the JSON description of a given DSP the JSONUIDecoder class is used to decode the DSP JSON description and implement its buildUserInterface and metadata methods the FUI class allows us to save and restore the parameters state as a text file the SoundUI class with the associated Soundfile class is used to implement the soundfile primitive, and load the described audio resources (typically audio files), by using different concrete implementations, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). Paths to sound files can be absolute, but it should be noted that a relative path mechanism can be set up when creating an instance of SoundUI , in order to load sound files with a more flexible strategy. the ControlSequenceUI class with the associated OSCSequenceReader class allow to control parameters change in time, using the OSC time tag format. Changing the control values will have to be mixed with audio rendering. Look at the sndfile.cpp use-case. the ValueConverter file contains several mapping classes used to map user interface values (for example a gui slider delivering values between 0 and 1) to Faust values (for example a vslider between 20 and 2000) using linear/log/exp scales. It also provides classes to handle the [acc:a b c d e] and [gyr:a b c d e] Sensors Control Metadatas .","title":"Some Useful UI Classes and Tools for Developers"},{"location":"manual/architectures/#multi-controller-and-synchronization","text":"A given DSP can perfectly be controlled by several UI classes at the same time, and they will all read and write the same DSP control memory zones. Here is an example of code using a GUI using GTKUI architecture, as well as OSC control using OSCUI : ... GTKUI gtk_interface(name, &argc, &argv); DSP->buildUserInterface(&gtk_interface); OSCUI osc_interface(name, argc, argv); DSP->buildUserInterface(&osc_interface); ... Since several controller access the same values, you may have to synchronize them, in order for instance to have the GUI sliders or buttons reflect the state that would have been changed by the OSCUI controller at reception time, of have OSC messages been sent each time UI items like sliders or buttons are moved. This synchronization mecanism is implemented in a generic way in the GUI class. First the uiItemBase class is defined as the basic synchronizable memory zone, then grouped in a list controlling the same zone from different GUI instances. The uiItemBase::modifyZone method is used to change the uiItemBase state at reception time, and uiItemBase::reflectZone will be called to reflect a new value, and can change the Widget layout for instance, or send a message (OSC, MIDI...). All classes needing to use this synchronization mechanism will have to subclass the GUI class, which keeps all of them at runtime in a static class GUI::fGuiList variable. This is the case for the previously used GTKUI and OSCUI classes. Note that when using the GUI class, the 2 following static class variables have to be defined in the code, (once in one .cpp file in the project) like in this code example: // Globals std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; Finally the static GUI::updateAllGuis() synchronization method will have to be called regularly, in the application or plugin event management loop, or in a periodic timer for instance. This is typically implemented in the GUI::run method which has to be called to start event or messages processing. In the following code, the OSCUI::run method is called first to start processing OSC messages, then the blocking GTKUI::run method, which opens the GUI window, to be closed to finally finish the application: ... // Start OSC messages processing osc_interface.run(); // Start GTK GUI as the last one, since it blocks until the opened window is closed gtk_interface.run() ...","title":"Multi-Controller and Synchronization"},{"location":"manual/architectures/#dsp-architecture-modules","text":"The Faust compiler produces a DSP module whose format will depend of the chosen backend: a C++ class with the -lang cpp option, a data structure with associated functions with the -lang c option, an LLVM IR module with the -lang llvm option, a WebAssembly binary module with the -lang wasm option, a bytecode stream with the -lang interp option... and so on.","title":"DSP Architecture Modules"},{"location":"manual/architectures/#the-base-dsp-class","text":"In C++, the generated class derives from a base dsp class: class dsp { public: dsp() {} virtual ~dsp() {} /* Return instance number of audio inputs */ virtual int getNumInputs() = 0; /* Return instance number of audio outputs */ virtual int getNumOutputs() = 0; /** * Trigger the ui_interface parameter with instance specific calls * to 'openTabBox', 'addButton', 'addVerticalSlider'... in order to build the UI. * * @param ui_interface - the user interface builder */ virtual void buildUserInterface(UI* ui_interface) = 0; /* Return the sample rate currently used by the instance */ virtual int getSampleRate() = 0; /** * Global init, calls the following methods: * - static class 'classInit': static tables initialization * - 'instanceInit': constants and instance state initialization * * @param sample_rate - the sampling rate in Hz */ virtual void init(int sample_rate) = 0; /** * Init instance state * * @param sample_rate - the sampling rate in Hz */ virtual void instanceInit(int sample_rate) = 0; /** * Init instance constant state * * @param sample_rate - the sampling rate in HZ */ virtual void instanceConstants(int sample_rate) = 0; /* Init default control parameters values */ virtual void instanceResetUserInterface() = 0; /* Init instance state (like delay lines..) but keep the control parameter values */ virtual void instanceClear() = 0; /** * Return a clone of the instance. * * @return a copy of the instance on success, otherwise a null pointer. */ virtual dsp* clone() = 0; /** * Trigger the Meta* parameter with instance specific calls to 'declare' * (key, value) metadata. * * @param m - the Meta* meta user */ virtual void metadata(Meta* m) = 0; /** * DSP instance computation, to be called with successive in/out audio buffers. * * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * */ virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; /** * Alternative DSP instance computation method for use by subclasses, incorporating an additional `date_usec` parameter, * which specifies the timestamp of the first sample in the audio buffers. * * @param date_usec - the timestamp in microsec given by audio driver. By convention timestamp of -1 means 'no timestamp conversion', * events already have a timestamp expressed in frames. * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * */ virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; }; The dsp class is central to the Faust architecture design: the getNumInputs , getNumOutputs methods provides information about the signal processor the buildUserInterface method creates the user interface using a given UI class object (see later) the init method (and some more specialized methods like instanceInit , instanceConstants , etc.) is called to initialize the dsp object with a given sampling rate, typically obtained from the audio architecture the compute method is called by the audio architecture to execute the actual audio processing. It takes a count number of samples to process, and inputs and outputs arrays of non-interleaved float/double samples, to be allocated and handled by the audio driver with the required dsp input and outputs channels (as given by getNumInputs and getNumOutputs ) the clone method can be used to duplicate the instance the metadata(Meta* m) method can be called with a Meta object to decode the instance global metadata (see next section) (note that FAUSTFLOAT label is typically defined to be the actual type of sample: either float or double using #define FAUSTFLOAT float in the code for instance). For a given compiled DSP program, the compiler will generate a mydsp subclass of dsp and fill the different methods (the actual name can be changed using the -cn option). For dynamic code producing backends like the LLVM IR, Cmajor or the Interpreter ones, the actual code (an LLVM module, a Cmajor module or a bytecode stream) is actually wrapped by some additional C++ code glue, to finally produces an llvm_dsp typed object (defined in the llvm-dsp.h file), a cmajorpatch_dsp typed object (defined in the cmajorpatch-dsp.h file) or an interpreter_dsp typed object (defined in interpreter-dsp.h file), ready to be used with the UI and audio C++ classes (like the C++ generated class). See the following class diagram:","title":"The Base dsp Class"},{"location":"manual/architectures/#global-dsp-metadata","text":"All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler, for instance the Faust program: declare name \"NoiseProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; import(\"stdfaust.lib\"); process = no.noise; will generate the following C++ metadata(Meta* m) method in the dsp class: void metadata(Meta* m) { m->declare(\"author\", \"MySelf\"); m->declare(\"compile_options\", \"-lang cpp -es 1 -scal -ftz 0\"); m->declare(\"copyright\", \"MyCompany\"); m->declare(\"filename\", \"metadata.dsp\"); m->declare(\"license\", \"BSD\"); m->declare(\"name\", \"NoiseProgram\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); m->declare(\"version\", \"1.00\"); } which interacts with an instance of an implementation class of the following virtual Meta class: struct Meta { virtual ~Meta() {}; virtual void declare(const char* key, const char* value) = 0; }; and are part of three different types of global metadata: metadata like compile_options or filename are automatically generated metadata like author of copyright are part of the Global Medata metadata like noises.lib/name are part of the Function Metadata Specialized subclasses of the Meta class can be implemented to decode the needed key/value pairs for a given use-case.","title":"Global DSP metadata"},{"location":"manual/architectures/#macro-construction-of-dsp-components","text":"The Faust program specification is usually entirely done in the language itself. But in some specific cases it may be useful to develop separated DSP components and combine them in a more complex setup. Since taking advantage of the huge number of already available UI and audio architecture files is important, keeping the same dsp API is preferable, so that more complex DSP can be controlled and audio rendered the usual way. Extended DSP classes will typically subclass the dsp base class and override or complete part of its API.","title":"Macro Construction of DSP Components"},{"location":"manual/architectures/#dsp-decorator-pattern","text":"A dsp_decorator class, subclass of the root dsp class has first been defined. Following the decorator design pattern, it allows behavior to be added to an individual object, either statically or dynamically. As an example of the decorator pattern, the timed_dsp class allows to decorate a given DSP with sample accurate control capability or the mydsp_poly class for polyphonic DSPs, explained in the next sections.","title":"DSP Decorator Pattern"},{"location":"manual/architectures/#combining-dsp-components","text":"A few additional macro construction classes, subclasses of the root dsp class have been defined in the dsp-combiner.h header file with a five operators construction API: the dsp_sequencer class combines two DSP in sequence, assuming that the number of outputs of the first DSP equals the number of input of the second one. It somewhat mimics the sequence (that is : ) operator of the language by combining two separated C++ objects. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSPs can be individually controlled. Its compute method is overloaded to call each DSP compute in sequence, using an intermediate output buffer produced by first DSP as the input one given to the second DSP. the dsp_parallelizer class combines two DSP in parallel. It somewhat mimics the parallel (that is , ) operator of the language by combining two separated C++ objects. Its getNumInputs/getNumOutputs methods are overloaded by correctly reflecting the input/output of the resulting DSP as the sum of the two combined ones. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSP can be individually controlled. Its compute method is overloaded to call each DSP compute, where each DSP consuming and producing its own number of input/output audio buffers taken from the method parameters. This methology is followed to implement the three remaining composition operators ( split , merge , recursion ), which ends up with a C++ API to combine DSPs with the usual five operators: createDSPSequencer , createDSPParallelizer , createDSPSplitter , createDSPMerger , createDSPRecursiver to be used at C++ level to dynamically combine DSPs. And finally the createDSPCrossfader tool allows you to crossfade between two DSP modules. The crossfade parameter (as a slider) controls the mix between the two modules outputs. When Crossfade = 1 , the first DSP only is computed, when Crossfade = 0 , the second DSP only is computed, otherwise both DSPs are computed and mixed. Note that this idea of decorating or combining several C++ dsp objects can perfectly be extended in specific projects, to meet other needs: like muting some part of a graph of several DSPs for instance. But keep in mind that keeping the dsp API then allows to take profit of all already available UI and audio based classes.","title":"Combining DSP Components"},{"location":"manual/architectures/#sample-accurate-control","text":"DSP audio languages usually deal with several timing dimensions when treating control events and generating audio samples. For performance reasons, systems maintain separated audio rate for samples generation and control rate for asynchronous messages handling. The audio stream is most often computed by blocks, and control is updated between blocks. To smooth control parameter changes, some languages chose to interpolate parameter values between blocks. In some cases control may be more finely interleaved with audio rendering, and some languages simply choose to interleave control and sample computation at sample level. Although the Faust language permits the description of sample level algorithms (i.e., like recursive filters, etc.), Faust generated DSP are usually computed by blocks. Underlying audio architectures give a fixed size buffer over and over to the DSP compute method which consumes and produces audio samples.","title":"Sample Accurate Control"},{"location":"manual/architectures/#control-to-dsp-link","text":"In the current version of the Faust generated code, the primary connection point between the control interface and the DSP code is simply a memory zone. For control inputs, the architecture layer continuously write values in this zone, which is then sampled by the DSP code at the beginning of the compute method, and used with the same values throughout the call. Because of this simple control/DSP connexion mechanism, the most recent value is used by the DSP code. Similarly for control outputs , the DSP code inside the compute method possibly writes several values at the same memory zone, and the last value only will be seen by the control architecture layer when the method finishes. Although this behaviour is satisfactory for most use-cases, some specific usages need to handle the complete stream of control values with sample accurate timing. For instance keeping all control messages and handling them at their exact position in time is critical for proper MIDI clock synchronisation.","title":"Control to DSP Link"},{"location":"manual/architectures/#timestamped-control","text":"The first step consists in extending the architecture control mechanism to deal with timestamped control events. Note that this requires the underlying event control layer to support this capability. The native MIDI API for instance is usually able to deliver timestamped MIDI messages. The next step is to keep all timestamped events in a time ordered data structure to be continuously written by the control side, and read by the audio side. Finally the sample computation has to take account of all queued control events, and correctly change the DSP control state at successive points in time.","title":"Timestamped Control"},{"location":"manual/architectures/#slices-based-dsp-computation","text":"With timestamped control messages, changing control values at precise sample indexes on the audio stream becomes possible. A generic slices based DSP rendering strategy has been implemented in the timed_dsp class. A ring-buffer is used to transmit the stream of timestamped events from the control layer to the DSP one. In the case of MIDI control for instance, the ring-buffer is written with a pair containing the timestamp expressed in samples (or microseconds) and the actual MIDI message each time one is received. In the DSP compute method, the ring-buffer will be read to handle all messages received during the previous audio block. Since control values can change several times inside the same audio block, the DSP compute cannot be called only once with the total number of frames and the complete inputs/outputs audio buffers. The following strategy has to be used: several slices are defined with control values changing between consecutive slices all control values having the same timestamp are handled together, and change the DSP control internal state. The slice is computed up to the next control parameters timestamp until the end of the given audio block is reached in the next figure, four slices with the sequence of c1, c2, c3, c4 frames are successively given to the DSP compute method, with the appropriate part of the audio input/output buffers. Control values (appearing here as [v1,v2,v3] , then [v1,v3] , then [v1] , then [v1,v2,v3] sets) are changed between slices Since timestamped control messages from the previous audio block are used in the current block, control messages are aways handled with one audio buffer latency. Note that this slices based computation model can always be directly implemented on top of the underlying audio layer, without relying on the timed_dsp wrapper class.","title":"Slices Based DSP Computation"},{"location":"manual/architectures/#audio-driver-timestamping","text":"Some audio drivers can get the timestamp of the first sample in the audio buffers, and will typically call the DSP alternative compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) function with the correct timestamp. By convention timestamp of -1 means 'no timestamp conversion', events already have a timestamp expressed in frames (see jackaudio_midi for an example driver using timestamp expressed in frames). The timed_dsp wrapper class is an example of a DSP class actually using the timestamp information.","title":"Audio driver timestamping"},{"location":"manual/architectures/#typical-use-case","text":"A typical Faust program can use the MIDI clock command signal to possibly compute the Beat Per Minutes (BPM) information for any synchronization need it may have. Here is a simple example of a sinusoid generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"stdfaust.lib\"); // square signal (1/0), changing state // at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled // with MIDI start/stop messages play = checkbox(\"On/Off [midi:start][midi:stop]\"); // detect front front(x) = (x-x\u2019) != 0.0; // count number of peaks during one second freq(x) = (x-x@ma.SR) : + ~ _; process = os.osc(8*freq(front(clocker))) * play; Each received group of 24 clocks will move the time position by exactly one beat. Then it is absolutely mandatory to never loose any MIDI clock message and the standard memory zone based model with the use the last received control value semantic is not adapted. The DSP object that needs to be controlled using the sample-accurate machinery can then simply be decorated using the timed_dsp class with the following kind of code: dsp* sample_accurate_dsp = new timed_dsp(DSP); Note that the described sample accurate MIDI clock synchronization model can currently only be used at input level. Because of the simple memory zone based connection point between the control interface and the DSP code, output controls (like bargraph) cannot generate a stream of control values. Thus a reliable MIDI clock generator cannot be implemented with the current approach.","title":"Typical Use-Case"},{"location":"manual/architectures/#polyphonic-instruments","text":"Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping.","title":"Polyphonic Instruments"},{"location":"manual/architectures/#polyphonic-ready-dsp-code","text":"By convention Faust architecture files with polyphonic capabilities expect to find control parameters named freq , gain , and gate . The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the freq parameter (which should be a frequency) will be automatically computed from MIDI note numbers, gain (which should be a value between 0 and 1) from velocity and gate from keyon/keyoff events. Thus, gate can be used as a trigger signal for any envelope generator, etc.","title":"Polyphonic ready DSP Code"},{"location":"manual/architectures/#using-the-mydsp_poly-class","text":"The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the poly-dsp.h file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp* objects, manage dynamic voice allocation, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold as a subclass of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global Polyphonic tabgroup. The first tab contains a Voices group, a master like component used to change parameters on all voices at the same time, with a Panic button to be used to stop running voices, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI , httpdUI , etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used. The polyphonic instrument allocation takes the DSP to be used for one voice, the desired number of voices, the dynamic voice allocation state, and the group state which controls if separated voices are displayed or not: dsp* poly = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: dsp* poly = new mydsp_poly(dsp, 8, false, true);","title":"Using the mydsp_poly Class"},{"location":"manual/architectures/#polyphonic-instrument-with-a-global-output-effect","text":"Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is generally not a good idea since it would be instantiated for each voice which would be very inefficient. A convention has been defined to use the effect = some effect; line in the DSP source code. The actual effect definition has to be extracted from the DSP code, compiled separately, and then combined using the dsp_sequencer class previously presented to connect the polyphonic DSP in sequence with a unique global effect, with something like: dsp* poly = new dsp_sequencer(new mydsp_poly(dsp, 2, true, true), new effect()); | Some helper classes like the base dsp_poly_factory class, and concrete implementations llvm_dsp_poly_factory when using the LLVM backend or interpreter_dsp_poly_factory when using the Interpreter backend can also be used to automatically handle the voice and effect part of the DSP.","title":"Polyphonic Instrument With a Global Output Effect"},{"location":"manual/architectures/#controlling-the-polyphonic-instrument","text":"The mydsp_poly class is also ready for MIDI control (as a class implementing the midi interface) and can react to keyOn/keyOff and pitchWheel events. Other MIDI control parameters can directly be added in the DSP source code as MIDI metadata. To receive MIDI events, the created polyphonic DSP will be automatically added to the midi_handler object when calling buildUserInterface on a MidiUI object.","title":"Controlling the Polyphonic Instrument"},{"location":"manual/architectures/#deploying-the-polyphonic-instrument","text":"Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. faustcaqt -midi -noices 12 inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. Polyphonic ready faust2xx scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready-to-use DSP.","title":"Deploying the Polyphonic Instrument"},{"location":"manual/architectures/#custom-memory-manager","text":"In C and C++, the Faust compiler produces a class (or a struct in C), to be instantiated to create each DSP instance. The standard generation model produces a flat memory layout, where all fields (scalar and arrays) are simply consecutive in the generated code (following the compilation order). So the DSP is allocated on a single block of memory, either on the stack or the heap depending on the use-case. The following DSP program: import(\"stdfaust.lib\"); gain = hslider(\"gain\", 0.5, 0, 1, 0.01); feedback = hslider(\"feedback\", 0.8, 0, 1, 0.01); echo(del_sec, fb, g) = + ~ de.delay(50000, del_samples) * fb * g with { del_samples = del_sec * ma.SR; }; process = echo(1.6, 0.6, 0.7), echo(0.7, feedback, gain); will have the flat memory layout: int IOTA0; int fSampleRate; int iConst1; float fRec0[65536]; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float fRec1[65536]; So scalar fHslider0 and fHslider1 correspond to the gain and feedback controllers. The iConst1 and iConst2 values are typically computed once at init time using the dynamically given the fSampleRate value, and used in the DSP loop later on. The fRec0 and fRec1 arrays are used for the recursive delays and finally the shared IOTA0 index is used to access them. Here is the generated compute function: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; float fSlow0 = float(fHslider0) * float(fHslider1); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 65535] = float(input0[i0]) + 0.419999987f * fRec0[(IOTA0 - iConst1) & 65535]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 65535]); fRec1[IOTA0 & 65535] = float(input1[i0]) + fSlow0 * fRec1[(IOTA0 - iConst2) & 65535]; output1[i0] = FAUSTFLOAT(fRec1[IOTA0 & 65535]); IOTA0 = IOTA0 + 1; } }","title":"Custom Memory Manager"},{"location":"manual/architectures/#the-mem-option","text":"On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. The first remark is that scalar values will typically stay in the DSP structure, and the point is to move the big array buffers ( fRec0 and fRec1 in the example) into separated memory blocks. The -mem (--memory-manager) option can be used to generate adapted code. On the previous DSP program, we now have the following generated C++ code: int IOTA0; int fSampleRate; int iConst1; float* fRec0; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float* fRec1; The two fRec0 and fRec1 arrays are becoming pointers, and will be allocated elsewhere. An external memory manager is needed to interact with the DSP code. The proposed model does the following: in a first step the generated C++ code will inform the memory allocator about its needs in terms of 1) number of separated memory zones, with 2) their size 3) access characteristics, like number of Read and Write for each frame computation. This is done be generating an additional static memoryInfo method with the complete information available, the memory manager can then define the best strategy to allocate all separated memory zones an additional memoryCreate method is generated to allocate each of the separated zones an additional memoryDestroy method is generated to deallocate each of the separated zones Here is the API for the memory manager: struct dsp_memory_manager { virtual ~dsp_memory_manager() {} /** * Inform the Memory Manager with the number of expected memory zones. * @param count - the number of memory zones */ virtual void begin(size_t count); /** * Give the Memory Manager information on a given memory zone. * @param size - the size in bytes of the memory zone * @param reads - the number of Read access to the zone used to compute one frame * @param writes - the number of Write access to the zone used to compute one frame */ virtual void info(size_t size, size_t reads, size_t writes) {} /** * Inform the Memory Manager that all memory zones have been described, * to possibly start a 'compute the best allocation strategy' step. */ virtual void end(); /** * Allocate a memory zone. * @param size - the memory zone size in bytes */ virtual void* allocate(size_t size) = 0; /** * Destroy a memory zone. * @param ptr - the memory zone pointer to be deallocated */ virtual void destroy(void* ptr) = 0; }; A class static member is added in the mydsp class, to be set with an concrete memory manager later on: dsp_memory_manager* mydsp::fManager = nullptr; The C++ generated code now contains a new memoryInfo method, which interacts with the memory manager: static void memoryInfo() { fManager->begin(3); // mydsp fManager->info(56, 9, 1); // fRec0 fManager->info(262144, 2, 1); // fRec1 fManager->info(262144, 2, 1); fManager->end(); } The begin method is first generated to inform that three separated memory zones will be needed. Then three consecutive calls to the info method are generated, one for the DSP object itself, one for each recursive delay array. The end method is then called to finish the memory layout description, and let the memory manager prepare the actual allocations. Note that the memory layout information is also available in the JSON file generated using the -json option, to possibly be used statically by the architecture machinery (that is at compile time). With the previous program, the memory layout section is: \"memory_layout\": [ { \"name\": \"mydsp\", \"type\": \"kObj_ptr\", \"size\": 0, \"size_bytes\": 56, \"read\": 9, \"write\": 1 }, { \"name\": \"IOTA0\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 7, \"write\": 1 }, { \"name\": \"iConst1\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec0\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 }, { \"name\": \"iConst2\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec1\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 } ] Finally the memoryCreate and memoryDestroy methods are generated. The memoryCreate method asks the memory manager to allocate the fRec0 and fRec1 buffers: void memoryCreate() { fRec0 = static_cast<float*>(fManager->allocate(262144)); fRec1 = static_cast<float*>(fManager->allocate(262144)); } And the memoryDestroy method asks the memory manager to destroy them: virtual memoryDestroy() { fManager->destroy(fRec0); fManager->destroy(fRec1); } Additional static create/destroy methods are generated: static mydsp* create() { mydsp* dsp = new (fManager->allocate(sizeof(mydsp))) mydsp(); dsp->memoryCreate(); return dsp; } static void destroy(dsp* dsp) { static_cast<mydsp*>(dsp)->memoryDestroy(); fManager->destroy(dsp); } Note that the so-called C++ placement new will be used to allocate the DSP object itself.","title":"The -mem option"},{"location":"manual/architectures/#static-tables","text":"When rdtable or rwtable primitives are used in the source code, the C++ class will contain a table shared by all instances of the class. By default, this table is generated as a static class array, and so allocated in the application global static memory. Taking the following DSP example: process = (waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable), (waveform {1.1,2.2,3.3,4.4,5.5,6.6,7.7}, %(7)~+(3) : rdtable); Here is the generated code in default mode: ... static int itbl0mydspSIG0[7]; static float ftbl1mydspSIG1[7]; class mydsp : public dsp { ... public: ... static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(); sig0->instanceInitmydspSIG0(sample_rate); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(); sig1->instanceInitmydspSIG1(sample_rate); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0); deletemydspSIG1(sig1); } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are static global arrays. They are filled in the classInit method. The architecture code will typically call the init method (which calls classInit ) on a given DSP, to allocate class related arrays and the DSP itself. If several DSPs are going to be allocated, calling classInit only once then the instanceInit method on each allocated DSP is the way to go. In the -mem mode, the generated C++ code is now: ... static int* itbl0mydspSIG0 = 0; static float* ftbl1mydspSIG1 = 0; class mydsp : public dsp { ... public: ... static dsp_memory_manager* fManager; static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(fManager); sig0->instanceInitmydspSIG0(sample_rate); itbl0mydspSIG0 = static_cast<int*>(fManager->allocate(28)); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(fManager); sig1->instanceInitmydspSIG1(sample_rate); ftbl1mydspSIG1 = static_cast<float*>(fManager->allocate(28)); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0, fManager); deletemydspSIG1(sig1, fManager); } static void classDestroy() { fManager->destroy(itbl0mydspSIG0); fManager->destroy(ftbl1mydspSIG1); } virtual void init(int sample_rate) {} virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are generated as static global pointers. The classInit method uses the fManager object used to allocate tables. A new classDestroy method is generated to deallocate the tables. Finally the init method is now empty, since the architecture file is supposed to use the classInit/classDestroy method once to allocate and deallocate static tables, and the instanceInit method on each allocated DSP. The memoryInfo method now has the following shape, with the two itbl0mydspSIG0 and ftbl1mydspSIG1 tables: static void memoryInfo() { fManager->begin(6); // mydspSIG0 fManager->info(4, 0, 0); // itbl0mydspSIG0 fManager->info(28, 1, 0); // mydspSIG1 fManager->info(4, 0, 0); // ftbl1mydspSIG1 fManager->info(28, 1, 0); // mydsp fManager->info(28, 0, 0); // iRec0 fManager->info(8, 3, 2); fManager->end(); }","title":"Static tables"},{"location":"manual/architectures/#defining-and-using-a-custom-memory-manager","text":"When compiled with the -mem option, the client code has to define an adapted memory_manager class for its specific needs. A cutom memory manager is implemented by subclassing the dsp_memory_manager abstract base class, and defining the begin , end , \u00ecnfo , allocate and destroy methods. Here is an example of a simple heap allocating manager (implemented in the dummy-mem.cpp architecture file): struct malloc_memory_manager : public dsp_memory_manager { virtual void begin(size_t count) { // TODO: use \u2018count\u2019 } virtual void end() { // TODO: start sorting the list of memory zones, to prepare // for the future allocations done in memoryCreate() } virtual void info(size_t size, size_t reads, size_t writes) { // TODO: use 'size', \u2018reads\u2019 and \u2018writes\u2019 // to prepare memory layout for allocation } virtual void* allocate(size_t size) { // TODO: refine the allocation scheme to take // in account what was collected in info return calloc(1, size); } virtual void destroy(void* ptr) { // TODO: refine the allocation scheme to take // in account what was collected in info free(ptr); } }; The specialized malloc_memory_manager class can now be used the following way: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // \u2018Placement new\u2019 and 'memoryCreate' are used inside the \u2018create\u2019 method dsp* DSP = mydsp::create(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // 'memoryDestroy' and memory manager 'destroy' are used to deallocate memory mydsp::destroy(); // Done once after the last DSP has been destroyed mydsp::classDestroy(); Note that the client code can still choose to allocate/deallocate the DSP instance using the regular C++ new/delete operators: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // Use regular C++ new dsp* DSP = new mydsp(); /// Allocate internal buffers DSP->memoryCreate(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP->memoryDestroy(); // Use regular C++ delete delete DSP; // Done once after the last DSP has been destroyed mydsp::classDestroy(); Or even on the stack with: ... // Allocation on the stack mydsp DSP; // Allocate internal buffers DSP.memoryCreate(); // Init the DSP instance DSP.instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP.memoryDestroy(); ... More complex custom memory allocators can be developed by refining this malloc_memory_manager example, possibly defining real-time memory allocators...etc... The OWL architecture file uses a custom OwlMemoryManager .","title":"Defining and using a custom memory manager"},{"location":"manual/architectures/#allocating-several-dsp-instances","text":"In a multiple instances scheme, static data structures shared by all instances have to be allocated once at beginning using mydsp::classInit , and deallocated at the end using mydsp::classDestroy . Individual instances are then allocated with mydsp::create() and deallocated with mydsp::destroy() , possibly directly using regular new/delete , or using stack allocation as explained before.","title":"Allocating several DSP instances"},{"location":"manual/architectures/#measuring-the-dsp-cpu","text":"The measure_dsp class defined in the faust/dsp/dsp-bench.h file allows to decorate a given DSP object and measure its compute method CPU consumption. Results are given in Megabytes/seconds (higher is better) and DSP CPU at 44,1 kHz. Here is a C++ code example of its use: static void bench(dsp* dsp, const string& name) { // Init the DSP dsp->init(48000); // Wraps it with a 'measure_dsp' decorator measure_dsp mes(dsp, 1024, 5); // Measure the CPU use mes.measure(); // Returns the Megabytes/seconds and relative standard deviation values std::pair<double, double> res = mes.getStats(); // Print the stats cout << name << \" MBytes/sec : \" << res.first << \" \" << \"(DSP CPU % : \" << (mes.getCPULoad() * 100) << \")\" << endl; } Defined in the faust/dsp/dsp-optimizer.h file, the dsp_optimizer class uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU. Here is a C++ code example of its use: static void dynamic_bench(const string& in_filename) { // Init the DSP optimizer with the in_filename to compile dsp_optimizer optimizer(in_filename, 0, nullptr, \"\", 1024); // Discover the best set of parameters tuple<double, double, double, TOption> res = optimizer.findOptimizedParameters(); cout << \"Best value for '\" << in_filename << \"' is : \" << get<0>(res) << \" MBytes/sec with \"; for (size_t i = 0; i < get<3>(res).size(); i++) { cout << get<3>(res)[i] << \" \"; } cout << endl; } This class can typically be used in tools that help developers discover the best Faust compilation parameters for a given DSP program, like the faustbench and faustbench-llvm tools.","title":"Measuring the DSP CPU"},{"location":"manual/architectures/#the-proxy-dsp-class","text":"In some cases, a DSP may run outside of the application or plugin context, like on another machine. The proxy_dsp class allows to create a proxy DSP that will be finally connected to the real one (using an OSC or HTTP based machinery for instance), and will reflect its behaviour. It uses the previously described JSONUIDecoder class. Then the proxy_dsp can be used in place of the real DSP, and connected with UI controllers using the standard buildUserInterface to control it. The faust-osc-controller tool demonstrates this capability using an OSC connection between the real DSP and its proxy. The proxy_osc_dsp class implements a specialized proxy_dsp using the liblo OSC library to connect to a OSC controllable DSP (which is using the OSCUI class and running in another context or machine). Then the faust-osc-controller program creates a real GUI (using GTKUI in this example) and have it control the remote DSP and reflect its dynamic state (like vumeter values coming back from the real DSP).","title":"The Proxy DSP Class"},{"location":"manual/architectures/#embedded-platforms","text":"Faust has been targeting an increasing number of embedded platforms for real-time audio signal processing applications in recent years. It can now be used to program microcontrollers (i.e., ESP32 , Teensy , Pico DSP and Daisy ), mobile platforms, embedded Linux systems (i.e., Bela and Elk ), Digital Signal Processors (DSPs), and more. Specialized architecture files and faust2xx scripts have been developed.","title":"Embedded Platforms"},{"location":"manual/architectures/#metadata-naming-convention","text":"A specific question arises when dealing with devices without or limited screen to display any GUI, and a set of physical knobs or buttons to be connected to control parameters. The standard way is then to use metadata in control labels. Since beeing able to use the same DSP file on all devices is always desirable, a common set of metadata has been defined: [switch:N] is used to connect to switch buttons [knob:N] is used to connect to knobs A extended set of metadata will probably have to be progressively defined and standardized.","title":"Metadata Naming Convention"},{"location":"manual/architectures/#using-the-uim-compiler-option","text":"On embedded platforms with limited capabilities, using the -uim option can be helpful. The C/C++ generated code then contains a static description of several caracteristics of the DSP, like the number of audio inputs/outputs , the number of controls inputs/outputs , and macros feed with the controls parameters (label, DSP field name, init, min, max, step) that can be implemented in the architecture file for various needs. For example the following DSP program: process = _*hslider(\"Gain\", 0, 0, 1, 0.01) : hbargraph(\"Vol\", 0, 1); compiled with faust -uim foo.dsp gives this additional section: #ifdef FAUST_UIMACROS #define FAUST_FILE_NAME \"foo.dsp\" #define FAUST_CLASS_NAME \"mydsp\" #define FAUST_INPUTS 1 #define FAUST_OUTPUTS 1 #define FAUST_ACTIVES 1 #define FAUST_PASSIVES 1 FAUST_ADDHORIZONTALSLIDER(\"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f); FAUST_ADDHORIZONTALBARGRAPH(\"Vol\", fHbargraph0, 0.0f, 1.0f); #define FAUST_LIST_ACTIVES(p) \\ p(HORIZONTALSLIDER, Gain, \"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f) \\ #define FAUST_LIST_PASSIVES(p) \\ p(HORIZONTALBARGRAPH, Vol, \"Vol\", fHbargraph0, 0.0, 0.0f, 1.0f, 0.0) \\ #endif The FAUST_ADDHORIZONTALSLIDER or FAUST_ADDHORIZONTALBARGRAPH macros can then be implemented to do whatever is needed with the Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f and \"Vol\", fHbargraph0, 0.0f, 1.0f parameters respectively. The more sophisticated FAUST_LIST_ACTIVES and FAUST_LIST_PASSIVES macros can possibly be used to call any p function (defined elsewhere in the architecture file) on each item. The minimal-static.cpp file demonstrates this feature.","title":"Using the -uim Compiler Option"},{"location":"manual/architectures/#developing-a-new-architecture-file","text":"Developing a new architecture file typically means writing a generic file, that will be populated with the actual output of the Faust compiler, in order to produce a complete file, ready-to-be-compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the <<includeIntrinsic>> and <<includeclass>> lines that will be recognized by the Faust compiler, and replaced by the generated code. Here is an example in C++, but the same logic can be used with other languages producing textual outputs, like C, Cmajor, Rust or Dlang. Look at the minimal.cpp example located in the architecture folder: #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #include \"faust/dsp/one-sample-dsp.h\" // To be replaced by the compiler generated C++ class <<includeIntrinsic>> <<includeclass>> int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", static_cast<dsp*>(&DSP)); // Render buffers... audio.start(); audio.stop(); } Calling faust -a minimal.cpp noise.dsp -o noise.cpp will produce a ready to compile noise.cpp file: /* ------------------------------------------------------------ name: \"noise\" Code generated with Faust 2.28.0 (https://faust.grame.fr) Compilation options: -lang cpp -scal -ftz 0 ------------------------------------------------------------ */ #ifndef __mydsp_H__ #define __mydsp_H__ #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #include <algorithm> #include <cmath> #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif #ifdef __APPLE__ #define exp10f __exp10f #define exp10 __exp10 #endif class mydsp : public dsp { private: FAUSTFLOAT fHslider0; int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"filename\", \"noise.dsp\"); m->declare(\"name\", \"noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fHslider0 = FAUSTFLOAT(0.5f); } virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"noise\"); ui_interface->addHorizontalSlider(\"Volume\", &fHslider0, 0.5, 0.0, 1.0, 0.001); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = (4.65661287e-10f * float(fHslider0)); for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((fSlow0 * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); } Generally, several files to connect to the audio layer, controller layer, and possibly other (MIDI, OSC...) have to be used. One of them is the main file and include the others. The -i option can be added to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with faust ) to produce a single self-contained unique file. Then a faust2xxx script has to be written to chain the Faust compilation step and the C++ compilation one (and possibly others). Look at the Developing a faust2xx Script section.","title":"Developing a New Architecture File"},{"location":"manual/architectures/#adapting-the-generated-dsp","text":"Developing the adapted C++ file may require aggregating the generated mydsp class (subclass of the dsp base class defined in faust/dsp/dsp.h header) in the specific class, so something like the following would have to be written: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the fDSP 'compute' fDSP.compute(count, inputs, outputs); } // Do something specific }; or subclassing and extending it , so writing something like: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' mydsp::compute(count, inputs, outputs); } // Do something specific }; or decorating a DSP object using the decorator pattern , which is already implemented in this file , and can possibly be sub-classed like: class my_decorator : public decorator_dsp { private: // Do something specific public: my_decorator(dsp* dsp):decorator_dsp(dsp) { // Do something specific } virtual ~my_class() { // Do something specific } // Implementation of some of the methods // Override the 'instanceClear' method void instanceClear() { // Do something specific // Call the inherited 'instanceClear' decorator_dsp::instanceClear(); } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' decorator_dsp::compute(count, inputs, outputs); } // Do something specific }; // Decorates a concrete instance my_decorator DSP = new my_decorator(new mydsp()); ...","title":"Adapting the Generated DSP"},{"location":"manual/architectures/#developing-new-ui-architectures","text":"For really new architectures, the UI base class, the GenericUI helper class or the GUI class (described before), have to be subclassed. Note that a lot of classes presented in the Some useful UI classes for developers section can also be subclassed or possibly enriched with additional code.","title":"Developing New UI Architectures"},{"location":"manual/architectures/#developing-new-audio-architectures","text":"The audio base class has to be subclassed and each method implemented for the given audio hardware. In some cases the audio driver can adapt to the required number of DSP inputs/outputs (like the JACK audio system for instance which can open any number of virtual audio ports). But in general, the number of hardware audio inputs/outputs may not exactly match the DSP ones. This is the responsability of the audio driver to adapt to this situation. The dsp_adapter dsp decorator can help in this case.","title":"Developing New Audio Architectures"},{"location":"manual/architectures/#developing-a-new-soundfile-loader","text":"Soundfiles are defined in the DSP program using the soundfile primitive . Here is a simple DSP program which uses a single tango.wav audio file and play it until its end: process = 0,_~+(1):soundfile(\"sound[url:{'tango.wav'}]\",2):!,!, The compiled C++ class has the following structure: class mydsp : public dsp { private: Soundfile* fSoundfile0; int iRec0[2]; int fSampleRate; .... with the Soundfile* fSoundfile0; field and its definition : struct Soundfile { void* fBuffers; // will correspond to a double** or float** pointer chosen at runtime int* fLength; // length of each part (so fLength[P] contains the length in frames of part P) int* fSR; // sample rate of each part (so fSR[P] contains the SR of part P) int* fOffset; // offset of each part in the global buffer (so fOffset[P] contains the offset in frames of part P) int fChannels; // max number of channels of all concatenated files int fParts; // the total number of loaded parts bool fIsDouble; // keep the sample format (float or double) }; The following buildUserInterface method in generated, containing a addSoundfile method called with the appropriate parameters extracted from the soundfile(\"sound[url:{'tango.wav'}]\",2) piece of DSP code, to be used to load the tango.wav audio file and prepare the fSoundfile0 field: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tp0\"); ui_interface->addSoundfile(\"sound\", \"{'tango.wav'}\", &fSoundfile0); ui_interface->closeBox(); } The specialized SoundUI architecture file is then used to load the required soundfiles at DSP init time, by using a SoundfileReader object. It only implements the addSoundfile method which will load all needed audio files, create and fill the fSoundfile0 object. Different concrete implementations are already written, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). A new audio file loader can be written by subclassing the SoundfileReader class. A pure memory reader could be implemented for instance to load wavetables to be used as the soundfile URL list. Look at the template MemoryReader class, as an example to be completed, with the following methods to be implemented: /** * Check the availability of a sound resource. * * @param path_name - the name of the file, or sound resource identified this way * * @return true if the sound resource is available, false otherwise. */ virtual bool checkFile(const std::string& path_name); /** * Get the channels and length values of the given sound resource. * * @param path_name - the name of the file, or sound resource identified this way * @param channels - the channels value to be filled with the sound resource * number of channels * @param length - the length value to be filled with the sound resource length in frames * */ virtual void getParamsFile(const std::string& path_name, int& channels, int& length); /** * Read one sound resource and fill the 'soundfile' structure accordingly * * @param path_name - the name of the file, or sound resource identified this way * @param part - the part number to be filled in the soundfile * @param offset - the offset value to be incremented with the actual * sound resource length in frames * @param max_chan - the maximum number of mono channels to fill * */ virtual void readFile(Soundfile* soundfile, const std::string& path_name, int part, int& offset, int max_chan); Another example to look at is WaveReader . The SoundUI architecture is then used the following way: mydsp DSP; // Here using a compiled time chosen SoundfileReader SoundUI* sound_interface = new SoundUI(); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; The SoundfileReader object can be dynamically choosen by using an alternate version of the SoundUI constructor, possibly choosing the sample format to be double when the DSP code is compiled with the -double option: mydsp DSP; // Here using a dynamically chosen custom MyMemoryReader SoundfileReader* sound_reader = new MyMemoryReader(...); SoundUI* sound_interface = new SoundUI(\"\", false, sound_reader, true); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface;","title":"Developing a New Soundfile Loader"},{"location":"manual/architectures/#other-languages-than-c","text":"Most of the architecture files have been developed in C++ over the years. Thus they are ready to be used with the C++ backend and the one that generate C++ wrapped modules (like the LLVM, Cmajor and Interpreter backends). For other languages, specific architecture files have to be written. Here is the current situation for other backends: the C backend needs additional CGlue.h and CInterface.h files, with the minimal-c file as a simple console mode example using them the Rust backend can be used with the minimal-rs architecture, the more complex JACK jack.rs used in faust2jackrust script, or the PortAudio portaudio.rs used in faust2portaudiorust script the experimental Dlang backend can be used with the minimal.d or the dplug.d to generate DPlug plugins with the faust2dplug script. the Julia backend can be used with the minimal.jl architecture or the portaudio.jl used in faust2portaudiojulia script.","title":"Other Languages Than C++"},{"location":"manual/architectures/#the-faust2xx-scripts","text":"","title":"The faust2xx Scripts"},{"location":"manual/architectures/#using-faust2xx-scripts","text":"The faust2xx scripts finally combine different architecture files to generate a ready-to-use application or plugin, etc... from a Faust DSP program. They typically combine the generated DSP with an UI architecture file and an audio architecture file. Most of the also have addition options like -midi , -nvoices <num> , -effect <auto|effect.dsp> or -soundfile to generate polyphonic instruments with or without effects, or audio file support. Look at the following page for a more complete description.","title":"Using faust2xx Scripts"},{"location":"manual/architectures/#developing-a-faust2xx-script","text":"The faust2xx script are mostly written in bash (but any scripting language can be used) and aims to produce a ready-to-use application, plugin, etc... from a DSP program. A faust2minimal template script using the C++ backend, can be used to start the process. The helper scripts, faustpath , faustoptflags , and usage.sh can be used to setup common variables: # Define some common paths . faustpath # Define compilation flags . faustoptflags # Helper file to build the 'help' option . usage.sh CXXFLAGS+=\" $MYGCCFLAGS\" # So that additional CXXFLAGS can be used # The architecture file name ARCHFILE=$FAUSTARCH/minimal.cpp # Global variables OPTIONS=\"\" FILES=\"\" The script arguments then have to be analysed, compiler options are kept in the OPTIONS variable and all DSP files in the FILES one: #------------------------------------------------------------------- # dispatch command arguments #------------------------------------------------------------------- while [ $1 ] do p=$1 if [ $p = \"-help\" ] || [ $p = \"-h\" ]; then usage faust2minimal \"[options] [Faust options] <file.dsp>\" exit fi echo \"dispatch command arguments\" if [ ${p:0:1} = \"-\" ]; then OPTIONS=\"$OPTIONS $p\" elif [[ -f \"$p\" ]] && [ ${p: -4} == \".dsp\" ]; then FILES=\"$FILES $p\" else OPTIONS=\"$OPTIONS $p\" fi shift done Each DSP file is first compiled to C++ using the faust -a command and the appropriate architecture file, then to the final executable program, here using the C++ compiler: #------------------------------------------------------------------- # compile the *.dsp files #------------------------------------------------------------------- for f in $FILES; do # compile the DSP to c++ using the architecture file echo \"compile the DSP to c++ using the architecture file\" faust -i -a $ARCHFILE $OPTIONS \"$f\" -o \"${f%.dsp}.cpp\"|| exit # compile c++ to binary echo \"compile c++ to binary\" ( $CXX $CXXFLAGS \"${f%.dsp}.cpp\" -o \"${f%.dsp}\" ) > /dev/null || exit # remove tempory files rm -f \"${f%.dsp}.cpp\" # collect binary file name for FaustWorks BINARIES=\"$BINARIES${f%.dsp};\" done echo $BINARIES The existing faust2xx scripts can be used as examples.","title":"Developing a faust2xx Script"},{"location":"manual/architectures/#the-faust2api-model","text":"This model combining the generated DSP the audio and UI architecture components is very convenient to automatically produce ready-to-use standalone application or plugins, since the controller part (GUI, MIDI or OSC...) is directly compiled and deployed. In some cases, developers prefer to control the DSP by creating a completely new GUI (using a toolkit not supported in the standard architecture files), or even without any GUI and using another control layer. A model that only combines the generated DSP with an audio architecture file to produce an audio engine has been developed (thus gluing the blue and red parts of the three color model explained at the beginning). A generic template class DspFaust has been written in the DspFaust.h and DspFaust.cpp files. This code contains conditional compilation sections to add and initialize the appropriate audio driver (written as a subclass of the previously described base audio class), and can produce audio generators , effects , of fully MIDI and sensor controllable pophyphonic instruments . The resulting audio engine contains start and stop methods to control audio processing. It also provides a set of functions like getParamsCount, setParamValue, getParamValue etc. to access all parameters (or the additional setVoiceParamValue method function to access a single voice in a polyphonic case), and let the developer adds his own GUI or any kind of controller. Look at the faust2api script, which uses the previously described architecture files, and provide a tool to easily generate custom APIs based on one or several Faust objects.","title":"The faust2api Model"},{"location":"manual/architectures/#using-the-inj-option-with-faust2xx-scripts","text":"The compiler -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. Two examples of use are presented next.","title":"Using the -inj Option With faust2xx Scripts"},{"location":"manual/architectures/#using-the-template-llvmcpp-architecture","text":"The first one demonstrates how faust2xx scripts can become more dynamic by loading and compiling an arbitrary DSP at runtime. This is done using the template-llvm.cpp architecture file which uses the libfaust library and the LLVM backend to dynamically compile a foo.dsp file. So instead of producing a static binary based on a given DSP, the resulting program will be able to load and compile a DSP at runtime. This template-llvm.cpp can be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application, ready to be used to load and compile a DSP, and run it with the CoreAudio audio layer and GTK as the GUI freamework. Then faust2cagtk-llvm will ask for a DSP to compile: ./faust2cagtk-llvm <Enter a foo.dsp file> A generic polyphonic (8 voices) and MIDI controllable version can be compiled using: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp (a dummy DSP) Note that the resulting binary keeps its own control options, like: ./faust2cagtk-llvm -h ./faust2cagtk-llvm [--frequency <val>] [--buffer <val>] [--nvoices <val>] [--control <0/1>] [--group <0/1>] [--virtual-midi <0/1>] So now ./faust2cagtk-llvm --nvoices 16 starts the program with 16 voices. The technique has currently be tested with the faust2cagtk , faust2jack , faust2csvplot , and faust2plot tools.","title":"Using the template-llvm.cpp architecture"},{"location":"manual/architectures/#second-use-case-computing-the-spectrogram-of-a-set-of-audio-files","text":"Here is a second use case where some external C++ code is used to compute the spectrogram of a set of audio files (which is something that cannot be simply done with the current version fo the Faust language) and output the spectrogram as an audio signal. A nentry controller will be used to select the currently playing spectrogram. The Faust compiler will be used to generate a C++ class which is going to be manually edited and enriched with additional code.","title":"Second use-case computing the spectrogram of a set of audio files"},{"location":"manual/architectures/#writting-the-dsp-code","text":"First a fake DSP program spectral.dsp using the soundfile primitive loading two audio files and a nentry control is written: sf = soundfile(\"sound[url:{'sound1.wav';'sound2.wav'}]\",2); process = (hslider(\"Spectro\", 0, 0, 1, 1),0) : sf : !,!,_,_; The point of explicitly using soundfile primitive and a nentry control is to generate a C++ file with a prefilled DSP structure (containing the fSoundfile0 and fHslider0 fields) and code inside the buildUserInterface method. Compiling it manually with the following command: faust spectral.dsp -cn spectral -o spectral.cpp produces the following C++ code containing the spectral class: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectrogram\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); .... } };","title":"Writting the DSP code"},{"location":"manual/architectures/#customizing-the-c-code","text":"Now the spectral class can be manually edited and completed with additional code, to compute the two audio files spectrograms in buildUserInterface , and play them in compute . a new line Spectrogram fSpectro[2]; is added in the DSP structure a createSpectrogram(fSoundfile0, fSpectro); function is added in buildUserInterface and used to compute and fill the two spectrograms, by reading the two loaded audio files in fSoundfile0 part of the generated code in compute is removed and replaced by new code to play one of spectrograms (selected with the fHslider0 control in the GUI) using a playSpectrogram(fSpectro, count, iSlow0, outputs); function: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; Spectrogram fSpectro[2]; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectro\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); // Read 'fSoundfile0' and fill 'fSpectro' createSpectrogram(fSoundfile0, fSpectro); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); // Play 'fSpectro' indexed by 'iSlow0' by writting 'count' samples in 'outputs' playSpectrogram(fSpectro, count, iSlow0, outputs); } }; Here we assume that createSpectrogram and playSpectrogram functions are defined elsewhere and ready to be compiled.","title":"Customizing the C++ code"},{"location":"manual/architectures/#deploying-it-as-a-maxmsp-external-using-the-faust2max6-script","text":"The completed spectral.cpp file is now ready to be deployed as a Max/MSP external using the faust2max6 script and the -inj option with the following line: faust2max6 -inj spectral.cpp -soundfile spectral.dsp The two needed sound1.wav and sound2.wav audio files are embedded in the generated external, loaded at init time (since the buildUserInterface method is automatically called), and the manually added C++ code will be executed to compute the spectrograms and play them. Finally by respecting the naming coherency for the fake spectral.dsp DSP program, the generated spectral.cpp C++ file, the automatically generated spectral.maxpat Max/MSP patch will be able to build the GUI with a ready-to-use slider.","title":"Deploying it as a Max/MSP External Using the faust2max6 Script"},{"location":"manual/architectures/#additional-ressources","text":"Several external projects are providing tools to arrange the way Faust source code is generated or used, in different languages.","title":"Additional Ressources"},{"location":"manual/architectures/#preprocessing-tools","text":"","title":"Preprocessing tools"},{"location":"manual/architectures/#fpp","text":"fpp is a standalone Perl script with no dependencies which allows ANY C/C++ code in a Faust .dsp file as long as you are targeting C/C++ in scalar mode.","title":"fpp"},{"location":"manual/architectures/#c-tools","text":"Using and adapting the dsp/UI/audio model in a more sophisticated way, or integrating Faust generated C++ classes in others frameworks (like JUCE).","title":"C++ tools"},{"location":"manual/architectures/#faust2hpp","text":"Convert Faust code to a header-only standalone C++ library. A collection of header files is generated as the output. A class is provided from which a DSP object can be built with methods in the style of JUCE DSP objects.","title":"faust2hpp"},{"location":"manual/architectures/#faustpp","text":"A post-processor for Faust, which allows to generate with more flexibility. This is a source transformation tool based on the Faust compiler. It permits to arrange the way how Faust source is generated with greater flexibility.","title":"faustpp"},{"location":"manual/architectures/#cookiecutter-dpf-faust","text":"A cookiecutter project template for DISTRHO plugin framework audio effect plugins using Faust for the implementation of the DSP pipeline.","title":"cookiecutter-dpf-faust"},{"location":"manual/architectures/#faustmd","text":"Static metadata generator for Faust/C++. This program builds the metadata for a Faust DSP ahead of time, rather than dynamically. The result is a block of C++ code which can be appended to the code generation.","title":"faustmd"},{"location":"manual/architectures/#faustcppconverter","text":"Eyal Amir tool to facilitate the use of Faust generated C++ code in JUCE projects.","title":"FaustCPPConverter"},{"location":"manual/architectures/#josmodules-and-josm_faust","text":"Julius Smith projects to facilitate the use of Faust generated C++ code in JUCE projects.","title":"JOSModules and josm_faust"},{"location":"manual/architectures/#arduino-tools","text":"An alternative way to use the ESP32 board with Faust, possibly easier and more versatile than the examples mentioned on the esp32 tutorial .","title":"Arduino tools"},{"location":"manual/architectures/#cmajor-tools","text":"","title":"Cmajor tools"},{"location":"manual/architectures/#using-faust-in-cmajor","text":"A tutorial to show how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation.","title":"Using Faust in Cmajor"},{"location":"manual/architectures/#rnbo-tools","text":"","title":"RNBO tools"},{"location":"manual/architectures/#using-faust-in-rnbo-with-codebox","text":"A tutorial to show how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi.","title":"Using Faust in RNBO with codebox~"},{"location":"manual/architectures/#dlang-tools","text":"","title":"DLang tools"},{"location":"manual/architectures/#faust-2-dplug-guide","text":"Explains how to use Faust in a Dplug project.","title":"Faust 2 Dplug Guide"},{"location":"manual/architectures/#dplug-faust-example","text":"This is an example plugin using Dplug with a Faust backend. It is a stereo reverb plugin using the Freeverb demo from the Faust library.","title":"Dplug Faust Example"},{"location":"manual/architectures/#julia-tools","text":"","title":"Julia tools"},{"location":"manual/architectures/#faustjl","text":"Julia wrapper for the Faust compiler. Uses the Faust LLVM C API.","title":"Faust.jl"},{"location":"manual/architectures/#using-faust-in-julia","text":"A tutorial to show how Faust can be used with Julia , a high-level, general-purpose dynamic programming language with features well suited for numerical analysis and computational science.","title":"Using Faust in Julia"},{"location":"manual/architectures/#python-tools","text":"","title":"Python tools"},{"location":"manual/architectures/#faustpy","text":"FAUSTPy is a Python wrapper for the FAUST DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork .","title":"FAUSTPy"},{"location":"manual/architectures/#faust-ctypes","text":"A port of Marc Joliet's FaustPy from CFFI to Ctypes. Faust-Ctypes documentation is available online .","title":"Faust Ctypes"},{"location":"manual/architectures/#an-scons-tool-for-faust","text":"This is an SCons tool for compiling FAUST programs. It adds various builders to your construction environment: Faust, FaustXML, FaustSVG, FaustSC, and FaustHaskell. Their behaviour can be modified by changing various construction variables (see \"Usage\" below).","title":"An SCons Tool for FAUST"},{"location":"manual/architectures/#faustwatch","text":"At the moment there is one tool present, faustwatch.py. Faustwatch is a tool that observes a .dsp file used by the dsp language Faust.","title":"Faustwatch"},{"location":"manual/architectures/#faustwidgets","text":"Creates interactive widgets inside jupyter notebooks from Faust dsp files and produces a (customizable) plot.","title":"faustWidgets"},{"location":"manual/architectures/#faust-synth","text":"This is an example project for controlling a synth, programmed and compiled with Faust, through a Python script. The synth runs as a JACK client on Linux systems and the output is automatically recorded by jack_capture.","title":"Faust Synth"},{"location":"manual/architectures/#dawdreamer","text":"DawDreamer is an audio-processing Python framework supporting Faust and Faust's Box API.","title":"DawDreamer"},{"location":"manual/architectures/#ode2dsp","text":"ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Finite difference equations (FDEs) are rendered to Faust code.","title":"ode2dsp"},{"location":"manual/architectures/#faustlab","text":"A exploratory project to wrap the Faust interpreter for use by python via the following wrapping frameworks using the RtAudio cross-platform audio driver: cyfaust: cython (faust c++ interface) cfaustt: cython (faust c interface) pyfaust: pybind11 (faust c++ interface) nanobind: nanobind (faust c++ interface)","title":"faustlab"},{"location":"manual/architectures/#cyfaust","text":"A cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension.","title":"cyfaust"},{"location":"manual/architectures/#rust-tools","text":"","title":"Rust tools"},{"location":"manual/architectures/#rust-faust","text":"A better integration of Faust for Rust. It allows to build the DSPs via build.rs and has some abstractions to make it much easier to work with params and meta of the DSPs.","title":"rust-faust"},{"location":"manual/architectures/#faust-egui","text":"Proof of concept of drawing a UI with egui and rust-faust .","title":"Faust egui"},{"location":"manual/architectures/#rustfaustexperiments","text":"Tools to compare C++ and Rust code generated from Faust.","title":"RustFaustExperiments"},{"location":"manual/architectures/#fl-tui","text":"Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API.","title":"fl-tui"},{"location":"manual/architectures/#faustlive-jack-rs","text":"Another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API.","title":"faustlive-jack-rs"},{"location":"manual/architectures/#lowpass-lr4-faust-nih-plug","text":"A work-in-progress project to integrate Faust generated Rust code with NIH-plug .","title":"lowpass-lr4-faust-nih-plug"},{"location":"manual/architectures/#nih-faust-jit","text":"A plugin to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"nih-faust-jit"},{"location":"manual/architectures/#webassembly-tools","text":"","title":"WebAssembly tools"},{"location":"manual/architectures/#faust-loader","text":"Import Faust .dsp files, and get back an AudioWorklet or ScriptProcessor node.","title":"faust-loader"},{"location":"manual/architectures/#faust2cpp2wasm","text":"A drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend.","title":"faust2cpp2wasm"},{"location":"manual/architectures/#faust-compiler-microservice","text":"This is a microservice that serves a single purpose: compiling Faust code that is sent to it into WebAssembly that can then be loaded and run natively from within the web synth application. It is written in go because go is supposed to be good for this sort of thing.","title":"Faust Compiler Microservice"},{"location":"manual/architectures/#mosfez-faust","text":"Makes dynamic compilation of Faust on the web a little easier, and has a dev project to run values through dsp offline, and preview dsp live. It's an opinionated version of some parts of Faust for webaudio , mostly just the Web Assembly Faust compiler, wrapped up in a library with additional features.","title":"mosfez-faust"},{"location":"manual/architectures/#faust-wap2-playground","text":"Playground and template for Faust-based web audio experiments.","title":"faust-wap2-playground"},{"location":"manual/architectures/#dart-tools","text":"","title":"Dart tools"},{"location":"manual/architectures/#flutter_faust_ffi","text":"A basic flutter app as a proof of concept utilizing Faust's C API export with Dart's ffi methods to create cross-platform plug-ins.","title":"flutter_faust_ffi"},{"location":"manual/community/","text":"Material from the community Here is a list of additional material contributed by the community of Faust developers or users. Articles, Video and Blog Posts Generate WAMs with FaustIDE Web Audio Modules (WAM) ias a standard for Web Audio plugins and DAWs. The 2.0 version of Web Audio Modules has been released in 2021 as a group effort by a large set of people and since then, multiple plugins and hosts have been published, mostly as open source and free software. The FAUST IDE is a very popular tool for generating WAMs from existing FAUST code (and there are hundreds of source code example available for audio effects, instruments, etc.). You can generate WAMs directly from the command line using the faust2wam script . Mozzi Revisited Mozzi brings your Arduino to life by allowing it to produce much more complex and interesting growls, sweeps and chorusing atmospherics. These sounds can be quickly and easily constructed from familiar synthesis units like oscillators, delays, filters and envelopes and can be programmed with Faust . How to compile HISE and FAUST for Audio Plugin Development This video shows how you can use Faust inside HISE . More info on how to use Faust in HISE can be found on the HISE Faust forum . How to build Mod Duo plugin written in Faust This article shows how you can compile a Faust program to run on Mod Duo . Handling infinity and not-a-number (NaN) values in Faust and C++ audio programming This post by Dario Sanfilippo discusses insights gained over a few years of audio programming to implement robust Faust/C++ software, particularly when dealing with infinity and NaN values. Three ways to implement recursive circuits in the Faust language This post by Dario Sanfilippo is about the implementation of not-so-simple recursive circuits in the Faust language. Make LV2 plugins with Faust This post by Nicola Landro is about making LV2 plugins with Faust. Getting started with Faust for SuperCollider This post by Mads Kjeldgaard is about using Faust with SuperCollider . Get Started Audio Programming with the FAUST Language This post by Matt K is about starting audio Programming with Faust. Using Faust on the OWL family of devices This tutorial focus on using Faust and on features that are specific to OWL and the OpenWare firmware. I ported native guitar plugins to JavaScript (in-depth) This post by Konstantine Kutalia is porting Faust coded Kapitonov Plugins Pack in JavaScript. Using Faust with the Arduino Audio Tools Library A blog about using Faust with Arduino Audio Tools. Writing a Slew Limiter in the Faust Language A video about writing a Slew Limiter in the Faust Language by Julius Smith. Make an Eight Channel Mixer in the Faust IDE A video about making an Eight Channel Mixer in the Faust IDE by Julius Smith. Creating VSTs and more using FAUST FAUST is a programming language that enables us to quickly create cross-platform DSP code. We can easily create VST plugins, Max-Externals and more. Its high-quality built-in library of effects and tools enables us to quickly draft high quality audio processing devices. The workshop aims at getting new users started, conveying what FAUST is good for and how to use it effectively to produce high quality results quickly. Various Tools Syntax Highlighting tree-sitter-faust Tree-sitter grammar Faust. Every Faust syntax feature should be supported. The npm package is here . Syntax Highlighting Files This folder contains syntax highlighting files for various editors. Sublime Text syntax Sublime Text syntax file for the Faust programming language. Faust-Mode Major Emacs mode for the Faust programming language, featuring syntax highlighting, automatic indentation and auto-completion. Faustine Faustine allows the edition of Faust code using emacs. faust neovim plugin Plugin to edit Faust code in the hyperextensible Vim-based text editor neowim . Code Generators faust2pdex Generator of Faust wrappers for Pure Data. This software wraps the C++ code generated by Faust into a native external for Pure Data. You obtain a piece of source code that you can use with pd-lib-builder to produce a native binary with the help of make. No knowledge of C++ programming is required. Faust.quark This SuperCollider package makes it possible to create SuperCollider packages (Quarks) containing plugins written in Faust code. With this, you can distribute plugins written in Faust and make it easy for others to install, compile or uninstall them. It also contains some simple interfaces for the faust and faust2sc.py commands used behind the scenes. ode2dsp ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Features: Support linear and nonlinear systems of ODEs Support trapezoidal and backward Euler discrete-time integral approximations Approximate solutions of implicit equations using Newton's method Render finite difference equations (FDEs) to Faust code Calculate stability of ODEs and FDEs at an operating point Contributing Feel free to contribute by forking this project and creating a pull request , or by mailing the library description here .","title":"Community"},{"location":"manual/community/#material-from-the-community","text":"Here is a list of additional material contributed by the community of Faust developers or users.","title":"Material from the community"},{"location":"manual/community/#articles-video-and-blog-posts","text":"","title":"Articles, Video and Blog Posts"},{"location":"manual/community/#generate-wams-with-faustide","text":"Web Audio Modules (WAM) ias a standard for Web Audio plugins and DAWs. The 2.0 version of Web Audio Modules has been released in 2021 as a group effort by a large set of people and since then, multiple plugins and hosts have been published, mostly as open source and free software. The FAUST IDE is a very popular tool for generating WAMs from existing FAUST code (and there are hundreds of source code example available for audio effects, instruments, etc.). You can generate WAMs directly from the command line using the faust2wam script .","title":"Generate WAMs with FaustIDE"},{"location":"manual/community/#mozzi-revisited","text":"Mozzi brings your Arduino to life by allowing it to produce much more complex and interesting growls, sweeps and chorusing atmospherics. These sounds can be quickly and easily constructed from familiar synthesis units like oscillators, delays, filters and envelopes and can be programmed with Faust .","title":"Mozzi Revisited"},{"location":"manual/community/#how-to-compile-hise-and-faust-for-audio-plugin-development","text":"This video shows how you can use Faust inside HISE . More info on how to use Faust in HISE can be found on the HISE Faust forum .","title":"How to compile HISE and FAUST for Audio Plugin Development"},{"location":"manual/community/#how-to-build-mod-duo-plugin-written-in-faust","text":"This article shows how you can compile a Faust program to run on Mod Duo .","title":"How to build Mod Duo plugin written in Faust"},{"location":"manual/community/#handling-infinity-and-not-a-number-nan-values-in-faust-and-c-audio-programming","text":"This post by Dario Sanfilippo discusses insights gained over a few years of audio programming to implement robust Faust/C++ software, particularly when dealing with infinity and NaN values.","title":"Handling infinity and not-a-number (NaN) values in Faust and C++ audio programming"},{"location":"manual/community/#three-ways-to-implement-recursive-circuits-in-the-faust-language","text":"This post by Dario Sanfilippo is about the implementation of not-so-simple recursive circuits in the Faust language.","title":"Three ways to implement recursive circuits in the Faust language"},{"location":"manual/community/#make-lv2-plugins-with-faust","text":"This post by Nicola Landro is about making LV2 plugins with Faust.","title":"Make LV2 plugins with Faust"},{"location":"manual/community/#getting-started-with-faust-for-supercollider","text":"This post by Mads Kjeldgaard is about using Faust with SuperCollider .","title":"Getting started with Faust for SuperCollider"},{"location":"manual/community/#get-started-audio-programming-with-the-faust-language","text":"This post by Matt K is about starting audio Programming with Faust.","title":"Get Started Audio Programming with the FAUST Language"},{"location":"manual/community/#using-faust-on-the-owl-family-of-devices","text":"This tutorial focus on using Faust and on features that are specific to OWL and the OpenWare firmware.","title":"Using Faust on the OWL family of devices"},{"location":"manual/community/#i-ported-native-guitar-plugins-to-javascript-in-depth","text":"This post by Konstantine Kutalia is porting Faust coded Kapitonov Plugins Pack in JavaScript.","title":"I ported native guitar plugins to JavaScript (in-depth)"},{"location":"manual/community/#using-faust-with-the-arduino-audio-tools-library","text":"A blog about using Faust with Arduino Audio Tools.","title":"Using Faust with the Arduino Audio Tools Library"},{"location":"manual/community/#writing-a-slew-limiter-in-the-faust-language","text":"A video about writing a Slew Limiter in the Faust Language by Julius Smith.","title":"Writing a Slew Limiter in the Faust Language"},{"location":"manual/community/#make-an-eight-channel-mixer-in-the-faust-ide","text":"A video about making an Eight Channel Mixer in the Faust IDE by Julius Smith.","title":"Make an Eight Channel Mixer in the Faust IDE"},{"location":"manual/community/#creating-vsts-and-more-using-faust","text":"FAUST is a programming language that enables us to quickly create cross-platform DSP code. We can easily create VST plugins, Max-Externals and more. Its high-quality built-in library of effects and tools enables us to quickly draft high quality audio processing devices. The workshop aims at getting new users started, conveying what FAUST is good for and how to use it effectively to produce high quality results quickly.","title":"Creating VSTs and more using FAUST"},{"location":"manual/community/#various-tools","text":"","title":"Various Tools"},{"location":"manual/community/#syntax-highlighting","text":"","title":"Syntax Highlighting"},{"location":"manual/community/#tree-sitter-faust","text":"Tree-sitter grammar Faust. Every Faust syntax feature should be supported. The npm package is here .","title":"tree-sitter-faust"},{"location":"manual/community/#syntax-highlighting-files","text":"This folder contains syntax highlighting files for various editors.","title":"Syntax Highlighting Files"},{"location":"manual/community/#sublime-text-syntax","text":"Sublime Text syntax file for the Faust programming language.","title":"Sublime Text syntax"},{"location":"manual/community/#faust-mode","text":"Major Emacs mode for the Faust programming language, featuring syntax highlighting, automatic indentation and auto-completion.","title":"Faust-Mode"},{"location":"manual/community/#faustine","text":"Faustine allows the edition of Faust code using emacs.","title":"Faustine"},{"location":"manual/community/#faust-neovim-plugin","text":"Plugin to edit Faust code in the hyperextensible Vim-based text editor neowim .","title":"faust neovim plugin"},{"location":"manual/community/#code-generators","text":"","title":"Code Generators"},{"location":"manual/community/#faust2pdex","text":"Generator of Faust wrappers for Pure Data. This software wraps the C++ code generated by Faust into a native external for Pure Data. You obtain a piece of source code that you can use with pd-lib-builder to produce a native binary with the help of make. No knowledge of C++ programming is required.","title":"faust2pdex"},{"location":"manual/community/#faustquark","text":"This SuperCollider package makes it possible to create SuperCollider packages (Quarks) containing plugins written in Faust code. With this, you can distribute plugins written in Faust and make it easy for others to install, compile or uninstall them. It also contains some simple interfaces for the faust and faust2sc.py commands used behind the scenes.","title":"Faust.quark"},{"location":"manual/community/#ode2dsp","text":"ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Features: Support linear and nonlinear systems of ODEs Support trapezoidal and backward Euler discrete-time integral approximations Approximate solutions of implicit equations using Newton's method Render finite difference equations (FDEs) to Faust code Calculate stability of ODEs and FDEs at an operating point","title":"ode2dsp"},{"location":"manual/community/#contributing","text":"Feel free to contribute by forking this project and creating a pull request , or by mailing the library description here .","title":"Contributing"},{"location":"manual/compiler/","text":"Using the Faust Compiler While the Faust compiler is available in different forms (e.g., Embedded Compiler , etc.), its most \"common\" one is the command line version, which can be invoked using the faust command. It translates a Faust program into code in a wide range of languages (C, C++, Rust, LLVM IR, WebAssembly, etc.). The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. A typical call of the Faust command line compiler is: faust [OPTIONS] faustFile.dsp The Faust compiler outputs C++ code by default therefore running: faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to reroute the standard output to a file: faust noise.dsp -o noise.cpp The -a option allows us to wrap the generated code into an architecture file: faust -a alsa-gtk.cpp noise.dsp which can either be placed in the same folder as the current Faust file ( noise.dsp here) or be one of the standard Faust architectures. To compile a Faust program into an ALSA application on Linux, the following commands can be used: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Note that a wide range of faust2... compilation scripts can be used to facilitate this operation by taking a Faust file and returning the corresponding binary for your platform. Structure of the Generated Code A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0; // This method can be called to retrieve the UI description of // the Faust program and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double /*date_usec*/, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Methods are filled by the compiler with the actual code. In the case of noise.dsp : class mydsp : public dsp { private: int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"author\", \"GRAME\"); m->declare(\"filename\", \"noise\"); m->declare(\"name\", \"Noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) {} virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() {} virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((4.65661287e-10f * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; Several fine-grained initialization methods are available: the instanceInit method calls several additional initialization methods. the instanceConstants method sets the instance constant state. the instanceClear method resets the instance dynamic state (delay lines...). the instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The init method combines class static state and instance initialization. When using a single instance, calling init is the simplest way to do \"what is needed.\" When using several instances, all of them can be initialized using instanceInit , with a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. Controlling Code Generation Several options of the Faust compiler allow to control the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code. Vector Code Generation Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 or 8 simple precision floating point numbers, leading to a theoretical speedup of 4 or 8. Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular, complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size <n> controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: The corresponding compute() method generated in scalar mode is the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { int iTemp0 = int((1048576.0f * mydsp_faustpower2_f(float(input0[i])))); iVec0[(IOTA & 1023)] = iTemp0; iRec0[0] = ((iRec0[1] + iTemp0) - iVec0[((IOTA - 1000) & 1023)]); output0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[0])))); IOTA = (IOTA + 1); iRec0[1] = iRec0[0]; } } The -vec option leads to the following reorganization of the code: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; FAUSTFLOAT* fInput0 = 0; fOutput0_ptr = outputs[0]; FAUSTFLOAT* fOutput0 = 0; int iRec0_tmp[36]; int* iRec0 = &iRec0_tmp[4]; int fullcount = count; int index = 0; /* Main loop */ for (index = 0; (index <= (fullcount - 32)); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = 32; /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } /* Remaining frames */ if (index < fullcount) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = (fullcount - index); /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f * mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. With the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2 , the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! The vector code generation is built on top of the scalar code generation (see previous figure). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see figure below). This graph is stored in the class object and a topological sort is applied to it before printing the code. Parallel Code Generation Parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option . It implies that the -vec option as well as the parallel code generation are built on top of the vector code generation. The OpenMP Code Generator The --openMP (or -omp ) option , when given to the Faust compiler, will insert appropriate OpenMP directives into the C++ code. OpenMP is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure above). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region, a group of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel group until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by every thread of the parallel // team ... } In order not to have every thread doing redundantly the exact same work, OpenMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... } Adding Open MP Directives As said before, parallel code generation is built on top of vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code } Example of Parallel OpenMP Code To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder: The corresponding compute() method obtained using the -omp option looks like this: virtual void compute(int fullcount, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { float fRec0_tmp[36]; float fRec1_tmp[36]; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; #pragma omp parallel\\ firstprivate(fInput0, fInput1, fOutput0, fRec0, fRec1) { for (int index = 0; (index < fullcount); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fInput1 = &fInput1_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = min(32, (fullcount - index)); #pragma omp sections { #pragma omp section { /* Recursive loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } } #pragma omp section { /* Recursive loop 1 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } } } #pragma omp single { /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } } } } } This code requires some comments: the parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1 . The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. the top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between threads. please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. the work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). the work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. the loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. finally #pragma omp single indicates that this section will be executed by only one thread (any of them). The Scheduler Code Generator With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separate computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large sub-tree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers, and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future. Example of Parallel Scheduler Code To illustrate how Faust generates the scheduler code, let's reuse the previous example made of two 1-pole filters in parallel connected to an adder: When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; fCount = count; fIndex = 0; /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in each thread WSQ */ initTaskList(fScheduler, -1); signalAll(fScheduler); computeThread(0); syncAll(fScheduler); } void computeThread(int num_thread) { int count = fCount; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; int tasknum = 0; while ((fIndex < fCount)) { fInput0 = &fInput0_ptr[fIndex]; fInput1 = &fInput1_ptr[fIndex]; fOutput0 = &fOutput0_ptr[fIndex]; count = min(32, (fCount - fIndex)); switch (tasknum) { case 0: { /* Work Stealing task */ tasknum = getNextTask(fScheduler, num_thread); break; } case 1: { /* Last task */ fIndex = (fIndex + 32); if (fIndex < fCount) { /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in 'num_thread' WSQ */ initTaskList(fScheduler, num_thread); } tasknum = 0; break; } case 2: { /* Recursive loop 2 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 3: { /* Recursive loop 3 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 4: { /* Vectorizable loop 4 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } tasknum = 1; break; } } } }","title":"Using the Compiler"},{"location":"manual/compiler/#using-the-faust-compiler","text":"While the Faust compiler is available in different forms (e.g., Embedded Compiler , etc.), its most \"common\" one is the command line version, which can be invoked using the faust command. It translates a Faust program into code in a wide range of languages (C, C++, Rust, LLVM IR, WebAssembly, etc.). The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. A typical call of the Faust command line compiler is: faust [OPTIONS] faustFile.dsp The Faust compiler outputs C++ code by default therefore running: faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to reroute the standard output to a file: faust noise.dsp -o noise.cpp The -a option allows us to wrap the generated code into an architecture file: faust -a alsa-gtk.cpp noise.dsp which can either be placed in the same folder as the current Faust file ( noise.dsp here) or be one of the standard Faust architectures. To compile a Faust program into an ALSA application on Linux, the following commands can be used: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Note that a wide range of faust2... compilation scripts can be used to facilitate this operation by taking a Faust file and returning the corresponding binary for your platform.","title":"Using the Faust Compiler"},{"location":"manual/compiler/#structure-of-the-generated-code","text":"A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0; // This method can be called to retrieve the UI description of // the Faust program and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double /*date_usec*/, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Methods are filled by the compiler with the actual code. In the case of noise.dsp : class mydsp : public dsp { private: int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"author\", \"GRAME\"); m->declare(\"filename\", \"noise\"); m->declare(\"name\", \"Noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) {} virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() {} virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((4.65661287e-10f * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; Several fine-grained initialization methods are available: the instanceInit method calls several additional initialization methods. the instanceConstants method sets the instance constant state. the instanceClear method resets the instance dynamic state (delay lines...). the instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The init method combines class static state and instance initialization. When using a single instance, calling init is the simplest way to do \"what is needed.\" When using several instances, all of them can be initialized using instanceInit , with a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type.","title":"Structure of the Generated Code"},{"location":"manual/compiler/#controlling-code-generation","text":"Several options of the Faust compiler allow to control the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code.","title":"Controlling Code Generation"},{"location":"manual/compiler/#vector-code-generation","text":"Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 or 8 simple precision floating point numbers, leading to a theoretical speedup of 4 or 8. Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular, complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size <n> controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: The corresponding compute() method generated in scalar mode is the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { int iTemp0 = int((1048576.0f * mydsp_faustpower2_f(float(input0[i])))); iVec0[(IOTA & 1023)] = iTemp0; iRec0[0] = ((iRec0[1] + iTemp0) - iVec0[((IOTA - 1000) & 1023)]); output0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[0])))); IOTA = (IOTA + 1); iRec0[1] = iRec0[0]; } } The -vec option leads to the following reorganization of the code: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; FAUSTFLOAT* fInput0 = 0; fOutput0_ptr = outputs[0]; FAUSTFLOAT* fOutput0 = 0; int iRec0_tmp[36]; int* iRec0 = &iRec0_tmp[4]; int fullcount = count; int index = 0; /* Main loop */ for (index = 0; (index <= (fullcount - 32)); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = 32; /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } /* Remaining frames */ if (index < fullcount) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = (fullcount - index); /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f * mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. With the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2 , the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! The vector code generation is built on top of the scalar code generation (see previous figure). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see figure below). This graph is stored in the class object and a topological sort is applied to it before printing the code.","title":"Vector Code Generation"},{"location":"manual/compiler/#parallel-code-generation","text":"Parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option . It implies that the -vec option as well as the parallel code generation are built on top of the vector code generation.","title":"Parallel Code Generation"},{"location":"manual/compiler/#the-openmp-code-generator","text":"The --openMP (or -omp ) option , when given to the Faust compiler, will insert appropriate OpenMP directives into the C++ code. OpenMP is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure above). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region, a group of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel group until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by every thread of the parallel // team ... } In order not to have every thread doing redundantly the exact same work, OpenMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... }","title":"The OpenMP Code Generator"},{"location":"manual/compiler/#adding-open-mp-directives","text":"As said before, parallel code generation is built on top of vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code }","title":"Adding Open MP Directives"},{"location":"manual/compiler/#example-of-parallel-openmp-code","text":"To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder: The corresponding compute() method obtained using the -omp option looks like this: virtual void compute(int fullcount, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { float fRec0_tmp[36]; float fRec1_tmp[36]; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; #pragma omp parallel\\ firstprivate(fInput0, fInput1, fOutput0, fRec0, fRec1) { for (int index = 0; (index < fullcount); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fInput1 = &fInput1_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = min(32, (fullcount - index)); #pragma omp sections { #pragma omp section { /* Recursive loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } } #pragma omp section { /* Recursive loop 1 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } } } #pragma omp single { /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } } } } } This code requires some comments: the parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1 . The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. the top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between threads. please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. the work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). the work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. the loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. finally #pragma omp single indicates that this section will be executed by only one thread (any of them).","title":"Example of Parallel OpenMP Code"},{"location":"manual/compiler/#the-scheduler-code-generator","text":"With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separate computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large sub-tree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers, and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future.","title":"The Scheduler Code Generator"},{"location":"manual/compiler/#example-of-parallel-scheduler-code","text":"To illustrate how Faust generates the scheduler code, let's reuse the previous example made of two 1-pole filters in parallel connected to an adder: When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; fCount = count; fIndex = 0; /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in each thread WSQ */ initTaskList(fScheduler, -1); signalAll(fScheduler); computeThread(0); syncAll(fScheduler); } void computeThread(int num_thread) { int count = fCount; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; int tasknum = 0; while ((fIndex < fCount)) { fInput0 = &fInput0_ptr[fIndex]; fInput1 = &fInput1_ptr[fIndex]; fOutput0 = &fOutput0_ptr[fIndex]; count = min(32, (fCount - fIndex)); switch (tasknum) { case 0: { /* Work Stealing task */ tasknum = getNextTask(fScheduler, num_thread); break; } case 1: { /* Last task */ fIndex = (fIndex + 32); if (fIndex < fCount) { /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in 'num_thread' WSQ */ initTaskList(fScheduler, num_thread); } tasknum = 0; break; } case 2: { /* Recursive loop 2 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 3: { /* Recursive loop 3 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 4: { /* Vectorizable loop 4 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } tasknum = 1; break; } } } }","title":"Example of Parallel Scheduler Code"},{"location":"manual/debugging/","text":"Debugging the Code Looking at the generated code Using the FIR backend The FIR (Faust Imperative Representation) backend can possibly be used to look at a textual version of the intermediate imperative language. Use the make developer target to compile the FIR backend, then use faust -lang fir foo.dsp to compile a given foo.dsp file as a FIR textual output. import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq1 = hslider(\"freq1 [unit:Hz]\", 1000, 20, 3000, 1); freq2 = hslider(\"freq2 [unit:Hz]\", 200, 20, 3000, 1); process = vgroup(\"Oscillator\", os.osc(freq1) * vol, os.osc(freq2) * vol); For instance compiling the previous code with the faust -lang fir osc.dsp command will display various statistics, for example the number of operations done in the generated compute method: ======= Compute DSP begin ========== Instructions complexity : Load = 23 Store = 9 Binop = 12 [ { Int(+) = 1 } { Int(<) = 1 } { Real(*) = 3 } { Real(+) = 5 } { Real(-) = 2 } ] Mathop = 2 [ { floorf = 2 } ] Numbers = 8 Declare = 1 Cast = 2 Select = 0 Loop = 1 As well as the DSP structure memory size and layout, and read/write statistics: ======= Object memory footprint ========== Heap size int = 4 bytes Heap size int* = 0 bytes Heap size real = 48 bytes Total heap size = 68 bytes Stack size in compute = 28 bytes ======= Variable access in compute control ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 1 w_count = 0 Field = fHslider0 size = 1 r_count = 1 w_count = 0 Field = fConst2 size = 1 r_count = 0 w_count = 0 Field = fRec0 size = 2 r_count = 0 w_count = 0 Field = fConst3 size = 1 r_count = 2 w_count = 0 Field = fHslider1 size = 1 r_count = 1 w_count = 0 Field = fRec2 size = 2 r_count = 0 w_count = 0 Field = fHslider2 size = 1 r_count = 1 w_count = 0 Field = fRec3 size = 2 r_count = 0 w_count = 0 ======= Variable access in compute DSP ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 0 w_count = 0 Field = fHslider0 size = 1 r_count = 0 w_count = 0 Field = fConst2 size = 1 r_count = 1 w_count = 0 Field = fRec0 size = 2 r_count = 4 w_count = 2 Field = fConst3 size = 1 r_count = 0 w_count = 0 Field = fHslider1 size = 1 r_count = 0 w_count = 0 Field = fRec2 size = 2 r_count = 4 w_count = 2 Field = fHslider2 size = 1 r_count = 0 w_count = 0 Field = fRec3 size = 2 r_count = 4 w_count = 2 Those informations can possibly be used to detect abnormal memory consumption. Debugging the DSP Code On a computer, doing a computation that is undefined in mathematics (like val/0 or log(-1) ), and unrepresentable in floating-point arithmetic, will produce a NaN value, which has a special internal representation . Similarly, some computations will exceed the range that is representable with floating-point arithmetics, and are represented with a special INFINITY value, which value depends of the chosen type (like float , double or long double ). After being produced, those values can actually contaminate the following flow of computations (that is Nan + any value = NaN for instance) up to the point of producing incorrect indexes when used in array access, and causing memory access crashes. The Faust compiler gives error messages when the written code is not syntactically or semantically correct, and the interval computation system on signals is supposed to detect possible problematic computations at compile time, and refuse to compile the corresponding DSP code. But the interval calculation is currently quite imperfect , can misbehave, and possibly allow problematic code to be generated. Several strategies have been developed to help programmers better understand their written DSP code, and possibly analyse it, both at compile time and runtime. Debugging at compile time The -ct option Using the -ct compilation option allows to check table index range and generate safe table access code. It verifies that the signal range is compatible with the table size, and if needed, generate safe read and write indexes access code, by constraining them to stay in a given [0.. size-1] range. Note that since the signal interval calculation is imperfect, you may see false positives , and unneeded range constraining code might be generated, especially when using recursive signals where the interval calculation system will typically produce [-inf, inf] range, which is not precise enough to correctly describe the real signal range. The -me option Starting with version 2.37.0, mathematical functions which have a finite domain (like sqrt defined for positive or null values, or asin defined for values in the [-1..1] range) are checked at compile time when they actually compute values at that time , and raise an error if the program tries to compute an out-of-domain value. If those functions appear in the generated code, their domain of use can also be checked (using the interval computation system) and the -me option will display warnings if the domain of use is incorrect. Note that again because of the imperfect interval computation system, false positives may appear and should be checked. Warning messages Warning messages do not stop the compilation process, but allow to get useful informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used. Debugging at runtime The interp-tracer tool The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL , FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW , CAST_INT_OVERFLOW and DIV_BY_ZERO operations, or LOAD/STORE errors. See the complete documentation and the Advanced debugging with interp-tracer tutorial. The faust2caqt tool On macOS, the faust2caqt script has a -me option to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow, etc.) at runtime. Developers can possibly use the dsp_me_checker class to decorate a given DSP object with the math computation exception handling code. Fixing the errors These errors must then be corrected by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items. Additional Resources Note that the Faust math library contains the implementation of isnan and isinf functions that may help during development. Handling infinity and not-a-number (NaN) the right way still remains a tricky problem that is not completely handled in the current version of the compiler. Dario Sanfilippo blog post is a very helpful summary of the situation with a lot of practical solutions to write safer DSP code .","title":"Debugging the Code"},{"location":"manual/debugging/#debugging-the-code","text":"","title":"Debugging the Code"},{"location":"manual/debugging/#looking-at-the-generated-code","text":"","title":"Looking at the generated code"},{"location":"manual/debugging/#using-the-fir-backend","text":"The FIR (Faust Imperative Representation) backend can possibly be used to look at a textual version of the intermediate imperative language. Use the make developer target to compile the FIR backend, then use faust -lang fir foo.dsp to compile a given foo.dsp file as a FIR textual output. import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq1 = hslider(\"freq1 [unit:Hz]\", 1000, 20, 3000, 1); freq2 = hslider(\"freq2 [unit:Hz]\", 200, 20, 3000, 1); process = vgroup(\"Oscillator\", os.osc(freq1) * vol, os.osc(freq2) * vol); For instance compiling the previous code with the faust -lang fir osc.dsp command will display various statistics, for example the number of operations done in the generated compute method: ======= Compute DSP begin ========== Instructions complexity : Load = 23 Store = 9 Binop = 12 [ { Int(+) = 1 } { Int(<) = 1 } { Real(*) = 3 } { Real(+) = 5 } { Real(-) = 2 } ] Mathop = 2 [ { floorf = 2 } ] Numbers = 8 Declare = 1 Cast = 2 Select = 0 Loop = 1 As well as the DSP structure memory size and layout, and read/write statistics: ======= Object memory footprint ========== Heap size int = 4 bytes Heap size int* = 0 bytes Heap size real = 48 bytes Total heap size = 68 bytes Stack size in compute = 28 bytes ======= Variable access in compute control ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 1 w_count = 0 Field = fHslider0 size = 1 r_count = 1 w_count = 0 Field = fConst2 size = 1 r_count = 0 w_count = 0 Field = fRec0 size = 2 r_count = 0 w_count = 0 Field = fConst3 size = 1 r_count = 2 w_count = 0 Field = fHslider1 size = 1 r_count = 1 w_count = 0 Field = fRec2 size = 2 r_count = 0 w_count = 0 Field = fHslider2 size = 1 r_count = 1 w_count = 0 Field = fRec3 size = 2 r_count = 0 w_count = 0 ======= Variable access in compute DSP ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 0 w_count = 0 Field = fHslider0 size = 1 r_count = 0 w_count = 0 Field = fConst2 size = 1 r_count = 1 w_count = 0 Field = fRec0 size = 2 r_count = 4 w_count = 2 Field = fConst3 size = 1 r_count = 0 w_count = 0 Field = fHslider1 size = 1 r_count = 0 w_count = 0 Field = fRec2 size = 2 r_count = 4 w_count = 2 Field = fHslider2 size = 1 r_count = 0 w_count = 0 Field = fRec3 size = 2 r_count = 4 w_count = 2 Those informations can possibly be used to detect abnormal memory consumption.","title":"Using the FIR backend"},{"location":"manual/debugging/#debugging-the-dsp-code","text":"On a computer, doing a computation that is undefined in mathematics (like val/0 or log(-1) ), and unrepresentable in floating-point arithmetic, will produce a NaN value, which has a special internal representation . Similarly, some computations will exceed the range that is representable with floating-point arithmetics, and are represented with a special INFINITY value, which value depends of the chosen type (like float , double or long double ). After being produced, those values can actually contaminate the following flow of computations (that is Nan + any value = NaN for instance) up to the point of producing incorrect indexes when used in array access, and causing memory access crashes. The Faust compiler gives error messages when the written code is not syntactically or semantically correct, and the interval computation system on signals is supposed to detect possible problematic computations at compile time, and refuse to compile the corresponding DSP code. But the interval calculation is currently quite imperfect , can misbehave, and possibly allow problematic code to be generated. Several strategies have been developed to help programmers better understand their written DSP code, and possibly analyse it, both at compile time and runtime.","title":"Debugging the DSP Code"},{"location":"manual/debugging/#debugging-at-compile-time","text":"","title":"Debugging at compile time"},{"location":"manual/debugging/#the-ct-option","text":"Using the -ct compilation option allows to check table index range and generate safe table access code. It verifies that the signal range is compatible with the table size, and if needed, generate safe read and write indexes access code, by constraining them to stay in a given [0.. size-1] range. Note that since the signal interval calculation is imperfect, you may see false positives , and unneeded range constraining code might be generated, especially when using recursive signals where the interval calculation system will typically produce [-inf, inf] range, which is not precise enough to correctly describe the real signal range.","title":"The -ct option"},{"location":"manual/debugging/#the-me-option","text":"Starting with version 2.37.0, mathematical functions which have a finite domain (like sqrt defined for positive or null values, or asin defined for values in the [-1..1] range) are checked at compile time when they actually compute values at that time , and raise an error if the program tries to compute an out-of-domain value. If those functions appear in the generated code, their domain of use can also be checked (using the interval computation system) and the -me option will display warnings if the domain of use is incorrect. Note that again because of the imperfect interval computation system, false positives may appear and should be checked.","title":"The -me option"},{"location":"manual/debugging/#warning-messages","text":"Warning messages do not stop the compilation process, but allow to get useful informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Warning messages"},{"location":"manual/debugging/#debugging-at-runtime","text":"","title":"Debugging at runtime"},{"location":"manual/debugging/#the-interp-tracer-tool","text":"The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL , FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW , CAST_INT_OVERFLOW and DIV_BY_ZERO operations, or LOAD/STORE errors. See the complete documentation and the Advanced debugging with interp-tracer tutorial.","title":"The interp-tracer tool"},{"location":"manual/debugging/#the-faust2caqt-tool","text":"On macOS, the faust2caqt script has a -me option to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow, etc.) at runtime. Developers can possibly use the dsp_me_checker class to decorate a given DSP object with the math computation exception handling code.","title":"The faust2caqt tool"},{"location":"manual/debugging/#fixing-the-errors","text":"These errors must then be corrected by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items.","title":"Fixing the errors"},{"location":"manual/debugging/#additional-resources","text":"Note that the Faust math library contains the implementation of isnan and isinf functions that may help during development. Handling infinity and not-a-number (NaN) the right way still remains a tricky problem that is not completely handled in the current version of the compiler. Dario Sanfilippo blog post is a very helpful summary of the situation with a lot of practical solutions to write safer DSP code .","title":"Additional Resources"},{"location":"manual/deploying/","text":"Deploying Faust DSP on the Web Using developments done for the Web (WebAssembly backends and libfaust library compiled in WebAssembly with Emscripten ), statically and dynamically Faust generated WebAudio nodes can be easily produced and deployed on the Web. See extended documentation here . Note : this model will soon be deprecated, better use the faustwasm package . Note : the faust2cpp2wasm tool can possibly be used as a drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend. The faustwasm package The FaustWasm library presents a convenient, high-level API that wraps around Faust compiler. This library's interface is primarily designed for TypeScript usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both Node.js and web browsers, has been compiled using Emscripten 3.1.31. The library offers functionality for compiling Faust DSP code into WebAssembly, enabling its utilization as WebAudio nodes within a standard WebAudio node graph. Moreover, it supports offline rendering scenarios. Furthermore, supplementary tools can be employed for generating SVGs from Faust DSP programs. Exporting for the Web Web targets can be exported from the Faust Editor or Faust IDE using the remote compilation service. Choose Platform = web , then Architecture with one of the following target: wasmjs allows you to export a ready to use Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. wasmjs-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. webaudiowasm allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. webaudiowasm-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. pwa allows you to export a ready to use Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. pwa-poly allows you to export a ready to use polyphonic MIDI controllable Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. Exporting WAM 2.0 plugins WAM 2.0 plugin can be exported from the Faust Editor or Faust IDE using the remote compilation service. A complete tutorial can be found here . Choose Platform = web , then Architecture with one of the following target: wam2-ts allows you to export a ready to use WAM 2.0 plugin. wam2-poly-ts allows you to export a ready to use polyphonic MIDI controllable WAM 2.0 plugin. wam2-fft-ts allows you to export a ready to use WAM 2.0 plugin using the FFT architecture presented in this paper . The faust-web-component package Tthe faust-web-component package provides two web components for embedding interactive Faust snippets in web pages: <faust-editor> displays an editor (using CodeMirror 6 ) with executable, editable Faust code, along with some bells & whistles (controls, block diagram, plots) in a side pane. This component is ideal for demonstrating some code in Faust and allowing the reader to try it out and tweak it themselves without having to leave the page, and can been tested here . <faust-widget> just shows the controls and does not allow editing, so it serves simply as a way to embed interactive DSP, and can been tested here . These components are built on top of faustwasm and faust-ui packages and is released as a npm package .","title":"Deploying on the Web"},{"location":"manual/deploying/#deploying-faust-dsp-on-the-web","text":"Using developments done for the Web (WebAssembly backends and libfaust library compiled in WebAssembly with Emscripten ), statically and dynamically Faust generated WebAudio nodes can be easily produced and deployed on the Web. See extended documentation here . Note : this model will soon be deprecated, better use the faustwasm package . Note : the faust2cpp2wasm tool can possibly be used as a drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend.","title":"Deploying Faust DSP on the Web"},{"location":"manual/deploying/#the-faustwasm-package","text":"The FaustWasm library presents a convenient, high-level API that wraps around Faust compiler. This library's interface is primarily designed for TypeScript usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both Node.js and web browsers, has been compiled using Emscripten 3.1.31. The library offers functionality for compiling Faust DSP code into WebAssembly, enabling its utilization as WebAudio nodes within a standard WebAudio node graph. Moreover, it supports offline rendering scenarios. Furthermore, supplementary tools can be employed for generating SVGs from Faust DSP programs.","title":"The faustwasm package"},{"location":"manual/deploying/#exporting-for-the-web","text":"Web targets can be exported from the Faust Editor or Faust IDE using the remote compilation service. Choose Platform = web , then Architecture with one of the following target: wasmjs allows you to export a ready to use Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. wasmjs-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. webaudiowasm allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. webaudiowasm-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrate how the node can be loaded and activated. pwa allows you to export a ready to use Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. pwa-poly allows you to export a ready to use polyphonic MIDI controllable Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code.","title":"Exporting for the Web"},{"location":"manual/deploying/#exporting-wam-20-plugins","text":"WAM 2.0 plugin can be exported from the Faust Editor or Faust IDE using the remote compilation service. A complete tutorial can be found here . Choose Platform = web , then Architecture with one of the following target: wam2-ts allows you to export a ready to use WAM 2.0 plugin. wam2-poly-ts allows you to export a ready to use polyphonic MIDI controllable WAM 2.0 plugin. wam2-fft-ts allows you to export a ready to use WAM 2.0 plugin using the FFT architecture presented in this paper .","title":"Exporting WAM 2.0 plugins"},{"location":"manual/deploying/#the-faust-web-component-package","text":"Tthe faust-web-component package provides two web components for embedding interactive Faust snippets in web pages: <faust-editor> displays an editor (using CodeMirror 6 ) with executable, editable Faust code, along with some bells & whistles (controls, block diagram, plots) in a side pane. This component is ideal for demonstrating some code in Faust and allowing the reader to try it out and tweak it themselves without having to leave the page, and can been tested here . <faust-widget> just shows the controls and does not allow editing, so it serves simply as a way to embed interactive DSP, and can been tested here . These components are built on top of faustwasm and faust-ui packages and is released as a npm package .","title":"The faust-web-component package"},{"location":"manual/embedding/","text":"Embedding the Faust Compiler Using libfaust Dynamic Compilation Chain The Faust compiler uses an intermediate FIR representation (Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures ( for and while loops, if structure, etc.). To generate various output languages, several backends have been developed for C, C++, Interpreter, Java, LLVM IR, WebAssembly, etc. The Interpreter, LLVM IR and WebAssembly ones are particularly interesting since they allow the direct compilation of a DSP program into executable code in memory, bypassing the external compiler requirement. Using libfaust with the LLVM backend Libfaust with LLVM backend API The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file-based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. Creation API The libfaust library exports the following API: given a Faust source code (as a string or a file), calling the createDSPFactoryFromString or createDSPFactoryFromFile functions runs the compilation chain (Faust + LLVM JIT) and generates the prototype of the class, as a llvm_dsp_factory pointer. This factory actually contains the compiled LLVM IR for the given DSP alternatively the createCPPDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance function (corresponding to the new className of C++) instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed a unique SHA1 key of the created factory can be obtained using its getSHAKey method Saving/restoring the factory After the DSP factory has been compiled, the application or the plugin running it might need to save it and then restore it. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR : get the DSP factory LLVM IR (in textual format) as a string writeDSPFactoryToIRFile : get the DSP factory LLVM IR (in textual format) and write it to a file writeDSPFactoryToBitcode : get the DSP factory LLVM IR (in binary format) as a string writeDSPFactoryToBitcodeFile : save the DSP factory LLVM IR (in binary format) in a file writeDSPFactoryToMachine : get the DSP factory executable machine code as a string writeDSPFactoryToMachineFile : save the DSP factory executable machine code in a file To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR : create a DSP factory from a string containing the LLVM IR (in textual format) readDSPFactoryFromIRFile : create a DSP factory from a file containing the LLVM IR (in textual format) readDSPFactoryFromBitcode : create a DSP factory from a string containing the LLVM IR (in binary format) readDSPFactoryFromBitcodeFile : create a DSP factory from a file containing the LLVM IR (in binary format) readDSPFactoryFromMachine : create a DSP factory from a string containing the executable machine code readDSPFactoryFromMachineFile : create a DSP factory from a file containing the executable machine code. Typical code example More generally, a typical use of libfaust in C++ could look like: // The Faust code to compile as a string (could be in a file too) string theCode = \"import(\\\"stdfaust.lib\\\"); process = no.noise;\"; // Compiling in memory (createDSPFactoryFromFile could be used alternatively) llvm_dsp_factory* m_factory = createDSPFactoryFromString( \"faust\", theCode, argc, argv, \"\", m_errorString, optimize); // creating the DSP instance for interfacing dsp* m_dsp = m_factory->createDSPInstance(); // Creating a generic UI to interact with the DSP my_ui* m_ui = new MyUI(); // linking the interface to the DSP instance m_dsp->buildUserInterface(m_ui); // Initializing the DSP instance with the SR m_dsp->init(44100); // Hypothetical audio callback, assuming m_input/m_output are previously allocated while (...) { m_dsp->compute(128, m_input, m_output); } // Cleaning // Manually delete the DSP delete m_dsp; delete m_ui; // The factory actually keeps track of all allocated DSP (done in createDSPInstance). // So if not manually deleted, all remaining DSP will be garbaged here. deleteDSPFactory(m_factory); The first step consists in creating a DSP factory from a DSP file (using createDSPFactoryFromFile ) or string (using createDSPFactoryFromString ) with additional parameters given to the compiler. Assuming the compilation works, a factory is returned, to create a DSP instance with the factory createDSPInstance method. Note that the resulting llvm_dsp* pointer type (see faust/dsp/llvm-dsp.h header file) is a subclass of the base dsp class (see faust/dsp/dsp.h header file). Thus it can be used with any UI type to plug a GUI, MIDI or OSC controller on the DSP object, like it would be done with a DSP program compiled to a C++ class (the generated mydsp class is also a subclass of the base dsp class). This is demonstrated with the my_ui* m_ui = new MyUI(); and m_dsp->buildUserInterface(m_ui); lines where the buildUserInterface method is used to connect a controller. Then the DSP object has to be connected to an audio driver to be rendered (see the m_dsp->compute(128, m_input, m_output); block). A more complete C++ example can be found here . A example using the pure C API can be found here . Using libfaust with the Interpreter backend When compiled to embed the Interpreter backend , libfaust can also be used to generate the Faust Bytes Code (FBC) format and interpret it in memory. Libfaust with Interpreter backend API The interpreter backend (described in this paper ) has been first written to allow dynamical compilation on iOS, where Apple does not allow LLVM based JIT compilation to be deployed, but can also be used to develop testing tools . It has been defined as a typed bytecode and a virtual machine to execute it. The FIR language is simple enough to be easily translated in the typed bytecode for an interpreter, generated by a FIR to bytecode compilation pass. The virtual machine then executes the bytecode on a stack based machine. Creation API The interpreter backend API is similar to the LLVM backend API: given a FAUST source code (as a file or a string), calling the createInterpreterDSPFactory function runs the compilation chain (Faust + interpreter backend) and generates the prototype of the class, as an interpreter_dsp_factory pointer. This factory actually contains the compiled bytecode for the given DSP alternatively the createInterpreterDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createInterpreterDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance method of the factory class, corresponding to the new className of C++, instantiates an interpreter_dsp pointer, to be used as any regular Faust compiled DSP object, run and controlled through its interface. The instance contains the interpreter virtual machine loaded with the compiled bytecode, to be executed for each method. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since interpreter_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteInterpreterDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed. a unique SHA1 key of the created factory can be obtained using its getSHAKey method Saving/restoring the factory After the DSP factory has been compiled, the application or plugin may want to save/restore it in order to save Faust to interpreter bytecode compilation at next use. To get the internal factory bytecode and save it, two functions are available: writeInterpreterDSPFactoryToMachine allows to get the interpreter bytecode as a string writeInterpreterDSPFactoryToMachineFile allows to save the interpreter bytecode in a file To re-create a DSP factory from a previously saved code, two functions are available: readInterpreterDSPFactoryFromMachine allows to create a DSP factory from a string containing the interpreter bytecode readInterpreterDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the interpreter bytecode The complete API is available and documented in the installed faust/dsp/interpreter-dsp.h header. Note that only the scalar compilation mode is supported. A more complete C++ example can be found here . Performances The generated code is obviously much slower than LLVM generated native code. Measurements on various DSPs examples have been done, and the code is between 3 and more than 10 times slower than the LLVM native code. Using libfaust with the WebAssembly backend The libfaust C++ library can be compiled in WebAssembly with Emscripten , and used in the web or NodeJS platforms. A specific page on the subject is available. Additional Functions Some additional functions are available in the libfaust API: Expanding the DSP code . The expandDSPFromString / expandDSPFromFile functions can be used to generate a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string. This is a way to create self-contained version of DSP programs. Using other backends or generating auxiliary files . The generateAuxFilesFromString and generateAuxFilesFromFile functions taking a DSP source string or file can be used: to activate and use other backends (depending of which ones have been compiled in libfaust) to generate like C, C++, or Cmajor code, etc. The argv parameter has to mimic the command line like for instance: -lang cpp -vec -lv 1 to generate a C++ file in vector mode. to generate auxiliary files which can be text files SVG, XML, ps, etc. The argv parameter has to mimic the command line like for instance: -json to generate a JSON file. Sample size adaptation When compiled with the -double option, the generated code internally uses double format for samples, but also expects inputs/outputs buffers to be filled with samples in double. The dsp_sample_adapter decorator class defined in faust/dsp/dsp-adapter.h can be used to adapt the buffers. Deployment The application or plugin using libfaust can embed the library either as a statically linked component (to get a self-contained binary) or provided as a separate component to be loaded dynamically at runtime. The Faust libraries themselves usually have to be bundled separately and can be accessed at runtime using the compiler -I /path/to/libraries option in createDSPFactoryFromString/createDSPFactoryFromFile functions. Additional Resources Some papers and tutorials are available: Comment Embarquer le Compilateur Faust dans Vos Applications ? An Overview of the FAUST Developer Ecosystem Using the box API Using the signal API Use Case Examples The dynamic compilation chain has been used in several projects: FaustLive : an integrated IDE for Faust development offering on-the-fly compilation and execution features Faustgen : a generic Faust Max/MSP programmable external object Faustgen : a generic Faust PureData programmable external object The faustgen2~ object is a Faust external for Pd a.k.a. Pure Data, Miller Puckette's interactive multimedia programming environment Faust for Csound : a Csound opcode running the Faust compiler internally LibAudioStream : a framework to manipulate audio ressources through the concept of streams Faust for JUCE : a tool integrating the Faust compiler to JUCE developed by Oliver Larkin and available as part of the pMix2 project An experimental integration of Faust in Antescofo FaucK : the combination of the ChucK Programming Language and Faust libossia is a modern C++, cross-environment distributed object model for creative coding. It is used in Ossia score project Radium is a music editor with a new type of interface, including a Faust audio DSP development environment using libfaust with the LLVM and Interpreter backends Mephisto LV2 is a Just-in-Time Faust compiler embedded in an LV2 plugin, using the C API. gwion-plug is a Faust plugin for the Gwion programming language. FaustGen allows to livecode Faust in SuperCollider. It uses the libfaust LLVM C++ API. FAUSTPy is a Python wrapper for the Faust DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust.jl is Julia wrapper for the Faust compiler. It uses the libfaust LLVM C API. fl-tui is a Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs is another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. DawDreamer is an audio-processing Python framework supporting core DAW features. It uses the libfaust LLVM C API. metaSurface64 is a real-time continuous sound transformation control surface that features both its own loop generator for up to 64 voices and a multi-effects FX engine. It uses the libfaust LLVM C++ API. metaFx is a control surface for continuous sound transformations in real time, just like the metaSurface64. Like metaSurface64, it has both its own loop generator and a multi-effects FX engine, but its operation is different, especially for the management of plugin chains and pads. HISE is an open source framework for building sample based virtual instruments combining a highly performant Disk-Streaming Engine, a flexible DSP-Audio Module system and a handy Interface Designer. AMATI is a VST plugin for live-coding effects in the Faust programming language. cyfaust is a cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. nih-faust-jit ia a plugin written in Rust to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"Embedding the Compiler"},{"location":"manual/embedding/#embedding-the-faust-compiler-using-libfaust","text":"","title":"Embedding the Faust Compiler Using libfaust"},{"location":"manual/embedding/#dynamic-compilation-chain","text":"The Faust compiler uses an intermediate FIR representation (Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures ( for and while loops, if structure, etc.). To generate various output languages, several backends have been developed for C, C++, Interpreter, Java, LLVM IR, WebAssembly, etc. The Interpreter, LLVM IR and WebAssembly ones are particularly interesting since they allow the direct compilation of a DSP program into executable code in memory, bypassing the external compiler requirement.","title":"Dynamic Compilation Chain"},{"location":"manual/embedding/#using-libfaust-with-the-llvm-backend","text":"","title":"Using libfaust with the LLVM backend"},{"location":"manual/embedding/#libfaust-with-llvm-backend-api","text":"The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file-based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters.","title":"Libfaust with LLVM backend API"},{"location":"manual/embedding/#creation-api","text":"The libfaust library exports the following API: given a Faust source code (as a string or a file), calling the createDSPFactoryFromString or createDSPFactoryFromFile functions runs the compilation chain (Faust + LLVM JIT) and generates the prototype of the class, as a llvm_dsp_factory pointer. This factory actually contains the compiled LLVM IR for the given DSP alternatively the createCPPDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance function (corresponding to the new className of C++) instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed a unique SHA1 key of the created factory can be obtained using its getSHAKey method","title":"Creation API"},{"location":"manual/embedding/#savingrestoring-the-factory","text":"After the DSP factory has been compiled, the application or the plugin running it might need to save it and then restore it. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR : get the DSP factory LLVM IR (in textual format) as a string writeDSPFactoryToIRFile : get the DSP factory LLVM IR (in textual format) and write it to a file writeDSPFactoryToBitcode : get the DSP factory LLVM IR (in binary format) as a string writeDSPFactoryToBitcodeFile : save the DSP factory LLVM IR (in binary format) in a file writeDSPFactoryToMachine : get the DSP factory executable machine code as a string writeDSPFactoryToMachineFile : save the DSP factory executable machine code in a file To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR : create a DSP factory from a string containing the LLVM IR (in textual format) readDSPFactoryFromIRFile : create a DSP factory from a file containing the LLVM IR (in textual format) readDSPFactoryFromBitcode : create a DSP factory from a string containing the LLVM IR (in binary format) readDSPFactoryFromBitcodeFile : create a DSP factory from a file containing the LLVM IR (in binary format) readDSPFactoryFromMachine : create a DSP factory from a string containing the executable machine code readDSPFactoryFromMachineFile : create a DSP factory from a file containing the executable machine code.","title":"Saving/restoring the factory"},{"location":"manual/embedding/#typical-code-example","text":"More generally, a typical use of libfaust in C++ could look like: // The Faust code to compile as a string (could be in a file too) string theCode = \"import(\\\"stdfaust.lib\\\"); process = no.noise;\"; // Compiling in memory (createDSPFactoryFromFile could be used alternatively) llvm_dsp_factory* m_factory = createDSPFactoryFromString( \"faust\", theCode, argc, argv, \"\", m_errorString, optimize); // creating the DSP instance for interfacing dsp* m_dsp = m_factory->createDSPInstance(); // Creating a generic UI to interact with the DSP my_ui* m_ui = new MyUI(); // linking the interface to the DSP instance m_dsp->buildUserInterface(m_ui); // Initializing the DSP instance with the SR m_dsp->init(44100); // Hypothetical audio callback, assuming m_input/m_output are previously allocated while (...) { m_dsp->compute(128, m_input, m_output); } // Cleaning // Manually delete the DSP delete m_dsp; delete m_ui; // The factory actually keeps track of all allocated DSP (done in createDSPInstance). // So if not manually deleted, all remaining DSP will be garbaged here. deleteDSPFactory(m_factory); The first step consists in creating a DSP factory from a DSP file (using createDSPFactoryFromFile ) or string (using createDSPFactoryFromString ) with additional parameters given to the compiler. Assuming the compilation works, a factory is returned, to create a DSP instance with the factory createDSPInstance method. Note that the resulting llvm_dsp* pointer type (see faust/dsp/llvm-dsp.h header file) is a subclass of the base dsp class (see faust/dsp/dsp.h header file). Thus it can be used with any UI type to plug a GUI, MIDI or OSC controller on the DSP object, like it would be done with a DSP program compiled to a C++ class (the generated mydsp class is also a subclass of the base dsp class). This is demonstrated with the my_ui* m_ui = new MyUI(); and m_dsp->buildUserInterface(m_ui); lines where the buildUserInterface method is used to connect a controller. Then the DSP object has to be connected to an audio driver to be rendered (see the m_dsp->compute(128, m_input, m_output); block). A more complete C++ example can be found here . A example using the pure C API can be found here .","title":"Typical code example"},{"location":"manual/embedding/#using-libfaust-with-the-interpreter-backend","text":"When compiled to embed the Interpreter backend , libfaust can also be used to generate the Faust Bytes Code (FBC) format and interpret it in memory.","title":"Using libfaust with the Interpreter backend"},{"location":"manual/embedding/#libfaust-with-interpreter-backend-api","text":"The interpreter backend (described in this paper ) has been first written to allow dynamical compilation on iOS, where Apple does not allow LLVM based JIT compilation to be deployed, but can also be used to develop testing tools . It has been defined as a typed bytecode and a virtual machine to execute it. The FIR language is simple enough to be easily translated in the typed bytecode for an interpreter, generated by a FIR to bytecode compilation pass. The virtual machine then executes the bytecode on a stack based machine.","title":"Libfaust with Interpreter backend API"},{"location":"manual/embedding/#creation-api_1","text":"The interpreter backend API is similar to the LLVM backend API: given a FAUST source code (as a file or a string), calling the createInterpreterDSPFactory function runs the compilation chain (Faust + interpreter backend) and generates the prototype of the class, as an interpreter_dsp_factory pointer. This factory actually contains the compiled bytecode for the given DSP alternatively the createInterpreterDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createInterpreterDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance method of the factory class, corresponding to the new className of C++, instantiates an interpreter_dsp pointer, to be used as any regular Faust compiled DSP object, run and controlled through its interface. The instance contains the interpreter virtual machine loaded with the compiled bytecode, to be executed for each method. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since interpreter_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteInterpreterDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed. a unique SHA1 key of the created factory can be obtained using its getSHAKey method","title":"Creation API"},{"location":"manual/embedding/#savingrestoring-the-factory_1","text":"After the DSP factory has been compiled, the application or plugin may want to save/restore it in order to save Faust to interpreter bytecode compilation at next use. To get the internal factory bytecode and save it, two functions are available: writeInterpreterDSPFactoryToMachine allows to get the interpreter bytecode as a string writeInterpreterDSPFactoryToMachineFile allows to save the interpreter bytecode in a file To re-create a DSP factory from a previously saved code, two functions are available: readInterpreterDSPFactoryFromMachine allows to create a DSP factory from a string containing the interpreter bytecode readInterpreterDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the interpreter bytecode The complete API is available and documented in the installed faust/dsp/interpreter-dsp.h header. Note that only the scalar compilation mode is supported. A more complete C++ example can be found here .","title":"Saving/restoring the factory"},{"location":"manual/embedding/#performances","text":"The generated code is obviously much slower than LLVM generated native code. Measurements on various DSPs examples have been done, and the code is between 3 and more than 10 times slower than the LLVM native code.","title":"Performances"},{"location":"manual/embedding/#using-libfaust-with-the-webassembly-backend","text":"The libfaust C++ library can be compiled in WebAssembly with Emscripten , and used in the web or NodeJS platforms. A specific page on the subject is available.","title":"Using libfaust with the WebAssembly backend"},{"location":"manual/embedding/#additional-functions","text":"Some additional functions are available in the libfaust API: Expanding the DSP code . The expandDSPFromString / expandDSPFromFile functions can be used to generate a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string. This is a way to create self-contained version of DSP programs. Using other backends or generating auxiliary files . The generateAuxFilesFromString and generateAuxFilesFromFile functions taking a DSP source string or file can be used: to activate and use other backends (depending of which ones have been compiled in libfaust) to generate like C, C++, or Cmajor code, etc. The argv parameter has to mimic the command line like for instance: -lang cpp -vec -lv 1 to generate a C++ file in vector mode. to generate auxiliary files which can be text files SVG, XML, ps, etc. The argv parameter has to mimic the command line like for instance: -json to generate a JSON file.","title":"Additional Functions"},{"location":"manual/embedding/#sample-size-adaptation","text":"When compiled with the -double option, the generated code internally uses double format for samples, but also expects inputs/outputs buffers to be filled with samples in double. The dsp_sample_adapter decorator class defined in faust/dsp/dsp-adapter.h can be used to adapt the buffers.","title":"Sample size adaptation"},{"location":"manual/embedding/#deployment","text":"The application or plugin using libfaust can embed the library either as a statically linked component (to get a self-contained binary) or provided as a separate component to be loaded dynamically at runtime. The Faust libraries themselves usually have to be bundled separately and can be accessed at runtime using the compiler -I /path/to/libraries option in createDSPFactoryFromString/createDSPFactoryFromFile functions.","title":"Deployment"},{"location":"manual/embedding/#additional-resources","text":"Some papers and tutorials are available: Comment Embarquer le Compilateur Faust dans Vos Applications ? An Overview of the FAUST Developer Ecosystem Using the box API Using the signal API","title":"Additional Resources"},{"location":"manual/embedding/#use-case-examples","text":"The dynamic compilation chain has been used in several projects: FaustLive : an integrated IDE for Faust development offering on-the-fly compilation and execution features Faustgen : a generic Faust Max/MSP programmable external object Faustgen : a generic Faust PureData programmable external object The faustgen2~ object is a Faust external for Pd a.k.a. Pure Data, Miller Puckette's interactive multimedia programming environment Faust for Csound : a Csound opcode running the Faust compiler internally LibAudioStream : a framework to manipulate audio ressources through the concept of streams Faust for JUCE : a tool integrating the Faust compiler to JUCE developed by Oliver Larkin and available as part of the pMix2 project An experimental integration of Faust in Antescofo FaucK : the combination of the ChucK Programming Language and Faust libossia is a modern C++, cross-environment distributed object model for creative coding. It is used in Ossia score project Radium is a music editor with a new type of interface, including a Faust audio DSP development environment using libfaust with the LLVM and Interpreter backends Mephisto LV2 is a Just-in-Time Faust compiler embedded in an LV2 plugin, using the C API. gwion-plug is a Faust plugin for the Gwion programming language. FaustGen allows to livecode Faust in SuperCollider. It uses the libfaust LLVM C++ API. FAUSTPy is a Python wrapper for the Faust DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust.jl is Julia wrapper for the Faust compiler. It uses the libfaust LLVM C API. fl-tui is a Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs is another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. DawDreamer is an audio-processing Python framework supporting core DAW features. It uses the libfaust LLVM C API. metaSurface64 is a real-time continuous sound transformation control surface that features both its own loop generator for up to 64 voices and a multi-effects FX engine. It uses the libfaust LLVM C++ API. metaFx is a control surface for continuous sound transformations in real time, just like the metaSurface64. Like metaSurface64, it has both its own loop generator and a multi-effects FX engine, but its operation is different, especially for the management of plugin chains and pads. HISE is an open source framework for building sample based virtual instruments combining a highly performant Disk-Streaming Engine, a flexible DSP-Audio Module system and a handy Interface Designer. AMATI is a VST plugin for live-coding effects in the Faust programming language. cyfaust is a cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. nih-faust-jit ia a plugin written in Rust to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"Use Case Examples"},{"location":"manual/errors/","text":"Error messages Error messages are typically displayed in the form of compiler errors. They occur when the code cannot be successfully compiled, and typically indicate issues such as syntax errors or semantic errors. They can occur at different stages in the compilation process, possibly with the file and line number where the error occurred (when this information can be retrieved), as well as a brief description of the error. The compiler is organized in several stages: starting from the DSP source code, the parser builds an internal memory representation of the source program (typically known as an Abstract Source Tree ) made here of primitives in the Box language . A first class of errors messages are known as syntax error messages, like missing the ; character to end a line, etc. the next step is to evaluate the definition of process programe entry point. This step is basically a \u03bb-calculus interpreter with a strict evaluation. The result is \u201dflat\u201d block-diagram where everything have been expanded. The resulting block is type annoatetd to discover its number of inputs and outputs. the \u201dflat\u201d block-diagram is then translated the Signal language where signals as conceptually infinite streams of samples or control values. The box language actually implements the Faust Block Diagram Algebra , and not following the connections rules will trigger a second class of errors messages, the box connection errors . Other errors can be produced at this stage when parameters for some primitives are not of the correct type. the pattern matching meta language allows to algorithmically create and manipulate block diagrams expressions. So a third class of pattern matching coding errors can occur at this level. signal expressions are optimized, type annotated (to associate an integer or real type with each signal, but also discovering when signals are to be computed: at init time, control-rate or sample-rate..) to produce a so-called normal-form . A fourth class of parameter range errors or typing errors can occur at this level, like using delays with a non-bounded size, etc. signal expressions are then converted in FIR (Faust Imperative Representation), a representation for state based computation (memory access, arithmetic computations, control flow, etc.), to be converted into the final target language (like C/C++, LLVM IR, Rust, WebAssembly, etc.). A fifth class of backend errors can occur at this level, like non supported compilation options for a given backend, etc. Note that the current error messages system is still far from perfect, usually when the origin of the error in the DSP source cannot be properly traced. In this case the file and line number where the error occurred are not displayed, but an internal description of the expression (as a Box of a Signal) is printed. Syntax errors Those errors happen when the language syntax is not respected. Here are some examples. The following program: box1 = 1 box2 = 2; process = box1,box2; will produce the following error message: errors.dsp : 2 : ERROR : syntax error, unexpected IDENT It means that an unexpected identifier as been found line 2 of the file test.dsp. Usually, this error is due to the absence of the semi-column ; at the end of the previous line. The following program: t1 = _~(+(1); 2 process = t1 / 2147483647; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF The parser finds the end of the definition ( ; ) while searching a closing right parenthesis. The following program: process = ffunction; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF, expecting LPAR The parser was expecting a left parenthesis. It identified a keyword of the language that requires arguments. The following program: process = +)1); will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected RPAR The wrong parenthesis has been used. The following program: process = <:+; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected SPLIT The <: split operator is not correctly used, and should have been written process = _<:+; . The following program: process = foo; will produce the following error message: errors.dsp : 1 : ERROR : undefined symbol : foo This happens when an undefined name is used. Box connection errors Diagram expressions express how block expressions can be combined to create new ones. The connection rules are precisely defined for each of them and have to be followed for the program to be correct. Remember the operator priority when writing more complex expressions. The five connections rules A second category of error messages is returned when block expressions are not correctly connected. Parallel connection Combining two blocks A and B in parallel can never produce a box connection error since the 2 blocks are placed one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Sequencial connection error Combining two blocks A and B in sequence will produce a box connection error if outputs(A) != inputs(B) . So for instance the following program: A = _,_; B = _,_,_; process = A : B; will produce the following error message: ERROR : sequential composition A:B The number of outputs [2] of A must be equal to the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Split connection error Combining two blocks A and B with the split composition will produce a box connection error if the number of inputs of B is not a multiple of the number of outputs of A . So for instance the following program: A = _,_; B = _,_,_; process = A <: B; will produce the following error message: ERROR : split composition A<:B The number of outputs [2] of A must be a divisor of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Merge connection error Combining two blocks A and B with the merge composition will produce a box connection error if the number of outputs of A is not a multiple of the number of inputs of B . So for instance the following program: A = _,_; B = _,_,_; process = A :> B; will produce the following error message: ERROR : merge composition A:>B The number of outputs [2] of A must be a multiple of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Recursive connection error Combining two blocks A and B with the recursive composition will produce a box connection error if the number of outputs of A is less than the number of inputs of B , or the number of outputs of B is more than the number of inputs of A (that is the following \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) connection rule is not respected). So for instance the following program: A = _,_; B = _,_,_; process = A ~ B; will produce the following error message: ERROR : recursive composition A~B The number of outputs [2] of A must be at least the number of inputs [3] of B. The number of inputs [2] of A must be at least the number of outputs [3] of B. Here A = _,_; has 2 inputs and 2 outputs while B = _,_,_; has 3 inputs and 3 outputs Route connection errors More complex routing between blocks can also be described using the route primitive. Two different errors can be produced in case of incorrect coding: process = route(+,8.7,(0,0),(0,1)); will produce the following error message: ERROR : invalid route expression, first two parameters should be blocks producing a value, third parameter a list of input/output pairs : route(+,8.7f,0,0,0,1) And the second one when the parameters are not actually numbers: process = route(9,8.7f,0,0,0,button(\"foo\")); will produce the following error message: ERROR : invalid route expression, parameters should be numbers : route(9,8.7f,0,0,0,button(\"foo\")) Iterative constructions Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. All par , seq , sum , prod expressions have the same form, take an identifier as first parameter, a number of iteration as an integer constant numerical expression as second parameter, then an arbitrary block-diagram as third parameter. The example code: process = par(+, 2, 8); will produce the following syntax error, since the first parameter is not an identifier: filename.dsp : xx : ERROR : syntax error, unexpected ADD, expecting IDENT The example code: process = par(i, +, 8); will produce the following error: filename.dsp : 1 : ERROR : not a constant expression of type : (0->1) : + Pattern matching errors Pattern matching mechanism allows to algorithmically create and manipulate block diagrams expressions. Pattern matching coding errors can occur at this level. Multiple symbol definition error This error happens when a symbol is defined several times in the DSP file: ERROR : [file foo.dsp : N] : multiple definitions of symbol 'foo' Since computation are done at compile time and the pattern matching language is Turing complete, even infinite loops can be produced at compile time and should be detected by the compiler. Loop detection error The following (somewhat extreme ) code: foo(x) = foo(x); process = foo; will produce the following error: ERROR : stack overflow in eval and similar kind of infinite loop errors can be produced with more complex code. [TO COMPLETE] Signal related errors Signal expressions are produced from box expressions, are type annotated and finally reduced to a normal-form. Some primitives expect their parameters to follow some constraints, like being in a specific range or being bounded for instance. The domain of mathematical functions is checked and non allowed operations are signaled. Automatic type promotion Some primitives (like route , rdtable , rwtable ...) expect arguments with an integer type, which is automatically promoted, that is the equivalent of int(exp) is internally added and is not necessary in the source code. Parameter range errors Soundfile usage error The soundfile primitive assumes the part number to stay in the [0..255] interval, so for instance the following code: process = _,0 : soundfile(\"foo.wav\", 2); will produce the following error: ERROR : out of range soundfile part number (interval(-1,1,-24) instead of interval(0,255)) in expression : length(soundfile(\"foo.wav\"),IN[0]) Delay primitive error The delay @ primitive assumes that the delay signal value is bounded, so the following expression: import(\"stdfaust.lib\"); process = @(ba.time); will produce the following error: ERROR : can't compute the min and max values of : proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1 used in delay expression : IN[0]@(proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1) (probably a recursive signal) [TO COMPLETE] Table construction errors The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The rwtable primitive can be used to implement a read/write table. Both have a size computed at compiled time The rdtable primitive assumes that the table content is produced by a processor with 0 input and one output, known at compiled time. So the following expression: process = rdtable(9, +, 4); will produce the following error, since the + is not of the correct type: ERROR : checkInit failed for type RSEVN interval(-2,2,-24) The same kind of errors will happen when read and write indexes are incorrectly defined in a rwtable primitive. Mathematical functions out of domain errors Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the -me option (see Warning messages section). Modulo primitive error The modulo % assumes that the denominator is not 0, thus the following code: process = _%0; will produce the following error: ERROR : % by 0 in IN[0] % 0 The same kind of errors will be produced for acos , asin , fmod , log10 , log , remainder and sqrt functions. FIR and backends related errors Some primitives of the language are not available in some backends. The example code: fun = ffunction(float fun(float), <fun.h>, \"\"); process = fun; compiled with the wast/wasm backends using: faust -lang wast errors.dsp will produce the following error: ERROR : calling foreign function 'fun' is not allowed in this compilation mode and the same kind of errors would happen also with foreign variables or constants. [TO COMPLETE] Compiler option errors All compiler options cannot be used with all backends. Moreover, some compiler options can not be combined. These will typically trigger errors, before any compilation actually begins. [TO COMPLETE] Warning messages Warning messages do not stop the compilation process, but allow to get usefull informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Error Messages"},{"location":"manual/errors/#error-messages","text":"Error messages are typically displayed in the form of compiler errors. They occur when the code cannot be successfully compiled, and typically indicate issues such as syntax errors or semantic errors. They can occur at different stages in the compilation process, possibly with the file and line number where the error occurred (when this information can be retrieved), as well as a brief description of the error. The compiler is organized in several stages: starting from the DSP source code, the parser builds an internal memory representation of the source program (typically known as an Abstract Source Tree ) made here of primitives in the Box language . A first class of errors messages are known as syntax error messages, like missing the ; character to end a line, etc. the next step is to evaluate the definition of process programe entry point. This step is basically a \u03bb-calculus interpreter with a strict evaluation. The result is \u201dflat\u201d block-diagram where everything have been expanded. The resulting block is type annoatetd to discover its number of inputs and outputs. the \u201dflat\u201d block-diagram is then translated the Signal language where signals as conceptually infinite streams of samples or control values. The box language actually implements the Faust Block Diagram Algebra , and not following the connections rules will trigger a second class of errors messages, the box connection errors . Other errors can be produced at this stage when parameters for some primitives are not of the correct type. the pattern matching meta language allows to algorithmically create and manipulate block diagrams expressions. So a third class of pattern matching coding errors can occur at this level. signal expressions are optimized, type annotated (to associate an integer or real type with each signal, but also discovering when signals are to be computed: at init time, control-rate or sample-rate..) to produce a so-called normal-form . A fourth class of parameter range errors or typing errors can occur at this level, like using delays with a non-bounded size, etc. signal expressions are then converted in FIR (Faust Imperative Representation), a representation for state based computation (memory access, arithmetic computations, control flow, etc.), to be converted into the final target language (like C/C++, LLVM IR, Rust, WebAssembly, etc.). A fifth class of backend errors can occur at this level, like non supported compilation options for a given backend, etc. Note that the current error messages system is still far from perfect, usually when the origin of the error in the DSP source cannot be properly traced. In this case the file and line number where the error occurred are not displayed, but an internal description of the expression (as a Box of a Signal) is printed.","title":"Error messages"},{"location":"manual/errors/#syntax-errors","text":"Those errors happen when the language syntax is not respected. Here are some examples. The following program: box1 = 1 box2 = 2; process = box1,box2; will produce the following error message: errors.dsp : 2 : ERROR : syntax error, unexpected IDENT It means that an unexpected identifier as been found line 2 of the file test.dsp. Usually, this error is due to the absence of the semi-column ; at the end of the previous line. The following program: t1 = _~(+(1); 2 process = t1 / 2147483647; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF The parser finds the end of the definition ( ; ) while searching a closing right parenthesis. The following program: process = ffunction; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF, expecting LPAR The parser was expecting a left parenthesis. It identified a keyword of the language that requires arguments. The following program: process = +)1); will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected RPAR The wrong parenthesis has been used. The following program: process = <:+; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected SPLIT The <: split operator is not correctly used, and should have been written process = _<:+; . The following program: process = foo; will produce the following error message: errors.dsp : 1 : ERROR : undefined symbol : foo This happens when an undefined name is used.","title":"Syntax errors"},{"location":"manual/errors/#box-connection-errors","text":"Diagram expressions express how block expressions can be combined to create new ones. The connection rules are precisely defined for each of them and have to be followed for the program to be correct. Remember the operator priority when writing more complex expressions.","title":"Box connection errors"},{"location":"manual/errors/#the-five-connections-rules","text":"A second category of error messages is returned when block expressions are not correctly connected.","title":"The five connections rules"},{"location":"manual/errors/#parallel-connection","text":"Combining two blocks A and B in parallel can never produce a box connection error since the 2 blocks are placed one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B .","title":"Parallel connection"},{"location":"manual/errors/#sequencial-connection-error","text":"Combining two blocks A and B in sequence will produce a box connection error if outputs(A) != inputs(B) . So for instance the following program: A = _,_; B = _,_,_; process = A : B; will produce the following error message: ERROR : sequential composition A:B The number of outputs [2] of A must be equal to the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Sequencial connection error"},{"location":"manual/errors/#split-connection-error","text":"Combining two blocks A and B with the split composition will produce a box connection error if the number of inputs of B is not a multiple of the number of outputs of A . So for instance the following program: A = _,_; B = _,_,_; process = A <: B; will produce the following error message: ERROR : split composition A<:B The number of outputs [2] of A must be a divisor of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Split connection error"},{"location":"manual/errors/#merge-connection-error","text":"Combining two blocks A and B with the merge composition will produce a box connection error if the number of outputs of A is not a multiple of the number of inputs of B . So for instance the following program: A = _,_; B = _,_,_; process = A :> B; will produce the following error message: ERROR : merge composition A:>B The number of outputs [2] of A must be a multiple of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Merge connection error"},{"location":"manual/errors/#recursive-connection-error","text":"Combining two blocks A and B with the recursive composition will produce a box connection error if the number of outputs of A is less than the number of inputs of B , or the number of outputs of B is more than the number of inputs of A (that is the following \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) connection rule is not respected). So for instance the following program: A = _,_; B = _,_,_; process = A ~ B; will produce the following error message: ERROR : recursive composition A~B The number of outputs [2] of A must be at least the number of inputs [3] of B. The number of inputs [2] of A must be at least the number of outputs [3] of B. Here A = _,_; has 2 inputs and 2 outputs while B = _,_,_; has 3 inputs and 3 outputs","title":"Recursive connection error"},{"location":"manual/errors/#route-connection-errors","text":"More complex routing between blocks can also be described using the route primitive. Two different errors can be produced in case of incorrect coding: process = route(+,8.7,(0,0),(0,1)); will produce the following error message: ERROR : invalid route expression, first two parameters should be blocks producing a value, third parameter a list of input/output pairs : route(+,8.7f,0,0,0,1) And the second one when the parameters are not actually numbers: process = route(9,8.7f,0,0,0,button(\"foo\")); will produce the following error message: ERROR : invalid route expression, parameters should be numbers : route(9,8.7f,0,0,0,button(\"foo\"))","title":"Route connection errors"},{"location":"manual/errors/#iterative-constructions","text":"Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. All par , seq , sum , prod expressions have the same form, take an identifier as first parameter, a number of iteration as an integer constant numerical expression as second parameter, then an arbitrary block-diagram as third parameter. The example code: process = par(+, 2, 8); will produce the following syntax error, since the first parameter is not an identifier: filename.dsp : xx : ERROR : syntax error, unexpected ADD, expecting IDENT The example code: process = par(i, +, 8); will produce the following error: filename.dsp : 1 : ERROR : not a constant expression of type : (0->1) : +","title":"Iterative constructions"},{"location":"manual/errors/#pattern-matching-errors","text":"Pattern matching mechanism allows to algorithmically create and manipulate block diagrams expressions. Pattern matching coding errors can occur at this level.","title":"Pattern matching errors"},{"location":"manual/errors/#multiple-symbol-definition-error","text":"This error happens when a symbol is defined several times in the DSP file: ERROR : [file foo.dsp : N] : multiple definitions of symbol 'foo' Since computation are done at compile time and the pattern matching language is Turing complete, even infinite loops can be produced at compile time and should be detected by the compiler.","title":"Multiple symbol definition error"},{"location":"manual/errors/#loop-detection-error","text":"The following (somewhat extreme ) code: foo(x) = foo(x); process = foo; will produce the following error: ERROR : stack overflow in eval and similar kind of infinite loop errors can be produced with more complex code. [TO COMPLETE]","title":"Loop detection error"},{"location":"manual/errors/#signal-related-errors","text":"Signal expressions are produced from box expressions, are type annotated and finally reduced to a normal-form. Some primitives expect their parameters to follow some constraints, like being in a specific range or being bounded for instance. The domain of mathematical functions is checked and non allowed operations are signaled.","title":"Signal related errors"},{"location":"manual/errors/#automatic-type-promotion","text":"Some primitives (like route , rdtable , rwtable ...) expect arguments with an integer type, which is automatically promoted, that is the equivalent of int(exp) is internally added and is not necessary in the source code.","title":"Automatic type promotion"},{"location":"manual/errors/#parameter-range-errors","text":"","title":"Parameter range errors"},{"location":"manual/errors/#soundfile-usage-error","text":"The soundfile primitive assumes the part number to stay in the [0..255] interval, so for instance the following code: process = _,0 : soundfile(\"foo.wav\", 2); will produce the following error: ERROR : out of range soundfile part number (interval(-1,1,-24) instead of interval(0,255)) in expression : length(soundfile(\"foo.wav\"),IN[0])","title":"Soundfile usage error"},{"location":"manual/errors/#delay-primitive-error","text":"The delay @ primitive assumes that the delay signal value is bounded, so the following expression: import(\"stdfaust.lib\"); process = @(ba.time); will produce the following error: ERROR : can't compute the min and max values of : proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1 used in delay expression : IN[0]@(proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1) (probably a recursive signal) [TO COMPLETE]","title":"Delay primitive error"},{"location":"manual/errors/#table-construction-errors","text":"The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The rwtable primitive can be used to implement a read/write table. Both have a size computed at compiled time The rdtable primitive assumes that the table content is produced by a processor with 0 input and one output, known at compiled time. So the following expression: process = rdtable(9, +, 4); will produce the following error, since the + is not of the correct type: ERROR : checkInit failed for type RSEVN interval(-2,2,-24) The same kind of errors will happen when read and write indexes are incorrectly defined in a rwtable primitive.","title":"Table construction errors"},{"location":"manual/errors/#mathematical-functions-out-of-domain-errors","text":"Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the -me option (see Warning messages section).","title":"Mathematical functions out of domain errors"},{"location":"manual/errors/#modulo-primitive-error","text":"The modulo % assumes that the denominator is not 0, thus the following code: process = _%0; will produce the following error: ERROR : % by 0 in IN[0] % 0 The same kind of errors will be produced for acos , asin , fmod , log10 , log , remainder and sqrt functions.","title":"Modulo primitive error"},{"location":"manual/errors/#fir-and-backends-related-errors","text":"Some primitives of the language are not available in some backends. The example code: fun = ffunction(float fun(float), <fun.h>, \"\"); process = fun; compiled with the wast/wasm backends using: faust -lang wast errors.dsp will produce the following error: ERROR : calling foreign function 'fun' is not allowed in this compilation mode and the same kind of errors would happen also with foreign variables or constants. [TO COMPLETE]","title":"FIR and backends related errors"},{"location":"manual/errors/#compiler-option-errors","text":"All compiler options cannot be used with all backends. Moreover, some compiler options can not be combined. These will typically trigger errors, before any compilation actually begins. [TO COMPLETE]","title":"Compiler option errors"},{"location":"manual/errors/#warning-messages","text":"Warning messages do not stop the compilation process, but allow to get usefull informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Warning messages"},{"location":"manual/faq/","text":"Frequently Asked Questions When to use int or float cast ? The Signal Processor Semantic section explains what a Faust program describes. In particular Faust considers two type of signals: integer signals and floating point signals . Mathematical operations either occur in the domain of integer numbers, or in the domain of floating point numbers, depending of their types, read here . Using explicit int cast or float cast may be needed to force a given computation to be done in the correct number domain. Some language primitives (like par , seq , route , soundfile , etc.) assume that their parameters are Constant Numerical Expressions of the integer type. In this case the compiler automatically does type promotion and there is no need to use int cast to have the argument be of the integer type (note that an uneeded cast will simply be ignored and will not add uneeded computation in the generated code). User interface items produce floating point signals . Depending of their use later in the computed expression, using explicit int cast may be needed also to force a given computation to be done in the correct number domain. Does select2 behaves as a standard C/C++ like if ? The short answer is no , select2 doesn't behave like the if-then-else of a traditional programming language, nor does ba.if of the standard library. To understand why, think of select2 as the tuner of a radio, it selects what you listen, but does not prevent the various radio stations from broadcasting. Actually, select2 could be easily redefined in Faust as: select2(i, x, y) = (1-i) * x + i * y; Strict vs Lazy semantics In computer science terminology, select2(i,x,y) has so-called strict semantics. This means that its three arguments i , x , y are always evaluated before select2 itself is executed, in other words, even if x or y is not selected. The standard C/C++ if-then-else has lazy semantics. The condition is always executed, but depending of the value of the condition , only the then or the else branch is executed. The strict semantics of select2 means that you cannot use it to prevent a division by 0 in an expression, or the square root of a negative number, etc... For example, the following code will not prevent a division by 0 error: select2(x == 0, 1/x, 10000); You cannot use ba.if either because it is implemented using select2 and has the same strict semantics. Therefore the following code will not prevent a division by 0 error: ba.if(x == 0, 10000, 1/x); But things are a little bit more complex... Concerning the way select2 is compiled by the Faust compiler, the strict semantic is always preserved. In particular, the type system flags problematic expressions and the stateful parts are always placed outside the if. For instance the DSP code: process = button(\"choose\"), (*(3) : +~_), (*(7):+~_) : select2; is compiled as the following C++ code, where fRec0[0] and fRec1[0] contains the computation of each branch: for (int i = 0; (i < count); i = (i + 1)) { fRec0[0] = (fRec0[1] + (3.0f * float(input0[i]))); fRec1[0] = (fRec1[1] + (7.0f * float(input1[i]))); output0[i] = FAUSTFLOAT((iSlow0 ? fRec1[0] : fRec0[0])); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } For code optimization strategies, the generated code is not fully strict on select2 . When Faust produces C++ code, the C++ compiler can decide to avoid the execution of the stateless part of the signal that is not selected (and not needed elsewhere). This doesn't change the semantics of the output signal, but it changes the strictness of the code if a division by 0 would have been executed in the stateless part. When stateless expressions are used, they are by default generated using a non-strict conditional expression. For instance the following DSP code: process = select2((+(1)~_)%10, sin:cos:sin:cos, cos:sin:cos:sin); is compiled in C/C++ as: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))) : std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))))); iRec0[1] = iRec0[0]; } where only one of the then or else branch will be effectively computed, thus saving CPU. If computing both branches is really desired, the -sts (--strict-select) option can be used to force their computation by putting them in local variables, as shown in the following generated with -sts code version of the same DSP code: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; float fThen0 = std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))); float fElse0 = std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))); output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? fElse0 : fThen0)); iRec0[1] = iRec0[0]; } to therefore preserve the strict semantic, even if a non-strict (cond) ? then : else form is used to produce the result of the select2 expression. This can be helpful for debugging purposes like testing if there is no division by 0, or producing INF or NaN values. The interp-tracer can be used for that by adding the -sts option. So again remember that select2 cannot be used to avoid computing something . For computations that need to avoid some values or ranges (like doing val/0 that would return INF , or log of a negative value that would return NaN ), the solution is to use min and max to force the arguments to be in the correct domain of values. For example, to avoid division by 0, you can write 1/max(ma.EPSILON, x) . Note that select2 is also typically used to compute rdtable/rwtable access indexes. In this case computing an array out-of-bound index, if is not used later on, is not a problem. What properties does the Faust compiler and generated code have ? [WIP] Compiler The compiler itself is turing complete because it contains a pattern matching meta-programming model. Thus a Faust DSP program can loop at compile time. For instance the following: foo = foo; process = foo; will loop and hopefully end with the message: ERROR : after 400 evaluation steps, the compiler has detected an endless evaluation cycle of 2 steps because the compiler contains an infinite loop detection heuristic. Generated code The generated code computes the sample in a finite number of operations, thus a DSP program that would loop infinitely cannot be written. It means the generated code is not turing complete. This is of course a limitation because certain classes of algorithms cannot be expressed ( TODO : Newton approximation used in diode VA model). But on the contrary it gives a strong garanty on the upper bound of CPU cost that is quite interesting to have when deploying a program in a real-time audio context. Memory footprint The DSP memory footprint is perfectly known at compile time, so the generated code always consume a finite amount of memory. Moreover the standard deployement model is to allocate the DSP a load time, init it with a given sample-rate, then execute the DSP code, be repeatedly calling the compute function to process audio buffers. CPU footprint Since the generated code computes the sample in a finite number of operations, the CPU use has an upper bound which is a very helpful property when deploying a program in a real-time audio context. Read the Does select2 behaves as a standard C/C++ like if ? for some subtle issues concerning the select2 primitive. Pattern matching and lists Strictly speaking, there are no lists in Faust. For example the expression () or NIL in Lisp, which indicates an empty list, does not exist in Faust. Similarly, the distinction in Lisp between the number 3 and the list with only one element (3) does not exist in Faust. However, list operations can be simulated (in part) using the parallel binary composition operation , and pattern matching. The parallel composition operation is right-associative. This means that the expression (1,2,3,4) is just a simplified form of the fully parenthesized expression (1,(2,(3,4))) . The same is true for (1,2,(3,4)) which is also a simplified form of the same fully parenthesized expression (1,(2,(3,4))) . You can think of pattern-matching as always being done on fully parenthesized expressions. Therefore no Faust function can ever distinguish (1,2,3,4) from (1,2,(3,4)) , because they represent the same fully parenthesized expression (1,(2,(3,4))) . This is why ba.count( ((1,2), (3,4), (5,6)) ) is not 3 but 4, and also why ba.count( ((1,2), ((3,4),5,6)) ) is not 2 but 4. Explanation: in both cases the fully parenthesized expression is ( (1,2),((3,4),(5,6)) ) . The definition of ba.count being: count((x,y)) = 1 + count(y); // rule R1 count(x) = 1; // rule R2 we have: ba.count( ((1,2),((3,4),(5,6))) ) -R1-> 1 + ba.count( ((3,4),(5,6)) ) -R1-> 1 + 1 + ba.count( (5,6) ) -R1-> 1 + 1 + 1 + ba.count( 6 ) -R2-> 1 + 1 + 1 + 1 Please note that pattern matching is not limited to parallel composition, the other composition operators (<: : :> ~) can be used too. What is the situation about Faust compiler licence and the deployed code? Q: Does the Faust license (GPL) apply somehow to the code exports that it produces as well? Or can the license of the exported code be freely chosen such that one could develop commercial software (e.g. VST plug-ins) using Faust? A: You can freely use Faust to develop commercial software. The GPL license of the compiler doesn't apply to the code generated by the compiler. The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use. Surprising effects of vgroup/hgroup on how controls and parameters work User interface widget primitives like button , vslider/hslider , vbargraph/hbargraph allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hiearchical manner using vgroup/hgroup/tgroup primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. Widgets that have the same path in the hiearchical structure will correspond to a same controller and will appear once in the GUI. For instance the following DSP code does not contain any explicit grouping mechanism: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = os.osc(freq1) + os.square(freq2), os.osc(freq1) + os.triangle(freq2); Shared freq1 and freq2 controllers So even if freq1 and freq2 controllers are used as parameters at four different places, freq1 used in os.osc(freq1) and os.square(freq1) will have the same path (like /foo/Freq1 ), be associated to a unique controller, and will finally appear once in the GUI. And this is the same mecanism for freq2 . Now if some grouping mecanism is used to better control the UI rendering, as in the following DSP code: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); The freq1 and freq2 controllers now don't have the same path in each group (like /foo/Voice1/Freq1 and /foo/Voice1/Freq2 in the first group, and /foo/Voice2/Freq1 and /foo/Voice2/Freq2 in the second group), and so four separated controllers and UI items are finally created. Four freq1 and freq2 controllers Using the relative pathname as explained in Labels as Pathnames possibly allows us to move freq1 one step higher in the hierarchical structure, thus having again a unique path (like /foo/Freq1 ) and controller: import(\"stdfaust.lib\"); freq1 = hslider(\"../Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); freq1 moved one step higher in the hierarchical structure Note that the name for a given hgroup , vgroup , or tgroup can be used more than once, and they will be merged. This can be useful when you want to define different names for different widget signals, but still want to group them. For example, this pattern can be used to separate a synth's UI design from the implementation of the synth's DSP: import (\"stdfaust.lib\"); synth(foo, bar, baz) = os.osc(foo+bar+baz); synth_ui = synth(foo, bar, baz) with { ui(x) = hgroup(\"Synth\", x); leftcol(x) = ui(vgroup(\"[0]foobar\", x)); foo = leftcol(hslider(\"[0]foo\", 100, 20, 1000, 1)); bar = leftcol(hslider(\"[1]bar\", 100, 20, 1000, 1)); baz = ui(vslider(\"[1]baz\", 100, 20, 1000, 1)); }; process = synth_ui; naming and grouping What are the rules used for partial application ? Assuming F is not an abstraction and has n+m inputs and A has n outputs, then we have the rewriting rule F(A) ==> A,bus(m):F (with bus(1) = _ and bus(n+1) = _,bus(n)) There is an exception when F is a binary operation like +,-,/,* . In this case, the rewriting rule is /(3) ==> _,3:/ . In other words, when we apply only one argument, it is the second one. Control rate versus audio rate Question: I have a question about sample rate / control rate issues. I have a Faust code that takes channel pressure messages from my keyboard as input, therefore at control rate, and outputs an expression signal at sample rate. The first part of the code can run at control rate, but I want to force it to run at sample rate (otherwise unwanted behavior will appear). Is there a simple way of forcing my pressure signal to be at sample rate (without making a smooth which may also result in unwanted behavior) . Answer: the ba.kr2ar function can be used for that purpose.","title":"Frequently Asked Questions"},{"location":"manual/faq/#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"manual/faq/#when-to-use-int-or-float-cast","text":"The Signal Processor Semantic section explains what a Faust program describes. In particular Faust considers two type of signals: integer signals and floating point signals . Mathematical operations either occur in the domain of integer numbers, or in the domain of floating point numbers, depending of their types, read here . Using explicit int cast or float cast may be needed to force a given computation to be done in the correct number domain. Some language primitives (like par , seq , route , soundfile , etc.) assume that their parameters are Constant Numerical Expressions of the integer type. In this case the compiler automatically does type promotion and there is no need to use int cast to have the argument be of the integer type (note that an uneeded cast will simply be ignored and will not add uneeded computation in the generated code). User interface items produce floating point signals . Depending of their use later in the computed expression, using explicit int cast may be needed also to force a given computation to be done in the correct number domain.","title":"When to use int or float cast ?"},{"location":"manual/faq/#does-select2-behaves-as-a-standard-cc-like-if","text":"The short answer is no , select2 doesn't behave like the if-then-else of a traditional programming language, nor does ba.if of the standard library. To understand why, think of select2 as the tuner of a radio, it selects what you listen, but does not prevent the various radio stations from broadcasting. Actually, select2 could be easily redefined in Faust as: select2(i, x, y) = (1-i) * x + i * y;","title":"Does select2 behaves as a standard C/C++ like if ?"},{"location":"manual/faq/#strict-vs-lazy-semantics","text":"In computer science terminology, select2(i,x,y) has so-called strict semantics. This means that its three arguments i , x , y are always evaluated before select2 itself is executed, in other words, even if x or y is not selected. The standard C/C++ if-then-else has lazy semantics. The condition is always executed, but depending of the value of the condition , only the then or the else branch is executed. The strict semantics of select2 means that you cannot use it to prevent a division by 0 in an expression, or the square root of a negative number, etc... For example, the following code will not prevent a division by 0 error: select2(x == 0, 1/x, 10000); You cannot use ba.if either because it is implemented using select2 and has the same strict semantics. Therefore the following code will not prevent a division by 0 error: ba.if(x == 0, 10000, 1/x);","title":"Strict vs Lazy semantics"},{"location":"manual/faq/#but-things-are-a-little-bit-more-complex","text":"Concerning the way select2 is compiled by the Faust compiler, the strict semantic is always preserved. In particular, the type system flags problematic expressions and the stateful parts are always placed outside the if. For instance the DSP code: process = button(\"choose\"), (*(3) : +~_), (*(7):+~_) : select2; is compiled as the following C++ code, where fRec0[0] and fRec1[0] contains the computation of each branch: for (int i = 0; (i < count); i = (i + 1)) { fRec0[0] = (fRec0[1] + (3.0f * float(input0[i]))); fRec1[0] = (fRec1[1] + (7.0f * float(input1[i]))); output0[i] = FAUSTFLOAT((iSlow0 ? fRec1[0] : fRec0[0])); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } For code optimization strategies, the generated code is not fully strict on select2 . When Faust produces C++ code, the C++ compiler can decide to avoid the execution of the stateless part of the signal that is not selected (and not needed elsewhere). This doesn't change the semantics of the output signal, but it changes the strictness of the code if a division by 0 would have been executed in the stateless part. When stateless expressions are used, they are by default generated using a non-strict conditional expression. For instance the following DSP code: process = select2((+(1)~_)%10, sin:cos:sin:cos, cos:sin:cos:sin); is compiled in C/C++ as: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))) : std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))))); iRec0[1] = iRec0[0]; } where only one of the then or else branch will be effectively computed, thus saving CPU. If computing both branches is really desired, the -sts (--strict-select) option can be used to force their computation by putting them in local variables, as shown in the following generated with -sts code version of the same DSP code: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; float fThen0 = std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))); float fElse0 = std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))); output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? fElse0 : fThen0)); iRec0[1] = iRec0[0]; } to therefore preserve the strict semantic, even if a non-strict (cond) ? then : else form is used to produce the result of the select2 expression. This can be helpful for debugging purposes like testing if there is no division by 0, or producing INF or NaN values. The interp-tracer can be used for that by adding the -sts option. So again remember that select2 cannot be used to avoid computing something . For computations that need to avoid some values or ranges (like doing val/0 that would return INF , or log of a negative value that would return NaN ), the solution is to use min and max to force the arguments to be in the correct domain of values. For example, to avoid division by 0, you can write 1/max(ma.EPSILON, x) . Note that select2 is also typically used to compute rdtable/rwtable access indexes. In this case computing an array out-of-bound index, if is not used later on, is not a problem.","title":"But things are a little bit more complex..."},{"location":"manual/faq/#what-properties-does-the-faust-compiler-and-generated-code-have-wip","text":"","title":"What properties does the Faust compiler and generated code have ? [WIP]"},{"location":"manual/faq/#compiler","text":"The compiler itself is turing complete because it contains a pattern matching meta-programming model. Thus a Faust DSP program can loop at compile time. For instance the following: foo = foo; process = foo; will loop and hopefully end with the message: ERROR : after 400 evaluation steps, the compiler has detected an endless evaluation cycle of 2 steps because the compiler contains an infinite loop detection heuristic.","title":"Compiler"},{"location":"manual/faq/#generated-code","text":"The generated code computes the sample in a finite number of operations, thus a DSP program that would loop infinitely cannot be written. It means the generated code is not turing complete. This is of course a limitation because certain classes of algorithms cannot be expressed ( TODO : Newton approximation used in diode VA model). But on the contrary it gives a strong garanty on the upper bound of CPU cost that is quite interesting to have when deploying a program in a real-time audio context.","title":"Generated code"},{"location":"manual/faq/#memory-footprint","text":"The DSP memory footprint is perfectly known at compile time, so the generated code always consume a finite amount of memory. Moreover the standard deployement model is to allocate the DSP a load time, init it with a given sample-rate, then execute the DSP code, be repeatedly calling the compute function to process audio buffers.","title":"Memory footprint"},{"location":"manual/faq/#cpu-footprint","text":"Since the generated code computes the sample in a finite number of operations, the CPU use has an upper bound which is a very helpful property when deploying a program in a real-time audio context. Read the Does select2 behaves as a standard C/C++ like if ? for some subtle issues concerning the select2 primitive.","title":"CPU footprint"},{"location":"manual/faq/#pattern-matching-and-lists","text":"Strictly speaking, there are no lists in Faust. For example the expression () or NIL in Lisp, which indicates an empty list, does not exist in Faust. Similarly, the distinction in Lisp between the number 3 and the list with only one element (3) does not exist in Faust. However, list operations can be simulated (in part) using the parallel binary composition operation , and pattern matching. The parallel composition operation is right-associative. This means that the expression (1,2,3,4) is just a simplified form of the fully parenthesized expression (1,(2,(3,4))) . The same is true for (1,2,(3,4)) which is also a simplified form of the same fully parenthesized expression (1,(2,(3,4))) . You can think of pattern-matching as always being done on fully parenthesized expressions. Therefore no Faust function can ever distinguish (1,2,3,4) from (1,2,(3,4)) , because they represent the same fully parenthesized expression (1,(2,(3,4))) . This is why ba.count( ((1,2), (3,4), (5,6)) ) is not 3 but 4, and also why ba.count( ((1,2), ((3,4),5,6)) ) is not 2 but 4. Explanation: in both cases the fully parenthesized expression is ( (1,2),((3,4),(5,6)) ) . The definition of ba.count being: count((x,y)) = 1 + count(y); // rule R1 count(x) = 1; // rule R2 we have: ba.count( ((1,2),((3,4),(5,6))) ) -R1-> 1 + ba.count( ((3,4),(5,6)) ) -R1-> 1 + 1 + ba.count( (5,6) ) -R1-> 1 + 1 + 1 + ba.count( 6 ) -R2-> 1 + 1 + 1 + 1 Please note that pattern matching is not limited to parallel composition, the other composition operators (<: : :> ~) can be used too.","title":"Pattern matching and lists"},{"location":"manual/faq/#what-is-the-situation-about-faust-compiler-licence-and-the-deployed-code","text":"Q: Does the Faust license (GPL) apply somehow to the code exports that it produces as well? Or can the license of the exported code be freely chosen such that one could develop commercial software (e.g. VST plug-ins) using Faust? A: You can freely use Faust to develop commercial software. The GPL license of the compiler doesn't apply to the code generated by the compiler. The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use.","title":"What is the situation about Faust compiler licence and the deployed code?"},{"location":"manual/faq/#surprising-effects-of-vgrouphgroup-on-how-controls-and-parameters-work","text":"User interface widget primitives like button , vslider/hslider , vbargraph/hbargraph allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hiearchical manner using vgroup/hgroup/tgroup primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. Widgets that have the same path in the hiearchical structure will correspond to a same controller and will appear once in the GUI. For instance the following DSP code does not contain any explicit grouping mechanism: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = os.osc(freq1) + os.square(freq2), os.osc(freq1) + os.triangle(freq2); Shared freq1 and freq2 controllers So even if freq1 and freq2 controllers are used as parameters at four different places, freq1 used in os.osc(freq1) and os.square(freq1) will have the same path (like /foo/Freq1 ), be associated to a unique controller, and will finally appear once in the GUI. And this is the same mecanism for freq2 . Now if some grouping mecanism is used to better control the UI rendering, as in the following DSP code: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); The freq1 and freq2 controllers now don't have the same path in each group (like /foo/Voice1/Freq1 and /foo/Voice1/Freq2 in the first group, and /foo/Voice2/Freq1 and /foo/Voice2/Freq2 in the second group), and so four separated controllers and UI items are finally created. Four freq1 and freq2 controllers Using the relative pathname as explained in Labels as Pathnames possibly allows us to move freq1 one step higher in the hierarchical structure, thus having again a unique path (like /foo/Freq1 ) and controller: import(\"stdfaust.lib\"); freq1 = hslider(\"../Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); freq1 moved one step higher in the hierarchical structure Note that the name for a given hgroup , vgroup , or tgroup can be used more than once, and they will be merged. This can be useful when you want to define different names for different widget signals, but still want to group them. For example, this pattern can be used to separate a synth's UI design from the implementation of the synth's DSP: import (\"stdfaust.lib\"); synth(foo, bar, baz) = os.osc(foo+bar+baz); synth_ui = synth(foo, bar, baz) with { ui(x) = hgroup(\"Synth\", x); leftcol(x) = ui(vgroup(\"[0]foobar\", x)); foo = leftcol(hslider(\"[0]foo\", 100, 20, 1000, 1)); bar = leftcol(hslider(\"[1]bar\", 100, 20, 1000, 1)); baz = ui(vslider(\"[1]baz\", 100, 20, 1000, 1)); }; process = synth_ui; naming and grouping","title":"Surprising effects of vgroup/hgroup on how controls and parameters work"},{"location":"manual/faq/#what-are-the-rules-used-for-partial-application","text":"Assuming F is not an abstraction and has n+m inputs and A has n outputs, then we have the rewriting rule F(A) ==> A,bus(m):F (with bus(1) = _ and bus(n+1) = _,bus(n)) There is an exception when F is a binary operation like +,-,/,* . In this case, the rewriting rule is /(3) ==> _,3:/ . In other words, when we apply only one argument, it is the second one.","title":"What are the rules used for partial application ?"},{"location":"manual/faq/#control-rate-versus-audio-rate","text":"Question: I have a question about sample rate / control rate issues. I have a Faust code that takes channel pressure messages from my keyboard as input, therefore at control rate, and outputs an expression signal at sample rate. The first part of the code can run at control rate, but I want to force it to run at sample rate (otherwise unwanted behavior will appear). Is there a simple way of forcing my pressure signal to be at sample rate (without making a smooth which may also result in unwanted behavior) . Answer: the ba.kr2ar function can be used for that purpose.","title":"Control rate versus audio rate"},{"location":"manual/http/","text":"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 HTTPD 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 lists 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 4 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 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 is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open 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 that 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 here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge 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 the 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 Let's say 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 concatenating ?value=1 at 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 purely developed in C/C++. A proxy version of the user interface can then be built, and parameters can be \"set and get\" 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 for the access of 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\" .","title":"HTTP Support"},{"location":"manual/http/#http-support","text":"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 HTTPD 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 lists Faust's architectures providing HTTP support:","title":"HTTP Support"},{"location":"manual/http/#linux-faust-architectures-with-http-support","text":"Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt","title":"Linux Faust Architectures with HTTP Support"},{"location":"manual/http/#osx-faust-architectures-with-http-support","text":"Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt","title":"OSX Faust Architectures with HTTP Support"},{"location":"manual/http/#windows-faust-architectures-with-http-support","text":"Audio System Environment Jack Qt, Console PortAudio Qt","title":"Windows Faust Architectures with HTTP Support"},{"location":"manual/http/#a-simple-example","text":"To illustrate how HTTP support works, let's reuse our previous example, a simple monophonic audio mixer with 4 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 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 is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page presented in the figure below:","title":"A Simple Example"},{"location":"manual/http/#json-description-of-the-user-interface","text":"The communication between the application and the Web browser is based on several underlying URLs. The first one is http://localhost:5510/JSON that 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\" } ] }, ... ] } ] }","title":"JSON Description of the User Interface"},{"location":"manual/http/#querying-the-state-of-the-application","text":"Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge 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 the 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","title":"Querying the State of the Application"},{"location":"manual/http/#changing-the-value-of-a-widget","text":"Let's say 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 concatenating ?value=1 at 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.","title":"Changing the Value of a Widget"},{"location":"manual/http/#proxy-control-access-to-the-web-server","text":"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 purely developed in C/C++. A proxy version of the user interface can then be built, and parameters can be \"set and get\" 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 for the access of the remote parameters.","title":"Proxy Control Access to the Web Server"},{"location":"manual/http/#http-cheat-sheet","text":"Here is a summary of the various URLs used to interact with the application's Web server.","title":"HTTP Cheat Sheet"},{"location":"manual/http/#default-ports","text":"Port Description 5510 default TCP port used by the application's Web server 5511... alternative TCP ports","title":"Default Ports"},{"location":"manual/http/#command-line-options","text":"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","title":"Command Line Options"},{"location":"manual/http/#urls","text":"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","title":"URLs"},{"location":"manual/http/#json","text":"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\" .","title":"JSON"},{"location":"manual/introduction/","text":"Introduction What is Faust? Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. This manual gives an overview of the Faust programming language and of its features through various interactive examples. What is Faust Good For? Faust's syntax allows us to express any DSP algorithm as a block diagram. For example, + is considered as a valid function (and block) taking two arguments (signals) and returning one: Blocks can be easily connected together using the : \"connection\" composition: In that case, we add two signals together and then scale the result of this operation. Thus, Faust is perfect to implement time-domain algorithms that can be easily represented as block diagrams such as filters, waveguide physical models, virtual analog elements, etc. Faust is very concise , for example, here's the implementation of a one pole filter/integrator equivalent to y(n) = x(n) + a_{1}y(n-1) (where a_{1} is the pole): Codes generated by Faust are extremely optimized and usually more efficient that handwritten codes (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using divides instead of multiplies as they get automatically replaced by multiplies by the compiler when possible, etc. Faust is very generic and allows us to write code that will run on dozens of platforms. What is Faust Not (So) Good For? Despite all this, Faust does have some limitations. For instance, it doesn't allow for the efficient implementation of algorithms requiring multi-rates such as the FFT, convolution, etc. While there are tricks to go around this issue, we're fully aware that it is a big one and we're working as hard as possible on it. Faust's conciseness can sometimes become a problem too, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have the \"mental global picture\" of the algorithm to be implemented which in some cases can be hard. While the Faust compiler is relatively bug-free, it does have some limitations and might get stuck in some extreme cases that you will probably never encounter. If you do, shoot us an e-mail ! From here, you can jump to the Quick Start Tutorial section of this manual. Design Principles Since the beginning of its development in 2002, Faust has been guided by various design principles: Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations: : , ~ <: :> (see the section on Diagram Composition Operations for more details). Thanks to the concept of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plug-in formats without any change to the Faust code. Signal Processor Semantic A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. Faust considers two type of signals: integer signals s:\\mathbb{Z}\\rightarrow\\mathbb{Z} and floating point signals s:\\mathbb{Z}\\rightarrow\\mathbb{Q} . Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0 . The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produces an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Introduction"},{"location":"manual/introduction/#introduction","text":"","title":"Introduction"},{"location":"manual/introduction/#what-is-faust","text":"Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. This manual gives an overview of the Faust programming language and of its features through various interactive examples.","title":"What is Faust?"},{"location":"manual/introduction/#what-is-faust-good-for","text":"Faust's syntax allows us to express any DSP algorithm as a block diagram. For example, + is considered as a valid function (and block) taking two arguments (signals) and returning one: Blocks can be easily connected together using the : \"connection\" composition: In that case, we add two signals together and then scale the result of this operation. Thus, Faust is perfect to implement time-domain algorithms that can be easily represented as block diagrams such as filters, waveguide physical models, virtual analog elements, etc. Faust is very concise , for example, here's the implementation of a one pole filter/integrator equivalent to y(n) = x(n) + a_{1}y(n-1) (where a_{1} is the pole): Codes generated by Faust are extremely optimized and usually more efficient that handwritten codes (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using divides instead of multiplies as they get automatically replaced by multiplies by the compiler when possible, etc. Faust is very generic and allows us to write code that will run on dozens of platforms.","title":"What is Faust Good For?"},{"location":"manual/introduction/#what-is-faust-not-so-good-for","text":"Despite all this, Faust does have some limitations. For instance, it doesn't allow for the efficient implementation of algorithms requiring multi-rates such as the FFT, convolution, etc. While there are tricks to go around this issue, we're fully aware that it is a big one and we're working as hard as possible on it. Faust's conciseness can sometimes become a problem too, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have the \"mental global picture\" of the algorithm to be implemented which in some cases can be hard. While the Faust compiler is relatively bug-free, it does have some limitations and might get stuck in some extreme cases that you will probably never encounter. If you do, shoot us an e-mail ! From here, you can jump to the Quick Start Tutorial section of this manual.","title":"What is Faust Not (So) Good For?"},{"location":"manual/introduction/#design-principles","text":"Since the beginning of its development in 2002, Faust has been guided by various design principles: Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations: : , ~ <: :> (see the section on Diagram Composition Operations for more details). Thanks to the concept of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plug-in formats without any change to the Faust code.","title":"Design Principles"},{"location":"manual/introduction/#signal-processor-semantic","text":"A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. Faust considers two type of signals: integer signals s:\\mathbb{Z}\\rightarrow\\mathbb{Z} and floating point signals s:\\mathbb{Z}\\rightarrow\\mathbb{Q} . Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0 . The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produces an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Signal Processor Semantic"},{"location":"manual/mathdoc/","text":"Mathematical Documentation The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long). Goals of the Mathdoc There are four main goals, or uses, of the Faust mathematical documentation generator: to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler, to preserve signal processors, independently from any computer language but only under a mathematical form, to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage, to give a new teaching support, as a bridge between code and formulas for signal processing. Installation Requirements faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as Latex doesn't embed SVG directly, breqn , a Latex package to handle automatic breaking of long equations, pdflatex , to compile the Latex output file. Generating the Mathdoc The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leaves the process of generating the documentation unfinished (only the source is produced). Invoking the -mdoc Option Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with -mdoc , 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a Latex file containing the formulas, SVG files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so with all needed libraries to have a self-contained DSP), svg/ contains SVG block-diagram files, tex/ contains the generated Latex file. Invoking faust2mathdoc The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all SVG files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the Latex file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ . Automatic Documentation By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a Latex file with four sections: Equations of process , gathering all formulas needed for process , Block-diagram schema of process , showing the top-level block-diagram of process , Notice of this documentation , summing up generation and conventions information, Complete listing of the input code , listing all needed input files (including libraries). Manual Documentation You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That allows you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the Latex stuff becomes up to you! Six Tags Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive\" notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to true by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections. The mdoc Top-Level Tags The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs. In addition of the four inner tags, <mdoc></mdoc> tags accept free Latex text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the Latex packages included by Faust can be found in the file architecture/latexheader.tex . An Example of Manual Mathdoc <mdoc> \\title{<metadata>name</metadata>} \\author{<metadata>author</metadata>} \\date{\\today} \\maketitle \\begin{tabular}{ll} \\hline \\textbf{name} & <metadata>name</metadata> \\\\ \\textbf{version} & <metadata>version</metadata> \\\\ \\textbf{author} & <metadata>author</metadata> \\\\ \\textbf{license} & <metadata>license</metadata> \\\\ \\textbf{copyright} & <metadata>copyright</metadata> \\\\ \\hline \\end{tabular} \\bigskip </mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; <mdoc> \\section{Presentation of the \"noise.dsp\" Faust program} This program describes a white noise generator with an interactive volume, using a random function. \\subsection{The random function} </mdoc> random = +(12345)~*(1103515245); <mdoc> The \\texttt{random} function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. <equation>random</equation> \\subsection{The noise function} </mdoc> noise = random/2147483647.0; <mdoc> The white noise then corresponds to: <equation>noise</equation> \\subsection{Just add a user interface element to play volume!} </mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); <mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: <equation>process</equation> \\section{Block-diagram schema of process} This process is illustrated on figure 1. <diagram>process</diagram> \\section{Notice of this documentation} You might be careful of certain information and naming conventions used in this documentation: <notice /> \\section{Listing of the input code} The following listing shows the input Faust code, parsed to compile this mathematical documentation. <listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> </mdoc> The -stripmdoc Option The listing of the input code contains all the mathdoc text. As it may be useless in certain cases, we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long). Localization of Mathdoc Files By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian at the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. Summary of the Mathdoc Generation Steps First, to get the full mathematical documentation done on your Faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Mathematical Documentation"},{"location":"manual/mathdoc/#mathematical-documentation","text":"The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long).","title":"Mathematical Documentation"},{"location":"manual/mathdoc/#goals-of-the-mathdoc","text":"There are four main goals, or uses, of the Faust mathematical documentation generator: to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler, to preserve signal processors, independently from any computer language but only under a mathematical form, to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage, to give a new teaching support, as a bridge between code and formulas for signal processing.","title":"Goals of the Mathdoc"},{"location":"manual/mathdoc/#installation-requirements","text":"faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as Latex doesn't embed SVG directly, breqn , a Latex package to handle automatic breaking of long equations, pdflatex , to compile the Latex output file.","title":"Installation Requirements"},{"location":"manual/mathdoc/#generating-the-mathdoc","text":"The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leaves the process of generating the documentation unfinished (only the source is produced).","title":"Generating the Mathdoc"},{"location":"manual/mathdoc/#invoking-the-mdoc-option","text":"Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with -mdoc , 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a Latex file containing the formulas, SVG files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so with all needed libraries to have a self-contained DSP), svg/ contains SVG block-diagram files, tex/ contains the generated Latex file.","title":"Invoking the -mdoc Option"},{"location":"manual/mathdoc/#invoking-faust2mathdoc","text":"The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all SVG files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the Latex file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ .","title":"Invoking faust2mathdoc"},{"location":"manual/mathdoc/#automatic-documentation","text":"By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a Latex file with four sections: Equations of process , gathering all formulas needed for process , Block-diagram schema of process , showing the top-level block-diagram of process , Notice of this documentation , summing up generation and conventions information, Complete listing of the input code , listing all needed input files (including libraries).","title":"Automatic Documentation"},{"location":"manual/mathdoc/#manual-documentation","text":"You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That allows you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the Latex stuff becomes up to you!","title":"Manual Documentation"},{"location":"manual/mathdoc/#six-tags","text":"Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive\" notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to true by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections.","title":"Six Tags"},{"location":"manual/mathdoc/#the-mdoc-top-level-tags","text":"The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs. In addition of the four inner tags, <mdoc></mdoc> tags accept free Latex text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the Latex packages included by Faust can be found in the file architecture/latexheader.tex .","title":"The mdoc Top-Level Tags"},{"location":"manual/mathdoc/#an-example-of-manual-mathdoc","text":"<mdoc> \\title{<metadata>name</metadata>} \\author{<metadata>author</metadata>} \\date{\\today} \\maketitle \\begin{tabular}{ll} \\hline \\textbf{name} & <metadata>name</metadata> \\\\ \\textbf{version} & <metadata>version</metadata> \\\\ \\textbf{author} & <metadata>author</metadata> \\\\ \\textbf{license} & <metadata>license</metadata> \\\\ \\textbf{copyright} & <metadata>copyright</metadata> \\\\ \\hline \\end{tabular} \\bigskip </mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; <mdoc> \\section{Presentation of the \"noise.dsp\" Faust program} This program describes a white noise generator with an interactive volume, using a random function. \\subsection{The random function} </mdoc> random = +(12345)~*(1103515245); <mdoc> The \\texttt{random} function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. <equation>random</equation> \\subsection{The noise function} </mdoc> noise = random/2147483647.0; <mdoc> The white noise then corresponds to: <equation>noise</equation> \\subsection{Just add a user interface element to play volume!} </mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); <mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: <equation>process</equation> \\section{Block-diagram schema of process} This process is illustrated on figure 1. <diagram>process</diagram> \\section{Notice of this documentation} You might be careful of certain information and naming conventions used in this documentation: <notice /> \\section{Listing of the input code} The following listing shows the input Faust code, parsed to compile this mathematical documentation. <listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> </mdoc>","title":"An Example of Manual Mathdoc"},{"location":"manual/mathdoc/#the-stripmdoc-option","text":"The listing of the input code contains all the mathdoc text. As it may be useless in certain cases, we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long).","title":"The -stripmdoc Option"},{"location":"manual/mathdoc/#localization-of-mathdoc-files","text":"By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian at the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work.","title":"Localization of Mathdoc Files"},{"location":"manual/mathdoc/#summary-of-the-mathdoc-generation-steps","text":"First, to get the full mathematical documentation done on your Faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Summary of the Mathdoc Generation Steps"},{"location":"manual/midi/","text":"MIDI and Polyphony Support Similarly to OSC , several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments. Configuring MIDI in Faust MIDI support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [midi:on] metadata to the standard options metadata : declare options \"[midi:on]\"; or using the -midi option in most of faust2xx scripts. MIDI control is configured in Faust using metadata in UI elements . MIDI channels from 1 to 16 can be used at reception or sending time. By convention, using the channel = 0 value (or no channel setting) means \"all channels\". That is, at reception time, MIDI messages received on all channels can be used to control a given parameter, and at sending time, the MIDI message associated to a parameter will be sent on all channels. MIDI metadata are decoded by a special architecture that parses incoming MIDI messages and updates the appropriate control parameters, or send MIDI messages when the UI elements (i.e., sliders, buttons, etc.) are moved. All MIDI configuration metadata in Faust follow the following format: [midi:xxx yyy...] This section provides a list of the most common metadata that can be used to configure of the MIDI behavior of a Faust program. Below, when a 7-bit MIDI parameter is used to drive a button or a checkbox , its maximum value (127) maps to 1 (\"on\") while its minimum value (0) maps to 0 (\"off\"). [midi:ctrl num] or [midi:ctrl num chan] Metadata The [midi:ctrl num] metadata assigns MIDI CC (control) to a specific UI element. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:ctrl num] version can receive messages on all channels, and will send on all channels. The second [midi:ctrl num chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:ctrl num chan]\",...); Where: num : the MIDI CC number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by MIDI CC 11. When CC11=0, then the frequency is 200Hz, when CC11=127, then the frequency is 1000Hz. [midi:keyon midikey] or [midi:keyon midikey chan] Metadata The [midi:keyon midikey] metadata assigns the velocity value of a key-on MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyon midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyon midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyon midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-on message is sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed. [midi:keyoff midikey] or [midi:keyoff midikey chan] Metadata The [midi:keyoff midikey] metadata assigns the velocity value of a key-off MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyoff midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyoff midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyoff midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-off message is sent. Therefore, the frequency will only be updated when MIDI key 62 is released. [midi:key midikey] or [midi:key midikey chan] Metadata The [midi:key midikey] metadata assigns the velocity value of key-on and key-off MIDI messages received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:midikey midikey] version can receive messages on all channels, and will send on all channels. The second [midi:midikey midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:key midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when key-on and key-off messages are sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed and released. [midi:keypress midikey] or [midi:keypress midikey chan] Metadata The [midi:keypress midikey] metadata assigns the pressure (after-touch) value of a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keypress midikey] version can receive messages on all channels, will send on all channels. The second [midi:keypress midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keypress midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the pressure (after-touch) values received on key 62. [midi:chanpress] or [midi:chanpress chan] Metadata The [midi:chanpress] metadata assigns the channel pressure value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:chanpress] version can receive messages on all channels, and will send on all channels. The second [midi:chanpress chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:chanpress chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the volume of a sawtooth wave oscillator is controlled by the channel pressure values. [midi:pgm] or [midi:pgm chan] Metadata The [midi:pgm] metadata assigns the program-change to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will use the UI element range. Only the values described in the UI element range will be used at reception, and can be sent. The first [midi:pgm] version can receive messages on all channels, and will send on all channels. The second [midi:pgm chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = nentry(\"foo[midi:pgm chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the instrument will be choosen in the {0,3} range. [midi:pitchwheel] or [midi:pitchwheel chan] Metadata The [midi:pitchwheel] metadata assigns the pitch-wheel value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 16383} range. When used with a button or a checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. Pitch-wheel values are typically used to control tuning, mapping the {0, 16383} MIDI range to a {-semitone, semitone} range. The ba.semi2ratio function must be used to convert semitones in a frequency multiplicative ratio. The first [midi:pitchwheel] version can receive messages on all channels, and will send on all channels. The second [midi:pitchwheel chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:pitchwheel chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the bend of a sawtooth wave oscillator is controlled by the pitch-wheel in the {-2, 2} semitone range, then converted as a frequency multiplicative ratio and multiplied by a given frequency. [midi:start] Metadata When used with a button or a checkbox, [midi:start] will trigger a value of 1 when a start MIDI message is received. Usage foo = checkbox(\"foo[midi:start]\"); [midi:stop] Metadata When used with a button or a checkbox, [midi:stop] will trigger a value of 0 when a stop MIDI message is received. Usage foo = checkbox(\"foo[midi:stop]\"); [midi:clock] Metadata When used with a button or a checkbox, [midi:clock] will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received (seen by Faust code as a square command signal, to be used to compute higher level information). Usage foo = checkbox(\"foo[midi:clock]\"); MIDI Sync MIDI clock-based synchronization can be used to slave a given Faust program using the metadata presented in the 3 past sections. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: MIDI Polyphony Support Polyphony is conveniently handled in Faust directly by Faust Architectures. Note that programming polyphonic instrument completely from scratch in Faust and without relying on architectures is also possible. In fact, this feature is indispensable if complex signal interactions between the different voices have to be described (like sympathetic strings resonance in a physical model, etc.). However, since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocation and control MIDI messages decoding and mapping. Polyphony support can be added to any Faust program (as long as the target architecture supports it) simply by adding the [nvoices:n] metadata to the standard option metadata where n is the maximum number of voices of polyphony to be allocated: declare options \"[midi:on][nvoices:12]\"; Standard Polyphony Parameters Most Faust architectures allow for the implementation of polyphonic instruments simply by using a set of \"standard user interface names.\" Hence, any Faust program declaring the freq (or key) , gain (or vel or velocity) , and gate parameter is polyphony-compatible. These 3 parameters are directly associated to key-on and key-off events and have the following behavior: When a key-on event is received, gate will be set to 1. Inversely, when a key-off event is received, gate will be set to 0. Therefore, gate is typically used to trigger an envelope, etc. freq is a frequency in Hz computed automatically in function of the value of the pitch contained in a key-on or a key-off message. Alternatively key can be used to get the raw MIDI pitch and describe the pitch to Hz conversion in the DSP code itself (for instance to implement alternative tunings). gain is a linear gain (value between 0-1) computed in function of the velocity value contained in a key-on or a key-off message. Alternatively vel or velocity can be used to get the raw MIDI velocity and describe the velocity to gain conversion in the DSP code itself (for instance to implement alternative velocity curves). Example: Simple Polyphonic Synthesizer In the following example, the standard freq , gain , and gate parameters are used to implement a simple polyphonic synth. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). In the next example, the standard key , gain , and gate parameters are used to implement a simple polyphonic synth with alternate tuning. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). The previous example can be slightly improved by adding an envelope generator and controlling it with gain and gate : Warning: Note that all the active voices of polyphony are added together without scaling! This means that the previous example will likely click if several voices are played at the same time. It is the Faust programmer's responsibility to take this into account in his code. For example, assuming that the number of active voices will always be smaller or equal to 4, the following safeguard could be added to the previous example: process = os.sawtooth(freq)*envelope : /(4); Configuring and Activating Polyphony Polyphony can be activated manually in some Faust architectures using an option/flag during compilation (e.g., typically -poly or -nvoices <num> in the faust2xx scripts). That's also how the Faust Online IDE works where a button can be used to turn polyphony on or off. However, the most standard way to activate polyphony in Faust is to declare the [nvoices:n] metadata which allows us to specify the maximum number of voices of polyphony ( n ) that will be allocated in the generated program. For example, the Faust program from the previous section could be modified such that: which when compiled running (for example): faust2jaqt faustProgram.dsp will generate a MIDI-controllable polyphonic synthesizer. Audio Effects and Polyphonic Synthesizer While audio audio effects can be added directly to the process line of a Faust synthesizer, for example: process = os.sawtooth(freq)*envelope : reverb; it is not a good practice since a new instance of that effect will be created for each active voice of polyphony. The main consequence of this would be an increased CPU cost. Similarly to process , Faust allows for the declaration of an effect line, which identifies an audio effect to be connected to the output of the polyphonic synthesizer. For example, a simple reverb can be added to the previous example simply by writing: In this case, the polyphonic part is based on process and a single instance of the effect defined in effect will be created and shared by all voices. The architecture machinery then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them. Here dm.zita_light is a stereo effect, the mono output of the os.sawtooth(freq)*envelope expression can be split into 2 signals (but would be splitted automatically if kept as a mono output). Also, be aware that this type of construction wont be visible in the corresponding block diagram that will only show what's implemented in the process line. Polyphony and Continuous Pitch Key-on and key-off MIDI messages only send the \"base pitch\" of the instance of a note. Hence, if only the freq standard parameter is used to control the frequency of the synthesizer, its pitch will always be \"quantized\" to the nearest semitone. In order to be able to do glissandi, vibrato, etc., a variable associated to the pitch-wheel needs to be declared and must interact with the \"base frequency\" value retrieved from freq as such: f = hslider(\"freq\",300,50,2000,0.01); bend = ba.semi2ratio(hslider(\"bend[midi:pitchwheel]\",0,-2,2,0.01)); freq = f*bend; // the \"final\" freq parameter to be used The bend variable is controlled by the pitch-wheel thanks to [midi:pitchwheel] metadata , then converted in a frequency ratio using the ba.semi2ratio function. bend is used as a factor multiplied to the base frequency retrieved from freq . Therefore, the default value of bend is 0 in semitones, which corresponds to the central position of the pitch wheel, and will correspond to a multiplicative ratio of 1. A value smaller than 0 will decrease the pitch and a value greater than 0 will increase it. While the above example will have the expected behavior, it is likely that clicking will happen when changing the value of bend since this parameter is not smoothed. Unfortunately, regular smoothing (through the use of si.smoo , for example) is not a good option here. This is due to the fact that instances of polyphonic voices are frozen when a voice is not being used. Since the value of bend might jump from one value to another when a voice is being reactivated/reused, continuous smoothing would probably create an \"ugly sweep\" in that case. Hence, si.polySmooth should be used in this context instead of si.smoo . This function shuts down smoothing for a given number of samples when a trigger is activated. Reusing the example from the previous section, we can implement a click-free polyphonic synthesizer with continuous pitch control: Observe the usage of si.polySmooth here: when gate=0 the signal is not smoothed, when gate=1 the signal is smoothed with a factor of 0.999 after one sample. Complete Example: Sustain Pedal and Additional Parameters Just for fun ;), we improve in this section the example from the previous one by implementing sustain pedal control as well as some modulation controlled by the modulation wheel of the MIDI keyboard. Sustain pedal control can be easily added simply by declaring a sustain parameter controlled by MIDI CC 64 (which is directly linked to the sustain pedal) and interacting with the standard gate parameter: s = hslider(\"sustain[midi:ctrl 64]\",0,0,1,1); t = button(\"gate\"); gate = t+s : min(1); Hence, gate will remain equal to 1 as long as the sustain pedal is pressed. The simple synthesizer from the previous section (which is literally just a sawtooth oscillator) can be slightly improved by processing it with a dynamically-controlled lowpass filter: MIDI CC 1 corresponds to the modulation wheel which is used here to control the cut-off frequency of the lowpass filter. Next we can add a global master, using the MIDI CC 7 standard volume control to change its level:","title":"MIDI Support"},{"location":"manual/midi/#midi-and-polyphony-support","text":"Similarly to OSC , several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments.","title":"MIDI and Polyphony Support"},{"location":"manual/midi/#configuring-midi-in-faust","text":"MIDI support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [midi:on] metadata to the standard options metadata : declare options \"[midi:on]\"; or using the -midi option in most of faust2xx scripts. MIDI control is configured in Faust using metadata in UI elements . MIDI channels from 1 to 16 can be used at reception or sending time. By convention, using the channel = 0 value (or no channel setting) means \"all channels\". That is, at reception time, MIDI messages received on all channels can be used to control a given parameter, and at sending time, the MIDI message associated to a parameter will be sent on all channels. MIDI metadata are decoded by a special architecture that parses incoming MIDI messages and updates the appropriate control parameters, or send MIDI messages when the UI elements (i.e., sliders, buttons, etc.) are moved. All MIDI configuration metadata in Faust follow the following format: [midi:xxx yyy...] This section provides a list of the most common metadata that can be used to configure of the MIDI behavior of a Faust program. Below, when a 7-bit MIDI parameter is used to drive a button or a checkbox , its maximum value (127) maps to 1 (\"on\") while its minimum value (0) maps to 0 (\"off\").","title":"Configuring MIDI in Faust"},{"location":"manual/midi/#midictrl-num-or-midictrl-num-chan-metadata","text":"The [midi:ctrl num] metadata assigns MIDI CC (control) to a specific UI element. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:ctrl num] version can receive messages on all channels, and will send on all channels. The second [midi:ctrl num chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:ctrl num chan]\",...); Where: num : the MIDI CC number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by MIDI CC 11. When CC11=0, then the frequency is 200Hz, when CC11=127, then the frequency is 1000Hz.","title":"[midi:ctrl num] or [midi:ctrl num chan] Metadata"},{"location":"manual/midi/#midikeyon-midikey-or-midikeyon-midikey-chan-metadata","text":"The [midi:keyon midikey] metadata assigns the velocity value of a key-on MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyon midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyon midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyon midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-on message is sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed.","title":"[midi:keyon midikey] or [midi:keyon midikey chan] Metadata"},{"location":"manual/midi/#midikeyoff-midikey-or-midikeyoff-midikey-chan-metadata","text":"The [midi:keyoff midikey] metadata assigns the velocity value of a key-off MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyoff midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyoff midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyoff midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-off message is sent. Therefore, the frequency will only be updated when MIDI key 62 is released.","title":"[midi:keyoff midikey] or [midi:keyoff midikey chan] Metadata"},{"location":"manual/midi/#midikey-midikey-or-midikey-midikey-chan-metadata","text":"The [midi:key midikey] metadata assigns the velocity value of key-on and key-off MIDI messages received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:midikey midikey] version can receive messages on all channels, and will send on all channels. The second [midi:midikey midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:key midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when key-on and key-off messages are sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed and released.","title":"[midi:key midikey] or [midi:key midikey chan] Metadata"},{"location":"manual/midi/#midikeypress-midikey-or-midikeypress-midikey-chan-metadata","text":"The [midi:keypress midikey] metadata assigns the pressure (after-touch) value of a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keypress midikey] version can receive messages on all channels, will send on all channels. The second [midi:keypress midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keypress midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the pressure (after-touch) values received on key 62.","title":"[midi:keypress midikey] or [midi:keypress midikey chan] Metadata"},{"location":"manual/midi/#midichanpress-or-midichanpress-chan-metadata","text":"The [midi:chanpress] metadata assigns the channel pressure value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:chanpress] version can receive messages on all channels, and will send on all channels. The second [midi:chanpress chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:chanpress chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the volume of a sawtooth wave oscillator is controlled by the channel pressure values.","title":"[midi:chanpress] or [midi:chanpress chan] Metadata"},{"location":"manual/midi/#midipgm-or-midipgm-chan-metadata","text":"The [midi:pgm] metadata assigns the program-change to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will use the UI element range. Only the values described in the UI element range will be used at reception, and can be sent. The first [midi:pgm] version can receive messages on all channels, and will send on all channels. The second [midi:pgm chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = nentry(\"foo[midi:pgm chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the instrument will be choosen in the {0,3} range.","title":"[midi:pgm] or [midi:pgm chan] Metadata"},{"location":"manual/midi/#midipitchwheel-or-midipitchwheel-chan-metadata","text":"The [midi:pitchwheel] metadata assigns the pitch-wheel value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 16383} range. When used with a button or a checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. Pitch-wheel values are typically used to control tuning, mapping the {0, 16383} MIDI range to a {-semitone, semitone} range. The ba.semi2ratio function must be used to convert semitones in a frequency multiplicative ratio. The first [midi:pitchwheel] version can receive messages on all channels, and will send on all channels. The second [midi:pitchwheel chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:pitchwheel chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the bend of a sawtooth wave oscillator is controlled by the pitch-wheel in the {-2, 2} semitone range, then converted as a frequency multiplicative ratio and multiplied by a given frequency.","title":"[midi:pitchwheel] or [midi:pitchwheel chan] Metadata"},{"location":"manual/midi/#midistart-metadata","text":"When used with a button or a checkbox, [midi:start] will trigger a value of 1 when a start MIDI message is received. Usage foo = checkbox(\"foo[midi:start]\");","title":"[midi:start] Metadata"},{"location":"manual/midi/#midistop-metadata","text":"When used with a button or a checkbox, [midi:stop] will trigger a value of 0 when a stop MIDI message is received. Usage foo = checkbox(\"foo[midi:stop]\");","title":"[midi:stop] Metadata"},{"location":"manual/midi/#midiclock-metadata","text":"When used with a button or a checkbox, [midi:clock] will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received (seen by Faust code as a square command signal, to be used to compute higher level information). Usage foo = checkbox(\"foo[midi:clock]\");","title":"[midi:clock] Metadata"},{"location":"manual/midi/#midi-sync","text":"MIDI clock-based synchronization can be used to slave a given Faust program using the metadata presented in the 3 past sections. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages:","title":"MIDI Sync"},{"location":"manual/midi/#midi-polyphony-support","text":"Polyphony is conveniently handled in Faust directly by Faust Architectures. Note that programming polyphonic instrument completely from scratch in Faust and without relying on architectures is also possible. In fact, this feature is indispensable if complex signal interactions between the different voices have to be described (like sympathetic strings resonance in a physical model, etc.). However, since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocation and control MIDI messages decoding and mapping. Polyphony support can be added to any Faust program (as long as the target architecture supports it) simply by adding the [nvoices:n] metadata to the standard option metadata where n is the maximum number of voices of polyphony to be allocated: declare options \"[midi:on][nvoices:12]\";","title":"MIDI Polyphony Support"},{"location":"manual/midi/#standard-polyphony-parameters","text":"Most Faust architectures allow for the implementation of polyphonic instruments simply by using a set of \"standard user interface names.\" Hence, any Faust program declaring the freq (or key) , gain (or vel or velocity) , and gate parameter is polyphony-compatible. These 3 parameters are directly associated to key-on and key-off events and have the following behavior: When a key-on event is received, gate will be set to 1. Inversely, when a key-off event is received, gate will be set to 0. Therefore, gate is typically used to trigger an envelope, etc. freq is a frequency in Hz computed automatically in function of the value of the pitch contained in a key-on or a key-off message. Alternatively key can be used to get the raw MIDI pitch and describe the pitch to Hz conversion in the DSP code itself (for instance to implement alternative tunings). gain is a linear gain (value between 0-1) computed in function of the velocity value contained in a key-on or a key-off message. Alternatively vel or velocity can be used to get the raw MIDI velocity and describe the velocity to gain conversion in the DSP code itself (for instance to implement alternative velocity curves). Example: Simple Polyphonic Synthesizer In the following example, the standard freq , gain , and gate parameters are used to implement a simple polyphonic synth. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). In the next example, the standard key , gain , and gate parameters are used to implement a simple polyphonic synth with alternate tuning. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). The previous example can be slightly improved by adding an envelope generator and controlling it with gain and gate : Warning: Note that all the active voices of polyphony are added together without scaling! This means that the previous example will likely click if several voices are played at the same time. It is the Faust programmer's responsibility to take this into account in his code. For example, assuming that the number of active voices will always be smaller or equal to 4, the following safeguard could be added to the previous example: process = os.sawtooth(freq)*envelope : /(4);","title":"Standard Polyphony Parameters"},{"location":"manual/midi/#configuring-and-activating-polyphony","text":"Polyphony can be activated manually in some Faust architectures using an option/flag during compilation (e.g., typically -poly or -nvoices <num> in the faust2xx scripts). That's also how the Faust Online IDE works where a button can be used to turn polyphony on or off. However, the most standard way to activate polyphony in Faust is to declare the [nvoices:n] metadata which allows us to specify the maximum number of voices of polyphony ( n ) that will be allocated in the generated program. For example, the Faust program from the previous section could be modified such that: which when compiled running (for example): faust2jaqt faustProgram.dsp will generate a MIDI-controllable polyphonic synthesizer.","title":"Configuring and Activating Polyphony"},{"location":"manual/midi/#audio-effects-and-polyphonic-synthesizer","text":"While audio audio effects can be added directly to the process line of a Faust synthesizer, for example: process = os.sawtooth(freq)*envelope : reverb; it is not a good practice since a new instance of that effect will be created for each active voice of polyphony. The main consequence of this would be an increased CPU cost. Similarly to process , Faust allows for the declaration of an effect line, which identifies an audio effect to be connected to the output of the polyphonic synthesizer. For example, a simple reverb can be added to the previous example simply by writing: In this case, the polyphonic part is based on process and a single instance of the effect defined in effect will be created and shared by all voices. The architecture machinery then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them. Here dm.zita_light is a stereo effect, the mono output of the os.sawtooth(freq)*envelope expression can be split into 2 signals (but would be splitted automatically if kept as a mono output). Also, be aware that this type of construction wont be visible in the corresponding block diagram that will only show what's implemented in the process line.","title":"Audio Effects and Polyphonic Synthesizer"},{"location":"manual/midi/#polyphony-and-continuous-pitch","text":"Key-on and key-off MIDI messages only send the \"base pitch\" of the instance of a note. Hence, if only the freq standard parameter is used to control the frequency of the synthesizer, its pitch will always be \"quantized\" to the nearest semitone. In order to be able to do glissandi, vibrato, etc., a variable associated to the pitch-wheel needs to be declared and must interact with the \"base frequency\" value retrieved from freq as such: f = hslider(\"freq\",300,50,2000,0.01); bend = ba.semi2ratio(hslider(\"bend[midi:pitchwheel]\",0,-2,2,0.01)); freq = f*bend; // the \"final\" freq parameter to be used The bend variable is controlled by the pitch-wheel thanks to [midi:pitchwheel] metadata , then converted in a frequency ratio using the ba.semi2ratio function. bend is used as a factor multiplied to the base frequency retrieved from freq . Therefore, the default value of bend is 0 in semitones, which corresponds to the central position of the pitch wheel, and will correspond to a multiplicative ratio of 1. A value smaller than 0 will decrease the pitch and a value greater than 0 will increase it. While the above example will have the expected behavior, it is likely that clicking will happen when changing the value of bend since this parameter is not smoothed. Unfortunately, regular smoothing (through the use of si.smoo , for example) is not a good option here. This is due to the fact that instances of polyphonic voices are frozen when a voice is not being used. Since the value of bend might jump from one value to another when a voice is being reactivated/reused, continuous smoothing would probably create an \"ugly sweep\" in that case. Hence, si.polySmooth should be used in this context instead of si.smoo . This function shuts down smoothing for a given number of samples when a trigger is activated. Reusing the example from the previous section, we can implement a click-free polyphonic synthesizer with continuous pitch control: Observe the usage of si.polySmooth here: when gate=0 the signal is not smoothed, when gate=1 the signal is smoothed with a factor of 0.999 after one sample.","title":"Polyphony and Continuous Pitch"},{"location":"manual/midi/#complete-example-sustain-pedal-and-additional-parameters","text":"Just for fun ;), we improve in this section the example from the previous one by implementing sustain pedal control as well as some modulation controlled by the modulation wheel of the MIDI keyboard. Sustain pedal control can be easily added simply by declaring a sustain parameter controlled by MIDI CC 64 (which is directly linked to the sustain pedal) and interacting with the standard gate parameter: s = hslider(\"sustain[midi:ctrl 64]\",0,0,1,1); t = button(\"gate\"); gate = t+s : min(1); Hence, gate will remain equal to 1 as long as the sustain pedal is pressed. The simple synthesizer from the previous section (which is literally just a sawtooth oscillator) can be slightly improved by processing it with a dynamically-controlled lowpass filter: MIDI CC 1 corresponds to the modulation wheel which is used here to control the cut-off frequency of the lowpass filter. Next we can add a global master, using the MIDI CC 7 standard volume control to change its level:","title":"Complete Example: Sustain Pedal and Additional Parameters"},{"location":"manual/optimizing/","text":"Optimizing the Code Optimizing the DSP Code Faust is a Domain Specific Language helping the programmer to write very high-level and concise DSP code, while letting the compiler do the hard work of producing the best and most efficient implementation of the specification. When processing the DSP source, the compiler typing system is able to discover how the described computations are effectively separated in four main categories: computations done at compilation/specialisation time : this is the place for algorithmic signal processors definition heavily based on the lambda-calculus constitute of the language, together with its pattern-matching capabilities computations done at init time : for instance all the code that depends of the actual sample-rate, or filling of some internal tables (coded with the rdtable or rwtable language primitives) computations done at control rate : typically all code that read the current values of controllers (buttons, sliders, nentries) and update the DSP internal state which depends of them computations done at sample rate : all remaining code that process and produce the samples One can think of these four categories as different computation rates . The programmer can possibly split its DSP algorithm to distribute the needed computation in the most appropriate domain ( slower rate domain better than faster rate domain) and possibly rewrite some parts of its DSP algorithm from one domain to a slower rate one to finally obtain the most efficient code. Computations Done at Compilation/Specialisation Time Using Pattern Matching TODO : explain how pattern-matching can be used to algorithmically describe signal processors, explain the principle of defining a new DSL inside the Faust DSL (with fds.lib , physmodels.lib , wdmodels.lib as examples). Specializing the DSP Code The Faust compiler can possibly do a lot of optimizations at compile time. The DSP code can for instance be compiled for a fixed sample rate, thus doing at compile time all computation that depends of it. Since the Faust compiler will look for librairies starting from the local folder, a simple way is to locally copy the libraries/platform.lib file (which contains the SR definition), and change its definition for a fixed value like 48000 Hz. Then the DSP code has to be recompiled for the specialisation to take effect. Note that libraries/platform.lib also contains the definition of the tablesize constant which is used in various places to allocate tables for oscillators. Thus decreasing this value can save memory, for instance when compiling for embedded devices. This is the technique used in some Faust services scripts which add the -I /usr/local/share/faust/embedded/ parameter to the Faust command line to use a special version of the platform.lib file. Computations Done at Init time If not specialized with a constant value at compilation time, all computations that use the sample rate (which is accessed with the ma.SR in the DSP source code and given as parameter in the DSP init function) will be done at init time, and possibly again each time the same DSP is initialized with another sample rate. Using rdtable or rwtable TODO : explain how computations can be done at init time and how to use rdtable or rwtable to store pre-computed values. Several tabulation functions can possibly be used. Computations Done at Control Rate Parameter Smoothing Control parameters are sampled once per block, their values are considered constant during the block, and the internal state depending of them is updated and appears at the beginning of the compute method, before the sample rate DSP loop. In the following DSP code, the vol slider value is directly applied on the input audio signal: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01); process = *(vol); In the generated C++ code for compute , the vol slider value is sampled before the actual DSP loop, by reading the fHslider0 field kept in a local fSlow0 variable: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0 * float(input0[i0])); } } If the control parameter needs to be smoothed (like to avoid clicks or too abrupt changes), with the control : si.smoo kind of code, the computation rate moves from control rate to sample rate . If the previous DSP code is now changed with: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01) : si.smoo; process = *(vol); The vol slider is sampled before the actual DSP loop and multiplied by the filter fConst0 constant computed at init time, and finally used in the DSP loop in the smoothing filter: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } So the CPU usage will obviously be higher, and the need for parameter smoothing should be carefully studied. Another point to consider is the order of computation when smoothing control. In the following DSP code, the dB slider value is first converted first to a linear value, then smoothed: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : ba.db2linear : si.smoo; process = *(smoother_vol); And the generated C++ code for compute has the costly pow math function used in ba.db2linear evaluted at control rate, so once before the DSP loop: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * std::pow(1e+01f, 0.05f * float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } But if the order between ba.db2linear and si.smoo is reversed like in the following code: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : si.smoo : ba.db2linear; process = *(smoother_vol); The generated C++ code for compute now has the pow math function used in ba.db2linear evaluated at sample rate in the DSP loop, which is obviously much more costly: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * std::pow(1e+01f, 0.05f * fRec0[0])); fRec0[1] = fRec0[0]; } } So to obtain the best performances in the generated code, all costly computations have to be done on the control value (as much as possible, this may not always be the desirable behaviour), and si.smoo (or any function that moves the computation from control rate to sample rate) as the last operation. Computations Done at Sample Rate Possibly deactivating table range check with -ct option The -ct option is activated by default (starting at Faust version 2.53.4), but can possibly be removed (using -ct 0 ) to speed up the code. Read Debugging rdtable and rwtable primitives for a complete description. Using Function Tabulation The use of rdtable kind of compilation done at init time can be simplified using the ba.tabulate or ba.tabulate_chebychev functions to tabulate a given unary function fun on a given range. A table is created and filled with precomputed values, and can be used to compute fun(x) in a more efficient way (at the cost of additional static memory needed for the table). Using Fast Math Functions When costly math functions still appear in the sample rate code, the -fm compilation option can possibly be used to replace the standard versions provided by the underlying OS (like std::cos , std::tan ... in C++ for instance) with user defined ones (hopefully faster, but possibly less precise). Delay lines implementation and DSP memory size The Faust compiler automatically allocates buffers for the delay lines. At each sample calculation, the delayed signal is written to a specific location (the write position) and read from another location (the read position), the distance in samples between the read and write indexes representing the delay itself. There are two possible strategies for implementing delay lines: either the read and write indices remain the same and the delay line memory is moved after each sample calculation, or the read and write indices move themselves along the delay line (with two possible wrapping index methods). These multiple methods allow arbitration between memory consumption and the CPU cost of using the delay line. Two compiler options -mcd <n> ( -max-copy-delay ) and -dlt <n> ( --delay-line-threshold ) allow you to play with both strategies and even combine them. For very short delay lines of up to two samples, the first strategy is implemented by manually shifting the buffer. Then a shift loop is generated for delay from 2 up to -mcd <n> samples. For delays values bigger than -mcd <n> samples, the second strategy is implemented by: either using arrays of power-of-two sizes accessed using mask based index computation with delays smaller than -dlt <n> value. or using a wrapping index moved by an if based method where the increasing index is compared to the delay-line size, and wrapped to zero when reaching it. This method is used for to delay values bigger then -dlt <n> . In this strategy the first method is faster but consumes more memory (since a delay line of a given size will be extended to the next power-of-two size), and the second method is slower but consume less memory. Note that by default -mcd 16 is -dlt <INT_MAX> values are used. Here is a scheme explaining the mecanism: [ shift buffer |-mcd <N1>| wrapping power-of-two buffer |-dlt <N2>| if based wrapping buffer ] Here is an example of a Faust program with 10 delay lines in parallel, each delaying a separated input, with three ways of compiling it (using the defaut -scalar mode): When compiling with faust -mcd 20 , since 20 is larger than the size of the largest delay line, all of them are compiled with the shifted memory strategy: ... // The DSP memory layout float fVec0[11]; float fVec1[10]; float fVec2[9]; float fVec3[8]; float fVec4[7]; float fVec5[6]; float fVec6[5]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[0] = float(input9[i0]); fVec1[0] = float(input8[i0]); fVec2[0] = float(input7[i0]); fVec3[0] = float(input6[i0]); fVec4[0] = float(input5[i0]); fVec5[0] = float(input4[i0]); fVec6[0] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } for (int j2 = 8; j2 > 0; j2 = j2 - 1) { fVec2[j2] = fVec2[j2 - 1]; } for (int j3 = 7; j3 > 0; j3 = j3 - 1) { fVec3[j3] = fVec3[j3 - 1]; } for (int j4 = 6; j4 > 0; j4 = j4 - 1) { fVec4[j4] = fVec4[j4 - 1]; } for (int j5 = 5; j5 > 0; j5 = j5 - 1) { fVec5[j5] = fVec5[j5 - 1]; } for (int j6 = 4; j6 > 0; j6 = j6 - 1) { fVec6[j6] = fVec6[j6 - 1]; } for (int j7 = 3; j7 > 0; j7 = j7 - 1) { fVec7[j7] = fVec7[j7 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the very short delay lines of up to two samples by manually shifting the buffer method can be seen in those lines: ... // Delay line of 1 sample fVec8[1] = fVec8[0]; // Delay line of 2 samples fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; ... and the shift loop is generated for delay from 2 up to -mcd <n> samples method can be seen in those lines: ... output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); // Shift delay line of 10 samples for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } // Shift delay line of 9 samples for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } ... When compiled with faust -mcd 0 , all delay lines use the wrapping index second strategy with power-of-two size (since -dlt <INT_MAX> is used by default): ... // The DSP memory layout int IOTA0; float fVec0[16]; float fVec1[16]; float fVec2[16]; float fVec3[8]; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[4]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[IOTA0 & 15] = float(input9[i0]); fVec1[IOTA0 & 15] = float(input8[i0]); fVec2[IOTA0 & 15] = float(input7[i0]); fVec3[IOTA0 & 7] = float(input6[i0]); fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[IOTA0 & 3] = float(input2[i0]); fVec8[IOTA0 & 1] = float(input0[i0]); fVec9[IOTA0 & 3] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[(IOTA0 - 10) & 15] + fVec1[(IOTA0 - 9) & 15] + fVec2[(IOTA0 - 8) & 15] + fVec3[(IOTA0 - 7) & 7] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[(IOTA0 - 3) & 3] + fVec8[(IOTA0 - 1) & 1] + fVec9[(IOTA0 - 2) & 3]); IOTA0 = IOTA0 + 1; } } ... In this code example, several delay lines of various power-of-two size (2, 4, 8, 16) are generated. A unique continuously incremented IOTA0 variable is shared between all delay lines. The wrapping index code is generated with this (IOTA0 - 5) & 7 kind of code, with a power-of-two - 1 mask (so 8 - 1 = 7 here). When compiled with faust -mcd 4 -dlt 7 , a mixture of the three generation strategies is used: // The DSP memory layout ... int fVec0_widx; float fVec0[11]; int fVec1_widx; float fVec1[10]; int fVec2_widx; float fVec2[9]; int fVec3_widx; float fVec3[8]; int IOTA0; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { int fVec0_widx_tmp = fVec0_widx; fVec0[fVec0_widx_tmp] = float(input9[i0]); int fVec0_ridx_tmp0 = fVec0_widx - 10; int fVec1_widx_tmp = fVec1_widx; fVec1[fVec1_widx_tmp] = float(input8[i0]); int fVec1_ridx_tmp0 = fVec1_widx - 9; int fVec2_widx_tmp = fVec2_widx; fVec2[fVec2_widx_tmp] = float(input7[i0]); int fVec2_ridx_tmp0 = fVec2_widx - 8; int fVec3_widx_tmp = fVec3_widx; fVec3[fVec3_widx_tmp] = float(input6[i0]); int fVec3_ridx_tmp0 = fVec3_widx - 7; fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[((fVec0_ridx_tmp0 < 0) ? fVec0_ridx_tmp0 + 11 : fVec0_ridx_tmp0)] + fVec1[((fVec1_ridx_tmp0 < 0) ? fVec1_ridx_tmp0 + 10 : fVec1_ridx_tmp0)] + fVec2[((fVec2_ridx_tmp0 < 0) ? fVec2_ridx_tmp0 + 9 : fVec2_ridx_tmp0)] + fVec3[((fVec3_ridx_tmp0 < 0) ? fVec3_ridx_tmp0 + 8 : fVec3_ridx_tmp0)] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[3] + fVec8[1] + fVec9[2]); fVec0_widx_tmp = fVec0_widx_tmp + 1; fVec0_widx_tmp = ((fVec0_widx_tmp == 11) ? 0 : fVec0_widx_tmp); fVec0_widx = fVec0_widx_tmp; fVec1_widx_tmp = fVec1_widx_tmp + 1; fVec1_widx_tmp = ((fVec1_widx_tmp == 10) ? 0 : fVec1_widx_tmp); fVec1_widx = fVec1_widx_tmp; fVec2_widx_tmp = fVec2_widx_tmp + 1; fVec2_widx_tmp = ((fVec2_widx_tmp == 9) ? 0 : fVec2_widx_tmp); fVec2_widx = fVec2_widx_tmp; fVec3_widx_tmp = fVec3_widx_tmp + 1; fVec3_widx_tmp = ((fVec3_widx_tmp == 8) ? 0 : fVec3_widx_tmp); fVec3_widx = fVec3_widx_tmp; IOTA0 = IOTA0 + 1; for (int j0 = 3; j0 > 0; j0 = j0 - 1) { fVec7[j0] = fVec7[j0 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the wrapping index moved by an if based method can be recognized with the use of those fVec0_ridx_tmp0 and fVec0_widx_tmp0 kind of variables. Choosing values that use less memory can be particularly important in the context of embedded devices. Testing different combinations of the -mcd and -dlt options can help optimize CPU utilisation, to summarize: chosing a big n value for -mcd n will consume less memory but the shift loop will start to be time consuming with big delay values. This model may sometimes be better suited if the C++ or LLVM compiler correctly auto-vectorizes the code and generates more efficient SIMD code. chosing -mcd 0 will activate the wrapping index second strategy for all delay lines in the DSP code, then playing with -dlt <n> allows to arbitrate between the faster but consuming more memory method and slower but consume less memory method. chosing a combinaison of -mcd n1 and -dlt <n2> can possibly be the model to chose when a lot of delay lines with different sizes are used in the DSP code. Using the benchmark tools faustbench and faustbench-llvm allow to refine the choice of compilation options. Recursive signals In the C++ generated code, the delays lines appear as fVecXX arrays. When recursion is used in the DSP, a one sample delay is automatically added in the recursive path, and a very short delay line is allocated (appearing as fRecX arrays in the generated code). Here is the code of a recursively defined integrator: And the generated C++ code with the iRec0 buffer: ... // The DSP memory layout int iRec0[2]; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(iRec0[0]); iRec0[1] = iRec0[0]; } } ... Delay lines in recursive signals Here is an example of a Faust program with 10 recursive blocks in parallel, each using a delay line of increasing value: Since a recursive signal uses a one sample delay in its loop, a buffer is allocated to handle the delay. When a delay is used in addition to the recursive signal, a single buffer is allocated to combine the two delay sources. The generated code using faust -mcd 0 for instance is now: ... // The DSP memory layout int IOTA0; float fRec0[4]; float fRec1[4]; float fRec2[8]; float fRec3[8]; float fRec4[8]; float fRec5[8]; float fRec6[16]; float fRec7[16]; float fRec8[16]; float fRec9[16]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 3] = float(input0[i0]) + fRec0[(IOTA0 - 2) & 3]; fRec1[IOTA0 & 3] = float(input1[i0]) + fRec1[(IOTA0 - 3) & 3]; fRec2[IOTA0 & 7] = float(input2[i0]) + fRec2[(IOTA0 - 4) & 7]; fRec3[IOTA0 & 7] = float(input3[i0]) + fRec3[(IOTA0 - 5) & 7]; fRec4[IOTA0 & 7] = float(input4[i0]) + fRec4[(IOTA0 - 6) & 7]; fRec5[IOTA0 & 7] = float(input5[i0]) + fRec5[(IOTA0 - 7) & 7]; fRec6[IOTA0 & 15] = float(input6[i0]) + fRec6[(IOTA0 - 8) & 15]; fRec7[IOTA0 & 15] = float(input7[i0]) + fRec7[(IOTA0 - 9) & 15]; fRec8[IOTA0 & 15] = float(input8[i0]) + fRec8[(IOTA0 - 10) & 15]; fRec9[IOTA0 & 15] = float(input9[i0]) + fRec9[(IOTA0 - 11) & 15]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 3] + fRec1[IOTA0 & 3] + fRec2[IOTA0 & 7] + fRec3[IOTA0 & 7] + fRec4[IOTA0 & 7] + fRec5[IOTA0 & 7] + fRec6[IOTA0 & 15] + fRec7[IOTA0 & 15] + fRec8[IOTA0 & 15] + fRec9[IOTA0 & 15]); IOTA0 = IOTA0 + 1; } } ... with buffers named fRecX instead of fVecX in the previous example. The -mcd <n> and -dlt <n> options can be used with the same purpose. Managing DSP Memory Layout On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. This can be controled using the -mem compilation option and an adapted architecture file . Optimizing the C++ or LLVM Code From a given DSP program, the Faust compiler tries to generate the most efficient implementation. Optimizations can be done at DSP writing time, or later on when the target langage is generated (like C++ or LLVM IR). The generated code can have different shapes depending of compilation options, and can run faster of slower. Several programs and tools are available to help Faust programmers to test (for possible numerical or precision issues), optimize their programs by discovering the best set of options for a given DSP code, and finally compile them into native code for the target CPUs. By default the Faust compiler produces a big scalar loop in the generated mydsp::compute method. Compiler options allow to generate other code shapes , like for instance separated simpler loops connected with buffers in the so-called vectorized mode (obtained using the -vec option). The assumption is that auto-vectorizer passes in modern compilers will be able to better generate efficient SIMD code for them. In this vec option, the size of the internal buffer can be changed using the -vs value option. Moreover the computation graph can be organized in deep-first order using -dfs . Delay lines implementation can be be controlled with the -mcd size and -dlt size options, to choose for example between power-of-two sizes and mask based wrapping (faster but consumming more memory) or if based wrapping , slower but consumming less memory. Many other compilation choices are fully controllable with options. Note that the C/C++ and LLVM backends offer the greatest number of compilation options. Here are just a few of them: -clang option: when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi option: when compiled with the C++ backend, does not add the 'virtual' keyword. This option can be especially useful in embedded devices context -mapp option: simpler/faster versions of 'floor/ceil/fmod/remainder' functions (experimental) Manually testing each of them and their combination is out of reach. So several tools have been developed to automatize that process and help search the configuration space to discover the best set of compilation options (be sure to run make benchmark && sudo make devinstall in Faust toplevel folder to install the benchmark tools): faustbench The faustbench tool uses the C++ backend to generate a set of C++ files produced with different Faust compiler options. All files are then compiled in a unique binary that will measure DSP CPU of all versions of the compiled DSP. The tool is supposed to be launched in a terminal, but it can be used to generate an iOS project, ready to be launched and tested in Xcode. A more complete documentation is available on the this page . faustbench-llvm The faustbench-llvm tool uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU usage. Additional Faust compiler options can be given beside the ones that will be automatically explored by the tool. A more complete documentation is available on the this page . faust2bench The faust2bench tool allows to benchmark a given DSP program: faust2bench -h Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable So something like faust2bench -vec -lv 0 -vs 4 foo.dsp is used to produce an executable, then launching ./foo gives : ./foo ./foo : 303.599 MBytes/sec (DSP CPU % : 0.224807 at 44100 Hz) The -inj option allows to possibly inject and benchmark an external C++ class to be adapted to behave as a dsp class, like in the following adapted.cpp example. The inherited compute method is rewritten to call the external C++ limiterStereo.SetPreGain etc... code to update the controllers, and the method limiterStereo.Process which computes the DSP: #include \"faust/dsp/dsp.h\" #include \"Limiter.hpp\" struct mydsp : public dsp { Limiter<float> limiterStereo; void init(int sample_rate) { limiterStereo.SetSR(sample_rate); } int getNumInputs() { return 2; } int getNumOutputs() { return 2; } int getSampleRate() { return 44100; } void instanceInit(int sample_rate) {} void instanceConstants(int sample_rate) {} void instanceResetUserInterface() {} void instanceClear() {} void buildUserInterface(UI* ui_interface) {} dsp* clone() { return new mydsp(); } void metadata(Meta* m) {} void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { limiterStereo.SetPreGain(0.5); limiterStereo.SetAttTime(0.5); limiterStereo.SetHoldTime(0.5); limiterStereo.SetRelTime(0.5); limiterStereo.SetThreshold(0.5); limiterStereo.Process(inputs, outputs, count); } }; Using faust2bench -inj adapted.cpp dummy.dsp creates the executable to be tested with ./dummy (remember that dummy.dsp is a program that is not actually used in -inj mode). dynamic-faust The dynamic-faust tool uses the dynamic compilation chain (based on the LLVM backend), and compiles a Faust DSP source to a LLVM IR (.ll), bicode (.bc), machine code (.mc) or object code (.o) output file. This is an alternative to the C++ compilation chain, since DSP code can be compiled to object code (.o), then used and linked in a regular C++ project. A more complete documentation is available on the this page . Optimizing with any faust2xx tool All faust2xx tools compile in scalar mode by default, but can take any combination of optimal options (like -vec -fun -vs 32 -dfs -mcd 32 for instance) the previously described tools will automatically find. So by chaining the use of faustbench of faustbench-llvm to discover the best compilation options for a given DSP, then use them in the desired faust2xx tool, a CPU optimized standalone or plugin can be obtained. Note that some faust2xx tools like faust2max6 or faust2caqt can internally call the faustbench-llvm tool to discover and later on use the best possible compilation options. Compiling for Multiple CPUs On modern CPUs, compiling native code dedicated to the target processor is critical to obtain the best possible performances. When using the C++ backend, the same C++ file can be compiled with gcc of clang for each possible target CPU using the appropriate -march=cpu option. When using the LLVM backend, the same LLVM IR code can be compiled into CPU specific machine code using the dynamic-faust tool. This step will typically be done using the best compilation options automatically found with the faustbench tool or faustbench-llvm tools. A specialized tool has been developed to combine all the possible options. faust2object The faust2object tool either uses the standard C++ compiler or the LLVM dynamic compilation chain (the dynamic-faust tool) to compile a Faust DSP to object code files (.o) and wrapper C++ header files for different CPUs. The DSP name is used in the generated C++ and object code files, thus allowing to generate distinct versions of the code that can finally be linked together in a single binary. A more complete documentation is available on the this page .","title":"Optimizing the Code"},{"location":"manual/optimizing/#optimizing-the-code","text":"","title":"Optimizing the Code"},{"location":"manual/optimizing/#optimizing-the-dsp-code","text":"Faust is a Domain Specific Language helping the programmer to write very high-level and concise DSP code, while letting the compiler do the hard work of producing the best and most efficient implementation of the specification. When processing the DSP source, the compiler typing system is able to discover how the described computations are effectively separated in four main categories: computations done at compilation/specialisation time : this is the place for algorithmic signal processors definition heavily based on the lambda-calculus constitute of the language, together with its pattern-matching capabilities computations done at init time : for instance all the code that depends of the actual sample-rate, or filling of some internal tables (coded with the rdtable or rwtable language primitives) computations done at control rate : typically all code that read the current values of controllers (buttons, sliders, nentries) and update the DSP internal state which depends of them computations done at sample rate : all remaining code that process and produce the samples One can think of these four categories as different computation rates . The programmer can possibly split its DSP algorithm to distribute the needed computation in the most appropriate domain ( slower rate domain better than faster rate domain) and possibly rewrite some parts of its DSP algorithm from one domain to a slower rate one to finally obtain the most efficient code.","title":"Optimizing the DSP Code"},{"location":"manual/optimizing/#computations-done-at-compilationspecialisation-time","text":"","title":"Computations Done at Compilation/Specialisation Time"},{"location":"manual/optimizing/#using-pattern-matching","text":"TODO : explain how pattern-matching can be used to algorithmically describe signal processors, explain the principle of defining a new DSL inside the Faust DSL (with fds.lib , physmodels.lib , wdmodels.lib as examples).","title":"Using Pattern Matching"},{"location":"manual/optimizing/#specializing-the-dsp-code","text":"The Faust compiler can possibly do a lot of optimizations at compile time. The DSP code can for instance be compiled for a fixed sample rate, thus doing at compile time all computation that depends of it. Since the Faust compiler will look for librairies starting from the local folder, a simple way is to locally copy the libraries/platform.lib file (which contains the SR definition), and change its definition for a fixed value like 48000 Hz. Then the DSP code has to be recompiled for the specialisation to take effect. Note that libraries/platform.lib also contains the definition of the tablesize constant which is used in various places to allocate tables for oscillators. Thus decreasing this value can save memory, for instance when compiling for embedded devices. This is the technique used in some Faust services scripts which add the -I /usr/local/share/faust/embedded/ parameter to the Faust command line to use a special version of the platform.lib file.","title":"Specializing the DSP Code"},{"location":"manual/optimizing/#computations-done-at-init-time","text":"If not specialized with a constant value at compilation time, all computations that use the sample rate (which is accessed with the ma.SR in the DSP source code and given as parameter in the DSP init function) will be done at init time, and possibly again each time the same DSP is initialized with another sample rate.","title":"Computations Done at Init time"},{"location":"manual/optimizing/#using-rdtable-or-rwtable","text":"TODO : explain how computations can be done at init time and how to use rdtable or rwtable to store pre-computed values. Several tabulation functions can possibly be used.","title":"Using rdtable or rwtable"},{"location":"manual/optimizing/#computations-done-at-control-rate","text":"","title":"Computations Done at Control Rate"},{"location":"manual/optimizing/#parameter-smoothing","text":"Control parameters are sampled once per block, their values are considered constant during the block, and the internal state depending of them is updated and appears at the beginning of the compute method, before the sample rate DSP loop. In the following DSP code, the vol slider value is directly applied on the input audio signal: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01); process = *(vol); In the generated C++ code for compute , the vol slider value is sampled before the actual DSP loop, by reading the fHslider0 field kept in a local fSlow0 variable: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0 * float(input0[i0])); } } If the control parameter needs to be smoothed (like to avoid clicks or too abrupt changes), with the control : si.smoo kind of code, the computation rate moves from control rate to sample rate . If the previous DSP code is now changed with: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01) : si.smoo; process = *(vol); The vol slider is sampled before the actual DSP loop and multiplied by the filter fConst0 constant computed at init time, and finally used in the DSP loop in the smoothing filter: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } So the CPU usage will obviously be higher, and the need for parameter smoothing should be carefully studied. Another point to consider is the order of computation when smoothing control. In the following DSP code, the dB slider value is first converted first to a linear value, then smoothed: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : ba.db2linear : si.smoo; process = *(smoother_vol); And the generated C++ code for compute has the costly pow math function used in ba.db2linear evaluted at control rate, so once before the DSP loop: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * std::pow(1e+01f, 0.05f * float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } But if the order between ba.db2linear and si.smoo is reversed like in the following code: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : si.smoo : ba.db2linear; process = *(smoother_vol); The generated C++ code for compute now has the pow math function used in ba.db2linear evaluated at sample rate in the DSP loop, which is obviously much more costly: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * std::pow(1e+01f, 0.05f * fRec0[0])); fRec0[1] = fRec0[0]; } } So to obtain the best performances in the generated code, all costly computations have to be done on the control value (as much as possible, this may not always be the desirable behaviour), and si.smoo (or any function that moves the computation from control rate to sample rate) as the last operation.","title":"Parameter Smoothing"},{"location":"manual/optimizing/#computations-done-at-sample-rate","text":"","title":"Computations Done at Sample Rate"},{"location":"manual/optimizing/#possibly-deactivating-table-range-check-with-ct-option","text":"The -ct option is activated by default (starting at Faust version 2.53.4), but can possibly be removed (using -ct 0 ) to speed up the code. Read Debugging rdtable and rwtable primitives for a complete description.","title":"Possibly deactivating table range check with -ct option"},{"location":"manual/optimizing/#using-function-tabulation","text":"The use of rdtable kind of compilation done at init time can be simplified using the ba.tabulate or ba.tabulate_chebychev functions to tabulate a given unary function fun on a given range. A table is created and filled with precomputed values, and can be used to compute fun(x) in a more efficient way (at the cost of additional static memory needed for the table).","title":"Using Function Tabulation"},{"location":"manual/optimizing/#using-fast-math-functions","text":"When costly math functions still appear in the sample rate code, the -fm compilation option can possibly be used to replace the standard versions provided by the underlying OS (like std::cos , std::tan ... in C++ for instance) with user defined ones (hopefully faster, but possibly less precise).","title":"Using Fast Math Functions"},{"location":"manual/optimizing/#delay-lines-implementation-and-dsp-memory-size","text":"The Faust compiler automatically allocates buffers for the delay lines. At each sample calculation, the delayed signal is written to a specific location (the write position) and read from another location (the read position), the distance in samples between the read and write indexes representing the delay itself. There are two possible strategies for implementing delay lines: either the read and write indices remain the same and the delay line memory is moved after each sample calculation, or the read and write indices move themselves along the delay line (with two possible wrapping index methods). These multiple methods allow arbitration between memory consumption and the CPU cost of using the delay line. Two compiler options -mcd <n> ( -max-copy-delay ) and -dlt <n> ( --delay-line-threshold ) allow you to play with both strategies and even combine them. For very short delay lines of up to two samples, the first strategy is implemented by manually shifting the buffer. Then a shift loop is generated for delay from 2 up to -mcd <n> samples. For delays values bigger than -mcd <n> samples, the second strategy is implemented by: either using arrays of power-of-two sizes accessed using mask based index computation with delays smaller than -dlt <n> value. or using a wrapping index moved by an if based method where the increasing index is compared to the delay-line size, and wrapped to zero when reaching it. This method is used for to delay values bigger then -dlt <n> . In this strategy the first method is faster but consumes more memory (since a delay line of a given size will be extended to the next power-of-two size), and the second method is slower but consume less memory. Note that by default -mcd 16 is -dlt <INT_MAX> values are used. Here is a scheme explaining the mecanism: [ shift buffer |-mcd <N1>| wrapping power-of-two buffer |-dlt <N2>| if based wrapping buffer ] Here is an example of a Faust program with 10 delay lines in parallel, each delaying a separated input, with three ways of compiling it (using the defaut -scalar mode): When compiling with faust -mcd 20 , since 20 is larger than the size of the largest delay line, all of them are compiled with the shifted memory strategy: ... // The DSP memory layout float fVec0[11]; float fVec1[10]; float fVec2[9]; float fVec3[8]; float fVec4[7]; float fVec5[6]; float fVec6[5]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[0] = float(input9[i0]); fVec1[0] = float(input8[i0]); fVec2[0] = float(input7[i0]); fVec3[0] = float(input6[i0]); fVec4[0] = float(input5[i0]); fVec5[0] = float(input4[i0]); fVec6[0] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } for (int j2 = 8; j2 > 0; j2 = j2 - 1) { fVec2[j2] = fVec2[j2 - 1]; } for (int j3 = 7; j3 > 0; j3 = j3 - 1) { fVec3[j3] = fVec3[j3 - 1]; } for (int j4 = 6; j4 > 0; j4 = j4 - 1) { fVec4[j4] = fVec4[j4 - 1]; } for (int j5 = 5; j5 > 0; j5 = j5 - 1) { fVec5[j5] = fVec5[j5 - 1]; } for (int j6 = 4; j6 > 0; j6 = j6 - 1) { fVec6[j6] = fVec6[j6 - 1]; } for (int j7 = 3; j7 > 0; j7 = j7 - 1) { fVec7[j7] = fVec7[j7 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the very short delay lines of up to two samples by manually shifting the buffer method can be seen in those lines: ... // Delay line of 1 sample fVec8[1] = fVec8[0]; // Delay line of 2 samples fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; ... and the shift loop is generated for delay from 2 up to -mcd <n> samples method can be seen in those lines: ... output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); // Shift delay line of 10 samples for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } // Shift delay line of 9 samples for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } ... When compiled with faust -mcd 0 , all delay lines use the wrapping index second strategy with power-of-two size (since -dlt <INT_MAX> is used by default): ... // The DSP memory layout int IOTA0; float fVec0[16]; float fVec1[16]; float fVec2[16]; float fVec3[8]; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[4]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[IOTA0 & 15] = float(input9[i0]); fVec1[IOTA0 & 15] = float(input8[i0]); fVec2[IOTA0 & 15] = float(input7[i0]); fVec3[IOTA0 & 7] = float(input6[i0]); fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[IOTA0 & 3] = float(input2[i0]); fVec8[IOTA0 & 1] = float(input0[i0]); fVec9[IOTA0 & 3] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[(IOTA0 - 10) & 15] + fVec1[(IOTA0 - 9) & 15] + fVec2[(IOTA0 - 8) & 15] + fVec3[(IOTA0 - 7) & 7] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[(IOTA0 - 3) & 3] + fVec8[(IOTA0 - 1) & 1] + fVec9[(IOTA0 - 2) & 3]); IOTA0 = IOTA0 + 1; } } ... In this code example, several delay lines of various power-of-two size (2, 4, 8, 16) are generated. A unique continuously incremented IOTA0 variable is shared between all delay lines. The wrapping index code is generated with this (IOTA0 - 5) & 7 kind of code, with a power-of-two - 1 mask (so 8 - 1 = 7 here). When compiled with faust -mcd 4 -dlt 7 , a mixture of the three generation strategies is used: // The DSP memory layout ... int fVec0_widx; float fVec0[11]; int fVec1_widx; float fVec1[10]; int fVec2_widx; float fVec2[9]; int fVec3_widx; float fVec3[8]; int IOTA0; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { int fVec0_widx_tmp = fVec0_widx; fVec0[fVec0_widx_tmp] = float(input9[i0]); int fVec0_ridx_tmp0 = fVec0_widx - 10; int fVec1_widx_tmp = fVec1_widx; fVec1[fVec1_widx_tmp] = float(input8[i0]); int fVec1_ridx_tmp0 = fVec1_widx - 9; int fVec2_widx_tmp = fVec2_widx; fVec2[fVec2_widx_tmp] = float(input7[i0]); int fVec2_ridx_tmp0 = fVec2_widx - 8; int fVec3_widx_tmp = fVec3_widx; fVec3[fVec3_widx_tmp] = float(input6[i0]); int fVec3_ridx_tmp0 = fVec3_widx - 7; fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[((fVec0_ridx_tmp0 < 0) ? fVec0_ridx_tmp0 + 11 : fVec0_ridx_tmp0)] + fVec1[((fVec1_ridx_tmp0 < 0) ? fVec1_ridx_tmp0 + 10 : fVec1_ridx_tmp0)] + fVec2[((fVec2_ridx_tmp0 < 0) ? fVec2_ridx_tmp0 + 9 : fVec2_ridx_tmp0)] + fVec3[((fVec3_ridx_tmp0 < 0) ? fVec3_ridx_tmp0 + 8 : fVec3_ridx_tmp0)] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[3] + fVec8[1] + fVec9[2]); fVec0_widx_tmp = fVec0_widx_tmp + 1; fVec0_widx_tmp = ((fVec0_widx_tmp == 11) ? 0 : fVec0_widx_tmp); fVec0_widx = fVec0_widx_tmp; fVec1_widx_tmp = fVec1_widx_tmp + 1; fVec1_widx_tmp = ((fVec1_widx_tmp == 10) ? 0 : fVec1_widx_tmp); fVec1_widx = fVec1_widx_tmp; fVec2_widx_tmp = fVec2_widx_tmp + 1; fVec2_widx_tmp = ((fVec2_widx_tmp == 9) ? 0 : fVec2_widx_tmp); fVec2_widx = fVec2_widx_tmp; fVec3_widx_tmp = fVec3_widx_tmp + 1; fVec3_widx_tmp = ((fVec3_widx_tmp == 8) ? 0 : fVec3_widx_tmp); fVec3_widx = fVec3_widx_tmp; IOTA0 = IOTA0 + 1; for (int j0 = 3; j0 > 0; j0 = j0 - 1) { fVec7[j0] = fVec7[j0 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the wrapping index moved by an if based method can be recognized with the use of those fVec0_ridx_tmp0 and fVec0_widx_tmp0 kind of variables. Choosing values that use less memory can be particularly important in the context of embedded devices. Testing different combinations of the -mcd and -dlt options can help optimize CPU utilisation, to summarize: chosing a big n value for -mcd n will consume less memory but the shift loop will start to be time consuming with big delay values. This model may sometimes be better suited if the C++ or LLVM compiler correctly auto-vectorizes the code and generates more efficient SIMD code. chosing -mcd 0 will activate the wrapping index second strategy for all delay lines in the DSP code, then playing with -dlt <n> allows to arbitrate between the faster but consuming more memory method and slower but consume less memory method. chosing a combinaison of -mcd n1 and -dlt <n2> can possibly be the model to chose when a lot of delay lines with different sizes are used in the DSP code. Using the benchmark tools faustbench and faustbench-llvm allow to refine the choice of compilation options.","title":"Delay lines implementation and DSP memory size"},{"location":"manual/optimizing/#recursive-signals","text":"In the C++ generated code, the delays lines appear as fVecXX arrays. When recursion is used in the DSP, a one sample delay is automatically added in the recursive path, and a very short delay line is allocated (appearing as fRecX arrays in the generated code). Here is the code of a recursively defined integrator: And the generated C++ code with the iRec0 buffer: ... // The DSP memory layout int iRec0[2]; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(iRec0[0]); iRec0[1] = iRec0[0]; } } ...","title":"Recursive signals"},{"location":"manual/optimizing/#delay-lines-in-recursive-signals","text":"Here is an example of a Faust program with 10 recursive blocks in parallel, each using a delay line of increasing value: Since a recursive signal uses a one sample delay in its loop, a buffer is allocated to handle the delay. When a delay is used in addition to the recursive signal, a single buffer is allocated to combine the two delay sources. The generated code using faust -mcd 0 for instance is now: ... // The DSP memory layout int IOTA0; float fRec0[4]; float fRec1[4]; float fRec2[8]; float fRec3[8]; float fRec4[8]; float fRec5[8]; float fRec6[16]; float fRec7[16]; float fRec8[16]; float fRec9[16]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 3] = float(input0[i0]) + fRec0[(IOTA0 - 2) & 3]; fRec1[IOTA0 & 3] = float(input1[i0]) + fRec1[(IOTA0 - 3) & 3]; fRec2[IOTA0 & 7] = float(input2[i0]) + fRec2[(IOTA0 - 4) & 7]; fRec3[IOTA0 & 7] = float(input3[i0]) + fRec3[(IOTA0 - 5) & 7]; fRec4[IOTA0 & 7] = float(input4[i0]) + fRec4[(IOTA0 - 6) & 7]; fRec5[IOTA0 & 7] = float(input5[i0]) + fRec5[(IOTA0 - 7) & 7]; fRec6[IOTA0 & 15] = float(input6[i0]) + fRec6[(IOTA0 - 8) & 15]; fRec7[IOTA0 & 15] = float(input7[i0]) + fRec7[(IOTA0 - 9) & 15]; fRec8[IOTA0 & 15] = float(input8[i0]) + fRec8[(IOTA0 - 10) & 15]; fRec9[IOTA0 & 15] = float(input9[i0]) + fRec9[(IOTA0 - 11) & 15]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 3] + fRec1[IOTA0 & 3] + fRec2[IOTA0 & 7] + fRec3[IOTA0 & 7] + fRec4[IOTA0 & 7] + fRec5[IOTA0 & 7] + fRec6[IOTA0 & 15] + fRec7[IOTA0 & 15] + fRec8[IOTA0 & 15] + fRec9[IOTA0 & 15]); IOTA0 = IOTA0 + 1; } } ... with buffers named fRecX instead of fVecX in the previous example. The -mcd <n> and -dlt <n> options can be used with the same purpose.","title":"Delay lines in recursive signals"},{"location":"manual/optimizing/#managing-dsp-memory-layout","text":"On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. This can be controled using the -mem compilation option and an adapted architecture file .","title":"Managing DSP Memory Layout"},{"location":"manual/optimizing/#optimizing-the-c-or-llvm-code","text":"From a given DSP program, the Faust compiler tries to generate the most efficient implementation. Optimizations can be done at DSP writing time, or later on when the target langage is generated (like C++ or LLVM IR). The generated code can have different shapes depending of compilation options, and can run faster of slower. Several programs and tools are available to help Faust programmers to test (for possible numerical or precision issues), optimize their programs by discovering the best set of options for a given DSP code, and finally compile them into native code for the target CPUs. By default the Faust compiler produces a big scalar loop in the generated mydsp::compute method. Compiler options allow to generate other code shapes , like for instance separated simpler loops connected with buffers in the so-called vectorized mode (obtained using the -vec option). The assumption is that auto-vectorizer passes in modern compilers will be able to better generate efficient SIMD code for them. In this vec option, the size of the internal buffer can be changed using the -vs value option. Moreover the computation graph can be organized in deep-first order using -dfs . Delay lines implementation can be be controlled with the -mcd size and -dlt size options, to choose for example between power-of-two sizes and mask based wrapping (faster but consumming more memory) or if based wrapping , slower but consumming less memory. Many other compilation choices are fully controllable with options. Note that the C/C++ and LLVM backends offer the greatest number of compilation options. Here are just a few of them: -clang option: when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi option: when compiled with the C++ backend, does not add the 'virtual' keyword. This option can be especially useful in embedded devices context -mapp option: simpler/faster versions of 'floor/ceil/fmod/remainder' functions (experimental) Manually testing each of them and their combination is out of reach. So several tools have been developed to automatize that process and help search the configuration space to discover the best set of compilation options (be sure to run make benchmark && sudo make devinstall in Faust toplevel folder to install the benchmark tools):","title":"Optimizing the C++ or LLVM Code"},{"location":"manual/optimizing/#faustbench","text":"The faustbench tool uses the C++ backend to generate a set of C++ files produced with different Faust compiler options. All files are then compiled in a unique binary that will measure DSP CPU of all versions of the compiled DSP. The tool is supposed to be launched in a terminal, but it can be used to generate an iOS project, ready to be launched and tested in Xcode. A more complete documentation is available on the this page .","title":"faustbench"},{"location":"manual/optimizing/#faustbench-llvm","text":"The faustbench-llvm tool uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU usage. Additional Faust compiler options can be given beside the ones that will be automatically explored by the tool. A more complete documentation is available on the this page .","title":"faustbench-llvm"},{"location":"manual/optimizing/#faust2bench","text":"The faust2bench tool allows to benchmark a given DSP program: faust2bench -h Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable So something like faust2bench -vec -lv 0 -vs 4 foo.dsp is used to produce an executable, then launching ./foo gives : ./foo ./foo : 303.599 MBytes/sec (DSP CPU % : 0.224807 at 44100 Hz) The -inj option allows to possibly inject and benchmark an external C++ class to be adapted to behave as a dsp class, like in the following adapted.cpp example. The inherited compute method is rewritten to call the external C++ limiterStereo.SetPreGain etc... code to update the controllers, and the method limiterStereo.Process which computes the DSP: #include \"faust/dsp/dsp.h\" #include \"Limiter.hpp\" struct mydsp : public dsp { Limiter<float> limiterStereo; void init(int sample_rate) { limiterStereo.SetSR(sample_rate); } int getNumInputs() { return 2; } int getNumOutputs() { return 2; } int getSampleRate() { return 44100; } void instanceInit(int sample_rate) {} void instanceConstants(int sample_rate) {} void instanceResetUserInterface() {} void instanceClear() {} void buildUserInterface(UI* ui_interface) {} dsp* clone() { return new mydsp(); } void metadata(Meta* m) {} void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { limiterStereo.SetPreGain(0.5); limiterStereo.SetAttTime(0.5); limiterStereo.SetHoldTime(0.5); limiterStereo.SetRelTime(0.5); limiterStereo.SetThreshold(0.5); limiterStereo.Process(inputs, outputs, count); } }; Using faust2bench -inj adapted.cpp dummy.dsp creates the executable to be tested with ./dummy (remember that dummy.dsp is a program that is not actually used in -inj mode).","title":"faust2bench"},{"location":"manual/optimizing/#dynamic-faust","text":"The dynamic-faust tool uses the dynamic compilation chain (based on the LLVM backend), and compiles a Faust DSP source to a LLVM IR (.ll), bicode (.bc), machine code (.mc) or object code (.o) output file. This is an alternative to the C++ compilation chain, since DSP code can be compiled to object code (.o), then used and linked in a regular C++ project. A more complete documentation is available on the this page .","title":"dynamic-faust"},{"location":"manual/optimizing/#optimizing-with-any-faust2xx-tool","text":"All faust2xx tools compile in scalar mode by default, but can take any combination of optimal options (like -vec -fun -vs 32 -dfs -mcd 32 for instance) the previously described tools will automatically find. So by chaining the use of faustbench of faustbench-llvm to discover the best compilation options for a given DSP, then use them in the desired faust2xx tool, a CPU optimized standalone or plugin can be obtained. Note that some faust2xx tools like faust2max6 or faust2caqt can internally call the faustbench-llvm tool to discover and later on use the best possible compilation options.","title":"Optimizing with any faust2xx tool"},{"location":"manual/optimizing/#compiling-for-multiple-cpus","text":"On modern CPUs, compiling native code dedicated to the target processor is critical to obtain the best possible performances. When using the C++ backend, the same C++ file can be compiled with gcc of clang for each possible target CPU using the appropriate -march=cpu option. When using the LLVM backend, the same LLVM IR code can be compiled into CPU specific machine code using the dynamic-faust tool. This step will typically be done using the best compilation options automatically found with the faustbench tool or faustbench-llvm tools. A specialized tool has been developed to combine all the possible options.","title":"Compiling for Multiple CPUs"},{"location":"manual/optimizing/#faust2object","text":"The faust2object tool either uses the standard C++ compiler or the LLVM dynamic compilation chain (the dynamic-faust tool) to compile a Faust DSP to object code files (.o) and wrapper C++ header files for different CPUs. The DSP name is used in the generated C++ and object code files, thus allowing to generate distinct versions of the code that can finally be linked together in a single binary. A more complete documentation is available on the this page .","title":"faust2object"},{"location":"manual/options/","text":"Faust Compiler Options FAUST compiler version 2.74.6 usage : faust [options] file1 [file2 ...]. where options represent zero or more compiler options and fileN represents a Faust source file (.dsp extension). Input options: -a <file> wrapper architecture file. -i --inline-architecture-files inline architecture files. -A <dir> --architecture-dir <dir> add the directory <dir> to the architecture search path. -I <dir> --import-dir <dir> add the directory <dir> to the libraries search path. -L <file> --library <file> link with the LLVM module <file>. Output options: -o <file> the output file. -e --export-dsp export expanded DSP (with all included libraries). -uim --user-interface-macros add user interface macro definitions to the output code. -xml generate an XML description file. -json generate a JSON description file. -O <dir> --output-dir <dir> specify the relative directory of the generated output code and of additional generated files (SVG, XML...). Code generation options: -lang <lang> --language select output language, 'lang' should be c, cpp (default), cmajor, codebox, csharp, dlang, fir, interp, java, jax, jsfx, julia, llvm, ocpp, rust, vhdl or wast/wasm. -single --single-precision-floats use single precision floats for internal computations (default). -double --double-precision-floats use double precision floats for internal computations. -quad --quad-precision-floats use quad precision floats for internal computations. -fx --fixed-point use fixed-point for internal computations. -fx-size --fixed-point-size fixed-point number total size in bits (-1 is used to generate a unique fixpoint_t type). -es 1|0 --enable-semantics 1|0 use enable semantics when 1 (default), and simple multiplication otherwise. -lcc --local-causality-check check causality also at local level. -light --light-mode do not generate the entire DSP API. -clang --clang when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi --no-virtual when compiled with the C++ backend, does not add the 'virtual' keyword. -fp --full-parentheses always add parentheses around binops. -cir --check-integer-range check float to integer range conversion. -exp10 --generate-exp10 pow(10,x) replaced by possibly faster exp10(x). -os --one-sample generate one sample computation. -ec --external-control separated 'control' and 'compute' functions. -it --inline-table inline rdtable/rwtable code in the main class. -cm --compute-mix mix in outputs buffers. -ct --check-table check rtable/rwtable index range and generate safe access code [0/1: 1 by default]. -cn <name> --class-name <name> specify the name of the dsp class to be used instead of mydsp. -scn <name> --super-class-name <name> specify the name of the super class to be used instead of dsp. -pn <name> --process-name <name> specify the name of the dsp entry-point instead of process. -mcd <n> --max-copy-delay <n> use a copy delay up to max delay <n> and a dense delay above (ocpp only) or a ring buffer (defaut 16 samples). -mdd <n> --max-dense-delay <n> use a dense delay up to max delay <n> (if enough density) and a ring buffer delay above (ocpp only, default 1024). -mdy <n> --min-density <n> minimal density (100*number of delays/max delay) to use a dense delays (ocpp only, default 33). -dlt <n> --delay-line-threshold <n> use a mask-based ring buffer delays up to max delay <n> and a select based ring buffers above (default INT_MAX samples). -mem --memory-manager allocations done using a custom memory manager. -mem1 --memory-manager1 allocations done using a custom memory manager, using the iControl/fControl and iZone/fZone model. -mem2 --memory-manager2 use iControl/fControl, iZone/fZone model and no explicit memory manager. -mem3 --memory-manager3 use iControl/fControl, iZone/fZone model and no explicit memory manager with access as function parameters. -ftz <n> --flush-to-zero <n> code added to recursive signals [0:no (default), 1:fabs based, 2:mask based (fastest)]. -rui --range-ui whether to generate code to constraint vslider/hslider/nentry values in [min..max] range. -fui --freeze-ui whether to freeze vslider/hslider/nentry to a given value (init value by default). -inj <f> --inject <f> inject source file <f> into architecture file instead of compiling a dsp file. -scal --scalar generate non-vectorized code (default). -inpl --in-place generates code working when input and output buffers are the same (scalar mode only). -vec --vectorize generate easier to vectorize code. -vs <n> --vec-size <n> size of the vector (default 32 samples). -lv <n> --loop-variant <n> [0:fastest, fixed vector size and a remaining loop (default), 1:simple, variable vector size, 2:fixed, fixed vector size]. -omp --openmp generate OpenMP pragmas, activates --vectorize option. -pl --par-loop generate parallel loops in --openmp mode. -sch --scheduler generate tasks and use a Work Stealing scheduler, activates --vectorize option. -ocl --opencl generate tasks with OpenCL (experimental). -cuda --cuda generate tasks with CUDA (experimental). -dfs --deep-first-scheduling schedule vector loops in deep first order. -g --group-tasks group single-threaded sequential tasks together when -omp or -sch is used. -fun --fun-tasks separate tasks code as separated functions (in -vec, -sch, or -omp mode). -fm <file> --fast-math <file> use optimized versions of mathematical functions implemented in <file>, use 'faust/dsp/fastmath.cpp' when file is 'def', assume functions are defined in the architecture file when file is 'arch'. -mapp --math-approximation simpler/faster versions of 'floor/ceil/fmod/remainder' functions. -noreprc --no-reprc (Rust only) Don't force dsp struct layout to follow C ABI. -ns <name> --namespace <name> generate C++ or D code in a namespace <name>. -vhdl-trace --vhdl-trace activate trace. -vhdl-float --vhdl-float uses IEEE-754 format for samples instead of fixed point. -vhdl-components <file> --vhdl-components <file> path to a file describing custom components for the VHDL backend. -fpga-mem <n> --fpga-mem <n> FPGA block ram max size, used in -mem1/-mem2 mode. -wi <n> --widening-iterations <n> number of iterations before widening in signal bounding. -ni <n> --narrowing-iterations <n> number of iterations before stopping narrowing in signal bounding. Block diagram options: -ps --postscript print block-diagram to a postscript file. -svg --svg print block-diagram to a svg file. -sd --simplify-diagrams try to further simplify diagrams before drawing. -drf --draw-route-frame draw route frames instead of simple cables. -f <n> --fold <n> threshold to activate folding mode during block-diagram generation (default 25 elements). -fc <n> --fold-complexity <n> complexity threshold to fold an expression in folding mode (default 2). -mns <n> --max-name-size <n> threshold during block-diagram generation (default 40 char). -sn --simple-names use simple names (without arguments) during block-diagram generation. -blur --shadow-blur add a shadow blur to SVG boxes. -sc --scaled-svg automatic scalable SVG. Math doc options: -mdoc --mathdoc print math documentation of the Faust program in LaTeX format in a -mdoc folder. -mdlang <l> --mathdoc-lang <l> if translation file exists (<l> = en, fr, ...). -stripmdoc --strip-mdoc-tags strip mdoc tags when printing Faust -mdoc listings. Debug options: -d --details print compilation details. -time --compilation-time display compilation phases timing information. -flist --file-list print file list (including libraries) used to eval process. -tg --task-graph print the internal task graph in dot format. -sg --signal-graph print the internal signal graph in dot format. -norm --normalized-form print signals in normalized form and exit. -me --math-exceptions check / for 0 as denominator and remainder, fmod, sqrt, log10, log, acos, asin functions domain. -sts --strict-select generate strict code for 'selectX' even for stateless branches (both are computed). -wall --warning-all print all warnings. -t <sec> --timeout <sec> abort compilation after <sec> seconds (default 120). Information options: -h --help print this help message. -v --version print version information and embedded backends list. -libdir --libdir print directory containing the Faust libraries. -includedir --includedir print directory containing the Faust headers. -archdir --archdir print directory containing the Faust architectures. -dspdir --dspdir print directory containing the Faust dsp libraries. -pathslist --pathslist print the architectures and dsp library paths. Example: faust -a jack-gtk.cpp -o myfx.cpp myfx.dsp","title":"Compiler Options"},{"location":"manual/options/#faust-compiler-options","text":"","title":"Faust Compiler Options"},{"location":"manual/options/#faust-compiler-version-2746","text":"usage : faust [options] file1 [file2 ...]. where options represent zero or more compiler options and fileN represents a Faust source file (.dsp extension).","title":"FAUST compiler version 2.74.6"},{"location":"manual/options/#input-options","text":"-a <file> wrapper architecture file. -i --inline-architecture-files inline architecture files. -A <dir> --architecture-dir <dir> add the directory <dir> to the architecture search path. -I <dir> --import-dir <dir> add the directory <dir> to the libraries search path. -L <file> --library <file> link with the LLVM module <file>.","title":"Input options:"},{"location":"manual/options/#output-options","text":"-o <file> the output file. -e --export-dsp export expanded DSP (with all included libraries). -uim --user-interface-macros add user interface macro definitions to the output code. -xml generate an XML description file. -json generate a JSON description file. -O <dir> --output-dir <dir> specify the relative directory of the generated output code and of additional generated files (SVG, XML...).","title":"Output options:"},{"location":"manual/options/#code-generation-options","text":"-lang <lang> --language select output language, 'lang' should be c, cpp (default), cmajor, codebox, csharp, dlang, fir, interp, java, jax, jsfx, julia, llvm, ocpp, rust, vhdl or wast/wasm. -single --single-precision-floats use single precision floats for internal computations (default). -double --double-precision-floats use double precision floats for internal computations. -quad --quad-precision-floats use quad precision floats for internal computations. -fx --fixed-point use fixed-point for internal computations. -fx-size --fixed-point-size fixed-point number total size in bits (-1 is used to generate a unique fixpoint_t type). -es 1|0 --enable-semantics 1|0 use enable semantics when 1 (default), and simple multiplication otherwise. -lcc --local-causality-check check causality also at local level. -light --light-mode do not generate the entire DSP API. -clang --clang when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi --no-virtual when compiled with the C++ backend, does not add the 'virtual' keyword. -fp --full-parentheses always add parentheses around binops. -cir --check-integer-range check float to integer range conversion. -exp10 --generate-exp10 pow(10,x) replaced by possibly faster exp10(x). -os --one-sample generate one sample computation. -ec --external-control separated 'control' and 'compute' functions. -it --inline-table inline rdtable/rwtable code in the main class. -cm --compute-mix mix in outputs buffers. -ct --check-table check rtable/rwtable index range and generate safe access code [0/1: 1 by default]. -cn <name> --class-name <name> specify the name of the dsp class to be used instead of mydsp. -scn <name> --super-class-name <name> specify the name of the super class to be used instead of dsp. -pn <name> --process-name <name> specify the name of the dsp entry-point instead of process. -mcd <n> --max-copy-delay <n> use a copy delay up to max delay <n> and a dense delay above (ocpp only) or a ring buffer (defaut 16 samples). -mdd <n> --max-dense-delay <n> use a dense delay up to max delay <n> (if enough density) and a ring buffer delay above (ocpp only, default 1024). -mdy <n> --min-density <n> minimal density (100*number of delays/max delay) to use a dense delays (ocpp only, default 33). -dlt <n> --delay-line-threshold <n> use a mask-based ring buffer delays up to max delay <n> and a select based ring buffers above (default INT_MAX samples). -mem --memory-manager allocations done using a custom memory manager. -mem1 --memory-manager1 allocations done using a custom memory manager, using the iControl/fControl and iZone/fZone model. -mem2 --memory-manager2 use iControl/fControl, iZone/fZone model and no explicit memory manager. -mem3 --memory-manager3 use iControl/fControl, iZone/fZone model and no explicit memory manager with access as function parameters. -ftz <n> --flush-to-zero <n> code added to recursive signals [0:no (default), 1:fabs based, 2:mask based (fastest)]. -rui --range-ui whether to generate code to constraint vslider/hslider/nentry values in [min..max] range. -fui --freeze-ui whether to freeze vslider/hslider/nentry to a given value (init value by default). -inj <f> --inject <f> inject source file <f> into architecture file instead of compiling a dsp file. -scal --scalar generate non-vectorized code (default). -inpl --in-place generates code working when input and output buffers are the same (scalar mode only). -vec --vectorize generate easier to vectorize code. -vs <n> --vec-size <n> size of the vector (default 32 samples). -lv <n> --loop-variant <n> [0:fastest, fixed vector size and a remaining loop (default), 1:simple, variable vector size, 2:fixed, fixed vector size]. -omp --openmp generate OpenMP pragmas, activates --vectorize option. -pl --par-loop generate parallel loops in --openmp mode. -sch --scheduler generate tasks and use a Work Stealing scheduler, activates --vectorize option. -ocl --opencl generate tasks with OpenCL (experimental). -cuda --cuda generate tasks with CUDA (experimental). -dfs --deep-first-scheduling schedule vector loops in deep first order. -g --group-tasks group single-threaded sequential tasks together when -omp or -sch is used. -fun --fun-tasks separate tasks code as separated functions (in -vec, -sch, or -omp mode). -fm <file> --fast-math <file> use optimized versions of mathematical functions implemented in <file>, use 'faust/dsp/fastmath.cpp' when file is 'def', assume functions are defined in the architecture file when file is 'arch'. -mapp --math-approximation simpler/faster versions of 'floor/ceil/fmod/remainder' functions. -noreprc --no-reprc (Rust only) Don't force dsp struct layout to follow C ABI. -ns <name> --namespace <name> generate C++ or D code in a namespace <name>. -vhdl-trace --vhdl-trace activate trace. -vhdl-float --vhdl-float uses IEEE-754 format for samples instead of fixed point. -vhdl-components <file> --vhdl-components <file> path to a file describing custom components for the VHDL backend. -fpga-mem <n> --fpga-mem <n> FPGA block ram max size, used in -mem1/-mem2 mode. -wi <n> --widening-iterations <n> number of iterations before widening in signal bounding. -ni <n> --narrowing-iterations <n> number of iterations before stopping narrowing in signal bounding.","title":"Code generation options:"},{"location":"manual/options/#block-diagram-options","text":"-ps --postscript print block-diagram to a postscript file. -svg --svg print block-diagram to a svg file. -sd --simplify-diagrams try to further simplify diagrams before drawing. -drf --draw-route-frame draw route frames instead of simple cables. -f <n> --fold <n> threshold to activate folding mode during block-diagram generation (default 25 elements). -fc <n> --fold-complexity <n> complexity threshold to fold an expression in folding mode (default 2). -mns <n> --max-name-size <n> threshold during block-diagram generation (default 40 char). -sn --simple-names use simple names (without arguments) during block-diagram generation. -blur --shadow-blur add a shadow blur to SVG boxes. -sc --scaled-svg automatic scalable SVG.","title":"Block diagram options:"},{"location":"manual/options/#math-doc-options","text":"-mdoc --mathdoc print math documentation of the Faust program in LaTeX format in a -mdoc folder. -mdlang <l> --mathdoc-lang <l> if translation file exists (<l> = en, fr, ...). -stripmdoc --strip-mdoc-tags strip mdoc tags when printing Faust -mdoc listings.","title":"Math doc options:"},{"location":"manual/options/#debug-options","text":"-d --details print compilation details. -time --compilation-time display compilation phases timing information. -flist --file-list print file list (including libraries) used to eval process. -tg --task-graph print the internal task graph in dot format. -sg --signal-graph print the internal signal graph in dot format. -norm --normalized-form print signals in normalized form and exit. -me --math-exceptions check / for 0 as denominator and remainder, fmod, sqrt, log10, log, acos, asin functions domain. -sts --strict-select generate strict code for 'selectX' even for stateless branches (both are computed). -wall --warning-all print all warnings. -t <sec> --timeout <sec> abort compilation after <sec> seconds (default 120).","title":"Debug options:"},{"location":"manual/options/#information-options","text":"-h --help print this help message. -v --version print version information and embedded backends list. -libdir --libdir print directory containing the Faust libraries. -includedir --includedir print directory containing the Faust headers. -archdir --archdir print directory containing the Faust architectures. -dspdir --dspdir print directory containing the Faust dsp libraries. -pathslist --pathslist print the architectures and dsp library paths.","title":"Information options:"},{"location":"manual/options/#example","text":"faust -a jack-gtk.cpp -o myfx.cpp myfx.dsp","title":"Example:"},{"location":"manual/osc/","text":"OSC Support Overview Most Faust architectures provide Open Sound Control (OSC) support (the implementation is based internally on the oscpack library by Ross Bencina). This allows applications to be remotely controlled from any OSC-capable application, programming language, or hardware device. OSC support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [osc:on] metadata to the standard option metadata : declare options \"[osc:on]\"; The following tables provides a list of Faust architectures providing OSC support. Linux Faust Architectures with OSC Support Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt OSX Faust Architectures with OSC Support Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt Windows Faust Architectures with OSC Support Audio System Environment Jack Qt, Console PortAudio Qt Other Faust Architectures with OSC Support Environment Android iOS JUCE Bela Simple Example To illustrate how OSC support works let's define a very simple noise generator with a level control (we'll call it noise.dsp ): This example can be compiled as a standalone Jack Qt application with OSC support simply by running the following command: faust2jaqt -osc noise.dsp When the generated application is ran from the command line: ./noise various information is printed in the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 Hence, the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \"Foo\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host sets the destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (i.e., bargraph , etc.) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that path can be a regular expression (like /freeverb/Reverb1/* ). For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination. Automatic Port Allocation In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let say that we start noise and mixer (two Faust-generated applications with OSC support) on the same machine, we'll get the following: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and opens it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications. Discovering OSC Applications The commands oscsend and oscdump from the liblo package provide a convenient mean to experiment with OSC control and potentially debug applications with OSC support. `oscsend [hostname] [port] [address] [types] [values]`: sends OSC messages via UDP. `[types]` is a string, the letters indicates the type of the following values: `i=integer`, `f=float`, `s=string`, etc. `oscdump [port]`: receives OSC messages via UDP and dump to standard output Note that OSC messages can be sent from any OSC-compatible applications (e.g., PureData, Max/MSP, etc.). In the following examples, we'll use two separate terminal windows. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . Commands executed on terminal 1 will be preceded by T1$ . Messages received on terminal 2 will be preceded by T2: . To monitor on terminal T2 the OSC messages received on UDP port 5511, oscdump will be used: T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for Faust applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512 Discovering the OSC Interface of an Application The OSC interface of an application (the set of OSC messages we can use to control it) can be discovered by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer to this OSC message, a full description is printed in terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the OSC interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is 127.0.0.1 , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 . Widget's OSC Address Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a dmute button and a level slider: If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see, each widget has a unique OSC address obtained by concatenating the top level group label \"mixer,\" with the \"input\" group label and the widget label (see the Labels as Pathnames Section ). Please, note that blank spaces are replaced by underscores and metadata are removed during this operation. All addresses must have a common root. This is the case in our example because there is a unique horizontal group mixer containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000 Controlling the Application Via OSC Any user interface element of the application can be controlled by sending one of the previously discovered messages/addresses. For example, to set the noise level of the application to 0.2 the following message can be sent: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000 Turning Transmission ON The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For example: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS ( xmit = 2 ) mode if you need to restrict the access to your program: when the ALIAS mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements ( bargraph ) will only emit on their aliases. Filtering OSC Messages When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter Using OSC Aliases Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our previous noise example with TouchOSC on Android. The first step is to configure the TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510 . Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510 ) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of \"simple layout\". Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because the range of /1/fader1 is 0 to 1 (like the level slider), we can remove the range mapping information and write simply : import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1]\",0,0,1,0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer . Using again oscdump 5510 we can visualize the messages sent by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see, TouchOSC sends the x, y and z accelerometers in a single message, as a triplet of values ranging approximately from -9.81 to 9.81. In order to select the appropriate accelerometer, we need to concatenate to /accxyz a suffix /0 , /1 or /2 . For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: import(\"stdfaust.lib\"); process = no.noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer **_Examples of OSC Message Aliases for TouchOSC (Layout Mix2)._** OSC Cheat Sheet Default Ports Port Description 5510 default listening port 5511 default transmission port 5512 default error port 5513 alternative listening ports Command Line Options Option Description -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time Discovery Messages Message Description oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port Control Messages Message Description oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value Alias Alias Description \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc:' address]...\" alias with min , max clipping DSP with polyphonic support When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0","title":"OSC Support"},{"location":"manual/osc/#osc-support","text":"","title":"OSC Support"},{"location":"manual/osc/#overview","text":"Most Faust architectures provide Open Sound Control (OSC) support (the implementation is based internally on the oscpack library by Ross Bencina). This allows applications to be remotely controlled from any OSC-capable application, programming language, or hardware device. OSC support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [osc:on] metadata to the standard option metadata : declare options \"[osc:on]\"; The following tables provides a list of Faust architectures providing OSC support.","title":"Overview"},{"location":"manual/osc/#linux-faust-architectures-with-osc-support","text":"Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt","title":"Linux Faust Architectures with OSC Support"},{"location":"manual/osc/#osx-faust-architectures-with-osc-support","text":"Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt","title":"OSX Faust Architectures with OSC Support"},{"location":"manual/osc/#windows-faust-architectures-with-osc-support","text":"Audio System Environment Jack Qt, Console PortAudio Qt","title":"Windows Faust Architectures with OSC Support"},{"location":"manual/osc/#other-faust-architectures-with-osc-support","text":"Environment Android iOS JUCE Bela","title":"Other Faust Architectures with OSC Support"},{"location":"manual/osc/#simple-example","text":"To illustrate how OSC support works let's define a very simple noise generator with a level control (we'll call it noise.dsp ): This example can be compiled as a standalone Jack Qt application with OSC support simply by running the following command: faust2jaqt -osc noise.dsp When the generated application is ran from the command line: ./noise various information is printed in the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 Hence, the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \"Foo\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host sets the destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (i.e., bargraph , etc.) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that path can be a regular expression (like /freeverb/Reverb1/* ). For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination.","title":"Simple Example"},{"location":"manual/osc/#automatic-port-allocation","text":"In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let say that we start noise and mixer (two Faust-generated applications with OSC support) on the same machine, we'll get the following: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and opens it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications.","title":"Automatic Port Allocation"},{"location":"manual/osc/#discovering-osc-applications","text":"The commands oscsend and oscdump from the liblo package provide a convenient mean to experiment with OSC control and potentially debug applications with OSC support. `oscsend [hostname] [port] [address] [types] [values]`: sends OSC messages via UDP. `[types]` is a string, the letters indicates the type of the following values: `i=integer`, `f=float`, `s=string`, etc. `oscdump [port]`: receives OSC messages via UDP and dump to standard output Note that OSC messages can be sent from any OSC-compatible applications (e.g., PureData, Max/MSP, etc.). In the following examples, we'll use two separate terminal windows. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . Commands executed on terminal 1 will be preceded by T1$ . Messages received on terminal 2 will be preceded by T2: . To monitor on terminal T2 the OSC messages received on UDP port 5511, oscdump will be used: T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for Faust applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512","title":"Discovering OSC Applications"},{"location":"manual/osc/#discovering-the-osc-interface-of-an-application","text":"The OSC interface of an application (the set of OSC messages we can use to control it) can be discovered by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer to this OSC message, a full description is printed in terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the OSC interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is 127.0.0.1 , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 .","title":"Discovering the OSC Interface of an Application"},{"location":"manual/osc/#widgets-osc-address","text":"Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a dmute button and a level slider: If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see, each widget has a unique OSC address obtained by concatenating the top level group label \"mixer,\" with the \"input\" group label and the widget label (see the Labels as Pathnames Section ). Please, note that blank spaces are replaced by underscores and metadata are removed during this operation. All addresses must have a common root. This is the case in our example because there is a unique horizontal group mixer containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000","title":"Widget's OSC Address"},{"location":"manual/osc/#controlling-the-application-via-osc","text":"Any user interface element of the application can be controlled by sending one of the previously discovered messages/addresses. For example, to set the noise level of the application to 0.2 the following message can be sent: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000","title":"Controlling the Application Via OSC"},{"location":"manual/osc/#turning-transmission-on","text":"The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For example: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS ( xmit = 2 ) mode if you need to restrict the access to your program: when the ALIAS mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements ( bargraph ) will only emit on their aliases.","title":"Turning Transmission ON"},{"location":"manual/osc/#filtering-osc-messages","text":"When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter","title":"Filtering OSC Messages"},{"location":"manual/osc/#using-osc-aliases","text":"Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our previous noise example with TouchOSC on Android. The first step is to configure the TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510 . Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510 ) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of \"simple layout\". Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because the range of /1/fader1 is 0 to 1 (like the level slider), we can remove the range mapping information and write simply : import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1]\",0,0,1,0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer . Using again oscdump 5510 we can visualize the messages sent by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see, TouchOSC sends the x, y and z accelerometers in a single message, as a triplet of values ranging approximately from -9.81 to 9.81. In order to select the appropriate accelerometer, we need to concatenate to /accxyz a suffix /0 , /1 or /2 . For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: import(\"stdfaust.lib\"); process = no.noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer **_Examples of OSC Message Aliases for TouchOSC (Layout Mix2)._**","title":"Using OSC Aliases"},{"location":"manual/osc/#osc-cheat-sheet","text":"","title":"OSC Cheat Sheet"},{"location":"manual/osc/#default-ports","text":"Port Description 5510 default listening port 5511 default transmission port 5512 default error port 5513 alternative listening ports","title":"Default Ports"},{"location":"manual/osc/#command-line-options","text":"Option Description -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time","title":"Command Line Options"},{"location":"manual/osc/#discovery-messages","text":"Message Description oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port","title":"Discovery Messages"},{"location":"manual/osc/#control-messages","text":"Message Description oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value","title":"Control Messages"},{"location":"manual/osc/#alias","text":"Alias Description \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc:' address]...\" alias with min , max clipping","title":"Alias"},{"location":"manual/osc/#dsp-with-polyphonic-support","text":"When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0","title":"DSP with polyphonic support"},{"location":"manual/overview/","text":"Overview of the Faust Universe While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This chapter provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust Distribution The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust architectures (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the Faust DSP Libraries (which in practice are hosted a separate Git submodule), etc. The latest stable release of the Faust distribution can be found here . It is recommended for most Faust users willing to compile the Faust compiler and libfaust from scratch. To have the latest stable development version, you can use the master branch of the Faust git repository which is hosted on GitHub. For something even more bleeding edge (to be used at your own risks), you might use the master-dev branch of the Faust git repository . master-dev is the development sub-branch of master . It is used by Faust developers to commit their changes and can be considered as \"the main development branch\". The goal is to make sure that master is always functional. Merges between master-dev and master are carried out at each stable release by the GRAME team. Also, note that pre-compiled packages of the Faust compiler and of libfaust for various platforms can be found on the of the Faust website . The Faust distribution is organized as follows: bin/ : contains the compiler and the [Faust tools](../tools) include/ : contains header files required by the Faust tools lib/ : contains the Faust libraries share/ : contains documentation, the Faust libraries and architecture files Note : you can install the Faust distribution anywhere you want, provided that the faust command is available from your PATH (requires to update your .profile if not in a standard location). The following subsections present the main tools build on top of the Faust compiler and intended to facilitate your life. Faust IDE Faust IDE is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures, but also various utilities for signal processing development. Faust Editor Faust Editor is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures. Faust Playground Faust Playground is a graphical environment to develop Faust programs with a higher level approach. It has been initially designed for kids and for pedagogical purpose. Faustgen Faustgen is a Max/MSP external that provides features similar to FaustLive. It's the ideal tool for fast prototyping in Max/MSP. Faustgen is part of the Faust project, and distributed in the Faust releases . FaustLive 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. It supports also native applications generation using the Faust online compiler. Note that FaustLive is regularly recompiled, but is no more developed, so Faust IDE is the recommended tool to use .","title":"Overview of the Faust Universe"},{"location":"manual/overview/#overview-of-the-faust-universe","text":"While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This chapter provides an overview of their role and will hopefully help you decide which one is better suited for your personal use.","title":"Overview of the Faust Universe"},{"location":"manual/overview/#the-faust-distribution","text":"The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust architectures (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the Faust DSP Libraries (which in practice are hosted a separate Git submodule), etc. The latest stable release of the Faust distribution can be found here . It is recommended for most Faust users willing to compile the Faust compiler and libfaust from scratch. To have the latest stable development version, you can use the master branch of the Faust git repository which is hosted on GitHub. For something even more bleeding edge (to be used at your own risks), you might use the master-dev branch of the Faust git repository . master-dev is the development sub-branch of master . It is used by Faust developers to commit their changes and can be considered as \"the main development branch\". The goal is to make sure that master is always functional. Merges between master-dev and master are carried out at each stable release by the GRAME team. Also, note that pre-compiled packages of the Faust compiler and of libfaust for various platforms can be found on the of the Faust website . The Faust distribution is organized as follows: bin/ : contains the compiler and the [Faust tools](../tools) include/ : contains header files required by the Faust tools lib/ : contains the Faust libraries share/ : contains documentation, the Faust libraries and architecture files Note : you can install the Faust distribution anywhere you want, provided that the faust command is available from your PATH (requires to update your .profile if not in a standard location). The following subsections present the main tools build on top of the Faust compiler and intended to facilitate your life.","title":"The Faust Distribution"},{"location":"manual/overview/#faust-ide","text":"Faust IDE is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures, but also various utilities for signal processing development.","title":"Faust IDE"},{"location":"manual/overview/#faust-editor","text":"Faust Editor is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures.","title":"Faust Editor"},{"location":"manual/overview/#faust-playground","text":"Faust Playground is a graphical environment to develop Faust programs with a higher level approach. It has been initially designed for kids and for pedagogical purpose.","title":"Faust Playground"},{"location":"manual/overview/#faustgen","text":"Faustgen is a Max/MSP external that provides features similar to FaustLive. It's the ideal tool for fast prototyping in Max/MSP. Faustgen is part of the Faust project, and distributed in the Faust releases .","title":"Faustgen"},{"location":"manual/overview/#faustlive","text":"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. It supports also native applications generation using the Faust online compiler. Note that FaustLive is regularly recompiled, but is no more developed, so Faust IDE is the recommended tool to use .","title":"FaustLive"},{"location":"manual/quick-start/","text":"Quick Start The goal of this section is to teach you how to use the basic elements of the Faust programming language in approximately two hours! While DSP algorithms can be easily written from scratch in Faust, we'll just show you here how to use existing elements implemented in the Faust libraries , connect them to each other, and implement basic user interfaces (UI) to control them. One of the strength of Faust lies in its libraries that implement hundreds of functions. So you should be able to go a long way after reading this section, simply by using what's already out here. This tutorial was written assuming that the reader is already familiar with basic concepts of computer music and programming. More generally, at the end of this section: your Faust development environment should be up and running, you should know enough to write basic Faust programs, you should be able to use them on different platforms. This tutorial was designed to be carried out in the Faust Online IDE (with its documentation ). If you wish to do it locally, you'll have to install Faust on your system but this step is absolutely not required, Making Sound Write the following code in the Faust Online IDE : and then click on the \"run\" button on the top left corner. Alternatively, you can also click on the \"Try it Yourself\" button of the window above if you're reading the online version of this documentation. You should now hear white noise, of course... ;) stdfaust.lib gives access to all the Faust libraries from a single point through a series of environments. For instance, we're using here the no environment which stands for noise.lib and the noise function (which is the standard white noise generator of Faust). The Faust Libraries Documentation provides more details about this system. The most fundamental element of any Faust code is the process line, which gives access to the audio inputs and outputs of the target. This system is completely dynamic and since no.noise has only one output and no input, the corresponding program will have a single output. Let's statically change the gain of the output of no.noise simply by multiplying it by a number between 0 and 1: process = no.noise*0.5; Thus, standard mathematical operations can be used in Faust just like in any other language. We'll now connect the noise generator to a resonant lowpass filter ( fi.resonlp ) by using the Faust sequential composition operator : : fi.resonlp has four arguments (in order): cut-off frequency , q , gain and its input . Note that you can have a quick look of what the arguments of a function are simply by hovering it in the online IDE. Here, we're setting the first three arguments with fixed variables. Variables don't have a type in Faust and everything is considered as a signal. The Faust compiler takes care of making the right optimizations by choosing which variable is ran at audio rate, what their types are, etc. Thus, ctFreq , q and gain could well be controlled by oscillators (i.e., signals running at audio rate) here. Since the input of the filter is not specified as an argument here (but it could, of course), it automatically becomes an \"implicit\" input/argument of fi.resonlp . The : sequential composition operator can be used to connect two elements that have the same number of outputs and inputs. Since no.noise has one output and fi.resonlp(ctFreq,q,gain) has one implicit input, we can connect them together. This is essentially the same as writing something like: While this would work, it's kind of ugly and not very \"Faustian\", so we don't do it... ;) At this point, you should be able to use and plug various elements of the Faust libraries together. The Faust libraries implement hundreds of functions and some of them have a very specialized use. Fortunately, the Faust libraries documentation contains a section on Standard Faust Libraries listing all the high level \"standard\" Faust functions organized by types. We recommend you to have a look at it now . As you do this, be aware that implicit signals in Faust can be explicitly represented with the _ character. Thus, when you see something like this in the libraries documentation: _ : aFunction(a,b) : _ it means that this function has one implicit input, one implicit output and two parameters ( a and b ). On the other hand: anotherFunction(a,b,c) : _,_ is a function that has three parameters, no implicit input and two outputs. Just for \"fun,\" try to rewrite the previous example running in the Faust online editor so that the process line looks like this: Of course, this should not affect the result. You probably noticed that we used the , Faust composition operator to express two signals in parallel . We can easily turn our filtered noise example into a stereo object using it: or we could even write this in a cleaner way: Note that this example allows us to have 2 separate filters for each channel. Since both filters currently have the same parameters, another way of writing this could be: process = no.noise : filter <: _,_; . You could think of the first form as a same noise signal splitted and then filtered on left and right channels, and the second form as the filtered noise then splitted on left and right channels. But the compiler understand that the same filtered noise will be produced on left and right channels in both cases. So the filtered noise signal can be computed only once and used on left and right channels. For the two progams, the compiler will actually generate the exact same optimized code ! This is a very powerful property of its semantically driven compilation model . Since filter,filter is considered here as a full expression, we cannot use the : operator to connect no.noise to the two filters in parallel because filter,filter has two inputs ( _,_ : filter,filter : _,_ ) and no.noise only has one output. The <: split composition operator used here takes n signals and splits them into m signals. The only rule is that m has to be a multiple of n . The merge :> composition operator can be used exactly the same way: import(\"stdfaust.lib\"); process = no.noise <: filter,filter :> _; Here we split the signal of no.noise into two signals that are connected to two filters in parallel. Finally, we merge the outputs of the filters into one signal. Note, that the previous expression could have been written as such too: import(\"stdfaust.lib\"); process = no.noise <: filter+filter; Keep in mind that splitting a signal doesn't mean that its energy get spread in each copy, for example, in the expression: the two _ both contain 1... All right, it's now time to add a basic user interface to our Faust program to make things a bit more interactive. Building a Simple User Interface In this section, we'll add a simple user interface to the code that we wrote in the previous section: Faust allows us to declare basic user interface (UI) elements to control the parameters of a Faust object. Since Faust can be used to make a wide range of elements ranging from standalone applications to audio plug-ins or API, the role of UI declarations differs a little in function of the target. For example, in the Faust Online Editor, a UI is a window with various kind of controllers (sliders, buttons, etc.). On the other hand, if you're using Faust to generate an audio engine using faust2api , then UI elements declared in your Faust code will be the parameters visible to \"the rest of the world\" and controllable through the API. An exhaustive list of the standard Faust UI elements is given in the corresponding section . Be aware that they not all supported by all the Faust targets. For example, you wont be able to declare vertical sliders if you're using the Faust Playground , etc. In the current case, we'd like to control the ctFreq , q and gain parameters of the previous program with horizontal sliders. To do this, we can write something like: The first argument of hslider is the name of the parameter as it will be displayed in the interface or used in the API (it can be different from the name of the variable associated with the UI element), the next one is the default value , then the min and max values and finally the step . To summarize: hslider(\"paramName\",default,min,max,step) . Let's now add a \"gate\" button to start and stop the sound (where gate is just the name of the button): Note that we were able to order parameters in the interface by numbering them in the parameter name field using squared brackets. Faust user interface elements run at control rate. Thus, you might have noticed that clicks are produced when moving sliders quickly. This problem can be easily solved by \"smoothing\" down the output of the sliders using the si.smoo function: Note that we're also using si.smoo on the output of the gate button to apply a exponential envelope on its signal. This is a very broad introduction to making user interface elements in Faust. You can do much more like creating groups, using knobs, different types of menus, etc. but at least you should be able to make Faust programs at this point that are controllable and sound good (or not ;) ). Final Polishing Some Faust functions already contain a built-in UI and are ready-to-be-used. These functions are all placed in demo.lib and are accessible through the dm. environment. As an example, let's add a reverb to our previous code by calling dm.zita_light (high quality feedback delay network based reverb). Since this function has two implicit inputs, we also need to split the output of the filter (otherwise you will get an error because Faust wont know how to connect things): Hopefully, you should see many more UI elements in your interface. That's it folks! At this point you should be able to use Faust standard functions , connect them together and build a simple UI at the top of them. Some Project Ideas In this section, we present a couple of project ideas that you could try to implement using Faust standard functions . Also, feel free to check the /examples folder of the Faust repository . Additive Synthesizer Make an additive synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // freqs and gains definitions go here process = os.osc(freq0)*gain0, os.osc(freq2)*gain2 :> _ // merging signals here <: dm.zita_light; // and then splitting them for stereo in FM Synthesizer Make a frequency modulation (FM) synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // carrierFreq, modulatorFreq and index definitions go here process = os.osc(carrierFreq+os.osc(modulatorFreq)*index) <: dm.zita_light; // splitting signals for stereo in Guitar Effect Chain Make a guitar effect chain: Since we're only using functions from demo.lib here, there's no need to define any UI since it is built-in in the functions that we're calling. Note that the mono output of dm.wah4_demo is split to fit the stereo input of dm.phaser2_demo . The last three effects have the same number of inputs and outputs (2x2) so no need to split or merge them. String Physical Model Based On a Comb Filter Make a string physical model based on a feedback comb filter: import(\"stdfaust.lib\"); // freq, res and gate definitions go here string(frequency,resonance,trigger) = trigger : ba.impulsify : fi.fb_fcomb(1024,del,1,resonance) with { del = ma.SR/frequency; }; process = string(freq,res,gate); Sampling rate is defined in maths.lib as SR . We're using it here to compute the length of the delay of the comb filter. with{} is a Faust primitive to attach local variables to a function. So in the current case, del is a local variable of string .","title":"Quick Start"},{"location":"manual/quick-start/#quick-start","text":"The goal of this section is to teach you how to use the basic elements of the Faust programming language in approximately two hours! While DSP algorithms can be easily written from scratch in Faust, we'll just show you here how to use existing elements implemented in the Faust libraries , connect them to each other, and implement basic user interfaces (UI) to control them. One of the strength of Faust lies in its libraries that implement hundreds of functions. So you should be able to go a long way after reading this section, simply by using what's already out here. This tutorial was written assuming that the reader is already familiar with basic concepts of computer music and programming. More generally, at the end of this section: your Faust development environment should be up and running, you should know enough to write basic Faust programs, you should be able to use them on different platforms. This tutorial was designed to be carried out in the Faust Online IDE (with its documentation ). If you wish to do it locally, you'll have to install Faust on your system but this step is absolutely not required,","title":"Quick Start"},{"location":"manual/quick-start/#making-sound","text":"Write the following code in the Faust Online IDE : and then click on the \"run\" button on the top left corner. Alternatively, you can also click on the \"Try it Yourself\" button of the window above if you're reading the online version of this documentation. You should now hear white noise, of course... ;) stdfaust.lib gives access to all the Faust libraries from a single point through a series of environments. For instance, we're using here the no environment which stands for noise.lib and the noise function (which is the standard white noise generator of Faust). The Faust Libraries Documentation provides more details about this system. The most fundamental element of any Faust code is the process line, which gives access to the audio inputs and outputs of the target. This system is completely dynamic and since no.noise has only one output and no input, the corresponding program will have a single output. Let's statically change the gain of the output of no.noise simply by multiplying it by a number between 0 and 1: process = no.noise*0.5; Thus, standard mathematical operations can be used in Faust just like in any other language. We'll now connect the noise generator to a resonant lowpass filter ( fi.resonlp ) by using the Faust sequential composition operator : : fi.resonlp has four arguments (in order): cut-off frequency , q , gain and its input . Note that you can have a quick look of what the arguments of a function are simply by hovering it in the online IDE. Here, we're setting the first three arguments with fixed variables. Variables don't have a type in Faust and everything is considered as a signal. The Faust compiler takes care of making the right optimizations by choosing which variable is ran at audio rate, what their types are, etc. Thus, ctFreq , q and gain could well be controlled by oscillators (i.e., signals running at audio rate) here. Since the input of the filter is not specified as an argument here (but it could, of course), it automatically becomes an \"implicit\" input/argument of fi.resonlp . The : sequential composition operator can be used to connect two elements that have the same number of outputs and inputs. Since no.noise has one output and fi.resonlp(ctFreq,q,gain) has one implicit input, we can connect them together. This is essentially the same as writing something like: While this would work, it's kind of ugly and not very \"Faustian\", so we don't do it... ;) At this point, you should be able to use and plug various elements of the Faust libraries together. The Faust libraries implement hundreds of functions and some of them have a very specialized use. Fortunately, the Faust libraries documentation contains a section on Standard Faust Libraries listing all the high level \"standard\" Faust functions organized by types. We recommend you to have a look at it now . As you do this, be aware that implicit signals in Faust can be explicitly represented with the _ character. Thus, when you see something like this in the libraries documentation: _ : aFunction(a,b) : _ it means that this function has one implicit input, one implicit output and two parameters ( a and b ). On the other hand: anotherFunction(a,b,c) : _,_ is a function that has three parameters, no implicit input and two outputs. Just for \"fun,\" try to rewrite the previous example running in the Faust online editor so that the process line looks like this: Of course, this should not affect the result. You probably noticed that we used the , Faust composition operator to express two signals in parallel . We can easily turn our filtered noise example into a stereo object using it: or we could even write this in a cleaner way: Note that this example allows us to have 2 separate filters for each channel. Since both filters currently have the same parameters, another way of writing this could be: process = no.noise : filter <: _,_; . You could think of the first form as a same noise signal splitted and then filtered on left and right channels, and the second form as the filtered noise then splitted on left and right channels. But the compiler understand that the same filtered noise will be produced on left and right channels in both cases. So the filtered noise signal can be computed only once and used on left and right channels. For the two progams, the compiler will actually generate the exact same optimized code ! This is a very powerful property of its semantically driven compilation model . Since filter,filter is considered here as a full expression, we cannot use the : operator to connect no.noise to the two filters in parallel because filter,filter has two inputs ( _,_ : filter,filter : _,_ ) and no.noise only has one output. The <: split composition operator used here takes n signals and splits them into m signals. The only rule is that m has to be a multiple of n . The merge :> composition operator can be used exactly the same way: import(\"stdfaust.lib\"); process = no.noise <: filter,filter :> _; Here we split the signal of no.noise into two signals that are connected to two filters in parallel. Finally, we merge the outputs of the filters into one signal. Note, that the previous expression could have been written as such too: import(\"stdfaust.lib\"); process = no.noise <: filter+filter; Keep in mind that splitting a signal doesn't mean that its energy get spread in each copy, for example, in the expression: the two _ both contain 1... All right, it's now time to add a basic user interface to our Faust program to make things a bit more interactive.","title":"Making Sound"},{"location":"manual/quick-start/#building-a-simple-user-interface","text":"In this section, we'll add a simple user interface to the code that we wrote in the previous section: Faust allows us to declare basic user interface (UI) elements to control the parameters of a Faust object. Since Faust can be used to make a wide range of elements ranging from standalone applications to audio plug-ins or API, the role of UI declarations differs a little in function of the target. For example, in the Faust Online Editor, a UI is a window with various kind of controllers (sliders, buttons, etc.). On the other hand, if you're using Faust to generate an audio engine using faust2api , then UI elements declared in your Faust code will be the parameters visible to \"the rest of the world\" and controllable through the API. An exhaustive list of the standard Faust UI elements is given in the corresponding section . Be aware that they not all supported by all the Faust targets. For example, you wont be able to declare vertical sliders if you're using the Faust Playground , etc. In the current case, we'd like to control the ctFreq , q and gain parameters of the previous program with horizontal sliders. To do this, we can write something like: The first argument of hslider is the name of the parameter as it will be displayed in the interface or used in the API (it can be different from the name of the variable associated with the UI element), the next one is the default value , then the min and max values and finally the step . To summarize: hslider(\"paramName\",default,min,max,step) . Let's now add a \"gate\" button to start and stop the sound (where gate is just the name of the button): Note that we were able to order parameters in the interface by numbering them in the parameter name field using squared brackets. Faust user interface elements run at control rate. Thus, you might have noticed that clicks are produced when moving sliders quickly. This problem can be easily solved by \"smoothing\" down the output of the sliders using the si.smoo function: Note that we're also using si.smoo on the output of the gate button to apply a exponential envelope on its signal. This is a very broad introduction to making user interface elements in Faust. You can do much more like creating groups, using knobs, different types of menus, etc. but at least you should be able to make Faust programs at this point that are controllable and sound good (or not ;) ).","title":"Building a Simple User Interface"},{"location":"manual/quick-start/#final-polishing","text":"Some Faust functions already contain a built-in UI and are ready-to-be-used. These functions are all placed in demo.lib and are accessible through the dm. environment. As an example, let's add a reverb to our previous code by calling dm.zita_light (high quality feedback delay network based reverb). Since this function has two implicit inputs, we also need to split the output of the filter (otherwise you will get an error because Faust wont know how to connect things): Hopefully, you should see many more UI elements in your interface. That's it folks! At this point you should be able to use Faust standard functions , connect them together and build a simple UI at the top of them.","title":"Final Polishing"},{"location":"manual/quick-start/#some-project-ideas","text":"In this section, we present a couple of project ideas that you could try to implement using Faust standard functions . Also, feel free to check the /examples folder of the Faust repository .","title":"Some Project Ideas"},{"location":"manual/quick-start/#additive-synthesizer","text":"Make an additive synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // freqs and gains definitions go here process = os.osc(freq0)*gain0, os.osc(freq2)*gain2 :> _ // merging signals here <: dm.zita_light; // and then splitting them for stereo in","title":"Additive Synthesizer"},{"location":"manual/quick-start/#fm-synthesizer","text":"Make a frequency modulation (FM) synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // carrierFreq, modulatorFreq and index definitions go here process = os.osc(carrierFreq+os.osc(modulatorFreq)*index) <: dm.zita_light; // splitting signals for stereo in","title":"FM Synthesizer"},{"location":"manual/quick-start/#guitar-effect-chain","text":"Make a guitar effect chain: Since we're only using functions from demo.lib here, there's no need to define any UI since it is built-in in the functions that we're calling. Note that the mono output of dm.wah4_demo is split to fit the stereo input of dm.phaser2_demo . The last three effects have the same number of inputs and outputs (2x2) so no need to split or merge them.","title":"Guitar Effect Chain"},{"location":"manual/quick-start/#string-physical-model-based-on-a-comb-filter","text":"Make a string physical model based on a feedback comb filter: import(\"stdfaust.lib\"); // freq, res and gate definitions go here string(frequency,resonance,trigger) = trigger : ba.impulsify : fi.fb_fcomb(1024,del,1,resonance) with { del = ma.SR/frequency; }; process = string(freq,res,gate); Sampling rate is defined in maths.lib as SR . We're using it here to compute the length of the delay of the comb filter. with{} is a Faust primitive to attach local variables to a function. So in the current case, del is a local variable of string .","title":"String Physical Model Based On a Comb Filter"},{"location":"manual/remote/","text":"Remote compilation Compiling a same Faust DSP program on different platforms and targets (applications and plugins) can be a tedious task when SDKs have to be installed and configurated, or when the user want to do cross-compilation. A remote compilation service has been developed to simplify this process. It allows to send DSP source code on a cloud based infrastructure, which hosts a lot of targets and can do cross-compilation. This service is accessible: in several applications like FaustLive , Faust Editor or Faust IDE with a dedicated API explained in more details in the faustservice project and in the FaustWeb client tool with the faustremote script (part of the Faust distribution), which allows to access the remote compilation service and execute compilation requests.","title":"Remote Compilation"},{"location":"manual/remote/#remote-compilation","text":"Compiling a same Faust DSP program on different platforms and targets (applications and plugins) can be a tedious task when SDKs have to be installed and configurated, or when the user want to do cross-compilation. A remote compilation service has been developed to simplify this process. It allows to send DSP source code on a cloud based infrastructure, which hosts a lot of targets and can do cross-compilation. This service is accessible: in several applications like FaustLive , Faust Editor or Faust IDE with a dedicated API explained in more details in the faustservice project and in the FaustWeb client tool with the faustremote script (part of the Faust distribution), which allows to access the remote compilation service and execute compilation requests.","title":"Remote compilation"},{"location":"manual/soundfiles/","text":"Sound files Support Sound files can be used with the soundfile language primitive. Sound files will be fully loaded in memory at init time and will be accessed with an input read index. The length and sample rate of the sound files can be accessed to implement more sophisticated playing schemes. A more complete description of the soundfile primitive can be found here . Using sound files with the faust2xx scripts Since using sound files (actually all formats that can be read by the libsndfile library , or by JUCE if you use the faust2juce tool), have to be embedded with the generated binary (application or plugin), the -soundfile option has been added in some of the faust2xx scripts to do that. Assuming a DSP program using the soundfile primitive is written, the following commands can be used to generate binaries: faust2caqt -soundfile foo.dsp to embed the needed sound files in the application bundle on OSX faust2max6 -soundfile foo.dsp to embed the needed sound files in the Max/MSP external bundle on OSX Check the faust2xx script description page to know which one currently support the -soundfile option. The Soundfile Library They are some additional functions in the soundfiles.lib library. Three basic functions are fully documented for now. There is more code already written in the library source that allows to read sound files with different kind of interpolation. The soundfile primitive can be used in the Web platform. See the Faust Web IDE related documentation.","title":"Soundfiles Support"},{"location":"manual/soundfiles/#sound-files-support","text":"Sound files can be used with the soundfile language primitive. Sound files will be fully loaded in memory at init time and will be accessed with an input read index. The length and sample rate of the sound files can be accessed to implement more sophisticated playing schemes. A more complete description of the soundfile primitive can be found here .","title":"Sound files Support"},{"location":"manual/soundfiles/#using-sound-files-with-the-faust2xx-scripts","text":"Since using sound files (actually all formats that can be read by the libsndfile library , or by JUCE if you use the faust2juce tool), have to be embedded with the generated binary (application or plugin), the -soundfile option has been added in some of the faust2xx scripts to do that. Assuming a DSP program using the soundfile primitive is written, the following commands can be used to generate binaries: faust2caqt -soundfile foo.dsp to embed the needed sound files in the application bundle on OSX faust2max6 -soundfile foo.dsp to embed the needed sound files in the Max/MSP external bundle on OSX Check the faust2xx script description page to know which one currently support the -soundfile option.","title":"Using sound files with the faust2xx scripts"},{"location":"manual/soundfiles/#the-soundfile-library","text":"They are some additional functions in the soundfiles.lib library. Three basic functions are fully documented for now. There is more code already written in the library source that allows to read sound files with different kind of interpolation. The soundfile primitive can be used in the Web platform. See the Faust Web IDE related documentation.","title":"The Soundfile Library"},{"location":"manual/syntax/","text":"Faust Syntax Faust Program A Faust program is essentially a list of statements . These statements can be metadata declarations (either global metadata or function metadata ), imports , definitions , and documentation tags , with optional C++ style ( //... and /*...*/ ) comments. Variants Some statements ( imports , definitions ) can be preceded by a variantlist , composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision . This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308; A Simple Program Here is a short Faust program that implements of a simple noise generator (called from the noises.lib Faust library). It exhibits various kind of statements: two global metadata declarations, an imports , a comment , and a definition . We will study later how documentation statements work: The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process . Statements The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions , documentation . All statements but documentation end with a semicolon ; . Metadata Metadata allow us to add elements which are not part of the language to Faust code. These can range to the name of a Faust program, its author, to potential compilation options or user interface element customizations. There are three different types of metadata in Faust: Global Metadata : metadata global to a Faust code Function Metadata : metadata specific to a function UI Metadata : metadata specific to a UI element Note that some Global Metadata have standard names and can be used for specific tasks. Their role is described in the Standard Metadata section. Global Metadata All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; Function Metadata Metadata can be associated to a specific function. In that case, declare is followed by the name of the function, a key, and a string. For example: declare add author \"John Doe\" add = +; This is very useful when a library has several contributors and that functions potentially have different license terms, etc. Standard Metadata There exists a series of standard global metadata in Faust whose role role is described in the following table: Metadata Role declare options \"[key0:value][key1:value]\" This metadata can be used to specify various options associated to a Faust code such as the fact its polyphonic, if it should have OSC, MIDI support, etc. Specific keys usable with this metadata are described throughout this documentation. declare interface \"xxx\" Specifies an interface replacing the standard Faust UI. Imports File imports allow us to import definitions from other source files. For example import(\"maths.lib\"); imports the definitions of the maths.lib library. The most common file to be imported is the stdfaust.lib library which gives access to all the standard Faust libraries from a single point: Documentation Tags Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed in the Mathematical Documentation chapter. In this section we essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in Latex format, can be placed in between these two tags. Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. The <metadata> tags allow to reference Faust global metadatas , calling the corresponding keyword. The <notice/> empty-element tag is used to generate the conventions used in the mathematical equations. The <listing/> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies , and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved Faust code between <mdoc> sections. Definitions A definition associates an identifier with an expression. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition. Simple Definitions The syntax of a simple definition is: identifier = expression; For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245); Function Definitions Definitions with formal parameters correspond to functions definitions. For example the definition of linear2db , a function that converts linear values to decibels, is: linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x)); Definitions With Pattern Matching Moreover, formal parameters can also be full expressions representing patterns: This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Note that this last definition is a convenient alternative to the more verbose: duplicate = case { (1,x) => x; (n,x) => x, duplicate(n-1,x); }; A use case for duplicate could be to put 5 white noise generators in parallel: Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11) . The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element: count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) , the expression will be evaluated as 10 . Note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in: count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time. Expressions Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. Constant Numerical Expressions Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time . We will refer to them as constant numerical expressions in the documentation. Diagram Expressions Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. Diagram Composition Operations Five binary composition operations are available to combine block-diagrams: recursion ( ~ ), parallel ( , ), sequential ( : ), split ( <: ), merge ( :> ). One can think of each of these composition operations as a particular way to connect two block diagrams. To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a block-diagram A are expressed as \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively expressed as: [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are: Syntax Priority Association Description expression ~ expression 4 left Recursive Composition expression , expression 3 right Parallel Composition expression : expression 2 right Sequential Composition expression <: expression 1 right Split Composition expression :> expression 1 right Merge Composition Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table that gives the associativity of each numerical operator in infix expressions. Parallel Composition The parallel composition (e.g., (A,B) ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation: (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used (e.g., A,B,C,D ), Faust uses right associativity and therefore builds internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example: Oscillators in Parallel Parallel composition can be used to put 3 oscillators of different kinds and frequencies in parallel, which will result in a Faust program with 3 outputs: Example: Stereo Effect Parallel composition can be used to easily turn a mono effect into a stereo one which will result in a Faust program with 2 inputs and 2 outputs: Note that there's a better to write this last example using the par iteration : Sequential Composition The sequential composition (e.g., A:B ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Sequential composition is an associative operation: (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore builds internally the expression (A:(B:(C:D))) . Example: Sine Oscillator Since everything is considered as a signal generator in Faust, sequential composition can be simply used to pass an argument to a function: Example: Effect Chain Sequential composition can be used to create an audio effect chain. Here we're plugging a guitar distortion to an autowah: Split Composition The split composition (e.g., A<:B ) operator is used to distribute the outputs of A to the inputs of B . For the operation to be valid, the number of inputs of B must be a multiple of the number of outputs of A : \\mathrm{outputs}(A).k=\\mathrm{inputs}(B) Each input i of B is connected to the output i \\bmod k of A : A[i \\bmod k]\\rightarrow[i]B Example: Duplicating the Output of an Oscillator Split composition can be used to duplicate signals. For example, the output of the following sawtooth oscillator is duplicated 3 times in parallel. Note that this can be written in a more effective way by replacing _,_,_ with par(i,3,_) using the par iteration . Example: Connecting a Mono Effect to a Stereo One More generally, the split composition can be used to connect a block with a certain number of output to a block with a greater number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A<:B the number of inputs of B has to be a multiple of the number of outputs of A . Merge Composition The merge composition (e.g., A:>B ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : \\mathrm{outputs}(A)=k.\\mathrm{inputs}(B) Each output i of A is connected to the input i \\bmod k of B : A[i]\\rightarrow\\ [i \\bmod k]B The k incoming signals of an input of B are summed together. Example: Summing Signals Together - Additive Synthesis Merge composition can be used to sum an arbitrary number of signals together. Here's an example of a simple additive synthesizer (note that the result of the sum of the signals is divided by 3 to prevent clicking): While the resulting block diagram will look slightly different, this is mathematically equivalent to: Example: Connecting a Stereo Effect to a Mono One More generally, the merge composition can be used to connect a block with a certain number of output to a block with a smaller number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A:>B the number of outputs of A has to be a multiple of the number of inputs of B . Recursive Composition The recursive composition (e.g., A~B ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable, it requires that: \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) Each input of B is connected to the corresponding output of A via an implicit 1-sample delay: A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . Example: Timer Recursive composition can be used to implement a \"timer\" that will count each sample starting at time n=0 : The difference equation corresponding to this program is: y(n) = y(n-1) + 1 an its output signal will look like: (1,2,3,4,5,6,\\dots) . Example: One Pole Filter Recursive composition can be used to implement a one pole filter with one line of code and just a few characters: The difference equation corresponding to this program is: y(n) = x(n) + a_{1}y(n-1) Note that the one sample delay of the filter is implicit here so it doesn't have to be declared. Inputs and Outputs of an Expression The number of inputs and outputs of a Faust expression can be known at compile time simply by using inputs(expression) and outputs(expression) . For example, the number of outputs of a sine wave oscillator can be known simply by writing the following program: Note that Faust automatically simplified the expression by generating a program that just outputs 1 . This type of construction is useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,ba.selector(n-i-1,n)) with { n = outputs(expr); }; And the inputs of an expression: Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr with { n = inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction: Iterations Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. The use and role of par , seq , sum , and prod are detailed in the following sections. par Iteration The par iteration can be used to duplicate an expression in parallel. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer i is used here at each iteration to compute the value of the frequency of the current oscillator. Also, note that this example could be re-wrtitten using sum iteration (see example in the corresponding section). seq Iteration The seq iteration can be used to duplicate an expression in series. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Peak Equalizer The fi.peak_eq function of the Faust libraries implements a second order \"peak equalizer\" section (gain boost or cut near some frequency). When placed in series, it can be used to implement a full peak equalizer: Note that i is used here at each iteration to compute various elements and to format some labels. Having user interface elements with different names is a way to force their differentiation in the generated interface. sum Iteration The sum iteration can be used to duplicate an expression as a sum. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer The following example is just a slightly different version from the one presented in the par iteration section. While their block diagrams look slightly different, the generated code is exactly the same. i is used here at each iteration to compute the value of the frequency of the current oscillator. prod Iteration The prod iteration can be used to duplicate an expression as a product. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Amplitude Modulation Synthesizer The following example implements an amplitude modulation synthesizer using an arbitrary number of oscillators thanks to the prod iteration: i is used here at each iteration to compute the value of the frequency of the current oscillator. Note that the shift parameter can be used to tune the frequency drift between each oscillator. Infix Notation and Other Syntax Extensions Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in 2+3 Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar infix notation . For example if you want to multiply two numbers, say 2 and 3 , you can write directly 2*3 instead of the equivalent core-syntax expression 2,3 : * . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example _/2 is equivalent to _,2:/ which divides the incoming signal by 2 . Here are a few examples of equivalences: Infix Syntax Core Syntax 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < In case of doubts on the meaning of an infix expression, for example _*_ , it is useful to translate it to its core syntax equivalent, here _,_:* , which is equivalent to * . Infix Operators Built-in primitives that can be used in infix notation are called infix operators and are listed below. Please note that a more detailed description of these operators is available section on primitives . Comparison Operators Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression < expression 5 left less than expression <= expression 5 left less or equal expression == expression 5 left equal expression != expression 5 left different expression >= expression 5 left greater or equal expression > expression 5 left greater than Math Operators Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression + expression 6 left addition expression - expression 6 left subtraction expression * expression 7 left multiplication expression / expression 7 left division expression % expression 7 left modulo expression ^ expression 8 left power Bitwise Operators Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The priority and associativity of the bitwise operators is given here: Syntax Pri. Assoc. Description expression | expression 6 left bitwise or expression & expression 7 left bitwise and expression xor expression 7 left bitwise xor expression << expression 7 left bitwise left shift expression >> expression 7 left bitwise right shift Delay operators Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \u2019 delays the left handside expression by one sample. Syntax Pri. Assoc. Description expression @ expression 9 left variable delay expression' 10 left one-sample delay Prefix Notation Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) : Prefix Syntax Core Syntax *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Partial Application The partial application notation is a variant of the prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube), and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one: Prefix Partial Application Syntax Core Syntax +(C) \\equiv _,C : + -(C) \\equiv _,C : - <(C) \\equiv _,C : < /(C) \\equiv _,C : / For commutative operations that doesn't matter. But for non-commutative ones, it is more \"natural\" to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not to other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Example: Gain Controller The following example demonstrates the use of partial application in the context of a gain controller: ' Time Expression ' is used to express a one sample delay. For example: will delay the incoming signal by one sample. ' time expressions can be chained, so the output signal of this program: will look like: (0,0,1,1,1,1,\\dots) . The ' time expression is useful when designing filters, etc. and is equivalent to @(1) (see the @ Time Expression ). @ Time Expression @ is used to express a delay with an arbitrary number of samples. For example: will delay the incoming signal by 10 samples. A delay expressed with @ doesn't have to be fixed but it must be bounded and cannot be negative. Therefore, the values of a slider are perfectly acceptable: @ only allows for the implementation of integer delay. Thus, various fractional delay algorithms are implemented in the Faust delays.lib library. Environment Expressions Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. with Expression The with construction allows to specify a local environment : a private list of definition that will be used to evaluate the left hand expression. In the following example: the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} . letrec Expression The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows us to easily express groups of mutually recursive signals, for example: x(t) = y(t-1) + 10\\\\ y(t) = x(t-1) - 1 as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: Note the special notation 'x = y + 10 instead of x = y' + 10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelope generator with an attack and a release time (as a number of samples), and a gate signal. A possible definition could be: With the following semantics for n(t) and v(t) : n(t) = (n(t-1)+1) * (g(t) <= g(t-1))\\\\ v(t) = max(0, v(t-1) + (n(t-1)<a(t))/a(t) - (n(t-1)>=a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of \u2019letrec\u2019: x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); }; environment Expression The environment construction allows to create an explicit environment. It is like a `with' , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. In the following example an environment construction is used to group together some constant definitions: constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next section). Access Expression Definitions inside an environment can be accessed using the . construction. For example constant.pi refers to the definition of pi in the constant environment defined above . Note that environments don't have to be named. We could have written directly: environment{pi = 3.14159; e = 2.718; ... }.pi library Expression The library construct allows to create an environment by reading the definitions from a file. For example library(\"filters.lib\") represents the environment obtained by reading the file filters.lib . It works like import(\"filters.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"filters.lib\").lowpass denotes the function lowpass as defined in the file filters.lib . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of: import(\"filters.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts: fl = library(\"filters.lib\"); ... ...fl.lowpass.... ... }; In practice, that's how the stdfaust.lib library works. component Expression The component construction allows us to reuse a full Faust program (e.g., a .dsp file) as a simple expression. For example component(\"freeverb.dsp\") denotes the signal processor defined in file freeverb.dsp . Components can be used within expressions like in: ...component(\"karplus32.dsp\") : component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . component works well in tandem with explicit substitution (see next section). Explicit Substitution Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing: ...component(\"freeverb.dsp\")[foo(x) = ...;]... }; Foreign Expressions Reference to external C functions , variables and constants can be introduced using the foreign expressions mechanism. Foreign function declaration An external C function is declared by indicating its name and signature as well as the required include file. The file maths.lib of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows: asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad or fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision and asinfx in fixed-point precision. This is why the four names are provided in the signature. Signature Types Foreign functions generally expect a precise type: int or float for their parameters. Note that currently only numerical functions involving simple int and float parameters are allowed currently in Faust. No vectors, tables or data structures can be passed as parameters or returned. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float . Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate. Foreign Variables and Constants External variables and constants can also be declared with a similar syntax. In the same maths.lib file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found: SR = min(192000.0,max(1.0,fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block. Include File In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include in the generated code. Library File In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model . Applications and Abstractions Abstractions and applications are fundamental programming constructions directly inspired by Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. Abstractions Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. Let's say we want to transform a stereo reverb, dm.zita_light for instance, into a mono effect. The following expression can be written (see the sections on Split Composition and Merge Composition ): _ <: dm.zita_light :> _ The incoming mono signal is split to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that we are interested in transforming other stereo effects. We could generalize this principle by making zita_light a variable: \\(zita_light).(_ <: zita_light :> _) The resulting abstraction can then be applied to transform other effects. Note that if zita_light is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) A name can be given to the abstraction and in turn use it on dm.zita_light : Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _; Applications Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. For example, the abstraction described in the previous section can be used to transform a stereo reverb: mono(dm.zita_light) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(dm.zita_light) Replacing the variable part with the argument is called beta-reduction in Lambda-Calculus Whenever the Faust compiler find an application of an abstraction it replaces the variable part with the argument. The resulting expression is as expected: (_ <: dm.zita_light :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments). Unapplied abstractions Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: In Faust, a proper semantic has also been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: can be simply defined as: which is actually equivalent to: process(x,y) = y,x; Pattern Matching Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(reverb : harmonizer) will produce: harmonizer : freeverb Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching. Primitives The primitive signal processing operations represent the built-in functionalities of Faust, that is the atomic operations on signals provided by the language. All these primitives denote signal processors , in other words, functions transforming input signals into output signals . Numbers Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double, or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type. route Primitive The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: A is the number of input signals, as an integer constant numerical expression , automatically promoted to int B is the number of output signals, as an integer constant numerical expression , automatically promoted to int a,b / (a,b) is an input/output pair, as integers constant numerical expressions , automatically promoted to int Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: waveform Primitive The waveform primitive was designed to facilitate the use of rdtable (read table). It allows us to specify a fixed periodic signal as a list of samples as literal numbers. waveform has two outputs: a constant indicating the size (as a number of samples) of the period the periodic signal itself For example waveform{0,1,2,3} produces two outputs: the constant signal 4 and the periodic signal (0,1,2,3,0,1,2,3,0,1,\\dots) . In the following example: waveform is used to define a triangle waveform (in its most primitive form), which is then used with a rdtable controlled by a phaser to implement a triangle wave oscillator. Note that the quality of this oscillator is very low because of the low resolution of the triangle waveform. soundfile Primitive The soundfile(\"label[url:{'path1';'path2';'path3'}]\", n) primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the %i syntax, as in the label part). The soundfile(\"label[url:path]\", n) simplified syntax, or soundfile(\"label\", n) (where label is used as the soundfile path) allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: two inputs: the sound number (as a integer between 0 and 255, automatically promoted to int ), and the read index in the sound (automatically promoted to int , which will access the last sample of the sound if the read index is greater than the sound length) two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound n several more outputs for the sound channels themselves, as a integer constant numerical expression If more outputs than the actual number of channels in the sound file are used, the audio channels will be automatically duplicated up to the wanted number of outputs (so for instance, if a stereo file is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. A minimal example to play a stereo soundfile until it's end can be written with: The 0 first parameter selects the first sound in the soundfile list (which only contains one file in this example), then uses an incrementing read index signal to play the soundfile, cuts the unneeded sound length in frames and sample rate ouputs, and keeps the two actual sound outputs. Having the sound length in frames first output allows to implement sound looping, or any kind of more sophisticated read index signal. Having the sound sample rate second output allows to possibly adapt or change the reading speed. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file in the Faust repository implements the void addSoundfile(label, path, sf_zone) method, which loads the actual soundfiles using the libsndfile library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that the complete soundfile content is preloaded in memory at initialisation time when the compiled program starts. Note that a special architecture file can well decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge of actually setting up all sound memory pointers when void addSoundfile(label, path, sf_zone) is called by the buidUserInterface mechanism. C-Equivalent Primitives Most Faust primitives are analogous to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . + can be used to very simply implement a mixer: Note that this is equivalent to (see Identity Function ): The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form. It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance, -(a*b) is a partial application. It is syntactic sugar for _,(a*b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a*b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Integer Number Integer numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described mathematically as y(t)=n . Example: DC Offset of 1 Floating Point Number Floating point numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described as y(t)=n.m . Example: DC Offset of 0.5 Identity Function The identity function is expressed in Faust with the _ primitive. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x(t) Example: a Signal Passing Through In the following example, the _ primitive is used to connect the single audio input of a Faust program to its output: Cut Primitive The cut primitive is expressed in Faust with ! . It can be used to \"stop\"/terminate a signal. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} Mathematical Description: \\forall x\\in\\mathbb{S},(x)\\rightarrow () Example: Stopping a Signal In the following example, the ! primitive is used to stop one of two parallel signals: int Primitive The int primitive can be used to force the cast of a signal to int. It is of type \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} and can be described mathematically as y(t)=(int)x(t) . This primitive is useful when declaringindices to read in a table, etc. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(int)x(t) Example: Simple Cast float Primitive The float primitive can be used to force the cast of a signal to float. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(float)x(t) Example: Simple Cast Add Primitive The + primitive can be used to add two signals together. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)+x_{2}(t) Example: Simple Mixer Subtract Primitive The - primitive can be used to subtract two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)-x_{2}(t) Example: Subtracting Two Input Signals Multiply Primitive The * primitive can be used to multiply two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)*x_{2}(t) Example: Multiplying a Signal by 0.5 Divide Primitive The / primitive can be used to divide two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)/{x_{2}(t)} Example: Dividing a Signal by 2 Power Primitive The ^ primitive can be used to raise to the power of N a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)^{x_{2}(t)} Example: Power of Two of a Signal Modulo Primitive The % primitive can be used to take the modulo of a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\%{x_{2}(t)} Example: Phaser The following example uses a counter and the % primitive to implement a basic phaser: will output a signal: (0,1,2,3,4,5,6,7,8,9,0,1,2,3,4) . AND Primitive Bitwise AND can be expressed in Faust with the & primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\&{x_{2}(t)} OR Primitive Bitwise OR can be expressed in Faust with the | primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)|{x_{2}(t)} Example The following example will output 1 if the incoming signal is smaller than 0.5 or greater than 0.7 and 0 otherwise. Note that the result of this operation could be multiplied to another signal to create a condition. XOR Primitive Bitwise XOR can be expressed in Faust with the xor primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\land {x_{2}(t)} Example Left Shift Primitive Left shift can be expressed in Faust with the << primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) << {x_{2}(t)} Example Right Shift Primitive Right shift can be expressed in Faust with the >> primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >> {x_{2}(t)} Example Smaller Than Primitive The smaller than comparison can be expressed in Faust with the < primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) < {x_{2}(t)} Example The following code will output 1 if the input signal is smaller than 0.5 and 0 otherwise. Smaller or Equal Than Primitive The smaller or equal than comparison can be expressed in Faust with the <= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) <= {x_{2}(t)} Example The following code will output 1 if the input signal is smaller or equal than 0.5 and 0 otherwise. Greater Than Primitive The greater than comparison can be expressed in Faust with the > primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) > {x_{2}(t)} Example The following code will output 1 if the input signal is greater than 0.5 and 0 otherwise. Greater or Equal Than Primitive The greater or equal than comparison can be expressed in Faust with the >= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >= {x_{2}(t)} Example The following code will output 1 if the input signal is greater or equal than 0.5 and 0 otherwise. Equal to Primitive The equal to comparison can be expressed in Faust with the == primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) == {x_{2}(t)} Example Different Than Primitive The different than comparison can be expressed in Faust with the != primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) != {x_{2}(t)} Example math.h -Equivalent Primitives Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib ). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. acos Primitive Arc cosine can be expressed as acos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{acosf}(x(t)) Example asin Primitive Arc sine can be expressed as asin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{asinf}(x(t)) Example atan Primitive Arc tangent can be expressed as atan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atanf}(x(t)) Example atan2 Primitive The arc tangent of 2 signals can be expressed as atan2 in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) Example cos Primitive Cosine can be expressed as cos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{cosf}(x(t)) Example sin Primitive Sine can be expressed as sin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sinf}(x(t)) Example tan Primitive Tangent can be expressed as tan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{tanf}(x(t)) Example exp Primitive Base-e exponential can be expressed as exp in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{expf}(x(t)) Example log Primitive Base-e logarithm can be expressed as log in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{logf}(x(t)) Example log10 Primitive Base-10 logarithm can be expressed as log10 in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{log10}(x(t)) Example pow Primitive Power can be expressed as pow in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) Example sqrt Primitive Square root can be expressed as sqrt in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sqrtf}(x(t)) Example abs Primitive Absolute value can be expressed as abs in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{abs}(x(t)) (int) or y(t)=\\mathrm{fabsf}(x(t)) (float) Example min Primitive Minimum can be expressed as min in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) Example max Primitive Maximum can be expressed as max in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) Example fmod Primitive Float modulo can be expressed as fmod in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) Example remainder Primitive Float remainder can be expressed as remainder in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) Example floor Primitive Largest int can be expressed as floor in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\leq : y(t)=\\mathrm{floorf}(x(t)) Example ceil Primitive Smallest int can be expressed as ceil in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\geq : y(t)=\\mathrm{ceilf}(x(t)) Example rint Primitive Closest int (using the current rounding mode) can be expressed as rint in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{rintf}(x(t)) Example round Primitive Nearest int value (regardless of the current rounding mode) can be expressed as round in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{roundf}(x(t)) Example Delay Primitives and Modifiers Faust hosts various modifiers and primitives to define one sample or integer delay of arbitrary length. They are presented in this section. mem Primitive A 1 sample delay can be expressed as mem in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+1)=x(t),y(0)=0 Example Note that this is equivalent to process = _' (see ' Modifier ) and process = @(1) (see @ Primitive ) ' Modifier ' can be used to apply a 1 sample delay to a signal in Faust. It can be seen as syntactic sugar to the mem primitive . ' is very convenient when implementing filters and can help significantly decrease the size of the Faust code. Example @ Primitive An integer delay of N samples can be expressed as @(N) in Faust. Note that N (automatically promoted to int ) can be dynamic but that its range must be bounded. This can be done by using a UI primitive (see example below) allowing for the definition of a range such as hslider , vslider , or nentry . Note that floating point delay is also available in Faust by the mean of various fractional delay implementations available in the Faust standard libraries. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+x_{2}(t))=x_{1}(t), y(t<x_{2}(t))=0 Usage _ : @(N) : _ Where: N : the length of the delay as a number of samples Example: Static N Samples Delay Example: Dynamic N Samples Delay Table Primitives rdtable Primitive The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The table can either be implemented by using the waveform primitive (as shown in the first example) or using a function controlled by a timer (such as ba.time ) as demonstrated in the second example. The idea is that the table is created during the initialization step and before audio computation begins. Type: \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=T[r(t)] Usage rdtable(n,s,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the table content r : the read index (an int between 0 and n-1 ), automatically promoted to int Example: Basic Triangle Wave Oscillator Using the waveform Primitive In this example, a basic (and dirty) triangle wave-table is defined using the waveform . It is then used with the rdtable primitive and a phasor to implement a triangle wave oscillator: Example: Basic Triangle Wave Oscillator Using the sin Primitive and a Timer In this example, a sine table is implemented using the sin primitive and a timer ( ba.time ). The timer calls the sin function during the initialization step of the Faust program. It is then used with rdtable to implement a sine wave oscillator. rwtable Primitive The rwtable primitive can be used to implement a read/write table. It takes an audio input that can be written in the table using a write index (i.e., w below) and read using a read index (i.e., r below). Type: \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} Mathematical Description: T[w(t)]=c(t); y(t)=T[r(t)] Usage _ : rwtable(n,s,w,_,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the initial table content w : the write index (an int between 0 and n-1 ), automatically promoted to int r : the read index (an int between 0 and n-1 ), automatically promoted to int Note that the fourth argument of rwtable corresponds to the input of the table. Example: Simple Looper In this example, an input signal is written in the table when record is true (equal to 1). The read index is constantly updated to loop through the table. The table size is set to 48000, which corresponds to one second if the sampling rate is 48000 KHz. Selector Primitives Selector primitives can be used to create conditions in Faust and to implement switches to choose between several signals. select2 Primitive The select2 primitive is a \"two-way selector\". It has three input signals: s , x_0 , x_1 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other two inputs x_0(t) and x_1(t) to the output y(t) . Note Please note that select2 is not the equivalent of a traditional if-then-else construction. Like every Faust primitive, it has a strict semantics. All input signals are always computed, even when they are not selected. Therefore you can't use select2 to avoid computing something. The semantics of select2 is as follows: Type: (s,x_0,x_1)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\end{array} \\right. Usage _,_ : select2(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine and a sawtooth wave oscillator. Note that select2 could be easily implemented from scratch in Faust: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient. select3 Primitive The select3 primitive is a \"three-ways selector\". It has four input signals: s , x_0 , x_1 , x_2 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other three inputs x_0(t) , x_1(t) and x_2(t) to the output y(t) . Type: (s,x_0,x_1,x_2)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\\\ x_2(t) & \\mathrm{if\\ } s(t) = 2.\\end{array} \\right. Usage _,_,_ : select3(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one, 2 for the third one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine, a sawtooth and a triangle wave oscillator. Note that select3 could be easily implemented from scratch in Faust using Boolean primitives: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient. Specific Primitives In Faust, signals operate within a [min, max] range. The lowest(sig) primitive determines the minimum value a given sig signal can attain, while the highest(sig) primitive identifies its maximum value. However, be aware that the compiler's interval computation might not accurately estimate the true [min, max] range, often resulting in -INFINITY for the minimum value and/or INFINITY for the maximum value. User Interface Primitives and Configuration Faust user interface widgets/primitives allow for an abstract description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be discrete (e.g., button , checkbox , etc.), continuous (e.g., hslider , vslider , nentry ), and organizational (e.g., vgroup , hgroup ). Discrete and continuous elements are signal generators. For example, a button produces a signal which is 1 when the button is pressed and 0 otherwise: These signals can be freely combined with other audio signals. In fact, the following code is perfectly valid and will generate sound: Each primitive implements a specific UI element, but their appearance can also be completely modified using metadata (a little bit like HTML and CSS in the web). Therefore, hslider , vslider , and nentry ) can for example be turned into a knob, a dropdown menu, etc. This concept is further developed in the section on UI metadata . Continuous UI elements (i.e., hslider , vslider , and nentry ) must all declare a range for the parameter they're controlling. In some cases, this range is used during compilation to allocate memory and will impact the generated code. For example, in the case of: a buffer of 10 samples will be allocated for the delay implemented with the @ primitive while 20 samples will be allocated in the following example: button Primitive The button primitive implements a button. Usage button(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger checkbox Primitive The checkbox primitive implements a checkbox/toggle. Usage checkbox(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger hslider Primitive The hslider primitive implements a horizontal slider. Usage hslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example: Gain Control Example: Additive Oscillator Here is an example of a 3 oscillators instrument where the default frequency of each partial is computed using a more complex constant numerical expression . vslider Primitive The vslider primitive implements a vertical slider. Usage vslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example nentry Primitive The nentry primitive implements a \"numerical entry\". Usage nentry(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the numerical entry, a constant numerical expression min : the minimum value of the numerical entry, a constant numerical expression max : the maximum value of the numerical entry, a constant numerical expression step : the precision (step) of the numerical entry (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example hgroup Primitive The hgroup primitive implements a horizontal group. A group contains other UI elements that can also be groups. hgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage hgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. vgroup Primitive The vgroup primitive implements a vertical group. A group contains other UI elements that can also be groups. vgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage vgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. tgroup Primitive The tgroup primitive implements a \"tab group.\" Tab groups can be used to group UI elements in tabs in the interface. A group contains other UI elements that can also be groups. tgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage tgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. vbargraph Primitive The vbargraph primitive implements a vertical bar-graph (typically a meter displaying the level of a signal). Usage vbargraph takes an input signal and outputs it while making it available to the UI. _ : vbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the vbargraph primitive: Note the use of the attach primitive here that forces the compilation of the vbargraph without using its output signal (see section on the attach primitive ). hbargraph Primitive The hbargraph primitive implements a horizontal bar-graph (typically a meter displaying the level of a signal). Usage hbargraph takes an input signal and outputs it while making it available to the UI. _ : hbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the hbargraph primitive: Note the use of the attach primitive here that forces the compilation of the hbargraph without using its output signal (see section on the attach primitive ). attach Primitive The attach primitive takes two input signals and produces one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical standpoint attach(x,y) is equivalent to 1*x+0*y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role, let's say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelope detector connected to a bargraph. The problem is that the signal of the envelope generators has no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. The examples in the hbargraph Primitive and the vbargraph Primitive illustrate well the use of attach . Variable Parts of a Label Labels can contain variable parts. These are indicated with the sign % followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example: creates 8 sliders in parallel with different names while par(i,8,hslider(\"Voice\",0.9,0,1,0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Labels as Pathnames Thanks to horizontal , vertical , and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of hslider(\"../volume\",...) would have been /h:Foo/volume , while the pathname of hslider(\"t:Fii/volume\",...) would have been /h:Foo/v:Faa/t:Fii/volume . Elements of a path are separated using / . Group types are defined with the following identifiers: Group Type Group Identifier hgroup h: vgroup v: tgroup t: Hence, the example presented in the section on the hgroup primitive can be rewritten as: which will be reflected in C++ as: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider1, 440.0f, 50.0f, 1000.0f, 0.100000001f); ui_interface->addVerticalSlider(\"gain\", &fVslider0, 0.0f, 0.0f, 1.0f, 0.00999999978f); ui_interface->closeBox(); } Note that path names are inherent to the use of tools gravitating around Faust such as OSC control or faust2api . In the case of faust2api , since no user interface is actually generated, UI elements just become a way to declare parameters of a Faust object. Therefore, there's no distinction between nentry , hslider , vslider , etc. Smoothing Despite the fact that the signal generated by user interface elements can be used in Faust with any other signals, UI elements run at a slower rate than the audio rate. This might be a source of clicking if the value of the corresponding parameter is modified while the program is running. This behavior is also amplified by the low resolution of signals generated by UI elements (as opposed to actual audio signals). For example, changing the value of the freq or gain parameters of the following code will likely create clicks (in the case of gain ) or abrupt jumps (in the case of freq ) in the signal: This problem can be easily solved in Faust by using the si.smoo function which implements an exponential smoothing by a unit-dc-gain one-pole lowpass with a pole at 0.999 ( si.smoo is just sugar for si.smooth(0.999) ). Therefore, the previous example can be rewritten as: Beware that each si.smoo that you place in your code will add some extra computation so they should be used precociously. Links to Generated Code UI elements provide a convenient entry point to the DSP process in the code generated by the Faust compiler (e.g., C++, etc.). For example, the Faust program: import(\"stdfaust.lib\"); freq = hslider(\"freq\",440,50,1000,0.1); process = os.osc(freq); will have the corresponding buildUserInterface method in C++: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"osc\"); ui_interface->addHorizontalSlider(\"freq\", &fHslider0, 440.0f, 50.0f, 1000.0f, 0.100001f); ui_interface->closeBox(); } The second argument of the addHorizontalSlider method is a pointer to the variable containing the current value of the freq parameter. The value of this pointer can be updated at any point to change the frequency of the corresponding oscillator. UI Label Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface, configure OSC and accelerometer control/mapping, etc. Since the format of the value associated to a key is relatively open, metadata constitute a flexible way for programmers to add features to the language. The Faust code: process = *(hslider(\"foo[key1: val 1][key2: val 2]\",0,0,1,0.1)); will produce the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tst\"); ui_interface->declare(&fHslider0, \"key1\", \"val 1\"); ui_interface->declare(&fHslider0, \"key2\", \"val 2\"); ui_interface->addHorizontalSlider(\"foo\", &fHslider0, 0.0f, 0.0f, 1.0f, 0.100000001f); ui_interface->closeBox(); } ... }; All metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. Metadata are architecture-specific: it is up to the architecture file to decide what to do with it. While some metadata will work with most architectures (e.g., accelerometer and OSC configuration, etc.), others might be more specific. Some of them are presented in the following sections. Ordering UI Elements The order of UI declarations in a Faust code doesn't necessarily reflect the actual order of the UI elements in the corresponding interface. Therefore, UI elements can be ordered by placing a metadata before the declaration of the name of the UI element in the label. For example, in the following declaration: gain = vslider(\"h:Oscillator/[1]gain\",0,0,1,0.01); freq = vslider(\"h:Oscillator/[0]freq\",440,50,1000,0.1); the freq parameter will be placed before gain despite the fact that gain is declared first. This system can be used to order groups as well. Ordering will be carried out on elements at the same level. For example: Note that this could also be written as: Global UI Metadata Note that global user interfaces completely replacing the one defined using the standard Faust UI primitives may be declared using global metadata . This is the case of the SmartKeyboard interface for example. In the following subsections, the standard Faust UI metadata are documented. Other types of metadata (e.g., accelerometers, OSC, etc.) are documented in the sections related to these topics. [style:knob] Metadata The [style:knob] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a knob. Example [style:menu] Metadata The [style:menu] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a drop-down menu. Usage [style:menu{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector [style:radio] Metadata The [style:radio] metadata turns a hslider or a vslider into a radio-button-menu. The orientation of the menu is determined by the type of UI element (i.e., hslider for horizontal and vslider for vertical). Usage [style:radio{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector [style:led] Metadata The [style:led] metadata turns a vbargraph or a hbargraph into a blinking LED (with varying intensity). Example: Level Display [style:numerical] Metadata The [style:numerical] metadata turns a vbargraph or a hbargraph into a numerical zone (thus the bargraph itself is no more displayed). Example: Level Display [unit:dB] Metadata The [unit:dB] metadata changes the unit of a vbargraph or a hbargraph to dB. This impacts its overall appearance by applying a rainbow color scheme, etc. Example: Level Display [unit:xx] Metadata The [unit:xx] metadata allows us to specify the unit of a UI element. The unit will be displayed right next to the current value of the parameter in the interface. Usage [unit:xx] Where: xx : the unit of the current parameter Example [scale:xx] Metadata The [scale:xx] metadata allows for the specification of a scale (different than the default linear one) to the parameter in the UI. [scale:log] can be used to change to scale to logarithmic and [scale:exp] to exponential. [tooltip:xx] Metadata The [tooltip:xx] metadata allows for the specification of a \"tooltip\" when the mouse hover a parameter in the interface. This is very convenient when implementing complex interfaces. Usage [tooltip:xx] Where: xx : a string to be used as a tooltip in the interface Example [hidden:0|1] Metadata The [hidden:0|1] metadata can be used to hide a parameter in the interface. This is convenient when controlling a parameter with a motion sensor or OSC messages and we don't want it to be visible in the interface. This feature is commonly used when making apps for Android and iOS using faust2android , faust2ios or in the Web platform. Compatibility iOS Android Web platform Sensors Control Metadatas Sensors control metadata can be used to map the built-in sensors of mobile devices to some of the parameters of a Faust program. Compatibility These metadatas are compatible with the following Faust targets and no additional step is required for them to be taken into account when the corresponding application is generated: faust2android faust2ios faust2smartkeyb Sensors control metadatas have five parameters and follow the following syntax: [acc: a b c d e] // for accelerometer [gyr: a b c d e] // for gyroscope They can be used in a Faust UI parameter declaration: parameter = nentry(\"UIparamName[acc: a b c d e]\",def,min,max,step); with: a : the accelerometer axis ( 0 : x, 1 : y, 2 : z) b : the accelerometer curve (see figure below) c : the minimum acceleration (m/s^2) d : the center acceleration (m/s^2) e : the maximum acceleration (m/s^2) def : the default/init value of the parameter min : the minimum value of the parameter max : the maximum value of the parameter step : the step of the parameter (precision) This allows for the implementation of complex linear and non-linear mappings that are summarized in this figure: For example, controlling the gain of a synthesizer using the X axis of the accelerometer can be easily done simply by writing something like: g = nentry(\"gain[acc: 0 0 -10 0 10]\",0.5,0,1,0.01); With this configuration, g = 0 when the device is standing vertically on its right side, g = 0.5 when the device is standing horizontally with screen facing up, and g = 1 when the device is standing vertically on its left side. Finally, in this slightly more complex mapping, g = 0 when the device is tilted on its right side and the value of g increases towards 1 when the device is tilted on its left side: g = nentry(\"gain[acc: 0 0 0 0 10]\",0,0,1,0.01); Complex nonlinear mappings can be implemented using this system. Widget Modulation Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: Here is a very simple example, assuming freeverb is a fully fonctional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb] Target Widgets Target widgets are specified by their label. Of course, this presupposes knowing the names of the sliders. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in: \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb] Modulators Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: [\"Wet\": * -> freeverb] Please note that the ':' sign used here is just a visual separator, it is not the sequential composition operator. To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs. Here is a complete example:","title":"Faust Syntax"},{"location":"manual/syntax/#faust-syntax","text":"","title":"Faust Syntax"},{"location":"manual/syntax/#faust-program","text":"A Faust program is essentially a list of statements . These statements can be metadata declarations (either global metadata or function metadata ), imports , definitions , and documentation tags , with optional C++ style ( //... and /*...*/ ) comments.","title":"Faust Program"},{"location":"manual/syntax/#variants","text":"Some statements ( imports , definitions ) can be preceded by a variantlist , composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision . This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308;","title":"Variants"},{"location":"manual/syntax/#a-simple-program","text":"Here is a short Faust program that implements of a simple noise generator (called from the noises.lib Faust library). It exhibits various kind of statements: two global metadata declarations, an imports , a comment , and a definition . We will study later how documentation statements work: The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process .","title":"A Simple Program"},{"location":"manual/syntax/#statements","text":"The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions , documentation . All statements but documentation end with a semicolon ; .","title":"Statements"},{"location":"manual/syntax/#metadata","text":"Metadata allow us to add elements which are not part of the language to Faust code. These can range to the name of a Faust program, its author, to potential compilation options or user interface element customizations. There are three different types of metadata in Faust: Global Metadata : metadata global to a Faust code Function Metadata : metadata specific to a function UI Metadata : metadata specific to a UI element Note that some Global Metadata have standard names and can be used for specific tasks. Their role is described in the Standard Metadata section.","title":"Metadata"},{"location":"manual/syntax/#global-metadata","text":"All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\";","title":"Global Metadata"},{"location":"manual/syntax/#function-metadata","text":"Metadata can be associated to a specific function. In that case, declare is followed by the name of the function, a key, and a string. For example: declare add author \"John Doe\" add = +; This is very useful when a library has several contributors and that functions potentially have different license terms, etc.","title":"Function Metadata"},{"location":"manual/syntax/#standard-metadata","text":"There exists a series of standard global metadata in Faust whose role role is described in the following table: Metadata Role declare options \"[key0:value][key1:value]\" This metadata can be used to specify various options associated to a Faust code such as the fact its polyphonic, if it should have OSC, MIDI support, etc. Specific keys usable with this metadata are described throughout this documentation. declare interface \"xxx\" Specifies an interface replacing the standard Faust UI.","title":"Standard Metadata"},{"location":"manual/syntax/#imports","text":"File imports allow us to import definitions from other source files. For example import(\"maths.lib\"); imports the definitions of the maths.lib library. The most common file to be imported is the stdfaust.lib library which gives access to all the standard Faust libraries from a single point:","title":"Imports"},{"location":"manual/syntax/#documentation-tags","text":"Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed in the Mathematical Documentation chapter. In this section we essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in Latex format, can be placed in between these two tags. Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. The <metadata> tags allow to reference Faust global metadatas , calling the corresponding keyword. The <notice/> empty-element tag is used to generate the conventions used in the mathematical equations. The <listing/> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies , and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved Faust code between <mdoc> sections.","title":"Documentation Tags"},{"location":"manual/syntax/#definitions","text":"A definition associates an identifier with an expression. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition.","title":"Definitions"},{"location":"manual/syntax/#simple-definitions","text":"The syntax of a simple definition is: identifier = expression; For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245);","title":"Simple Definitions"},{"location":"manual/syntax/#function-definitions","text":"Definitions with formal parameters correspond to functions definitions. For example the definition of linear2db , a function that converts linear values to decibels, is: linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x));","title":"Function Definitions"},{"location":"manual/syntax/#definitions-with-pattern-matching","text":"Moreover, formal parameters can also be full expressions representing patterns: This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Note that this last definition is a convenient alternative to the more verbose: duplicate = case { (1,x) => x; (n,x) => x, duplicate(n-1,x); }; A use case for duplicate could be to put 5 white noise generators in parallel: Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11) . The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element: count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) , the expression will be evaluated as 10 . Note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in: count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time.","title":"Definitions With Pattern Matching"},{"location":"manual/syntax/#expressions","text":"Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions.","title":"Expressions"},{"location":"manual/syntax/#constant-numerical-expressions","text":"Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time . We will refer to them as constant numerical expressions in the documentation.","title":"Constant Numerical Expressions"},{"location":"manual/syntax/#diagram-expressions","text":"Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions.","title":"Diagram Expressions"},{"location":"manual/syntax/#diagram-composition-operations","text":"Five binary composition operations are available to combine block-diagrams: recursion ( ~ ), parallel ( , ), sequential ( : ), split ( <: ), merge ( :> ). One can think of each of these composition operations as a particular way to connect two block diagrams. To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a block-diagram A are expressed as \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively expressed as: [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are: Syntax Priority Association Description expression ~ expression 4 left Recursive Composition expression , expression 3 right Parallel Composition expression : expression 2 right Sequential Composition expression <: expression 1 right Split Composition expression :> expression 1 right Merge Composition Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table that gives the associativity of each numerical operator in infix expressions.","title":"Diagram Composition Operations"},{"location":"manual/syntax/#parallel-composition","text":"The parallel composition (e.g., (A,B) ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation: (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used (e.g., A,B,C,D ), Faust uses right associativity and therefore builds internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example: Oscillators in Parallel Parallel composition can be used to put 3 oscillators of different kinds and frequencies in parallel, which will result in a Faust program with 3 outputs: Example: Stereo Effect Parallel composition can be used to easily turn a mono effect into a stereo one which will result in a Faust program with 2 inputs and 2 outputs: Note that there's a better to write this last example using the par iteration :","title":"Parallel Composition"},{"location":"manual/syntax/#sequential-composition","text":"The sequential composition (e.g., A:B ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Sequential composition is an associative operation: (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore builds internally the expression (A:(B:(C:D))) . Example: Sine Oscillator Since everything is considered as a signal generator in Faust, sequential composition can be simply used to pass an argument to a function: Example: Effect Chain Sequential composition can be used to create an audio effect chain. Here we're plugging a guitar distortion to an autowah:","title":"Sequential Composition"},{"location":"manual/syntax/#split-composition","text":"The split composition (e.g., A<:B ) operator is used to distribute the outputs of A to the inputs of B . For the operation to be valid, the number of inputs of B must be a multiple of the number of outputs of A : \\mathrm{outputs}(A).k=\\mathrm{inputs}(B) Each input i of B is connected to the output i \\bmod k of A : A[i \\bmod k]\\rightarrow[i]B Example: Duplicating the Output of an Oscillator Split composition can be used to duplicate signals. For example, the output of the following sawtooth oscillator is duplicated 3 times in parallel. Note that this can be written in a more effective way by replacing _,_,_ with par(i,3,_) using the par iteration . Example: Connecting a Mono Effect to a Stereo One More generally, the split composition can be used to connect a block with a certain number of output to a block with a greater number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A<:B the number of inputs of B has to be a multiple of the number of outputs of A .","title":"Split Composition"},{"location":"manual/syntax/#merge-composition","text":"The merge composition (e.g., A:>B ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : \\mathrm{outputs}(A)=k.\\mathrm{inputs}(B) Each output i of A is connected to the input i \\bmod k of B : A[i]\\rightarrow\\ [i \\bmod k]B The k incoming signals of an input of B are summed together. Example: Summing Signals Together - Additive Synthesis Merge composition can be used to sum an arbitrary number of signals together. Here's an example of a simple additive synthesizer (note that the result of the sum of the signals is divided by 3 to prevent clicking): While the resulting block diagram will look slightly different, this is mathematically equivalent to: Example: Connecting a Stereo Effect to a Mono One More generally, the merge composition can be used to connect a block with a certain number of output to a block with a smaller number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A:>B the number of outputs of A has to be a multiple of the number of inputs of B .","title":"Merge Composition"},{"location":"manual/syntax/#recursive-composition","text":"The recursive composition (e.g., A~B ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable, it requires that: \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) Each input of B is connected to the corresponding output of A via an implicit 1-sample delay: A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . Example: Timer Recursive composition can be used to implement a \"timer\" that will count each sample starting at time n=0 : The difference equation corresponding to this program is: y(n) = y(n-1) + 1 an its output signal will look like: (1,2,3,4,5,6,\\dots) . Example: One Pole Filter Recursive composition can be used to implement a one pole filter with one line of code and just a few characters: The difference equation corresponding to this program is: y(n) = x(n) + a_{1}y(n-1) Note that the one sample delay of the filter is implicit here so it doesn't have to be declared.","title":"Recursive Composition"},{"location":"manual/syntax/#inputs-and-outputs-of-an-expression","text":"The number of inputs and outputs of a Faust expression can be known at compile time simply by using inputs(expression) and outputs(expression) . For example, the number of outputs of a sine wave oscillator can be known simply by writing the following program: Note that Faust automatically simplified the expression by generating a program that just outputs 1 . This type of construction is useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,ba.selector(n-i-1,n)) with { n = outputs(expr); }; And the inputs of an expression: Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr with { n = inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction:","title":"Inputs and Outputs of an Expression"},{"location":"manual/syntax/#iterations","text":"Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. The use and role of par , seq , sum , and prod are detailed in the following sections.","title":"Iterations"},{"location":"manual/syntax/#par-iteration","text":"The par iteration can be used to duplicate an expression in parallel. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer i is used here at each iteration to compute the value of the frequency of the current oscillator. Also, note that this example could be re-wrtitten using sum iteration (see example in the corresponding section).","title":"par Iteration"},{"location":"manual/syntax/#seq-iteration","text":"The seq iteration can be used to duplicate an expression in series. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Peak Equalizer The fi.peak_eq function of the Faust libraries implements a second order \"peak equalizer\" section (gain boost or cut near some frequency). When placed in series, it can be used to implement a full peak equalizer: Note that i is used here at each iteration to compute various elements and to format some labels. Having user interface elements with different names is a way to force their differentiation in the generated interface.","title":"seq Iteration"},{"location":"manual/syntax/#sum-iteration","text":"The sum iteration can be used to duplicate an expression as a sum. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer The following example is just a slightly different version from the one presented in the par iteration section. While their block diagrams look slightly different, the generated code is exactly the same. i is used here at each iteration to compute the value of the frequency of the current oscillator.","title":"sum Iteration"},{"location":"manual/syntax/#prod-iteration","text":"The prod iteration can be used to duplicate an expression as a product. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Amplitude Modulation Synthesizer The following example implements an amplitude modulation synthesizer using an arbitrary number of oscillators thanks to the prod iteration: i is used here at each iteration to compute the value of the frequency of the current oscillator. Note that the shift parameter can be used to tune the frequency drift between each oscillator.","title":"prod Iteration"},{"location":"manual/syntax/#infix-notation-and-other-syntax-extensions","text":"Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in 2+3 Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar infix notation . For example if you want to multiply two numbers, say 2 and 3 , you can write directly 2*3 instead of the equivalent core-syntax expression 2,3 : * . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example _/2 is equivalent to _,2:/ which divides the incoming signal by 2 . Here are a few examples of equivalences: Infix Syntax Core Syntax 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < In case of doubts on the meaning of an infix expression, for example _*_ , it is useful to translate it to its core syntax equivalent, here _,_:* , which is equivalent to * .","title":"Infix Notation and Other Syntax Extensions"},{"location":"manual/syntax/#infix-operators","text":"Built-in primitives that can be used in infix notation are called infix operators and are listed below. Please note that a more detailed description of these operators is available section on primitives .","title":"Infix Operators"},{"location":"manual/syntax/#comparison-operators","text":"Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression < expression 5 left less than expression <= expression 5 left less or equal expression == expression 5 left equal expression != expression 5 left different expression >= expression 5 left greater or equal expression > expression 5 left greater than","title":"Comparison Operators"},{"location":"manual/syntax/#math-operators","text":"Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression + expression 6 left addition expression - expression 6 left subtraction expression * expression 7 left multiplication expression / expression 7 left division expression % expression 7 left modulo expression ^ expression 8 left power","title":"Math Operators"},{"location":"manual/syntax/#bitwise-operators","text":"Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The priority and associativity of the bitwise operators is given here: Syntax Pri. Assoc. Description expression | expression 6 left bitwise or expression & expression 7 left bitwise and expression xor expression 7 left bitwise xor expression << expression 7 left bitwise left shift expression >> expression 7 left bitwise right shift","title":"Bitwise Operators"},{"location":"manual/syntax/#delay-operators","text":"Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \u2019 delays the left handside expression by one sample. Syntax Pri. Assoc. Description expression @ expression 9 left variable delay expression' 10 left one-sample delay","title":"Delay operators"},{"location":"manual/syntax/#prefix-notation","text":"Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) : Prefix Syntax Core Syntax *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : <","title":"Prefix Notation"},{"location":"manual/syntax/#partial-application","text":"The partial application notation is a variant of the prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube), and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one: Prefix Partial Application Syntax Core Syntax +(C) \\equiv _,C : + -(C) \\equiv _,C : - <(C) \\equiv _,C : < /(C) \\equiv _,C : / For commutative operations that doesn't matter. But for non-commutative ones, it is more \"natural\" to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not to other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Example: Gain Controller The following example demonstrates the use of partial application in the context of a gain controller:","title":"Partial Application"},{"location":"manual/syntax/#time-expression","text":"' is used to express a one sample delay. For example: will delay the incoming signal by one sample. ' time expressions can be chained, so the output signal of this program: will look like: (0,0,1,1,1,1,\\dots) . The ' time expression is useful when designing filters, etc. and is equivalent to @(1) (see the @ Time Expression ).","title":"' Time Expression"},{"location":"manual/syntax/#time-expression_1","text":"@ is used to express a delay with an arbitrary number of samples. For example: will delay the incoming signal by 10 samples. A delay expressed with @ doesn't have to be fixed but it must be bounded and cannot be negative. Therefore, the values of a slider are perfectly acceptable: @ only allows for the implementation of integer delay. Thus, various fractional delay algorithms are implemented in the Faust delays.lib library.","title":"@ Time Expression"},{"location":"manual/syntax/#environment-expressions","text":"Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design.","title":"Environment Expressions"},{"location":"manual/syntax/#with-expression","text":"The with construction allows to specify a local environment : a private list of definition that will be used to evaluate the left hand expression. In the following example: the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} .","title":"with Expression"},{"location":"manual/syntax/#letrec-expression","text":"The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows us to easily express groups of mutually recursive signals, for example: x(t) = y(t-1) + 10\\\\ y(t) = x(t-1) - 1 as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: Note the special notation 'x = y + 10 instead of x = y' + 10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelope generator with an attack and a release time (as a number of samples), and a gate signal. A possible definition could be: With the following semantics for n(t) and v(t) : n(t) = (n(t-1)+1) * (g(t) <= g(t-1))\\\\ v(t) = max(0, v(t-1) + (n(t-1)<a(t))/a(t) - (n(t-1)>=a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of \u2019letrec\u2019: x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); };","title":"letrec Expression"},{"location":"manual/syntax/#environment-expression","text":"The environment construction allows to create an explicit environment. It is like a `with' , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. In the following example an environment construction is used to group together some constant definitions: constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next section).","title":"environment Expression"},{"location":"manual/syntax/#access-expression","text":"Definitions inside an environment can be accessed using the . construction. For example constant.pi refers to the definition of pi in the constant environment defined above . Note that environments don't have to be named. We could have written directly: environment{pi = 3.14159; e = 2.718; ... }.pi","title":"Access Expression"},{"location":"manual/syntax/#library-expression","text":"The library construct allows to create an environment by reading the definitions from a file. For example library(\"filters.lib\") represents the environment obtained by reading the file filters.lib . It works like import(\"filters.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"filters.lib\").lowpass denotes the function lowpass as defined in the file filters.lib . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of: import(\"filters.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts: fl = library(\"filters.lib\"); ... ...fl.lowpass.... ... }; In practice, that's how the stdfaust.lib library works.","title":"library Expression"},{"location":"manual/syntax/#component-expression","text":"The component construction allows us to reuse a full Faust program (e.g., a .dsp file) as a simple expression. For example component(\"freeverb.dsp\") denotes the signal processor defined in file freeverb.dsp . Components can be used within expressions like in: ...component(\"karplus32.dsp\") : component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . component works well in tandem with explicit substitution (see next section).","title":"component Expression"},{"location":"manual/syntax/#explicit-substitution","text":"Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing: ...component(\"freeverb.dsp\")[foo(x) = ...;]... };","title":"Explicit Substitution"},{"location":"manual/syntax/#foreign-expressions","text":"Reference to external C functions , variables and constants can be introduced using the foreign expressions mechanism.","title":"Foreign Expressions"},{"location":"manual/syntax/#foreign-function-declaration","text":"An external C function is declared by indicating its name and signature as well as the required include file. The file maths.lib of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows: asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad or fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision and asinfx in fixed-point precision. This is why the four names are provided in the signature.","title":"Foreign function declaration"},{"location":"manual/syntax/#signature","text":"","title":"Signature"},{"location":"manual/syntax/#types","text":"Foreign functions generally expect a precise type: int or float for their parameters. Note that currently only numerical functions involving simple int and float parameters are allowed currently in Faust. No vectors, tables or data structures can be passed as parameters or returned. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float . Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate.","title":"Types"},{"location":"manual/syntax/#foreign-variables-and-constants","text":"External variables and constants can also be declared with a similar syntax. In the same maths.lib file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found: SR = min(192000.0,max(1.0,fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block.","title":"Foreign Variables and Constants"},{"location":"manual/syntax/#include-file","text":"In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include in the generated code.","title":"Include File"},{"location":"manual/syntax/#library-file","text":"In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model .","title":"Library File"},{"location":"manual/syntax/#applications-and-abstractions","text":"Abstractions and applications are fundamental programming constructions directly inspired by Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically.","title":"Applications and Abstractions"},{"location":"manual/syntax/#abstractions","text":"Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. Let's say we want to transform a stereo reverb, dm.zita_light for instance, into a mono effect. The following expression can be written (see the sections on Split Composition and Merge Composition ): _ <: dm.zita_light :> _ The incoming mono signal is split to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that we are interested in transforming other stereo effects. We could generalize this principle by making zita_light a variable: \\(zita_light).(_ <: zita_light :> _) The resulting abstraction can then be applied to transform other effects. Note that if zita_light is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) A name can be given to the abstraction and in turn use it on dm.zita_light : Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _;","title":"Abstractions"},{"location":"manual/syntax/#applications","text":"Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. For example, the abstraction described in the previous section can be used to transform a stereo reverb: mono(dm.zita_light) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(dm.zita_light) Replacing the variable part with the argument is called beta-reduction in Lambda-Calculus Whenever the Faust compiler find an application of an abstraction it replaces the variable part with the argument. The resulting expression is as expected: (_ <: dm.zita_light :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments).","title":"Applications"},{"location":"manual/syntax/#unapplied-abstractions","text":"Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: In Faust, a proper semantic has also been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: can be simply defined as: which is actually equivalent to: process(x,y) = y,x;","title":"Unapplied abstractions"},{"location":"manual/syntax/#pattern-matching","text":"Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(reverb : harmonizer) will produce: harmonizer : freeverb Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching.","title":"Pattern Matching"},{"location":"manual/syntax/#primitives","text":"The primitive signal processing operations represent the built-in functionalities of Faust, that is the atomic operations on signals provided by the language. All these primitives denote signal processors , in other words, functions transforming input signals into output signals .","title":"Primitives"},{"location":"manual/syntax/#numbers","text":"Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double, or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type.","title":"Numbers"},{"location":"manual/syntax/#route-primitive","text":"The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: A is the number of input signals, as an integer constant numerical expression , automatically promoted to int B is the number of output signals, as an integer constant numerical expression , automatically promoted to int a,b / (a,b) is an input/output pair, as integers constant numerical expressions , automatically promoted to int Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: More complex expressions can be written using algorithmic constructions, like the following one to cross N signals:","title":"route Primitive"},{"location":"manual/syntax/#waveform-primitive","text":"The waveform primitive was designed to facilitate the use of rdtable (read table). It allows us to specify a fixed periodic signal as a list of samples as literal numbers. waveform has two outputs: a constant indicating the size (as a number of samples) of the period the periodic signal itself For example waveform{0,1,2,3} produces two outputs: the constant signal 4 and the periodic signal (0,1,2,3,0,1,2,3,0,1,\\dots) . In the following example: waveform is used to define a triangle waveform (in its most primitive form), which is then used with a rdtable controlled by a phaser to implement a triangle wave oscillator. Note that the quality of this oscillator is very low because of the low resolution of the triangle waveform.","title":"waveform Primitive"},{"location":"manual/syntax/#soundfile-primitive","text":"The soundfile(\"label[url:{'path1';'path2';'path3'}]\", n) primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the %i syntax, as in the label part). The soundfile(\"label[url:path]\", n) simplified syntax, or soundfile(\"label\", n) (where label is used as the soundfile path) allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: two inputs: the sound number (as a integer between 0 and 255, automatically promoted to int ), and the read index in the sound (automatically promoted to int , which will access the last sample of the sound if the read index is greater than the sound length) two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound n several more outputs for the sound channels themselves, as a integer constant numerical expression If more outputs than the actual number of channels in the sound file are used, the audio channels will be automatically duplicated up to the wanted number of outputs (so for instance, if a stereo file is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. A minimal example to play a stereo soundfile until it's end can be written with: The 0 first parameter selects the first sound in the soundfile list (which only contains one file in this example), then uses an incrementing read index signal to play the soundfile, cuts the unneeded sound length in frames and sample rate ouputs, and keeps the two actual sound outputs. Having the sound length in frames first output allows to implement sound looping, or any kind of more sophisticated read index signal. Having the sound sample rate second output allows to possibly adapt or change the reading speed. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file in the Faust repository implements the void addSoundfile(label, path, sf_zone) method, which loads the actual soundfiles using the libsndfile library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that the complete soundfile content is preloaded in memory at initialisation time when the compiled program starts. Note that a special architecture file can well decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge of actually setting up all sound memory pointers when void addSoundfile(label, path, sf_zone) is called by the buidUserInterface mechanism.","title":"soundfile Primitive"},{"location":"manual/syntax/#c-equivalent-primitives","text":"Most Faust primitives are analogous to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . + can be used to very simply implement a mixer: Note that this is equivalent to (see Identity Function ): The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form. It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance, -(a*b) is a partial application. It is syntactic sugar for _,(a*b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a*b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type.","title":"C-Equivalent Primitives"},{"location":"manual/syntax/#integer-number","text":"Integer numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described mathematically as y(t)=n . Example: DC Offset of 1","title":"Integer Number"},{"location":"manual/syntax/#floating-point-number","text":"Floating point numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described as y(t)=n.m . Example: DC Offset of 0.5","title":"Floating Point Number"},{"location":"manual/syntax/#identity-function","text":"The identity function is expressed in Faust with the _ primitive. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x(t) Example: a Signal Passing Through In the following example, the _ primitive is used to connect the single audio input of a Faust program to its output:","title":"Identity Function"},{"location":"manual/syntax/#cut-primitive","text":"The cut primitive is expressed in Faust with ! . It can be used to \"stop\"/terminate a signal. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} Mathematical Description: \\forall x\\in\\mathbb{S},(x)\\rightarrow () Example: Stopping a Signal In the following example, the ! primitive is used to stop one of two parallel signals:","title":"Cut Primitive"},{"location":"manual/syntax/#int-primitive","text":"The int primitive can be used to force the cast of a signal to int. It is of type \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} and can be described mathematically as y(t)=(int)x(t) . This primitive is useful when declaringindices to read in a table, etc. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(int)x(t) Example: Simple Cast","title":"int Primitive"},{"location":"manual/syntax/#float-primitive","text":"The float primitive can be used to force the cast of a signal to float. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(float)x(t) Example: Simple Cast","title":"float Primitive"},{"location":"manual/syntax/#add-primitive","text":"The + primitive can be used to add two signals together. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)+x_{2}(t) Example: Simple Mixer","title":"Add Primitive"},{"location":"manual/syntax/#subtract-primitive","text":"The - primitive can be used to subtract two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)-x_{2}(t) Example: Subtracting Two Input Signals","title":"Subtract Primitive"},{"location":"manual/syntax/#multiply-primitive","text":"The * primitive can be used to multiply two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)*x_{2}(t) Example: Multiplying a Signal by 0.5","title":"Multiply Primitive"},{"location":"manual/syntax/#divide-primitive","text":"The / primitive can be used to divide two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)/{x_{2}(t)} Example: Dividing a Signal by 2","title":"Divide Primitive"},{"location":"manual/syntax/#power-primitive","text":"The ^ primitive can be used to raise to the power of N a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)^{x_{2}(t)} Example: Power of Two of a Signal","title":"Power Primitive"},{"location":"manual/syntax/#modulo-primitive","text":"The % primitive can be used to take the modulo of a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\%{x_{2}(t)} Example: Phaser The following example uses a counter and the % primitive to implement a basic phaser: will output a signal: (0,1,2,3,4,5,6,7,8,9,0,1,2,3,4) .","title":"Modulo Primitive"},{"location":"manual/syntax/#and-primitive","text":"Bitwise AND can be expressed in Faust with the & primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\&{x_{2}(t)}","title":"AND Primitive"},{"location":"manual/syntax/#or-primitive","text":"Bitwise OR can be expressed in Faust with the | primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)|{x_{2}(t)} Example The following example will output 1 if the incoming signal is smaller than 0.5 or greater than 0.7 and 0 otherwise. Note that the result of this operation could be multiplied to another signal to create a condition.","title":"OR Primitive"},{"location":"manual/syntax/#xor-primitive","text":"Bitwise XOR can be expressed in Faust with the xor primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\land {x_{2}(t)} Example","title":"XOR Primitive"},{"location":"manual/syntax/#left-shift-primitive","text":"Left shift can be expressed in Faust with the << primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) << {x_{2}(t)} Example","title":"Left Shift Primitive"},{"location":"manual/syntax/#right-shift-primitive","text":"Right shift can be expressed in Faust with the >> primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >> {x_{2}(t)} Example","title":"Right Shift Primitive"},{"location":"manual/syntax/#smaller-than-primitive","text":"The smaller than comparison can be expressed in Faust with the < primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) < {x_{2}(t)} Example The following code will output 1 if the input signal is smaller than 0.5 and 0 otherwise.","title":"Smaller Than Primitive"},{"location":"manual/syntax/#smaller-or-equal-than-primitive","text":"The smaller or equal than comparison can be expressed in Faust with the <= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) <= {x_{2}(t)} Example The following code will output 1 if the input signal is smaller or equal than 0.5 and 0 otherwise.","title":"Smaller or Equal Than Primitive"},{"location":"manual/syntax/#greater-than-primitive","text":"The greater than comparison can be expressed in Faust with the > primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) > {x_{2}(t)} Example The following code will output 1 if the input signal is greater than 0.5 and 0 otherwise.","title":"Greater Than Primitive"},{"location":"manual/syntax/#greater-or-equal-than-primitive","text":"The greater or equal than comparison can be expressed in Faust with the >= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >= {x_{2}(t)} Example The following code will output 1 if the input signal is greater or equal than 0.5 and 0 otherwise.","title":"Greater or Equal Than Primitive"},{"location":"manual/syntax/#equal-to-primitive","text":"The equal to comparison can be expressed in Faust with the == primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) == {x_{2}(t)} Example","title":"Equal to Primitive"},{"location":"manual/syntax/#different-than-primitive","text":"The different than comparison can be expressed in Faust with the != primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) != {x_{2}(t)} Example","title":"Different Than Primitive"},{"location":"manual/syntax/#mathh-equivalent-primitives","text":"Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib ). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it.","title":"math.h-Equivalent Primitives"},{"location":"manual/syntax/#acos-primitive","text":"Arc cosine can be expressed as acos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{acosf}(x(t)) Example","title":"acos Primitive"},{"location":"manual/syntax/#asin-primitive","text":"Arc sine can be expressed as asin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{asinf}(x(t)) Example","title":"asin Primitive"},{"location":"manual/syntax/#atan-primitive","text":"Arc tangent can be expressed as atan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atanf}(x(t)) Example","title":"atan Primitive"},{"location":"manual/syntax/#atan2-primitive","text":"The arc tangent of 2 signals can be expressed as atan2 in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) Example","title":"atan2 Primitive"},{"location":"manual/syntax/#cos-primitive","text":"Cosine can be expressed as cos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{cosf}(x(t)) Example","title":"cos Primitive"},{"location":"manual/syntax/#sin-primitive","text":"Sine can be expressed as sin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sinf}(x(t)) Example","title":"sin Primitive"},{"location":"manual/syntax/#tan-primitive","text":"Tangent can be expressed as tan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{tanf}(x(t)) Example","title":"tan Primitive"},{"location":"manual/syntax/#exp-primitive","text":"Base-e exponential can be expressed as exp in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{expf}(x(t)) Example","title":"exp Primitive"},{"location":"manual/syntax/#log-primitive","text":"Base-e logarithm can be expressed as log in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{logf}(x(t)) Example","title":"log Primitive"},{"location":"manual/syntax/#log10-primitive","text":"Base-10 logarithm can be expressed as log10 in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{log10}(x(t)) Example","title":"log10 Primitive"},{"location":"manual/syntax/#pow-primitive","text":"Power can be expressed as pow in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) Example","title":"pow Primitive"},{"location":"manual/syntax/#sqrt-primitive","text":"Square root can be expressed as sqrt in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sqrtf}(x(t)) Example","title":"sqrt Primitive"},{"location":"manual/syntax/#abs-primitive","text":"Absolute value can be expressed as abs in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{abs}(x(t)) (int) or y(t)=\\mathrm{fabsf}(x(t)) (float) Example","title":"abs Primitive"},{"location":"manual/syntax/#min-primitive","text":"Minimum can be expressed as min in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) Example","title":"min Primitive"},{"location":"manual/syntax/#max-primitive","text":"Maximum can be expressed as max in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) Example","title":"max Primitive"},{"location":"manual/syntax/#fmod-primitive","text":"Float modulo can be expressed as fmod in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) Example","title":"fmod Primitive"},{"location":"manual/syntax/#remainder-primitive","text":"Float remainder can be expressed as remainder in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) Example","title":"remainder Primitive"},{"location":"manual/syntax/#floor-primitive","text":"Largest int can be expressed as floor in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\leq : y(t)=\\mathrm{floorf}(x(t)) Example","title":"floor Primitive"},{"location":"manual/syntax/#ceil-primitive","text":"Smallest int can be expressed as ceil in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\geq : y(t)=\\mathrm{ceilf}(x(t)) Example","title":"ceil Primitive"},{"location":"manual/syntax/#rint-primitive","text":"Closest int (using the current rounding mode) can be expressed as rint in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{rintf}(x(t)) Example","title":"rint Primitive"},{"location":"manual/syntax/#round-primitive","text":"Nearest int value (regardless of the current rounding mode) can be expressed as round in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{roundf}(x(t)) Example","title":"round Primitive"},{"location":"manual/syntax/#delay-primitives-and-modifiers","text":"Faust hosts various modifiers and primitives to define one sample or integer delay of arbitrary length. They are presented in this section.","title":"Delay Primitives and Modifiers"},{"location":"manual/syntax/#mem-primitive","text":"A 1 sample delay can be expressed as mem in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+1)=x(t),y(0)=0 Example Note that this is equivalent to process = _' (see ' Modifier ) and process = @(1) (see @ Primitive )","title":"mem Primitive"},{"location":"manual/syntax/#modifier","text":"' can be used to apply a 1 sample delay to a signal in Faust. It can be seen as syntactic sugar to the mem primitive . ' is very convenient when implementing filters and can help significantly decrease the size of the Faust code. Example","title":"' Modifier"},{"location":"manual/syntax/#primitive","text":"An integer delay of N samples can be expressed as @(N) in Faust. Note that N (automatically promoted to int ) can be dynamic but that its range must be bounded. This can be done by using a UI primitive (see example below) allowing for the definition of a range such as hslider , vslider , or nentry . Note that floating point delay is also available in Faust by the mean of various fractional delay implementations available in the Faust standard libraries. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+x_{2}(t))=x_{1}(t), y(t<x_{2}(t))=0 Usage _ : @(N) : _ Where: N : the length of the delay as a number of samples Example: Static N Samples Delay Example: Dynamic N Samples Delay","title":"@ Primitive"},{"location":"manual/syntax/#table-primitives","text":"","title":"Table Primitives"},{"location":"manual/syntax/#rdtable-primitive","text":"The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The table can either be implemented by using the waveform primitive (as shown in the first example) or using a function controlled by a timer (such as ba.time ) as demonstrated in the second example. The idea is that the table is created during the initialization step and before audio computation begins. Type: \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=T[r(t)] Usage rdtable(n,s,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the table content r : the read index (an int between 0 and n-1 ), automatically promoted to int Example: Basic Triangle Wave Oscillator Using the waveform Primitive In this example, a basic (and dirty) triangle wave-table is defined using the waveform . It is then used with the rdtable primitive and a phasor to implement a triangle wave oscillator: Example: Basic Triangle Wave Oscillator Using the sin Primitive and a Timer In this example, a sine table is implemented using the sin primitive and a timer ( ba.time ). The timer calls the sin function during the initialization step of the Faust program. It is then used with rdtable to implement a sine wave oscillator.","title":"rdtable Primitive"},{"location":"manual/syntax/#rwtable-primitive","text":"The rwtable primitive can be used to implement a read/write table. It takes an audio input that can be written in the table using a write index (i.e., w below) and read using a read index (i.e., r below). Type: \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} Mathematical Description: T[w(t)]=c(t); y(t)=T[r(t)] Usage _ : rwtable(n,s,w,_,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the initial table content w : the write index (an int between 0 and n-1 ), automatically promoted to int r : the read index (an int between 0 and n-1 ), automatically promoted to int Note that the fourth argument of rwtable corresponds to the input of the table. Example: Simple Looper In this example, an input signal is written in the table when record is true (equal to 1). The read index is constantly updated to loop through the table. The table size is set to 48000, which corresponds to one second if the sampling rate is 48000 KHz.","title":"rwtable Primitive"},{"location":"manual/syntax/#selector-primitives","text":"Selector primitives can be used to create conditions in Faust and to implement switches to choose between several signals.","title":"Selector Primitives"},{"location":"manual/syntax/#select2-primitive","text":"The select2 primitive is a \"two-way selector\". It has three input signals: s , x_0 , x_1 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other two inputs x_0(t) and x_1(t) to the output y(t) . Note Please note that select2 is not the equivalent of a traditional if-then-else construction. Like every Faust primitive, it has a strict semantics. All input signals are always computed, even when they are not selected. Therefore you can't use select2 to avoid computing something. The semantics of select2 is as follows: Type: (s,x_0,x_1)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\end{array} \\right. Usage _,_ : select2(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine and a sawtooth wave oscillator. Note that select2 could be easily implemented from scratch in Faust: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.","title":"select2 Primitive"},{"location":"manual/syntax/#select3-primitive","text":"The select3 primitive is a \"three-ways selector\". It has four input signals: s , x_0 , x_1 , x_2 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other three inputs x_0(t) , x_1(t) and x_2(t) to the output y(t) . Type: (s,x_0,x_1,x_2)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\\\ x_2(t) & \\mathrm{if\\ } s(t) = 2.\\end{array} \\right. Usage _,_,_ : select3(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one, 2 for the third one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine, a sawtooth and a triangle wave oscillator. Note that select3 could be easily implemented from scratch in Faust using Boolean primitives: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.","title":"select3 Primitive"},{"location":"manual/syntax/#specific-primitives","text":"In Faust, signals operate within a [min, max] range. The lowest(sig) primitive determines the minimum value a given sig signal can attain, while the highest(sig) primitive identifies its maximum value. However, be aware that the compiler's interval computation might not accurately estimate the true [min, max] range, often resulting in -INFINITY for the minimum value and/or INFINITY for the maximum value.","title":"Specific Primitives"},{"location":"manual/syntax/#user-interface-primitives-and-configuration","text":"Faust user interface widgets/primitives allow for an abstract description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be discrete (e.g., button , checkbox , etc.), continuous (e.g., hslider , vslider , nentry ), and organizational (e.g., vgroup , hgroup ). Discrete and continuous elements are signal generators. For example, a button produces a signal which is 1 when the button is pressed and 0 otherwise: These signals can be freely combined with other audio signals. In fact, the following code is perfectly valid and will generate sound: Each primitive implements a specific UI element, but their appearance can also be completely modified using metadata (a little bit like HTML and CSS in the web). Therefore, hslider , vslider , and nentry ) can for example be turned into a knob, a dropdown menu, etc. This concept is further developed in the section on UI metadata . Continuous UI elements (i.e., hslider , vslider , and nentry ) must all declare a range for the parameter they're controlling. In some cases, this range is used during compilation to allocate memory and will impact the generated code. For example, in the case of: a buffer of 10 samples will be allocated for the delay implemented with the @ primitive while 20 samples will be allocated in the following example:","title":"User Interface Primitives and Configuration"},{"location":"manual/syntax/#button-primitive","text":"The button primitive implements a button. Usage button(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger","title":"button Primitive"},{"location":"manual/syntax/#checkbox-primitive","text":"The checkbox primitive implements a checkbox/toggle. Usage checkbox(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger","title":"checkbox Primitive"},{"location":"manual/syntax/#hslider-primitive","text":"The hslider primitive implements a horizontal slider. Usage hslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example: Gain Control Example: Additive Oscillator Here is an example of a 3 oscillators instrument where the default frequency of each partial is computed using a more complex constant numerical expression .","title":"hslider Primitive"},{"location":"manual/syntax/#vslider-primitive","text":"The vslider primitive implements a vertical slider. Usage vslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example","title":"vslider Primitive"},{"location":"manual/syntax/#nentry-primitive","text":"The nentry primitive implements a \"numerical entry\". Usage nentry(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the numerical entry, a constant numerical expression min : the minimum value of the numerical entry, a constant numerical expression max : the maximum value of the numerical entry, a constant numerical expression step : the precision (step) of the numerical entry (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example","title":"nentry Primitive"},{"location":"manual/syntax/#hgroup-primitive","text":"The hgroup primitive implements a horizontal group. A group contains other UI elements that can also be groups. hgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage hgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"hgroup Primitive"},{"location":"manual/syntax/#vgroup-primitive","text":"The vgroup primitive implements a vertical group. A group contains other UI elements that can also be groups. vgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage vgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"vgroup Primitive"},{"location":"manual/syntax/#tgroup-primitive","text":"The tgroup primitive implements a \"tab group.\" Tab groups can be used to group UI elements in tabs in the interface. A group contains other UI elements that can also be groups. tgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage tgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"tgroup Primitive"},{"location":"manual/syntax/#vbargraph-primitive","text":"The vbargraph primitive implements a vertical bar-graph (typically a meter displaying the level of a signal). Usage vbargraph takes an input signal and outputs it while making it available to the UI. _ : vbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the vbargraph primitive: Note the use of the attach primitive here that forces the compilation of the vbargraph without using its output signal (see section on the attach primitive ).","title":"vbargraph Primitive"},{"location":"manual/syntax/#hbargraph-primitive","text":"The hbargraph primitive implements a horizontal bar-graph (typically a meter displaying the level of a signal). Usage hbargraph takes an input signal and outputs it while making it available to the UI. _ : hbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the hbargraph primitive: Note the use of the attach primitive here that forces the compilation of the hbargraph without using its output signal (see section on the attach primitive ).","title":"hbargraph Primitive"},{"location":"manual/syntax/#attach-primitive","text":"The attach primitive takes two input signals and produces one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical standpoint attach(x,y) is equivalent to 1*x+0*y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role, let's say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelope detector connected to a bargraph. The problem is that the signal of the envelope generators has no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. The examples in the hbargraph Primitive and the vbargraph Primitive illustrate well the use of attach .","title":"attach Primitive"},{"location":"manual/syntax/#variable-parts-of-a-label","text":"Labels can contain variable parts. These are indicated with the sign % followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example: creates 8 sliders in parallel with different names while par(i,8,hslider(\"Voice\",0.9,0,1,0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) .","title":"Variable Parts of a Label"},{"location":"manual/syntax/#labels-as-pathnames","text":"Thanks to horizontal , vertical , and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of hslider(\"../volume\",...) would have been /h:Foo/volume , while the pathname of hslider(\"t:Fii/volume\",...) would have been /h:Foo/v:Faa/t:Fii/volume . Elements of a path are separated using / . Group types are defined with the following identifiers: Group Type Group Identifier hgroup h: vgroup v: tgroup t: Hence, the example presented in the section on the hgroup primitive can be rewritten as: which will be reflected in C++ as: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider1, 440.0f, 50.0f, 1000.0f, 0.100000001f); ui_interface->addVerticalSlider(\"gain\", &fVslider0, 0.0f, 0.0f, 1.0f, 0.00999999978f); ui_interface->closeBox(); } Note that path names are inherent to the use of tools gravitating around Faust such as OSC control or faust2api . In the case of faust2api , since no user interface is actually generated, UI elements just become a way to declare parameters of a Faust object. Therefore, there's no distinction between nentry , hslider , vslider , etc.","title":"Labels as Pathnames"},{"location":"manual/syntax/#smoothing","text":"Despite the fact that the signal generated by user interface elements can be used in Faust with any other signals, UI elements run at a slower rate than the audio rate. This might be a source of clicking if the value of the corresponding parameter is modified while the program is running. This behavior is also amplified by the low resolution of signals generated by UI elements (as opposed to actual audio signals). For example, changing the value of the freq or gain parameters of the following code will likely create clicks (in the case of gain ) or abrupt jumps (in the case of freq ) in the signal: This problem can be easily solved in Faust by using the si.smoo function which implements an exponential smoothing by a unit-dc-gain one-pole lowpass with a pole at 0.999 ( si.smoo is just sugar for si.smooth(0.999) ). Therefore, the previous example can be rewritten as: Beware that each si.smoo that you place in your code will add some extra computation so they should be used precociously.","title":"Smoothing"},{"location":"manual/syntax/#links-to-generated-code","text":"UI elements provide a convenient entry point to the DSP process in the code generated by the Faust compiler (e.g., C++, etc.). For example, the Faust program: import(\"stdfaust.lib\"); freq = hslider(\"freq\",440,50,1000,0.1); process = os.osc(freq); will have the corresponding buildUserInterface method in C++: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"osc\"); ui_interface->addHorizontalSlider(\"freq\", &fHslider0, 440.0f, 50.0f, 1000.0f, 0.100001f); ui_interface->closeBox(); } The second argument of the addHorizontalSlider method is a pointer to the variable containing the current value of the freq parameter. The value of this pointer can be updated at any point to change the frequency of the corresponding oscillator.","title":"Links to Generated Code"},{"location":"manual/syntax/#ui-label-metadata","text":"Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface, configure OSC and accelerometer control/mapping, etc. Since the format of the value associated to a key is relatively open, metadata constitute a flexible way for programmers to add features to the language. The Faust code: process = *(hslider(\"foo[key1: val 1][key2: val 2]\",0,0,1,0.1)); will produce the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tst\"); ui_interface->declare(&fHslider0, \"key1\", \"val 1\"); ui_interface->declare(&fHslider0, \"key2\", \"val 2\"); ui_interface->addHorizontalSlider(\"foo\", &fHslider0, 0.0f, 0.0f, 1.0f, 0.100000001f); ui_interface->closeBox(); } ... }; All metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. Metadata are architecture-specific: it is up to the architecture file to decide what to do with it. While some metadata will work with most architectures (e.g., accelerometer and OSC configuration, etc.), others might be more specific. Some of them are presented in the following sections.","title":"UI Label Metadata"},{"location":"manual/syntax/#ordering-ui-elements","text":"The order of UI declarations in a Faust code doesn't necessarily reflect the actual order of the UI elements in the corresponding interface. Therefore, UI elements can be ordered by placing a metadata before the declaration of the name of the UI element in the label. For example, in the following declaration: gain = vslider(\"h:Oscillator/[1]gain\",0,0,1,0.01); freq = vslider(\"h:Oscillator/[0]freq\",440,50,1000,0.1); the freq parameter will be placed before gain despite the fact that gain is declared first. This system can be used to order groups as well. Ordering will be carried out on elements at the same level. For example: Note that this could also be written as:","title":"Ordering UI Elements"},{"location":"manual/syntax/#global-ui-metadata","text":"Note that global user interfaces completely replacing the one defined using the standard Faust UI primitives may be declared using global metadata . This is the case of the SmartKeyboard interface for example. In the following subsections, the standard Faust UI metadata are documented. Other types of metadata (e.g., accelerometers, OSC, etc.) are documented in the sections related to these topics.","title":"Global UI Metadata"},{"location":"manual/syntax/#styleknob-metadata","text":"The [style:knob] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a knob. Example","title":"[style:knob] Metadata"},{"location":"manual/syntax/#stylemenu-metadata","text":"The [style:menu] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a drop-down menu. Usage [style:menu{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector","title":"[style:menu] Metadata"},{"location":"manual/syntax/#styleradio-metadata","text":"The [style:radio] metadata turns a hslider or a vslider into a radio-button-menu. The orientation of the menu is determined by the type of UI element (i.e., hslider for horizontal and vslider for vertical). Usage [style:radio{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector","title":"[style:radio] Metadata"},{"location":"manual/syntax/#styleled-metadata","text":"The [style:led] metadata turns a vbargraph or a hbargraph into a blinking LED (with varying intensity). Example: Level Display","title":"[style:led] Metadata"},{"location":"manual/syntax/#stylenumerical-metadata","text":"The [style:numerical] metadata turns a vbargraph or a hbargraph into a numerical zone (thus the bargraph itself is no more displayed). Example: Level Display","title":"[style:numerical] Metadata"},{"location":"manual/syntax/#unitdb-metadata","text":"The [unit:dB] metadata changes the unit of a vbargraph or a hbargraph to dB. This impacts its overall appearance by applying a rainbow color scheme, etc. Example: Level Display","title":"[unit:dB] Metadata"},{"location":"manual/syntax/#unitxx-metadata","text":"The [unit:xx] metadata allows us to specify the unit of a UI element. The unit will be displayed right next to the current value of the parameter in the interface. Usage [unit:xx] Where: xx : the unit of the current parameter Example","title":"[unit:xx] Metadata"},{"location":"manual/syntax/#scalexx-metadata","text":"The [scale:xx] metadata allows for the specification of a scale (different than the default linear one) to the parameter in the UI. [scale:log] can be used to change to scale to logarithmic and [scale:exp] to exponential.","title":"[scale:xx] Metadata"},{"location":"manual/syntax/#tooltipxx-metadata","text":"The [tooltip:xx] metadata allows for the specification of a \"tooltip\" when the mouse hover a parameter in the interface. This is very convenient when implementing complex interfaces. Usage [tooltip:xx] Where: xx : a string to be used as a tooltip in the interface Example","title":"[tooltip:xx] Metadata"},{"location":"manual/syntax/#hidden01-metadata","text":"The [hidden:0|1] metadata can be used to hide a parameter in the interface. This is convenient when controlling a parameter with a motion sensor or OSC messages and we don't want it to be visible in the interface. This feature is commonly used when making apps for Android and iOS using faust2android , faust2ios or in the Web platform. Compatibility iOS Android Web platform","title":"[hidden:0|1] Metadata"},{"location":"manual/syntax/#sensors-control-metadatas","text":"Sensors control metadata can be used to map the built-in sensors of mobile devices to some of the parameters of a Faust program. Compatibility These metadatas are compatible with the following Faust targets and no additional step is required for them to be taken into account when the corresponding application is generated: faust2android faust2ios faust2smartkeyb Sensors control metadatas have five parameters and follow the following syntax: [acc: a b c d e] // for accelerometer [gyr: a b c d e] // for gyroscope They can be used in a Faust UI parameter declaration: parameter = nentry(\"UIparamName[acc: a b c d e]\",def,min,max,step); with: a : the accelerometer axis ( 0 : x, 1 : y, 2 : z) b : the accelerometer curve (see figure below) c : the minimum acceleration (m/s^2) d : the center acceleration (m/s^2) e : the maximum acceleration (m/s^2) def : the default/init value of the parameter min : the minimum value of the parameter max : the maximum value of the parameter step : the step of the parameter (precision) This allows for the implementation of complex linear and non-linear mappings that are summarized in this figure: For example, controlling the gain of a synthesizer using the X axis of the accelerometer can be easily done simply by writing something like: g = nentry(\"gain[acc: 0 0 -10 0 10]\",0.5,0,1,0.01); With this configuration, g = 0 when the device is standing vertically on its right side, g = 0.5 when the device is standing horizontally with screen facing up, and g = 1 when the device is standing vertically on its left side. Finally, in this slightly more complex mapping, g = 0 when the device is tilted on its right side and the value of g increases towards 1 when the device is tilted on its left side: g = nentry(\"gain[acc: 0 0 0 0 10]\",0,0,1,0.01); Complex nonlinear mappings can be implemented using this system.","title":"Sensors Control Metadatas"},{"location":"manual/syntax/#widget-modulation","text":"Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: Here is a very simple example, assuming freeverb is a fully fonctional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb]","title":"Widget Modulation"},{"location":"manual/syntax/#target-widgets","text":"Target widgets are specified by their label. Of course, this presupposes knowing the names of the sliders. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in: \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb]","title":"Target Widgets"},{"location":"manual/syntax/#modulators","text":"Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: [\"Wet\": * -> freeverb] Please note that the ':' sign used here is just a visual separator, it is not the sequential composition operator. To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 .","title":"Modulators"},{"location":"manual/syntax/#modulators-with-no-inputs","text":"Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb]","title":"Modulators with no inputs"},{"location":"manual/syntax/#modulators-with-one-input","text":"A 1->1 modulator transforms the signal produced by the widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider.","title":"Modulators with one input"},{"location":"manual/syntax/#modulators-with-two-inputs","text":"Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs. Here is a complete example:","title":"Modulators with two inputs"},{"location":"manual/tools/","text":"faust2[...] Tools While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This description provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust tools is a set of scripts that take a dsp file as input to generate various output for a lot of architectures and platforms. All the tools names are in the form faust2xx where xx is the target architecture. Use -h or -help to get more information on each specific script options, the supported platforms and possibly the required packages. Additional Faust compiler options (like -vec -lv 0 -I /path/to/lib ) can be given. For scripts that combines Faust and the C++ compiler, you can possibly use the CXXFLAGS environment variable to give additional options to the C++ compiler. Note that some of the tools are somewhat meta tools when they are based on a framework that itself can generate several formats later on. This is the case of the faust2juce script for instance. Note that using -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. The template-llvm.cpp file that uses libfaust + LLVM backend to dynamically compile a foo.dsp file is an example of this approach. It has be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application. or: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp to generate a polyphonic (8 voices), MIDI controllable faust2cagtk-llvm application. Note that libfaust and LLVM libraries still have to be added at the link stage, so a -dyn : create libfaust + LLVM backend dynamic version option has been added to the faust2cagtk tool and some others. faust2alqt Usage: faust2alqt [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa, QT Compiles Faust programs to ALSA and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2alsa Usage: faust2alsa [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to ALSA and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2alsaconsole Usage: faust2alsaconsole [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to CLI and ALSA Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -arch32 : compiles a 32 bits binary -arch64 : compiles a 64 bits binary Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2android Usage: faust2android [options] [Faust options] <file.dsp> Target platform: Android Require: Android SDK Compile a Faust program to an Android app (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/android) Options: -osc : activates OSC control -source : creates an eclipse project of the app in the current directory. -swig : regenerates the C++ and the JAVA interface for the native portion of the app. -faust : only carries out the Faust compilation and install the generated C++ file in the JNI folder. -reuse : preserves build directory and reuse it to speedup compilation. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -install : once compilation is over, installs the generated apk on the Android device connected to the computer -debug : activates verbose output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2androidunity Usage: faust2androidunity [options] [Faust options] <file1.dsp> [<file2.dsp>] Target platform: Android Unity Require: Android SDK Make sure the ANDROID_HOME environment variable is set to the sdk folder. Creates android libraries (armeabi-v7a and x86) for faust unity plugin. If you need other android architectures, open architecture/unity/Android/Application.mk and modify APP_ABI. See architecture/unity/README.md for more info (also available from the compile folder) Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -android : creates also the c# and JSON files Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2api Usage: faust2api [options] [Faust options] <file.dsp> faust2api can be used to generate Faust based dsp objects for various platforms (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/api): Output options: -ios : generates an iOS API -android : generates an Android API -coreaudio : generates an OSX CoreAudio API -alsa : generates an ALSA API -jack : generates a JACK API -portaudio : generates a PortAudio API -rtaudio : generates an RTAudio API -of : generates an openFrameworks API -juce : generates a JUCE API -dummy : generates a dummy audio API -teensy : generates a Teensy API -esp32 : generates a ESP32 API Global options: -opt native|generic : activates the best compilation options for the native or generic CPU -nvoices <num> : creates a polyphonic object with <num> voices -effect <effect.dsp> : adds an effect to the polyphonic synth (ignored if -nvoices is not specified) -effect auto : adds an effect (extracted automatically from the dsp file) to the polyphonic synth (ignored if -nvoices is not specified) -nodoc : prevents documentation from being generated -nozip : prevents generated files to be put in a zip file -target <target> : sets a name of the target folder or the zip file. Defaults to \"dsp-faust\" Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. Android specific options: -package : set the JAVA package name (e.g. '-package mypackage' will change the JAVA package name to 'mypackage.DspFaust'). The default package name is 'com.DspFaust.' -soundfile : add built-in Soundfile support to the API Options supported by iOS, CoreAudio, ALSA, JACK, PortAudio, openFrameworks and JUCE -midi : add built-in RtMidi support to the API -osc : add built-in OSC support to the API -soundfile : add built-in Soundfile support to the API JACK specific options -build : build a ready to test binary -dynamic : add libfaust/LLVM dynamic DSP compilation mode faust2bela Usage: faust2bela [options] [Faust options] <file.dsp> Target platform: Bela Compiles Faust programs to the BELA board Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Polyphonic mode means MIDI instrument with at least 1 voice. Use no arguments for a simple effect. -gui : activates a self-hosted GUI interface. Requires to have libmicrohttpd and libHTTPDFaust installed. -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI -tobela : to send C++ file into bela, and to run it Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2bench Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2caconsole Usage: faust2caconsole [options] [Faust options] <file.dsp> Target platform: MacOS Compiles Faust programs to CLI and CoreAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2cagtk Usage: faust2cagtk [options] [Faust options] <file.dsp> Target platform: MacOS Require: GTK Compiles Faust programs to CoreAudio and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2caqt Usage: faust2caqt [options] [Faust options] <file.dsp> Target platform: MacOS Require: QT Compiles Faust programs to CoreAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -opt native' to activate the best compilation options for the native CPU : -opt generic' to activate the best compilation options for a generic CPU : -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -resample : to resample soundfiles to the audio driver sample rate -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -me : to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow) -debug : to print all the build steps -nodeploy : skip self-contained application generation (using 'macdeployqt') -I include-path : add an include-directory to the generated Qt project for finding ffunction headers and such Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2cmajor Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/cmajor) Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -test : to test the resulting patch with 'cmaj render' -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2comparator Usage: faust2comparator [options] [Faust options] <file.dsp> faust2csound Usage: faust2csound [options] [Faust options] <file.dsp> Target platform: any Require: CSound Dev Kit Compiles a Faust program into a Csound opcode Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2csvplot Usage: faust2csvplot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 5 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) -bs <buffer> : change the buffer size (default is 512 frames) Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. -double : generates code with samples of type 'double'. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2daisy faust2daisy [-patch] [-midi] [-nvoices <num>] [-sr <num>] [-bs <num>] [-source] [Faust options (-vec -vs 8...)] <file.dsp> Compiles Faust programs to Daisy boards (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/daisy) Options: -patch : to compile for 4 ins/outs Patch (knob[1,2,3,4]) -pod : to compile for 2 ins/outs Pod (knob[1,3]) -patchsm : to compile for the Pod.init eurorack module -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -sr <num> : to specify sample rate -bs <num> : to specify buffer size -source : to only create the source folder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2dplug Usage: faust2dplug [options] [Faust options] <file.dsp> Require: Dplug Compiles Faust programs to Dplug plugins Options: -vendor <My Company Name> : -vendorid <FaUs> : -pluginid <PlUg> : -homepage <https://faust.grame.fr/> : -effectType <effectDynamics> : Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2dssi Usage: faust2dssi [options] [Faust options] <file.dsp> Compiles Faust programs to dssi plugins Options: -osc : activates OSC control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2esp32 Usage: faust2esp32 [options] [Faust options] <file.dsp> <file.dsp> faust2esp32 can be used to fully program the ESP32 microncontroller and to generate DSP objects that can be integrated into any ESP32 project (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/esp32) Options: -gramophone : generates for GRAME Gramophone -multi : generate for GRAME Gramophone in multi DSP mode -lib : generates a package containing an object compatible with any ESP32 project -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -main : add a 'main' entry point -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -wm8978, -es8388 or -ac101 : to choose codec driver Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2faustvst Usage: faust2faustvst [options ...] <file.dsp> Require: VST SDK Compiles Faust programs to VST plugins Options: -gui : build the plugin GUI. -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui). -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include FAUSTARCH: specify the location of the Faust VST library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake SDK: specify the location of the VST SDK Default: /usr/local/src/vstsdk SDKSRC: specify the location of the VST SDK sources Default: /usr/local/src/vstsdk/public.sdk/source/vst2.x faust2feh Usage: faust2feh <file.dsp> Compiles Faust programs to SVG and opens them with feh faust2gen Usage: faust2gen [options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to a fausgen~ patch Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events faust2ios Usage: faust2ios [options] [Faust options] <file.dsp> Target platform: iOS Compiles Faust programs to iOS applications Options: -midi : activates MIDI control -osc : activates OSC control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -xcode : to compile and keep the intermediate Xcode project -xcodeproj : to produce the intermediate Xcode project -archive : to generate the archive for Apple Store -32bits : to compile 32 bits only binary -noagc : to deactivate audio automatic gain control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jack Usage: faust2jack [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack Compiles Faust programs to JACK and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackconsole Usage: faust2jackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to CLI and JACK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackrust Usage: faust2jackrust [-source] [Faust options] <file.dsp> Compiles Faust programs to JACK and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackserver Usage: faust2jackserver [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT (server mode) Options: -httpd : activates HTTP control -osc : activates OSC control -qrcode : activates QR code generation Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jaqt Usage: faust2jaqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -resample : to resample soundfiles to the audio driver sample rate. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jaqtchain Usage: faust2jaqtchain [options] [Faust options] <file.dsp> Require: Jack, QT Compiles several Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2juce Usage: faust2juce [options] [Faust options] <file.dsp> Require: Juce Compiles Faust programs to JUCE standalones or plugins (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/juce) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -standalone : to produce a standalone project, otherwise a plugin project is generated -vst2sdkdir <folder> : to set directory to VST 2 SDK. -jucemodulesdir <folder> : to set JUCE modules directory to <folder>, such as ~/JUCE/modules -disable-splash-screen : to disable the JUCE splash screen (license is required). -jsynth : to use JUCE polyphonic Synthesizer instead of Faust polyphonic code -llvm : to use the LLVM compilation chain (OSX and Linux for now) -magic : to generate a project using the PluginGuiMagic GUI builder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2ladspa Usage: faust2ladspa [options] [Faust options] <file.dsp> Target platform: Linux Compiles Faust programs to LADSPA plugins Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2linuxunity Usage: faust2linuxunity [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack, Unity Compiles Faust programs to Linux x86_64 libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2lv2 -std=c++11 -fvisibility=hidden -O3 Usage: faust2lv2 [options ...] <file.dsp> Require: QT Compiles Faust programs to lv2 plugins Options: -dyn-manifest : use dynamic manifests (requires LV2 host support). -gui : build the plugin GUI (requires LV2 UI host support). -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -osx : -osx to compile on OSX -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui) -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include/faust FAUSTLIB: specify the location of the Faust LV2 library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake faust2mathdoc Usage: faust2mathdoc [options] <file.dsp> Require: svg2pdf pdflatex breqn Generate a full Faust documentation in a '*-mdoc' top directory Options: -l LANG : LANG is usually a 2-lowercase-letters language name, like en, fr, or it. -utf8 : force file.dsp to be recoded in UTF-8 before being processed faust2max6 Usage: faust2max6 [options] [Faust options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to Max6 externals using double precision samples (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/max-msp) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -soundfile-dynamic : similar to -soundfile, but using the installed libsndfile (so possibly using dynamic link). -opt native|generic : activates the best compilation options for the native or generic CPU. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -us <factor> : upsample the DSP by a factor -ds <factor> : downsample the DSP by a factor -filter <filter> : use a filter for upsampling or downsampling [0..4] -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -mc : to activate multi-channels model -native : to compile for the native CPU (otherwise the 'generic' mode is used by default) -universal : to generate a universal (arm/intel) external -nopatch : to deactivate patch generation -nopost : to disable Faust messages to Max console Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2minimal Usage: faust2minimal [options] [Faust options] <file.dsp> Compiles Faust programs to a minimal executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2netjackconsole Usage: faust2netjackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to NetJack Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2netjackqt Usage: faust2netjackqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to NetJack and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2nodejs Usage: faust2nodejs [driver] [Faust options] <file.dsp> Generate Faust-based nodejs native addons. The generated addons can embed most of the audio engines supported by Faust: ALSA, JACK, CoreAudio, RtAudio, PortAudio, etc. Since faust2nodejs essentially acts as a wrapper to faust2api, it offers the same features than this system (MIDI and OSC support, polyphony, separate effect file, etc.). The following drivers are available: -coreaudio // -alsa // -jack // -portaudio // -rtaudio // -dummy. For example, to create a native nodejs addon with a JACK audio engine, run: faust2nodjs -jack faustFile.dsp The following options are inherited directly from faust2api and can be used with faust2nodejs: Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -source : generates the source of the addon without compiling it -electronv <VERSION> : allows to specify the current version of electron if generating an addon for this framework -debug : prints compilation output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2osxiosunity Usage: faust2osxiosunity [options] [Faust options] <file.dsp> Target platform: MacOSX Require: Unity Compiles Faust programs to OSX/iOS libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -ios : create an iOS static library -universal : generate a 64/32 bits external Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info. faust2paconsole Usage: faust2paconsole [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2paqt Usage: faust2paqt [options] [Faust options] <file.dsp> Require: PortAudio, QT Compiles Faust programs to PortAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2plot Usage: faust2plot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 4 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2portaudiojulia Usage: faust2portaudiojulia [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Julia binary -osc : to activate OSC control on 5000 and 5001 ports -play <num> : to start the 'Julia' runtime with <num> threads and the generated file.jl Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2portaudiorust Usage: faust2portaudiorust [-source] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2raqt Usage: faust2raqt [options] [Faust options] <file.dsp> Require: QT Compiles Faust programs to RtAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rnbo Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rpialsaconsole Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: Alsa Compiles Faust programs to RaspberryPi - alsa console architecture Options: -osc : activates OSC control -httpd : activates HTTP control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rpinetjackconsole Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: NetJack Compiles Faust programs to RaspberryPi - netjack-console architecture Options: -osc : activates OSC control -httpd : activates HTTP control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2sam Usage: faust2sam [options] [Faust options] <file.dsp> Target platform: ADI SHARC Audio Module board Generates inline Faust objects for the ADI SHARC Audio Module board Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2smartkeyb FAUST2SMARTKEYB - MUSICAL MOBILE APP GENERATOR faust2smartkeyb takes a Faust code as its main argument and convert it into a ready-to-use app for Android or iOS. The only two required arguments of faust2smartkeyb are a Faust file and the target platform (-android or -ios): Usage: faust2smartkeyb [options] [Faust options] <file.dsp> Target platform: iOS, Android Options: -android : generates an Android app -ios : generates an iOS app -osc : activates OSC control -debug : activate debug mode -effect : allow to specify an effect Faust file (e.g., -effect myEffect.dsp) -install : install the app on the connected device (Android only) -nvoices : specify the max number of voices -reuse : reuse the same project source -source : only generate the source (no compilation) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. More information and tutorials at: https://ccrma.stanford.edu/~rmichon/smartKeyboard faust2sndfile Usage: faust2sndfile [Faust options] <file.dsp> Require: libsndfile Process audio files with Faust DSP Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2stratus Usage: faust2stratus [options] [Faust options] <file.dsp> ... [<file.cpp> ...] Target platform: Chaos Audio Stratus pedal Compiles Faust programs for the Chaos Audio Stratus pedal with optional c++ compile for, and effect install to, the pedal Unlike most other faust2xxx scripts, this can also be used to compile effect c++ code that has been constructed elsewhere, or has been modified after being generated by the Faust compiler (e.g. where the algorithm c++ code has been 'tweaked' after generation) The script can be used to build and install multiple different effects in one go Running this script with no options except input files will result in effect libraries built for the platform upon which the script is executed, not for the pedal Options: -nocppc : Do not compile the generated c++ source files -nodocker : Do not use docker for pedal builds even if it is available -stratusbuild : Generates the c++ code locally, then builds the effect library for the Stratus pedal -stratusinstall : Generates the c++ code locally, then builds and installs the effect library for the Stratus pedal Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. the script automatically uses '-i -scn FaustDSP -light -nvi' -O and/or -o can be used, otherwise all output is in the same folder as the corresponding input faust2teensy faust2teensy [-lib] [-midi] [-nvoices <num>] [Faust options (-vec -vs 8...)] <file.dsp> Options: -lib : generates a package containing an object compatible with the Teensy audio library (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/teensy) -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2unity Usage: faust2unity [options] [Faust options] <file.dsp> Target platform: Android, Linux, MacOSX, iOS, Windows Require: Unity Generates a unity package (compressed .unitypackage folder) with all available architecture libraries for faust unity plugin and the C# files required. Use arguments to generate specific architectures (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/unity) Options: -w32 : generates a Windows 32 bits library -w64 : generates a Windows 64 bits library -osx : generates a macOS library -ios : generates an iOS library -android : generates Android libraries (armeabi-v7a and x86). -linux : generates a Linux library -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -source : generates the source files (uncompressed folder) -unpacked : generates an unpacked folder with files organized like the Unity Asset hierarchy. Use this options to add specific files in the unity package (in the Assets folder, then use 'encoderunitypackage <folder>' to compress and pack it. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info. faust2vcvrack faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [Faust options] <file.dsp> Compiles Faust programs to VCV Rack modules (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/vcvrack) -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -source : to only create the source folder -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -version <1|2> : to set the plugin version, 2 by default Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2[...] Tools"},{"location":"manual/tools/#faust2-tools","text":"While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This description provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust tools is a set of scripts that take a dsp file as input to generate various output for a lot of architectures and platforms. All the tools names are in the form faust2xx where xx is the target architecture. Use -h or -help to get more information on each specific script options, the supported platforms and possibly the required packages. Additional Faust compiler options (like -vec -lv 0 -I /path/to/lib ) can be given. For scripts that combines Faust and the C++ compiler, you can possibly use the CXXFLAGS environment variable to give additional options to the C++ compiler. Note that some of the tools are somewhat meta tools when they are based on a framework that itself can generate several formats later on. This is the case of the faust2juce script for instance. Note that using -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. The template-llvm.cpp file that uses libfaust + LLVM backend to dynamically compile a foo.dsp file is an example of this approach. It has be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application. or: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp to generate a polyphonic (8 voices), MIDI controllable faust2cagtk-llvm application. Note that libfaust and LLVM libraries still have to be added at the link stage, so a -dyn : create libfaust + LLVM backend dynamic version option has been added to the faust2cagtk tool and some others.","title":"faust2[...] Tools"},{"location":"manual/tools/#faust2alqt","text":"Usage: faust2alqt [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa, QT Compiles Faust programs to ALSA and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alqt"},{"location":"manual/tools/#faust2alsa","text":"Usage: faust2alsa [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to ALSA and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alsa"},{"location":"manual/tools/#faust2alsaconsole","text":"Usage: faust2alsaconsole [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to CLI and ALSA Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -arch32 : compiles a 32 bits binary -arch64 : compiles a 64 bits binary Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alsaconsole"},{"location":"manual/tools/#faust2android","text":"Usage: faust2android [options] [Faust options] <file.dsp> Target platform: Android Require: Android SDK Compile a Faust program to an Android app (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/android) Options: -osc : activates OSC control -source : creates an eclipse project of the app in the current directory. -swig : regenerates the C++ and the JAVA interface for the native portion of the app. -faust : only carries out the Faust compilation and install the generated C++ file in the JNI folder. -reuse : preserves build directory and reuse it to speedup compilation. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -install : once compilation is over, installs the generated apk on the Android device connected to the computer -debug : activates verbose output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2android"},{"location":"manual/tools/#faust2androidunity","text":"Usage: faust2androidunity [options] [Faust options] <file1.dsp> [<file2.dsp>] Target platform: Android Unity Require: Android SDK Make sure the ANDROID_HOME environment variable is set to the sdk folder. Creates android libraries (armeabi-v7a and x86) for faust unity plugin. If you need other android architectures, open architecture/unity/Android/Application.mk and modify APP_ABI. See architecture/unity/README.md for more info (also available from the compile folder) Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -android : creates also the c# and JSON files Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2androidunity"},{"location":"manual/tools/#faust2api","text":"Usage: faust2api [options] [Faust options] <file.dsp> faust2api can be used to generate Faust based dsp objects for various platforms (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/api): Output options: -ios : generates an iOS API -android : generates an Android API -coreaudio : generates an OSX CoreAudio API -alsa : generates an ALSA API -jack : generates a JACK API -portaudio : generates a PortAudio API -rtaudio : generates an RTAudio API -of : generates an openFrameworks API -juce : generates a JUCE API -dummy : generates a dummy audio API -teensy : generates a Teensy API -esp32 : generates a ESP32 API Global options: -opt native|generic : activates the best compilation options for the native or generic CPU -nvoices <num> : creates a polyphonic object with <num> voices -effect <effect.dsp> : adds an effect to the polyphonic synth (ignored if -nvoices is not specified) -effect auto : adds an effect (extracted automatically from the dsp file) to the polyphonic synth (ignored if -nvoices is not specified) -nodoc : prevents documentation from being generated -nozip : prevents generated files to be put in a zip file -target <target> : sets a name of the target folder or the zip file. Defaults to \"dsp-faust\" Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. Android specific options: -package : set the JAVA package name (e.g. '-package mypackage' will change the JAVA package name to 'mypackage.DspFaust'). The default package name is 'com.DspFaust.' -soundfile : add built-in Soundfile support to the API Options supported by iOS, CoreAudio, ALSA, JACK, PortAudio, openFrameworks and JUCE -midi : add built-in RtMidi support to the API -osc : add built-in OSC support to the API -soundfile : add built-in Soundfile support to the API JACK specific options -build : build a ready to test binary -dynamic : add libfaust/LLVM dynamic DSP compilation mode","title":"faust2api"},{"location":"manual/tools/#faust2bela","text":"Usage: faust2bela [options] [Faust options] <file.dsp> Target platform: Bela Compiles Faust programs to the BELA board Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Polyphonic mode means MIDI instrument with at least 1 voice. Use no arguments for a simple effect. -gui : activates a self-hosted GUI interface. Requires to have libmicrohttpd and libHTTPDFaust installed. -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI -tobela : to send C++ file into bela, and to run it Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2bela"},{"location":"manual/tools/#faust2bench","text":"Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2bench"},{"location":"manual/tools/#faust2caconsole","text":"Usage: faust2caconsole [options] [Faust options] <file.dsp> Target platform: MacOS Compiles Faust programs to CLI and CoreAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2caconsole"},{"location":"manual/tools/#faust2cagtk","text":"Usage: faust2cagtk [options] [Faust options] <file.dsp> Target platform: MacOS Require: GTK Compiles Faust programs to CoreAudio and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2cagtk"},{"location":"manual/tools/#faust2caqt","text":"Usage: faust2caqt [options] [Faust options] <file.dsp> Target platform: MacOS Require: QT Compiles Faust programs to CoreAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -opt native' to activate the best compilation options for the native CPU : -opt generic' to activate the best compilation options for a generic CPU : -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -resample : to resample soundfiles to the audio driver sample rate -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -me : to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow) -debug : to print all the build steps -nodeploy : skip self-contained application generation (using 'macdeployqt') -I include-path : add an include-directory to the generated Qt project for finding ffunction headers and such Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2caqt"},{"location":"manual/tools/#faust2cmajor","text":"Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/cmajor) Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -test : to test the resulting patch with 'cmaj render' -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2cmajor"},{"location":"manual/tools/#faust2comparator","text":"Usage: faust2comparator [options] [Faust options] <file.dsp>","title":"faust2comparator"},{"location":"manual/tools/#faust2csound","text":"Usage: faust2csound [options] [Faust options] <file.dsp> Target platform: any Require: CSound Dev Kit Compiles a Faust program into a Csound opcode Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2csound"},{"location":"manual/tools/#faust2csvplot","text":"Usage: faust2csvplot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 5 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) -bs <buffer> : change the buffer size (default is 512 frames) Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. -double : generates code with samples of type 'double'. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2csvplot"},{"location":"manual/tools/#faust2daisy","text":"faust2daisy [-patch] [-midi] [-nvoices <num>] [-sr <num>] [-bs <num>] [-source] [Faust options (-vec -vs 8...)] <file.dsp> Compiles Faust programs to Daisy boards (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/daisy) Options: -patch : to compile for 4 ins/outs Patch (knob[1,2,3,4]) -pod : to compile for 2 ins/outs Pod (knob[1,3]) -patchsm : to compile for the Pod.init eurorack module -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -sr <num> : to specify sample rate -bs <num> : to specify buffer size -source : to only create the source folder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2daisy"},{"location":"manual/tools/#faust2dplug","text":"Usage: faust2dplug [options] [Faust options] <file.dsp> Require: Dplug Compiles Faust programs to Dplug plugins Options: -vendor <My Company Name> : -vendorid <FaUs> : -pluginid <PlUg> : -homepage <https://faust.grame.fr/> : -effectType <effectDynamics> : Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2dplug"},{"location":"manual/tools/#faust2dssi","text":"Usage: faust2dssi [options] [Faust options] <file.dsp> Compiles Faust programs to dssi plugins Options: -osc : activates OSC control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2dssi"},{"location":"manual/tools/#faust2esp32","text":"Usage: faust2esp32 [options] [Faust options] <file.dsp> <file.dsp> faust2esp32 can be used to fully program the ESP32 microncontroller and to generate DSP objects that can be integrated into any ESP32 project (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/esp32) Options: -gramophone : generates for GRAME Gramophone -multi : generate for GRAME Gramophone in multi DSP mode -lib : generates a package containing an object compatible with any ESP32 project -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -main : add a 'main' entry point -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -wm8978, -es8388 or -ac101 : to choose codec driver Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2esp32"},{"location":"manual/tools/#faust2faustvst","text":"Usage: faust2faustvst [options ...] <file.dsp> Require: VST SDK Compiles Faust programs to VST plugins Options: -gui : build the plugin GUI. -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui). -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include FAUSTARCH: specify the location of the Faust VST library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake SDK: specify the location of the VST SDK Default: /usr/local/src/vstsdk SDKSRC: specify the location of the VST SDK sources Default: /usr/local/src/vstsdk/public.sdk/source/vst2.x","title":"faust2faustvst"},{"location":"manual/tools/#faust2feh","text":"Usage: faust2feh <file.dsp> Compiles Faust programs to SVG and opens them with feh","title":"faust2feh"},{"location":"manual/tools/#faust2gen","text":"Usage: faust2gen [options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to a fausgen~ patch Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events","title":"faust2gen"},{"location":"manual/tools/#faust2ios","text":"Usage: faust2ios [options] [Faust options] <file.dsp> Target platform: iOS Compiles Faust programs to iOS applications Options: -midi : activates MIDI control -osc : activates OSC control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -xcode : to compile and keep the intermediate Xcode project -xcodeproj : to produce the intermediate Xcode project -archive : to generate the archive for Apple Store -32bits : to compile 32 bits only binary -noagc : to deactivate audio automatic gain control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2ios"},{"location":"manual/tools/#faust2jack","text":"Usage: faust2jack [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack Compiles Faust programs to JACK and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jack"},{"location":"manual/tools/#faust2jackconsole","text":"Usage: faust2jackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to CLI and JACK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackconsole"},{"location":"manual/tools/#faust2jackrust","text":"Usage: faust2jackrust [-source] [Faust options] <file.dsp> Compiles Faust programs to JACK and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackrust"},{"location":"manual/tools/#faust2jackserver","text":"Usage: faust2jackserver [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT (server mode) Options: -httpd : activates HTTP control -osc : activates OSC control -qrcode : activates QR code generation Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackserver"},{"location":"manual/tools/#faust2jaqt","text":"Usage: faust2jaqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -resample : to resample soundfiles to the audio driver sample rate. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jaqt"},{"location":"manual/tools/#faust2jaqtchain","text":"Usage: faust2jaqtchain [options] [Faust options] <file.dsp> Require: Jack, QT Compiles several Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jaqtchain"},{"location":"manual/tools/#faust2juce","text":"Usage: faust2juce [options] [Faust options] <file.dsp> Require: Juce Compiles Faust programs to JUCE standalones or plugins (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/juce) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -standalone : to produce a standalone project, otherwise a plugin project is generated -vst2sdkdir <folder> : to set directory to VST 2 SDK. -jucemodulesdir <folder> : to set JUCE modules directory to <folder>, such as ~/JUCE/modules -disable-splash-screen : to disable the JUCE splash screen (license is required). -jsynth : to use JUCE polyphonic Synthesizer instead of Faust polyphonic code -llvm : to use the LLVM compilation chain (OSX and Linux for now) -magic : to generate a project using the PluginGuiMagic GUI builder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2juce"},{"location":"manual/tools/#faust2ladspa","text":"Usage: faust2ladspa [options] [Faust options] <file.dsp> Target platform: Linux Compiles Faust programs to LADSPA plugins Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2ladspa"},{"location":"manual/tools/#faust2linuxunity","text":"Usage: faust2linuxunity [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack, Unity Compiles Faust programs to Linux x86_64 libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2linuxunity"},{"location":"manual/tools/#faust2lv2","text":"-std=c++11 -fvisibility=hidden -O3 Usage: faust2lv2 [options ...] <file.dsp> Require: QT Compiles Faust programs to lv2 plugins Options: -dyn-manifest : use dynamic manifests (requires LV2 host support). -gui : build the plugin GUI (requires LV2 UI host support). -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -osx : -osx to compile on OSX -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui) -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include/faust FAUSTLIB: specify the location of the Faust LV2 library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake","title":"faust2lv2"},{"location":"manual/tools/#faust2mathdoc","text":"Usage: faust2mathdoc [options] <file.dsp> Require: svg2pdf pdflatex breqn Generate a full Faust documentation in a '*-mdoc' top directory Options: -l LANG : LANG is usually a 2-lowercase-letters language name, like en, fr, or it. -utf8 : force file.dsp to be recoded in UTF-8 before being processed","title":"faust2mathdoc"},{"location":"manual/tools/#faust2max6","text":"Usage: faust2max6 [options] [Faust options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to Max6 externals using double precision samples (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/max-msp) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -soundfile-dynamic : similar to -soundfile, but using the installed libsndfile (so possibly using dynamic link). -opt native|generic : activates the best compilation options for the native or generic CPU. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -us <factor> : upsample the DSP by a factor -ds <factor> : downsample the DSP by a factor -filter <filter> : use a filter for upsampling or downsampling [0..4] -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -mc : to activate multi-channels model -native : to compile for the native CPU (otherwise the 'generic' mode is used by default) -universal : to generate a universal (arm/intel) external -nopatch : to deactivate patch generation -nopost : to disable Faust messages to Max console Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2max6"},{"location":"manual/tools/#faust2minimal","text":"Usage: faust2minimal [options] [Faust options] <file.dsp> Compiles Faust programs to a minimal executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2minimal"},{"location":"manual/tools/#faust2netjackconsole","text":"Usage: faust2netjackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to NetJack Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2netjackconsole"},{"location":"manual/tools/#faust2netjackqt","text":"Usage: faust2netjackqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to NetJack and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2netjackqt"},{"location":"manual/tools/#faust2nodejs","text":"Usage: faust2nodejs [driver] [Faust options] <file.dsp> Generate Faust-based nodejs native addons. The generated addons can embed most of the audio engines supported by Faust: ALSA, JACK, CoreAudio, RtAudio, PortAudio, etc. Since faust2nodejs essentially acts as a wrapper to faust2api, it offers the same features than this system (MIDI and OSC support, polyphony, separate effect file, etc.). The following drivers are available: -coreaudio // -alsa // -jack // -portaudio // -rtaudio // -dummy. For example, to create a native nodejs addon with a JACK audio engine, run: faust2nodjs -jack faustFile.dsp The following options are inherited directly from faust2api and can be used with faust2nodejs: Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -source : generates the source of the addon without compiling it -electronv <VERSION> : allows to specify the current version of electron if generating an addon for this framework -debug : prints compilation output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2nodejs"},{"location":"manual/tools/#faust2osxiosunity","text":"Usage: faust2osxiosunity [options] [Faust options] <file.dsp> Target platform: MacOSX Require: Unity Compiles Faust programs to OSX/iOS libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -ios : create an iOS static library -universal : generate a 64/32 bits external Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info.","title":"faust2osxiosunity"},{"location":"manual/tools/#faust2paconsole","text":"Usage: faust2paconsole [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2paconsole"},{"location":"manual/tools/#faust2paqt","text":"Usage: faust2paqt [options] [Faust options] <file.dsp> Require: PortAudio, QT Compiles Faust programs to PortAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2paqt"},{"location":"manual/tools/#faust2plot","text":"Usage: faust2plot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 4 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2plot"},{"location":"manual/tools/#faust2portaudiojulia","text":"Usage: faust2portaudiojulia [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Julia binary -osc : to activate OSC control on 5000 and 5001 ports -play <num> : to start the 'Julia' runtime with <num> threads and the generated file.jl Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2portaudiojulia"},{"location":"manual/tools/#faust2portaudiorust","text":"Usage: faust2portaudiorust [-source] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2portaudiorust"},{"location":"manual/tools/#faust2raqt","text":"Usage: faust2raqt [options] [Faust options] <file.dsp> Require: QT Compiles Faust programs to RtAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2raqt"},{"location":"manual/tools/#faust2rnbo","text":"Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rnbo"},{"location":"manual/tools/#faust2rpialsaconsole","text":"Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: Alsa Compiles Faust programs to RaspberryPi - alsa console architecture Options: -osc : activates OSC control -httpd : activates HTTP control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rpialsaconsole"},{"location":"manual/tools/#faust2rpinetjackconsole","text":"Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: NetJack Compiles Faust programs to RaspberryPi - netjack-console architecture Options: -osc : activates OSC control -httpd : activates HTTP control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rpinetjackconsole"},{"location":"manual/tools/#faust2sam","text":"Usage: faust2sam [options] [Faust options] <file.dsp> Target platform: ADI SHARC Audio Module board Generates inline Faust objects for the ADI SHARC Audio Module board Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2sam"},{"location":"manual/tools/#faust2smartkeyb","text":"FAUST2SMARTKEYB - MUSICAL MOBILE APP GENERATOR faust2smartkeyb takes a Faust code as its main argument and convert it into a ready-to-use app for Android or iOS. The only two required arguments of faust2smartkeyb are a Faust file and the target platform (-android or -ios): Usage: faust2smartkeyb [options] [Faust options] <file.dsp> Target platform: iOS, Android Options: -android : generates an Android app -ios : generates an iOS app -osc : activates OSC control -debug : activate debug mode -effect : allow to specify an effect Faust file (e.g., -effect myEffect.dsp) -install : install the app on the connected device (Android only) -nvoices : specify the max number of voices -reuse : reuse the same project source -source : only generate the source (no compilation) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. More information and tutorials at: https://ccrma.stanford.edu/~rmichon/smartKeyboard","title":"faust2smartkeyb"},{"location":"manual/tools/#faust2sndfile","text":"Usage: faust2sndfile [Faust options] <file.dsp> Require: libsndfile Process audio files with Faust DSP Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2sndfile"},{"location":"manual/tools/#faust2stratus","text":"Usage: faust2stratus [options] [Faust options] <file.dsp> ... [<file.cpp> ...] Target platform: Chaos Audio Stratus pedal Compiles Faust programs for the Chaos Audio Stratus pedal with optional c++ compile for, and effect install to, the pedal Unlike most other faust2xxx scripts, this can also be used to compile effect c++ code that has been constructed elsewhere, or has been modified after being generated by the Faust compiler (e.g. where the algorithm c++ code has been 'tweaked' after generation) The script can be used to build and install multiple different effects in one go Running this script with no options except input files will result in effect libraries built for the platform upon which the script is executed, not for the pedal Options: -nocppc : Do not compile the generated c++ source files -nodocker : Do not use docker for pedal builds even if it is available -stratusbuild : Generates the c++ code locally, then builds the effect library for the Stratus pedal -stratusinstall : Generates the c++ code locally, then builds and installs the effect library for the Stratus pedal Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. the script automatically uses '-i -scn FaustDSP -light -nvi' -O and/or -o can be used, otherwise all output is in the same folder as the corresponding input","title":"faust2stratus"},{"location":"manual/tools/#faust2teensy","text":"faust2teensy [-lib] [-midi] [-nvoices <num>] [Faust options (-vec -vs 8...)] <file.dsp> Options: -lib : generates a package containing an object compatible with the Teensy audio library (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/teensy) -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2teensy"},{"location":"manual/tools/#faust2unity","text":"Usage: faust2unity [options] [Faust options] <file.dsp> Target platform: Android, Linux, MacOSX, iOS, Windows Require: Unity Generates a unity package (compressed .unitypackage folder) with all available architecture libraries for faust unity plugin and the C# files required. Use arguments to generate specific architectures (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/unity) Options: -w32 : generates a Windows 32 bits library -w64 : generates a Windows 64 bits library -osx : generates a macOS library -ios : generates an iOS library -android : generates Android libraries (armeabi-v7a and x86). -linux : generates a Linux library -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -source : generates the source files (uncompressed folder) -unpacked : generates an unpacked folder with files organized like the Unity Asset hierarchy. Use this options to add specific files in the unity package (in the Assets folder, then use 'encoderunitypackage <folder>' to compress and pack it. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info.","title":"faust2unity"},{"location":"manual/tools/#faust2vcvrack","text":"faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [Faust options] <file.dsp> Compiles Faust programs to VCV Rack modules (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/vcvrack) -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -source : to only create the source folder -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -version <1|2> : to set the plugin version, 2 by default Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2vcvrack"},{"location":"qreference/1-introduction/","text":"Introduction Faust ( Functional Audio Stream ) is a functional programming language specifically designed for real-time signal processing and synthesis. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. Design Principles Various principles have guided the design of Faust : Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled, not interpreted. The compiler translates Faust programs into equivalent C++ programs taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations ( : , ~ <: :> ). Thanks to the notion of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plugin formats without any change to the Faust code. Signal Processor Semantic A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . Faust considers two type of signals: **integer signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Z}\\)) and **floating point signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Q}\\)) Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0. The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produce an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"1 introduction"},{"location":"qreference/1-introduction/#introduction","text":"Faust ( Functional Audio Stream ) is a functional programming language specifically designed for real-time signal processing and synthesis. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards.","title":"Introduction"},{"location":"qreference/1-introduction/#design-principles","text":"Various principles have guided the design of Faust : Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled, not interpreted. The compiler translates Faust programs into equivalent C++ programs taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations ( : , ~ <: :> ). Thanks to the notion of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plugin formats without any change to the Faust code.","title":"Design Principles"},{"location":"qreference/1-introduction/#signal-processor-semantic","text":"A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . Faust considers two type of signals: **integer signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Z}\\)) and **floating point signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Q}\\)) Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0. The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produce an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Signal Processor Semantic"},{"location":"qreference/10-poly/","text":"Polyphonic support Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described\\footnote{Like sympathetic strings resonance in a physical model of a piano for instance.}. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special {\\it polyphonic instrument aware} architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping. Polyphonic ready DSP code By convention Faust architecture files with polyphonic capabilities expect to find control parameters named {\\it freq}, {\\it gain} and {\\it gate}. The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the {\\it freq} parameter (which should be a frequency) will be automatically computed from MIDI note numbers, {\\it gain} (which should be a value between 0 and 1) from velocity and {\\it gate} from {\\it keyon/keyoff} events. Thus, gate can be used as a trigger signal for any envelope generator, etc. Using the mydsp_poly class The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the {\\it faust/dsp/poly-dsp.h} file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp type of objects, manage dynamic voice allocations, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold. as a sub-class of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global {\\it Polyphonic} tabgroup. The first tab contains a {\\it Voices} group, a master like component used to change parameters on all voices at the same time, with a {\\it Panic} button to be used to stop running voices\\footnote{An internal control grouping mechanism has been defined to automatically dispatch a user interface action done on the master component on all linked voices, except for the {\\it freq}, {\\it gain} and {\\it gate} controls.}, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP (Figure fig:poly-ui ). Extended multi-voices GUI interface The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI, httpdUI, etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /0x00/0x00/vol f -10.0 /0x00/0x00/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/0x00/0x00/pan f 0.0 /Polyphonic/Voices/0x00/0x00/vol f -10.0 ... /Polyphonic/Voice1/0x00/0x00/vol f -10.0 /Polyphonic/Voice1/0x00/0x00/pan f 0.0 ... /Polyphonic/Voice2/0x00/0x00/vol f -10.0 /Polyphonic/Voice2/0x00/0x00/pan f 0.0 ... The polyphonic instrument allocation takes the DSP to be used for one voice\\footnote{The DSP object will be automatically cloned in the mydsp_poly class to create all needed voices.}, the desired number of voices, the {\\it dynamic voice allocation} state\\footnote{Voices may be always running, or dynamically started/stopped in case of MIDI control.}, and the {\\it group} state which controls if separated voices are displayed or not (Figure fig:poly-ui ): DSP = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: DSP = new mydsp_poly(dsp, 8, false, true); Controlling the polyphonic instrument The mydsp_poly class is also ready for MIDI control and can react to {\\it keyon/keyoff} and {\\it pitchwheel} messages. Other MIDI control parameters can directly be added in the DSP source code. Deploying the polyphonic instrument Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter\\footnote{-nvoices parameter takes precedence over the metadata value.}. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. Polyphonic instrument with a global output effect Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is not a good idea since it would be instantiated for each voice which would be very inefficient. This is a typical use case for the dsp_sequencer class previously presented with the polyphonic DSP connected in sequence with a unique global effect (Figure fig:poly-ui-effect ). faustcaqt inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. A dsp_sequencer object will be created to combine the polyphonic instrument in sequence with the single output effect. Polyphonic ready {\\it faust2xx} scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready to use DSP. Polyphonic instrument with output effect GUI interface: left tab window shows the polyphonic instrument with its Integrated global output effect Starting with the 2.5.17 version, a new convention has been defined to directly integrate a global output effect inside the DSP source code itself. The effect has simply to be declared in a effect = effect_code; line in the source. Here is a more complete source code example: import(\"stdfaust.lib\"); process = pm.clarinet_ui_MIDI <: _,_; effect = dm.freeverb_demo; The architecture script then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them with the dsp_sequencer object. A new auto parameter to be used in {\\it faust2xx} script has been defined, as in the faustcaqt inst.dsp -effect auto line for example. Integrated global output effect and libfaust For developers using the libfaust library, an helper file named faust/dsp/poly-dsp-tools.h is available. It defines an API to automatically create a polyphonic instrument with an output effect, starting from a DSP source file using the effect effect = ... convention. The function createPolyDSPFactoryFromString or \\ createPolyDSPFactoryFromFile must be used to create the polyphonic DSP factory. Next, the createPolyDSPInstance function creates the polyphonic object (a subclass of dsp_poly type) to be used like a regular dsp type object. After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writePolyDSPFactoryToIRFile allows to save the polyphonic factory LLVM IR (in textual format) in a file, writePolyDSPFactoryToBitcodeFile allows to save the polyphonic factory LLVM IR (in binary format) in a file, writePolyDSPFactoryToMachineFile allows to save the polyphonic factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readPolyDSPFactoryFromIRFile allows to create a polyphonic DSP factory from a file containing the LLVM IR (in textual format), readPolyDSPFactoryFromBitcodeFile allows to create a polyphonic factory from a file containing the LLVM IR (in binary format), readPolyDSPFactoryFromMachineFile allows to create a polyphonic DSP factory from a file containing the executable machine code.","title":"10 poly"},{"location":"qreference/10-poly/#polyphonic-support","text":"Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described\\footnote{Like sympathetic strings resonance in a physical model of a piano for instance.}. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special {\\it polyphonic instrument aware} architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping.","title":"Polyphonic support"},{"location":"qreference/10-poly/#polyphonic-ready-dsp-code","text":"By convention Faust architecture files with polyphonic capabilities expect to find control parameters named {\\it freq}, {\\it gain} and {\\it gate}. The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the {\\it freq} parameter (which should be a frequency) will be automatically computed from MIDI note numbers, {\\it gain} (which should be a value between 0 and 1) from velocity and {\\it gate} from {\\it keyon/keyoff} events. Thus, gate can be used as a trigger signal for any envelope generator, etc.","title":"Polyphonic ready DSP code"},{"location":"qreference/10-poly/#using-the-mydsp_poly-class","text":"The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the {\\it faust/dsp/poly-dsp.h} file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp type of objects, manage dynamic voice allocations, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold. as a sub-class of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global {\\it Polyphonic} tabgroup. The first tab contains a {\\it Voices} group, a master like component used to change parameters on all voices at the same time, with a {\\it Panic} button to be used to stop running voices\\footnote{An internal control grouping mechanism has been defined to automatically dispatch a user interface action done on the master component on all linked voices, except for the {\\it freq}, {\\it gain} and {\\it gate} controls.}, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP (Figure fig:poly-ui ). Extended multi-voices GUI interface The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI, httpdUI, etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /0x00/0x00/vol f -10.0 /0x00/0x00/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/0x00/0x00/pan f 0.0 /Polyphonic/Voices/0x00/0x00/vol f -10.0 ... /Polyphonic/Voice1/0x00/0x00/vol f -10.0 /Polyphonic/Voice1/0x00/0x00/pan f 0.0 ... /Polyphonic/Voice2/0x00/0x00/vol f -10.0 /Polyphonic/Voice2/0x00/0x00/pan f 0.0 ... The polyphonic instrument allocation takes the DSP to be used for one voice\\footnote{The DSP object will be automatically cloned in the mydsp_poly class to create all needed voices.}, the desired number of voices, the {\\it dynamic voice allocation} state\\footnote{Voices may be always running, or dynamically started/stopped in case of MIDI control.}, and the {\\it group} state which controls if separated voices are displayed or not (Figure fig:poly-ui ): DSP = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: DSP = new mydsp_poly(dsp, 8, false, true);","title":"Using the mydsp_poly class"},{"location":"qreference/10-poly/#controlling-the-polyphonic-instrument","text":"The mydsp_poly class is also ready for MIDI control and can react to {\\it keyon/keyoff} and {\\it pitchwheel} messages. Other MIDI control parameters can directly be added in the DSP source code.","title":"Controlling the polyphonic instrument"},{"location":"qreference/10-poly/#deploying-the-polyphonic-instrument","text":"Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter\\footnote{-nvoices parameter takes precedence over the metadata value.}. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions.","title":"Deploying the polyphonic instrument"},{"location":"qreference/10-poly/#polyphonic-instrument-with-a-global-output-effect","text":"Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is not a good idea since it would be instantiated for each voice which would be very inefficient. This is a typical use case for the dsp_sequencer class previously presented with the polyphonic DSP connected in sequence with a unique global effect (Figure fig:poly-ui-effect ). faustcaqt inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. A dsp_sequencer object will be created to combine the polyphonic instrument in sequence with the single output effect. Polyphonic ready {\\it faust2xx} scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready to use DSP. Polyphonic instrument with output effect GUI interface: left tab window shows the polyphonic instrument with its","title":"Polyphonic instrument with a global output effect"},{"location":"qreference/10-poly/#integrated-global-output-effect","text":"Starting with the 2.5.17 version, a new convention has been defined to directly integrate a global output effect inside the DSP source code itself. The effect has simply to be declared in a effect = effect_code; line in the source. Here is a more complete source code example: import(\"stdfaust.lib\"); process = pm.clarinet_ui_MIDI <: _,_; effect = dm.freeverb_demo; The architecture script then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them with the dsp_sequencer object. A new auto parameter to be used in {\\it faust2xx} script has been defined, as in the faustcaqt inst.dsp -effect auto line for example.","title":"Integrated global output effect"},{"location":"qreference/10-poly/#integrated-global-output-effect-and-libfaust","text":"For developers using the libfaust library, an helper file named faust/dsp/poly-dsp-tools.h is available. It defines an API to automatically create a polyphonic instrument with an output effect, starting from a DSP source file using the effect effect = ... convention. The function createPolyDSPFactoryFromString or \\ createPolyDSPFactoryFromFile must be used to create the polyphonic DSP factory. Next, the createPolyDSPInstance function creates the polyphonic object (a subclass of dsp_poly type) to be used like a regular dsp type object. After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writePolyDSPFactoryToIRFile allows to save the polyphonic factory LLVM IR (in textual format) in a file, writePolyDSPFactoryToBitcodeFile allows to save the polyphonic factory LLVM IR (in binary format) in a file, writePolyDSPFactoryToMachineFile allows to save the polyphonic factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readPolyDSPFactoryFromIRFile allows to create a polyphonic DSP factory from a file containing the LLVM IR (in textual format), readPolyDSPFactoryFromBitcodeFile allows to create a polyphonic factory from a file containing the LLVM IR (in binary format), readPolyDSPFactoryFromMachineFile allows to create a polyphonic DSP factory from a file containing the executable machine code.","title":"Integrated global output effect and libfaust"},{"location":"qreference/11-codegeneration/","text":"Controlling the code generation Several options of the Faust compiler allow to control the generated C++ code. By default the computations are done sample by sample in a single loop. But the compiler can also generate vector and parallel code. Vector code generation Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 simple precision floating point numbers thus leading to a theoretical speedup of \\times4 . Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular too complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: // Root Mean Square of n consecutive samples RMS(n) = square : mean(n) : sqrt; // Square of a signal square(x) = x * x; // Mean of n consecutive samples of a signal // (uses fixpoint to avoid the accumulation of // rounding errors) mean(n) = float2fix : integrate(n) : fix2float : /(n); // Sliding sum of n consecutive samples integrate(n,x) = x - x@n : +~_; // Convertion between float and fix point float2fix(x) = int(x*(1<<20)); fix2float(x) = float(x)/(1<<20); // Root Mean Square of 1000 consecutive samples process = RMS(1000); The compute() method generated in scalar mode is the following: virtual void compute (int count, float** input, float** output) { float* input0 = input[0]; float* output0 = output[0]; for (int i=0; i<count; i++) { float fTemp0 = input0[i]; int iTemp1 = int(1048576*fTemp0*fTemp0); iVec0[IOTA&1023] = iTemp1; iRec0[0] = ((iVec0[IOTA&1023] + iRec0[1]) - iVec0[(IOTA-1000)&1023]); output0[i] = sqrtf(9.536744e-10f * float(iRec0[0])); // post processing iRec0[1] = iRec0[0]; IOTA = IOTA+1; } The -vec option leads to the following reorganization of the code: virtual void compute (int fullcount, float** input, float** output) { int iRec0_tmp[32+4]; int* iRec0 = &iRec0_tmp[4]; for (int index=0; index<fullcount; index+=32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* output0 = &output[0][index]; for (int i=0; i<4; i++) iRec0_tmp[i]=iRec0_perm[i]; // SECTION : 1 for (int i=0; i<count; i++) { iYec0[(iYec0_idx+i)&2047] = int(1048576*input0[i]*input0[i]); } // SECTION : 2 for (int i=0; i<count; i++) { iRec0[i] = ((iYec0[i] + iRec0[i-1]) - iYec0[(iYec0_idx+i-1000)&2047]); } // SECTION : 3 for (int i=0; i<count; i++) { output0[i] = sqrtf((9.536744e-10f * float(iRec0[i]))); } // SECTION : 4 iYec0_idx = (iYec0_idx+count)&2047; for (int i=0; i<4; i++) iRec0_perm[i]=iRec0_tmp[count+i]; } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. Using Intel icc 11.0, with the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2, the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! Faust 's stack of code generators The vector code generation is built on top of the scalar code generation (see figure fig:stack ). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. It applies some simple rules for that. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see Figure fig:loopgraph ). This graph is stored in the klass object and a topological sort is applied to it before printing the code. The result of the -vec option is a directed acyclic graph (DAG) of small computation loops Parallel code generation The parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option. It implies the -vec options as the parallel code generation is built on top of the vector code generation. The OpenMP code generator OpenMP is based on a fork-join model The --openMP (or -omp ) option given to the Faust compiler will insert appropriate OpenMP directives in the C++ code. OpenMP (http://wwww.openmp.org) is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure fig:openmp ). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region a team of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel team until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by // every thread of the parallel team ... In order not to have every thread doing redundantly the exact same work, OpemMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... Adding OpenMP directives As said before the parallel code generation is built on top of the vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 in the DAG of Figure fig:loopgraph ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code } Example of parallel OpenMP code To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; two filters in parallel connected to an adder The corresponding compute() method obtained using the -omp option is the following: virtual void compute (int fullcount, float** input, float** output) { float fRec0_tmp[32+4]; float fRec1_tmp[32+4]; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; #pragma omp parallel firstprivate(fRec0,fRec1) { for (int index = 0; index < fullcount; index += 32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* input1 = &input[1][index]; float* output0 = &output[0][index]; #pragma omp single { for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; } // SECTION : 1 #pragma omp sections { #pragma omp section for (int i=0; i<count; i++) { fRec0[i] = ((0.1f * input1[i]) + (0.9f * fRec0[i-1])); } #pragma omp section for (int i=0; i<count; i++) { fRec1[i] = ((0.1f * input0[i]) + (0.9f * fRec1[i-1])); } } // SECTION : 2 #pragma omp for for (int i=0; i<count; i++) { output0[i] = (fRec1[i] + fRec0[i]); } // SECTION : 3 #pragma omp single { for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; } } } This code requires some comments: The parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. Variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1. The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. The top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between the threads. Please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. The work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). The work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. The loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. Finally #pragma omp single in section 3 indicates that this last section will be executed by only one thread (any of them). The scheduler code generator With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separated computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large subtree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers (only quite recent versions like GCC 4.4 start to show some improvements), and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future. Example of parallel scheduler code To illustrate how Faust generates the scheduler code, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute (int fullcount, float** input, float** output) { GetRealTime(); this->input = input; this->output = output; StartMeasure(); for (fIndex = 0; fIndex < fullcount; fIndex += 32) { fFullCount = min (32, fullcount-fIndex); TaskQueue::Init(); // Initialize end task fGraph.InitTask(1,1); // Only initialize tasks with inputs fGraph.InitTask(4,2); fIsFinished = false; fThreadPool.SignalAll(fDynamicNumThreads - 1); computeThread(0); while (!fThreadPool.IsFinished()) {} } StopMeasure(fStaticNumThreads, fDynamicNumThreads); void computeThread (int cur_thread) { float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; // Init graph state { TaskQueue taskqueue; int tasknum = -1; int count = fFullCount; // Init input and output FAUSTFLOAT* input0 = &input[0][fIndex]; FAUSTFLOAT* input1 = &input[1][fIndex]; FAUSTFLOAT* output0 = &output[0][fIndex]; int task_list_size = 2; int task_list[2] = {2,3}; taskqueue.InitTaskList(task_list_size, task_list, fDynamicNumThreads, cur_thread, tasknum); while (!fIsFinished) { switch (tasknum) { case WORK_STEALING_INDEX: { tasknum = TaskQueue::GetNextTask(cur_thread); break; } case LAST_TASK_INDEX: { fIsFinished = true; break; } // SECTION : 1 case 2: { // LOOP 0x101111680 // pre processing for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; // exec code for (int i=0; i<count; i++) { fRec0[i] = ((1.000000e-01f * (float)input1[i]) + (0.9f * fRec0[i-1])); } // post processing for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 3: { // LOOP 0x1011125e0 // pre processing for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; // exec code for (int i=0; i<count; i++) { fRec1[i] = ((1.000000e-01f * (float)input0[i]) + (0.9f * fRec1[i-1])); } // post processing for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 4: { // LOOP 0x101111580 // exec code for (int i=0; i<count; i++) { output0[i] = (FAUSTFLOAT)(fRec1[i] + fRec0[i]); } tasknum = LAST_TASK_INDEX; break; } } } }","title":"11 codegeneration"},{"location":"qreference/11-codegeneration/#controlling-the-code-generation","text":"Several options of the Faust compiler allow to control the generated C++ code. By default the computations are done sample by sample in a single loop. But the compiler can also generate vector and parallel code.","title":"Controlling the code generation"},{"location":"qreference/11-codegeneration/#vector-code-generation","text":"Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 simple precision floating point numbers thus leading to a theoretical speedup of \\times4 . Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular too complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: // Root Mean Square of n consecutive samples RMS(n) = square : mean(n) : sqrt; // Square of a signal square(x) = x * x; // Mean of n consecutive samples of a signal // (uses fixpoint to avoid the accumulation of // rounding errors) mean(n) = float2fix : integrate(n) : fix2float : /(n); // Sliding sum of n consecutive samples integrate(n,x) = x - x@n : +~_; // Convertion between float and fix point float2fix(x) = int(x*(1<<20)); fix2float(x) = float(x)/(1<<20); // Root Mean Square of 1000 consecutive samples process = RMS(1000); The compute() method generated in scalar mode is the following: virtual void compute (int count, float** input, float** output) { float* input0 = input[0]; float* output0 = output[0]; for (int i=0; i<count; i++) { float fTemp0 = input0[i]; int iTemp1 = int(1048576*fTemp0*fTemp0); iVec0[IOTA&1023] = iTemp1; iRec0[0] = ((iVec0[IOTA&1023] + iRec0[1]) - iVec0[(IOTA-1000)&1023]); output0[i] = sqrtf(9.536744e-10f * float(iRec0[0])); // post processing iRec0[1] = iRec0[0]; IOTA = IOTA+1; } The -vec option leads to the following reorganization of the code: virtual void compute (int fullcount, float** input, float** output) { int iRec0_tmp[32+4]; int* iRec0 = &iRec0_tmp[4]; for (int index=0; index<fullcount; index+=32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* output0 = &output[0][index]; for (int i=0; i<4; i++) iRec0_tmp[i]=iRec0_perm[i]; // SECTION : 1 for (int i=0; i<count; i++) { iYec0[(iYec0_idx+i)&2047] = int(1048576*input0[i]*input0[i]); } // SECTION : 2 for (int i=0; i<count; i++) { iRec0[i] = ((iYec0[i] + iRec0[i-1]) - iYec0[(iYec0_idx+i-1000)&2047]); } // SECTION : 3 for (int i=0; i<count; i++) { output0[i] = sqrtf((9.536744e-10f * float(iRec0[i]))); } // SECTION : 4 iYec0_idx = (iYec0_idx+count)&2047; for (int i=0; i<4; i++) iRec0_perm[i]=iRec0_tmp[count+i]; } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. Using Intel icc 11.0, with the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2, the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! Faust 's stack of code generators The vector code generation is built on top of the scalar code generation (see figure fig:stack ). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. It applies some simple rules for that. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see Figure fig:loopgraph ). This graph is stored in the klass object and a topological sort is applied to it before printing the code. The result of the -vec option is a directed acyclic graph (DAG) of small computation loops","title":"Vector code generation"},{"location":"qreference/11-codegeneration/#parallel-code-generation","text":"The parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option. It implies the -vec options as the parallel code generation is built on top of the vector code generation.","title":"Parallel code generation"},{"location":"qreference/11-codegeneration/#the-openmp-code-generator","text":"OpenMP is based on a fork-join model The --openMP (or -omp ) option given to the Faust compiler will insert appropriate OpenMP directives in the C++ code. OpenMP (http://wwww.openmp.org) is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure fig:openmp ). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region a team of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel team until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by // every thread of the parallel team ... In order not to have every thread doing redundantly the exact same work, OpemMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ...","title":"The OpenMP code generator"},{"location":"qreference/11-codegeneration/#adding-openmp-directives","text":"As said before the parallel code generation is built on top of the vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 in the DAG of Figure fig:loopgraph ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code }","title":"Adding OpenMP directives"},{"location":"qreference/11-codegeneration/#example-of-parallel-openmp-code","text":"To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; two filters in parallel connected to an adder The corresponding compute() method obtained using the -omp option is the following: virtual void compute (int fullcount, float** input, float** output) { float fRec0_tmp[32+4]; float fRec1_tmp[32+4]; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; #pragma omp parallel firstprivate(fRec0,fRec1) { for (int index = 0; index < fullcount; index += 32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* input1 = &input[1][index]; float* output0 = &output[0][index]; #pragma omp single { for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; } // SECTION : 1 #pragma omp sections { #pragma omp section for (int i=0; i<count; i++) { fRec0[i] = ((0.1f * input1[i]) + (0.9f * fRec0[i-1])); } #pragma omp section for (int i=0; i<count; i++) { fRec1[i] = ((0.1f * input0[i]) + (0.9f * fRec1[i-1])); } } // SECTION : 2 #pragma omp for for (int i=0; i<count; i++) { output0[i] = (fRec1[i] + fRec0[i]); } // SECTION : 3 #pragma omp single { for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; } } } This code requires some comments: The parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. Variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1. The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. The top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between the threads. Please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. The work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). The work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. The loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. Finally #pragma omp single in section 3 indicates that this last section will be executed by only one thread (any of them).","title":"Example of parallel OpenMP code"},{"location":"qreference/11-codegeneration/#the-scheduler-code-generator","text":"With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separated computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large subtree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers (only quite recent versions like GCC 4.4 start to show some improvements), and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future.","title":"The scheduler code generator"},{"location":"qreference/11-codegeneration/#example-of-parallel-scheduler-code","text":"To illustrate how Faust generates the scheduler code, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute (int fullcount, float** input, float** output) { GetRealTime(); this->input = input; this->output = output; StartMeasure(); for (fIndex = 0; fIndex < fullcount; fIndex += 32) { fFullCount = min (32, fullcount-fIndex); TaskQueue::Init(); // Initialize end task fGraph.InitTask(1,1); // Only initialize tasks with inputs fGraph.InitTask(4,2); fIsFinished = false; fThreadPool.SignalAll(fDynamicNumThreads - 1); computeThread(0); while (!fThreadPool.IsFinished()) {} } StopMeasure(fStaticNumThreads, fDynamicNumThreads); void computeThread (int cur_thread) { float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; // Init graph state { TaskQueue taskqueue; int tasknum = -1; int count = fFullCount; // Init input and output FAUSTFLOAT* input0 = &input[0][fIndex]; FAUSTFLOAT* input1 = &input[1][fIndex]; FAUSTFLOAT* output0 = &output[0][fIndex]; int task_list_size = 2; int task_list[2] = {2,3}; taskqueue.InitTaskList(task_list_size, task_list, fDynamicNumThreads, cur_thread, tasknum); while (!fIsFinished) { switch (tasknum) { case WORK_STEALING_INDEX: { tasknum = TaskQueue::GetNextTask(cur_thread); break; } case LAST_TASK_INDEX: { fIsFinished = true; break; } // SECTION : 1 case 2: { // LOOP 0x101111680 // pre processing for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; // exec code for (int i=0; i<count; i++) { fRec0[i] = ((1.000000e-01f * (float)input1[i]) + (0.9f * fRec0[i-1])); } // post processing for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 3: { // LOOP 0x1011125e0 // pre processing for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; // exec code for (int i=0; i<count; i++) { fRec1[i] = ((1.000000e-01f * (float)input0[i]) + (0.9f * fRec1[i-1])); } // post processing for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 4: { // LOOP 0x101111580 // exec code for (int i=0; i<count; i++) { output0[i] = (FAUSTFLOAT)(fRec1[i] + fRec0[i]); } tasknum = LAST_TASK_INDEX; break; } } } }","title":"Example of parallel scheduler code"},{"location":"qreference/12-mdoc/","text":"Mathematical Documentation The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long). Goals of the mathdoc There are for main goals, or uses, of this mathematical documentation: - to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler; - to preserve signal processors, independently from any computer language but only under a mathematical form; - to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage; - to give a new teaching support, as a bridge between code and formulas for signal processing. Installation requirements faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as LaTeX doesn't eat Svg directly yet... breqn , a LaTeX package to handle automatic breaking of long equations, pdflatex , to compile the LaTeX output file. Generating the mathdoc The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leave the documentation production unfinished. For example: faust2mathdoc noise.dsp Invoking the -mdoc option Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with \"-mdoc\", 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a LaTeX file containing the formulas, Svg files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so all needed libraries to have a self-contained DSP), svg/ contains Svg block-diagram files, tex/ contains the generated LaTeX file. Invoking faust2mathdoc The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all Svg files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the LaTeX file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ . Online examples To get an idea of the results of this mathematical documentation, which captures the mathematical semantic of Faust programs, you can look at two pdf files online: http://faust.grame.fr/pdf/karplus.pdf (automatic documentation), http://faust.grame.fr/pdf/noise.pdf (manual documentation). You can also generate all mdoc pdfs at once, simply invoking the make mathdoc command inside the examples/ directory: for each %.dsp file, a complete %-mdoc directory will be generated, a single allmathpdfs/ directory will gather all the generated pdf files. Automatic documentation By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a LaTeX file with four sections: - '' Equations of process '', gathering all formulas needed for process , - '' Block-diagram schema of process '', showing the top-level block-diagram of process , - '' Notice of this documentation '', summing up generation and conventions information, - '' Complete listing of the input code '', listing all needed input files (including libraries). Manual documentation You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That permits you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the LaTeX stuff becomes up to you! Six tags Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive'' notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to \"true\" by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections. The mdoc top-level tags The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs (see section \\ref{documentation}). In addition of the four inner tags, <mdoc></mdoc> tags accept free LaTeX text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the LaTeX packages included by Faust can be found in the file architecture/latexheader.tex . An example of manual mathdoc &lt;mdoc> \\title{&lt;metadata>name&lt;/metadata>} \\author{&lt;metadata>author&lt;/metadata>} \\date{\\today} \\maketitle | | | |------|------| | **name** | &lt;metadata>name&lt;/metadata> | | **version** | &lt;metadata>version&lt;/metadata> | | **author** | &lt;metadata>author&lt;/metadata> | | **license** | &lt;metadata>license&lt;/metadata> | | **copyright** | &lt;metadata>copyright&lt;/metadata> | &lt;/mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; &lt;mdoc> ## Presentation of the \"noise.dsp\" Faust program This program describes a white noise generator with an interactive volume, using a random function. ### The random function &lt;/mdoc> random = +(12345)~*(1103515245); &lt;mdoc> The random function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. &lt;equation>random&lt;/equation> ### The noise function &lt;/mdoc> noise = random/2147483647.0; &lt;mdoc> The white noise then corresponds to: &lt;equation>noise&lt;/equation> ### Just add a user interface element to play volume! &lt;/mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); &lt;mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: &lt;equation>process&lt;/equation> ## Block-diagram schema of process This process is illustrated on figure 1. &lt;diagram>process&lt;/diagram> ## Notice of this documentation You might be careful of certain information and naming conventions used in this documentation: &lt;notice /> ## Listing of the input code The following listing shows the input Faust code, parsed to compile this mathematical documentation. &lt;listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> &lt;/mdoc> The following page which gathers the four resulting pages of noise.pdf in small size. might give you an idea of the produced documentation. The -stripmdoc option As you can see on the resulting file noisemetadata.pdf on its pages 3 and 4, the listing of the input code (section\\,4) contains all the mathdoc text (here colored in grey). As it may be useless in certain cases (see Goals, section goals-of-mdoc ), we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long). Localization of mathdoc files By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian for the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. \\includepdf[pages=-, frame=true, angle=-90, scale=0.75, nup=1x2]{images/noisemetadata} Summary of the mathdoc generation steps First, to get the full mathematical documentation done on your faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"12 mdoc"},{"location":"qreference/12-mdoc/#mathematical-documentation","text":"The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long).","title":"Mathematical Documentation"},{"location":"qreference/12-mdoc/#goals-of-the-mathdoc","text":"There are for main goals, or uses, of this mathematical documentation: - to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler; - to preserve signal processors, independently from any computer language but only under a mathematical form; - to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage; - to give a new teaching support, as a bridge between code and formulas for signal processing.","title":"Goals of the mathdoc"},{"location":"qreference/12-mdoc/#installation-requirements","text":"faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as LaTeX doesn't eat Svg directly yet... breqn , a LaTeX package to handle automatic breaking of long equations, pdflatex , to compile the LaTeX output file.","title":"Installation requirements"},{"location":"qreference/12-mdoc/#generating-the-mathdoc","text":"The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leave the documentation production unfinished. For example: faust2mathdoc noise.dsp","title":"Generating the mathdoc"},{"location":"qreference/12-mdoc/#invoking-the-mdoc-option","text":"Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with \"-mdoc\", 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a LaTeX file containing the formulas, Svg files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so all needed libraries to have a self-contained DSP), svg/ contains Svg block-diagram files, tex/ contains the generated LaTeX file.","title":"Invoking the -mdoc option"},{"location":"qreference/12-mdoc/#invoking-faust2mathdoc","text":"The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all Svg files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the LaTeX file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ .","title":"Invoking faust2mathdoc"},{"location":"qreference/12-mdoc/#online-examples","text":"To get an idea of the results of this mathematical documentation, which captures the mathematical semantic of Faust programs, you can look at two pdf files online: http://faust.grame.fr/pdf/karplus.pdf (automatic documentation), http://faust.grame.fr/pdf/noise.pdf (manual documentation). You can also generate all mdoc pdfs at once, simply invoking the make mathdoc command inside the examples/ directory: for each %.dsp file, a complete %-mdoc directory will be generated, a single allmathpdfs/ directory will gather all the generated pdf files.","title":"Online examples"},{"location":"qreference/12-mdoc/#automatic-documentation","text":"By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a LaTeX file with four sections: - '' Equations of process '', gathering all formulas needed for process , - '' Block-diagram schema of process '', showing the top-level block-diagram of process , - '' Notice of this documentation '', summing up generation and conventions information, - '' Complete listing of the input code '', listing all needed input files (including libraries).","title":"Automatic documentation"},{"location":"qreference/12-mdoc/#manual-documentation","text":"You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That permits you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the LaTeX stuff becomes up to you!","title":"Manual documentation"},{"location":"qreference/12-mdoc/#six-tags","text":"Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive'' notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to \"true\" by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections.","title":"Six tags"},{"location":"qreference/12-mdoc/#the-mdoc-top-level-tags","text":"The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs (see section \\ref{documentation}). In addition of the four inner tags, <mdoc></mdoc> tags accept free LaTeX text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the LaTeX packages included by Faust can be found in the file architecture/latexheader.tex .","title":"The mdoc top-level tags"},{"location":"qreference/12-mdoc/#an-example-of-manual-mathdoc","text":"&lt;mdoc> \\title{&lt;metadata>name&lt;/metadata>} \\author{&lt;metadata>author&lt;/metadata>} \\date{\\today} \\maketitle | | | |------|------| | **name** | &lt;metadata>name&lt;/metadata> | | **version** | &lt;metadata>version&lt;/metadata> | | **author** | &lt;metadata>author&lt;/metadata> | | **license** | &lt;metadata>license&lt;/metadata> | | **copyright** | &lt;metadata>copyright&lt;/metadata> | &lt;/mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; &lt;mdoc> ## Presentation of the \"noise.dsp\" Faust program This program describes a white noise generator with an interactive volume, using a random function. ### The random function &lt;/mdoc> random = +(12345)~*(1103515245); &lt;mdoc> The random function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. &lt;equation>random&lt;/equation> ### The noise function &lt;/mdoc> noise = random/2147483647.0; &lt;mdoc> The white noise then corresponds to: &lt;equation>noise&lt;/equation> ### Just add a user interface element to play volume! &lt;/mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); &lt;mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: &lt;equation>process&lt;/equation> ## Block-diagram schema of process This process is illustrated on figure 1. &lt;diagram>process&lt;/diagram> ## Notice of this documentation You might be careful of certain information and naming conventions used in this documentation: &lt;notice /> ## Listing of the input code The following listing shows the input Faust code, parsed to compile this mathematical documentation. &lt;listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> &lt;/mdoc> The following page which gathers the four resulting pages of noise.pdf in small size. might give you an idea of the produced documentation.","title":"An example of manual mathdoc"},{"location":"qreference/12-mdoc/#the-stripmdoc-option","text":"As you can see on the resulting file noisemetadata.pdf on its pages 3 and 4, the listing of the input code (section\\,4) contains all the mathdoc text (here colored in grey). As it may be useless in certain cases (see Goals, section goals-of-mdoc ), we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long).","title":"The -stripmdoc option"},{"location":"qreference/12-mdoc/#localization-of-mathdoc-files","text":"By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian for the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. \\includepdf[pages=-, frame=true, angle=-90, scale=0.75, nup=1x2]{images/noisemetadata}","title":"Localization of mathdoc files"},{"location":"qreference/12-mdoc/#summary-of-the-mathdoc-generation-steps","text":"First, to get the full mathematical documentation done on your faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Summary of the mathdoc generation steps"},{"location":"qreference/13-acknowledgments/","text":"Acknowledgments Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen Karim Barkati J\\'er\\^ome Barth\\'elemy Tim Blechmann Tiziano Bole Alain Bonardi Thomas Charbonnel Raffaele Ciavarella Julien Colafrancesco Damien Cramet Sarah Denoux \\'Etienne Gaudrin Olivier Guillerminet Pierre Guillot Albert Gr\\\"af Pierre Jouvelot Stefan Kersten Victor Lazzarini Matthieu Leberre Mathieu Leroi Fernando Lopez-Lezcano Kjetil Matheussen Hermann Meyer Romain Michon R\\'emy Muller Eliott Paris Reza Payami Laurent Pottier Sampo Savolainen Nicolas Scaringella Anne Sedes Priyanka Shekar Stephen Sinclair Travis Skare Julius Smith Mike Solomon Michael Wilson as well as our colleagues at GRAME: Dominique Fober Christophe Lebreton St\\'ephane Letz Romain Michon We would like also to thank for their financial support: the French Ministry of Culture the Rh\\^one-Alpes Region the City of Lyon the French National Research Agency ( ANR )","title":"13 acknowledgments"},{"location":"qreference/13-acknowledgments/#acknowledgments","text":"Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen Karim Barkati J\\'er\\^ome Barth\\'elemy Tim Blechmann Tiziano Bole Alain Bonardi Thomas Charbonnel Raffaele Ciavarella Julien Colafrancesco Damien Cramet Sarah Denoux \\'Etienne Gaudrin Olivier Guillerminet Pierre Guillot Albert Gr\\\"af Pierre Jouvelot Stefan Kersten Victor Lazzarini Matthieu Leberre Mathieu Leroi Fernando Lopez-Lezcano Kjetil Matheussen Hermann Meyer Romain Michon R\\'emy Muller Eliott Paris Reza Payami Laurent Pottier Sampo Savolainen Nicolas Scaringella Anne Sedes Priyanka Shekar Stephen Sinclair Travis Skare Julius Smith Mike Solomon Michael Wilson as well as our colleagues at GRAME: Dominique Fober Christophe Lebreton St\\'ephane Letz Romain Michon We would like also to thank for their financial support: the French Ministry of Culture the Rh\\^one-Alpes Region the City of Lyon the French National Research Agency ( ANR )","title":"Acknowledgments"},{"location":"qreference/2-install/","text":"Compiling and installing Faust The Faust source distribution faust-2.74.6.tar.gz can be downloaded from GitHub ( https://github.com/grame-cncm/faust/releases ). Organization of the distribution The first thing is to decompress the downloaded archive. tar xzf faust-2.74.6.tar.gz The resulting faust-2.74.6/ folder should contain the following elements: architecture/ Faust libraries and architecture files benchmark tools to measure the efficiency of the generated code compiler/ sources of the Faust compiler examples/ examples of Faust programs syntax-highlighting/ & support for syntax highlighting for several editors documentation/ Faust 's documentation, including this manual tools/ tools to produce audio applications and plugins COPYING license information Makefile Makefile used to build and install Faust README instructions on how to build and install Faust Compilation Faust has no dependencies outside standard libraries. Therefore the compilation should be straightforward. There is no configuration phase, to compile the Faust compiler simply do : cd faust-2.74.6/ make If the compilation was successful you can test the compiler before installing it: [cd faust-2.74.6/] ./build/bin/faust -v It should output: FAUST Version 2.74.6 Embedded backends: DSP to C DSP to C++ DSP to Cmajor DSP to Codebox DSP to CSharp DSP to DLang DSP to Java DSP to JAX DSP to Julia DSP to JSFX DSP to old C++ DSP to Rust DSP to WebAssembly (wast/wasm) Copyright (C) 2002-2024, GRAME - Centre National de Creation Musicale. All rights reserved. Then you can also try to compile one of the examples : [cd faust-2.74.6/] ./build/bin/faust examples/generator/noise.dsp It should produce some C++ code on the standard output. Installation You can install Faust with: [cd faust-2.74.6/] sudo make install or [cd faust-2.74.6/] su make install depending on your system. Compilation of the examples Once Faust correctly installed, you can have a look at the provided examples in the examples/ folder. You can use any of the faust2... script installed on your system (go in /tools/faust2appls to get an exhaustive list) to compile the Faust codes available in this folder. For example, if you're a Mac user and you want to turn filtering/vcfWahLab.dsp into a standalone CoreAudio application with a QT interface, just run: faust2caqt filtering/vcfWahLab.dsp","title":"2 install"},{"location":"qreference/2-install/#compiling-and-installing-faust","text":"The Faust source distribution faust-2.74.6.tar.gz can be downloaded from GitHub ( https://github.com/grame-cncm/faust/releases ).","title":"Compiling and installing Faust"},{"location":"qreference/2-install/#organization-of-the-distribution","text":"The first thing is to decompress the downloaded archive. tar xzf faust-2.74.6.tar.gz The resulting faust-2.74.6/ folder should contain the following elements: architecture/ Faust libraries and architecture files benchmark tools to measure the efficiency of the generated code compiler/ sources of the Faust compiler examples/ examples of Faust programs syntax-highlighting/ & support for syntax highlighting for several editors documentation/ Faust 's documentation, including this manual tools/ tools to produce audio applications and plugins COPYING license information Makefile Makefile used to build and install Faust README instructions on how to build and install Faust","title":"Organization of the distribution"},{"location":"qreference/2-install/#compilation","text":"Faust has no dependencies outside standard libraries. Therefore the compilation should be straightforward. There is no configuration phase, to compile the Faust compiler simply do : cd faust-2.74.6/ make If the compilation was successful you can test the compiler before installing it: [cd faust-2.74.6/] ./build/bin/faust -v It should output: FAUST Version 2.74.6 Embedded backends: DSP to C DSP to C++ DSP to Cmajor DSP to Codebox DSP to CSharp DSP to DLang DSP to Java DSP to JAX DSP to Julia DSP to JSFX DSP to old C++ DSP to Rust DSP to WebAssembly (wast/wasm) Copyright (C) 2002-2024, GRAME - Centre National de Creation Musicale. All rights reserved. Then you can also try to compile one of the examples : [cd faust-2.74.6/] ./build/bin/faust examples/generator/noise.dsp It should produce some C++ code on the standard output.","title":"Compilation"},{"location":"qreference/2-install/#installation","text":"You can install Faust with: [cd faust-2.74.6/] sudo make install or [cd faust-2.74.6/] su make install depending on your system.","title":"Installation"},{"location":"qreference/2-install/#compilation-of-the-examples","text":"Once Faust correctly installed, you can have a look at the provided examples in the examples/ folder. You can use any of the faust2... script installed on your system (go in /tools/faust2appls to get an exhaustive list) to compile the Faust codes available in this folder. For example, if you're a Mac user and you want to turn filtering/vcfWahLab.dsp into a standalone CoreAudio application with a QT interface, just run: faust2caqt filtering/vcfWahLab.dsp","title":"Compilation of the examples"},{"location":"qreference/3-syntax/","text":"Faust syntax This section describes the syntax of Faust . Figure fig-syntax gives an overview of the various concepts and where they are defined in this section. Overview of Faust syntax As we will see, definitions and expressions have a central role. Faust program A Faust program is essentially a list of statements . These statements can be declarations , imports , definitions and documentation tags , with optional C++ style (//... and / ... /) comments. program ComplexDiagram( OneOrMore (NonTerminal('statement')) ).addTo() A Simple Program Here is a short Faust program that implements of a simple noise generator. It exhibits various kind of statements: two declarations , an import , a comment and a definition . We will see later on documentation statements ( sec-documentation ). declare name \"noise\"; declare copyright \"(c)GRAME 2006\"; import(\"music.lib\"); // noise level controlled by a slider process = noise * vslider(\"volume\", 0, 0, 1, 0.1); The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process . Statements The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions and documentation . All statements but documentation end with a semicolon ( ; ). statement ComplexDiagram( Choice (0, NonTerminal('declaration'), NonTerminal('fileimport'), NonTerminal('definition'), NonTerminal('documentation')) ).addTo() Declarations Meta-data declarations (for example declare name \"noise\"; ) are optional and typically used to document a Faust project. declaration ComplexDiagram( Sequence (\"declare\", NonTerminal('key'), NonTerminal('string'), ';') ).addTo() key ComplexDiagram( NonTerminal('identifier') ).addTo() Contrary to regular comments, these declarations will appear in the C++ code generated by the compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; Imports File imports allow to import definitions from other source files. fileimport ComplexDiagram( Sequence (\"import\", '(', NonTerminal('filename'), ')', ';') ).addTo() For example import(\"maths.lib\"); imports the definitions of the maths.lib library, a set of additional mathematical functions provided as foreign functions. Documentation Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed chapter \\ref{chapter-mdoc}. In this section we will essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in LaTeX format, can be placed in between these two tags. documentation ComplexDiagram( Sequence (\"<mdoc>\", OneOrMore (Choice (0, NonTerminal('freetext'), NonTerminal('equation'), NonTerminal('diagram'), NonTerminal('metadata'), NonTerminal('notice'), NonTerminal('listing'))), \"</mdoc>\") ).addTo() Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . equation ComplexDiagram( Sequence (\"<equation>\", NonTerminal('expression'), \"</equation>\") ).addTo() The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. diagram ComplexDiagram( Sequence (\"<diagram>\", NonTerminal('expression'), \"</diagram>\") ).addTo() Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. metadata ComplexDiagram( Sequence (\"<metadata>\", NonTerminal('keyword'), \"</metadata>\") ).addTo() The <metadata> tags allow to reference Faust metadatas (cf. declarations), calling the corresponding keyword. notice ComplexDiagram( \"<notice />\" ).addTo() The <notice /> empty-element tag is used to generate the conventions used in the mathematical equations. listing ComplexDiagram( Sequence (\"<listing\", NonTerminal('listingattribute*'), \" />\") ).addTo() listingattribute ComplexDiagram( Sequence (Choice (0, \"mdoctags\", \"dependencies\", \"distributed\"), \"=\", Choice (0, '\"true\"', '\"false\"')) ).addTo() The <listing /> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved faust code between sections. Definitions A definition associates an identifier with an expression it stands for. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition. Simple Definitions The syntax of a simple definition is: definition ComplexDiagram( Sequence (NonTerminal('identifier'), '=', NonTerminal('expression'), ';') ).addTo() For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245); Function Definitions Definitions with formal parameters correspond to functions definitions. fdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('parameter'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() For example the definition of linear2db , a function that converts linear values to decibels, is : linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x)); Definitions with pattern matching Moreover, formal parameters can also be full expressions representing patterns. pdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('pattern'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Please note that this last definition is a convenient alternative to the more verbose : duplicate = case { (1,x) => x; (n,x) => duplicate(n-1,x); }; Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11). The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element : count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) the expression will be evaluated to 10 . Please note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in : count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time. Variants Some statements (imports, definitions) can be preceded by a variantlist, composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308; Expressions Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. expression ComplexDiagram( Choice (0, NonTerminal('diagram'), NonTerminal('insouts'), NonTerminal('numerical'), NonTerminal('time'), NonTerminal('lexical'), NonTerminal('foreign'), NonTerminal('lambda')) ).addTo() Constant Numerical Expressions Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time. We will refer to them as constant numerical expressions in the documentation. Diagram Expressions Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. diagramexp ComplexDiagram( Choice (0, NonTerminal('diagcomposition'), NonTerminal('diagiteration')) ).addTo() Diagram composition operations Five binary composition operations are available to combine block-diagrams: recursion , parallel , sequential , split and merge composition. One can think of each of these composition operations as a particular way to connect two block diagrams. diagcomposition ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('~'), ',', ':', '<:', ':>'), NonTerminal('expression')) ).addTo() To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a bloc-diagram A are notated \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively notated : [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc.. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are given table table-composition . Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table infix-comparison-priority that gives the associativity of each numerical operator in infix expressions. Syntax Pri. Assoc. Description expression \\ \\sim \\ expression 4 left recursive composition expression \\ ,\\ expression 3 right parallel composition expression \\ :\\ expression 2 right sequential composition expression \\ <:\\ expression 1 right split composition expression \\ :>\\ expression 1 right merge composition Block-Diagram composition operation priorities Parallel Composition The parallel composition (A,B) (figure figure-par1 ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation : (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used : A,B,C,D , Faust uses right associativity and therefore build internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example of parallel composition (10,*) Sequential Composition The sequential composition A:B (figure figure-seq1 ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Example of sequential composition ((*,/):+) Sequential composition is an associative operation : (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore build internally the expression (A:(B:(C:D))) . Split Composition The split composition A<:B (figure figure-split1 ) operator is used to distribute the outputs of A to the inputs of B . example of split composition ((10,20) <: (+,*,/)) Each input i of B is connected to the output i \\bmod k of A : Merge Composition The merge composition A:>B (figure figure-merge1 ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : Each output i of A is connected to the input i \\bmod k of B : The k incoming signals of an input of B are summed together. example of merge composition ((10,20,30,40) :> *) Recursive Composition The recursive composition A~B (figure figure-rec1 ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable it requires that : Each input of B is connected to the corresponding output of A via an implicit 1-sample delay : A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . example of recursive composition +(12345) ~ *(1103515245) Inputs and outputs of an expression These two constructions can be used to know at compile time the number of inputs and outputs of any Faust expression. insouts ComplexDiagram( Choice (0, Sequence (\"inputs\", '(', NonTerminal('expression'), ')'), Sequence (\"outputs\", '(', NonTerminal('expression'), ')')) ).addTo() They are useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,selector(n-i-1,n)) with { n=outputs(expr); }; And the inputs of an expression : Xi(expr) = bus(n) <: par(i,n,selector(n-i-1,n)) : expr with { n=inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction. Iterations Iterations are analogous to for(...) loops and provide a convenient way to automate some complex block-diagram constructions. diagiteration ComplexDiagram( Choice (0, Sequence (\"par\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"seq\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"sum\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"prod\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')')) ).addTo() The following example shows the usage of seq to create a 10-bands filter: process = seq(i, 10, vgroup(\"band %i\", bandfilter( 1000*(1+i) ) ) ); numiter ComplexDiagram( NonTerminal('expression') ).addTo() The number of iterations must be a constant expression. Infix Notation Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in \\(2+3\\)}Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar \\emph{infix notation . For example if you want to multiply two numbers, let say 2 and 3 , you can write directly 2 3 instead of the equivalent core-syntax expression 2,3: . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example you can write /2 . It is equivalent to ,2:/ which divides the incoming signal by 2 . Examples of equivalences are given table tab-infixrules . 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < Infix and core syntax equivalences In case of doubts on the meaning of an infix expression, for example _ , it is useful to translate it to its core syntax equivalent, here ,_: , which is equivalent to * . Built-in primitives that can be used in infix notation are called infix operators and are listed in this section. Please note that a more detailed description of these operators is available section primitives . Comparison Operators Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. comparison ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '<', '<=', '>', '>=', '==', '!='), NonTerminal('expression')) ).addTo() The priority and associativity of the comparison operators is given table infix-comparison-priority . Syntax Pri. Assoc. Description expression \\ <\\ expression 5 left less than expression \\ <=\\ expression 5 left less or equal expression \\ !=\\ expression 5 left different expression \\ >=\\ expression 5 left greater or equal expression \\ >\\ expression 5 left greater than Comparison operators priorities in infix expressions Math Operators Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. math ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '+', '-', '*', '/', '%', NonTerminal('\u22c0')), NonTerminal('expression')) ).addTo() The priority and associativity of the math operators is given table infix-math-priority . Syntax Pri. Assoc. Description expression \\ +\\ expression 6 left addition expression \\ -\\ expression 6 left subtraction expression \\ *\\ expression 7 left multiplication expression \\ /\\ expression 7 left division expression \\ %\\ expression 7 left modulo expression \\ \\^\\ expression 8 left power Math operators priorities in infix expressions Bitwise operators Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. bitwise ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('|'), NonTerminal('&'), 'xor', '<<', '>>'), NonTerminal('expression')) ).addTo() The priority and associativity of the bitwise operators is given table infix-bitwise-priority . Syntax Pri. Assoc. Description expression \\ |\\ expression 6 left bitwise or expression \\ \\ expression 7 left expression \\ xor\\ expression 7 left bitwise xor expression \\ <<\\ expression 7 left bitwise left shift expression \\ >>\\ expression 7 left bitwise right shift Bitwise operators priorities in infix expressions Delay operators Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. delay ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \"'\" delays the left handside expression by one sample. The priority and associativity of the delay operators is given table infix-delay-priority . Syntax Pri. Assoc. Description expression \\ @\\ expression 9 left variable delay expression \\' 10 left one-sample delay Delay operators priorities in infix expressions Prefix Notation Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Prefix to core syntax translation rules It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) (see table tab-prefixrules ). Partial Application The partial application notation is a variant of prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube) and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one, as summarized table tab-partialrules . +(C) \\equiv _,C:* -(C) \\equiv _,C:- <(C) \\equiv _,C:< /(C) \\equiv _,C:/ Partial application of infix operators For commutative operations that doesn't matter. But for non-commutative ones, it is more ``natural'' to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Time expressions Time expressions are used to express delays. The notation X@10 represent the signal X delayed by 10 samples. The notation \"X'\" represent the signal X delayed by one sample and is therefore equivalent to X@1 . time ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay (automatically promoted to int ) don't have to be fixed, but it must be positive and bounded. The values of a slider are perfectly acceptable as in the following example: process = _ @ hslider(\"delay\",0, 0, 100, 1); Environment expressions Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. envexp ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), NonTerminal('definition+'), NonTerminal('}')), Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')), Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')), Sequence (NonTerminal('expression'), '.', NonTerminal('ident')), Sequence ('library', '(', NonTerminal('filename'), ')'), Sequence ('component', '(', NonTerminal('filename'), ')'), Sequence (NonTerminal('expression'), '[', OneOrMore (NonTerminal('definition')), ']')) ).addTo() With The with construction allows to specify a local environment , a private list of definition that will be used to evaluate the left hand expression withexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example : pink = f : + ~ g with { f(x) = 0.04957526213389*x - 0.06305581334498*x' + 0.01483220320740*x''; g(x) = 1.80116083982126*x - 0.80257737639225*x'; }; the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} . Letrec The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows to easily express groups of mutually recursive signals, for example: x(t)&=&y(t-1)+10; y(t)&=&x(t-1)-1; as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: letrecexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')) ).addTo() diffequation ComplexDiagram( Sequence (NonTerminal('''), NonTerminal('ident'), '=', NonTerminal('expression'), ';') ).addTo() Please remarks the special notation 'x=y+10 instead of x=y'+10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelop generator with an attack time, a release time and a gate signal. A possible definition is the following: ar(a,r,g) = v letrec { 'n = (n+1) * (g<=g'); 'v = max(0, v + (n<a)/a - (n>=a)/r) * (g<=g'); }; With the following semantics for n(t) and v(t) : n(t)&=&(n(t-1)+1) * (g(t) <= g(t-1)) v(t)&=& max(0, v(t-1) + (n(t-1) =a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of 'letrec': x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); }; Environment The environment construction allows to create an explicit environment. It is like a with , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. environment ComplexDiagram( Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example an environment construction is used to group together some constant definitions : constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next paragraph). Access Definitions inside an environment can be accessed using the '.' construction. access ComplexDiagram( Sequence (NonTerminal('expression'), '.', NonTerminal('ident')) ).addTo() For example constant.pi refers to the definition of pi in the above constant environment. Please note that environment don't have to be named. We could have written directly environment{pi = 3.14159; e = 2.718; ... }.pi Library The library construct allows to create an environment by reading the definitions from a file. library ComplexDiagram( Sequence ('library', '(', NonTerminal('filename'), ')') ).addTo() For example library(\"miscfilter.lib\") represents the environment obtained by reading the file \"miscfilter.lib\". It works like import(\"miscfilter.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"miscfilter.lib\").lowpass denotes the function lowpass as defined in the file \"miscfilter.lib\" . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of : import(\"miscfilter.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts : fl = library(\"miscfilter.lib\"); ... ...fl.lowpass.... ... }; Component The component(...) construction allows to reuse a full Faust program as a simple expression. component ComplexDiagram( Sequence ('component', '(', NonTerminal('filename'), ')') ).addTo() For example component(\"freeverb.dsp\") denotes the signal processor defined in file \"freeverb.dsp\". Components can be used within expressions like in: ...component(\"karplus32.dsp\"):component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . Explicit substitution Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. explicitsubst ComplexDiagram( Sequence (NonTerminal('expression'), \"[\", OneOrMore (NonTerminal('definition')), \"]\") ).addTo() For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing : ...component(\"freeverb.dsp\")[foo(x) = ...;]... }; Foreign expressions Reference to external (foreign) C functions , variables and constants can be introduced using the foreign expressions mechanism. foreignexp ComplexDiagram( Choice (0, Sequence ('ffunction', '(', NonTerminal('signature'), ',', NonTerminal('includefile'), ',', NonTerminal('library'), ')'), Sequence ('fvariable', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')'), Sequence ('fconstant', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')')) ).addTo() Foreign function declaration An external C function is declared by indicating its name and signature as well as the required include file. The file \"maths.lib\" of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad and fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision, and asinhfx in fixed-point precision. This is why the four names are provided in the signature. signature ComplexDiagram( Sequence (NonTerminal('type'), NonTerminal('funnames'), '(', OneOrMore (NonTerminal('argtype'), ','), ')') ).addTo() funnames ComplexDiagram( Sequence (NonTerminal('identifier'), Optional ( Sequence ('|', NonTerminal('identifier'))), Optional ( Sequence ('|', NonTerminal('identifier')))) ).addTo() Foreign functions generally expect a precise type: ( int or float ) for their parameters. Note that currently only numerical functions involving scalar parameters are allowed. No vectors, tables or data structures can be passed as parameters or returned. During the compilation if the type of an argument is not the same as the type of the parameter, it is automatically converted to the expected one. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float. Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); type ComplexDiagram( Choice (0, 'int', 'float') ).addTo() argtype ComplexDiagram( Choice (0, 'int', 'float', 'any') ).addTo() Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate. Foreign variables and constants External variables and constants can also be declared with a similar syntax. In the same \"maths.lib\" file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found : SR = min(192000.0, max(1.0, fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block. Include file In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include... in the generated code. includefile ComplexDiagram( Choice (0, Sequence ('<', OneOrMore (NonTerminal('char')), '>'), Sequence ('\"', OneOrMore (NonTerminal('char')), '\"')) ).addTo() Library file In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model. Applications and Abstractions Abstractions and applications are fundamental programming constructions directly inspired by the Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. progexp ComplexDiagram( Choice (0, NonTerminal('abstraction'), NonTerminal('application')) ).addTo() Abstractions Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. abstraction ComplexDiagram( Choice (0, NonTerminal('lambdaabstraction'), NonTerminal('patternabstraction')) ).addTo() lambdaabstraction ComplexDiagram( Sequence (NonTerminal('\\'), '(', OneOrMore (NonTerminal('ident'), ','), ')', '.', '(', NonTerminal('expression'), ')') ).addTo() Let's say you want to transform a stereo reverb, freeverb for instance, into a mono effect. You can write the following expression: _ <: freeverb :> _ The incoming mono signal is splitted to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that you are interested in transforming other stereo effects. It can be interesting to generalize this principle by making freeverb a variable: \\(freeverb).(_ <: freeverb :> _) The resulting abstraction can then be applied to transform other effects. Note that if freeverb is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) Moreover it could be convenient to give a name to this abstraction: mono = \\(fx).(_ <: fx :> _); Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _; Applications Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. application ComplexDiagram( Sequence (NonTerminal('expression'), '(', OneOrMore (NonTerminal('expression'), ','), ')') ).addTo() For example you can apply the previous abstraction to transform your stereo harmonizer: mono(harmonizer) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(harmonizer) Whenever the Faust compiler find an application of an abstraction it replaces Replacing the variable part with the argument is called \\beta -reduction in Lambda-Calculus} the \\emph{variable part with the argument. The resulting expression is as expected: (_ <: harmonizer :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments). Unapplied abstractions Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values\\footnote{ https://en.wikipedia.org/wiki/First-class_function } which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: import(\"stdfaust.lib\"); repeat(fx) = fx : fx; process = repeat(dm.zita_light); In Faust, a proper semantic has been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: process = _,_ <: !,_,_,!; can be simply defined as: process = \\(x,y).(y,x); which is actually equivalent to: process(x,y) = y,x; Pattern Matching Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. patternabstraction ComplexDiagram( Sequence (\"case\", NonTerminal('{'), OneOrMore (NonTerminal('rule')), NonTerminal('}')) ).addTo() Rule ComplexDiagram( Sequence ('(', OneOrMore (NonTerminal('pattern'), ','), ')', \"=>\", NonTerminal('expression'), ';') ).addTo() Pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(freeverb:harmonizer) will produce: (harmonizer:freeverb) Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching. Primitives The primitive signal processing operations represent the built-in functionalities of Faust , that is the atomic operations on signals provided by the language. All these primitives denote signal processors , functions transforming input signals into output signals . primitive ComplexDiagram( Choice (0, NonTerminal('number'), NonTerminal('route'), NonTerminal('waveform'), NonTerminal('soundfile'), NonTerminal('cprimitive'), NonTerminal('mathprimitive'), NonTerminal('delayandtables'), NonTerminal('uielements'), NonTerminal('%ulation')) ).addTo() Numbers Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. int ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() float ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), Choice (0, Sequence (NonTerminal('digit+'), '.', NonTerminal('digit*')), Sequence (NonTerminal('digit*'), '.', NonTerminal('digit+'))), Optional ( NonTerminal('exponent'))) ).addTo() exponent ComplexDiagram( Sequence ('e', Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() digit ComplexDiagram( \"0--9\" ).addTo() Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type. Route Primitive The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: - <span class=\"lstinline\">A</span> is the number of input signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">B</span> is the number of output signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">a,b / (a,b)</span> is an input/output pair, as integers _constant numerical expressions_, automatically promoted to _int_ Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: process = route(2,2,1,2,2,1); In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: process = route(2,2,(1,2),(2,1)); More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: // cross 10 signals: // input 0 -> output 10, // input 1 -> output 9, // ..., // input 9 -> output 0 N = 10; r = route(N,N,par(i,N,(i+1,N-i))); process = r; Waveform Primitive A waveform is a fixed periodic signal defined by a list of samples as literal numbers. A waveform has two outputs. The first output is constant and indicates the size (number of samples) of the period. The second output is the periodic signal itself. waveform ComplexDiagram( Sequence (\"waveform\", NonTerminal('{'), OneOrMore (NonTerminal('number'), ','), NonTerminal('}')) ).addTo() For example waveform {0,1,2,3} produces two outputs, the constant signal 4 and the periodic signal 0,1,2,3,0,1,2,3,0,1 \\ldots. Please note that waveform works nicely with rdtable . Its first output, known at compile time, gives the size of the table, while the second signal gives the content of the table. Here is an example: process = waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable; Soundfile Primitive The soundfile(\"label[url:{ path1';'path2';'path3';}]\", n)' primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the '%i' syntax, as in the label part). The soundfile(\"label[url:path]\", n) , or soundfile(\"label\", n) (where label is used as the soundfile path) simplified syntax allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: - two inputs: the sound number (as a integer between 0 and 255, automatically promoted to _int_), and the read index in the sound (automatically promoted to _int_, which will access the last sample of the sound if the read index is greater than the sound length) - two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound - <span class=\"lstinline\">n</span> several more outputs for the sound channels themselves, as a integer _constant numerical expression_ If more outputs than the actual number of channels in the soundfile are used, the sound channels will be automatically duplicated up to the wanted number of outputs (so for instance if a stereo sound is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file implements the void addSoundfile(label, url, sf_zone) method, which loads the actual soundfiles using the {\\it libsndfile} library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that a special architecture file can perfectly decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge to actually setup all sound memory pointers when void addSoundfile(label, url, sf_zone) is called by the buidUserInterface mechanism. C-equivalent primitives Most Faust primitives are analogue to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form Warning: unlike other programming languages the unary operatior - only exists in limited form in Faust . It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance -(a * b) is a partial application. It is syntactic sugar for _,(a * b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a * b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Syntax Type Description n \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} integer number: y(t)=n n.m \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} floating point number: y(t)=n.m _ \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} identity function: y(t)=x(t) ! \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} cut function: \\forall x\\in\\mathbb{S},(x)\\rightarrow () int \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an int signal: y(t)=(int)x(t) float \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an float signal: y(t)=(float)x(t) + \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} addition: y(t)=x_{1}(t)+x_{2}(t) - \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} subtraction: y(t)=x_{1}(t)-x_{2}(t) * \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} multiplication: y(t)=x_{1}(t)*x_{2}(t) \\land \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=x_{1}(t)^{x_{2}(t)} / \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} division: y(t)=x_{1}(t)/x_{2}(t) % \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} modulo: y(t)=x_{1}(t)%x_{2}(t) \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} | \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise OR: y(t)=x_{1}(t)\\|x_{2}(t) xor \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise XOR: y(t)=x_{1}(t)\\land x_{2}(t) << \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift left: y(t)=x_{1}(t) << x_{2}(t) >> \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift right: y(t)=x_{1}(t) >> x_{2}(t) < \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less than: y(t)=x_{1}(t) < x_{2}(t) <= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less or equal: y(t)=x_{1}(t) <= x_{2}(t) > \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater than: y(t)=x_{1}(t) > x_{2}(t) >= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater or equal: y(t)=x_{1}(t) >= x_{2}(t) == \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} equal: y(t)=x_{1}(t) == x_{2}(t) != \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} different: y(t)=x_{1}(t) != x_{2}(t) math.h-equivalent primitives Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. Syntax Type Description acos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc cosine: y(t)=\\mathrm{acosf}(x(t)) asin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc sine: y(t)=\\mathrm{asinf}(x(t)) atan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atanf}(x(t)) atan2 \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) cos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cosine: y(t)=\\mathrm{cosf}(x(t)) sin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} sine: y(t)=\\mathrm{sinf}(x(t)) tan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} tangent: y(t)=\\mathrm{tanf}(x(t)) exp \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e exponential: y(t)=\\mathrm{expf}(x(t)) log \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e logarithm: y(t)=\\mathrm{logf}(x(t)) log10 \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-10 logarithm: y(t)=\\mathrm{log10f}(x(t)) pow \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) sqrt \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} square root: y(t)=\\mathrm{sqrtf}(x(t)) abs \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} absolute value (int): y(t)=\\mathrm{abs}(x(t)) absolute value (float): y(t)=\\mathrm{fabsf}(x(t)) min \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} minimum: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) max \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} maximum: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) fmod \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float modulo: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) remainder \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float remainder: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) floor \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} largest int \\leq : y(t)=\\mathrm{floorf}(x(t)) ceil \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} smallest int \\geq : y(t)=\\mathrm{ceilf}(x(t)) rint \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} closest int using the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) round \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} nearest int value, regardless of the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) Delay, Table, Selector primitives The following primitives allow to define delays, read-only and read-write tables and 2 or 3-ways selectors (see figure fig-delays ), and some other specific primitives. Syntax Type Description mem \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x(t),y(0)=0 prefix \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x_{2}(t),y(0)=x_{1}(0) @ \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} variable delay: y(t)=x_{1}(t-x_{2}(t)), x_{1}(t<0)=0 rdtable \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} read-only table: y(t)=T[r(t)] rwtable \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} read-write table: T[w(t)]=c(t); y(t)=T[r(t)] select2 \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} select between 2 signals: T[]={x_{0}(t),x_{1}(t)}; y(t)=T[s(t)] select3 \\mathbb{S}^{4}\\rightarrow\\mathbb{S}^{1} select between 3 signals: T[]={x_{0}(t),x_{1}(t),x_{2}(t)}; y(t)=T[s(t)] lowest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\min_{j=0}^{\\inf} x(j) highest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\max_{j=0}^{\\inf} x(j) <a name=\"fig-delays\"></a> Delays, tables and selectors primitives The size input of rdtable and rwtable are integer constant numerical expressions automatically promoted to int , and the read and write indexes are also automatically promoted to int . The delay value is automatically promoted to int . User Interface Elements Faust user interface widgets allow an abstract description of the user interface from within the Faust code. This description is independent of any GUI toolkits. It is based on buttons , checkboxes , sliders , etc. that are grouped together vertically and horizontally using appropriate grouping schemes. All these GUI elements produce signals. A button for example (see figure fig-button ) produces a signal which is 1 when the button is pressed and 0 otherwise. These signals can be freely combined with other audio signals. <a name=\"fig-button\"></a> User Interface Button Syntax Example button( str ) button(\"play\") checkbox( str ) checkbox(\"mute\") vslider( str , cur , min , max , step ) vslider(\"vol\",50,0,100,1) hslider( str , cur , min , max , step ) hslider(\"vol\",0.5,0,1,0.01) nentry( str , cur , min , max , step ) nentry(\"freq\",440,0,8000,1) vgroup( str , block-diagram ) vgroup(\"reverb\", \\ldots) hgroup( str , block-diagram ) hgroup(\"mixer\", \\ldots) tgroup( str , block-diagram ) tgroup(\"parametric\", \\ldots) vbargraph( str , min , max ) vbargraph(\"input\",0,100) hbargraph( str , min , max ) hbargraph(\"signal\",0,1.0) attach attach(x, vumeter(x)) All numerical parameters (like {\\it cur}, {\\it min}, {\\it max}, {\\it step}) are constant numerical expressions . Labels Every user interface widget has a label (a string) that identifies it and informs the user of its purpose. There are three important mechanisms associated with labels (and coded inside the string): variable parts , pathnames and metadata . Variable parts. Labels can contain variable parts. These variable parts are indicated by the sign '%' followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example par(i,8,hslider(\"Voice %i\", 0.9, 0, 1, 0.01)) creates 8 different sliders in parallel : hslider(\"Voice 0\", 0.9, 0, 1, 0.01), hslider(\"Voice 1\", 0.9, 0, 1, 0.01), ... hslider(\"Voice 7\", 0.9, 0, 1, 0.01). while par(i,8,hslider(\"Voice\", 0.9, 0, 1, 0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Pathnames. Thanks to horizontal, vertical and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated pathname obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of: hslider(\"../volume\",...) would have been \"/h:Foo/volume\" , while the pathname of: hslider(\"t:Fii/volume\",...) would have been: \"/h:Foo/v:Faa/t:Fii/volume\" . The grammar for labels with pathnames is the following: label ComplexDiagram( Sequence (NonTerminal('path'), NonTerminal('name')) ).addTo() path ComplexDiagram( Sequence (Optional ( '/'), Optional ( OneOrMore (Sequence (NonTerminal('folder'), '/')))) ).addTo() folder ComplexDiagram( Choice (0, \"..\", Sequence (Choice (0, \"h:\", \"v:\", \"t:\"), NonTerminal('name'))) ).addTo() Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface. The Faust code: process = *(hslider(\"foo [key1: val 1][key2: val 2]\", 0, 0, 1, 0.1)); will produce and the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* interface) { interface->openVerticalBox(\"m\"); interface->declare(&fslider0, \"key1\", \"val 1\"); interface->declare(&fslider0, \"key2\", \"val 2\"); interface->addHorizontalSlider(\"foo\", &fslider0, 0.0f, 0.0f, 1.0f, 0.1f); interface->closeBox(); } ... }; All the metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. It is the role of the architecture file to decide what to do with these metadata. The jack-qt.cpp architecture file for example implements the following: - \"...[style:knob]...\" creates a rotating knob instead of a regular slider or nentry. - \"...[style:led]...\" in a bargraph's label creates a small LED instead of a full bargraph - \"...[unit:dB]...\" in a bargraph's label creates a more realistic bargraph with colors ranging from green to red depending of the level of the value - \"...[unit:xx]...\" in a widget postfixes the value displayed with xx - \"...[tooltip:bla bla]...\" add a tooltip to the widget - \"...[osc:/address min max]...\" Open Sound Control message alias Moreover starting a label with a number option like in \"[1]...\" provides a convenient means to control the alphabetical order of the widgets. Attach The attach primitive takes two input signals and produce one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical point of view attach(x,y) is equivalent to 1 x+0 y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role let say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelop detector connected to a bargraph. The problem is that these envelop signals have no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. Widget Modulation Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: modulation Here is a very simple example of widget modulation, assuming freeverb is a fully functional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb] Target Widgets Target widgets are specified by their label. Of course, this presupposes knowing the names of the widgets. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb] Modulators Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: Please note that the `':'` sign used here is just a visual separator, it is not the sequential composition operator. [\"Wet\": * -> freeverb] To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the target widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs.","title":"3 syntax"},{"location":"qreference/3-syntax/#faust-syntax","text":"This section describes the syntax of Faust . Figure fig-syntax gives an overview of the various concepts and where they are defined in this section. Overview of Faust syntax As we will see, definitions and expressions have a central role.","title":"Faust syntax"},{"location":"qreference/3-syntax/#faust-program","text":"A Faust program is essentially a list of statements . These statements can be declarations , imports , definitions and documentation tags , with optional C++ style (//... and / ... /) comments. program ComplexDiagram( OneOrMore (NonTerminal('statement')) ).addTo()","title":"Faust program"},{"location":"qreference/3-syntax/#a-simple-program","text":"Here is a short Faust program that implements of a simple noise generator. It exhibits various kind of statements: two declarations , an import , a comment and a definition . We will see later on documentation statements ( sec-documentation ). declare name \"noise\"; declare copyright \"(c)GRAME 2006\"; import(\"music.lib\"); // noise level controlled by a slider process = noise * vslider(\"volume\", 0, 0, 1, 0.1); The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process .","title":"A Simple Program"},{"location":"qreference/3-syntax/#statements","text":"The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions and documentation . All statements but documentation end with a semicolon ( ; ). statement ComplexDiagram( Choice (0, NonTerminal('declaration'), NonTerminal('fileimport'), NonTerminal('definition'), NonTerminal('documentation')) ).addTo()","title":"Statements"},{"location":"qreference/3-syntax/#declarations","text":"Meta-data declarations (for example declare name \"noise\"; ) are optional and typically used to document a Faust project. declaration ComplexDiagram( Sequence (\"declare\", NonTerminal('key'), NonTerminal('string'), ';') ).addTo() key ComplexDiagram( NonTerminal('identifier') ).addTo() Contrary to regular comments, these declarations will appear in the C++ code generated by the compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\";","title":"Declarations"},{"location":"qreference/3-syntax/#imports","text":"File imports allow to import definitions from other source files. fileimport ComplexDiagram( Sequence (\"import\", '(', NonTerminal('filename'), ')', ';') ).addTo() For example import(\"maths.lib\"); imports the definitions of the maths.lib library, a set of additional mathematical functions provided as foreign functions.","title":"Imports"},{"location":"qreference/3-syntax/#documentation","text":"Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed chapter \\ref{chapter-mdoc}. In this section we will essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in LaTeX format, can be placed in between these two tags. documentation ComplexDiagram( Sequence (\"<mdoc>\", OneOrMore (Choice (0, NonTerminal('freetext'), NonTerminal('equation'), NonTerminal('diagram'), NonTerminal('metadata'), NonTerminal('notice'), NonTerminal('listing'))), \"</mdoc>\") ).addTo() Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . equation ComplexDiagram( Sequence (\"<equation>\", NonTerminal('expression'), \"</equation>\") ).addTo() The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. diagram ComplexDiagram( Sequence (\"<diagram>\", NonTerminal('expression'), \"</diagram>\") ).addTo() Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. metadata ComplexDiagram( Sequence (\"<metadata>\", NonTerminal('keyword'), \"</metadata>\") ).addTo() The <metadata> tags allow to reference Faust metadatas (cf. declarations), calling the corresponding keyword. notice ComplexDiagram( \"<notice />\" ).addTo() The <notice /> empty-element tag is used to generate the conventions used in the mathematical equations. listing ComplexDiagram( Sequence (\"<listing\", NonTerminal('listingattribute*'), \" />\") ).addTo() listingattribute ComplexDiagram( Sequence (Choice (0, \"mdoctags\", \"dependencies\", \"distributed\"), \"=\", Choice (0, '\"true\"', '\"false\"')) ).addTo() The <listing /> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved faust code between sections.","title":"Documentation"},{"location":"qreference/3-syntax/#definitions","text":"A definition associates an identifier with an expression it stands for. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition.","title":"Definitions"},{"location":"qreference/3-syntax/#simple-definitions","text":"The syntax of a simple definition is: definition ComplexDiagram( Sequence (NonTerminal('identifier'), '=', NonTerminal('expression'), ';') ).addTo() For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245);","title":"Simple Definitions"},{"location":"qreference/3-syntax/#function-definitions","text":"Definitions with formal parameters correspond to functions definitions. fdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('parameter'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() For example the definition of linear2db , a function that converts linear values to decibels, is : linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x));","title":"Function Definitions"},{"location":"qreference/3-syntax/#definitions-with-pattern-matching","text":"Moreover, formal parameters can also be full expressions representing patterns. pdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('pattern'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Please note that this last definition is a convenient alternative to the more verbose : duplicate = case { (1,x) => x; (n,x) => duplicate(n-1,x); }; Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11). The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element : count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) the expression will be evaluated to 10 . Please note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in : count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time.","title":"Definitions with pattern matching"},{"location":"qreference/3-syntax/#variants","text":"Some statements (imports, definitions) can be preceded by a variantlist, composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308;","title":"Variants"},{"location":"qreference/3-syntax/#expressions","text":"Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. expression ComplexDiagram( Choice (0, NonTerminal('diagram'), NonTerminal('insouts'), NonTerminal('numerical'), NonTerminal('time'), NonTerminal('lexical'), NonTerminal('foreign'), NonTerminal('lambda')) ).addTo()","title":"Expressions"},{"location":"qreference/3-syntax/#constant-numerical-expressions","text":"Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time. We will refer to them as constant numerical expressions in the documentation.","title":"Constant Numerical Expressions"},{"location":"qreference/3-syntax/#diagram-expressions","text":"Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. diagramexp ComplexDiagram( Choice (0, NonTerminal('diagcomposition'), NonTerminal('diagiteration')) ).addTo()","title":"Diagram Expressions"},{"location":"qreference/3-syntax/#diagram-composition-operations","text":"Five binary composition operations are available to combine block-diagrams: recursion , parallel , sequential , split and merge composition. One can think of each of these composition operations as a particular way to connect two block diagrams. diagcomposition ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('~'), ',', ':', '<:', ':>'), NonTerminal('expression')) ).addTo() To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a bloc-diagram A are notated \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively notated : [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc.. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are given table table-composition . Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table infix-comparison-priority that gives the associativity of each numerical operator in infix expressions. Syntax Pri. Assoc. Description expression \\ \\sim \\ expression 4 left recursive composition expression \\ ,\\ expression 3 right parallel composition expression \\ :\\ expression 2 right sequential composition expression \\ <:\\ expression 1 right split composition expression \\ :>\\ expression 1 right merge composition Block-Diagram composition operation priorities Parallel Composition The parallel composition (A,B) (figure figure-par1 ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation : (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used : A,B,C,D , Faust uses right associativity and therefore build internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example of parallel composition (10,*) Sequential Composition The sequential composition A:B (figure figure-seq1 ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Example of sequential composition ((*,/):+) Sequential composition is an associative operation : (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore build internally the expression (A:(B:(C:D))) . Split Composition The split composition A<:B (figure figure-split1 ) operator is used to distribute the outputs of A to the inputs of B . example of split composition ((10,20) <: (+,*,/)) Each input i of B is connected to the output i \\bmod k of A : Merge Composition The merge composition A:>B (figure figure-merge1 ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : Each output i of A is connected to the input i \\bmod k of B : The k incoming signals of an input of B are summed together. example of merge composition ((10,20,30,40) :> *) Recursive Composition The recursive composition A~B (figure figure-rec1 ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable it requires that : Each input of B is connected to the corresponding output of A via an implicit 1-sample delay : A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . example of recursive composition +(12345) ~ *(1103515245)","title":"Diagram composition operations"},{"location":"qreference/3-syntax/#inputs-and-outputs-of-an-expression","text":"These two constructions can be used to know at compile time the number of inputs and outputs of any Faust expression. insouts ComplexDiagram( Choice (0, Sequence (\"inputs\", '(', NonTerminal('expression'), ')'), Sequence (\"outputs\", '(', NonTerminal('expression'), ')')) ).addTo() They are useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,selector(n-i-1,n)) with { n=outputs(expr); }; And the inputs of an expression : Xi(expr) = bus(n) <: par(i,n,selector(n-i-1,n)) : expr with { n=inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction.","title":"Inputs and outputs of an expression"},{"location":"qreference/3-syntax/#iterations","text":"Iterations are analogous to for(...) loops and provide a convenient way to automate some complex block-diagram constructions. diagiteration ComplexDiagram( Choice (0, Sequence (\"par\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"seq\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"sum\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"prod\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')')) ).addTo() The following example shows the usage of seq to create a 10-bands filter: process = seq(i, 10, vgroup(\"band %i\", bandfilter( 1000*(1+i) ) ) ); numiter ComplexDiagram( NonTerminal('expression') ).addTo() The number of iterations must be a constant expression.","title":"Iterations"},{"location":"qreference/3-syntax/#infix-notation","text":"Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in \\(2+3\\)}Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar \\emph{infix notation . For example if you want to multiply two numbers, let say 2 and 3 , you can write directly 2 3 instead of the equivalent core-syntax expression 2,3: . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example you can write /2 . It is equivalent to ,2:/ which divides the incoming signal by 2 . Examples of equivalences are given table tab-infixrules . 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < Infix and core syntax equivalences In case of doubts on the meaning of an infix expression, for example _ , it is useful to translate it to its core syntax equivalent, here ,_: , which is equivalent to * . Built-in primitives that can be used in infix notation are called infix operators and are listed in this section. Please note that a more detailed description of these operators is available section primitives .","title":"Infix Notation"},{"location":"qreference/3-syntax/#comparison-operators","text":"Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. comparison ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '<', '<=', '>', '>=', '==', '!='), NonTerminal('expression')) ).addTo() The priority and associativity of the comparison operators is given table infix-comparison-priority . Syntax Pri. Assoc. Description expression \\ <\\ expression 5 left less than expression \\ <=\\ expression 5 left less or equal expression \\ !=\\ expression 5 left different expression \\ >=\\ expression 5 left greater or equal expression \\ >\\ expression 5 left greater than Comparison operators priorities in infix expressions","title":"Comparison Operators"},{"location":"qreference/3-syntax/#math-operators","text":"Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. math ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '+', '-', '*', '/', '%', NonTerminal('\u22c0')), NonTerminal('expression')) ).addTo() The priority and associativity of the math operators is given table infix-math-priority . Syntax Pri. Assoc. Description expression \\ +\\ expression 6 left addition expression \\ -\\ expression 6 left subtraction expression \\ *\\ expression 7 left multiplication expression \\ /\\ expression 7 left division expression \\ %\\ expression 7 left modulo expression \\ \\^\\ expression 8 left power Math operators priorities in infix expressions","title":"Math Operators"},{"location":"qreference/3-syntax/#bitwise-operators","text":"Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. bitwise ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('|'), NonTerminal('&'), 'xor', '<<', '>>'), NonTerminal('expression')) ).addTo() The priority and associativity of the bitwise operators is given table infix-bitwise-priority . Syntax Pri. Assoc. Description expression \\ |\\ expression 6 left bitwise or expression \\ \\ expression 7 left expression \\ xor\\ expression 7 left bitwise xor expression \\ <<\\ expression 7 left bitwise left shift expression \\ >>\\ expression 7 left bitwise right shift Bitwise operators priorities in infix expressions","title":"Bitwise operators"},{"location":"qreference/3-syntax/#delay-operators","text":"Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. delay ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \"'\" delays the left handside expression by one sample. The priority and associativity of the delay operators is given table infix-delay-priority . Syntax Pri. Assoc. Description expression \\ @\\ expression 9 left variable delay expression \\' 10 left one-sample delay Delay operators priorities in infix expressions","title":"Delay operators"},{"location":"qreference/3-syntax/#prefix-notation","text":"Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Prefix to core syntax translation rules It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) (see table tab-prefixrules ).","title":"Prefix Notation"},{"location":"qreference/3-syntax/#partial-application","text":"The partial application notation is a variant of prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube) and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one, as summarized table tab-partialrules . +(C) \\equiv _,C:* -(C) \\equiv _,C:- <(C) \\equiv _,C:< /(C) \\equiv _,C:/ Partial application of infix operators For commutative operations that doesn't matter. But for non-commutative ones, it is more ``natural'' to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter.","title":"Partial Application"},{"location":"qreference/3-syntax/#time-expressions","text":"Time expressions are used to express delays. The notation X@10 represent the signal X delayed by 10 samples. The notation \"X'\" represent the signal X delayed by one sample and is therefore equivalent to X@1 . time ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay (automatically promoted to int ) don't have to be fixed, but it must be positive and bounded. The values of a slider are perfectly acceptable as in the following example: process = _ @ hslider(\"delay\",0, 0, 100, 1);","title":"Time expressions"},{"location":"qreference/3-syntax/#environment-expressions","text":"Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. envexp ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), NonTerminal('definition+'), NonTerminal('}')), Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')), Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')), Sequence (NonTerminal('expression'), '.', NonTerminal('ident')), Sequence ('library', '(', NonTerminal('filename'), ')'), Sequence ('component', '(', NonTerminal('filename'), ')'), Sequence (NonTerminal('expression'), '[', OneOrMore (NonTerminal('definition')), ']')) ).addTo()","title":"Environment expressions"},{"location":"qreference/3-syntax/#with","text":"The with construction allows to specify a local environment , a private list of definition that will be used to evaluate the left hand expression withexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example : pink = f : + ~ g with { f(x) = 0.04957526213389*x - 0.06305581334498*x' + 0.01483220320740*x''; g(x) = 1.80116083982126*x - 0.80257737639225*x'; }; the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} .","title":"With"},{"location":"qreference/3-syntax/#letrec","text":"The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows to easily express groups of mutually recursive signals, for example: x(t)&=&y(t-1)+10; y(t)&=&x(t-1)-1; as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: letrecexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')) ).addTo() diffequation ComplexDiagram( Sequence (NonTerminal('''), NonTerminal('ident'), '=', NonTerminal('expression'), ';') ).addTo() Please remarks the special notation 'x=y+10 instead of x=y'+10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelop generator with an attack time, a release time and a gate signal. A possible definition is the following: ar(a,r,g) = v letrec { 'n = (n+1) * (g<=g'); 'v = max(0, v + (n<a)/a - (n>=a)/r) * (g<=g'); }; With the following semantics for n(t) and v(t) : n(t)&=&(n(t-1)+1) * (g(t) <= g(t-1)) v(t)&=& max(0, v(t-1) + (n(t-1) =a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of 'letrec': x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); };","title":"Letrec"},{"location":"qreference/3-syntax/#environment","text":"The environment construction allows to create an explicit environment. It is like a with , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. environment ComplexDiagram( Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example an environment construction is used to group together some constant definitions : constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next paragraph).","title":"Environment"},{"location":"qreference/3-syntax/#access","text":"Definitions inside an environment can be accessed using the '.' construction. access ComplexDiagram( Sequence (NonTerminal('expression'), '.', NonTerminal('ident')) ).addTo() For example constant.pi refers to the definition of pi in the above constant environment. Please note that environment don't have to be named. We could have written directly environment{pi = 3.14159; e = 2.718; ... }.pi","title":"Access"},{"location":"qreference/3-syntax/#library","text":"The library construct allows to create an environment by reading the definitions from a file. library ComplexDiagram( Sequence ('library', '(', NonTerminal('filename'), ')') ).addTo() For example library(\"miscfilter.lib\") represents the environment obtained by reading the file \"miscfilter.lib\". It works like import(\"miscfilter.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"miscfilter.lib\").lowpass denotes the function lowpass as defined in the file \"miscfilter.lib\" . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of : import(\"miscfilter.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts : fl = library(\"miscfilter.lib\"); ... ...fl.lowpass.... ... };","title":"Library"},{"location":"qreference/3-syntax/#component","text":"The component(...) construction allows to reuse a full Faust program as a simple expression. component ComplexDiagram( Sequence ('component', '(', NonTerminal('filename'), ')') ).addTo() For example component(\"freeverb.dsp\") denotes the signal processor defined in file \"freeverb.dsp\". Components can be used within expressions like in: ...component(\"karplus32.dsp\"):component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process .","title":"Component"},{"location":"qreference/3-syntax/#explicit-substitution","text":"Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. explicitsubst ComplexDiagram( Sequence (NonTerminal('expression'), \"[\", OneOrMore (NonTerminal('definition')), \"]\") ).addTo() For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing : ...component(\"freeverb.dsp\")[foo(x) = ...;]... };","title":"Explicit substitution"},{"location":"qreference/3-syntax/#foreign-expressions","text":"Reference to external (foreign) C functions , variables and constants can be introduced using the foreign expressions mechanism. foreignexp ComplexDiagram( Choice (0, Sequence ('ffunction', '(', NonTerminal('signature'), ',', NonTerminal('includefile'), ',', NonTerminal('library'), ')'), Sequence ('fvariable', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')'), Sequence ('fconstant', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')')) ).addTo()","title":"Foreign expressions"},{"location":"qreference/3-syntax/#foreign-function-declaration","text":"An external C function is declared by indicating its name and signature as well as the required include file. The file \"maths.lib\" of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad and fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision, and asinhfx in fixed-point precision. This is why the four names are provided in the signature. signature ComplexDiagram( Sequence (NonTerminal('type'), NonTerminal('funnames'), '(', OneOrMore (NonTerminal('argtype'), ','), ')') ).addTo() funnames ComplexDiagram( Sequence (NonTerminal('identifier'), Optional ( Sequence ('|', NonTerminal('identifier'))), Optional ( Sequence ('|', NonTerminal('identifier')))) ).addTo() Foreign functions generally expect a precise type: ( int or float ) for their parameters. Note that currently only numerical functions involving scalar parameters are allowed. No vectors, tables or data structures can be passed as parameters or returned. During the compilation if the type of an argument is not the same as the type of the parameter, it is automatically converted to the expected one. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float. Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); type ComplexDiagram( Choice (0, 'int', 'float') ).addTo() argtype ComplexDiagram( Choice (0, 'int', 'float', 'any') ).addTo() Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate.","title":"Foreign function declaration"},{"location":"qreference/3-syntax/#foreign-variables-and-constants","text":"External variables and constants can also be declared with a similar syntax. In the same \"maths.lib\" file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found : SR = min(192000.0, max(1.0, fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block.","title":"Foreign variables and constants"},{"location":"qreference/3-syntax/#include-file","text":"In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include... in the generated code. includefile ComplexDiagram( Choice (0, Sequence ('<', OneOrMore (NonTerminal('char')), '>'), Sequence ('\"', OneOrMore (NonTerminal('char')), '\"')) ).addTo()","title":"Include file"},{"location":"qreference/3-syntax/#library-file","text":"In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model.","title":"Library file"},{"location":"qreference/3-syntax/#applications-and-abstractions","text":"Abstractions and applications are fundamental programming constructions directly inspired by the Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. progexp ComplexDiagram( Choice (0, NonTerminal('abstraction'), NonTerminal('application')) ).addTo()","title":"Applications and Abstractions"},{"location":"qreference/3-syntax/#abstractions","text":"Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. abstraction ComplexDiagram( Choice (0, NonTerminal('lambdaabstraction'), NonTerminal('patternabstraction')) ).addTo() lambdaabstraction ComplexDiagram( Sequence (NonTerminal('\\'), '(', OneOrMore (NonTerminal('ident'), ','), ')', '.', '(', NonTerminal('expression'), ')') ).addTo() Let's say you want to transform a stereo reverb, freeverb for instance, into a mono effect. You can write the following expression: _ <: freeverb :> _ The incoming mono signal is splitted to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that you are interested in transforming other stereo effects. It can be interesting to generalize this principle by making freeverb a variable: \\(freeverb).(_ <: freeverb :> _) The resulting abstraction can then be applied to transform other effects. Note that if freeverb is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) Moreover it could be convenient to give a name to this abstraction: mono = \\(fx).(_ <: fx :> _); Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _;","title":"Abstractions"},{"location":"qreference/3-syntax/#applications","text":"Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. application ComplexDiagram( Sequence (NonTerminal('expression'), '(', OneOrMore (NonTerminal('expression'), ','), ')') ).addTo() For example you can apply the previous abstraction to transform your stereo harmonizer: mono(harmonizer) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(harmonizer) Whenever the Faust compiler find an application of an abstraction it replaces Replacing the variable part with the argument is called \\beta -reduction in Lambda-Calculus} the \\emph{variable part with the argument. The resulting expression is as expected: (_ <: harmonizer :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments).","title":"Applications"},{"location":"qreference/3-syntax/#unapplied-abstractions","text":"Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values\\footnote{ https://en.wikipedia.org/wiki/First-class_function } which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: import(\"stdfaust.lib\"); repeat(fx) = fx : fx; process = repeat(dm.zita_light); In Faust, a proper semantic has been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: process = _,_ <: !,_,_,!; can be simply defined as: process = \\(x,y).(y,x); which is actually equivalent to: process(x,y) = y,x;","title":"Unapplied abstractions"},{"location":"qreference/3-syntax/#pattern-matching","text":"Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. patternabstraction ComplexDiagram( Sequence (\"case\", NonTerminal('{'), OneOrMore (NonTerminal('rule')), NonTerminal('}')) ).addTo() Rule ComplexDiagram( Sequence ('(', OneOrMore (NonTerminal('pattern'), ','), ')', \"=>\", NonTerminal('expression'), ';') ).addTo() Pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(freeverb:harmonizer) will produce: (harmonizer:freeverb) Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching.","title":"Pattern Matching"},{"location":"qreference/3-syntax/#primitives","text":"The primitive signal processing operations represent the built-in functionalities of Faust , that is the atomic operations on signals provided by the language. All these primitives denote signal processors , functions transforming input signals into output signals . primitive ComplexDiagram( Choice (0, NonTerminal('number'), NonTerminal('route'), NonTerminal('waveform'), NonTerminal('soundfile'), NonTerminal('cprimitive'), NonTerminal('mathprimitive'), NonTerminal('delayandtables'), NonTerminal('uielements'), NonTerminal('%ulation')) ).addTo()","title":"Primitives"},{"location":"qreference/3-syntax/#numbers","text":"Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. int ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() float ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), Choice (0, Sequence (NonTerminal('digit+'), '.', NonTerminal('digit*')), Sequence (NonTerminal('digit*'), '.', NonTerminal('digit+'))), Optional ( NonTerminal('exponent'))) ).addTo() exponent ComplexDiagram( Sequence ('e', Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() digit ComplexDiagram( \"0--9\" ).addTo() Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type.","title":"Numbers"},{"location":"qreference/3-syntax/#route-primitive","text":"The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: - <span class=\"lstinline\">A</span> is the number of input signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">B</span> is the number of output signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">a,b / (a,b)</span> is an input/output pair, as integers _constant numerical expressions_, automatically promoted to _int_ Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: process = route(2,2,1,2,2,1); In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: process = route(2,2,(1,2),(2,1)); More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: // cross 10 signals: // input 0 -> output 10, // input 1 -> output 9, // ..., // input 9 -> output 0 N = 10; r = route(N,N,par(i,N,(i+1,N-i))); process = r;","title":"Route Primitive"},{"location":"qreference/3-syntax/#waveform-primitive","text":"A waveform is a fixed periodic signal defined by a list of samples as literal numbers. A waveform has two outputs. The first output is constant and indicates the size (number of samples) of the period. The second output is the periodic signal itself. waveform ComplexDiagram( Sequence (\"waveform\", NonTerminal('{'), OneOrMore (NonTerminal('number'), ','), NonTerminal('}')) ).addTo() For example waveform {0,1,2,3} produces two outputs, the constant signal 4 and the periodic signal 0,1,2,3,0,1,2,3,0,1 \\ldots. Please note that waveform works nicely with rdtable . Its first output, known at compile time, gives the size of the table, while the second signal gives the content of the table. Here is an example: process = waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable;","title":"Waveform Primitive"},{"location":"qreference/3-syntax/#soundfile-primitive","text":"The soundfile(\"label[url:{ path1';'path2';'path3';}]\", n)' primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the '%i' syntax, as in the label part). The soundfile(\"label[url:path]\", n) , or soundfile(\"label\", n) (where label is used as the soundfile path) simplified syntax allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: - two inputs: the sound number (as a integer between 0 and 255, automatically promoted to _int_), and the read index in the sound (automatically promoted to _int_, which will access the last sample of the sound if the read index is greater than the sound length) - two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound - <span class=\"lstinline\">n</span> several more outputs for the sound channels themselves, as a integer _constant numerical expression_ If more outputs than the actual number of channels in the soundfile are used, the sound channels will be automatically duplicated up to the wanted number of outputs (so for instance if a stereo sound is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file implements the void addSoundfile(label, url, sf_zone) method, which loads the actual soundfiles using the {\\it libsndfile} library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that a special architecture file can perfectly decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge to actually setup all sound memory pointers when void addSoundfile(label, url, sf_zone) is called by the buidUserInterface mechanism.","title":"Soundfile Primitive"},{"location":"qreference/3-syntax/#c-equivalent-primitives","text":"Most Faust primitives are analogue to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form Warning: unlike other programming languages the unary operatior - only exists in limited form in Faust . It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance -(a * b) is a partial application. It is syntactic sugar for _,(a * b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a * b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Syntax Type Description n \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} integer number: y(t)=n n.m \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} floating point number: y(t)=n.m _ \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} identity function: y(t)=x(t) ! \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} cut function: \\forall x\\in\\mathbb{S},(x)\\rightarrow () int \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an int signal: y(t)=(int)x(t) float \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an float signal: y(t)=(float)x(t) + \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} addition: y(t)=x_{1}(t)+x_{2}(t) - \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} subtraction: y(t)=x_{1}(t)-x_{2}(t) * \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} multiplication: y(t)=x_{1}(t)*x_{2}(t) \\land \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=x_{1}(t)^{x_{2}(t)} / \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} division: y(t)=x_{1}(t)/x_{2}(t) % \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} modulo: y(t)=x_{1}(t)%x_{2}(t) \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} | \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise OR: y(t)=x_{1}(t)\\|x_{2}(t) xor \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise XOR: y(t)=x_{1}(t)\\land x_{2}(t) << \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift left: y(t)=x_{1}(t) << x_{2}(t) >> \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift right: y(t)=x_{1}(t) >> x_{2}(t) < \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less than: y(t)=x_{1}(t) < x_{2}(t) <= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less or equal: y(t)=x_{1}(t) <= x_{2}(t) > \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater than: y(t)=x_{1}(t) > x_{2}(t) >= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater or equal: y(t)=x_{1}(t) >= x_{2}(t) == \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} equal: y(t)=x_{1}(t) == x_{2}(t) != \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} different: y(t)=x_{1}(t) != x_{2}(t)","title":"C-equivalent primitives"},{"location":"qreference/3-syntax/#mathh-equivalent-primitives","text":"Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. Syntax Type Description acos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc cosine: y(t)=\\mathrm{acosf}(x(t)) asin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc sine: y(t)=\\mathrm{asinf}(x(t)) atan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atanf}(x(t)) atan2 \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) cos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cosine: y(t)=\\mathrm{cosf}(x(t)) sin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} sine: y(t)=\\mathrm{sinf}(x(t)) tan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} tangent: y(t)=\\mathrm{tanf}(x(t)) exp \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e exponential: y(t)=\\mathrm{expf}(x(t)) log \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e logarithm: y(t)=\\mathrm{logf}(x(t)) log10 \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-10 logarithm: y(t)=\\mathrm{log10f}(x(t)) pow \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) sqrt \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} square root: y(t)=\\mathrm{sqrtf}(x(t)) abs \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} absolute value (int): y(t)=\\mathrm{abs}(x(t)) absolute value (float): y(t)=\\mathrm{fabsf}(x(t)) min \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} minimum: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) max \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} maximum: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) fmod \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float modulo: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) remainder \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float remainder: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) floor \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} largest int \\leq : y(t)=\\mathrm{floorf}(x(t)) ceil \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} smallest int \\geq : y(t)=\\mathrm{ceilf}(x(t)) rint \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} closest int using the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) round \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} nearest int value, regardless of the current rounding mode: y(t)=\\mathrm{rintf}(x(t))","title":"math.h-equivalent primitives"},{"location":"qreference/3-syntax/#delay-table-selector-primitives","text":"The following primitives allow to define delays, read-only and read-write tables and 2 or 3-ways selectors (see figure fig-delays ), and some other specific primitives. Syntax Type Description mem \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x(t),y(0)=0 prefix \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x_{2}(t),y(0)=x_{1}(0) @ \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} variable delay: y(t)=x_{1}(t-x_{2}(t)), x_{1}(t<0)=0 rdtable \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} read-only table: y(t)=T[r(t)] rwtable \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} read-write table: T[w(t)]=c(t); y(t)=T[r(t)] select2 \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} select between 2 signals: T[]={x_{0}(t),x_{1}(t)}; y(t)=T[s(t)] select3 \\mathbb{S}^{4}\\rightarrow\\mathbb{S}^{1} select between 3 signals: T[]={x_{0}(t),x_{1}(t),x_{2}(t)}; y(t)=T[s(t)] lowest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\min_{j=0}^{\\inf} x(j) highest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\max_{j=0}^{\\inf} x(j) <a name=\"fig-delays\"></a> Delays, tables and selectors primitives The size input of rdtable and rwtable are integer constant numerical expressions automatically promoted to int , and the read and write indexes are also automatically promoted to int . The delay value is automatically promoted to int .","title":"Delay, Table, Selector primitives"},{"location":"qreference/3-syntax/#user-interface-elements","text":"Faust user interface widgets allow an abstract description of the user interface from within the Faust code. This description is independent of any GUI toolkits. It is based on buttons , checkboxes , sliders , etc. that are grouped together vertically and horizontally using appropriate grouping schemes. All these GUI elements produce signals. A button for example (see figure fig-button ) produces a signal which is 1 when the button is pressed and 0 otherwise. These signals can be freely combined with other audio signals. <a name=\"fig-button\"></a> User Interface Button Syntax Example button( str ) button(\"play\") checkbox( str ) checkbox(\"mute\") vslider( str , cur , min , max , step ) vslider(\"vol\",50,0,100,1) hslider( str , cur , min , max , step ) hslider(\"vol\",0.5,0,1,0.01) nentry( str , cur , min , max , step ) nentry(\"freq\",440,0,8000,1) vgroup( str , block-diagram ) vgroup(\"reverb\", \\ldots) hgroup( str , block-diagram ) hgroup(\"mixer\", \\ldots) tgroup( str , block-diagram ) tgroup(\"parametric\", \\ldots) vbargraph( str , min , max ) vbargraph(\"input\",0,100) hbargraph( str , min , max ) hbargraph(\"signal\",0,1.0) attach attach(x, vumeter(x)) All numerical parameters (like {\\it cur}, {\\it min}, {\\it max}, {\\it step}) are constant numerical expressions .","title":"User Interface Elements"},{"location":"qreference/3-syntax/#labels","text":"Every user interface widget has a label (a string) that identifies it and informs the user of its purpose. There are three important mechanisms associated with labels (and coded inside the string): variable parts , pathnames and metadata . Variable parts. Labels can contain variable parts. These variable parts are indicated by the sign '%' followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example par(i,8,hslider(\"Voice %i\", 0.9, 0, 1, 0.01)) creates 8 different sliders in parallel : hslider(\"Voice 0\", 0.9, 0, 1, 0.01), hslider(\"Voice 1\", 0.9, 0, 1, 0.01), ... hslider(\"Voice 7\", 0.9, 0, 1, 0.01). while par(i,8,hslider(\"Voice\", 0.9, 0, 1, 0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Pathnames. Thanks to horizontal, vertical and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated pathname obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of: hslider(\"../volume\",...) would have been \"/h:Foo/volume\" , while the pathname of: hslider(\"t:Fii/volume\",...) would have been: \"/h:Foo/v:Faa/t:Fii/volume\" . The grammar for labels with pathnames is the following: label ComplexDiagram( Sequence (NonTerminal('path'), NonTerminal('name')) ).addTo() path ComplexDiagram( Sequence (Optional ( '/'), Optional ( OneOrMore (Sequence (NonTerminal('folder'), '/')))) ).addTo() folder ComplexDiagram( Choice (0, \"..\", Sequence (Choice (0, \"h:\", \"v:\", \"t:\"), NonTerminal('name'))) ).addTo() Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface. The Faust code: process = *(hslider(\"foo [key1: val 1][key2: val 2]\", 0, 0, 1, 0.1)); will produce and the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* interface) { interface->openVerticalBox(\"m\"); interface->declare(&fslider0, \"key1\", \"val 1\"); interface->declare(&fslider0, \"key2\", \"val 2\"); interface->addHorizontalSlider(\"foo\", &fslider0, 0.0f, 0.0f, 1.0f, 0.1f); interface->closeBox(); } ... }; All the metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. It is the role of the architecture file to decide what to do with these metadata. The jack-qt.cpp architecture file for example implements the following: - \"...[style:knob]...\" creates a rotating knob instead of a regular slider or nentry. - \"...[style:led]...\" in a bargraph's label creates a small LED instead of a full bargraph - \"...[unit:dB]...\" in a bargraph's label creates a more realistic bargraph with colors ranging from green to red depending of the level of the value - \"...[unit:xx]...\" in a widget postfixes the value displayed with xx - \"...[tooltip:bla bla]...\" add a tooltip to the widget - \"...[osc:/address min max]...\" Open Sound Control message alias Moreover starting a label with a number option like in \"[1]...\" provides a convenient means to control the alphabetical order of the widgets.","title":"Labels"},{"location":"qreference/3-syntax/#attach","text":"The attach primitive takes two input signals and produce one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical point of view attach(x,y) is equivalent to 1 x+0 y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role let say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelop detector connected to a bargraph. The problem is that these envelop signals have no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled.","title":"Attach"},{"location":"qreference/3-syntax/#widget-modulation","text":"Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: modulation Here is a very simple example of widget modulation, assuming freeverb is a fully functional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb]","title":"Widget Modulation"},{"location":"qreference/3-syntax/#target-widgets","text":"Target widgets are specified by their label. Of course, this presupposes knowing the names of the widgets. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb]","title":"Target Widgets"},{"location":"qreference/3-syntax/#modulators","text":"Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: Please note that the `':'` sign used here is just a visual separator, it is not the sequential composition operator. [\"Wet\": * -> freeverb] To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the target widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs.","title":"Modulators"},{"location":"qreference/4-compiler/","text":"Invoking the Faust compiler The Faust compiler is invoked using the faust command. It translate Faust programs into C++ code. The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. compiler ComplexDiagram( Sequence (\"faust\", NonTerminal('options'), OneOrMore (NonTerminal('file'))) ).addTo() For example faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to choose the output file: faust noise.dsp -o noise.cpp . The option -a allows to choose the architecture file: faust -a alsa-gtk.cpp noise.dsp . To compile a Faust program into an ALSA application on Linux you can use the following commands: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Structure of the generated code A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0 // This method can be called to retrieve // the UI description of the Faust program // and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Here is the class generated with the command faust noise.dsp . Methods are filled by the compiler with the actual code. Several fine-grained initialization methods are available. The instanceInit method calls several additional initialization methods. The instanceConstants method sets the instance constant state. The instanceClear method resets the instance dynamic state (delay lines...). The instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The classInit static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once. Finally the init method combines class static state and instance initialization. When using a single instance, then calling init is the simplest way to do what is needed. When using several instances, then all of them can be initialized using instanceInit , whith a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSampleRate; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; Compilation options Compilation options are listed in the following table : \\small \\tablefirsthead{ Short & Long & Description \\tablehead{ Short & Long & Description \\tabletail{ \\multicolumn{3}{|r|}{\\small\\sl continued on next page} \\tablelasttail{ -h & --help & print the help message -v & --version & print version information -d & --details & print compilation details -tg & --task-graph & draw a graph of all internal computation loops as a .dot (graphviz) file. -sg & --signal-graph & draw a graph of all internal signal expressions as a .dot (graphviz) file. -ps & --postscript & generate block-diagram postscript files -svg & --svg & generate block-diagram svg files -blur & --shadow-blur & add a blur to boxes shadows -sd & --simplify-diagrams & simplify block-diagram before drawing them -f n & --fold n & max complexity of svg diagrams before splitting into several files (default 25 boxes) -mns n & --max-name-size n & max character size used in svg diagram labels -sn & --simple-names & use simple names (without arguments) for block-diagram (default max size : 40 chars) -xml & --xml & generate an additional description file in xml format -uim & --user-interface-macros & add user interface macro definitions to the C++ code -flist & --file-list & list all the source files and libraries implied in a compilation -norm & --normalized-form & prints the internal signals in normalized form and exits -lb & --left-balanced & generate left-balanced expressions -mb & --mid-balanced & generate mid-balanced expressions (default) -rb & --right-balanced & generate right-balanced expressions -lt & --less-temporaries & generate less temporaries in compiling delays -mcd n & --max-copy-delay n & threshold between copy and ring buffer delays (default 16 samples) -vec & --vectorize & generate easier to vectorize code -vs n & --vec-size n & size of the vector (default 32 samples) when -vec -lv n & --loop-variant n & loop variant [0:fastest (default), 1:simple] when -vec -dfs & --deepFirstScheduling & schedule vector loops in deep first order when -vec -omp & --openMP & generate parallel code using OpenMP (implies -vec) -sch & --scheduler & generate parallel code using threads directly (implies -vec) -g & --groupTasks & group sequential tasks together when -omp or -sch is used -single & --single-precision-floats & use floats for internal computations (default) -double & --double-precision-floats & use doubles for internal computations -quad & --quad-precision-floats & use extended for internal computations -mdoc & --mathdoc & generates the full mathematical description of a Faust program -mdlang l & --mathdoc-lang l & choose the language of the mathematical description ( l = en, fr, ...) -stripmdoc & --strip-mdoc-tags & remove documentation tags when printing Faust listings -cn name & --class-name name & name of the dsp class to be used instead of 'mydsp' -t time & --timeout time & time out of time seconds (default 600) for the compiler to abort -a file & & architecture file to use -o file & & C++ output file","title":"4 compiler"},{"location":"qreference/4-compiler/#invoking-the-faust-compiler","text":"The Faust compiler is invoked using the faust command. It translate Faust programs into C++ code. The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. compiler ComplexDiagram( Sequence (\"faust\", NonTerminal('options'), OneOrMore (NonTerminal('file'))) ).addTo() For example faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to choose the output file: faust noise.dsp -o noise.cpp . The option -a allows to choose the architecture file: faust -a alsa-gtk.cpp noise.dsp . To compile a Faust program into an ALSA application on Linux you can use the following commands: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise","title":"Invoking the Faust compiler"},{"location":"qreference/4-compiler/#structure-of-the-generated-code","text":"A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0 // This method can be called to retrieve // the UI description of the Faust program // and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Here is the class generated with the command faust noise.dsp . Methods are filled by the compiler with the actual code. Several fine-grained initialization methods are available. The instanceInit method calls several additional initialization methods. The instanceConstants method sets the instance constant state. The instanceClear method resets the instance dynamic state (delay lines...). The instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The classInit static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once. Finally the init method combines class static state and instance initialization. When using a single instance, then calling init is the simplest way to do what is needed. When using several instances, then all of them can be initialized using instanceInit , whith a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSampleRate; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } };","title":"Structure of the generated code"},{"location":"qreference/4-compiler/#compilation-options","text":"Compilation options are listed in the following table : \\small \\tablefirsthead{ Short & Long & Description \\tablehead{ Short & Long & Description \\tabletail{ \\multicolumn{3}{|r|}{\\small\\sl continued on next page} \\tablelasttail{ -h & --help & print the help message -v & --version & print version information -d & --details & print compilation details -tg & --task-graph & draw a graph of all internal computation loops as a .dot (graphviz) file. -sg & --signal-graph & draw a graph of all internal signal expressions as a .dot (graphviz) file. -ps & --postscript & generate block-diagram postscript files -svg & --svg & generate block-diagram svg files -blur & --shadow-blur & add a blur to boxes shadows -sd & --simplify-diagrams & simplify block-diagram before drawing them -f n & --fold n & max complexity of svg diagrams before splitting into several files (default 25 boxes) -mns n & --max-name-size n & max character size used in svg diagram labels -sn & --simple-names & use simple names (without arguments) for block-diagram (default max size : 40 chars) -xml & --xml & generate an additional description file in xml format -uim & --user-interface-macros & add user interface macro definitions to the C++ code -flist & --file-list & list all the source files and libraries implied in a compilation -norm & --normalized-form & prints the internal signals in normalized form and exits -lb & --left-balanced & generate left-balanced expressions -mb & --mid-balanced & generate mid-balanced expressions (default) -rb & --right-balanced & generate right-balanced expressions -lt & --less-temporaries & generate less temporaries in compiling delays -mcd n & --max-copy-delay n & threshold between copy and ring buffer delays (default 16 samples) -vec & --vectorize & generate easier to vectorize code -vs n & --vec-size n & size of the vector (default 32 samples) when -vec -lv n & --loop-variant n & loop variant [0:fastest (default), 1:simple] when -vec -dfs & --deepFirstScheduling & schedule vector loops in deep first order when -vec -omp & --openMP & generate parallel code using OpenMP (implies -vec) -sch & --scheduler & generate parallel code using threads directly (implies -vec) -g & --groupTasks & group sequential tasks together when -omp or -sch is used -single & --single-precision-floats & use floats for internal computations (default) -double & --double-precision-floats & use doubles for internal computations -quad & --quad-precision-floats & use extended for internal computations -mdoc & --mathdoc & generates the full mathematical description of a Faust program -mdlang l & --mathdoc-lang l & choose the language of the mathematical description ( l = en, fr, ...) -stripmdoc & --strip-mdoc-tags & remove documentation tags when printing Faust listings -cn name & --class-name name & name of the dsp class to be used instead of 'mydsp' -t time & --timeout time & time out of time seconds (default 600) for the compiler to abort -a file & & architecture file to use -o file & & C++ output file","title":"Compilation options"},{"location":"qreference/5-libfaust/","text":"Embedding the Faust compiler using libfaust The dynamic compilation chain allows developers to embed the Faust compiler technology directly in their application or plugins. Thanks to the awesome LLVM technology combined with libfaust, the library version of the Faust compiler, Faust DSP programs can directly be compiled and executed on the fly at full speed. Dynamic compilation chain The Faust compiler uses an intermediate FIR representation ( Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures (for and while loops, if structure etc.). To generate various output languages, several backends have been developed: for C, C++, Java, JavaScript, asm.js, and LLVM IR. The native LLVM based compilation chain is particularly interesting: it provides direct compilation of a DSP source into executable code in memory, bypassing the external compiler requirement. LLVM LLVM (formerly Low Level Virtual Machine) is a compiler infrastructure, designed for compile-time, link-time, run-time optimization of programs written in arbitrary programming languages. Executable code is produced dynamically using a {\\it Just In Time} compiler from a specific code representation, called LLVM IR. Clang, the LLVM native C/C++/Objective- C compiler is a front-end for LLVM Compiler. It can, for instance, convert a C or C++ source file into LLVM IR code. Domain-specific languages like Faust can easily target the LLVM IR. This has been done by developing an LLVM IR backend in the Faust compiler. Compiling in memory The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. The Faust compiler has been packaged as an embeddable library called libfaust, published with an associated API that imitates the concept of oriented-object languages, like C++. Given a Faust source code (as a file or a string), calling the createDSPFactoryXXX function runs the compilation chain ( Faust + LLVM JIT) and generates the {\\it prototype} of the class, as a llvm_dsp_factory pointer. class llvm_dsp_factory { public: /* Return Factory name */ std::string getName(); /* Return Factory LLVM target */ std::string getTarget(); /* Return Factory SHA key */ std::string getSHAKey(); /* Return Factory expanded DSP code */ std::string getDSPCode(); /* Create a new DSP instance, to be deleted with C++ 'delete' */ llvm_dsp* createDSPInstance(); /* Set a custom memory manager to be used when creating instances */ void setMemoryManager(dsp_memory_manager* manager); /* Return the currently set custom memory manager */ dsp_memory_manager* getMemoryManager(); }; Note that the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code, that is same source code and same set of {\\it normalized} (= sorted in a canonical order) compilations options, will return the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly decrement the reference counter when the factory is no more needed. You can get a unique SHA1 key of the created factory using its getSHAKey method. Next, the createDSPInstance function, corresponding to the new className of C++, instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, use delete to destroy the dsp instance. class llvm_dsp : public dsp { public: int getNumInputs(); int getNumOutputs(); void buildUserInterface(UI* ui_interface); int getSampleRate(); void init(int sample_rate); void instanceInit(int sample_rate); void instanceConstants(int sample_rate); void instanceResetUserInterface(); void instanceClear(); llvm_dsp* clone(); void metadata(Meta* m); void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs); }; Since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all already available audio and UI classes, in essence reusing all architecture files already developed for the static C++ class compilation scheme (like OSCUI, httpdUI interfaces etc.), look at Developing a new architecture file section. Saving/restoring the factory After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR allows to get the DSP factory LLVM IR (in textual format) as a string, writeDSPFactoryToIRFile allows to save the DSP factory LLVM IR (in textual format) in a file, writeDSPFactoryToBitcode allows to get the DSP factory LLVM IR (in binary format) as a string, writeDSPFactoryToBitcodeFile allows to save the DSP factory LLVM IR (in binary format) in a file, writeDSPFactoryToMachine allows to get the DSP factory executable machine code as a string, writeDSPFactoryToMachineFile allows to save the DSP factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR allows to create a DSP factory from a string containing the LLVM IR (in textual format), readDSPFactoryFromIRFile allows to create a DSP factory from a file containing the LLVM IR (in textual format), readDSPFactoryFromBitcode allows to create a DSP factory from a string containing the LLVM IR (in binary format), readDSPFactoryFromBitcodeFile allows to create a DSP factory from a file containing the LLVM IR (in binary format), readDSPFactoryFromMachine allows to create a DSP factory from a string containing the executable machine code, readDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the executable machine code. Additional functions Some additional functions are available in the libfaust API: expandDSPFromString/expandDSPFromFile creates a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string, generateAuxFilesFromString/generateAuxFilesFromFile : from a DSP source string or file, generates auxiliary files: SVG, XML, ps... depending of the argv parameters. Using the libfaust library The libfaust library is part of the Faust tree. You'll have to compile and install it. Then look at the installed faust/dsp/llvm-dsp.h header for a complete description of the API. Note that faust/dsp/llvm-c-dsp.h is a pure C version of the same API. The additional functions are available in the faust/dsp/libfaust.h header and their C version is in faust/dsp/libfaust-c.h . Use case examples The dynamic compilation chain has been used in several projects: FaustLive, an integrated IDE for Faust development Faustgen, an external object for Cycling Max/MSP language Csound6, see this demo video LibAudioStream, a framework to manipulate audio ressources through the concept of streams Oliver Larkin JUCE framework integration and pMix2 project an experimental version of Antescofo FaucK: the combination of the Chuck language and Faust","title":"5 libfaust"},{"location":"qreference/5-libfaust/#embedding-the-faust-compiler-using-libfaust","text":"The dynamic compilation chain allows developers to embed the Faust compiler technology directly in their application or plugins. Thanks to the awesome LLVM technology combined with libfaust, the library version of the Faust compiler, Faust DSP programs can directly be compiled and executed on the fly at full speed.","title":"Embedding the Faust  compiler using libfaust"},{"location":"qreference/5-libfaust/#dynamic-compilation-chain","text":"The Faust compiler uses an intermediate FIR representation ( Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures (for and while loops, if structure etc.). To generate various output languages, several backends have been developed: for C, C++, Java, JavaScript, asm.js, and LLVM IR. The native LLVM based compilation chain is particularly interesting: it provides direct compilation of a DSP source into executable code in memory, bypassing the external compiler requirement.","title":"Dynamic compilation chain"},{"location":"qreference/5-libfaust/#llvm","text":"LLVM (formerly Low Level Virtual Machine) is a compiler infrastructure, designed for compile-time, link-time, run-time optimization of programs written in arbitrary programming languages. Executable code is produced dynamically using a {\\it Just In Time} compiler from a specific code representation, called LLVM IR. Clang, the LLVM native C/C++/Objective- C compiler is a front-end for LLVM Compiler. It can, for instance, convert a C or C++ source file into LLVM IR code. Domain-specific languages like Faust can easily target the LLVM IR. This has been done by developing an LLVM IR backend in the Faust compiler.","title":"LLVM"},{"location":"qreference/5-libfaust/#compiling-in-memory","text":"The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. The Faust compiler has been packaged as an embeddable library called libfaust, published with an associated API that imitates the concept of oriented-object languages, like C++. Given a Faust source code (as a file or a string), calling the createDSPFactoryXXX function runs the compilation chain ( Faust + LLVM JIT) and generates the {\\it prototype} of the class, as a llvm_dsp_factory pointer. class llvm_dsp_factory { public: /* Return Factory name */ std::string getName(); /* Return Factory LLVM target */ std::string getTarget(); /* Return Factory SHA key */ std::string getSHAKey(); /* Return Factory expanded DSP code */ std::string getDSPCode(); /* Create a new DSP instance, to be deleted with C++ 'delete' */ llvm_dsp* createDSPInstance(); /* Set a custom memory manager to be used when creating instances */ void setMemoryManager(dsp_memory_manager* manager); /* Return the currently set custom memory manager */ dsp_memory_manager* getMemoryManager(); }; Note that the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code, that is same source code and same set of {\\it normalized} (= sorted in a canonical order) compilations options, will return the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly decrement the reference counter when the factory is no more needed. You can get a unique SHA1 key of the created factory using its getSHAKey method. Next, the createDSPInstance function, corresponding to the new className of C++, instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, use delete to destroy the dsp instance. class llvm_dsp : public dsp { public: int getNumInputs(); int getNumOutputs(); void buildUserInterface(UI* ui_interface); int getSampleRate(); void init(int sample_rate); void instanceInit(int sample_rate); void instanceConstants(int sample_rate); void instanceResetUserInterface(); void instanceClear(); llvm_dsp* clone(); void metadata(Meta* m); void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs); }; Since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all already available audio and UI classes, in essence reusing all architecture files already developed for the static C++ class compilation scheme (like OSCUI, httpdUI interfaces etc.), look at Developing a new architecture file section.","title":"Compiling in memory"},{"location":"qreference/5-libfaust/#savingrestoring-the-factory","text":"After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR allows to get the DSP factory LLVM IR (in textual format) as a string, writeDSPFactoryToIRFile allows to save the DSP factory LLVM IR (in textual format) in a file, writeDSPFactoryToBitcode allows to get the DSP factory LLVM IR (in binary format) as a string, writeDSPFactoryToBitcodeFile allows to save the DSP factory LLVM IR (in binary format) in a file, writeDSPFactoryToMachine allows to get the DSP factory executable machine code as a string, writeDSPFactoryToMachineFile allows to save the DSP factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR allows to create a DSP factory from a string containing the LLVM IR (in textual format), readDSPFactoryFromIRFile allows to create a DSP factory from a file containing the LLVM IR (in textual format), readDSPFactoryFromBitcode allows to create a DSP factory from a string containing the LLVM IR (in binary format), readDSPFactoryFromBitcodeFile allows to create a DSP factory from a file containing the LLVM IR (in binary format), readDSPFactoryFromMachine allows to create a DSP factory from a string containing the executable machine code, readDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the executable machine code.","title":"Saving/restoring the factory"},{"location":"qreference/5-libfaust/#additional-functions","text":"Some additional functions are available in the libfaust API: expandDSPFromString/expandDSPFromFile creates a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string, generateAuxFilesFromString/generateAuxFilesFromFile : from a DSP source string or file, generates auxiliary files: SVG, XML, ps... depending of the argv parameters.","title":"Additional functions"},{"location":"qreference/5-libfaust/#using-the-libfaust-library","text":"The libfaust library is part of the Faust tree. You'll have to compile and install it. Then look at the installed faust/dsp/llvm-dsp.h header for a complete description of the API. Note that faust/dsp/llvm-c-dsp.h is a pure C version of the same API. The additional functions are available in the faust/dsp/libfaust.h header and their C version is in faust/dsp/libfaust-c.h .","title":"Using the libfaust library"},{"location":"qreference/5-libfaust/#use-case-examples","text":"The dynamic compilation chain has been used in several projects: FaustLive, an integrated IDE for Faust development Faustgen, an external object for Cycling Max/MSP language Csound6, see this demo video LibAudioStream, a framework to manipulate audio ressources through the concept of streams Oliver Larkin JUCE framework integration and pMix2 project an experimental version of Antescofo FaucK: the combination of the Chuck language and Faust","title":"Use case examples"},{"location":"qreference/6-audio/","text":"Architecture files 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 vsti-poly.cpp VSTi polyphonic 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 Some of the available architectures. The main available architecture files are listed table tab:availablearch . 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. 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 { public: audio() {} virtual ~audio() {} virtual bool init(const char*, dsp*) = 0; virtual bool start() = 0; virtual void stop() = 0; virtual void shutdown(shutdown_callback cb, void* arg) {} virtual int getBufferSize() = 0; virtual int getSampleRate() = 0; virtual int getNumInputs() = 0; virtual int getNumOutputs() = 0; virtual float getCPULoad() { return 0.f; } }; 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 tab:aarch gives some of the audio architectures currently available for various operating systems. Audio system Operating system Alsa Linux CoreAudio Mac OS X, iOS JACK Linux, Mac OS X, Windows PortAudio Linux, Mac OS X, Windows OSC 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 Some of Faust audio architectures. 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 tab:ui ). #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif class UI { public: UI() {} virtual ~UI() {} -- 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; -- active widgets virtual void addButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addCheckButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addVerticalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addHorizontalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addNumEntry(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; -- passive widgets virtual void addHorizontalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; virtual void addVerticalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; -- metadata declarations virtual void declare(FAUSTFLOAT*, const char*, const char*) {} }; UI, the root user interface class 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, using the FAUSTFLOAT macro type (defined at compile time as either float or double). The widget currently considered are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values. 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 HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type. 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. UI Comment console a textual command line UI GTKUI a GTK-based GUI QTGUI a multi-platform QT-based GUI FUI a file-based UI to store and recall modules states OSCUI OSC control (see section osc ) httpdUI HTTP control (see section http ) ... ... Some of the available UI architectures. Metadata The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT zone, const char key, const char* value) Here is the table of currently supported general medatada (look at section osc for OSC specific metadata and section midi for MIDI specific metadata): Key Value tooltip actual string content hidden 0 or 1 size actual value unit Hz or dB scale log or exp style knob or led or numerical style radio{\\'label1\\':v1;\\'label2\\':v2... } style menu{\\'label1\\':v1;\\'label2\\':v2... } acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Supported medatada. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\\'white noise\\':0;\\'pink noise\\':1;\\'sine\\':2 ][hidden:0]\", 0, 20, 100, 1)} or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for exemple) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future. Developing a new architecture file Developing a new architecture file typically means writing a generic C++ file, that will be populated with the actual output of the Faust compiler, in order to produce a complete C++ file, ready to be compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the < > and < > lines that will be looked at by the Faust compiler, and replaced by the generated C++ class. Look at the minimal.cpp example located in the architecture folder: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //------------------------------------------------- // FAUST generated signal processor //------------------------------------------------- <<includeIntrinsic>> <<includeclass>> int main(int argc, char *argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); Calling faust -a minimal.cpp noise.dsp -a noise.cpp will produce a ready to compile noise.cpp file: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //--------------------------------------------------- // FAUST generated signal processor //-------------------------------------------------- #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSamplingFreq; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int samplingFreq) { } virtual void instanceConstants(int samplingFreq) { fSamplingFreq = samplingFreq; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int samplingFreq) { classInit(samplingFreq); instanceInit(samplingFreq); } virtual void instanceInit(int samplingFreq) { instanceConstants(samplingFreq); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSamplingFreq; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"acc\", \"0 0 -10 0 10\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); You can possibly add the -i option to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with \"faust\"). Then you will have to write a faust2xxx script that will chain the Faust compilation step and the C++ compilation one. Look at scripts in the tools/faust2appls folder for real examples. Developing the adapted C++ file may require \"aggregating\" the generated mydsp class (subclass of dsp base class defined in faust/dsp/dsp.h header) in your specific class, or \"subclassing\" and extend it. So you will have to write something like: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific fDSP.compute(count, inputs, outputs); } // Do something specific }; or: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific compute(count, inputs, outputs); } // Do something specific }; This way your architecture file will be adapted to any \"shape\" of the generated code. That is, depending if you generate purely scalar, or vector code (using the -vec option), or any other option, the generated mydsp class will always be correctly inserted in the final C++ file. Look for instance at csound.cpp and unity.cpp architecture files in the architecture folder for real examples.","title":"6 audio"},{"location":"qreference/6-audio/#architecture-files","text":"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 vsti-poly.cpp VSTi polyphonic 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 Some of the available architectures. The main available architecture files are listed table tab:availablearch . 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.","title":"Architecture files"},{"location":"qreference/6-audio/#audio-architecture-modules","text":"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 { public: audio() {} virtual ~audio() {} virtual bool init(const char*, dsp*) = 0; virtual bool start() = 0; virtual void stop() = 0; virtual void shutdown(shutdown_callback cb, void* arg) {} virtual int getBufferSize() = 0; virtual int getSampleRate() = 0; virtual int getNumInputs() = 0; virtual int getNumOutputs() = 0; virtual float getCPULoad() { return 0.f; } }; 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 tab:aarch gives some of the audio architectures currently available for various operating systems. Audio system Operating system Alsa Linux CoreAudio Mac OS X, iOS JACK Linux, Mac OS X, Windows PortAudio Linux, Mac OS X, Windows OSC 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 Some of Faust audio architectures.","title":"Audio architecture modules"},{"location":"qreference/6-audio/#ui-architecture-modules","text":"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 tab:ui ). #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif class UI { public: UI() {} virtual ~UI() {} -- 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; -- active widgets virtual void addButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addCheckButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addVerticalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addHorizontalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addNumEntry(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; -- passive widgets virtual void addHorizontalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; virtual void addVerticalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; -- metadata declarations virtual void declare(FAUSTFLOAT*, const char*, const char*) {} }; UI, the root user interface class","title":"UI architecture modules"},{"location":"qreference/6-audio/#active-widgets","text":"Active widgets are graphical elements that control a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double). The widget currently considered are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values.","title":"Active widgets"},{"location":"qreference/6-audio/#passive-widgets","text":"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 HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type.","title":"Passive widgets"},{"location":"qreference/6-audio/#widgets-layout","text":"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. UI Comment console a textual command line UI GTKUI a GTK-based GUI QTGUI a multi-platform QT-based GUI FUI a file-based UI to store and recall modules states OSCUI OSC control (see section osc ) httpdUI HTTP control (see section http ) ... ... Some of the available UI architectures.","title":"Widgets layout"},{"location":"qreference/6-audio/#metadata","text":"The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT zone, const char key, const char* value) Here is the table of currently supported general medatada (look at section osc for OSC specific metadata and section midi for MIDI specific metadata): Key Value tooltip actual string content hidden 0 or 1 size actual value unit Hz or dB scale log or exp style knob or led or numerical style radio{\\'label1\\':v1;\\'label2\\':v2... } style menu{\\'label1\\':v1;\\'label2\\':v2... } acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Supported medatada. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\\'white noise\\':0;\\'pink noise\\':1;\\'sine\\':2 ][hidden:0]\", 0, 20, 100, 1)} or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for exemple) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future.","title":"Metadata"},{"location":"qreference/6-audio/#developing-a-new-architecture-file","text":"Developing a new architecture file typically means writing a generic C++ file, that will be populated with the actual output of the Faust compiler, in order to produce a complete C++ file, ready to be compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the < > and < > lines that will be looked at by the Faust compiler, and replaced by the generated C++ class. Look at the minimal.cpp example located in the architecture folder: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //------------------------------------------------- // FAUST generated signal processor //------------------------------------------------- <<includeIntrinsic>> <<includeclass>> int main(int argc, char *argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); Calling faust -a minimal.cpp noise.dsp -a noise.cpp will produce a ready to compile noise.cpp file: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //--------------------------------------------------- // FAUST generated signal processor //-------------------------------------------------- #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSamplingFreq; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int samplingFreq) { } virtual void instanceConstants(int samplingFreq) { fSamplingFreq = samplingFreq; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int samplingFreq) { classInit(samplingFreq); instanceInit(samplingFreq); } virtual void instanceInit(int samplingFreq) { instanceConstants(samplingFreq); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSamplingFreq; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"acc\", \"0 0 -10 0 10\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); You can possibly add the -i option to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with \"faust\"). Then you will have to write a faust2xxx script that will chain the Faust compilation step and the C++ compilation one. Look at scripts in the tools/faust2appls folder for real examples. Developing the adapted C++ file may require \"aggregating\" the generated mydsp class (subclass of dsp base class defined in faust/dsp/dsp.h header) in your specific class, or \"subclassing\" and extend it. So you will have to write something like: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific fDSP.compute(count, inputs, outputs); } // Do something specific }; or: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific compute(count, inputs, outputs); } // Do something specific }; This way your architecture file will be adapted to any \"shape\" of the generated code. That is, depending if you generate purely scalar, or vector code (using the -vec option), or any other option, the generated mydsp class will always be correctly inserted in the final C++ file. Look for instance at csound.cpp and unity.cpp architecture files in the architecture folder for real examples.","title":"Developing a new architecture file"},{"location":"qreference/7-osc/","text":"OSC support Most Faust architectures provide Open Sound Control (OSC) support \\footnote{The implementation is based internally on the oscpack library by Ross Bencina}. This allows Faust applications to be remotely controlled from any OSC capable application, programming language, or hardware device. OSC support can be activated using the -osc option when building the application with the appropriate faust2xxx command. The following table (table tab:oscarch ) lists Faust 's architectures which provide OSC support. Audio system Environment OSC support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with OSC support. A simple example To illustrate how OSC support works let's define a very simple noise generator with a level control: noise.dsp process = library(\"music.lib\").noise * hslider(\"level\", 0, 0, 1, 0.01); We are going to compile this example as a standalone Jack QT application with OSC support using the command: faust2jaqt -osc noise.dsp When we start the application from the command line: ./noise we get various information on the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 As we can see the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \\\"Foo\\\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host set sthe destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (bargraph) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements (bargraph) are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that 'path' can be a regular expression (like \"/freeverb/Reverb1/*\"). -bundle 0|1 activates the bundle mode where all transmitted values are sent in a single message, to be used together with the -xmit option. For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination. Automatic port allocation In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let's say that we start two applications noise and mixer on the same machine, here is what we get: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and open it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications. Discovering OSC applications The commands oscsend oscsend hostname port address types values : send OpenSound Control message via UDP. types is a string, the letters indicates the type of the following values: i=integer, f=float, s=string,... Send OpenSound Control message via UDP. and oscdump oscdump port : receive OpenSound Control messages via UDP and dump to standard output from the liblo package provide a convenient mean to experiment with OSC control. For the experiment let's use two additional terminals. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . We will indicate by T1$ the command types on terminal T1 and by T2: the messages received on terminal T2. To monitor on terminal T2 the OSC messages received on UDP port 5511 we will use oscdump : T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for FAUST applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512 Discovering the OSC interface of an application Once we have an application we can discover its OSC interface (the set of OSC messages we can use to control it) by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer of the osc messages understood by the application, a full description is available on terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the osc interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is \"127.0.0.1\" , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 . Widget's OSC address Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example mix4.dsp , a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see each widget has a unique OSC address obtained by concatenating the top level group label \"mixer\", with the \"input\" group label and the widget label. Please note that in this operation whites spaces are replaced by underscores and metadata are removed. All addresses must have a common root. This is the case in our example because there is a unique horizontal group \"mixer\" containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000 Controlling the application via OSC We can control any user interface element of the application by sending one of the previously discovered messages. For example to set the noise level of the application to 0.2 we send: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000 Turning transmission ON The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For examples: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS (xmit = 2) mode if you need restricted access to your program: when ALIAS is mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements (bargraph) will only emit on their aliases. Filtering OSC messages When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter the unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter Using OSC aliases Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our noise example with touchOSC on Android. The first step is to configure TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510. Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of simple layout. Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: \\marginpar{ Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages. process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because here the range of /1/fader1 is 0 to 1 like the level slider we can remove the range mapping information and write simply : process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1]\", 0, 0, 1, 0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer. Using again oscdump 5510 we can visualize the messages send by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see TouchOSC send the x, y and z accelerometers in a single message, as a triplet of values ranging approximatively from -9.81 to 9.81 . In order to select the appropriate accelerometer we need to concatenate to /accxyz a suffix /0, /1 or /2. For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: process = library(\"music.lib\").noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer Examples of OSC message aliases for TouchOSC (layout Mix2). OSC cheat sheet Default ports 5510 default listening port 5511 default transmission port 5512 default error port 5513... alternative listening ports Command line options -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time Discovery messages oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port Control messages oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value Alias \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc: address ]...\" alias with min , max clipping DSP with polyphonic support When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used.","title":"7 osc"},{"location":"qreference/7-osc/#osc-support","text":"Most Faust architectures provide Open Sound Control (OSC) support \\footnote{The implementation is based internally on the oscpack library by Ross Bencina}. This allows Faust applications to be remotely controlled from any OSC capable application, programming language, or hardware device. OSC support can be activated using the -osc option when building the application with the appropriate faust2xxx command. The following table (table tab:oscarch ) lists Faust 's architectures which provide OSC support. Audio system Environment OSC support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with OSC support.","title":"OSC support"},{"location":"qreference/7-osc/#a-simple-example","text":"To illustrate how OSC support works let's define a very simple noise generator with a level control: noise.dsp process = library(\"music.lib\").noise * hslider(\"level\", 0, 0, 1, 0.01); We are going to compile this example as a standalone Jack QT application with OSC support using the command: faust2jaqt -osc noise.dsp When we start the application from the command line: ./noise we get various information on the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 As we can see the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \\\"Foo\\\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host set sthe destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (bargraph) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements (bargraph) are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that 'path' can be a regular expression (like \"/freeverb/Reverb1/*\"). -bundle 0|1 activates the bundle mode where all transmitted values are sent in a single message, to be used together with the -xmit option. For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination.","title":"A simple example"},{"location":"qreference/7-osc/#automatic-port-allocation","text":"In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let's say that we start two applications noise and mixer on the same machine, here is what we get: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and open it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications.","title":"Automatic port allocation"},{"location":"qreference/7-osc/#discovering-osc-applications","text":"The commands oscsend oscsend hostname port address types values : send OpenSound Control message via UDP. types is a string, the letters indicates the type of the following values: i=integer, f=float, s=string,... Send OpenSound Control message via UDP. and oscdump oscdump port : receive OpenSound Control messages via UDP and dump to standard output from the liblo package provide a convenient mean to experiment with OSC control. For the experiment let's use two additional terminals. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . We will indicate by T1$ the command types on terminal T1 and by T2: the messages received on terminal T2. To monitor on terminal T2 the OSC messages received on UDP port 5511 we will use oscdump : T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for FAUST applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512","title":"Discovering OSC applications"},{"location":"qreference/7-osc/#discovering-the-osc-interface-of-an-application","text":"Once we have an application we can discover its OSC interface (the set of OSC messages we can use to control it) by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer of the osc messages understood by the application, a full description is available on terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the osc interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is \"127.0.0.1\" , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 .","title":"Discovering the OSC interface of an application"},{"location":"qreference/7-osc/#widgets-osc-address","text":"Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example mix4.dsp , a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see each widget has a unique OSC address obtained by concatenating the top level group label \"mixer\", with the \"input\" group label and the widget label. Please note that in this operation whites spaces are replaced by underscores and metadata are removed. All addresses must have a common root. This is the case in our example because there is a unique horizontal group \"mixer\" containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000","title":"Widget's OSC address"},{"location":"qreference/7-osc/#controlling-the-application-via-osc","text":"We can control any user interface element of the application by sending one of the previously discovered messages. For example to set the noise level of the application to 0.2 we send: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000","title":"Controlling the application via OSC"},{"location":"qreference/7-osc/#turning-transmission-on","text":"The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For examples: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS (xmit = 2) mode if you need restricted access to your program: when ALIAS is mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements (bargraph) will only emit on their aliases.","title":"Turning transmission ON"},{"location":"qreference/7-osc/#filtering-osc-messages","text":"When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter the unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter","title":"Filtering OSC messages"},{"location":"qreference/7-osc/#using-osc-aliases","text":"Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our noise example with touchOSC on Android. The first step is to configure TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510. Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of simple layout. Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: \\marginpar{ Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages. process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because here the range of /1/fader1 is 0 to 1 like the level slider we can remove the range mapping information and write simply : process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1]\", 0, 0, 1, 0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer. Using again oscdump 5510 we can visualize the messages send by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see TouchOSC send the x, y and z accelerometers in a single message, as a triplet of values ranging approximatively from -9.81 to 9.81 . In order to select the appropriate accelerometer we need to concatenate to /accxyz a suffix /0, /1 or /2. For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: process = library(\"music.lib\").noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer Examples of OSC message aliases for TouchOSC (layout Mix2).","title":"Using OSC aliases"},{"location":"qreference/7-osc/#osc-cheat-sheet","text":"","title":"OSC cheat sheet"},{"location":"qreference/7-osc/#default-ports","text":"5510 default listening port 5511 default transmission port 5512 default error port 5513... alternative listening ports","title":"Default ports"},{"location":"qreference/7-osc/#command-line-options","text":"-port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time","title":"Command line options"},{"location":"qreference/7-osc/#discovery-messages","text":"oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port","title":"Discovery messages"},{"location":"qreference/7-osc/#control-messages","text":"oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value","title":"Control messages"},{"location":"qreference/7-osc/#alias","text":"\"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc: address ]...\" alias with min , max clipping","title":"Alias"},{"location":"qreference/7-osc/#dsp-with-polyphonic-support","text":"When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used.","title":"DSP with polyphonic support"},{"location":"qreference/8-http/","text":"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 HTTPD can be freely combined. While OSC support is installed by default when Faust is build, this is not the case for HTTP. That's because it depends on 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. The HTTP support can be activated using the -httpd option when building the audio application with the appropriate faust2xxx command. The following table (table tab:httparch ) lists Faust 's architectures which provide HTTP support. Audio system Environment HTTP support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with HTTP support. A simple example To illustrate how HTTP support works let's reuse our previous mix4.dsp example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); We are going to compile this example as a standalone Jack QT application with HTTP support using the command: faust2jaqt -httpd mix4.dsp Th effect of the -httpd is to embed a small Web server into the application, which purpose is to serve an HTML page representing its user interface. This page makes use of JavaScript and SVG and is quite similar to the native QT interface. When we start the application from the command line: ./mix4 we get various information on the standard output, including: Faust httpd server version 0.72 is running on TCP port 5510 As we can see the embedded Web server is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page reproduced figure fig:mix4-http . User interface of mix4 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 that return 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\" } ] }, ... ] } ] Quering the state of the application Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge an 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 query 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 the 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 Muting input 1 by forging the appropriate URL Let's say that we want to mute input 1 of our mixer. We can use for that purpose the URL http://localhost:5510/mixer/input_1/mute?value=1 obtained by concatenating ?value=1 at the end of the widget URL. All widgets can be controlled similarly. For example http://localhost:5510/mixer/input_3/level?value=0.7 will sets 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 purely be developed in C/C++, then build a proxy version of the use interface, and set and get parameters using HTTP requests. This mode can be started dynamically using the _ -server URL _ parameter. Assuming an application with HTTP support is running remotely on the given URL, the control application will fetch its json description, use it to dynamically build the user interface, and allow to access 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 5510 default TCP port used by the application's Web server 5511... alternative TCP ports Command line options -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 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 \\subsubsection*{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 is either a group (of items) or a widget. \\subsubsection*{Groups} A group is essentially a list of items with a specific layout: { \"type\": <type>, \"label\": <label>, \"items\": [ <item>, <item>,...] The defines the layout. It can be either \"vgroup\" , \"hgroup\" or \"tgroup\" \\subsubsection*{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 : \"button\" , \"checkbox\" , \"nentry\" , \"vslider\" , \"hslider\" , \"vbargraph\" or \"hbargraph\" .","title":"8 http"},{"location":"qreference/8-http/#http-support","text":"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 HTTPD can be freely combined. While OSC support is installed by default when Faust is build, this is not the case for HTTP. That's because it depends on 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. The HTTP support can be activated using the -httpd option when building the audio application with the appropriate faust2xxx command. The following table (table tab:httparch ) lists Faust 's architectures which provide HTTP support. Audio system Environment HTTP support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with HTTP support.","title":"HTTP support"},{"location":"qreference/8-http/#a-simple-example","text":"To illustrate how HTTP support works let's reuse our previous mix4.dsp example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); We are going to compile this example as a standalone Jack QT application with HTTP support using the command: faust2jaqt -httpd mix4.dsp Th effect of the -httpd is to embed a small Web server into the application, which purpose is to serve an HTML page representing its user interface. This page makes use of JavaScript and SVG and is quite similar to the native QT interface. When we start the application from the command line: ./mix4 we get various information on the standard output, including: Faust httpd server version 0.72 is running on TCP port 5510 As we can see the embedded Web server is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page reproduced figure fig:mix4-http . User interface of mix4","title":"A simple example"},{"location":"qreference/8-http/#json-description-of-the-user-interface","text":"The communication between the application and the Web browser is based on several underlying URLs. The first one is http://localhost:5510/JSON that return 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\" } ] }, ... ] } ]","title":"JSON description of the user interface"},{"location":"qreference/8-http/#quering-the-state-of-the-application","text":"Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge an 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 query 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 the 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","title":"Quering the state of the application"},{"location":"qreference/8-http/#changing-the-value-of-a-widget","text":"Muting input 1 by forging the appropriate URL Let's say that we want to mute input 1 of our mixer. We can use for that purpose the URL http://localhost:5510/mixer/input_1/mute?value=1 obtained by concatenating ?value=1 at the end of the widget URL. All widgets can be controlled similarly. For example http://localhost:5510/mixer/input_3/level?value=0.7 will sets the input 3 level to 0.7.","title":"Changing the value of a widget"},{"location":"qreference/8-http/#proxy-control-access-to-the-web-server","text":"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 purely be developed in C/C++, then build a proxy version of the use interface, and set and get parameters using HTTP requests. This mode can be started dynamically using the _ -server URL _ parameter. Assuming an application with HTTP support is running remotely on the given URL, the control application will fetch its json description, use it to dynamically build the user interface, and allow to access the remote parameters.","title":"Proxy control access to the Web server"},{"location":"qreference/8-http/#http-cheat-sheet","text":"Here is a summary of the various URLs used to interact with the application's Web server.","title":"HTTP cheat sheet"},{"location":"qreference/8-http/#default-ports","text":"5510 default TCP port used by the application's Web server 5511... alternative TCP ports","title":"Default ports"},{"location":"qreference/8-http/#command-line-options","text":"-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","title":"Command line options"},{"location":"qreference/8-http/#urls","text":"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","title":"URLs"},{"location":"qreference/8-http/#json","text":"\\subsubsection*{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 is either a group (of items) or a widget. \\subsubsection*{Groups} A group is essentially a list of items with a specific layout: { \"type\": <type>, \"label\": <label>, \"items\": [ <item>, <item>,...] The defines the layout. It can be either \"vgroup\" , \"hgroup\" or \"tgroup\" \\subsubsection*{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 : \"button\" , \"checkbox\" , \"nentry\" , \"vslider\" , \"hslider\" , \"vbargraph\" or \"hbargraph\" .","title":"JSON"},{"location":"qreference/9-midi/","text":"MIDI support Similarly to OSC, several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments. MIDI messages description in the dsp source code MIDI control messages are described as metadata in UI elements. They are decoded by a special architecture MidiUI class that will parse incoming MIDI messages and update the appropriate control parameters, or send MIDI messages when the UI elements (sliders, buttons...) are moved. Description of the possible standard MIDI messages Below, when a 7-bit MIDI parameter is used to drive a button or checkbox, its maximum value 127 maps to 1 (\"on\") while its minimum value 0 maps to 0 (\"off\"). A special [midi:xxx yyy...] metadata needs to be added in the UI element description. The more usual MIDI messages can be used as described here: [midi:ctrl num] in a slider or bargraph will map the UI element value to (0, 127) range. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyon pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyoff pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-off velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:key pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0. Note-on and note-off events will be handled, [midi:keypress pitch] in a slider or bargraph will register the UI element's state-variable to be driven by the MIDI key-pressure (an integer between 0 and 127) from MIDI key, [midi:pgm num] in a slider or bargraph will map the UI element value to the progchange value, so progchange message with the same num value will be sent. When used with a button or checkbox, 1 will send the progchange message with num value, 0 will send nothing, [midi:chanpress num] in a slider or bargraph will map the UI element value to the chanpress value, so chanpress message with the same num value will be sent. When used with a button or checkbox, 1 will send the chanpress message with num value, 0 will send nothing, [midi:pitchwheel] in a slider or bargraph will map the UI element value to (0,16383) range. When used with a button or checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. A simple example An example with a volume slider controlled with MIDI ctrlchange 7 messages : //----------------------------------------------- // Volume MIDI control in dB //----------------------------------------------- import(\"music.lib\"); smooth(c) = *(1-c) : +~*(c); gain = vslider(\"Volume [midi:ctrl 7]\", 0, -70, +4, 0.1) : db2linear : smooth(0.999); process = *(gain); A complete testing example named midi_tester.dsp is available in the Faust distribution examples folder. MIDI messages testing example The MIDI support can be activated using the -midi option when building the audio application with the appropriate faust2xxx command. The following table (table tab:midiarch ) lists Faust 's architectures which provide MIDI support. Audio system Environment HTTP support Linux Alsa Qt yes Jack Qt yes Mac OS X CoreAudio Qt yes Jack Qt yes Faust architectures with HTTP support. MIDI synchronization MIDI clock based synchronization can be used to slave a given Faust program. The following three messages need to be used: [midi:start] in a button or checkbox will trigger a value of 1 when a start MIDI message is received [midi:stop] in a button or checkbox will trigger a value of 0 when a stop MIDI message is received [midi:clock] in a button or checkbox will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received, seen by Faust code as a square command signal, to be used to compute higher level information. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"music.lib\"); // square signal (1/0), changing state at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled with MIDI start/stop messages play = checkbox(\"ON/OFF [midi:start] [midi:stop]\"); // detect front front(x) = (x-x') != 0.0; // count number of peaks during one second freq(x) = (x-x@SR) : + ~ _; process = osc(8*freq(front(clocker))) * play;","title":"9 midi"},{"location":"qreference/9-midi/#midi-support","text":"Similarly to OSC, several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments.","title":"MIDI support"},{"location":"qreference/9-midi/#midi-messages-description-in-the-dsp-source-code","text":"MIDI control messages are described as metadata in UI elements. They are decoded by a special architecture MidiUI class that will parse incoming MIDI messages and update the appropriate control parameters, or send MIDI messages when the UI elements (sliders, buttons...) are moved.","title":"MIDI messages description in the dsp source code"},{"location":"qreference/9-midi/#description-of-the-possible-standard-midi-messages","text":"Below, when a 7-bit MIDI parameter is used to drive a button or checkbox, its maximum value 127 maps to 1 (\"on\") while its minimum value 0 maps to 0 (\"off\"). A special [midi:xxx yyy...] metadata needs to be added in the UI element description. The more usual MIDI messages can be used as described here: [midi:ctrl num] in a slider or bargraph will map the UI element value to (0, 127) range. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyon pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyoff pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-off velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:key pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0. Note-on and note-off events will be handled, [midi:keypress pitch] in a slider or bargraph will register the UI element's state-variable to be driven by the MIDI key-pressure (an integer between 0 and 127) from MIDI key, [midi:pgm num] in a slider or bargraph will map the UI element value to the progchange value, so progchange message with the same num value will be sent. When used with a button or checkbox, 1 will send the progchange message with num value, 0 will send nothing, [midi:chanpress num] in a slider or bargraph will map the UI element value to the chanpress value, so chanpress message with the same num value will be sent. When used with a button or checkbox, 1 will send the chanpress message with num value, 0 will send nothing, [midi:pitchwheel] in a slider or bargraph will map the UI element value to (0,16383) range. When used with a button or checkbox, 1 will be mapped to 16383, 0 will be mapped to 0.","title":"Description of the possible standard MIDI messages"},{"location":"qreference/9-midi/#a-simple-example","text":"An example with a volume slider controlled with MIDI ctrlchange 7 messages : //----------------------------------------------- // Volume MIDI control in dB //----------------------------------------------- import(\"music.lib\"); smooth(c) = *(1-c) : +~*(c); gain = vslider(\"Volume [midi:ctrl 7]\", 0, -70, +4, 0.1) : db2linear : smooth(0.999); process = *(gain); A complete testing example named midi_tester.dsp is available in the Faust distribution examples folder. MIDI messages testing example The MIDI support can be activated using the -midi option when building the audio application with the appropriate faust2xxx command. The following table (table tab:midiarch ) lists Faust 's architectures which provide MIDI support. Audio system Environment HTTP support Linux Alsa Qt yes Jack Qt yes Mac OS X CoreAudio Qt yes Jack Qt yes Faust architectures with HTTP support.","title":"A simple example"},{"location":"qreference/9-midi/#midi-synchronization","text":"MIDI clock based synchronization can be used to slave a given Faust program. The following three messages need to be used: [midi:start] in a button or checkbox will trigger a value of 1 when a start MIDI message is received [midi:stop] in a button or checkbox will trigger a value of 0 when a stop MIDI message is received [midi:clock] in a button or checkbox will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received, seen by Faust code as a square command signal, to be used to compute higher level information. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"music.lib\"); // square signal (1/0), changing state at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled with MIDI start/stop messages play = checkbox(\"ON/OFF [midi:start] [midi:stop]\"); // detect front front(x) = (x-x') != 0.0; // count number of peaks during one second freq(x) = (x-x@SR) : + ~ _; process = osc(8*freq(front(clocker))) * play;","title":"MIDI synchronization"},{"location":"tutorials/basic-osc/","text":"Making a Sine Oscillator From Scratch and Additive Synthesis Goals Implementing a sine oscillator from scratch in Faust Understand the relation between the sine function and the generated sound Use multiple sine oscillator to implement an additive synthesizer Use SmartKeyboard to produce polyphonic mobile apps to control this synth Sine Function in Faust The sine function in Faust works like on a calculator: will output 0 . To verify this, you could click on the truck (export function) in the Faust Online IDE and then choose misc/csv to get a table containing the first n samples output by the program. will output 1 . Note that stdfaust.lib is imported here in order to use ma.pi . will output 0 . Implementing a Phasor What is needed to \"print\" a full sine wave? -> We need to create a series of numbers (vector) going from 0 to 2pi, in other words, draw a line. First let's create a \"counter\" in Faust: Don't forget that you can always print the output of a Faust program by using the in the Faust Online IDE misc/csv The current counter counts one by one. Instead we'd like to count slower 0.01 by 0.01. Now, we want to reset the counter back to 0 when it reaches 1. This can be done easily using the ma.frac function: Note the use of ma.frac in the loop here to prevent numerical errors. Try to run the program (play button in the editor) and it should make sound! What are we generating here? -> A sawtooth wave . How do we change the pitch of the sawtooth wave? -> We should increment the counter faster or slower. Try different values (e.g., 0.001, 0.1, etc.). Instead of controlling the increment of the counter, we'd like to control the frequency of the sawtooth wave. To do that, we need to know the number of values of the wave processed by the computer in one second. That's what we call the sampling rate . This value changes in function of the context of the program so it can be retrieved with ma.SR . A sampling rate of 44100 corresponds to a frequency of 44100 Hz. If we want a frequency of 440, what increment do we need to put in our counter? -> freq/ma.SR In the end, we get: A this point feel free to plot the output of the Faust program using misc/csv in the export function of the online editor. The freq parameter can be controlled dynamically: The code can be cleaned up by placing our phasor in a function: Generating a Sine Wave Almost there! Now we want our phasor to go from 0 to 2pi so that we can plug it to the sin function: Note that we created an osc function in order to have a cleaner code. Additive Synthesis A sine wave generates what we call a pure tone . More complex sounds can be produced by adding multiple sine waves together to create harmonics . The frequency and the gain of each harmonic will determine the timbre of the sound . Using this technique, it is possible to \"sculpt\" a sound. A simple organ synthesizer can be implemented using additive synthesis: This is what we call a harmonic series . Making a Synthesizer In order to use this synthesizer with a keyboard, we need to be able to turn the sound on and off and also to control its volume: An envelope could be added to make it sound more natural: This synth can be controlled with a MIDI keyboard. Turn it Into an Android App Use the export function of the Faust editor and choose android/smartkeyb install the app on the phone and have fun! This could also be turned into an app always making sound and controllable with accelerometers: import(\"stdfaust.lib\"); f = hslider(\"freq[acc: 0 0 -10 0 10]\",1000,50,2000,0.01) : si.smoo; phasor(freq) = (+(freq/ma.SR) ~ ma.frac); osc(freq) = sin(phasor(freq)*2*ma.PI); organ(freq) = (osc(freq) + osc(freq*2) + osc(freq*3))/3; process = organ(f); In that case, export with android/android .","title":"Making a Sine Oscillator From Scratch"},{"location":"tutorials/basic-osc/#making-a-sine-oscillator-from-scratch-and-additive-synthesis","text":"","title":"Making a Sine Oscillator From Scratch and Additive Synthesis"},{"location":"tutorials/basic-osc/#goals","text":"Implementing a sine oscillator from scratch in Faust Understand the relation between the sine function and the generated sound Use multiple sine oscillator to implement an additive synthesizer Use SmartKeyboard to produce polyphonic mobile apps to control this synth","title":"Goals"},{"location":"tutorials/basic-osc/#sine-function-in-faust","text":"The sine function in Faust works like on a calculator: will output 0 . To verify this, you could click on the truck (export function) in the Faust Online IDE and then choose misc/csv to get a table containing the first n samples output by the program. will output 1 . Note that stdfaust.lib is imported here in order to use ma.pi . will output 0 .","title":"Sine Function in Faust"},{"location":"tutorials/basic-osc/#implementing-a-phasor","text":"What is needed to \"print\" a full sine wave? -> We need to create a series of numbers (vector) going from 0 to 2pi, in other words, draw a line. First let's create a \"counter\" in Faust: Don't forget that you can always print the output of a Faust program by using the in the Faust Online IDE misc/csv The current counter counts one by one. Instead we'd like to count slower 0.01 by 0.01. Now, we want to reset the counter back to 0 when it reaches 1. This can be done easily using the ma.frac function: Note the use of ma.frac in the loop here to prevent numerical errors. Try to run the program (play button in the editor) and it should make sound! What are we generating here? -> A sawtooth wave . How do we change the pitch of the sawtooth wave? -> We should increment the counter faster or slower. Try different values (e.g., 0.001, 0.1, etc.). Instead of controlling the increment of the counter, we'd like to control the frequency of the sawtooth wave. To do that, we need to know the number of values of the wave processed by the computer in one second. That's what we call the sampling rate . This value changes in function of the context of the program so it can be retrieved with ma.SR . A sampling rate of 44100 corresponds to a frequency of 44100 Hz. If we want a frequency of 440, what increment do we need to put in our counter? -> freq/ma.SR In the end, we get: A this point feel free to plot the output of the Faust program using misc/csv in the export function of the online editor. The freq parameter can be controlled dynamically: The code can be cleaned up by placing our phasor in a function:","title":"Implementing a Phasor"},{"location":"tutorials/basic-osc/#generating-a-sine-wave","text":"Almost there! Now we want our phasor to go from 0 to 2pi so that we can plug it to the sin function: Note that we created an osc function in order to have a cleaner code.","title":"Generating a Sine Wave"},{"location":"tutorials/basic-osc/#additive-synthesis","text":"A sine wave generates what we call a pure tone . More complex sounds can be produced by adding multiple sine waves together to create harmonics . The frequency and the gain of each harmonic will determine the timbre of the sound . Using this technique, it is possible to \"sculpt\" a sound. A simple organ synthesizer can be implemented using additive synthesis: This is what we call a harmonic series .","title":"Additive Synthesis"},{"location":"tutorials/basic-osc/#making-a-synthesizer","text":"In order to use this synthesizer with a keyboard, we need to be able to turn the sound on and off and also to control its volume: An envelope could be added to make it sound more natural: This synth can be controlled with a MIDI keyboard.","title":"Making a Synthesizer"},{"location":"tutorials/basic-osc/#turn-it-into-an-android-app","text":"Use the export function of the Faust editor and choose android/smartkeyb install the app on the phone and have fun! This could also be turned into an app always making sound and controllable with accelerometers: import(\"stdfaust.lib\"); f = hslider(\"freq[acc: 0 0 -10 0 10]\",1000,50,2000,0.01) : si.smoo; phasor(freq) = (+(freq/ma.SR) ~ ma.frac); osc(freq) = sin(phasor(freq)*2*ma.PI); organ(freq) = (osc(freq) + osc(freq*2) + osc(freq*3))/3; process = organ(f); In that case, export with android/android .","title":"Turn it Into an Android App"},{"location":"tutorials/box-api/","text":"Using the box API The box API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the box API, and take profit of part of the Faust compiler infrastructure. Faust compiler structure The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated into a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends. Accessing the box stage A new intermediate public entry point has been created in the Semantic Phase , after the Evaluation, lambda-calculus step to allow the creation of a box expression, then beneficiate of all remaining parts of the compilation chain. The box API (or the C box API version) allows to programmatically create the box expression, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the signal API allows to access another stage in the compilation stage. Compiling box expressions To use the box API, the following steps must be taken: creating a global compilation context using the createLibContext function creating a box expression using the box API, progressively building more complex expressions by combining simpler ones compiling the box expression using the createCPPDSPFactoryFromBoxes function to create a DSP factory (or createDSPFactoryFromBoxes to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromBoxes to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used. Tools Let's first define a compile function, which uses the createCPPDSPFactoryFromBoxes function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\ Examples For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps). All presented C++ examples (as well as some more) are defined in the box-tester tool, to be compiled with make box-tester in the tools/benchmark folder. Expression generating constant signals Let's create a program generating a parallel construction of 7 and 3.14 constant values. Here is the Faust DSP code: The following code creates a box expression, containing a box boxPar(boxInt(7), boxReal(3.14)) expression, then compile it and display the C++ class: static void test1() { COMPILER ( Box box = boxPar(boxInt(7), boxReal(3.14)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(7); output1[i0] = FAUSTFLOAT(3.1400001f); } } Doing some mathematical operations on an input signal Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with boxWire() expression, then transformed using the boxAdd and boxSeq operators to produce one output: static void test2() { COMPILER ( Box box = boxSeq(boxPar(boxWire(), boxReal(3.14)), boxAdd()); compile(\"test2\", box); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((float(input0[i0]) + 3.1400001f)); } } In the published API, most operators are exported as simple no-argument operators, using the language core-syntax . The prefix notation has been added for each relevant operator, and can be used with additional multi-argument versions. So the previous example can be written in a simpler way with the following code, which will produce the exact same C++: static void test3() { COMPILER ( Box box = boxAdd(boxWire(), boxReal(3.14)); compile(\"test3\", box); ) } Defining a delay expression Here is a simple program delaying the first input: The prefix-notation boxDelay(x, y) operator is used to delay the boxWire() first parameter with the second boxInt(7) : static void test6() { COMPILER ( Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test3\", test6); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(fVec0[7]); for (int j0 = 7; (j0 > 0); j0 = (j0 - 1)) { fVec0[j0] = fVec0[(j0 - 1)]; } } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code shows how to compile in vector mode: static void test7() { createLibContext(); Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test7\", box, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; float fYec0_tmp[40]; float* fYec0 = &fYec0_tmp[8]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 8); j0 = (j0 + 1)) { fYec0_tmp[j0] = fYec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[i] = float(input0[i]); } /* Post code */ for (int j1 = 0; (j1 < 8); j1 = (j1 + 1)) { fYec0_perm[j1] = fYec0_tmp[(vsize + j1)]; } /* Vectorizable loop 1 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec0[(i - 7)]); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test8() { COMPILER ( Box box = boxSplit(boxWire(), boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxMul(boxDelay(boxWire(), boxReal(3000)), boxReal(1.5)))); compile(\"test8\", box); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Equivalent box expressions It is really important to note that syntactically equivalent box expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( Box b1 = boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)); Box box = boxPar(b1, b1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( Box box = boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5))); compile(\"equivalent2\", box); ) } It can be a property to remember when creating a DSL on top of the box API. Using User Interface items User Interface items can be used, as in the following example, with a hslider : Built with the following code: static void test8() { COMPILER ( Box box = boxMul(boxWire(), boxHSlider(\"Freq [midi:ctrl 7][style:knob]\", boxReal(100), boxReal(100), boxReal(2000), boxReal(1))); compile(\"test8\", box); ) } The buildUserInterface method is generated, using the fHslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->declare(&fHslider0, \"midi\", \"ctrl 7\"); ui_interface->declare(&fHslider0, \"style\", \"knob\"); ui_interface->addHorizontalSlider(\"Freq\", &fHslider0, FAUSTFLOAT(100.0f), FAUSTFLOAT(100.0f), FAUSTFLOAT(2000.0f), FAUSTFLOAT(1.0f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((fSlow0 * float(input0[i0]))); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the box API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( Box box = boxMul(boxVSlider(\"h:Oscillator/freq\", boxReal(440), boxReal(50), boxReal(1000), boxReal(0.1)), boxVSlider(\"h:Oscillator/gain\", boxReal(0), boxReal(0), boxReal(1), boxReal(0.01))); compile(\"test9\", box); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); } Defining recursive signals Recursive signals can be defined using the boxRec expression. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( Box box = boxRec(boxAdd(), boxWire()); compile(\"test10\", box); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Accessing the global context In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the box language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Box SR() { return boxMin(boxReal(192000.0), boxMax(boxReal(1.0), boxFConst(SType::kSInt, \"fSampleFreq\", \"<math.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return boxFVar(SType::kSInt, \"count\", \"<math.h>\"); } So the following DSP program: Can be written at the box API level with: static void test11() { COMPILER ( Box box = boxPar(SR(), BS()); compile(\"test11\", box); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } } Creating tables Read only and read/write tables can be created. The read only table signal is created with boxReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxReadOnlyTable(boxInt(10), boxInt(1), boxIntCast(boxWire())); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with boxWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxWriteReadTable(boxInt(10), boxInt(1), boxIntCast(boxWire()), boxIntCast(boxWire()), boxIntCast(boxWire())); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } } Creating waveforms The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with boxWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(boxReal(100*i)); } Box box = boxWaveform(waveform); // the size and the waveform content compile(\"test12\", box); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } } Creating soundfile The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with boxSoundfile . Thus the following DSP code: Will be created using the box API with: static void test19() { COMPILER ( Box box = boxSoundfile(\"sound[url:{'tango.wav'}]\", boxInt(2), boxInt(0), boxInt(0)); compile(\"test19\", box); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; } Using the DSPToBoxes function Complete DSP programs can be compiled to boxes using the DSPToBoxes function, which takes a DSP program as a string, and returns the number of inputs/outputs and the created box: static void test25(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the oscillator Box osc = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = os.osc(440);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Compile it dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", osc, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } The resulting box expression can possibly be reused in a more complex construction, as in the following example, where a filter is created using the DSPToBoxes function, then called with a slider to control its frequency, and the actual input: static void test26(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the filter without parameter Box filter = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = fi.lowpass(5);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Create the filter parameters and connect Box cutoff = boxHSlider(\"cutoff\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box cutoffAndInput = boxPar(cutoff, boxWire()); Box filteredInput = boxSeq(cutoffAndInput, filter); bool res = getBoxType(filteredInput, &inputs, &outputs); std::cout << \"getBoxType inputs: \" << inputs << \" outputs: \" << outputs << std::endl; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", filteredInput, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } Note that the getBoxType function can be used to retrieve a given box number of inputs and outputs. Defining more complex expressions: phasor and oscillator More complex signal expressions can be defined, creating boxes using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Box decimalpart() { return boxSub(boxWire(), boxIntCast(boxWire())); } static Box phasor(Box f) { return boxSeq(boxDiv(f, SR()), boxRec(boxSplit(boxAdd(), decimalpart()), boxWire())); } And the main function combining them: static void test17() { COMPILER ( Box box = phasor(boxReal(440)); compile(\"test17\", box); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Box osc(Box f) { return boxSin(boxMul(boxMul(boxReal(2.0), boxReal(3.141592653)), phasor(f))); } static void test18() { COMPILER ( Box box = boxPar(osc(boxReal(440)), osc(boxReal(440))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } } Using the generated code Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromBoxes (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromBoxes (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory); Connecting the audio layer Audio drivers allow you to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop(); Connecting the controller layer Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual. Example with audio rendering and GUI control Here is a more complete example, first with the DSP code: Then with the C++ code using the box API: // Using the Interpreter backend. static void test22(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Generating the signals as an intermediate step The boxesToSignals function allows you to compile a box in a list of signals, to be used with the signal API . The following example shows how the two steps (box => signals then signals => DSP factory) can be chained, rewriting the previous code as: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); // Compile the 'box' to 'signals' tvec signals = boxesToSignals(box, error_msg); // Then compile the 'signals' to a DSP factory factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Polyphonic MIDI controllable simple synthesizer Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the box API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Box freq = boxNumEntry(\"freq\", boxReal(100), boxReal(100), boxReal(3000), boxReal(0.01)); Box gate = boxButton(\"gate\"); Box gain = boxNumEntry(\"gain\", boxReal(0.5), boxReal(0), boxReal(1), boxReal(0.01)); Box organ = boxMul(gate, boxAdd(boxMul(osc(freq), gain), boxMul(osc(boxMul(freq, boxInt(2))), gain))); // Stereo Box box = boxPar(organ, organ); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Examples with the C API The box API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create box expressions, where the LLVM backend is used with the C version createCDSPFactoryFromBoxes function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Box decimalpart() { return CboxSubAux(CboxWire(), CboxIntCastAux(CboxWire())); } static Box phasor(Box f) { return CboxSeq(CboxDivAux(f, SR()), CboxRec(CboxSplit(CboxAdd(), decimalpart()), CboxWire())); } static void test1() { createLibContext(); { Box box = phasor(CboxReal(2000)); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test1\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Box freq = CboxVSlider(\"h:Oscillator/freq\", CboxReal(440), CboxReal(50), CboxReal(1000), CboxReal(0.1)); Box gain = CboxVSlider(\"h:Oscillator/gain\", CboxReal(0), CboxReal(0), CboxReal(1), CboxReal(0.011)); Box box = CboxMulAux(freq, CboxMulAux(gain, CboxWire())); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test3\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the box-tester-c tool, to be compiled with make box-tester-c in the tools/benchmark folder.","title":"Using the box API"},{"location":"tutorials/box-api/#using-the-box-api","text":"The box API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the box API, and take profit of part of the Faust compiler infrastructure.","title":"Using the box API"},{"location":"tutorials/box-api/#faust-compiler-structure","text":"The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated into a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends.","title":"Faust compiler structure"},{"location":"tutorials/box-api/#accessing-the-box-stage","text":"A new intermediate public entry point has been created in the Semantic Phase , after the Evaluation, lambda-calculus step to allow the creation of a box expression, then beneficiate of all remaining parts of the compilation chain. The box API (or the C box API version) allows to programmatically create the box expression, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the signal API allows to access another stage in the compilation stage.","title":"Accessing the box stage"},{"location":"tutorials/box-api/#compiling-box-expressions","text":"To use the box API, the following steps must be taken: creating a global compilation context using the createLibContext function creating a box expression using the box API, progressively building more complex expressions by combining simpler ones compiling the box expression using the createCPPDSPFactoryFromBoxes function to create a DSP factory (or createDSPFactoryFromBoxes to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromBoxes to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used.","title":"Compiling box expressions"},{"location":"tutorials/box-api/#tools","text":"Let's first define a compile function, which uses the createCPPDSPFactoryFromBoxes function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\","title":"Tools"},{"location":"tutorials/box-api/#examples","text":"For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps). All presented C++ examples (as well as some more) are defined in the box-tester tool, to be compiled with make box-tester in the tools/benchmark folder.","title":"Examples"},{"location":"tutorials/box-api/#expression-generating-constant-signals","text":"Let's create a program generating a parallel construction of 7 and 3.14 constant values. Here is the Faust DSP code: The following code creates a box expression, containing a box boxPar(boxInt(7), boxReal(3.14)) expression, then compile it and display the C++ class: static void test1() { COMPILER ( Box box = boxPar(boxInt(7), boxReal(3.14)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(7); output1[i0] = FAUSTFLOAT(3.1400001f); } }","title":"Expression generating constant signals"},{"location":"tutorials/box-api/#doing-some-mathematical-operations-on-an-input-signal","text":"Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with boxWire() expression, then transformed using the boxAdd and boxSeq operators to produce one output: static void test2() { COMPILER ( Box box = boxSeq(boxPar(boxWire(), boxReal(3.14)), boxAdd()); compile(\"test2\", box); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((float(input0[i0]) + 3.1400001f)); } } In the published API, most operators are exported as simple no-argument operators, using the language core-syntax . The prefix notation has been added for each relevant operator, and can be used with additional multi-argument versions. So the previous example can be written in a simpler way with the following code, which will produce the exact same C++: static void test3() { COMPILER ( Box box = boxAdd(boxWire(), boxReal(3.14)); compile(\"test3\", box); ) }","title":"Doing some mathematical operations on an input signal"},{"location":"tutorials/box-api/#defining-a-delay-expression","text":"Here is a simple program delaying the first input: The prefix-notation boxDelay(x, y) operator is used to delay the boxWire() first parameter with the second boxInt(7) : static void test6() { COMPILER ( Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test3\", test6); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(fVec0[7]); for (int j0 = 7; (j0 > 0); j0 = (j0 - 1)) { fVec0[j0] = fVec0[(j0 - 1)]; } } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code shows how to compile in vector mode: static void test7() { createLibContext(); Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test7\", box, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; float fYec0_tmp[40]; float* fYec0 = &fYec0_tmp[8]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 8); j0 = (j0 + 1)) { fYec0_tmp[j0] = fYec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[i] = float(input0[i]); } /* Post code */ for (int j1 = 0; (j1 < 8); j1 = (j1 + 1)) { fYec0_perm[j1] = fYec0_tmp[(vsize + j1)]; } /* Vectorizable loop 1 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec0[(i - 7)]); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test8() { COMPILER ( Box box = boxSplit(boxWire(), boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxMul(boxDelay(boxWire(), boxReal(3000)), boxReal(1.5)))); compile(\"test8\", box); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } }","title":"Defining a delay expression"},{"location":"tutorials/box-api/#equivalent-box-expressions","text":"It is really important to note that syntactically equivalent box expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( Box b1 = boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)); Box box = boxPar(b1, b1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( Box box = boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5))); compile(\"equivalent2\", box); ) } It can be a property to remember when creating a DSL on top of the box API.","title":"Equivalent box expressions"},{"location":"tutorials/box-api/#using-user-interface-items","text":"User Interface items can be used, as in the following example, with a hslider : Built with the following code: static void test8() { COMPILER ( Box box = boxMul(boxWire(), boxHSlider(\"Freq [midi:ctrl 7][style:knob]\", boxReal(100), boxReal(100), boxReal(2000), boxReal(1))); compile(\"test8\", box); ) } The buildUserInterface method is generated, using the fHslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->declare(&fHslider0, \"midi\", \"ctrl 7\"); ui_interface->declare(&fHslider0, \"style\", \"knob\"); ui_interface->addHorizontalSlider(\"Freq\", &fHslider0, FAUSTFLOAT(100.0f), FAUSTFLOAT(100.0f), FAUSTFLOAT(2000.0f), FAUSTFLOAT(1.0f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((fSlow0 * float(input0[i0]))); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the box API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( Box box = boxMul(boxVSlider(\"h:Oscillator/freq\", boxReal(440), boxReal(50), boxReal(1000), boxReal(0.1)), boxVSlider(\"h:Oscillator/gain\", boxReal(0), boxReal(0), boxReal(1), boxReal(0.01))); compile(\"test9\", box); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); }","title":"Using User Interface items"},{"location":"tutorials/box-api/#defining-recursive-signals","text":"Recursive signals can be defined using the boxRec expression. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( Box box = boxRec(boxAdd(), boxWire()); compile(\"test10\", box); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } }","title":"Defining recursive signals"},{"location":"tutorials/box-api/#accessing-the-global-context","text":"In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the box language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Box SR() { return boxMin(boxReal(192000.0), boxMax(boxReal(1.0), boxFConst(SType::kSInt, \"fSampleFreq\", \"<math.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return boxFVar(SType::kSInt, \"count\", \"<math.h>\"); } So the following DSP program: Can be written at the box API level with: static void test11() { COMPILER ( Box box = boxPar(SR(), BS()); compile(\"test11\", box); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } }","title":"Accessing the global context"},{"location":"tutorials/box-api/#creating-tables","text":"Read only and read/write tables can be created. The read only table signal is created with boxReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxReadOnlyTable(boxInt(10), boxInt(1), boxIntCast(boxWire())); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with boxWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxWriteReadTable(boxInt(10), boxInt(1), boxIntCast(boxWire()), boxIntCast(boxWire()), boxIntCast(boxWire())); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } }","title":"Creating tables"},{"location":"tutorials/box-api/#creating-waveforms","text":"The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with boxWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(boxReal(100*i)); } Box box = boxWaveform(waveform); // the size and the waveform content compile(\"test12\", box); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } }","title":"Creating waveforms"},{"location":"tutorials/box-api/#creating-soundfile","text":"The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with boxSoundfile . Thus the following DSP code: Will be created using the box API with: static void test19() { COMPILER ( Box box = boxSoundfile(\"sound[url:{'tango.wav'}]\", boxInt(2), boxInt(0), boxInt(0)); compile(\"test19\", box); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; }","title":"Creating soundfile"},{"location":"tutorials/box-api/#using-the-dsptoboxes-function","text":"Complete DSP programs can be compiled to boxes using the DSPToBoxes function, which takes a DSP program as a string, and returns the number of inputs/outputs and the created box: static void test25(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the oscillator Box osc = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = os.osc(440);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Compile it dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", osc, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } The resulting box expression can possibly be reused in a more complex construction, as in the following example, where a filter is created using the DSPToBoxes function, then called with a slider to control its frequency, and the actual input: static void test26(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the filter without parameter Box filter = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = fi.lowpass(5);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Create the filter parameters and connect Box cutoff = boxHSlider(\"cutoff\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box cutoffAndInput = boxPar(cutoff, boxWire()); Box filteredInput = boxSeq(cutoffAndInput, filter); bool res = getBoxType(filteredInput, &inputs, &outputs); std::cout << \"getBoxType inputs: \" << inputs << \" outputs: \" << outputs << std::endl; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", filteredInput, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } Note that the getBoxType function can be used to retrieve a given box number of inputs and outputs.","title":"Using the DSPToBoxes function"},{"location":"tutorials/box-api/#defining-more-complex-expressions-phasor-and-oscillator","text":"More complex signal expressions can be defined, creating boxes using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Box decimalpart() { return boxSub(boxWire(), boxIntCast(boxWire())); } static Box phasor(Box f) { return boxSeq(boxDiv(f, SR()), boxRec(boxSplit(boxAdd(), decimalpart()), boxWire())); } And the main function combining them: static void test17() { COMPILER ( Box box = phasor(boxReal(440)); compile(\"test17\", box); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Box osc(Box f) { return boxSin(boxMul(boxMul(boxReal(2.0), boxReal(3.141592653)), phasor(f))); } static void test18() { COMPILER ( Box box = boxPar(osc(boxReal(440)), osc(boxReal(440))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } }","title":"Defining more complex expressions: phasor and oscillator"},{"location":"tutorials/box-api/#using-the-generated-code","text":"Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromBoxes (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromBoxes (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory);","title":"Using the generated code"},{"location":"tutorials/box-api/#connecting-the-audio-layer","text":"Audio drivers allow you to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop();","title":"Connecting the audio layer"},{"location":"tutorials/box-api/#connecting-the-controller-layer","text":"Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual.","title":"Connecting the controller layer"},{"location":"tutorials/box-api/#example-with-audio-rendering-and-gui-control","text":"Here is a more complete example, first with the DSP code: Then with the C++ code using the box API: // Using the Interpreter backend. static void test22(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Example with audio rendering and GUI control"},{"location":"tutorials/box-api/#generating-the-signals-as-an-intermediate-step","text":"The boxesToSignals function allows you to compile a box in a list of signals, to be used with the signal API . The following example shows how the two steps (box => signals then signals => DSP factory) can be chained, rewriting the previous code as: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); // Compile the 'box' to 'signals' tvec signals = boxesToSignals(box, error_msg); // Then compile the 'signals' to a DSP factory factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Generating the signals as an intermediate step"},{"location":"tutorials/box-api/#polyphonic-midi-controllable-simple-synthesizer","text":"Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the box API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Box freq = boxNumEntry(\"freq\", boxReal(100), boxReal(100), boxReal(3000), boxReal(0.01)); Box gate = boxButton(\"gate\"); Box gain = boxNumEntry(\"gain\", boxReal(0.5), boxReal(0), boxReal(1), boxReal(0.01)); Box organ = boxMul(gate, boxAdd(boxMul(osc(freq), gain), boxMul(osc(boxMul(freq, boxInt(2))), gain))); // Stereo Box box = boxPar(organ, organ); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Polyphonic MIDI controllable simple synthesizer"},{"location":"tutorials/box-api/#examples-with-the-c-api","text":"The box API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create box expressions, where the LLVM backend is used with the C version createCDSPFactoryFromBoxes function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Box decimalpart() { return CboxSubAux(CboxWire(), CboxIntCastAux(CboxWire())); } static Box phasor(Box f) { return CboxSeq(CboxDivAux(f, SR()), CboxRec(CboxSplit(CboxAdd(), decimalpart()), CboxWire())); } static void test1() { createLibContext(); { Box box = phasor(CboxReal(2000)); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test1\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Box freq = CboxVSlider(\"h:Oscillator/freq\", CboxReal(440), CboxReal(50), CboxReal(1000), CboxReal(0.1)); Box gain = CboxVSlider(\"h:Oscillator/gain\", CboxReal(0), CboxReal(0), CboxReal(1), CboxReal(0.011)); Box box = CboxMulAux(freq, CboxMulAux(gain, CboxWire())); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test3\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the box-tester-c tool, to be compiled with make box-tester-c in the tools/benchmark folder.","title":"Examples with the C API"},{"location":"tutorials/cmajor/","text":"Using Faust in Cmajor In this tutorial, we present how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. Compiling Faust DSP to cmajor code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for Cmajor users who want to discover Faust. Installing the required packages Download the cmaj package and install to have it in your PATH. Using command line tools Generating Cmajor code Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The Cmajor code can be generated using: faust -lang cmajor osc.dsp -o osc.cmajor This will generate a mydsp processor included in a namespace faust {...} with a set of methods to manipulate it. This API basically mimics the one defined for the C++ backend . Looking at the generated code The generated code contains input event definition for the three sliders defined in the DSP source code: input event float32 eventfHslider1 [[ name: \"freq1\", group: \"/v:Oscillator/freq1\", min: 20.0f, max: 3000.0f, init: 1000.0f, step: 1.0f, meta_unit0: \"Hz\" ]]; input event float32 eventfHslider2 [[ name: \"freq2\", group: \"/v:Oscillator/freq2\", min: 20.0f, max: 3000.0f, init: 200.0f, step: 1.0f, meta_unit1: \"Hz\" ]]; input event float32 eventfHslider0 [[ name: \"volume\", group: \"/v:Oscillator/volume\", min: 0.0f, max: 1.0f, init: 0.5f, step: 0.01f ]]; The needed main function executes the DSP sample generation code: void main() { // DSP loop running forever... loop { if (fUpdated) { fUpdated = false; control(); } // Computes one sample fRec1[0] = fControl[1] + fRec1[1] - floor (fControl[1] + fRec1[1]); output0 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec1[0]))); fRec2[0] = fControl[2] + fRec2[1] - floor (fControl[2] + fRec2[1]); output1 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec2[0]))); fRec1[1] = fRec1[0]; fRec2[1] = fRec2[0]; // Moves all streams forward by one 'tick' advance(); } } Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is inlined on the Cmajor loop block. We cannot directly play the generated osc.cmajor file since the cmaj program expects a osc.cmajorpatch to execute. A simple solution is to use the following command: cmaj create --name=osc osc to create an osc folder with default osc.cmajor and osc.cmajorpatch files. Then using the command: faust -lang cmajor osc.dsp -o osc/osc.cmajor allows to simply replace the default osc.cmajor with our own Faust generated version. The patchfile can now be compiled and executed using the cmaj program: cmaj play osc/osc.cmajorpatch The three declared sliders are automatically created and can be used to change the two channels frequencies and their volume. The Cmajor processor code can directly be used in a more complex Cmajor program, possibly connected to other Faust generated or Cmajor hand-written processors. Note that the generated processor name can simply be changed using the Faust compiler -cn <name> option, so that several Faust generated processors can be distinguished by their names: faust -lang cmajor -cn osc osc.dsp -o osc/osc.cmajor Using the faust2cmajor tool The faust2cmajor tool allows to automate calling the Faust compiler with the right options and interacting with the cmaj program: faust2cmajor -h Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. So the following command: faust2cmajor -play osc.dsp will directly compile the osc.dsp file, generate the osc.cmajor and osc.cmajorpatch files: { \"CmajorVersion\": 1, \"ID\": \"grame.cmajor.osc\", \"version\": \"1.0\", \"name\": \"osc\", \"description\": \"Cmajor example\", \"category\": \"synth\", \"manufacturer\": \"GRAME\", \"website\": \"https://faust.grame.fr\", \"isInstrument\": false, \"source\": \"osc.cmajor\" } And activate the cmaj program to run the processor. The following polyphonic ready instrument DSP can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 organ.dsp Note that the generated GUI is empty, since the generated processor cannot automatically reflects its controls in the main graph. The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 -effect auto clarinet.dsp Here again the generated GUI is empty. Generating the Cmajor output using faustremote A possibility is to use the faustremote script to convert a local DSP with the following commands: faustremote cmajor cmajor foo.dsp unzip binary.zip Using the Faust Web IDE Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Cmajor code. Generating the Cmajor output The output as a Cmajor program can directly be generated using the Platform = cmajor and Architecture = cmajor export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The program can be executed using cmaj play foo/foo.cmajorpatch command or possibly converted as a JUCE plugin . Exporting the code Generating the Cmajor output in polyphonic mode DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = cmajor and Architecture = cmajor-poly export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin . Generating the Cmajor output in polyphonic mode with a global effect DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = cmajor and Architecture = cmajor-poly-effect export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin . Generating the Cmajor output from a Faust DSP program found in the web Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a Cmajor program as already showed basic Examples have been compiled to Cmajor here examples of the faustplayground platform can be found here and possibly converted. They have been compiled to Cmajor here . Experimental Faust in Cmajor integration With the release of the Cmajor source code , an experimental Faust in Cmajor integration can be tested starting with Cmajor 1.0.2616 release . Known limitations The Cmajor language generates some usefull API when the patch is exported in C++ or JavaScript. For example the getInputEndpoints/getOutputEndpoints and getEndpointHandle functions allow an external piece of code to enumerate and access all endpoints, to possibly control the program or build a GUI. But unfortunately those functions are not part of the language itself . Thus there is no way we know of: to write a generic Cmajor program that would automatically connect some endpoints (assuming they would use some kind of MIDI describing metadata) to MIDI messages to write a generic Cmajor program that would automatically wraps a voice generated from a Faust DSP program in a polyphonic and MIDI aware program, and expose the voice set of parameters at the main graph level, to be controlled globally for all voices We think the language would gain expressive power by having some kind of reflexivity .","title":"Using Faust in Cmajor"},{"location":"tutorials/cmajor/#using-faust-in-cmajor","text":"In this tutorial, we present how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. Compiling Faust DSP to cmajor code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net.","title":"Using Faust in Cmajor"},{"location":"tutorials/cmajor/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for Cmajor users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/cmajor/#installing-the-required-packages","text":"Download the cmaj package and install to have it in your PATH.","title":"Installing the required packages"},{"location":"tutorials/cmajor/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/cmajor/#generating-cmajor-code","text":"Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The Cmajor code can be generated using: faust -lang cmajor osc.dsp -o osc.cmajor This will generate a mydsp processor included in a namespace faust {...} with a set of methods to manipulate it. This API basically mimics the one defined for the C++ backend .","title":"Generating Cmajor code"},{"location":"tutorials/cmajor/#looking-at-the-generated-code","text":"The generated code contains input event definition for the three sliders defined in the DSP source code: input event float32 eventfHslider1 [[ name: \"freq1\", group: \"/v:Oscillator/freq1\", min: 20.0f, max: 3000.0f, init: 1000.0f, step: 1.0f, meta_unit0: \"Hz\" ]]; input event float32 eventfHslider2 [[ name: \"freq2\", group: \"/v:Oscillator/freq2\", min: 20.0f, max: 3000.0f, init: 200.0f, step: 1.0f, meta_unit1: \"Hz\" ]]; input event float32 eventfHslider0 [[ name: \"volume\", group: \"/v:Oscillator/volume\", min: 0.0f, max: 1.0f, init: 0.5f, step: 0.01f ]]; The needed main function executes the DSP sample generation code: void main() { // DSP loop running forever... loop { if (fUpdated) { fUpdated = false; control(); } // Computes one sample fRec1[0] = fControl[1] + fRec1[1] - floor (fControl[1] + fRec1[1]); output0 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec1[0]))); fRec2[0] = fControl[2] + fRec2[1] - floor (fControl[2] + fRec2[1]); output1 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec2[0]))); fRec1[1] = fRec1[0]; fRec2[1] = fRec2[0]; // Moves all streams forward by one 'tick' advance(); } } Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is inlined on the Cmajor loop block. We cannot directly play the generated osc.cmajor file since the cmaj program expects a osc.cmajorpatch to execute. A simple solution is to use the following command: cmaj create --name=osc osc to create an osc folder with default osc.cmajor and osc.cmajorpatch files. Then using the command: faust -lang cmajor osc.dsp -o osc/osc.cmajor allows to simply replace the default osc.cmajor with our own Faust generated version. The patchfile can now be compiled and executed using the cmaj program: cmaj play osc/osc.cmajorpatch The three declared sliders are automatically created and can be used to change the two channels frequencies and their volume. The Cmajor processor code can directly be used in a more complex Cmajor program, possibly connected to other Faust generated or Cmajor hand-written processors. Note that the generated processor name can simply be changed using the Faust compiler -cn <name> option, so that several Faust generated processors can be distinguished by their names: faust -lang cmajor -cn osc osc.dsp -o osc/osc.cmajor","title":"Looking at the generated code"},{"location":"tutorials/cmajor/#using-the-faust2cmajor-tool","text":"The faust2cmajor tool allows to automate calling the Faust compiler with the right options and interacting with the cmaj program: faust2cmajor -h Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. So the following command: faust2cmajor -play osc.dsp will directly compile the osc.dsp file, generate the osc.cmajor and osc.cmajorpatch files: { \"CmajorVersion\": 1, \"ID\": \"grame.cmajor.osc\", \"version\": \"1.0\", \"name\": \"osc\", \"description\": \"Cmajor example\", \"category\": \"synth\", \"manufacturer\": \"GRAME\", \"website\": \"https://faust.grame.fr\", \"isInstrument\": false, \"source\": \"osc.cmajor\" } And activate the cmaj program to run the processor. The following polyphonic ready instrument DSP can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 organ.dsp Note that the generated GUI is empty, since the generated processor cannot automatically reflects its controls in the main graph. The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 -effect auto clarinet.dsp Here again the generated GUI is empty.","title":"Using the faust2cmajor tool"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-using-faustremote","text":"A possibility is to use the faustremote script to convert a local DSP with the following commands: faustremote cmajor cmajor foo.dsp unzip binary.zip","title":"Generating the Cmajor output using faustremote"},{"location":"tutorials/cmajor/#using-the-faust-web-ide","text":"Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Cmajor code.","title":"Using the Faust Web IDE"},{"location":"tutorials/cmajor/#generating-the-cmajor-output","text":"The output as a Cmajor program can directly be generated using the Platform = cmajor and Architecture = cmajor export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The program can be executed using cmaj play foo/foo.cmajorpatch command or possibly converted as a JUCE plugin . Exporting the code","title":"Generating the Cmajor output"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-in-polyphonic-mode","text":"DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = cmajor and Architecture = cmajor-poly export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin .","title":"Generating the Cmajor output in polyphonic mode"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-in-polyphonic-mode-with-a-global-effect","text":"DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = cmajor and Architecture = cmajor-poly-effect export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin .","title":"Generating the Cmajor output in polyphonic mode with a global effect"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-from-a-faust-dsp-program-found-in-the-web","text":"Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a Cmajor program as already showed basic Examples have been compiled to Cmajor here examples of the faustplayground platform can be found here and possibly converted. They have been compiled to Cmajor here .","title":"Generating the Cmajor output from a Faust DSP program found in the web"},{"location":"tutorials/cmajor/#experimental-faust-in-cmajor-integration","text":"With the release of the Cmajor source code , an experimental Faust in Cmajor integration can be tested starting with Cmajor 1.0.2616 release .","title":"Experimental Faust in Cmajor integration"},{"location":"tutorials/cmajor/#known-limitations","text":"The Cmajor language generates some usefull API when the patch is exported in C++ or JavaScript. For example the getInputEndpoints/getOutputEndpoints and getEndpointHandle functions allow an external piece of code to enumerate and access all endpoints, to possibly control the program or build a GUI. But unfortunately those functions are not part of the language itself . Thus there is no way we know of: to write a generic Cmajor program that would automatically connect some endpoints (assuming they would use some kind of MIDI describing metadata) to MIDI messages to write a generic Cmajor program that would automatically wraps a voice generated from a Faust DSP program in a polyphonic and MIDI aware program, and expose the voice set of parameters at the main graph level, to be controlled globally for all voices We think the language would gain expressive power by having some kind of reflexivity .","title":"Known limitations"},{"location":"tutorials/debugging/","text":"Advanced debugging with interp-tracer Some general informations are given here on how to debug the Faust DSP code. This tutorial aims to better explain how the interp-tracer tool can be used to debug code at runtime. The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL, FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW, CAST_INT_OVERFLOW, NEGATIVE_BITSHIFT and DIV_BY_ZERO operations, or LOAD/STORE errors. Debugging out-of-domain computations Using the -trace 4 option allows to exit at first error and write FBC (Faust Byte Code) trace as a DumpCode-foo.txt file, and the program memory layout as DumpMem-fooXXX.txt file. The following debug.dsp DSP program: process = hslider(\"foo\", 0.5, -1, 1, 0.01) : log; will produce out-of-domain values as soon at the slider value is 0 or below, with the following trace written on the console: -------- Interpreter 'NaN' trace start -------- opcode 202 kLogf int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 2 kLoadReal int 0 real 0 offset1 1 offset2 0 name fHslider0 Stack [Int: 0] [REAL: -4,605170] opcode 279 kCondBranch int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: -4,605170] opcode 46 kLTInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 1 offset2 0 name count Stack [Int: 16] [REAL: -4,605170] opcode 7 kStoreInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 33 kAddInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] -------- Interpreter 'NaN' trace end -------- The trace contains the stack of Faust Byte Code (FBC) instructions executed by the interpreter, with the latest instructions executed before the actual error, here the kLogf operation. The names of the fields in the DSP structure are also visible, here fHslider0 . Looking at the generated C++ can help understand the control flow: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = std::log(float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } The generated DumpMem-debug22419.txt file contains the content of the interpreter Virtual Machine REAL (float/double depending on the -single/-double compilation option) memory array, and INT (integer) memory array. DSP name: debug ================================= REAL memory: 3 0 defaultsound 0 1 fHslider0 -0.01 2 fSlow0 -4.60517 ================================= INT memory: 3 0 44100 1 count 16 2 i0 16 Debugging rdtable and rwtable primitives The rdtable primitive uses a read index, and the rwtable primitive uses a read index and a write index. The table size is known at compile time, and read/write indexes must stay inside the table to avoid memory access crashes at runtime. The -ct option can be used to check table index range and generate safe table access code. For the following DSP table.dsp program: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; integrator = +(1) ~ _; rdx = integrator%(SIZE*2); wdx = integrator%(SIZE*2); }; the generated code with the -ct 0 option will produce: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 32; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with incorrect table access code in the compute method, where the iTemp0 read and write indexes may exceed the table size of 16. Executing interp-tracer -trace 4 -ct 0 table.dsp generates the following trace on the console, showing memory read/write access errors: -------- Interpreter crash trace start -------- assertStoreRealHeap array: fIntHeapSize 17 index 16 size 16 name ftbl0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 15] [REAL: 0,000000] opcode 24 kLoadInput int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 6 offset2 0 name i0 Stack [Int: 16] [REAL: 0,000000] opcode 7 kStoreInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 16] [REAL: 0,000000] opcode 41 kRemInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 11 kLoadIndexedInt int 0 real 0 offset1 0 offset2 2 name iRec0 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 32 real 0 offset1 -1 offset2 -1 -------- Interpreter crash trace end -------- With the -ct 1 option, the generated code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0] % 32, 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } where the iTemp0 read and write index is now constrained to stay in the [0..15] range and the code will not crash at runtime anymore. The DSP program was indeed incorrect with the indexes wrapping at 32 samples boundaries. It can be rewritten as: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) : %(SIZE)) ~ _; rdx = index; wdx = index; }; and the generated C++ code with the -ct 1 option (and using the -wall option to print warning messages on the console) is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = (iRec0[1] + 1) % 16; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0], 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with the warning messages: WARNING : RDTbl read index [0:inf] is outside of table size (16) in read(write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0) WARNING : WRTbl write index [0:inf] is outside of table size (16) in write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]) The range test code checks if the read or write index interval is inside the [0..size-1] range, and only generates constraining code when needed. But since the signal interval calculation is currently imperfect, unneeded range constraining code might be generated ! This is actually the case in the generated code, and can be tested using interp-tracer -trace 4 -ct 0 table.dsp , which does not generate constraining code, but does not show any problem. If one is absolutely sure of the stay in range property, then adding constraining code can be deactivated using -ct 0 and the generated code will be faster. The hope is to improve the signal interval calculation model, so that the index constraining code will not be needed anymore. Note that the DSP program can be rewritten this way: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) ~ _) : %(SIZE); rdx = index; wdx = index; }; in this case the signal interval is correct and the generated C++ code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 16; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } without any added range constraining code. Note that -ct 1 option is the default, so safe code is always generated. Debugging the select2 primitive The select2 primitive has a strict semantic, but for code optimization strategies, the generated code is not fully strict . For the following DSP program: process = select2(button(\"gate\"), branch1, branch2) with { branch1 = (hslider(\"foo\", 0.5, 0, 1, 0.01):log); branch2 = (hslider(\"bar\", 0.5, -1, 1, 0.01):sqrt); }; the generated C++ is using the ((cond) ? then : else) form which actually only computes one of the then or else branch depending of the button(\"gate\") condition: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = ((int(float(fButton0))) ? std::sqrt(float(fHslider1)) : std::log(float(fHslider0))); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } Thus executing it with interp-tracer -trace 4 debug.dsp allows it to detect one falling branch when the condition is in a given state. To force computation of both branches, the -sts (--strict-select) option can be used. The generated C++ is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fThen0 = std::log(float(fHslider0)); float fElse0 = std::sqrt(float(fHslider1)); float fSlow0 = ((int(float(fButton0))) ? fElse0 : fThen0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } where intermediate fThen0 and fElse0 created variables force the actual computation of both branches. Then executing interp-tracer -trace 4 -sts debug.dsp will reveal the out-of-bounds calculation on both branches, for both states of the condition. Debugging using test signals Effects DSP programs usually need to be fed with standardized test input signals to possibly trigger abnormal behavior. The interp-tracer tool has an -input option to connect an impulse program (defined with the process = 1-1'; ), then a noise program (defined with the import(\"stdfaust.lib\"); process = no.noise; ) to all inputs of the tested DSP. So something like the interp-tracer -trace 4 -input debug.dsp command has to be used. More specialized test input signals can be used by directly modifying the debug.dsp code, then running the DSP code normally (that is not using the -input option anymore). So writing something like: process = test_signal <: effect; to connect a given mono test_signal to all inputs of the effect program. Correcting the program The interp-tracer tool helps finding programming errors. But obviously, the detected errors must then be corrected: by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items by checking mathematical function domains by checking indexes when using by rdtable\\rwtable primitives ...","title":"Advanced debugging with interp-tracer"},{"location":"tutorials/debugging/#advanced-debugging-with-interp-tracer","text":"Some general informations are given here on how to debug the Faust DSP code. This tutorial aims to better explain how the interp-tracer tool can be used to debug code at runtime. The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL, FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW, CAST_INT_OVERFLOW, NEGATIVE_BITSHIFT and DIV_BY_ZERO operations, or LOAD/STORE errors.","title":"Advanced debugging with interp-tracer"},{"location":"tutorials/debugging/#debugging-out-of-domain-computations","text":"Using the -trace 4 option allows to exit at first error and write FBC (Faust Byte Code) trace as a DumpCode-foo.txt file, and the program memory layout as DumpMem-fooXXX.txt file. The following debug.dsp DSP program: process = hslider(\"foo\", 0.5, -1, 1, 0.01) : log; will produce out-of-domain values as soon at the slider value is 0 or below, with the following trace written on the console: -------- Interpreter 'NaN' trace start -------- opcode 202 kLogf int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 2 kLoadReal int 0 real 0 offset1 1 offset2 0 name fHslider0 Stack [Int: 0] [REAL: -4,605170] opcode 279 kCondBranch int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: -4,605170] opcode 46 kLTInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 1 offset2 0 name count Stack [Int: 16] [REAL: -4,605170] opcode 7 kStoreInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 33 kAddInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] -------- Interpreter 'NaN' trace end -------- The trace contains the stack of Faust Byte Code (FBC) instructions executed by the interpreter, with the latest instructions executed before the actual error, here the kLogf operation. The names of the fields in the DSP structure are also visible, here fHslider0 . Looking at the generated C++ can help understand the control flow: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = std::log(float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } The generated DumpMem-debug22419.txt file contains the content of the interpreter Virtual Machine REAL (float/double depending on the -single/-double compilation option) memory array, and INT (integer) memory array. DSP name: debug ================================= REAL memory: 3 0 defaultsound 0 1 fHslider0 -0.01 2 fSlow0 -4.60517 ================================= INT memory: 3 0 44100 1 count 16 2 i0 16","title":"Debugging out-of-domain computations"},{"location":"tutorials/debugging/#debugging-rdtable-and-rwtable-primitives","text":"The rdtable primitive uses a read index, and the rwtable primitive uses a read index and a write index. The table size is known at compile time, and read/write indexes must stay inside the table to avoid memory access crashes at runtime. The -ct option can be used to check table index range and generate safe table access code. For the following DSP table.dsp program: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; integrator = +(1) ~ _; rdx = integrator%(SIZE*2); wdx = integrator%(SIZE*2); }; the generated code with the -ct 0 option will produce: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 32; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with incorrect table access code in the compute method, where the iTemp0 read and write indexes may exceed the table size of 16. Executing interp-tracer -trace 4 -ct 0 table.dsp generates the following trace on the console, showing memory read/write access errors: -------- Interpreter crash trace start -------- assertStoreRealHeap array: fIntHeapSize 17 index 16 size 16 name ftbl0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 15] [REAL: 0,000000] opcode 24 kLoadInput int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 6 offset2 0 name i0 Stack [Int: 16] [REAL: 0,000000] opcode 7 kStoreInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 16] [REAL: 0,000000] opcode 41 kRemInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 11 kLoadIndexedInt int 0 real 0 offset1 0 offset2 2 name iRec0 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 32 real 0 offset1 -1 offset2 -1 -------- Interpreter crash trace end -------- With the -ct 1 option, the generated code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0] % 32, 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } where the iTemp0 read and write index is now constrained to stay in the [0..15] range and the code will not crash at runtime anymore. The DSP program was indeed incorrect with the indexes wrapping at 32 samples boundaries. It can be rewritten as: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) : %(SIZE)) ~ _; rdx = index; wdx = index; }; and the generated C++ code with the -ct 1 option (and using the -wall option to print warning messages on the console) is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = (iRec0[1] + 1) % 16; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0], 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with the warning messages: WARNING : RDTbl read index [0:inf] is outside of table size (16) in read(write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0) WARNING : WRTbl write index [0:inf] is outside of table size (16) in write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]) The range test code checks if the read or write index interval is inside the [0..size-1] range, and only generates constraining code when needed. But since the signal interval calculation is currently imperfect, unneeded range constraining code might be generated ! This is actually the case in the generated code, and can be tested using interp-tracer -trace 4 -ct 0 table.dsp , which does not generate constraining code, but does not show any problem. If one is absolutely sure of the stay in range property, then adding constraining code can be deactivated using -ct 0 and the generated code will be faster. The hope is to improve the signal interval calculation model, so that the index constraining code will not be needed anymore. Note that the DSP program can be rewritten this way: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) ~ _) : %(SIZE); rdx = index; wdx = index; }; in this case the signal interval is correct and the generated C++ code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 16; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } without any added range constraining code. Note that -ct 1 option is the default, so safe code is always generated.","title":"Debugging rdtable and rwtable primitives"},{"location":"tutorials/debugging/#debugging-the-select2-primitive","text":"The select2 primitive has a strict semantic, but for code optimization strategies, the generated code is not fully strict . For the following DSP program: process = select2(button(\"gate\"), branch1, branch2) with { branch1 = (hslider(\"foo\", 0.5, 0, 1, 0.01):log); branch2 = (hslider(\"bar\", 0.5, -1, 1, 0.01):sqrt); }; the generated C++ is using the ((cond) ? then : else) form which actually only computes one of the then or else branch depending of the button(\"gate\") condition: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = ((int(float(fButton0))) ? std::sqrt(float(fHslider1)) : std::log(float(fHslider0))); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } Thus executing it with interp-tracer -trace 4 debug.dsp allows it to detect one falling branch when the condition is in a given state. To force computation of both branches, the -sts (--strict-select) option can be used. The generated C++ is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fThen0 = std::log(float(fHslider0)); float fElse0 = std::sqrt(float(fHslider1)); float fSlow0 = ((int(float(fButton0))) ? fElse0 : fThen0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } where intermediate fThen0 and fElse0 created variables force the actual computation of both branches. Then executing interp-tracer -trace 4 -sts debug.dsp will reveal the out-of-bounds calculation on both branches, for both states of the condition.","title":"Debugging the select2 primitive"},{"location":"tutorials/debugging/#debugging-using-test-signals","text":"Effects DSP programs usually need to be fed with standardized test input signals to possibly trigger abnormal behavior. The interp-tracer tool has an -input option to connect an impulse program (defined with the process = 1-1'; ), then a noise program (defined with the import(\"stdfaust.lib\"); process = no.noise; ) to all inputs of the tested DSP. So something like the interp-tracer -trace 4 -input debug.dsp command has to be used. More specialized test input signals can be used by directly modifying the debug.dsp code, then running the DSP code normally (that is not using the -input option anymore). So writing something like: process = test_signal <: effect; to connect a given mono test_signal to all inputs of the effect program.","title":"Debugging using test signals"},{"location":"tutorials/debugging/#correcting-the-program","text":"The interp-tracer tool helps finding programming errors. But obviously, the detected errors must then be corrected: by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items by checking mathematical function domains by checking indexes when using by rdtable\\rwtable primitives ...","title":"Correcting the program"},{"location":"tutorials/esp32/","text":"DSP on the ESP32 With Faust The ESP32 is a cheap microcontroller providing built-in Bluetooth and Wifi support, many GPIOs and analog inputs, etc. It's extremely low price (a few dollars) makes it very attractive and it is being used in an increasing number of boards. A wide range of \"unknown/secret\" development boards targeting audio applications are based on the ESP32 and can be found on Alibaba/AliExpress. While most of them target the development of \"intelligent speakers\" (e.g., Alexa, etc.), they host all the components to carry out real-time DSP applications and can therefore be used to develop digital musical instruments, effect processors, synthesizer hardware, etc. The TTGO T-Audio or the ESP32 Audio Dev Kit are good examples of such boards. The TTGO T-Audio (left) and the ESP32 Audio Dev Kit (right) They both host relatively good quality audio codecs with stereo in and out and built-in amplifier, battery circuit, external RAM, and various motion sensors (only for the TTGO T-Audio), all that for less than $15!! Since these boards don't run any OS, very low audio latency can be achieved (i.e., buffer size of 8 samples, etc.). Compared to the Teensy 3.6/4.0 and their respective audio shields , these boards are MUCH cheaper, they're more powerful than the Teensy 3.6 (dual core with a much higher clock) and most importantly, they have enough RAM to run DSP algorithms with a large memory footprint such as reverbs, echos, etc. (which is relatively limited on the Teensy 3.6 and 4.0). Finally, the ESP32 ecosystem is entirely open source (including its loader)! In many ways, they can compete with much more expensive dedicated audio platforms such as the BELA (<$150), etc. The Faust distribution now comes with faust2esp32 , a tool to program ESP32-based boards with Faust. faust2esp32 is still under development and its current version allows to generate DSP engines that can be used in ESP32 projects to carry out sound synthesis and processing tasks. While the mechanism ( i2s ) used to communicate between the ESP32 and the audio codec is the same on all boards, the brand and the type of audio codecs used on ESP32-based boards varies quite a lot. faust2esp32 supports a few audio codecs which can be listed by running faust2esp32 -h or by looking at the faust2esp32 doc . DSP engines produced by faust2esp32 are compatible with both the C++ and the Arduino development environment of the ESP32. The two following sections walk you through starting a new ESP32 project and adding Faust audio support to it using both methods. Using the ESP32 C++ Development Environment The final source code of this tutorial can be found here . Programming the ESP32 with its native C++ environment offers many advantages. In particular, it allows for a very fine tuning of the board configuration and compilation options. For example, if your DSP algorithm will have a large memory footprint, you might have no other option since external RAM will have to be activated (see Using the External RAM of the ESP32 section). In this short tutorial, we walk you through the steps of making a C++ project from scratch with audio DSP support for the TTGO T-Audio board (the procedure should be more or less the same for similar types of boards). Starting a New ESP32 Project Information on how to configure your ESP32 C++ development environment can be found in this tutorial (read it until the end of step 4). Once your environment is up and running, copy the ESP32 hello_world example project somewhere on your system. Then run make , which should automatically prompt the ESP32 configuration panel. Make some modifications if needed (i.e., serial flasher config as specified in the ESP32 get started tutorial, etc.). Once you exit the menu, compilation should start and complete without any issue. Since the DSP engine that we're about to generate with faust2esp32 uses C++, the main file of the current project should be modified to use C++ as well. To do so, just rename main/hello_world_main.c to main/main.cpp (or any other name you'd like, of course, as long as you use the cpp extension). Then, make sure the basic structure of your program looks like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" extern \"C\" { void app_main(void); } void app_main(void) { while(1) { vTaskDelay(1000 / portTICK_PERIOD_MS); } } Here, the infinite while loop gets ran in the main thread/task and is updated every second. Update the CMakeLists.txt file at the root of the project to change the project name (e.g., project(FaustTutorial) ). Similarly, update the CMakeLists.txt file in main to set the right file for the component source (e.g., set(COMPONENT_SRCS \"main.cpp\") ). Run make again to be sure that your program still compiles and that you didn't break anything. Making a Simple DSP Engine Let's now write a simple Faust program (the usual one haha) implementing a band limited sawtooth wave with smoothed control: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.sawtooth(freq)*gain; Save it in a file called FaustSawtooth.dsp (this will define the name of the corresponding DSP engine) and compile it using faust2esp32 by running the following command: faust2esp32 -lib FaustSawtooth.dsp -lib asks to generate a C++ DSP engine here as opposed to a complete firmware. Note: the current version of faust2esp32 only allows to generate DSP engines (not complete ESP32 programs) so the -lib option is not really necessary here. Alternatively, this could be done by selecting the ESP32 target in the Faust compilation service in the online IDE . In both cases, a .zip package containing a set of C++ files will be returned. In the current example, FaustSawtooth.[cpp/h] implement the Faust DSP object produced from FaustSawtooth.dsp and WM8978.[cpp/h] is the object corresponding to the audio codec of your board. Note: in the current version of faust2esp32 , the only supported audio codecs are the WM8978 ( -WM8978 option) which is that of the TTGO T-Audio board and the AC101 ( -AC101 option). All these files should be placed in the main folder of the project. After that, they should be included to main.cpp as follows: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } Configuring the Audio Codec Next, the WM8978 object (which corresponds to the audio codec, i.e., audio interface on the board) should be instantiated and configured in app_main : WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); Once again, the current version of faust2esp32 only provides support for the Wolfson WM8978 present on the TTGO T-Audio and the AC101, but we're working at adding new codecs from other manufacturers, etc. The procedure should be similar with other codecs. The present configuration activates the mic input, deactivates the amp for the speaker, sets the headphone gain to 40, etc. Please refer to the WM8978 object documentation for more information. Note that each of these commands will be called \"in real-time\" at start-up so the configuration of the audio codec is progressively done and should be carried out before sending any audio buffer to it. Instantiating the Faust DSP Engine After configuring the audio codec, the Faust DSP object produced in the previous step and included in main.cpp should be instantiated in app_main as well: int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); The constructor of FaustSawtooth takes two arguments: the sampling rate (48kHz here) and the block size (8 here). Calling the constructor will configure the object, allocate memory for it, etc. but in order to start computation, the start() method needs to be called. Since ESP32 firmwares are based on freertos , audio is computed in its own high priority task and calling start() will launch this task. Note that this task can be removed and audio computation stopped at any time simply by calling stop() . Finally, the setParamValue method of the FaustSawtooth object can be called at any point to change the value of one of the parameter of the Faust object (here, two parameters were declared: freq and gain ). For example, the frequency of the generated sawtooth could be randomly changed at every sample by calling the following line in the while loop at the bottom of app_main : faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); At this point, main.cpp should look like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } void app_main(void) { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); while(1) { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); vTaskDelay(1000 / portTICK_PERIOD_MS); } } Try to recompile the firmware and upload it to your board. If headphones are connected to it, you should hear a sawtooth wave whose frequency changes randomly every second. Using the External RAM of the ESP32 Some DSP algorithms might require a large amount of memory allocation (e.g., wave tables, delays, etc.). In that case, the object generated by Faust might not fit in the built-in RAM of the ESP32 and it might be necessary to use the external RAM module (SRAM) of the board. In order to test this, we first need to write a Faust program that will need a large amount of memory. Replacing the sawtooth wave of the previous example by a sine wave should do it since the default sine wave oscillator of Faust ( os.osc ) is based on a wave table of size 65536: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.osc(freq)*gain; You can then follow the same steps as the ones described in the Making a Simple DSP Engine section to integrate this Faust program to your C++ ESP32 project. If you try to compile your firmware again (i.e., make ), you should get the following error during linking : [...]/xtensa-esp32-elf/bin/ld: hello-world.elf section `.dram0.bss' will not fit in region `dram0_0_seg' [...]/xtensa-esp32-elf/bin/ld: DRAM segment data does not fit. [...]/xtensa-esp32-elf/bin/ld: region `dram0_0_seg' overflowed by 93408 bytes collect2: error: ld returned 1 exit status To solve this problem, the external RAM can be integrated to the memory map of the ESP32. To do so, run make menuconfig and navigate to Component Config/ESP32-specific . Then activate Support for external RAM, SPI-Connected RAM by highlighting this zone and pressing the y key. Enter the SPI RAM config/SPI RAM access method menu and choose Integrate RAM into ESP32 memory map . Then select Allow .bss segment placed in external memory and press the y key to activate this function. Finally, open FaustSawtooth.cpp (even though we're trying to synthesize a sine wave now, i.e., the name of this file might differ in your case) and search for static float ftbl0mydspSIG0 which is the static table that will be filled with the sine wave table. This section of the C++ code generated by the Faust compiler will always contain large tables requiring lots of memory. You now want to add the EXT_RAM_ATTR attribute next to the table definition: static float ftbl0mydspSIG0[65536] EXT_RAM_ATTR; It indicates the C++ compiler that this static table should be placed in the external memory rather than in the built-in one. In case your Faust program is doing something else than synthesizing a sine wave, you might have to put this attribute in each table definition. Note: We're currently modifying the Faust compiler to automatize this process when a specific option is given to it. Finally, try to recompile your firmware and it should all work nicely now! Using the Arduino Development Environment The final source code of this tutorial can be found here . The Arduino development environment can also be used to program the ESP32. The steps to use a Faust-generated DSP engine in that context are quite similar to that of the C++ environment described in the previous section . First, make sure that the esp32 package is installed in the Arduino Boards Manager ( Tools/Board/Boards Manager ). Next, create a new empty project and save it. You can then follow the same steps as the one described in the Making a Simple DSP Engine section of the previous tutorial, however you should place the FaustSawtooth.[cpp/h] and WM8978.[cpp/h] files in the same folder as the one containing the .ino file of your project. Hence, the tree of your project folder should now look like this: esp32Tuto.ino FaustSawtooth.cpp FaustSawtooth.h WM8978.cpp WM8978.h You can then edit your Arduino program as follows: #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth(48000,8); void setup() { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); faustSawtooth.start(); } void loop() { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); delay(1000); } and the resulting firmware should have the same effect as the one presented in the previous C++ tutorial . You can refer to the Configuring the Audio Codec section to get more information of what the WM8978 lines are doing, etc.","title":"DSP on the ESP-32 With Faust"},{"location":"tutorials/esp32/#dsp-on-the-esp32-with-faust","text":"The ESP32 is a cheap microcontroller providing built-in Bluetooth and Wifi support, many GPIOs and analog inputs, etc. It's extremely low price (a few dollars) makes it very attractive and it is being used in an increasing number of boards. A wide range of \"unknown/secret\" development boards targeting audio applications are based on the ESP32 and can be found on Alibaba/AliExpress. While most of them target the development of \"intelligent speakers\" (e.g., Alexa, etc.), they host all the components to carry out real-time DSP applications and can therefore be used to develop digital musical instruments, effect processors, synthesizer hardware, etc. The TTGO T-Audio or the ESP32 Audio Dev Kit are good examples of such boards. The TTGO T-Audio (left) and the ESP32 Audio Dev Kit (right) They both host relatively good quality audio codecs with stereo in and out and built-in amplifier, battery circuit, external RAM, and various motion sensors (only for the TTGO T-Audio), all that for less than $15!! Since these boards don't run any OS, very low audio latency can be achieved (i.e., buffer size of 8 samples, etc.). Compared to the Teensy 3.6/4.0 and their respective audio shields , these boards are MUCH cheaper, they're more powerful than the Teensy 3.6 (dual core with a much higher clock) and most importantly, they have enough RAM to run DSP algorithms with a large memory footprint such as reverbs, echos, etc. (which is relatively limited on the Teensy 3.6 and 4.0). Finally, the ESP32 ecosystem is entirely open source (including its loader)! In many ways, they can compete with much more expensive dedicated audio platforms such as the BELA (<$150), etc. The Faust distribution now comes with faust2esp32 , a tool to program ESP32-based boards with Faust. faust2esp32 is still under development and its current version allows to generate DSP engines that can be used in ESP32 projects to carry out sound synthesis and processing tasks. While the mechanism ( i2s ) used to communicate between the ESP32 and the audio codec is the same on all boards, the brand and the type of audio codecs used on ESP32-based boards varies quite a lot. faust2esp32 supports a few audio codecs which can be listed by running faust2esp32 -h or by looking at the faust2esp32 doc . DSP engines produced by faust2esp32 are compatible with both the C++ and the Arduino development environment of the ESP32. The two following sections walk you through starting a new ESP32 project and adding Faust audio support to it using both methods.","title":"DSP on the ESP32 With Faust"},{"location":"tutorials/esp32/#using-the-esp32-c-development-environment","text":"The final source code of this tutorial can be found here . Programming the ESP32 with its native C++ environment offers many advantages. In particular, it allows for a very fine tuning of the board configuration and compilation options. For example, if your DSP algorithm will have a large memory footprint, you might have no other option since external RAM will have to be activated (see Using the External RAM of the ESP32 section). In this short tutorial, we walk you through the steps of making a C++ project from scratch with audio DSP support for the TTGO T-Audio board (the procedure should be more or less the same for similar types of boards).","title":"Using the ESP32 C++ Development Environment"},{"location":"tutorials/esp32/#starting-a-new-esp32-project","text":"Information on how to configure your ESP32 C++ development environment can be found in this tutorial (read it until the end of step 4). Once your environment is up and running, copy the ESP32 hello_world example project somewhere on your system. Then run make , which should automatically prompt the ESP32 configuration panel. Make some modifications if needed (i.e., serial flasher config as specified in the ESP32 get started tutorial, etc.). Once you exit the menu, compilation should start and complete without any issue. Since the DSP engine that we're about to generate with faust2esp32 uses C++, the main file of the current project should be modified to use C++ as well. To do so, just rename main/hello_world_main.c to main/main.cpp (or any other name you'd like, of course, as long as you use the cpp extension). Then, make sure the basic structure of your program looks like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" extern \"C\" { void app_main(void); } void app_main(void) { while(1) { vTaskDelay(1000 / portTICK_PERIOD_MS); } } Here, the infinite while loop gets ran in the main thread/task and is updated every second. Update the CMakeLists.txt file at the root of the project to change the project name (e.g., project(FaustTutorial) ). Similarly, update the CMakeLists.txt file in main to set the right file for the component source (e.g., set(COMPONENT_SRCS \"main.cpp\") ). Run make again to be sure that your program still compiles and that you didn't break anything.","title":"Starting a New ESP32 Project"},{"location":"tutorials/esp32/#making-a-simple-dsp-engine","text":"Let's now write a simple Faust program (the usual one haha) implementing a band limited sawtooth wave with smoothed control: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.sawtooth(freq)*gain; Save it in a file called FaustSawtooth.dsp (this will define the name of the corresponding DSP engine) and compile it using faust2esp32 by running the following command: faust2esp32 -lib FaustSawtooth.dsp -lib asks to generate a C++ DSP engine here as opposed to a complete firmware. Note: the current version of faust2esp32 only allows to generate DSP engines (not complete ESP32 programs) so the -lib option is not really necessary here. Alternatively, this could be done by selecting the ESP32 target in the Faust compilation service in the online IDE . In both cases, a .zip package containing a set of C++ files will be returned. In the current example, FaustSawtooth.[cpp/h] implement the Faust DSP object produced from FaustSawtooth.dsp and WM8978.[cpp/h] is the object corresponding to the audio codec of your board. Note: in the current version of faust2esp32 , the only supported audio codecs are the WM8978 ( -WM8978 option) which is that of the TTGO T-Audio board and the AC101 ( -AC101 option). All these files should be placed in the main folder of the project. After that, they should be included to main.cpp as follows: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); }","title":"Making a Simple DSP Engine"},{"location":"tutorials/esp32/#configuring-the-audio-codec","text":"Next, the WM8978 object (which corresponds to the audio codec, i.e., audio interface on the board) should be instantiated and configured in app_main : WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); Once again, the current version of faust2esp32 only provides support for the Wolfson WM8978 present on the TTGO T-Audio and the AC101, but we're working at adding new codecs from other manufacturers, etc. The procedure should be similar with other codecs. The present configuration activates the mic input, deactivates the amp for the speaker, sets the headphone gain to 40, etc. Please refer to the WM8978 object documentation for more information. Note that each of these commands will be called \"in real-time\" at start-up so the configuration of the audio codec is progressively done and should be carried out before sending any audio buffer to it.","title":"Configuring the Audio Codec"},{"location":"tutorials/esp32/#instantiating-the-faust-dsp-engine","text":"After configuring the audio codec, the Faust DSP object produced in the previous step and included in main.cpp should be instantiated in app_main as well: int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); The constructor of FaustSawtooth takes two arguments: the sampling rate (48kHz here) and the block size (8 here). Calling the constructor will configure the object, allocate memory for it, etc. but in order to start computation, the start() method needs to be called. Since ESP32 firmwares are based on freertos , audio is computed in its own high priority task and calling start() will launch this task. Note that this task can be removed and audio computation stopped at any time simply by calling stop() . Finally, the setParamValue method of the FaustSawtooth object can be called at any point to change the value of one of the parameter of the Faust object (here, two parameters were declared: freq and gain ). For example, the frequency of the generated sawtooth could be randomly changed at every sample by calling the following line in the while loop at the bottom of app_main : faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); At this point, main.cpp should look like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } void app_main(void) { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); while(1) { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); vTaskDelay(1000 / portTICK_PERIOD_MS); } } Try to recompile the firmware and upload it to your board. If headphones are connected to it, you should hear a sawtooth wave whose frequency changes randomly every second.","title":"Instantiating the Faust DSP Engine"},{"location":"tutorials/esp32/#using-the-external-ram-of-the-esp32","text":"Some DSP algorithms might require a large amount of memory allocation (e.g., wave tables, delays, etc.). In that case, the object generated by Faust might not fit in the built-in RAM of the ESP32 and it might be necessary to use the external RAM module (SRAM) of the board. In order to test this, we first need to write a Faust program that will need a large amount of memory. Replacing the sawtooth wave of the previous example by a sine wave should do it since the default sine wave oscillator of Faust ( os.osc ) is based on a wave table of size 65536: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.osc(freq)*gain; You can then follow the same steps as the ones described in the Making a Simple DSP Engine section to integrate this Faust program to your C++ ESP32 project. If you try to compile your firmware again (i.e., make ), you should get the following error during linking : [...]/xtensa-esp32-elf/bin/ld: hello-world.elf section `.dram0.bss' will not fit in region `dram0_0_seg' [...]/xtensa-esp32-elf/bin/ld: DRAM segment data does not fit. [...]/xtensa-esp32-elf/bin/ld: region `dram0_0_seg' overflowed by 93408 bytes collect2: error: ld returned 1 exit status To solve this problem, the external RAM can be integrated to the memory map of the ESP32. To do so, run make menuconfig and navigate to Component Config/ESP32-specific . Then activate Support for external RAM, SPI-Connected RAM by highlighting this zone and pressing the y key. Enter the SPI RAM config/SPI RAM access method menu and choose Integrate RAM into ESP32 memory map . Then select Allow .bss segment placed in external memory and press the y key to activate this function. Finally, open FaustSawtooth.cpp (even though we're trying to synthesize a sine wave now, i.e., the name of this file might differ in your case) and search for static float ftbl0mydspSIG0 which is the static table that will be filled with the sine wave table. This section of the C++ code generated by the Faust compiler will always contain large tables requiring lots of memory. You now want to add the EXT_RAM_ATTR attribute next to the table definition: static float ftbl0mydspSIG0[65536] EXT_RAM_ATTR; It indicates the C++ compiler that this static table should be placed in the external memory rather than in the built-in one. In case your Faust program is doing something else than synthesizing a sine wave, you might have to put this attribute in each table definition. Note: We're currently modifying the Faust compiler to automatize this process when a specific option is given to it. Finally, try to recompile your firmware and it should all work nicely now!","title":"Using the External RAM of the ESP32"},{"location":"tutorials/esp32/#using-the-arduino-development-environment","text":"The final source code of this tutorial can be found here . The Arduino development environment can also be used to program the ESP32. The steps to use a Faust-generated DSP engine in that context are quite similar to that of the C++ environment described in the previous section . First, make sure that the esp32 package is installed in the Arduino Boards Manager ( Tools/Board/Boards Manager ). Next, create a new empty project and save it. You can then follow the same steps as the one described in the Making a Simple DSP Engine section of the previous tutorial, however you should place the FaustSawtooth.[cpp/h] and WM8978.[cpp/h] files in the same folder as the one containing the .ino file of your project. Hence, the tree of your project folder should now look like this: esp32Tuto.ino FaustSawtooth.cpp FaustSawtooth.h WM8978.cpp WM8978.h You can then edit your Arduino program as follows: #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth(48000,8); void setup() { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); faustSawtooth.start(); } void loop() { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); delay(1000); } and the resulting firmware should have the same effect as the one presented in the previous C++ tutorial . You can refer to the Configuring the Audio Codec section to get more information of what the WM8978 lines are doing, etc.","title":"Using the Arduino Development Environment"},{"location":"tutorials/jsfx/","text":"Using Faust in JSFX In this tutorial, we present how Faust can be used with JSFX , a scripting language used in Reaper . The JSFX engine is integrated in Reaper by default, and can also be found as a plugin opcode for Csound, as well as a set of standalone projects : ysfx , jsusfx . The JSFX language is based on Cockos EEL2 open-source programming language. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for JSFX users who want to discover Faust. Using command line tools Generating JSFX code Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The JSFX code can be generated using faust -lang jsfx osc.dsp -o osc.jsfx This will generate JSFX code that follows the standard JSFX file structure: @init // init section @block // control section @slider // called when a control value changes @sample // audio computation section This code can be directly imported in Reaper or placed in Reaper Effects directory. Generated JSFX plugin in Reaper The generated code is fully self-contained and can be directly imported as a Reaper JSFX audio plugin, on any supported platform. At the top of the generated file, a few lines are dedicated to report file description and metadata. Then, the initialization starts with: Sliders Inputs and outputs slider1:fHslider0=1000<20,3000,1>hslider_freq10 slider2:fHslider2=200<20,3000,1>hslider_freq20 slider3:fHslider1=0<-96,0,0.1>hslider_volume0 out_pin:output0 out_pin:output1 In JSFX, sliders are the only available controls that match Faust controls. It has been decided that buttons and checkboxes are thus represented as 0-1 sliders in JSFX. Next, the @init section starts with all required functions - including math functions missing in JSFX and memory management functions. These functions will always be included in generated JSFX code, since the rest of the code requires it. The @init section then defines a few constants (bitmasks for MIDI processing, and useful constants for processing like number of voices nvoices ). The actual DSP part starts right after these constants. Global tables are then allocated, here the table where sine waveform will be computed: ftbl0mydspSIG0 = MEMORY.alloc_memory(65536); And the structure of our DSP class is defined. Since JSFX is not a real object oriented programming language, we use indexes inside memory chunks to access DSP object members. Each object itself is represented as an address in JSFX preallocated memory. The dsp. fields indicate the position of members inside the object memory. // DSP struct memory layout dsp.memory = MEMORY.alloc_memory(0); ddsp.size = 24; dsp.iVec1 = 0; dsp.fHslider0 = 2; dsp.fSampleRate = 3; dsp.fConst1 = 4; dsp.fRec1 = 5; dsp.fConst2 = 7; dsp.fConst3 = 8; dsp.fHslider1 = 9; dsp.fRec2 = 10; dsp.fHslider2 = 12; dsp.fRec3 = 13; dsp.iVec0 = 15; dsp.iRec0 = 17; dsp.fSlow0 = 19; dsp.fSlow1 = 20; dsp.fSlow2 = 21; dsp.output0 = 22; dsp.output1 = 23; The next part consists in two functions used to create DSP objects, allocate their memory and initialize their states. One object represents one voice. If an object has no [nvoices] metadata, or if [nvoices:1] , only one object will be created. The create_instance function allocates memory, then init_instances precomputes object state, including constants and everything that doesn't need to be computed at runtime. Finally, the @init section defines the control function. This function corresponds to the computation happening just before the audio loop in the C++ backend. These correspond to the computations related to controls and MIDI. In JSFX sandboxed context, we don't need to call it on every loop, thus it has been pushed outside of @block . Moreover, this computation must be accessible from both @slider and @block . The current implementation will trigger a call to control function everytime a slider value changes, or everytime a MIDI input event happens. By default, the @block section is empty. It will be filled with code if MIDI is somehow enabled: by associating MIDI input to a control in slider metadata [keyon:64] by setting polyphonic mode with declare options [\"nvoices:4\"] The former will actually connect MIDI key or ctrl to the slider, while the latter will connect MIDI note inputs to sliders named freq , key , vel , gain , gate , and will convert the MIDI value to whatever it is supposed to represent: frequency for freq , raw MIDI note number for \"key\" (...). The @block section contains a condition so that it will only call the control function when MIDI events occur. The \u0300 @slider section only calls control , and is itself only computed when a slider value changes. Finally, the @sample section is where the magic happens. It will loop through the different objects and compute the audio output. This section is represented in JSFX as a block of code called for every single sample. At the bottom of generated code, object outputs are summed in JSFX special variables spl0 , spl1 (...), which are the actual outputs of a JSFX plugin. MIDI basic example Basic MIDI inputs can be retrieved with controls (Faust sliders) if specific metadata are added to the control name. The available MIDI inputs are: keyon keyoff key (both keyon and keyoff) ctrl See MIDI for more information about MIDI metadata syntax. The generated code will contain a @block section that connects MIDI CC input (for CC 10 and 11) to relevant control values. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == CC) ? ( midi_event += 1; (msg2 == 0xa) ? (fHslider1 = midi_scale(msg3, 0.0000000000000000, 127.0000000000000000, 1.0000000000000000)); (msg2 == 0xb) ? (fHslider0 = midi_scale(msg3, 50.0000000000000000, 1000.0000000000000000, 0.1000000000000000)); ); ); (midi_event > 0) ? (control()); MIDI polyphonic example As explained in the MIDI documentation, Faust supports MIDI polyphonic audio plugins. These plugins respond to MIDI note inputs with three different data: key or frequency velocity or gain a gate used to trigger an envelope Be careful that key will be a value between 0-127 while frequency will be converted to cycle per seconds. Same mechanism applies to velocity (0-127) versus gain (0-1). The following code shows the basic mechanism of the MIDI polyphonic instrument that compiles for JSFX. In this JSFX backend, polyphonic voices use a voice stealing mechanism, allowing a new voice to steal the oldest one if no voice is free. The generated code contains a filled @block section that is used to look for MIDI input notes midirecv , thus performing expected actions: a NOTE ON message looks for an available voice (or steals the oldest one if necessary) and sets its controls a NOTE OFF message looks for the voice that is playing its key to turn its gate off. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == NOTE_ON) ? ( midi_event += 1; voice_idx = get_oldest_voice(); sort_voices(voice_idx); obj = get_dsp(voice_idx); obj[dsp.key_id] = msg2; obj[dsp.gate] = 1; obj[dsp.fCheckbox0] = 1; obj[dsp.fHslider1] = midi_scale(msg3, 0.0000000000000000, 1.0000000000000000, 0.0100000000000000); obj[dsp.fHslider0] = limit(mtof(msg2), 0.0000000000000000, 10000.0000000000000000); ); // NOTE ON condition off (status == NOTE_OFF) ? ( midi_event += 1; voice_idx = 0; while(voice_idx < nvoices) ( obj = get_dsp(voice_idx); (obj[dsp.key_id] == msg2 && obj[dsp.gate] > 0) ? ( obj[dsp.gate] = 0; obj[dsp.fCheckbox0] = 0; voice_idx = nvoices; ); voice_idx += 1; ); // end of while ); // end of condition ); (midi_event > 0) ? (control()); Using the Faust Web IDE Generating a JSFX file The JSFX backend is available on the Faust web IDE . In order to export a Faust program as JSFX code, you will need to click on the \"export/compile to specific target\" button (on the left side, below \"Save as\"). Then, you need to choose jsfx both as the platform and architecture, and click compile . This will allow your to download a binary.zip file, containing the resulting jsfx file and your original dsp file. Generating a JSFX file in polyphonic mode The declare options \"[midi:on][nvoices:n]\"; coding convention can be used in the DSP code to activate MIDI and polyphonic mode. Limitations As JSFX is a sandboxed environment, this backend cannot match the full Faust potential. Some features are missing, some others might come in the future. First, only three controls are available: sliders: hslider, vslider, nentry button checkbox All of these are mapped to sliders in JSFX. On the MIDI side, this backend does not support program changes, neither channel press, or pitchweel. As described before, the available MIDI is key, keyon, keyoff, ctrl and polyphonic mode.","title":"Using Faust in JSFX"},{"location":"tutorials/jsfx/#using-faust-in-jsfx","text":"In this tutorial, we present how Faust can be used with JSFX , a scripting language used in Reaper . The JSFX engine is integrated in Reaper by default, and can also be found as a plugin opcode for Csound, as well as a set of standalone projects : ysfx , jsusfx . The JSFX language is based on Cockos EEL2 open-source programming language.","title":"Using Faust in JSFX"},{"location":"tutorials/jsfx/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for JSFX users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/jsfx/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/jsfx/#generating-jsfx-code","text":"Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The JSFX code can be generated using faust -lang jsfx osc.dsp -o osc.jsfx This will generate JSFX code that follows the standard JSFX file structure: @init // init section @block // control section @slider // called when a control value changes @sample // audio computation section This code can be directly imported in Reaper or placed in Reaper Effects directory. Generated JSFX plugin in Reaper The generated code is fully self-contained and can be directly imported as a Reaper JSFX audio plugin, on any supported platform. At the top of the generated file, a few lines are dedicated to report file description and metadata. Then, the initialization starts with: Sliders Inputs and outputs slider1:fHslider0=1000<20,3000,1>hslider_freq10 slider2:fHslider2=200<20,3000,1>hslider_freq20 slider3:fHslider1=0<-96,0,0.1>hslider_volume0 out_pin:output0 out_pin:output1 In JSFX, sliders are the only available controls that match Faust controls. It has been decided that buttons and checkboxes are thus represented as 0-1 sliders in JSFX. Next, the @init section starts with all required functions - including math functions missing in JSFX and memory management functions. These functions will always be included in generated JSFX code, since the rest of the code requires it. The @init section then defines a few constants (bitmasks for MIDI processing, and useful constants for processing like number of voices nvoices ). The actual DSP part starts right after these constants. Global tables are then allocated, here the table where sine waveform will be computed: ftbl0mydspSIG0 = MEMORY.alloc_memory(65536); And the structure of our DSP class is defined. Since JSFX is not a real object oriented programming language, we use indexes inside memory chunks to access DSP object members. Each object itself is represented as an address in JSFX preallocated memory. The dsp. fields indicate the position of members inside the object memory. // DSP struct memory layout dsp.memory = MEMORY.alloc_memory(0); ddsp.size = 24; dsp.iVec1 = 0; dsp.fHslider0 = 2; dsp.fSampleRate = 3; dsp.fConst1 = 4; dsp.fRec1 = 5; dsp.fConst2 = 7; dsp.fConst3 = 8; dsp.fHslider1 = 9; dsp.fRec2 = 10; dsp.fHslider2 = 12; dsp.fRec3 = 13; dsp.iVec0 = 15; dsp.iRec0 = 17; dsp.fSlow0 = 19; dsp.fSlow1 = 20; dsp.fSlow2 = 21; dsp.output0 = 22; dsp.output1 = 23; The next part consists in two functions used to create DSP objects, allocate their memory and initialize their states. One object represents one voice. If an object has no [nvoices] metadata, or if [nvoices:1] , only one object will be created. The create_instance function allocates memory, then init_instances precomputes object state, including constants and everything that doesn't need to be computed at runtime. Finally, the @init section defines the control function. This function corresponds to the computation happening just before the audio loop in the C++ backend. These correspond to the computations related to controls and MIDI. In JSFX sandboxed context, we don't need to call it on every loop, thus it has been pushed outside of @block . Moreover, this computation must be accessible from both @slider and @block . The current implementation will trigger a call to control function everytime a slider value changes, or everytime a MIDI input event happens. By default, the @block section is empty. It will be filled with code if MIDI is somehow enabled: by associating MIDI input to a control in slider metadata [keyon:64] by setting polyphonic mode with declare options [\"nvoices:4\"] The former will actually connect MIDI key or ctrl to the slider, while the latter will connect MIDI note inputs to sliders named freq , key , vel , gain , gate , and will convert the MIDI value to whatever it is supposed to represent: frequency for freq , raw MIDI note number for \"key\" (...). The @block section contains a condition so that it will only call the control function when MIDI events occur. The \u0300 @slider section only calls control , and is itself only computed when a slider value changes. Finally, the @sample section is where the magic happens. It will loop through the different objects and compute the audio output. This section is represented in JSFX as a block of code called for every single sample. At the bottom of generated code, object outputs are summed in JSFX special variables spl0 , spl1 (...), which are the actual outputs of a JSFX plugin.","title":"Generating JSFX code"},{"location":"tutorials/jsfx/#midi-basic-example","text":"Basic MIDI inputs can be retrieved with controls (Faust sliders) if specific metadata are added to the control name. The available MIDI inputs are: keyon keyoff key (both keyon and keyoff) ctrl See MIDI for more information about MIDI metadata syntax. The generated code will contain a @block section that connects MIDI CC input (for CC 10 and 11) to relevant control values. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == CC) ? ( midi_event += 1; (msg2 == 0xa) ? (fHslider1 = midi_scale(msg3, 0.0000000000000000, 127.0000000000000000, 1.0000000000000000)); (msg2 == 0xb) ? (fHslider0 = midi_scale(msg3, 50.0000000000000000, 1000.0000000000000000, 0.1000000000000000)); ); ); (midi_event > 0) ? (control());","title":"MIDI basic example"},{"location":"tutorials/jsfx/#midi-polyphonic-example","text":"As explained in the MIDI documentation, Faust supports MIDI polyphonic audio plugins. These plugins respond to MIDI note inputs with three different data: key or frequency velocity or gain a gate used to trigger an envelope Be careful that key will be a value between 0-127 while frequency will be converted to cycle per seconds. Same mechanism applies to velocity (0-127) versus gain (0-1). The following code shows the basic mechanism of the MIDI polyphonic instrument that compiles for JSFX. In this JSFX backend, polyphonic voices use a voice stealing mechanism, allowing a new voice to steal the oldest one if no voice is free. The generated code contains a filled @block section that is used to look for MIDI input notes midirecv , thus performing expected actions: a NOTE ON message looks for an available voice (or steals the oldest one if necessary) and sets its controls a NOTE OFF message looks for the voice that is playing its key to turn its gate off. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == NOTE_ON) ? ( midi_event += 1; voice_idx = get_oldest_voice(); sort_voices(voice_idx); obj = get_dsp(voice_idx); obj[dsp.key_id] = msg2; obj[dsp.gate] = 1; obj[dsp.fCheckbox0] = 1; obj[dsp.fHslider1] = midi_scale(msg3, 0.0000000000000000, 1.0000000000000000, 0.0100000000000000); obj[dsp.fHslider0] = limit(mtof(msg2), 0.0000000000000000, 10000.0000000000000000); ); // NOTE ON condition off (status == NOTE_OFF) ? ( midi_event += 1; voice_idx = 0; while(voice_idx < nvoices) ( obj = get_dsp(voice_idx); (obj[dsp.key_id] == msg2 && obj[dsp.gate] > 0) ? ( obj[dsp.gate] = 0; obj[dsp.fCheckbox0] = 0; voice_idx = nvoices; ); voice_idx += 1; ); // end of while ); // end of condition ); (midi_event > 0) ? (control());","title":"MIDI polyphonic example"},{"location":"tutorials/jsfx/#using-the-faust-web-ide","text":"","title":"Using the Faust Web IDE"},{"location":"tutorials/jsfx/#generating-a-jsfx-file","text":"The JSFX backend is available on the Faust web IDE . In order to export a Faust program as JSFX code, you will need to click on the \"export/compile to specific target\" button (on the left side, below \"Save as\"). Then, you need to choose jsfx both as the platform and architecture, and click compile . This will allow your to download a binary.zip file, containing the resulting jsfx file and your original dsp file.","title":"Generating a JSFX file"},{"location":"tutorials/jsfx/#generating-a-jsfx-file-in-polyphonic-mode","text":"The declare options \"[midi:on][nvoices:n]\"; coding convention can be used in the DSP code to activate MIDI and polyphonic mode.","title":"Generating a JSFX file in polyphonic mode"},{"location":"tutorials/jsfx/#limitations","text":"As JSFX is a sandboxed environment, this backend cannot match the full Faust potential. Some features are missing, some others might come in the future. First, only three controls are available: sliders: hslider, vslider, nentry button checkbox All of these are mapped to sliders in JSFX. On the MIDI side, this backend does not support program changes, neither channel press, or pitchweel. As described before, the available MIDI is key, keyon, keyoff, ctrl and polyphonic mode.","title":"Limitations"},{"location":"tutorials/julia/","text":"Using Faust in Julia In this tutorial, we present how Faust can be used in Julia , a high-level, high-performance, dynamic programming language. While it is a general-purpose language and can be used to write any application, many of its features are well suited for numerical analysis and computational science. An integration of the libfaust compiler in Julia has been firstly developed by Cora Johnson-Roberson , and will be covered by the last section of the tutorial . Then a Julia backend has been added in a second step in the Faust compiler. It allows to generate ready to use Julia code from any Faust DSP program. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section and third section are better suited for Julia users who want to discover Faust. Installing the required packages Be sure to have the julia command available in your PATH, as explained here . With a fresh Julia install, all required packages are decribed in the packages.jl file: in case you have an installed Faust version, it can be installed with the julia packages.jl command done in the architecture/julia folder of the Faust repository of directly downloaded, and executed with the julia packages.jl command Using command line tools Generating Julia code Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The Julia code can be generated using: faust -lang julia osc.dsp -o osc.jl This will generate a mydsp{T} data structure, as a subtype of the abstract type dsp , with a set of methods to manipulate it. The generated API simply follows the one defined for the base dsp type. This API basically mimics the one defined for the C++ backend . The resulting file is not self-contained and so cannot be directly compiled using the julia program: julia osc.jl ERROR: LoadError: UndefVarError: dsp not defined ... Some additional types like FAUSTFLOAT , dsp , Meta and UI have to be defined in a so-called architecture files . The Julia specific ones are described here . A simple one named minimal.jl can be used for that with the following command: faust -lang julia osc.dsp -a julia/minimal.jl -o osc.jl Now the resulting foo.jl file is self-contained and can be executed with: julia -i osc.jl (here -i to stay in interactive mode) Which compiles the Julia code, executes it and produces: Application name: osc getNumInputs: 0 getNumOutputs: 2 Path/UIZone dictionary: Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) With the name of the application, the number of input/output channels, the set of controller paths with their range, and a display of the first samples of the computed outputs (using the powerful Plots.jl package), and showing here the effect of the si.smoo at the beginning of the signals: Displaying the outputs Looking at the generated code A mydsp{T} data structure, as a subtype of the abstract type dsp is generated, and contains the field definitions with their types, as well as a constructor initializing them: mutable struct mydsp{T} <: dsp fSampleRate::Int32 fConst1::T fHslider0::FAUSTFLOAT fConst2::T fRec0::Vector{T} fConst3::T fHslider1::FAUSTFLOAT fRec2::Vector{T} fHslider2::FAUSTFLOAT fRec3::Vector{T} iVec0::Vector{Int32} iRec1::Vector{Int32} ftbl0mydspSIG0::Vector{T} mydsp{T}() where {T} = begin dsp = new{T}() dsp.fRec0 = zeros(T, 2) dsp.fRec2 = zeros(T, 2) dsp.fRec3 = zeros(T, 2) dsp.iVec0 = zeros(Int32, 2) dsp.iRec1 = zeros(Int32, 2) dsp.ftbl0mydspSIG0 = zeros(T, 65536) dsp end end Note that the structure is parametrized with a {T} type to be given at initialization time. The const REAL = Float32 or const REAL = Float64 line is generated depending of the -single (default), or -double option given at compilation time, and can be used for that. Several access methods are generated: function getNumInputs(dsp::mydsp{T}) where {T} return Int32(0) end function getNumOutputs(dsp::mydsp{T}) where {T} return Int32(2) end Several initialiation methods like init! , initanceInit! , instanceResetUserInterface! etc. are generated, here is one of them: function instanceResetUserInterface!(dsp::mydsp{T}) where {T} dsp.fHslider0 = FAUSTFLOAT(0.0f0) dsp.fHslider1 = FAUSTFLOAT(1000.0f0) dsp.fHslider2 = FAUSTFLOAT(200.0f0) end The buildUserInterface! method uses a UI subtype to build a controller, which could be a Graphical User Interface (for instance using GTK ), or an OSC controller: function buildUserInterface!(dsp::mydsp{T}, ui_interface::UI) where {T} openVerticalBox!(ui_interface, \"Oscillator\") declare!(ui_interface, :fHslider1, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq1\", :fHslider1, FAUSTFLOAT(1000.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider2, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq2\", :fHslider2, FAUSTFLOAT(500.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider0, \"unit\", \"dB\") addHorizontalSlider!(ui_interface, \"volume\", :fHslider0, FAUSTFLOAT(0.0f0), FAUSTFLOAT(-96.0f0), FAUSTFLOAT(0.0f0), FAUSTFLOAT(0.1f0)) closeBox!(ui_interface) end The DSP structure fields to access are simply described with their name (actually a Symbol in Julia terminology), and can later be used with the standard setproperty! and getproperty access methods, like in the setParamValue! and getParamValue methods written in the MapUI architecture. And finally the compute! method that processes and input buffer with count frames to produce an output buffer: @inbounds function compute!(dsp::mydsp, count::Int32, inputs, outputs) output0 = @inbounds @view outputs[:, 1] output1 = @inbounds @view outputs[:, 2] fSlow0::Float32 = (dsp.fConst1 * pow(10.0f0, (0.0500000007f0 * Float32(dsp.fHslider0)))) fSlow1::Float32 = (dsp.fConst3 * Float32(dsp.fHslider1)) fSlow2::Float32 = (dsp.fConst3 * Float32(dsp.fHslider2)) @inbounds for i0 in 0:count-1 dsp.fRec0[1] = (fSlow0 + (dsp.fConst2 * dsp.fRec0[2])) dsp.fRec2[1] = (fSlow1 + (dsp.fRec2[2] - floor((fSlow1 + dsp.fRec2[2])))) output0[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec2[1]))+1])) dsp.fRec3[1] = (fSlow2 + (dsp.fRec3[2] - floor((fSlow2 + dsp.fRec3[2])))) output1[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec3[1]))+1])) dsp.fRec0[2] = dsp.fRec0[1] dsp.fRec2[2] = dsp.fRec2[1] dsp.fRec3[2] = dsp.fRec3[1] end end Note that not all generated methods are presented in this short presentation. Look at the generated osc.jl file to see all of them. Using the generated code Some globals have to be defined: # Testing samplerate = Int32(44100) block_size = Int32(16) The DSP object has to be created and initialized, here using the generated REAL type alias: # Init DSP my_dsp = mydsp{REAL}() init!(my_dsp, samplerate) His name can be extracted from the DSP metadata using the following code: # Retrieve the application name mutable struct NameMeta <: Meta name::String end function declare!(m::NameMeta, key::String, value::String) if (key == \"name\") m.name = value; end end) m = NameMeta(\"\") metadata!(my_dsp, m) println(\"Application name: \", m.name, \"\\n\") The number of inputs/outputs can be printed: println(\"getNumInputs: \", getNumInputs(my_dsp)) println(\"getNumOutputs: \", getNumOutputs(my_dsp), \"\\n\") Information on all controllers can be retrieved using the MapUI type: # Create a MapUI controller map_ui = MapUI(my_dsp) buildUserInterface!(my_dsp, map_ui) # Print all zones println(\"Path/UIZone dictionary: \", getZoneMap(map_ui), \"\\n\") And finally one buffer can be processed with the following code, here giving FAUSTFLOAT as the actual type for external samples: inputs = zeros(FAUSTFLOAT, block_size, getNumInputs(my_dsp)) outputs = zeros(FAUSTFLOAT, block_size, getNumOutputs(my_dsp)) compute!(my_dsp, block_size, inputs, outputs) println(\"One computed output buffer: \", outputs) Now the osc.jl can possibly be directly integrated in a larger project, or customized using an adapted new architecture file. The faust2portaudiojulia tool The Faust DSP program can be compiled and run with the more sophisticated faust2portaudiojulia tool which will render it using the PortAudio.jl package to access the audio driver, OpenSoundControl.jl package for OSC control, and GTK.jl package for the Graphical User Interface. The faust2portaudiojulia tool use this portaudio_gtk.jl architecture file. When used the following way: faust2portaudiojulia osc.dsp It creates an osc.jl file that can simply be executed using: julia osc.jl So the stereo program generating sinewaves at 1000 Hz and 200 Hz by default is now playing, without any interface to control it. Now using the following command: faust2portaudiojulia -play 2 osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and GTK GUI (and with 2 threads needed for GTK and audio). Note that the GUI is still quite simple: The GTK based controller The following command: faust2portaudiojulia -play 2 -osc osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and OSC control (and with 2 threads needed for OSC and audio). Now the application starts with an OSC controller running on ports 5000 and 5001: getNumInputs: 0 getNumOutputs: 2 Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 500.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) Faust OSC application 'Oscillator' is running on UDP ports 5000, 5001 Direct OSC commands can be sent, as explained here . So for instance to change both channel frequencies: oscsend localhost 5000 /Oscillator/freq1 f 400 oscsend localhost 5000 /Oscillator/freq2 f 960 You can possibly use the faust-osc-controller tool to remotely control the Julia program, with the following command: faust-osc-controller /Oscillator -port 5001 -outport 5000 -xmit 1 The faust-osc-controller OSC controller And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the faust2portaudiojulia -play 2 -oscc osc.dsp command. Using the Faust Web IDE Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Julia code, or possibly as working audio applications. Generating the pure Julia output The output of the Julia backend can directly be generated using the Platform = source and Architecture = julia export options. As previously explained, the resulting file is not self-contained, but shows the code which has to be wrapped with adapted Julia architecture files. Exporting the code Generating a minimal working Julia file The Platform = julia and Architecture = julia export options allow to generate a self-contained file using the minimal.jl architecture, to be by started with the following command: julia -i foo.jl (here -i to stay in interactive mode) Generating an audio application controllable with GTK or OSC based interfaces The Platform = julia and Architecture = portaudiojulia export options allow to generate a self-contained file using the portaudio_gtk.jl architecture. The following command starts the program with the GTK control interface: julia -t 2 foo.jl -gtk The following command starts the program with the OSC control interface, ready to receive OSC commands or controlled with the faust-osc-controller tool as previously explained: julia -t 2 foo.jl -osc And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the following command: julia -t 2 foo.jl -oscc Using the Faust.jl Julia package The Julia ecosystem contains over 4,000 packages that are registered in the General registry . A Faust.lj package initially developed by Cora Johnson-Roberson , has been forked and extended here . It allows the use of the libfaust library and the Julia Faust backend. The Visual Studio Code application can be configurated with a Julia extension . It is a very convenient way to edit, compile and test Julia + Faust code. Installing the forked Faust.jl package In VS Code, you can enter the package mode . Pkg comes with a REPL. Enter the Pkg REPL by pressing ] from the Julia REPL and install the Faust package with: pkg> add https://github.com/sletz/Faust.jl To get back to the Julia REPL, press backspace or ^C, then load the Faust package with: julia> using Faust Assuming a working Julia environment is setup, the following commands can be used. Using the libfaust compiler # Create a DSP factory. dsp = compile(\"\"\" import(\"stdfaust.lib\"); freq = hslider(\"freq\", 440, 20, 20000, 1); gain = hslider(\"gain\", 0.25, 0, 1, 0.001); process = os.oscs(freq) * gain; \"\"\") # Initialize DSP instance and controls. init!(dsp; block_size=1024, samplerate=48000) # Compute one block of audio. compute!(dsp) By default, programs are compiled as single-precision; you can give -double or other arguments to the compiler like so: compile(\"process = _;\"; name=\"passthrough\", argv=[\"-double\", \"-vec\"]) Each call to compute! will calculate block_size samples and return the output as a matrix of (block_size, n_channels). If the program takes input, set dsp.inputs to a (block_size, n_channels) matrix before calling compute! : passthrough = init!(compile(\"process = _,_;\")) x = rand(Float32, 256, 2) passthrough.inputs = x @test compute!(passthrough) == x After calling init! , any UI elements declared in your code will have their path names and ranges available via dsp.ui.ranges . julia> dsp.ui.ranges Dict{String, Faust.UIRange} with 2 entries: \"/score/gain\" => UIRange(0.25, 0.0, 1.0, 0.001) \"/score/freq\" => UIRange(440.0, 20.0, 20000.0, 1.0) julia> ctrl = dsp.ui.ranges[\"/score/freq\"]; (ctrl.min, ctrl.max) (20.0f0, 20000.0f0) One can then set the values of these params like: setparams!(dsp, Dict(\"/score/freq\" => 220.0f0)) Displaying signals Julia offers a lot of packages to display signals, for example with the following commands ( coded here ) to display the outputs buffers: # Define a block of DSP code julia> code = \"\"\"import(\"stdfaust.lib\"); process = os.osc(500), os.sawtooth(1000);\"\"\" # Compile the DSP, compute one block of audio and display the outputs julia> compileFaustString(code) # Compile the DSP, with additional compiler arguments and display the outputs julia> compileFaustString(code; argv=[\"-double\", \"-vec\"]) # Compile the DSP, with a larger block_size and display the outputs julia> compileFaustString(code; block_size=50000) With the following result in VS code: Using Julia in VS code More sophisticated analysis can be done, like this example , or this projet to experiment using NNs in Faust .","title":"Using Faust in Julia"},{"location":"tutorials/julia/#using-faust-in-julia","text":"In this tutorial, we present how Faust can be used in Julia , a high-level, high-performance, dynamic programming language. While it is a general-purpose language and can be used to write any application, many of its features are well suited for numerical analysis and computational science. An integration of the libfaust compiler in Julia has been firstly developed by Cora Johnson-Roberson , and will be covered by the last section of the tutorial . Then a Julia backend has been added in a second step in the Faust compiler. It allows to generate ready to use Julia code from any Faust DSP program.","title":"Using Faust in Julia"},{"location":"tutorials/julia/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section and third section are better suited for Julia users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/julia/#installing-the-required-packages","text":"Be sure to have the julia command available in your PATH, as explained here . With a fresh Julia install, all required packages are decribed in the packages.jl file: in case you have an installed Faust version, it can be installed with the julia packages.jl command done in the architecture/julia folder of the Faust repository of directly downloaded, and executed with the julia packages.jl command","title":"Installing the required packages"},{"location":"tutorials/julia/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/julia/#generating-julia-code","text":"Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The Julia code can be generated using: faust -lang julia osc.dsp -o osc.jl This will generate a mydsp{T} data structure, as a subtype of the abstract type dsp , with a set of methods to manipulate it. The generated API simply follows the one defined for the base dsp type. This API basically mimics the one defined for the C++ backend . The resulting file is not self-contained and so cannot be directly compiled using the julia program: julia osc.jl ERROR: LoadError: UndefVarError: dsp not defined ... Some additional types like FAUSTFLOAT , dsp , Meta and UI have to be defined in a so-called architecture files . The Julia specific ones are described here . A simple one named minimal.jl can be used for that with the following command: faust -lang julia osc.dsp -a julia/minimal.jl -o osc.jl Now the resulting foo.jl file is self-contained and can be executed with: julia -i osc.jl (here -i to stay in interactive mode) Which compiles the Julia code, executes it and produces: Application name: osc getNumInputs: 0 getNumOutputs: 2 Path/UIZone dictionary: Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) With the name of the application, the number of input/output channels, the set of controller paths with their range, and a display of the first samples of the computed outputs (using the powerful Plots.jl package), and showing here the effect of the si.smoo at the beginning of the signals: Displaying the outputs","title":"Generating Julia code"},{"location":"tutorials/julia/#looking-at-the-generated-code","text":"A mydsp{T} data structure, as a subtype of the abstract type dsp is generated, and contains the field definitions with their types, as well as a constructor initializing them: mutable struct mydsp{T} <: dsp fSampleRate::Int32 fConst1::T fHslider0::FAUSTFLOAT fConst2::T fRec0::Vector{T} fConst3::T fHslider1::FAUSTFLOAT fRec2::Vector{T} fHslider2::FAUSTFLOAT fRec3::Vector{T} iVec0::Vector{Int32} iRec1::Vector{Int32} ftbl0mydspSIG0::Vector{T} mydsp{T}() where {T} = begin dsp = new{T}() dsp.fRec0 = zeros(T, 2) dsp.fRec2 = zeros(T, 2) dsp.fRec3 = zeros(T, 2) dsp.iVec0 = zeros(Int32, 2) dsp.iRec1 = zeros(Int32, 2) dsp.ftbl0mydspSIG0 = zeros(T, 65536) dsp end end Note that the structure is parametrized with a {T} type to be given at initialization time. The const REAL = Float32 or const REAL = Float64 line is generated depending of the -single (default), or -double option given at compilation time, and can be used for that. Several access methods are generated: function getNumInputs(dsp::mydsp{T}) where {T} return Int32(0) end function getNumOutputs(dsp::mydsp{T}) where {T} return Int32(2) end Several initialiation methods like init! , initanceInit! , instanceResetUserInterface! etc. are generated, here is one of them: function instanceResetUserInterface!(dsp::mydsp{T}) where {T} dsp.fHslider0 = FAUSTFLOAT(0.0f0) dsp.fHslider1 = FAUSTFLOAT(1000.0f0) dsp.fHslider2 = FAUSTFLOAT(200.0f0) end The buildUserInterface! method uses a UI subtype to build a controller, which could be a Graphical User Interface (for instance using GTK ), or an OSC controller: function buildUserInterface!(dsp::mydsp{T}, ui_interface::UI) where {T} openVerticalBox!(ui_interface, \"Oscillator\") declare!(ui_interface, :fHslider1, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq1\", :fHslider1, FAUSTFLOAT(1000.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider2, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq2\", :fHslider2, FAUSTFLOAT(500.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider0, \"unit\", \"dB\") addHorizontalSlider!(ui_interface, \"volume\", :fHslider0, FAUSTFLOAT(0.0f0), FAUSTFLOAT(-96.0f0), FAUSTFLOAT(0.0f0), FAUSTFLOAT(0.1f0)) closeBox!(ui_interface) end The DSP structure fields to access are simply described with their name (actually a Symbol in Julia terminology), and can later be used with the standard setproperty! and getproperty access methods, like in the setParamValue! and getParamValue methods written in the MapUI architecture. And finally the compute! method that processes and input buffer with count frames to produce an output buffer: @inbounds function compute!(dsp::mydsp, count::Int32, inputs, outputs) output0 = @inbounds @view outputs[:, 1] output1 = @inbounds @view outputs[:, 2] fSlow0::Float32 = (dsp.fConst1 * pow(10.0f0, (0.0500000007f0 * Float32(dsp.fHslider0)))) fSlow1::Float32 = (dsp.fConst3 * Float32(dsp.fHslider1)) fSlow2::Float32 = (dsp.fConst3 * Float32(dsp.fHslider2)) @inbounds for i0 in 0:count-1 dsp.fRec0[1] = (fSlow0 + (dsp.fConst2 * dsp.fRec0[2])) dsp.fRec2[1] = (fSlow1 + (dsp.fRec2[2] - floor((fSlow1 + dsp.fRec2[2])))) output0[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec2[1]))+1])) dsp.fRec3[1] = (fSlow2 + (dsp.fRec3[2] - floor((fSlow2 + dsp.fRec3[2])))) output1[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec3[1]))+1])) dsp.fRec0[2] = dsp.fRec0[1] dsp.fRec2[2] = dsp.fRec2[1] dsp.fRec3[2] = dsp.fRec3[1] end end Note that not all generated methods are presented in this short presentation. Look at the generated osc.jl file to see all of them.","title":"Looking at the generated code"},{"location":"tutorials/julia/#using-the-generated-code","text":"Some globals have to be defined: # Testing samplerate = Int32(44100) block_size = Int32(16) The DSP object has to be created and initialized, here using the generated REAL type alias: # Init DSP my_dsp = mydsp{REAL}() init!(my_dsp, samplerate) His name can be extracted from the DSP metadata using the following code: # Retrieve the application name mutable struct NameMeta <: Meta name::String end function declare!(m::NameMeta, key::String, value::String) if (key == \"name\") m.name = value; end end) m = NameMeta(\"\") metadata!(my_dsp, m) println(\"Application name: \", m.name, \"\\n\") The number of inputs/outputs can be printed: println(\"getNumInputs: \", getNumInputs(my_dsp)) println(\"getNumOutputs: \", getNumOutputs(my_dsp), \"\\n\") Information on all controllers can be retrieved using the MapUI type: # Create a MapUI controller map_ui = MapUI(my_dsp) buildUserInterface!(my_dsp, map_ui) # Print all zones println(\"Path/UIZone dictionary: \", getZoneMap(map_ui), \"\\n\") And finally one buffer can be processed with the following code, here giving FAUSTFLOAT as the actual type for external samples: inputs = zeros(FAUSTFLOAT, block_size, getNumInputs(my_dsp)) outputs = zeros(FAUSTFLOAT, block_size, getNumOutputs(my_dsp)) compute!(my_dsp, block_size, inputs, outputs) println(\"One computed output buffer: \", outputs) Now the osc.jl can possibly be directly integrated in a larger project, or customized using an adapted new architecture file.","title":"Using the generated code"},{"location":"tutorials/julia/#the-faust2portaudiojulia-tool","text":"The Faust DSP program can be compiled and run with the more sophisticated faust2portaudiojulia tool which will render it using the PortAudio.jl package to access the audio driver, OpenSoundControl.jl package for OSC control, and GTK.jl package for the Graphical User Interface. The faust2portaudiojulia tool use this portaudio_gtk.jl architecture file. When used the following way: faust2portaudiojulia osc.dsp It creates an osc.jl file that can simply be executed using: julia osc.jl So the stereo program generating sinewaves at 1000 Hz and 200 Hz by default is now playing, without any interface to control it. Now using the following command: faust2portaudiojulia -play 2 osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and GTK GUI (and with 2 threads needed for GTK and audio). Note that the GUI is still quite simple: The GTK based controller The following command: faust2portaudiojulia -play 2 -osc osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and OSC control (and with 2 threads needed for OSC and audio). Now the application starts with an OSC controller running on ports 5000 and 5001: getNumInputs: 0 getNumOutputs: 2 Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 500.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) Faust OSC application 'Oscillator' is running on UDP ports 5000, 5001 Direct OSC commands can be sent, as explained here . So for instance to change both channel frequencies: oscsend localhost 5000 /Oscillator/freq1 f 400 oscsend localhost 5000 /Oscillator/freq2 f 960 You can possibly use the faust-osc-controller tool to remotely control the Julia program, with the following command: faust-osc-controller /Oscillator -port 5001 -outport 5000 -xmit 1 The faust-osc-controller OSC controller And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the faust2portaudiojulia -play 2 -oscc osc.dsp command.","title":"The faust2portaudiojulia tool"},{"location":"tutorials/julia/#using-the-faust-web-ide","text":"Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Julia code, or possibly as working audio applications.","title":"Using the Faust Web IDE"},{"location":"tutorials/julia/#generating-the-pure-julia-output","text":"The output of the Julia backend can directly be generated using the Platform = source and Architecture = julia export options. As previously explained, the resulting file is not self-contained, but shows the code which has to be wrapped with adapted Julia architecture files. Exporting the code","title":"Generating the pure Julia output"},{"location":"tutorials/julia/#generating-a-minimal-working-julia-file","text":"The Platform = julia and Architecture = julia export options allow to generate a self-contained file using the minimal.jl architecture, to be by started with the following command: julia -i foo.jl (here -i to stay in interactive mode)","title":"Generating a minimal working Julia file"},{"location":"tutorials/julia/#generating-an-audio-application-controllable-with-gtk-or-osc-based-interfaces","text":"The Platform = julia and Architecture = portaudiojulia export options allow to generate a self-contained file using the portaudio_gtk.jl architecture. The following command starts the program with the GTK control interface: julia -t 2 foo.jl -gtk The following command starts the program with the OSC control interface, ready to receive OSC commands or controlled with the faust-osc-controller tool as previously explained: julia -t 2 foo.jl -osc And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the following command: julia -t 2 foo.jl -oscc","title":"Generating an audio application controllable with GTK or OSC based interfaces"},{"location":"tutorials/julia/#using-the-faustjl-julia-package","text":"The Julia ecosystem contains over 4,000 packages that are registered in the General registry . A Faust.lj package initially developed by Cora Johnson-Roberson , has been forked and extended here . It allows the use of the libfaust library and the Julia Faust backend. The Visual Studio Code application can be configurated with a Julia extension . It is a very convenient way to edit, compile and test Julia + Faust code.","title":"Using the Faust.jl Julia package"},{"location":"tutorials/julia/#installing-the-forked-faustjl-package","text":"In VS Code, you can enter the package mode . Pkg comes with a REPL. Enter the Pkg REPL by pressing ] from the Julia REPL and install the Faust package with: pkg> add https://github.com/sletz/Faust.jl To get back to the Julia REPL, press backspace or ^C, then load the Faust package with: julia> using Faust Assuming a working Julia environment is setup, the following commands can be used.","title":"Installing the forked Faust.jl package"},{"location":"tutorials/julia/#using-the-libfaust-compiler","text":"# Create a DSP factory. dsp = compile(\"\"\" import(\"stdfaust.lib\"); freq = hslider(\"freq\", 440, 20, 20000, 1); gain = hslider(\"gain\", 0.25, 0, 1, 0.001); process = os.oscs(freq) * gain; \"\"\") # Initialize DSP instance and controls. init!(dsp; block_size=1024, samplerate=48000) # Compute one block of audio. compute!(dsp) By default, programs are compiled as single-precision; you can give -double or other arguments to the compiler like so: compile(\"process = _;\"; name=\"passthrough\", argv=[\"-double\", \"-vec\"]) Each call to compute! will calculate block_size samples and return the output as a matrix of (block_size, n_channels). If the program takes input, set dsp.inputs to a (block_size, n_channels) matrix before calling compute! : passthrough = init!(compile(\"process = _,_;\")) x = rand(Float32, 256, 2) passthrough.inputs = x @test compute!(passthrough) == x After calling init! , any UI elements declared in your code will have their path names and ranges available via dsp.ui.ranges . julia> dsp.ui.ranges Dict{String, Faust.UIRange} with 2 entries: \"/score/gain\" => UIRange(0.25, 0.0, 1.0, 0.001) \"/score/freq\" => UIRange(440.0, 20.0, 20000.0, 1.0) julia> ctrl = dsp.ui.ranges[\"/score/freq\"]; (ctrl.min, ctrl.max) (20.0f0, 20000.0f0) One can then set the values of these params like: setparams!(dsp, Dict(\"/score/freq\" => 220.0f0))","title":"Using the libfaust compiler"},{"location":"tutorials/julia/#displaying-signals","text":"Julia offers a lot of packages to display signals, for example with the following commands ( coded here ) to display the outputs buffers: # Define a block of DSP code julia> code = \"\"\"import(\"stdfaust.lib\"); process = os.osc(500), os.sawtooth(1000);\"\"\" # Compile the DSP, compute one block of audio and display the outputs julia> compileFaustString(code) # Compile the DSP, with additional compiler arguments and display the outputs julia> compileFaustString(code; argv=[\"-double\", \"-vec\"]) # Compile the DSP, with a larger block_size and display the outputs julia> compileFaustString(code; block_size=50000) With the following result in VS code: Using Julia in VS code More sophisticated analysis can be done, like this example , or this projet to experiment using NNs in Faust .","title":"Displaying signals"},{"location":"tutorials/rnbo/","text":"Using Faust in RNBO with codebox~ In this tutorial, we present how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DSP programs can be compiled to the internal codebox~ sample level scripting language. Compiling Faust DSP to codebox~ code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for RNBO users who want to discover Faust. Using command line tools Generating codebox~ code Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The codebox~ code can be generated using the following line (note the use of -double option, the default sample format in RNBO/codebox~): faust -lang codebox -double osc.dsp -o osc.codebox This will generate a series of functions to init, update parameters and compute audio frames. Looking at the generated code The generated code contains a sequence of parameters definitions with their min, max, step and default values: // Params @param({min: 2e+01, max: 3e+03, step: 0.1}) freq1 = 1e+03; @param({min: 2e+01, max: 3e+03, step: 0.1}) freq2 = 2e+02; @param({min: -96.0, max: 0.0, step: 0.1}) volume = 0.0; Next the declaration of the DSP structure using the @state decorator, creating a state that persists across the lifetime of the codebox object. Scalar and arrays with the proper type are created: // Fields @state fSampleRate_cb : Int = 0; @state fConst1_cb : number = 0; @state fHslider0_cb : number = 0; @state fConst2_cb : number = 0; @state iVec0_cb = new FixedIntArray(2); @state fRec0_cb = new FixedDoubleArray(2); @state fConst3_cb : number = 0; @state fHslider1_cb : number = 0; @state fRec2_cb = new FixedDoubleArray(2); @state fHslider2_cb : number = 0; @state fRec3_cb = new FixedDoubleArray(2); @state iVec1_cb = new FixedIntArray(2); @state iRec1_cb = new FixedIntArray(2); @state ftbl0mydspSIG0_cb = new FixedDoubleArray(65536); @state fUpdated : Int = 0; @state fControl_cb = new FixedDoubleArray(3); Next the DSP init code, which is added in dspsetup , only available in codebox~ where it will be called each time audio is turned on in Max (which is basically every time the audio state is toggled, or the sample rate or vector size is changed). Here the DSP state is initialized using the RNBO current sample rate: // Init function dspsetup() { fUpdated = true; for (let l2_re0_cb : Int = 0; (l2_re0_cb < 2); l2_re0_cb = (l2_re0_cb + 1)) { iVec1_cb[l2_re0_cb] = 0; } for (let l3_re0_cb : Int = 0; (l3_re0_cb < 2); l3_re0_cb = (l3_re0_cb + 1)) { iRec1_cb[l3_re0_cb] = 0; } for (let i1_re0_cb : Int = 0; (i1_re0_cb < 65536); i1_re0_cb = (i1_re0_cb + 1)) { iVec1_cb[0] = 1; iRec1_cb[0] = ((iVec1_cb[1] + iRec1_cb[1]) % 65536); ftbl0mydspSIG0_cb[i1_re0_cb] = sin((9.587379924285257e-05 * iRec1_cb[0])); iVec1_cb[1] = iVec1_cb[0]; iRec1_cb[1] = iRec1_cb[0]; } fHslider0_cb = 0.0; fHslider1_cb = 1e+03; fHslider2_cb = 2e+02; ... ... fSampleRate_cb = samplerate(); let fConst0_cb : number = min(1.92e+05, max(1.0, fSampleRate_cb)); fConst1_cb = (44.1 / fConst0_cb); fConst2_cb = (1.0 - fConst1_cb); fConst3_cb = (1.0 / fConst0_cb); } Parameters handling is separated in two functions: control is called each time a parameter has changed: // Control function control() { fControl_cb[0] = (fConst1_cb * pow(1e+01, (0.05 * fHslider0_cb))); fControl_cb[1] = (fConst3_cb * fHslider1_cb); fControl_cb[2] = (fConst3_cb * fHslider2_cb); } And the actual change is triggered when at least one parameter has changed, controlled by the state of fUpdated global variable: // Update parameters function update(freq1,freq2,volume) { fUpdated = int(fUpdated) | (freq1 != fHslider1_cb); fHslider1_cb = freq1; fUpdated = int(fUpdated) | (freq2 != fHslider2_cb); fHslider2_cb = freq2; fUpdated = int(fUpdated) | (volume != fHslider0_cb); fHslider0_cb = volume; if (fUpdated) { fUpdated = false; control(); } } Finally compute process the audio inputs and produces audio outputs: // Update parameters / Compute one frame function compute() { iVec0_cb[0] = 1; fRec0_cb[0] = (fControl_cb[0] + (fConst2_cb * fRec0_cb[1])); let iTemp0_cb : Int = (1 - iVec0_cb[1]); let fTemp1_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[1] + fRec2_cb[1])); fRec2_cb[0] = (fTemp1_cb - floor(fTemp1_cb)); output0_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec2_cb[0])), 65535))]); let fTemp2_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[2] + fRec3_cb[1])); fRec3_cb[0] = (fTemp2_cb - floor(fTemp2_cb)); output1_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec3_cb[0])), 65535))]); iVec0_cb[1] = iVec0_cb[0]; fRec0_cb[1] = fRec0_cb[0]; fRec2_cb[1] = fRec2_cb[0]; fRec3_cb[1] = fRec3_cb[0]; return [output0_cb,output1_cb]; } With this code in place, the following sequence of operations is done at each sample: // Update parameters update(freq1,freq2,volume); // Compute one frame outputs = compute(); // Write the outputs out1 = outputs[0]; out2 = outputs[1]; Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is done in compute . Testing the generated codebox~ code To be tested, the generated code has to be pasted in a codebox~ component in an encompassing RNBO patch, with additional patching to add the needed audio inputs/outputs and control parameters. Thus a more integrated and simpler model is to use the faust2rnbo tool. Using the faust2rnbo tool The faust2rnbo tool transforms a Faust DSP program into a RNBO patch containing a rnbo~ object and including the codebox code (generated using the codebox backend ) as a subpatch. Needed audio inputs/outputs and parameters (with the proper name, default, min and max values) are automatically added in the patch. Additional options allow to generate a special version of the RNBO patch used in the testing infrastructure. The code is written in Python and uses the very powerful py2max library to generate the maxpat JSON format. faust2rnbo -h Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file (and possibly file_effect.rnbopat) -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. The resulting patch contains: an audio adc~ input automatically connected to the rnbo~ object (when the DSP has audio inputs) an audio dac~ output automatically connected with the rnbo~ object. So the following command: faust2rnbo osc.dsp will directly compile the osc.dsp file and generate the osc.maxpat file, that can be opened in Max/MSP, with the following user-interface: Generated RNBO patch and with the rnbo~ subpatcher containing the codebox object as well as the parameter control machinery: rnbo~ subpatcher with parameter control machinery (after manual editing) Note that the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other contexts as explained on this page . So faust2rnbo -sp osc.dsp will create both osc.maxpat and osc.rnbopat files. In this case the main patch uses the patchername/paramname parameter naming convention: Generated RNBO patch in -sp mode and the subpatcher contains a p object to load and use the osc.rnbopat file: rnbo~ subpatcher with parameter control machinery in p mode Bargraph handling In Faust, bargraph are typically used to analyze audio signals where computed values are sent at control rate. This cannot be directly done in the RNBO model where only audio signals can be sent from the codebox code. So additional audio outputs are created for bargraph, and will be sampled (using snapshot~ and change ) and be connected to param objects, like input controllers. So for instance the following example: compiled with faust2rnbo will create a subpatcher with 2 audio inputs and 4 audio outputs (2 real ones and 2 used for bargraph), and the user-interface: rnbo~ subpatcher with additional audio outputs for bargraph and the main patch with parameters displaying the bargraph values: RNBO main patch displaying bargraph values MIDI control Control of parameters with MIDI can be activated using the -midi option, or using the declare options \"[midi:on]\"; syntax in the DSP code. The patch will then contain midiin/midiout objects at global level and specialized ctlin/notein etc. objects in the codebox subpatcher with the appropriate scale object to map the MIDI message range on the target parameter range. So for instance the MIDI augmented example: can now be controlled with MIDI volume (ctrl 7), ctrl 1 and ctrl 2 for each channel frequency. Modification done on the parameters in the GUI will be sent as MIDI output messages. And the following command: faust2rnbo -midi osc.dsp will compile a osc.maxpat file containing additional midiin/midiout objects, with the following user-interface: Generated RNBO patch with MIDI control Polyphonic instruments When the DSP follows the polyphonic ready instrument convention, it can be activated in MIDI controllable polyphonic mode. So the following DSP program: compiled with the command: faust2rnbo -midi -nvoices 12 organ.dsp will create a patch containing a rnbo~ object with 12 voices, and with a notein object added in the subpatcher correctly connected to the appropriate freq/gain/gate aware parameters. Additional mapping depending of the convention used to describe the pitch (freq or key) or gain (gain or velocity) will be added when needed, with the generated user-interface: Generated polyphonic RNBO patch with MIDI control In the DSP, note that the master slider can be controlled using the crl 7 (= Volume) MIDI message. Note that here again, the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other context. Polyphonic instruments with an effect The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a polyphonic MIDI ready patch: To be compiled with the following: faust2rnbo -midi -nvoices 16 -effect auto organ2.dsp with the generated user-interface and the polyphonic DSP rnbo~ object, using the p abstraction model to load and activate the polyphonic instrument (as a organ2.rnbopat file), connected to the global effect (as a organ2_effect.rnbopat file). Having a single rnbo~ object with the two embedded subpachers is mandatory to properly create the exported project: Generated polyphonic RNBO patch with MIDI control and the rnbo~ subpather: rnbo~ subpatcher with the polyphonic instrument and global effect as p abstractions Using the Faust Web IDE Faust DSP programs can be written, tested in the Faust Web IDE and generated as RNBO patches. Generating a RNBO patch The output as a RNBO patch can directly be generated using the Platform = rnbo and Architecture = rnbo export options. The resulting foo folder is self-contained, containing the foo.maxpat file.to be opened with Max/MSP. Exporting the code Generating the RNBO patch in polyphonic mode DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = rnbo and Architecture = rnbo-poly export options. The resulting foo folder is self-contained, containing the foo.maxpat file to be opened with Max/MSP. Generating the RNBO patch in polyphonic mode with a global effect DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = rnbo and Architecture = rnbo-poly-effect export options. The resulting foo folder is self-contained, containing the foo.maxpat , foo.rnbopat and foo_effect.rnbopat files (using the p abstraction model), with foo.maxpat file to be opened with Max/MSP. Generating the RNBO patch from a Faust DSP program found in the web Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a RNBO patch as already showed. examples of the faustplayground platform can be found here and possibly converted.","title":"Using Faust in RNBO with codebox~"},{"location":"tutorials/rnbo/#using-faust-in-rnbo-with-codebox","text":"In this tutorial, we present how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DSP programs can be compiled to the internal codebox~ sample level scripting language. Compiling Faust DSP to codebox~ code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net.","title":"Using Faust in RNBO with codebox~"},{"location":"tutorials/rnbo/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for RNBO users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/rnbo/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/rnbo/#generating-codebox-code","text":"Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The codebox~ code can be generated using the following line (note the use of -double option, the default sample format in RNBO/codebox~): faust -lang codebox -double osc.dsp -o osc.codebox This will generate a series of functions to init, update parameters and compute audio frames.","title":"Generating codebox~ code"},{"location":"tutorials/rnbo/#looking-at-the-generated-code","text":"The generated code contains a sequence of parameters definitions with their min, max, step and default values: // Params @param({min: 2e+01, max: 3e+03, step: 0.1}) freq1 = 1e+03; @param({min: 2e+01, max: 3e+03, step: 0.1}) freq2 = 2e+02; @param({min: -96.0, max: 0.0, step: 0.1}) volume = 0.0; Next the declaration of the DSP structure using the @state decorator, creating a state that persists across the lifetime of the codebox object. Scalar and arrays with the proper type are created: // Fields @state fSampleRate_cb : Int = 0; @state fConst1_cb : number = 0; @state fHslider0_cb : number = 0; @state fConst2_cb : number = 0; @state iVec0_cb = new FixedIntArray(2); @state fRec0_cb = new FixedDoubleArray(2); @state fConst3_cb : number = 0; @state fHslider1_cb : number = 0; @state fRec2_cb = new FixedDoubleArray(2); @state fHslider2_cb : number = 0; @state fRec3_cb = new FixedDoubleArray(2); @state iVec1_cb = new FixedIntArray(2); @state iRec1_cb = new FixedIntArray(2); @state ftbl0mydspSIG0_cb = new FixedDoubleArray(65536); @state fUpdated : Int = 0; @state fControl_cb = new FixedDoubleArray(3); Next the DSP init code, which is added in dspsetup , only available in codebox~ where it will be called each time audio is turned on in Max (which is basically every time the audio state is toggled, or the sample rate or vector size is changed). Here the DSP state is initialized using the RNBO current sample rate: // Init function dspsetup() { fUpdated = true; for (let l2_re0_cb : Int = 0; (l2_re0_cb < 2); l2_re0_cb = (l2_re0_cb + 1)) { iVec1_cb[l2_re0_cb] = 0; } for (let l3_re0_cb : Int = 0; (l3_re0_cb < 2); l3_re0_cb = (l3_re0_cb + 1)) { iRec1_cb[l3_re0_cb] = 0; } for (let i1_re0_cb : Int = 0; (i1_re0_cb < 65536); i1_re0_cb = (i1_re0_cb + 1)) { iVec1_cb[0] = 1; iRec1_cb[0] = ((iVec1_cb[1] + iRec1_cb[1]) % 65536); ftbl0mydspSIG0_cb[i1_re0_cb] = sin((9.587379924285257e-05 * iRec1_cb[0])); iVec1_cb[1] = iVec1_cb[0]; iRec1_cb[1] = iRec1_cb[0]; } fHslider0_cb = 0.0; fHslider1_cb = 1e+03; fHslider2_cb = 2e+02; ... ... fSampleRate_cb = samplerate(); let fConst0_cb : number = min(1.92e+05, max(1.0, fSampleRate_cb)); fConst1_cb = (44.1 / fConst0_cb); fConst2_cb = (1.0 - fConst1_cb); fConst3_cb = (1.0 / fConst0_cb); } Parameters handling is separated in two functions: control is called each time a parameter has changed: // Control function control() { fControl_cb[0] = (fConst1_cb * pow(1e+01, (0.05 * fHslider0_cb))); fControl_cb[1] = (fConst3_cb * fHslider1_cb); fControl_cb[2] = (fConst3_cb * fHslider2_cb); } And the actual change is triggered when at least one parameter has changed, controlled by the state of fUpdated global variable: // Update parameters function update(freq1,freq2,volume) { fUpdated = int(fUpdated) | (freq1 != fHslider1_cb); fHslider1_cb = freq1; fUpdated = int(fUpdated) | (freq2 != fHslider2_cb); fHslider2_cb = freq2; fUpdated = int(fUpdated) | (volume != fHslider0_cb); fHslider0_cb = volume; if (fUpdated) { fUpdated = false; control(); } } Finally compute process the audio inputs and produces audio outputs: // Update parameters / Compute one frame function compute() { iVec0_cb[0] = 1; fRec0_cb[0] = (fControl_cb[0] + (fConst2_cb * fRec0_cb[1])); let iTemp0_cb : Int = (1 - iVec0_cb[1]); let fTemp1_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[1] + fRec2_cb[1])); fRec2_cb[0] = (fTemp1_cb - floor(fTemp1_cb)); output0_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec2_cb[0])), 65535))]); let fTemp2_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[2] + fRec3_cb[1])); fRec3_cb[0] = (fTemp2_cb - floor(fTemp2_cb)); output1_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec3_cb[0])), 65535))]); iVec0_cb[1] = iVec0_cb[0]; fRec0_cb[1] = fRec0_cb[0]; fRec2_cb[1] = fRec2_cb[0]; fRec3_cb[1] = fRec3_cb[0]; return [output0_cb,output1_cb]; } With this code in place, the following sequence of operations is done at each sample: // Update parameters update(freq1,freq2,volume); // Compute one frame outputs = compute(); // Write the outputs out1 = outputs[0]; out2 = outputs[1]; Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is done in compute .","title":"Looking at the generated code"},{"location":"tutorials/rnbo/#testing-the-generated-codebox-code","text":"To be tested, the generated code has to be pasted in a codebox~ component in an encompassing RNBO patch, with additional patching to add the needed audio inputs/outputs and control parameters. Thus a more integrated and simpler model is to use the faust2rnbo tool.","title":"Testing the generated codebox~ code"},{"location":"tutorials/rnbo/#using-the-faust2rnbo-tool","text":"The faust2rnbo tool transforms a Faust DSP program into a RNBO patch containing a rnbo~ object and including the codebox code (generated using the codebox backend ) as a subpatch. Needed audio inputs/outputs and parameters (with the proper name, default, min and max values) are automatically added in the patch. Additional options allow to generate a special version of the RNBO patch used in the testing infrastructure. The code is written in Python and uses the very powerful py2max library to generate the maxpat JSON format. faust2rnbo -h Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file (and possibly file_effect.rnbopat) -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. The resulting patch contains: an audio adc~ input automatically connected to the rnbo~ object (when the DSP has audio inputs) an audio dac~ output automatically connected with the rnbo~ object. So the following command: faust2rnbo osc.dsp will directly compile the osc.dsp file and generate the osc.maxpat file, that can be opened in Max/MSP, with the following user-interface: Generated RNBO patch and with the rnbo~ subpatcher containing the codebox object as well as the parameter control machinery: rnbo~ subpatcher with parameter control machinery (after manual editing) Note that the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other contexts as explained on this page . So faust2rnbo -sp osc.dsp will create both osc.maxpat and osc.rnbopat files. In this case the main patch uses the patchername/paramname parameter naming convention: Generated RNBO patch in -sp mode and the subpatcher contains a p object to load and use the osc.rnbopat file: rnbo~ subpatcher with parameter control machinery in p mode","title":"Using the faust2rnbo tool"},{"location":"tutorials/rnbo/#bargraph-handling","text":"In Faust, bargraph are typically used to analyze audio signals where computed values are sent at control rate. This cannot be directly done in the RNBO model where only audio signals can be sent from the codebox code. So additional audio outputs are created for bargraph, and will be sampled (using snapshot~ and change ) and be connected to param objects, like input controllers. So for instance the following example: compiled with faust2rnbo will create a subpatcher with 2 audio inputs and 4 audio outputs (2 real ones and 2 used for bargraph), and the user-interface: rnbo~ subpatcher with additional audio outputs for bargraph and the main patch with parameters displaying the bargraph values: RNBO main patch displaying bargraph values","title":"Bargraph handling"},{"location":"tutorials/rnbo/#midi-control","text":"Control of parameters with MIDI can be activated using the -midi option, or using the declare options \"[midi:on]\"; syntax in the DSP code. The patch will then contain midiin/midiout objects at global level and specialized ctlin/notein etc. objects in the codebox subpatcher with the appropriate scale object to map the MIDI message range on the target parameter range. So for instance the MIDI augmented example: can now be controlled with MIDI volume (ctrl 7), ctrl 1 and ctrl 2 for each channel frequency. Modification done on the parameters in the GUI will be sent as MIDI output messages. And the following command: faust2rnbo -midi osc.dsp will compile a osc.maxpat file containing additional midiin/midiout objects, with the following user-interface: Generated RNBO patch with MIDI control","title":"MIDI control"},{"location":"tutorials/rnbo/#polyphonic-instruments","text":"When the DSP follows the polyphonic ready instrument convention, it can be activated in MIDI controllable polyphonic mode. So the following DSP program: compiled with the command: faust2rnbo -midi -nvoices 12 organ.dsp will create a patch containing a rnbo~ object with 12 voices, and with a notein object added in the subpatcher correctly connected to the appropriate freq/gain/gate aware parameters. Additional mapping depending of the convention used to describe the pitch (freq or key) or gain (gain or velocity) will be added when needed, with the generated user-interface: Generated polyphonic RNBO patch with MIDI control In the DSP, note that the master slider can be controlled using the crl 7 (= Volume) MIDI message. Note that here again, the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other context.","title":"Polyphonic instruments"},{"location":"tutorials/rnbo/#polyphonic-instruments-with-an-effect","text":"The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a polyphonic MIDI ready patch: To be compiled with the following: faust2rnbo -midi -nvoices 16 -effect auto organ2.dsp with the generated user-interface and the polyphonic DSP rnbo~ object, using the p abstraction model to load and activate the polyphonic instrument (as a organ2.rnbopat file), connected to the global effect (as a organ2_effect.rnbopat file). Having a single rnbo~ object with the two embedded subpachers is mandatory to properly create the exported project: Generated polyphonic RNBO patch with MIDI control and the rnbo~ subpather: rnbo~ subpatcher with the polyphonic instrument and global effect as p abstractions","title":"Polyphonic instruments with an effect"},{"location":"tutorials/rnbo/#using-the-faust-web-ide","text":"Faust DSP programs can be written, tested in the Faust Web IDE and generated as RNBO patches.","title":"Using the Faust Web IDE"},{"location":"tutorials/rnbo/#generating-a-rnbo-patch","text":"The output as a RNBO patch can directly be generated using the Platform = rnbo and Architecture = rnbo export options. The resulting foo folder is self-contained, containing the foo.maxpat file.to be opened with Max/MSP. Exporting the code","title":"Generating a RNBO patch"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-in-polyphonic-mode","text":"DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = rnbo and Architecture = rnbo-poly export options. The resulting foo folder is self-contained, containing the foo.maxpat file to be opened with Max/MSP.","title":"Generating the RNBO patch in polyphonic mode"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-in-polyphonic-mode-with-a-global-effect","text":"DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = rnbo and Architecture = rnbo-poly-effect export options. The resulting foo folder is self-contained, containing the foo.maxpat , foo.rnbopat and foo_effect.rnbopat files (using the p abstraction model), with foo.maxpat file to be opened with Max/MSP.","title":"Generating the RNBO patch in polyphonic mode with a global effect"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-from-a-faust-dsp-program-found-in-the-web","text":"Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a RNBO patch as already showed. examples of the faustplayground platform can be found here and possibly converted.","title":"Generating the RNBO patch from a Faust DSP program found in the web"},{"location":"tutorials/signal-api/","text":"Using the signal API The signal API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the signal API, and take profit of part of the Faust compiler infrastructure. Faust compiler structure The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated in a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends. Accessing the signal stage A new intermediate public entry point has been created in the Semantic Phase to allow the creation of a signal set (as a list of output signals), then beneficiate of all remaining parts of the compilation chain. The signal API (or the C signal API version) allows to programmatically create the list of output signals, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the box API allows to access another stage in the compilation stage. Compiling signal expressions To use the signal API, the following steps must be taken: creating a global compilation context using the createLibContext function creating signals outputs using the signal API, progressively building more complex expressions by combining simpler ones compiling the list of outputs using the createCPPDSPFactoryFromSignals function to create a DSP factory (or createDSPFactoryFromSignals to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromSignals to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used. Tools Let's first define a compile function, which uses the createCPPDSPFactoryFromSignals function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromSignals(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\ Examples For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps) and clearly shows how each output signal expression has to be created. All presented C++ examples (as well as some more) are defined in the signal-tester tool, to be compiled with make signal-tester in the tools/benchmark folder. Simple constant signal Let's create a program generating the 0.5 constant value. Here is the Faust DSP code: The following code creates a vector of output signals (with the tvec type), containing the single sigReal(0.5) signal, then compile it and display the C++ class: static void test1() { COMPILER ( tvec signals; signals.push_back(sigReal(0.5)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(0.5f); } } Doing some mathematical operations on an input signal Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with sigInput(0) signal, then transformed using sigAdd and sigMul signal operators to produce two outputs: static void test2() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(in1, sigReal(0.5))); signals.push_back(sigMul(in1, sigReal(1.5))); compile(\"test2\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); output0[i0] = FAUSTFLOAT((fTemp0 + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fTemp0)); } } Note that accessing input N is simply done using the sigInput(N) expression. Defining delayed signals Here is a simple program using a signal input and doing mathematical operations on it, then delaying the signals: The sigDelay(x, y) operator is used to delay the x first parameter with the second y parameter, here with constant values: static void test3() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); compile(\"test3\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; fVec1[(IOTA & 511)] = (fTemp0 + 0.5f); output0[i0] = FAUSTFLOAT(fVec1[((IOTA - 500) & 511)]); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code show how to compile in vector mode: static void test5() { createLibContext(); tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); // Vector compilation compile(\"test5\", signals, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; FAUSTFLOAT* output1_ptr = outputs[1]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; FAUSTFLOAT* output1 = &output1_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ fYec0_idx = ((fYec0_idx + fYec0_idx_save) & 4095); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[((i + fYec0_idx) & 4095)] = float(input0[i]); } /* Post code */ fYec0_idx_save = vsize; /* Vectorizable loop 1 */ /* Pre code */ fYec1_idx = ((fYec1_idx + fYec1_idx_save) & 1023); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec1[((i + fYec1_idx) & 1023)] = (float(input0[i]) + 0.5f); } /* Post code */ fYec1_idx_save = vsize; /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec1[(((i + fYec1_idx) - 500) & 1023)]); } /* Vectorizable loop 3 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output1[i] = FAUSTFLOAT((1.5f * fYec0[(((i + fYec0_idx) - 3000) & 4095)])); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test4() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(sigDelay(in1, sigInt(500)), sigReal(0.5))); signals.push_back(sigMul(sigDelay(in1, sigInt(3000)), sigReal(1.5))); compile(\"test4\", signals); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Equivalent signal expressions It is really important to note that syntactically equivalent signal expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( tvec signals; Signal s1 = sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) signals.push_back(s1); signals.push_back(s1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( tvec signals; signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); compile(\"equivalent2\", signals); ) } It can be a property to remember when creating a DSL on top of the signal API. Using User Interface items User Interface items can be used, as in the following example, with a vslider : Built with the following code: static void test8() { COMPILER ( tvec signals; Signal in1 = sigInput(0); Signal s = sigVSlider(\"Vol\", sigReal(0.5), sigReal(0.), sigReal(1.), sigReal(0.01)); signals.push_back(sigMul(s, sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500)))); compile(\"test8\", signals); ) } The buildUserInterface method is generated, using the fVslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->addVerticalSlider(\"Vol\", &fVslider0, FAUSTFLOAT(0.5f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.00999999978f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fVslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[(IOTA & 511)] = (float(input0[i0]) + 0.5f); output0[i0] = FAUSTFLOAT((fSlow0 * fVec0[((IOTA - 500) & 511)])); IOTA = (IOTA + 1); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the signal API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( tvec signals; Signal freq = sigVSlider(\"h:Oscillator/freq\", sigReal(440), sigReal(50), sigReal(1000), sigReal(0.1)); Signal gain = sigVSlider(\"h:Oscillator/gain\", sigReal(0), sigReal(0), sigReal(1), sigReal(0.011)); signals.push_back(sigMul(freq, sigMul(gain, sigInput(0)))); compile(\"test9\", signals); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); } Defining recursive signals Recursive signals can be defined using the sigRecursion function to build the recursion, and the sigSelf function to refer to the recursive signal itself. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursion(sigAdd(sigSelf(), in1))); compile(\"test10\", signals); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } The same equivalent code can be defined using the more general sigRecursionN and sigSelfN functions which allow to build a list of (possibly mutually dependent) recursive signals: static void test10bis() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursionN(sigAdd(sigSelfN(0), in1))); compile(\"test10\", signals); ) } Here is an example of the definition of mutually dependent recursive signals: static void test10ter() { COMPILER ( Signal in0 = sigInput(0); Signal in1 = sigInput(1); tvec ins; ins.push_back(sigAdd(sigMul(sigSelfN(1), sigReal(0.5)), in0)); ins.push_back(sigAdd(sigMul(sigSelfN(0), sigReal(0.9)), in1)); tvec outs = sigRecursionN(ins); compile(\"test10ter\", outs); ) } With the following compute method: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = float(input0[i0]) + 0.5f * fRec1[1]; fRec1[0] = float(input1[i0]) + 0.9f * fRec0[1]; output0[i0] = FAUSTFLOAT(fRec0[0]); output1[i0] = FAUSTFLOAT(fRec1[0]); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } } Accessing the global context In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the signal language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Signal SR() { return sigMin(sigReal(192000.0), sigMax(sigReal(1.0), sigFConst(SType::kSInt, \"fSampleFreq\", \"<dummy.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return sigFVar(SType::kSInt, \"count\", \"<dummy.h>\"); } So the following DSP program: Can be written at the signal API level with: static void test11() { COMPILER ( tvec signals; signals.push_back(SR()); signals.push_back(BS()); compile(\"test11\", signals); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } } Creating tables Read only and read/write tables can be created. The read only table signal is created with sigReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigReadOnlyTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)))); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with sigWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigWriteReadTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)), sigIntCast(sigInput(1)), sigIntCast(sigInput(2)))); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } } Creating waveforms The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with sigWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(sigReal(100*i)); } tvec signals; signals.push_back(sigInt(waveform.size())); // the waveform size signals.push_back(sigWaveform(waveform)); // the waveform content compile(\"test12\", signals); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } } Creating soundfile The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with sigSoundfile , but cannot be used directly. It has to be used with: sigSoundfileLength to access the sound length in frames sigSoundfileRate to access the sound rate in Hz sigSoundfileBuffer to access the actual samples Thus the following DSP code: Will be created using the signal API with: static void test19() { COMPILER ( tvec signals; // Soundfile definition Signal sf = sigSoundfile(\"sound[url:{'tango.wav'}]\"); // Simple read index of 0 to simplify the code Signal rdx = sigInt(0); // Part 0 Signal part = sigInt(0); // Wrapped index to avoid reading outside the buffer Signal wridx = sigIntCast(sigMax(sigInt(0), sigMin(rdx, sigSub(sigSoundfileLength(sf, sigInt(0)), sigInt(1))))); // Accessing part 0 signals.push_back(sigSoundfileLength(sf, part)); // Accessing part 0 signals.push_back(sigSoundfileRate(sf, part)); // Accessing chan 0 and part 0, with a wrapped read index signals.push_back(sigSoundfileBuffer(sf, sigInt(0), part, wridx)); compile(\"test19\", signals); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; } Defining more complex expressions: phasor and oscillator More complex signal expressions can be defined, creating signals using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Signal decimalpart(Signal x) { return sigSub(x, sigIntCast(x)); } static Signal phasor(Signal f) { return sigRecursion(decimalpart(sigAdd(sigSelf(), sigDiv(f, SR())))); } And the main function combining them: static void test17() { COMPILER ( tvec signals; signals.push_back(phasor(sigReal(440.0))); compile(\"test17\", signals); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Signal osc(Signal f) { return sigSin(sigMul(phasor(f), sigMul(sigReal(2.0), sigReal(3.141592653)))); } static void test18() { COMPILER ( tvec signals; signals.push_back(osc(sigReal(440.0))); signals.push_back(osc(sigReal(440.0))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } } Using the generated code Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromSignals (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromSignals (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory); Connecting the audio layer Audio drivers allow to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop(); Connecting the controller layer Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual. Example with audio rendering and GUI control Here is a more complete example, first with the DSP code: Then with the C++ code using the signal API: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq1\", sigReal(300), sigReal(100), sigReal(2000), sigReal(0.01)))); signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq2\", sigReal(500), sigReal(100), sigReal(2000), sigReal(0.01)))); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Polyphonic MIDI controllable simple synthesizer Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the signal API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Signal freq = sigNumEntry(\"freq\", sigReal(100), sigReal(100), sigReal(3000), sigReal(0.01)); Signal gate = sigButton(\"gate\"); Signal gain = sigNumEntry(\"gain\", sigReal(0.5), sigReal(0), sigReal(1), sigReal(0.01)); Signal organ = sigMul(gate, sigAdd(sigMul(osc(freq), gain), sigMul(osc(sigMul(freq, sigInt(2))), gain))); // Stereo signals.push_back(organ); signals.push_back(organ); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Examples with the C API The signal API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create signals, where the LLVM backend is used with the C version createCDSPFactoryFromSignals function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Signal decimalpart(Signal x) { return CsigSub(x, CsigIntCast(x)); } static Signal phasor(Signal f) { return CsigRecursion(decimalpart(CsigAdd(CsigSelf(), CsigDiv(f, SR())))); } static void test1() { createLibContext(); { Signal signals[2]; signals[0] = phasor(CsigReal(2000)); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test1\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Signal signals[2]; Signal freq = CsigVSlider(\"h:Oscillator/freq\", CsigReal(440), CsigReal(50), CsigReal(1000), CsigReal(0.1)); Signal gain = CsigVSlider(\"h:Oscillator/gain\", CsigReal(0), CsigReal(0), CsigReal(1), CsigReal(0.011)); signals[0] = CsigMul(freq, CsigMul(gain, CsigInput(0))); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test3\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the signal-tester-c tool, to be compiled with make signal-tester-c in the tools/benchmark folder. Creating a signal language based on this API Generating complex expressions by directly using the signal API can quickly become really tricky and unpracticable. So a language created on top of the signal API is usually needed. This is exactly what the Block Diagram Algebra is all about, and the entire Faust language itself. But some other approaches can possibly be tested. The Elementary audio language for instance is built over a similar signal language and uses JavaScript as the upper layer language to help create a complex list of output signals programmatically. Other approaches using graphical based tools could certainly be tested.","title":"Using the signal API"},{"location":"tutorials/signal-api/#using-the-signal-api","text":"The signal API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the signal API, and take profit of part of the Faust compiler infrastructure.","title":"Using the signal API"},{"location":"tutorials/signal-api/#faust-compiler-structure","text":"The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated in a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends.","title":"Faust compiler structure"},{"location":"tutorials/signal-api/#accessing-the-signal-stage","text":"A new intermediate public entry point has been created in the Semantic Phase to allow the creation of a signal set (as a list of output signals), then beneficiate of all remaining parts of the compilation chain. The signal API (or the C signal API version) allows to programmatically create the list of output signals, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the box API allows to access another stage in the compilation stage.","title":"Accessing the signal stage"},{"location":"tutorials/signal-api/#compiling-signal-expressions","text":"To use the signal API, the following steps must be taken: creating a global compilation context using the createLibContext function creating signals outputs using the signal API, progressively building more complex expressions by combining simpler ones compiling the list of outputs using the createCPPDSPFactoryFromSignals function to create a DSP factory (or createDSPFactoryFromSignals to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromSignals to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used.","title":"Compiling signal expressions"},{"location":"tutorials/signal-api/#tools","text":"Let's first define a compile function, which uses the createCPPDSPFactoryFromSignals function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromSignals(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\","title":"Tools"},{"location":"tutorials/signal-api/#examples","text":"For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps) and clearly shows how each output signal expression has to be created. All presented C++ examples (as well as some more) are defined in the signal-tester tool, to be compiled with make signal-tester in the tools/benchmark folder.","title":"Examples"},{"location":"tutorials/signal-api/#simple-constant-signal","text":"Let's create a program generating the 0.5 constant value. Here is the Faust DSP code: The following code creates a vector of output signals (with the tvec type), containing the single sigReal(0.5) signal, then compile it and display the C++ class: static void test1() { COMPILER ( tvec signals; signals.push_back(sigReal(0.5)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(0.5f); } }","title":"Simple constant signal"},{"location":"tutorials/signal-api/#doing-some-mathematical-operations-on-an-input-signal","text":"Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with sigInput(0) signal, then transformed using sigAdd and sigMul signal operators to produce two outputs: static void test2() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(in1, sigReal(0.5))); signals.push_back(sigMul(in1, sigReal(1.5))); compile(\"test2\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); output0[i0] = FAUSTFLOAT((fTemp0 + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fTemp0)); } } Note that accessing input N is simply done using the sigInput(N) expression.","title":"Doing some mathematical operations on an input signal"},{"location":"tutorials/signal-api/#defining-delayed-signals","text":"Here is a simple program using a signal input and doing mathematical operations on it, then delaying the signals: The sigDelay(x, y) operator is used to delay the x first parameter with the second y parameter, here with constant values: static void test3() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); compile(\"test3\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; fVec1[(IOTA & 511)] = (fTemp0 + 0.5f); output0[i0] = FAUSTFLOAT(fVec1[((IOTA - 500) & 511)]); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code show how to compile in vector mode: static void test5() { createLibContext(); tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); // Vector compilation compile(\"test5\", signals, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; FAUSTFLOAT* output1_ptr = outputs[1]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; FAUSTFLOAT* output1 = &output1_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ fYec0_idx = ((fYec0_idx + fYec0_idx_save) & 4095); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[((i + fYec0_idx) & 4095)] = float(input0[i]); } /* Post code */ fYec0_idx_save = vsize; /* Vectorizable loop 1 */ /* Pre code */ fYec1_idx = ((fYec1_idx + fYec1_idx_save) & 1023); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec1[((i + fYec1_idx) & 1023)] = (float(input0[i]) + 0.5f); } /* Post code */ fYec1_idx_save = vsize; /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec1[(((i + fYec1_idx) - 500) & 1023)]); } /* Vectorizable loop 3 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output1[i] = FAUSTFLOAT((1.5f * fYec0[(((i + fYec0_idx) - 3000) & 4095)])); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test4() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(sigDelay(in1, sigInt(500)), sigReal(0.5))); signals.push_back(sigMul(sigDelay(in1, sigInt(3000)), sigReal(1.5))); compile(\"test4\", signals); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } }","title":"Defining delayed signals"},{"location":"tutorials/signal-api/#equivalent-signal-expressions","text":"It is really important to note that syntactically equivalent signal expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( tvec signals; Signal s1 = sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) signals.push_back(s1); signals.push_back(s1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( tvec signals; signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); compile(\"equivalent2\", signals); ) } It can be a property to remember when creating a DSL on top of the signal API.","title":"Equivalent signal expressions"},{"location":"tutorials/signal-api/#using-user-interface-items","text":"User Interface items can be used, as in the following example, with a vslider : Built with the following code: static void test8() { COMPILER ( tvec signals; Signal in1 = sigInput(0); Signal s = sigVSlider(\"Vol\", sigReal(0.5), sigReal(0.), sigReal(1.), sigReal(0.01)); signals.push_back(sigMul(s, sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500)))); compile(\"test8\", signals); ) } The buildUserInterface method is generated, using the fVslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->addVerticalSlider(\"Vol\", &fVslider0, FAUSTFLOAT(0.5f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.00999999978f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fVslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[(IOTA & 511)] = (float(input0[i0]) + 0.5f); output0[i0] = FAUSTFLOAT((fSlow0 * fVec0[((IOTA - 500) & 511)])); IOTA = (IOTA + 1); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the signal API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( tvec signals; Signal freq = sigVSlider(\"h:Oscillator/freq\", sigReal(440), sigReal(50), sigReal(1000), sigReal(0.1)); Signal gain = sigVSlider(\"h:Oscillator/gain\", sigReal(0), sigReal(0), sigReal(1), sigReal(0.011)); signals.push_back(sigMul(freq, sigMul(gain, sigInput(0)))); compile(\"test9\", signals); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); }","title":"Using User Interface items"},{"location":"tutorials/signal-api/#defining-recursive-signals","text":"Recursive signals can be defined using the sigRecursion function to build the recursion, and the sigSelf function to refer to the recursive signal itself. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursion(sigAdd(sigSelf(), in1))); compile(\"test10\", signals); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } The same equivalent code can be defined using the more general sigRecursionN and sigSelfN functions which allow to build a list of (possibly mutually dependent) recursive signals: static void test10bis() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursionN(sigAdd(sigSelfN(0), in1))); compile(\"test10\", signals); ) } Here is an example of the definition of mutually dependent recursive signals: static void test10ter() { COMPILER ( Signal in0 = sigInput(0); Signal in1 = sigInput(1); tvec ins; ins.push_back(sigAdd(sigMul(sigSelfN(1), sigReal(0.5)), in0)); ins.push_back(sigAdd(sigMul(sigSelfN(0), sigReal(0.9)), in1)); tvec outs = sigRecursionN(ins); compile(\"test10ter\", outs); ) } With the following compute method: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = float(input0[i0]) + 0.5f * fRec1[1]; fRec1[0] = float(input1[i0]) + 0.9f * fRec0[1]; output0[i0] = FAUSTFLOAT(fRec0[0]); output1[i0] = FAUSTFLOAT(fRec1[0]); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } }","title":"Defining recursive signals"},{"location":"tutorials/signal-api/#accessing-the-global-context","text":"In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the signal language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Signal SR() { return sigMin(sigReal(192000.0), sigMax(sigReal(1.0), sigFConst(SType::kSInt, \"fSampleFreq\", \"<dummy.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return sigFVar(SType::kSInt, \"count\", \"<dummy.h>\"); } So the following DSP program: Can be written at the signal API level with: static void test11() { COMPILER ( tvec signals; signals.push_back(SR()); signals.push_back(BS()); compile(\"test11\", signals); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } }","title":"Accessing the global context"},{"location":"tutorials/signal-api/#creating-tables","text":"Read only and read/write tables can be created. The read only table signal is created with sigReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigReadOnlyTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)))); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with sigWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigWriteReadTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)), sigIntCast(sigInput(1)), sigIntCast(sigInput(2)))); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } }","title":"Creating tables"},{"location":"tutorials/signal-api/#creating-waveforms","text":"The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with sigWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(sigReal(100*i)); } tvec signals; signals.push_back(sigInt(waveform.size())); // the waveform size signals.push_back(sigWaveform(waveform)); // the waveform content compile(\"test12\", signals); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } }","title":"Creating waveforms"},{"location":"tutorials/signal-api/#creating-soundfile","text":"The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with sigSoundfile , but cannot be used directly. It has to be used with: sigSoundfileLength to access the sound length in frames sigSoundfileRate to access the sound rate in Hz sigSoundfileBuffer to access the actual samples Thus the following DSP code: Will be created using the signal API with: static void test19() { COMPILER ( tvec signals; // Soundfile definition Signal sf = sigSoundfile(\"sound[url:{'tango.wav'}]\"); // Simple read index of 0 to simplify the code Signal rdx = sigInt(0); // Part 0 Signal part = sigInt(0); // Wrapped index to avoid reading outside the buffer Signal wridx = sigIntCast(sigMax(sigInt(0), sigMin(rdx, sigSub(sigSoundfileLength(sf, sigInt(0)), sigInt(1))))); // Accessing part 0 signals.push_back(sigSoundfileLength(sf, part)); // Accessing part 0 signals.push_back(sigSoundfileRate(sf, part)); // Accessing chan 0 and part 0, with a wrapped read index signals.push_back(sigSoundfileBuffer(sf, sigInt(0), part, wridx)); compile(\"test19\", signals); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; }","title":"Creating soundfile"},{"location":"tutorials/signal-api/#defining-more-complex-expressions-phasor-and-oscillator","text":"More complex signal expressions can be defined, creating signals using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Signal decimalpart(Signal x) { return sigSub(x, sigIntCast(x)); } static Signal phasor(Signal f) { return sigRecursion(decimalpart(sigAdd(sigSelf(), sigDiv(f, SR())))); } And the main function combining them: static void test17() { COMPILER ( tvec signals; signals.push_back(phasor(sigReal(440.0))); compile(\"test17\", signals); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Signal osc(Signal f) { return sigSin(sigMul(phasor(f), sigMul(sigReal(2.0), sigReal(3.141592653)))); } static void test18() { COMPILER ( tvec signals; signals.push_back(osc(sigReal(440.0))); signals.push_back(osc(sigReal(440.0))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } }","title":"Defining more complex expressions: phasor and oscillator"},{"location":"tutorials/signal-api/#using-the-generated-code","text":"Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromSignals (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromSignals (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory);","title":"Using the generated code"},{"location":"tutorials/signal-api/#connecting-the-audio-layer","text":"Audio drivers allow to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop();","title":"Connecting the audio layer"},{"location":"tutorials/signal-api/#connecting-the-controller-layer","text":"Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual.","title":"Connecting the controller layer"},{"location":"tutorials/signal-api/#example-with-audio-rendering-and-gui-control","text":"Here is a more complete example, first with the DSP code: Then with the C++ code using the signal API: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq1\", sigReal(300), sigReal(100), sigReal(2000), sigReal(0.01)))); signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq2\", sigReal(500), sigReal(100), sigReal(2000), sigReal(0.01)))); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Example with audio rendering and GUI control"},{"location":"tutorials/signal-api/#polyphonic-midi-controllable-simple-synthesizer","text":"Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the signal API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Signal freq = sigNumEntry(\"freq\", sigReal(100), sigReal(100), sigReal(3000), sigReal(0.01)); Signal gate = sigButton(\"gate\"); Signal gain = sigNumEntry(\"gain\", sigReal(0.5), sigReal(0), sigReal(1), sigReal(0.01)); Signal organ = sigMul(gate, sigAdd(sigMul(osc(freq), gain), sigMul(osc(sigMul(freq, sigInt(2))), gain))); // Stereo signals.push_back(organ); signals.push_back(organ); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Polyphonic MIDI controllable simple synthesizer"},{"location":"tutorials/signal-api/#examples-with-the-c-api","text":"The signal API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create signals, where the LLVM backend is used with the C version createCDSPFactoryFromSignals function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Signal decimalpart(Signal x) { return CsigSub(x, CsigIntCast(x)); } static Signal phasor(Signal f) { return CsigRecursion(decimalpart(CsigAdd(CsigSelf(), CsigDiv(f, SR())))); } static void test1() { createLibContext(); { Signal signals[2]; signals[0] = phasor(CsigReal(2000)); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test1\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Signal signals[2]; Signal freq = CsigVSlider(\"h:Oscillator/freq\", CsigReal(440), CsigReal(50), CsigReal(1000), CsigReal(0.1)); Signal gain = CsigVSlider(\"h:Oscillator/gain\", CsigReal(0), CsigReal(0), CsigReal(1), CsigReal(0.011)); signals[0] = CsigMul(freq, CsigMul(gain, CsigInput(0))); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test3\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the signal-tester-c tool, to be compiled with make signal-tester-c in the tools/benchmark folder.","title":"Examples with the C API"},{"location":"tutorials/signal-api/#creating-a-signal-language-based-on-this-api","text":"Generating complex expressions by directly using the signal API can quickly become really tricky and unpracticable. So a language created on top of the signal API is usually needed. This is exactly what the Block Diagram Algebra is all about, and the entire Faust language itself. But some other approaches can possibly be tested. The Elementary audio language for instance is built over a similar signal language and uses JavaScript as the upper layer language to help create a complex list of output signals programmatically. Other approaches using graphical based tools could certainly be tested.","title":"Creating a signal language based on this API"},{"location":"tutorials/summation/","text":"RMS and Summation in Faust In this tutorial, we present different programming techniques to compute the sum of n consecutive samples in Faust. Such sums are typically used when computing the RMS value of a signal. It is therefore in the RMS context that we will present them. We will not use any predefined function, only Faust primitives, so that you can see all the details. The text is intended for beginners, but with some basic knowledge of Faust. If this is not your case have a look at the various documentations on this website. RMS value The computation of the RMS (Root Mean Square) value of a signal is defined by the following Faust expression: ^(2) : summation : /(n) : sqrt where n is the number of consecutive samples considered. This expression involves several steps: First, we take the square of the signal: ^(2) . This is the S of RMS. Then we sum the n consecutive samples: summation and divide this sum by n to get the mean value: /(n) . This is the M of RMS. Finally, we take the square root sqrt . This is the R of RMS. In other words, RMS is written S:M:R in Faust (leaving the summation function undefined for the moment): RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; }; In the following paragraphs, we will introduce 4 different techniques to write this summation function. We will assume that the audio samples are between -1 and 1. Sliding Sum Let's start with the sliding sum approach, probably the simplest way to efficiently add n consecutive samples. First, let's recall that we can add up all the samples of a signal s , from time 0 to the present time, with the following expression: s : +~_ . The trick for adding only the last n samples is to subtract from this sum the same sum but as it was n samples earlier. For example, in order to keep only the sum of the last 10 samples, we just have to subtract from the sum of all samples (s:+~_) the value of this same sum 10 samples ago (s:+~_ : @(10)) : (s:+~_), (s:+~_ : @(10)) : - This expression can be further simplified by factoring s:+~_ . We then get: s : +~_ <: _, @(10) : - From a mathematical point of view, this is perfectly correct but poses problems when computed using floating-point numbers. Unlike mathematical numbers, floating-point numbers have a limited precision (23 bits in single precision). When calculating the RMS value, we only add positive numbers. Therefore the sum will increase forever. But at some point, when the sum exceeds 2^{23} \u200b, the least significant bit will be higher than any number between 0 \u200b and 1 \u200b. Therefore adding such a small number will be exactly like adding 0, and the sum will never evolve anymore. Fortunately, the problem can be solved easily. We just have to swap the integration and the difference parts: s <: _, @(10) : - : +~_ This new formulation is identical to the previous one from a mathematical point of view. But now, the sum will always stay between -10\u200b and +10 \u200b\u200b, and the accuracy problems are only on the least significant bits. If the roundoff error due to quantization is modeled as a uniformly distributed random number between -q/2 and q/2, then its variance (mean square) is q^2/12, and this value increases linearly over time in a running sum (see \"Wiener process\"). Thus, we expect the roundoff error in a running-sum rms calculator to grow proportional to the square root of time. We can now complete the definition of RMS: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = _ <: _, @(n) : - : +~_; }; Fix-Point Sliding Sum While the previous solution works very well with typical signals over practical time spans, the roundoff error continues to grow slowly. To avoid a gradual loss of precision, we can use a fix-point encoding of the samples, so that the subtraction after delay is always exact. Let's say that we want a sliding sum of 10 values between 0 and 1. We know that this sum will never exceed 2^4 \u200b\u200b\u200b. We could therefore use up to 27 bits (31-4) to code the fractional part of values. The conversions are straightforward. To convert floating-point values to fix-point we can use the following expression: *(2^27):int . To convert back from fix-point to floating-point we can use the inverse expression: float:/(2^27) . We can now complete the definition of RMS. As we can see in the summation definition below, we first convert the samples to fix-point, do the summation on integers, then convert the result back to floating-point: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = float2fix(16) : _ <: _, @(n) : - : +~_ : fix2float(16); float2fix(p) = *(2^p) : int; fix2float(p) = float : /(2^p); }; Obviously this is correct only if we let enough bits for the integral part. Here we have 15 bits (31-16), enough for n up to 32000 samples. Block Sum Sliding sums have a nice and smooth behavior because an updated sum is produced every sample. But they require a large delay line (larger than n \u200b)\u200b\u200b, and can have precision problems. In this third approach, we will use a summation by blocks. The summation will be exact, will not require a large delay line, but will be only updated once per block of n samples. The code is a little bit more involved. It will require a phase signal: 0,1,2,3,\\ldots,n-1,0,1\\ldots \u200b,\u200b\u200b\u200b and a capture (sample and hold) operation. Let's start with a simplified version derived from: s:+~_ . Remind that _ is the identity function and is equivalent to *(1) . We can therefore rewrite the previous expression s:+~*(1) . Now, imagine that instead of 1 we have a boolean b as in: s:~*(b) . When b is 1 the input sample is added to the previous sum, but when b is 0 the input sample is added to 0 , and the sum is reset to be the input sample. In our case, we want to reset the sum after every block of n samples, that is, every time phase returns to 0 . This can be written: s:+~*(phase!=0) . Note that we can't use the output of this expression directly. It only represents the sum we are looking for when phase==(n-1) . That is why we need an additional capture stage to sample the sum and hold it while the next block is processed. Let's say that b indicates when to capture the input value, then: select2(b)~_ will do the job. When b is 0 , it reproduces the feedback signal, and when b is 1 , it captures the input signal. Here is the full implementation: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = + ~ *(phase != 0) : capture(phase==(n-1)); phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; }; Overlapping Block Sum As we mentioned, the block sum has the disadvantage of producing a new value only once per block. If the blocks are large, this can be a problem. In this fourth approach, we will see how to overlap the produced values. For example, we would like to compute the sum of the last 1000 samples, but with a new result every 250 samples (i.e., an overlap of 75%). The principle will be to sum small blocks of 250 samples, keep the last four sums, and add them together to produce, every 250 samples, a new sum of the last 1000 samples. Let's call w the size of a small block, and c the number of small blocks in a large block of n samples (i.e., n=c*w )\u200b. Instead of computing sums of n samples as with: + ~ *(phase != 0) , we compute sums of w samples: + ~ *(phase%w != 0) . Instead of having one capture every n samples: capture(phase == (n-1)) , we need c captures in parallel at 1*w-1 , 2*w-1 , etc.: par(i,c, capture( phase == (w*(i+1) - 1) )) Here is the full code: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; c = 4; // number of overlaps summation = + ~ *(phase%w != 0) <: par(i, c, capture( phase == (w*(i+1) - 1) )) :> _ with { w = n/c; }; phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; }; Comparing all the solutions Using the Faust IDE, we can easily compare all these solutions. To encapsulate all the definitions and select the RMS implementation, we will use an environment. If you are not familiar with the concept of environment, it is a way to group definitions. The screen shot of the Faust IDE below shows the RMS values of testsource according to the 4 methods: Sliding Sum , Fix-Point Sliding Sum , Block Sum , and Overlapping Block Sum .","title":"RMS and Summation in Faust"},{"location":"tutorials/summation/#rms-and-summation-in-faust","text":"In this tutorial, we present different programming techniques to compute the sum of n consecutive samples in Faust. Such sums are typically used when computing the RMS value of a signal. It is therefore in the RMS context that we will present them. We will not use any predefined function, only Faust primitives, so that you can see all the details. The text is intended for beginners, but with some basic knowledge of Faust. If this is not your case have a look at the various documentations on this website.","title":"RMS and Summation in Faust"},{"location":"tutorials/summation/#rms-value","text":"The computation of the RMS (Root Mean Square) value of a signal is defined by the following Faust expression: ^(2) : summation : /(n) : sqrt where n is the number of consecutive samples considered. This expression involves several steps: First, we take the square of the signal: ^(2) . This is the S of RMS. Then we sum the n consecutive samples: summation and divide this sum by n to get the mean value: /(n) . This is the M of RMS. Finally, we take the square root sqrt . This is the R of RMS. In other words, RMS is written S:M:R in Faust (leaving the summation function undefined for the moment): RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; }; In the following paragraphs, we will introduce 4 different techniques to write this summation function. We will assume that the audio samples are between -1 and 1.","title":"RMS value"},{"location":"tutorials/summation/#sliding-sum","text":"Let's start with the sliding sum approach, probably the simplest way to efficiently add n consecutive samples. First, let's recall that we can add up all the samples of a signal s , from time 0 to the present time, with the following expression: s : +~_ . The trick for adding only the last n samples is to subtract from this sum the same sum but as it was n samples earlier. For example, in order to keep only the sum of the last 10 samples, we just have to subtract from the sum of all samples (s:+~_) the value of this same sum 10 samples ago (s:+~_ : @(10)) : (s:+~_), (s:+~_ : @(10)) : - This expression can be further simplified by factoring s:+~_ . We then get: s : +~_ <: _, @(10) : - From a mathematical point of view, this is perfectly correct but poses problems when computed using floating-point numbers. Unlike mathematical numbers, floating-point numbers have a limited precision (23 bits in single precision). When calculating the RMS value, we only add positive numbers. Therefore the sum will increase forever. But at some point, when the sum exceeds 2^{23} \u200b, the least significant bit will be higher than any number between 0 \u200b and 1 \u200b. Therefore adding such a small number will be exactly like adding 0, and the sum will never evolve anymore. Fortunately, the problem can be solved easily. We just have to swap the integration and the difference parts: s <: _, @(10) : - : +~_ This new formulation is identical to the previous one from a mathematical point of view. But now, the sum will always stay between -10\u200b and +10 \u200b\u200b, and the accuracy problems are only on the least significant bits. If the roundoff error due to quantization is modeled as a uniformly distributed random number between -q/2 and q/2, then its variance (mean square) is q^2/12, and this value increases linearly over time in a running sum (see \"Wiener process\"). Thus, we expect the roundoff error in a running-sum rms calculator to grow proportional to the square root of time. We can now complete the definition of RMS: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = _ <: _, @(n) : - : +~_; };","title":"Sliding Sum"},{"location":"tutorials/summation/#fix-point-sliding-sum","text":"While the previous solution works very well with typical signals over practical time spans, the roundoff error continues to grow slowly. To avoid a gradual loss of precision, we can use a fix-point encoding of the samples, so that the subtraction after delay is always exact. Let's say that we want a sliding sum of 10 values between 0 and 1. We know that this sum will never exceed 2^4 \u200b\u200b\u200b. We could therefore use up to 27 bits (31-4) to code the fractional part of values. The conversions are straightforward. To convert floating-point values to fix-point we can use the following expression: *(2^27):int . To convert back from fix-point to floating-point we can use the inverse expression: float:/(2^27) . We can now complete the definition of RMS. As we can see in the summation definition below, we first convert the samples to fix-point, do the summation on integers, then convert the result back to floating-point: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = float2fix(16) : _ <: _, @(n) : - : +~_ : fix2float(16); float2fix(p) = *(2^p) : int; fix2float(p) = float : /(2^p); }; Obviously this is correct only if we let enough bits for the integral part. Here we have 15 bits (31-16), enough for n up to 32000 samples.","title":"Fix-Point Sliding Sum"},{"location":"tutorials/summation/#block-sum","text":"Sliding sums have a nice and smooth behavior because an updated sum is produced every sample. But they require a large delay line (larger than n \u200b)\u200b\u200b, and can have precision problems. In this third approach, we will use a summation by blocks. The summation will be exact, will not require a large delay line, but will be only updated once per block of n samples. The code is a little bit more involved. It will require a phase signal: 0,1,2,3,\\ldots,n-1,0,1\\ldots \u200b,\u200b\u200b\u200b and a capture (sample and hold) operation. Let's start with a simplified version derived from: s:+~_ . Remind that _ is the identity function and is equivalent to *(1) . We can therefore rewrite the previous expression s:+~*(1) . Now, imagine that instead of 1 we have a boolean b as in: s:~*(b) . When b is 1 the input sample is added to the previous sum, but when b is 0 the input sample is added to 0 , and the sum is reset to be the input sample. In our case, we want to reset the sum after every block of n samples, that is, every time phase returns to 0 . This can be written: s:+~*(phase!=0) . Note that we can't use the output of this expression directly. It only represents the sum we are looking for when phase==(n-1) . That is why we need an additional capture stage to sample the sum and hold it while the next block is processed. Let's say that b indicates when to capture the input value, then: select2(b)~_ will do the job. When b is 0 , it reproduces the feedback signal, and when b is 1 , it captures the input signal. Here is the full implementation: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = + ~ *(phase != 0) : capture(phase==(n-1)); phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; };","title":"Block Sum"},{"location":"tutorials/summation/#overlapping-block-sum","text":"As we mentioned, the block sum has the disadvantage of producing a new value only once per block. If the blocks are large, this can be a problem. In this fourth approach, we will see how to overlap the produced values. For example, we would like to compute the sum of the last 1000 samples, but with a new result every 250 samples (i.e., an overlap of 75%). The principle will be to sum small blocks of 250 samples, keep the last four sums, and add them together to produce, every 250 samples, a new sum of the last 1000 samples. Let's call w the size of a small block, and c the number of small blocks in a large block of n samples (i.e., n=c*w )\u200b. Instead of computing sums of n samples as with: + ~ *(phase != 0) , we compute sums of w samples: + ~ *(phase%w != 0) . Instead of having one capture every n samples: capture(phase == (n-1)) , we need c captures in parallel at 1*w-1 , 2*w-1 , etc.: par(i,c, capture( phase == (w*(i+1) - 1) )) Here is the full code: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; c = 4; // number of overlaps summation = + ~ *(phase%w != 0) <: par(i, c, capture( phase == (w*(i+1) - 1) )) :> _ with { w = n/c; }; phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; };","title":"Overlapping Block Sum"},{"location":"tutorials/summation/#comparing-all-the-solutions","text":"Using the Faust IDE, we can easily compare all these solutions. To encapsulate all the definitions and select the RMS implementation, we will use an environment. If you are not familiar with the concept of environment, it is a way to group definitions. The screen shot of the Faust IDE below shows the RMS values of testsource according to the 4 methods: Sliding Sum , Fix-Point Sliding Sum , Block Sum , and Overlapping Block Sum .","title":"Comparing all the solutions"},{"location":"tutorials/teensy/","text":"DSP on the Teensy With Faust Introduction The Teensy is a development board series based on a microcontroller and distributed by PJRC . The Teensys 3.(2+) are based on an ARM Cortex-M4 providing plenty of computational power for real-time audio signal processing applications. In particular, the Cortex-M4 used on the Teensy 3.6 (MK66FX1M0VMD18) hosts a Floating Point Unit (FPU) and has a clock of 180MHz (overclockable at 240MHz). Also, PJRC recently released the Teensy 4.0 which is based on a Cortex-M7 (FPU) with a clock of 600MHz and much more memory than the 3.6. When combined with their respective audio shields (also distributed by PJRC), the Teensy 3.6/4.0 can be used to synthesize and process sound with advanced algorithms, etc. This paper provides a survey on the performances of such system when used with Faust-generated DSP objects. The Teensy and Its Audio Shield Using this type of chip for embedded real-time audio DSP presents a wide range of advantages: low power consumption (i.e., can be easily powered by a battery), bare-metal: the lack of operating system allows for the use of very low block sizes (i.e., as low as 8 samples on the Teensy) and therefore extremely low latency, very short boot time (<1s), etc. The Teensy/ Teensyduino comes with an Audio Library that can be used to synthesize sound directly on the Teensy. It uses a patching paradigm where DSP objects can be connected together using virtual patch chords. An online tool provides a user interface to this system and allows for the implementation of sound processing algorithms in a \"Max/MSP way.\" Various elements can be used as the input and the output of the system (e.g., built-in Teensy DAC/ADC, audio shield, etc.). More information and tutorials can be found on the Audio Library webpage . The current DSP objects of the Teensy Audio Library can be used to implement simple algorithms but their scope is relatively limited (i.e., basic oscillators, filters, etc.). faust2teensy can be used to implement new objects for the Teensy Audio Library using Faust. Since Faust is currently not able to produce fixed-point DSP C++ code, generated object use floating point arithmetic internally. The main consequence is that this system will only work efficiently if it's used on a Teensy board hosting an FPU. Hence, we strongly recommend you to use the Teensy 3.6/4.0 for this (things will work on the 3.2, but computational power will be extremely limited). This tutorial walks you through the steps of synthesizing sound with Faust on the Teensy. Band-Limited Sawtooth Oscillator on the Teensy The source code of the section can be downloaded here The Teensy Audio Library doesn't come with any band-limited sawtooth wave oscillator (which are crucial to the implementation of good quality virtual analog synthesizer). The Faust libraries come with a wide range of band-limited oscillators that can be easily ported to the Teensy. The following program ( FaustSawtooth.dsp ) implements a sawtooth wave oscillator with controllable gain and frequency: si.smoo is used to interpolate the values of the freq and gain parameters to prevent clicks and abrupt changes. This Faust program can be turned into an object for the Teensy Audio Library simply by running the following command in a terminal: faust2teensy -lib FaustSawtooth.dsp which will generate a zip file containing a .cpp and a .h file in return. Alternatively, the Faust online compilation service can be used through the Faust Web IDE to carry out this task (Export(Truck)/source/teensy). The generated package should contain a file called FaustSawtooth.cpp and FaustSawtooth.h . Create a new project in the Arduino/Teensyduino software (e.g., call it faustSawtooth ) and place FaustSawtooth.cpp and FaustSawtooth.h in the same folder (whose name should probably be /faustSawtooth ) than faustSawtooth.ino . Replace the content of the Arduino program with the following: #include <Audio.h> #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,0,out,1); void setup() { AudioMemory(2); audioShield.enable(); audioShield.volume(0.1); } void loop() { faustSawtooth.setParamValue(\"freq\",random(50,1000)); delay(50); } First, the header file ( .h ) of the object generated with faust2teensy is included. An instance of FaustSawtooth is then created. Since the Teensy (3.6/4.0) that we're using for this tutorial is equipped with a Teensy Audio Shied, we also create an instance of AudioOutputI2S and AudioControlSGTL5000 . We then connect the Faust object to the 2 outputs of the audio shield using AudioConnection s. Note that if the Faust object had a stereo output (i.e., process = os.sawtooth(freq)*gain <: _,_ ), the following should have been written instead: AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,1,out,1); The number of inputs and outputs of objects generated with faust2teensy corresponds to the number inputs and outputs of the Faust program. 2 bytes of memory are allocated in setup() . Note that if the Faust object had audio inputs, this number should probably be greater (i.e., typically 6 for stereo in and stereo out). audioShield.enable() activates the audio shield and audioShield.volume(0.1) sets the gain of the headphone output (this step is optional). The value of the freq and gain parameters can be set using the setParamValue method. Note that for larger Faust objects, parameter paths might be used instead. Here, the value of freq is randomly generated every 50ms. After making these changes, you should be able to compile and upload your sketch to the Teensy 4.0. Special Note About the Teensy 3.6 Before this program can be compiled and uploaded to the Teensy 3.6, some modifications need to be made to the configuration file used by the compilation script used by Teensyduino ( boards.txt ). You should be able to find it in hardware/teensy/avr in the source of the Arduino software (its location will vary depending on the platform your using). The most important thing to do here is to use g++ instead of gcc for linking, so: teensy36.build.command.linker=arm-none-eabi-gcc should become: teensy36.build.command.linker=arm-none-eabi-g++ in boards.txt . Beware that on older versions of Teensyduino, these changes should be made directly to platform.txt . After making these changes, you should be able to compile and upload your sketch to the Teensy 3.6. Audio Effect The source code of the section can be downloaded here The same procedure as the one described in the previous section can be followed to generate audio effects for the Teensy Audio Library. dm.zita_light implements a high quality stereo feedback delay network reverb. It hosts its own user interface elements/parameters to control its dry/wet mix ( Dry/Wet Mix ) and its level in dB ( Level ). A simple Faust program ( FaustZita.dsp ) calling this effect could look like that: The corresponding Teensy Audio Library object can be generated by running: faust2teensy -lib FaustZita.dsp and finally called in a Teensy program: #include <Audio.h> #include \"FaustZita.h\" FaustZita faustZita; AudioInputI2S in; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(in,0,faustZita,0); AudioConnection patchCord1(in,1,faustZita,1); AudioConnection patchCord2(faustZita,0,out,0); AudioConnection patchCord3(faustZita,1,out,1); void setup() { AudioMemory(6); audioShield.enable(); faustZita.setParamValue(\"level\",0); } void loop() { float dw = analogRead(A0)/512 - 1; faustZita.setParamValue(\"dryWet\",dw); delay(10); } Note that in this example, a potentiometer connected to the Analog Input 0 of the Teensy is used to control the dry/wet mix of the reverb. Additional Configuration for Low Audio Latency Thanks to its bare-metal architecture, the Teensy allows for extremely low audio latency which would be more or less impossible to achieve if an operating system was used. Audio latency is mostly determined by the block size of the system. The default block size of the Teensy Audio Library is 128 samples but it can be cranked down to 8 samples (only if Faust DSP objects are used exclusively) without impacting performances too much (see the corresponding SMC paper ). Block size is set by a C++ macro ( AUDIO_BLOCK_SAMPLES ) that can be overridden before compilation by passing it as an argument to the C++ compiler by substituting the following line in boards.txt (see previous section): teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 3.6, and: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 4.0. Similarly, the sampling rate (44100KHz by default) can be set using the AUDIO_SAMPLE_RATE_EXACT macro. Note that computing the \"exact\" sampling rate compatible with the clock of your Teensy might be a bit tricky. For example, AUDIO_SAMPLE_RATE_EXACT is 44117.64706 by default and not 44100, etc. Warning!!! In the latest version of the Teensy Audio Library, a \"weird\" correction to the code of the built-in freeverb function has been made an will prevent you from using a block size of 8 samples. Here's a fix to this problem that should be made in the installed version of effect_freeverb.cpp : 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0, #if AUDIO_BLOCK_SAMPLES > 8 0, 0, 0, 0, 0, 0, 0, 0, #endif #if AUDIO_BLOCK_SAMPLES > 16 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, #endif Notes About Computational Power and Memory Footprint While the Teensy 3.6 is relatively powerful and can be used to run complex DSP algorithm (up to 90 Faust sine waves in parallel), it doesn't have a lot of RAM. For that reason, algorithms with a large memory footprint (e.g., anything using delay a lot such a reverbs, wave table oscillators, etc.) might have to be adapted to be run on the Teensy. For example, the default Faust sine wave oscillator uses a table of 65536 samples which is to big to be loaded in the Teensy RAM. Hence, its definition should be adapted, e.g.: osc(freq) = rdtable(tablesize, os.sinwaveform(tablesize), int(os.phasor(tablesize,freq))) with{ tablesize = 1 << 15; // instead of 1 << 16 }; Similarly, the maximum size of the delay lines of some reverb algorithms might be too big and should be adjusted. Using the -dlt option can help, see the Managing DSP Memory Size section.","title":"DSP on the Teensy With Faust"},{"location":"tutorials/teensy/#dsp-on-the-teensy-with-faust","text":"","title":"DSP on the Teensy With Faust"},{"location":"tutorials/teensy/#introduction","text":"The Teensy is a development board series based on a microcontroller and distributed by PJRC . The Teensys 3.(2+) are based on an ARM Cortex-M4 providing plenty of computational power for real-time audio signal processing applications. In particular, the Cortex-M4 used on the Teensy 3.6 (MK66FX1M0VMD18) hosts a Floating Point Unit (FPU) and has a clock of 180MHz (overclockable at 240MHz). Also, PJRC recently released the Teensy 4.0 which is based on a Cortex-M7 (FPU) with a clock of 600MHz and much more memory than the 3.6. When combined with their respective audio shields (also distributed by PJRC), the Teensy 3.6/4.0 can be used to synthesize and process sound with advanced algorithms, etc. This paper provides a survey on the performances of such system when used with Faust-generated DSP objects. The Teensy and Its Audio Shield Using this type of chip for embedded real-time audio DSP presents a wide range of advantages: low power consumption (i.e., can be easily powered by a battery), bare-metal: the lack of operating system allows for the use of very low block sizes (i.e., as low as 8 samples on the Teensy) and therefore extremely low latency, very short boot time (<1s), etc. The Teensy/ Teensyduino comes with an Audio Library that can be used to synthesize sound directly on the Teensy. It uses a patching paradigm where DSP objects can be connected together using virtual patch chords. An online tool provides a user interface to this system and allows for the implementation of sound processing algorithms in a \"Max/MSP way.\" Various elements can be used as the input and the output of the system (e.g., built-in Teensy DAC/ADC, audio shield, etc.). More information and tutorials can be found on the Audio Library webpage . The current DSP objects of the Teensy Audio Library can be used to implement simple algorithms but their scope is relatively limited (i.e., basic oscillators, filters, etc.). faust2teensy can be used to implement new objects for the Teensy Audio Library using Faust. Since Faust is currently not able to produce fixed-point DSP C++ code, generated object use floating point arithmetic internally. The main consequence is that this system will only work efficiently if it's used on a Teensy board hosting an FPU. Hence, we strongly recommend you to use the Teensy 3.6/4.0 for this (things will work on the 3.2, but computational power will be extremely limited). This tutorial walks you through the steps of synthesizing sound with Faust on the Teensy.","title":"Introduction"},{"location":"tutorials/teensy/#band-limited-sawtooth-oscillator-on-the-teensy","text":"The source code of the section can be downloaded here The Teensy Audio Library doesn't come with any band-limited sawtooth wave oscillator (which are crucial to the implementation of good quality virtual analog synthesizer). The Faust libraries come with a wide range of band-limited oscillators that can be easily ported to the Teensy. The following program ( FaustSawtooth.dsp ) implements a sawtooth wave oscillator with controllable gain and frequency: si.smoo is used to interpolate the values of the freq and gain parameters to prevent clicks and abrupt changes. This Faust program can be turned into an object for the Teensy Audio Library simply by running the following command in a terminal: faust2teensy -lib FaustSawtooth.dsp which will generate a zip file containing a .cpp and a .h file in return. Alternatively, the Faust online compilation service can be used through the Faust Web IDE to carry out this task (Export(Truck)/source/teensy). The generated package should contain a file called FaustSawtooth.cpp and FaustSawtooth.h . Create a new project in the Arduino/Teensyduino software (e.g., call it faustSawtooth ) and place FaustSawtooth.cpp and FaustSawtooth.h in the same folder (whose name should probably be /faustSawtooth ) than faustSawtooth.ino . Replace the content of the Arduino program with the following: #include <Audio.h> #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,0,out,1); void setup() { AudioMemory(2); audioShield.enable(); audioShield.volume(0.1); } void loop() { faustSawtooth.setParamValue(\"freq\",random(50,1000)); delay(50); } First, the header file ( .h ) of the object generated with faust2teensy is included. An instance of FaustSawtooth is then created. Since the Teensy (3.6/4.0) that we're using for this tutorial is equipped with a Teensy Audio Shied, we also create an instance of AudioOutputI2S and AudioControlSGTL5000 . We then connect the Faust object to the 2 outputs of the audio shield using AudioConnection s. Note that if the Faust object had a stereo output (i.e., process = os.sawtooth(freq)*gain <: _,_ ), the following should have been written instead: AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,1,out,1); The number of inputs and outputs of objects generated with faust2teensy corresponds to the number inputs and outputs of the Faust program. 2 bytes of memory are allocated in setup() . Note that if the Faust object had audio inputs, this number should probably be greater (i.e., typically 6 for stereo in and stereo out). audioShield.enable() activates the audio shield and audioShield.volume(0.1) sets the gain of the headphone output (this step is optional). The value of the freq and gain parameters can be set using the setParamValue method. Note that for larger Faust objects, parameter paths might be used instead. Here, the value of freq is randomly generated every 50ms. After making these changes, you should be able to compile and upload your sketch to the Teensy 4.0.","title":"Band-Limited Sawtooth Oscillator on the Teensy"},{"location":"tutorials/teensy/#special-note-about-the-teensy-36","text":"Before this program can be compiled and uploaded to the Teensy 3.6, some modifications need to be made to the configuration file used by the compilation script used by Teensyduino ( boards.txt ). You should be able to find it in hardware/teensy/avr in the source of the Arduino software (its location will vary depending on the platform your using). The most important thing to do here is to use g++ instead of gcc for linking, so: teensy36.build.command.linker=arm-none-eabi-gcc should become: teensy36.build.command.linker=arm-none-eabi-g++ in boards.txt . Beware that on older versions of Teensyduino, these changes should be made directly to platform.txt . After making these changes, you should be able to compile and upload your sketch to the Teensy 3.6.","title":"Special Note About the Teensy 3.6"},{"location":"tutorials/teensy/#audio-effect","text":"The source code of the section can be downloaded here The same procedure as the one described in the previous section can be followed to generate audio effects for the Teensy Audio Library. dm.zita_light implements a high quality stereo feedback delay network reverb. It hosts its own user interface elements/parameters to control its dry/wet mix ( Dry/Wet Mix ) and its level in dB ( Level ). A simple Faust program ( FaustZita.dsp ) calling this effect could look like that: The corresponding Teensy Audio Library object can be generated by running: faust2teensy -lib FaustZita.dsp and finally called in a Teensy program: #include <Audio.h> #include \"FaustZita.h\" FaustZita faustZita; AudioInputI2S in; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(in,0,faustZita,0); AudioConnection patchCord1(in,1,faustZita,1); AudioConnection patchCord2(faustZita,0,out,0); AudioConnection patchCord3(faustZita,1,out,1); void setup() { AudioMemory(6); audioShield.enable(); faustZita.setParamValue(\"level\",0); } void loop() { float dw = analogRead(A0)/512 - 1; faustZita.setParamValue(\"dryWet\",dw); delay(10); } Note that in this example, a potentiometer connected to the Analog Input 0 of the Teensy is used to control the dry/wet mix of the reverb.","title":"Audio Effect"},{"location":"tutorials/teensy/#additional-configuration-for-low-audio-latency","text":"Thanks to its bare-metal architecture, the Teensy allows for extremely low audio latency which would be more or less impossible to achieve if an operating system was used. Audio latency is mostly determined by the block size of the system. The default block size of the Teensy Audio Library is 128 samples but it can be cranked down to 8 samples (only if Faust DSP objects are used exclusively) without impacting performances too much (see the corresponding SMC paper ). Block size is set by a C++ macro ( AUDIO_BLOCK_SAMPLES ) that can be overridden before compilation by passing it as an argument to the C++ compiler by substituting the following line in boards.txt (see previous section): teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 3.6, and: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 4.0. Similarly, the sampling rate (44100KHz by default) can be set using the AUDIO_SAMPLE_RATE_EXACT macro. Note that computing the \"exact\" sampling rate compatible with the clock of your Teensy might be a bit tricky. For example, AUDIO_SAMPLE_RATE_EXACT is 44117.64706 by default and not 44100, etc.","title":"Additional Configuration for Low Audio Latency"},{"location":"tutorials/teensy/#warning","text":"In the latest version of the Teensy Audio Library, a \"weird\" correction to the code of the built-in freeverb function has been made an will prevent you from using a block size of 8 samples. Here's a fix to this problem that should be made in the installed version of effect_freeverb.cpp : 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0, #if AUDIO_BLOCK_SAMPLES > 8 0, 0, 0, 0, 0, 0, 0, 0, #endif #if AUDIO_BLOCK_SAMPLES > 16 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, #endif","title":"Warning!!!"},{"location":"tutorials/teensy/#notes-about-computational-power-and-memory-footprint","text":"While the Teensy 3.6 is relatively powerful and can be used to run complex DSP algorithm (up to 90 Faust sine waves in parallel), it doesn't have a lot of RAM. For that reason, algorithms with a large memory footprint (e.g., anything using delay a lot such a reverbs, wave table oscillators, etc.) might have to be adapted to be run on the Teensy. For example, the default Faust sine wave oscillator uses a table of 65536 samples which is to big to be loaded in the Teensy RAM. Hence, its definition should be adapted, e.g.: osc(freq) = rdtable(tablesize, os.sinwaveform(tablesize), int(os.phasor(tablesize,freq))) with{ tablesize = 1 << 15; // instead of 1 << 16 }; Similarly, the maximum size of the delay lines of some reverb algorithms might be too big and should be adjusted. Using the -dlt option can help, see the Managing DSP Memory Size section.","title":"Notes About Computational Power and Memory Footprint"},{"location":"tutorials/unity/","text":"Faust and Unity TODO","title":"Faust and Unity"},{"location":"tutorials/unity/#faust-and-unity","text":"TODO","title":"Faust and Unity"},{"location":"workshops/2018-12-01-paw/","text":"Building a Simple MIDI Synthesizer We are going to build a MIDI synthesizer from scratch (without using the Faust libraries). Phase Generator The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate: Ramp In order to produce the above signal we need first to produce a ramp signal using the following Faust program: You can think of a Faust program as a description of an audio circuit where 0.125 , + and _ are primitives of the language (predefined elementary audio components), and the other two signs: : and ~ are used to connect together these audio components. Semantics To understand the above diagram let's annotate it with its mathematical semantics. As we can see in the diagram, the formula of the output signal is: y(t) = y(t-1) + 0.125 We can compute the first values of y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Phase Signal How can we transform the above ramp into sawtooth signal ? By removing the integer part of the samples in order to keep only the decimal (fractional) part ( 3.14159 -> 0.14159 ). Let's define a function to do that: decimalpart(x) = x - int(x); We can now use that function to transform our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view that would be perfectly correct, but we will accumulate rounding errors. To keep full precision it is better to place the decimal part operation inside the loop: process = 0.125 : (+ : decimalpart) ~ _; We can now listen the produced signal. Just copy and past decimalpart and process definitions into the Faust Web IDE . Controlling the Frequency of the Phase Signal Let's first rearrange our code: In our phase definition the step value, here 0.125 controls the frequency of the generated signal. We would like to compute this step value according to the desired frequency. In order to do the conversion we need to know the sampling rate. It is available from the standard library as ma.SR . Let say we would like our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR so that is will take ma.SR samples (i.e. 1 second) for the phase signal to reach 1. If we want a frequency of 440 Hz, we need a step 440 times bigger for the phase signal to reach 1 440 times faster. phase = 440/ma.SR : (+ : decimalpart) ~ _; We can generalize this definition by replacing 440 by a parameter f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and by indicating the desired frequency when we use phase : process = phase(440); Creating a Sine Wave Oscillator The next step is to transform above phase generator into a sine wave generator. We will use the sin primitive that computes the sine of x (measured in radians). Therefore we start for the phase signal, we multiply it by 2PI to obtain radiants, and compute the sine. The full program is the following: Controlling the Frequency and Gain of the Oscillator The next step is to add some controls on the frequency and gain of the oscillator. We can replace the fixed frequency 440 by a user interface slider: process = osc(hslider(\"freq\", 440, 20, 10000, 1)); and add a gain to control the output level of the oscillator: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01); Adding a Gate Button In order to prepare our MIDI synthesizer we need to add a gate button so that the sound is only when we press it: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01) * button(\"gate\"); Adding an Envelope Generator It is a good idea to also add an envelop generator. Here we will use a predefined ADSR in the Standard Faust library. Improving the Timbre Instead of playing pure sine waves tones, let's improve the timbre with simple additive synthesis: Running as a Polyphonic MIDI Synth To control the synthesizer using MIDI you need to use Chrome. The polyphonic MIDI mode is activated using the drop down menu Poly Voices on the left side of the editor. Choose Computer Keyboard as MIDI input to play notes with the computer keyboard, or plug a MIDI keyboard. Adding a Global Effect A global effect can be added by providing a definition for effect . // Common effect effect = dm.zita_light;","title":" 2018-12-01 PAW "},{"location":"workshops/2018-12-01-paw/#building-a-simple-midi-synthesizer","text":"We are going to build a MIDI synthesizer from scratch (without using the Faust libraries).","title":"Building a Simple MIDI Synthesizer"},{"location":"workshops/2018-12-01-paw/#phase-generator","text":"The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate:","title":"Phase Generator"},{"location":"workshops/2018-12-01-paw/#ramp","text":"In order to produce the above signal we need first to produce a ramp signal using the following Faust program: You can think of a Faust program as a description of an audio circuit where 0.125 , + and _ are primitives of the language (predefined elementary audio components), and the other two signs: : and ~ are used to connect together these audio components.","title":"Ramp"},{"location":"workshops/2018-12-01-paw/#semantics","text":"To understand the above diagram let's annotate it with its mathematical semantics. As we can see in the diagram, the formula of the output signal is: y(t) = y(t-1) + 0.125 We can compute the first values of y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"Semantics"},{"location":"workshops/2018-12-01-paw/#phase-signal","text":"How can we transform the above ramp into sawtooth signal ? By removing the integer part of the samples in order to keep only the decimal (fractional) part ( 3.14159 -> 0.14159 ). Let's define a function to do that: decimalpart(x) = x - int(x); We can now use that function to transform our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view that would be perfectly correct, but we will accumulate rounding errors. To keep full precision it is better to place the decimal part operation inside the loop: process = 0.125 : (+ : decimalpart) ~ _; We can now listen the produced signal. Just copy and past decimalpart and process definitions into the Faust Web IDE .","title":"Phase Signal"},{"location":"workshops/2018-12-01-paw/#controlling-the-frequency-of-the-phase-signal","text":"Let's first rearrange our code: In our phase definition the step value, here 0.125 controls the frequency of the generated signal. We would like to compute this step value according to the desired frequency. In order to do the conversion we need to know the sampling rate. It is available from the standard library as ma.SR . Let say we would like our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR so that is will take ma.SR samples (i.e. 1 second) for the phase signal to reach 1. If we want a frequency of 440 Hz, we need a step 440 times bigger for the phase signal to reach 1 440 times faster. phase = 440/ma.SR : (+ : decimalpart) ~ _; We can generalize this definition by replacing 440 by a parameter f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and by indicating the desired frequency when we use phase : process = phase(440);","title":"Controlling the Frequency of the Phase Signal"},{"location":"workshops/2018-12-01-paw/#creating-a-sine-wave-oscillator","text":"The next step is to transform above phase generator into a sine wave generator. We will use the sin primitive that computes the sine of x (measured in radians). Therefore we start for the phase signal, we multiply it by 2PI to obtain radiants, and compute the sine. The full program is the following:","title":"Creating a Sine Wave Oscillator"},{"location":"workshops/2018-12-01-paw/#controlling-the-frequency-and-gain-of-the-oscillator","text":"The next step is to add some controls on the frequency and gain of the oscillator. We can replace the fixed frequency 440 by a user interface slider: process = osc(hslider(\"freq\", 440, 20, 10000, 1)); and add a gain to control the output level of the oscillator: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01);","title":"Controlling the Frequency and Gain of the Oscillator"},{"location":"workshops/2018-12-01-paw/#adding-a-gate-button","text":"In order to prepare our MIDI synthesizer we need to add a gate button so that the sound is only when we press it: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01) * button(\"gate\");","title":"Adding a Gate Button"},{"location":"workshops/2018-12-01-paw/#adding-an-envelope-generator","text":"It is a good idea to also add an envelop generator. Here we will use a predefined ADSR in the Standard Faust library.","title":"Adding an Envelope Generator"},{"location":"workshops/2018-12-01-paw/#improving-the-timbre","text":"Instead of playing pure sine waves tones, let's improve the timbre with simple additive synthesis:","title":"Improving the Timbre"},{"location":"workshops/2018-12-01-paw/#running-as-a-polyphonic-midi-synth","text":"To control the synthesizer using MIDI you need to use Chrome. The polyphonic MIDI mode is activated using the drop down menu Poly Voices on the left side of the editor. Choose Computer Keyboard as MIDI input to play notes with the computer keyboard, or plug a MIDI keyboard.","title":"Running as a Polyphonic MIDI Synth"},{"location":"workshops/2018-12-01-paw/#adding-a-global-effect","text":"A global effect can be added by providing a definition for effect . // Common effect effect = dm.zita_light;","title":"Adding a Global Effect"},{"location":"workshops/2020-03-24-faust-citi/","text":"Faust workshop at CITI L'objectif de ce workshop est de se familiariser avec le langage Faust \u00e0 travers des exemples simples de synth\u00e8se sonore. Tous les exemples seront execut\u00e9 dans l'IDE Faust en ligne https://faustide.grame.fr . Si jamais les sons produits avec l'IDE sont de mauvaise qualit\u00e9, avec des clics, on peut utiliser l'\u00e9diteur en ligne, plus rustique, mais aussi plus l\u00e9ger https://fausteditor.grame.fr Signal en dent de scie Par convention, en Faust, un signal audio \u00e0 pleine \u00e9chelle varie entre -1 et +1. Mais dans un premier temps nous allons commencer par un signal en dent de scie entre 0 et 1 qui nous servira par la suite de g\u00e9n\u00e9rateur de phase pour produire diff\u00e9rentes formes d'onde. G\u00e9n\u00e9rateur de Phase La premi\u00e8re \u00e9tape consiste \u00e0 construire un g\u00e9n\u00e9rateur de phase qui produit un signal p\u00e9riodique en dents de scie entre 0 et 1. Voici le signal que nous voulons g\u00e9n\u00e9rer : Rampe Pour cela nous allons produire une rampe \"infinie\", que nous transformerons ensuite en un signal p\u00e9riodique gr\u00e2ce \u00e0 une op\u00e9ration partie-decimale : La rampe est produite par le programme suivant : S\u00e9mantique Dans l'exemple pr\u00e9c\u00e9dent, 0,125 , + et _ sont des primitives du langage. Les deux autres signes : : et ~ sont des op\u00e9rateurs de cablage. Ils sont utilis\u00e9s pour relier entre elles les expressions du langage. Pour comprendre le diagramme ci-dessus, nous allons l'annoter avec sa s\u00e9mantique math\u00e9matique : Comme on peut le voir dans le diagramme, la formule du signal de sortie est : y(t) = y(t-1) + 0.125 On peut calculer les premi\u00e8res valeurs de y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Signal de phase Comment transformer la rampe ci-dessus en signal en dents de scie ? En supprimant la partie enti\u00e8re des \u00e9chantillons afin de ne garder que la partie d\u00e9cimale (fractionnaire) ( 3.14159 -> 0.14159 ). D\u00e9finissons une fonction pour faire cela : decimalpart(x) = x - int(x); Nous pouvons maintenant utiliser cette fonction pour transformer notre rampe en dents de scie. Il est alors tentant d'\u00e9crire : process = 0.125 : + ~ _ : decimalpart; D'un point de vue math\u00e9matique, ce serait parfaitement correct, mais nous allons accumuler les erreurs d'arrondi. Pour conserver une pr\u00e9cision totale, il est pr\u00e9f\u00e9rable de placer l'op\u00e9ration de la partie d\u00e9cimale \u00e0 l'int\u00e9rieur de la boucle comme ceci : process = 0.125 : (+ : decimalpart) ~ _; On peut maintenant essayer l'ensemble du code ( pensez \u00e0 baisser le volume ) : Dans notre d\u00e9finition de la phase , la valeur du pas, ici 0,125 , contr\u00f4le la fr\u00e9quence du signal g\u00e9n\u00e9r\u00e9. Nous aimerions calculer cette valeur de pas en fonction de la fr\u00e9quence souhait\u00e9e. Afin de faire la conversion, nous devons conna\u00eetre la fr\u00e9quence d'\u00e9chantillonnage. Elle est disponible dans la biblioth\u00e8que standard sous le nom de ma.SR . Pour utiliser cette biblioth\u00e8que standard nous ajoutons au programme la ligne suivante : import(\"stdfaust.lib\"); Supposons que nous voulions que notre signal de phase ait une fr\u00e9quence de 1 Hz, alors le pas devrait \u00eatre tr\u00e8s petit 1/ma.SR , afin qu'il faille ma.SR \u00e9chantillons (c'est \u00e0 dire 1 seconde) pour que le signal de phase passe de 0 \u00e0 1. Si nous voulons une fr\u00e9quence de 440 Hz, nous avons besoin d'un pas 440 fois plus grand pour que le signal de phase passe de 0 \u00e0 1 440 fois plus vite : phase = 440/ma.SR : (+ : decimalpart) ~ _; On peut g\u00e9n\u00e9raliser cette d\u00e9finition en rempla\u00e7ant 440 par un param\u00e8tre f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; et en passant la fr\u00e9quence souhait\u00e9e \u00e0 phase : process = phase(440); Generateur de signal en dent de scie Nous pouvons maintenant nous servir du g\u00e9n\u00e9rateur de phase pour produire un signal en dent de scie : Generateur de signal carr\u00e9 Nous pouvons \u00e9galement nous servir du g\u00e9n\u00e9rateurr de phase pour produire un signal carr\u00e9 : Synth\u00e8se additive Exemple 1 : g\u00e9n\u00e9rateur sinusoidal Le g\u00e9n\u00e9rateur de phase est \u00e9galement \u00e0 la base de l'oscillateur sinusoidal : Mais maintenant que nous avons vu comment cr\u00e9er de toutes pi\u00e8ces un oscillateur sinusoidal, nous allons utiliser celui qui est d\u00e9fini dans la libraries standard de Faust : Exemple 2 : une onde sinusoidale avec controle de volume Dans ce deuxi\u00e8me exemple on a utilis\u00e9 un slider horizontal hslider(...) pour r\u00e9gler le niveau sonore : Le premier param\u00e8tre est une chaine de caract\u00e8re qui indique le nom du slider. Il est suivi de quatre param\u00e8tres num\u00e9riques. Le deuxi\u00e8me param\u00e8tre 0.1 indique la valeur par d\u00e9faut du slider, c'est \u00e0 dire la valeur que va d\u00e9livrer le slider quand on lance le programme. Ensuite nous avons la valeur minimale 0 , la valeur maximale 1 et le pas de variation 0.01 . Exemple 3 : Exercice, ajouter un contr\u00f4le de fr\u00e9quence A titre d'exercice, remplacer, dans l'exemple pr\u00e9c\u00e9dent, la fr\u00e9quence 440 par un slider horizontal dont le nom sera \"freq\" , la valeur par d\u00e9faut 110 , la valeur minimale 40 , la valeur maximale 8000 et le pas 1 . Exemple 4 : Ph\u00e9nom\u00e8ne de repliement de fr\u00e9quence au-del\u00e0 de SR/2 Un probl\u00e8me bien connu dans le domaine de la synth\u00e8se num\u00e9rique du son est celui du repliement de fr\u00e9quence : toute fr\u00e9quence au dela de la moiti\u00e9 de la fr\u00e9quence d'\u00e9chatillonnage se retrouve repli\u00e9e dans le spectre audible : Exemple 5 : Synth\u00e8se additive Un exemple de synth\u00e8se additive ou le niveau de chaque partiel peut \u00eatre r\u00e9gl\u00e9 individuellement : A noter l'utilisation de la construction sum(i, n, foo(i)) qui est equivalente \u00e0 foo(0)+foo(1)+...+foo(n-1) . Exemple 6 : Approximation d'un signal carr\u00e9 par synth\u00e8se additive Nous avons vu pr\u00e9c\u00e9demment comment produire une signal carr\u00e9 parfait. Ce signal carr\u00e9 parfait comporte une infinit\u00e9 d'harmoniques qui, du fait de l'\u00e9chantillonnage, vont se replier sur le spectre audible, ce qui va donner un son bruit\u00e9 moins fid\u00e8le ! On peut approximer un signal carr\u00e9 par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques impaires (voir https://fr.wikipedia.org/wiki/Signal_carr\u00e9 ) : A titre d'excercice, faire varier le nombre d'harmoniques pour voir l'approximation s'am\u00e9liorer (mais sans d\u00e9passer SR/2). Exemple 7 : Approximation d'un signal en dent de scie par synth\u00e8se additive De m\u00eame on peut approximer un signal en dent de scie par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques (voir https://fr.wikipedia.org/wiki/Signal_en_dents_de_scie ) : Synth\u00e8se soustractive La synth\u00e8se soustractive proc\u00e8de \u00e0 l'inverse de la synth\u00e8se additive. Elle consiste \u00e0 partir d'un son riche, par exemple un bruit blanc, et \u00e0 sculpter son spectre. Exemple 1 : un bruit blanc Un bruit blanc : Exemple 2 : lowpass Exemple 3 : high pass Exemple 4 : bandpass Exemple 5 : resonnant Exemple 6 : fir Exemple 7 : iir Exemple 8 : filtre en peigne Exemple 9 : Karplus Strong (1/2) Exemple 10 : Karplus Strong (2/2) Exemple 11 : Kisana Synth\u00e8se par modulation de fr\u00e9quence Exemple 1 : fm1 Exemple 2 : fm2","title":" 2020-03-24 CITI "},{"location":"workshops/2020-03-24-faust-citi/#faust-workshop-at-citi","text":"L'objectif de ce workshop est de se familiariser avec le langage Faust \u00e0 travers des exemples simples de synth\u00e8se sonore. Tous les exemples seront execut\u00e9 dans l'IDE Faust en ligne https://faustide.grame.fr . Si jamais les sons produits avec l'IDE sont de mauvaise qualit\u00e9, avec des clics, on peut utiliser l'\u00e9diteur en ligne, plus rustique, mais aussi plus l\u00e9ger https://fausteditor.grame.fr","title":"Faust workshop at CITI"},{"location":"workshops/2020-03-24-faust-citi/#signal-en-dent-de-scie","text":"Par convention, en Faust, un signal audio \u00e0 pleine \u00e9chelle varie entre -1 et +1. Mais dans un premier temps nous allons commencer par un signal en dent de scie entre 0 et 1 qui nous servira par la suite de g\u00e9n\u00e9rateur de phase pour produire diff\u00e9rentes formes d'onde.","title":"Signal en dent de scie"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-phase","text":"La premi\u00e8re \u00e9tape consiste \u00e0 construire un g\u00e9n\u00e9rateur de phase qui produit un signal p\u00e9riodique en dents de scie entre 0 et 1. Voici le signal que nous voulons g\u00e9n\u00e9rer :","title":"G\u00e9n\u00e9rateur de Phase"},{"location":"workshops/2020-03-24-faust-citi/#rampe","text":"Pour cela nous allons produire une rampe \"infinie\", que nous transformerons ensuite en un signal p\u00e9riodique gr\u00e2ce \u00e0 une op\u00e9ration partie-decimale : La rampe est produite par le programme suivant :","title":"Rampe"},{"location":"workshops/2020-03-24-faust-citi/#semantique","text":"Dans l'exemple pr\u00e9c\u00e9dent, 0,125 , + et _ sont des primitives du langage. Les deux autres signes : : et ~ sont des op\u00e9rateurs de cablage. Ils sont utilis\u00e9s pour relier entre elles les expressions du langage. Pour comprendre le diagramme ci-dessus, nous allons l'annoter avec sa s\u00e9mantique math\u00e9matique : Comme on peut le voir dans le diagramme, la formule du signal de sortie est : y(t) = y(t-1) + 0.125 On peut calculer les premi\u00e8res valeurs de y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"S\u00e9mantique"},{"location":"workshops/2020-03-24-faust-citi/#signal-de-phase","text":"Comment transformer la rampe ci-dessus en signal en dents de scie ? En supprimant la partie enti\u00e8re des \u00e9chantillons afin de ne garder que la partie d\u00e9cimale (fractionnaire) ( 3.14159 -> 0.14159 ). D\u00e9finissons une fonction pour faire cela : decimalpart(x) = x - int(x); Nous pouvons maintenant utiliser cette fonction pour transformer notre rampe en dents de scie. Il est alors tentant d'\u00e9crire : process = 0.125 : + ~ _ : decimalpart; D'un point de vue math\u00e9matique, ce serait parfaitement correct, mais nous allons accumuler les erreurs d'arrondi. Pour conserver une pr\u00e9cision totale, il est pr\u00e9f\u00e9rable de placer l'op\u00e9ration de la partie d\u00e9cimale \u00e0 l'int\u00e9rieur de la boucle comme ceci : process = 0.125 : (+ : decimalpart) ~ _; On peut maintenant essayer l'ensemble du code ( pensez \u00e0 baisser le volume ) : Dans notre d\u00e9finition de la phase , la valeur du pas, ici 0,125 , contr\u00f4le la fr\u00e9quence du signal g\u00e9n\u00e9r\u00e9. Nous aimerions calculer cette valeur de pas en fonction de la fr\u00e9quence souhait\u00e9e. Afin de faire la conversion, nous devons conna\u00eetre la fr\u00e9quence d'\u00e9chantillonnage. Elle est disponible dans la biblioth\u00e8que standard sous le nom de ma.SR . Pour utiliser cette biblioth\u00e8que standard nous ajoutons au programme la ligne suivante : import(\"stdfaust.lib\"); Supposons que nous voulions que notre signal de phase ait une fr\u00e9quence de 1 Hz, alors le pas devrait \u00eatre tr\u00e8s petit 1/ma.SR , afin qu'il faille ma.SR \u00e9chantillons (c'est \u00e0 dire 1 seconde) pour que le signal de phase passe de 0 \u00e0 1. Si nous voulons une fr\u00e9quence de 440 Hz, nous avons besoin d'un pas 440 fois plus grand pour que le signal de phase passe de 0 \u00e0 1 440 fois plus vite : phase = 440/ma.SR : (+ : decimalpart) ~ _; On peut g\u00e9n\u00e9raliser cette d\u00e9finition en rempla\u00e7ant 440 par un param\u00e8tre f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; et en passant la fr\u00e9quence souhait\u00e9e \u00e0 phase : process = phase(440);","title":"Signal de phase"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-signal-en-dent-de-scie","text":"Nous pouvons maintenant nous servir du g\u00e9n\u00e9rateur de phase pour produire un signal en dent de scie :","title":"Generateur de signal en dent de scie"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-signal-carre","text":"Nous pouvons \u00e9galement nous servir du g\u00e9n\u00e9rateurr de phase pour produire un signal carr\u00e9 :","title":"Generateur de signal carr\u00e9"},{"location":"workshops/2020-03-24-faust-citi/#synthese-additive","text":"","title":"Synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-generateur-sinusoidal","text":"Le g\u00e9n\u00e9rateur de phase est \u00e9galement \u00e0 la base de l'oscillateur sinusoidal : Mais maintenant que nous avons vu comment cr\u00e9er de toutes pi\u00e8ces un oscillateur sinusoidal, nous allons utiliser celui qui est d\u00e9fini dans la libraries standard de Faust :","title":"Exemple 1 : g\u00e9n\u00e9rateur sinusoidal"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-une-onde-sinusoidale-avec-controle-de-volume","text":"Dans ce deuxi\u00e8me exemple on a utilis\u00e9 un slider horizontal hslider(...) pour r\u00e9gler le niveau sonore : Le premier param\u00e8tre est une chaine de caract\u00e8re qui indique le nom du slider. Il est suivi de quatre param\u00e8tres num\u00e9riques. Le deuxi\u00e8me param\u00e8tre 0.1 indique la valeur par d\u00e9faut du slider, c'est \u00e0 dire la valeur que va d\u00e9livrer le slider quand on lance le programme. Ensuite nous avons la valeur minimale 0 , la valeur maximale 1 et le pas de variation 0.01 .","title":"Exemple 2 : une onde sinusoidale avec controle de volume"},{"location":"workshops/2020-03-24-faust-citi/#exemple-3-exercice-ajouter-un-controle-de-frequence","text":"A titre d'exercice, remplacer, dans l'exemple pr\u00e9c\u00e9dent, la fr\u00e9quence 440 par un slider horizontal dont le nom sera \"freq\" , la valeur par d\u00e9faut 110 , la valeur minimale 40 , la valeur maximale 8000 et le pas 1 .","title":"Exemple 3 : Exercice, ajouter un contr\u00f4le de fr\u00e9quence"},{"location":"workshops/2020-03-24-faust-citi/#exemple-4-phenomene-de-repliement-de-frequence-au-dela-de-sr2","text":"Un probl\u00e8me bien connu dans le domaine de la synth\u00e8se num\u00e9rique du son est celui du repliement de fr\u00e9quence : toute fr\u00e9quence au dela de la moiti\u00e9 de la fr\u00e9quence d'\u00e9chatillonnage se retrouve repli\u00e9e dans le spectre audible :","title":"Exemple 4 : Ph\u00e9nom\u00e8ne de repliement de fr\u00e9quence au-del\u00e0 de SR/2"},{"location":"workshops/2020-03-24-faust-citi/#exemple-5-synthese-additive","text":"Un exemple de synth\u00e8se additive ou le niveau de chaque partiel peut \u00eatre r\u00e9gl\u00e9 individuellement : A noter l'utilisation de la construction sum(i, n, foo(i)) qui est equivalente \u00e0 foo(0)+foo(1)+...+foo(n-1) .","title":"Exemple 5 : Synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-6-approximation-dun-signal-carre-par-synthese-additive","text":"Nous avons vu pr\u00e9c\u00e9demment comment produire une signal carr\u00e9 parfait. Ce signal carr\u00e9 parfait comporte une infinit\u00e9 d'harmoniques qui, du fait de l'\u00e9chantillonnage, vont se replier sur le spectre audible, ce qui va donner un son bruit\u00e9 moins fid\u00e8le ! On peut approximer un signal carr\u00e9 par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques impaires (voir https://fr.wikipedia.org/wiki/Signal_carr\u00e9 ) : A titre d'excercice, faire varier le nombre d'harmoniques pour voir l'approximation s'am\u00e9liorer (mais sans d\u00e9passer SR/2).","title":"Exemple 6 : Approximation d'un signal carr\u00e9 par synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-7-approximation-dun-signal-en-dent-de-scie-par-synthese-additive","text":"De m\u00eame on peut approximer un signal en dent de scie par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques (voir https://fr.wikipedia.org/wiki/Signal_en_dents_de_scie ) :","title":"Exemple 7 : Approximation d'un signal en dent de scie par synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#synthese-soustractive","text":"La synth\u00e8se soustractive proc\u00e8de \u00e0 l'inverse de la synth\u00e8se additive. Elle consiste \u00e0 partir d'un son riche, par exemple un bruit blanc, et \u00e0 sculpter son spectre.","title":"Synth\u00e8se soustractive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-un-bruit-blanc","text":"Un bruit blanc :","title":"Exemple 1 : un bruit blanc"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-lowpass","text":"","title":"Exemple 2 : lowpass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-3-high-pass","text":"","title":"Exemple 3 : high pass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-4-bandpass","text":"","title":"Exemple 4 : bandpass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-5-resonnant","text":"","title":"Exemple 5 : resonnant"},{"location":"workshops/2020-03-24-faust-citi/#exemple-6-fir","text":"","title":"Exemple 6 : fir"},{"location":"workshops/2020-03-24-faust-citi/#exemple-7-iir","text":"","title":"Exemple 7 : iir"},{"location":"workshops/2020-03-24-faust-citi/#exemple-8-filtre-en-peigne","text":"","title":"Exemple 8 : filtre en peigne"},{"location":"workshops/2020-03-24-faust-citi/#exemple-9-karplus-strong-12","text":"","title":"Exemple 9 : Karplus Strong (1/2)"},{"location":"workshops/2020-03-24-faust-citi/#exemple-10-karplus-strong-22","text":"","title":"Exemple 10 : Karplus Strong (2/2)"},{"location":"workshops/2020-03-24-faust-citi/#exemple-11-kisana","text":"","title":"Exemple 11 : Kisana"},{"location":"workshops/2020-03-24-faust-citi/#synthese-par-modulation-de-frequence","text":"","title":"Synth\u00e8se par modulation de fr\u00e9quence"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-fm1","text":"","title":"Exemple 1 : fm1"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-fm2","text":"","title":"Exemple 2 : fm2"},{"location":"workshops/2020-04-10-faust-101/","text":"Faust 101 for the confined The covid-19 containment gives us at least one excellent opportunity to train! If you've always wanted to get into Faust programming but didn't have the time, here's your chance! The objective of this workshop is to help you get familiar with the Faust language through very simple examples of signal processing and sound synthesis. The documentation and the examples we will use can be found here: https://faustdoc.grame.fr/workshops/2020-04-10-faust-101/ All examples will be run in the online Faust IDE: https://faustide.grame.fr If ever the sounds produced with the IDE are of poor quality, with some clicks, one can use the online editor, which is more rustic, but also lighter: https://fausteditor.grame.fr Faust in a few words Faust is a Domain-Specific Language for real-time signal processing and synthesis (like Csound, Max/MSP, SuperCollider, PureData,. . . ). Faust is based on purely functional approach. a Faust program denotes a signal processor: a function that maps input signals to output signals. Programming in Faust is essentially combining signal processors using an algebra of 5 composition operations: <: :> : , ~ . Faust is a compiled language, the role of the Faust compiler is to synthesize the most efficient implementations. Faust offers end-users a high-level alternative to C/C++ to develop audio applications for a large variety of platforms. Part 1: Very simple examples Let's start with some simple examples of Faust programs. Example 1: The simplest Faust program This is the simplest Faust program imaginable. It contains only one line of code, the definition: process = _; . This program copies the audio input to the audio output. Let's try this program using the online Faust IDE: Several lessons can be learned from this very simple example: a Faust program has at least one definition, that of the keyword process which indicates the entry point of the program. a definition always ends with a ; . A common mistake is to forget the semicolon at the end of a definition. the _ sign represents one of the primitives of the language (primitives are the predefined functions of the language). It represents an audio cable that lets the signal pass through without transforming it. This is what one calls in mathematics the identity function, the signal that enters on the left comes out on the right identically. Example 2: Adding two signals We saw in the previous example the primitive _ . Faust has a large number of primitives, including all mathematical operations . The + primitive for instance is used to add two signals. It can therefore be used to transform a stereophonic signal (on two channels) into a monophonic signal as in the following example: Example 3: Multiplying two signals The * primitive for instance is used to multiply two signals: As you can hear, multiplying the two channels of a signal between them transforms the sound quite drastically. Example 4: Parallel composition Programming in Faust consists in assembling primitive operations to form more or less complex audio circuits. To realize these assemblies, Faust has 5 composition operations: ~ , , , ; , <: , :> . Let's first look at the parallel composition represented by the comma , : We made a stereo cable and when we play the audio file, we now hear it on both speakers. It is very important to distinguish between primitives , such as _ , + or * , and composition operations such as , or : . Primitives represent operations on audio signals, whereas composition operations are used to link two audio operations together. In other words, you can write + or * alone, because they represent valid audio operations, but you can never write , or : alone because they are used to connect two audio operations. You must always write A,B or A:B . The primitives of Faust are organized in several categories. We find all the numerical functions of the C language, but applied to audio signals: Category Primitives Arithmetic + , - , * , / , ... Comparison < , == , != , <= , ... Trigonometric sin , cos , ... Log and Co. log , exp , ... Min, Max min , max , ... Selectors select2 , select3 , ... Delays and Tables @ , rdtable , ... GUI hslider() , button() , ... Here is a summary table of the five composition operators: Syntax Priority Association Description A ~ B 4 left Recursive Composition A , B 3 right Parallel Composition A : B 2 right Sequential Composition A <: B 1 right Split Composition A :> B 1 right Merge Composition Example 5: Controlling the volume Let's see an example where we combine three primitives: _ , 0.1 and * , with two composition operators: , and : . The idea here is to lower the volume of the incoming signal to one tenth of its initial value. This is done by multiplying the incoming signal by 0.1 : Note that we have used parentheses in this example to clearly mark the order in which things should be done. We start by putting _ and 0.1 in parallel, and then compose them in sequence with * . But, just as in (2*3)+7 were the parentheses are not really necessary because multiplication takes precedence over addition, one could write directly process = _,0.1 : *; without the parentheses, because parallel composing takes precedence over sequential composing. The priority of the composition operators is shown in the previous table. Example 6: Controlling the volume with a slider Instead of controlling the volume by editing the code, it is far more convenient to use a graphical slider. For that purpose we can use a hslider(...) , a horizontal slider. It takes five parameters. The first one is the name \"volume\" , then we have the defaut value 0.1 , the minimun value 0 , the maximum value 1 and a step value 0.1 . So here the default value is 0.1 : Example 7: Mono Amplifier We have written very simple programs so far, that fit into one line of code. We will now introduce additional definitions. A definition should be understood as a way of giving a name to something, which saves us from typing the definition every time and makes the program easier to understand: Example 8: Stereo Amplifier Continuing in the same vein, we will define a stereo amplifier as two mono amplifiers in parallel: Note that even if the hslider volume appears several times in our code, there will only be one in the user interface: Example 9: Vertical sliders Instead of horizontal sliders, we could use vertical sliders. Just replace hslider(...) with vslider(...) : Example 10: Knobs instead of sliders By default sliders are ... sliders! You can change their appearance by using the metadata mechanism. Metadata is information that you put in square brackets in the slider name. For example the metadata \"...[style:knob]...\" allows you to turn the slider into a rotary knob: Example 11: Syntactic sugar We have used the core syntax of Faust so far. For example to multiply the incoming signal by 0.1 , we wrote _,0.1:* . For numerical expressions this notation is not always the most convenient and sometimes we would prefer to use the more traditional infix notation and write instead _*0.1 . We can also use the prefixed notation and write *(0.1) . Let's rewrite the definition of the monoamp using the prefix notation: Here is a table of equivalent notations, with the same expression in all three syntaxes. Keep in mind that infix and prefix expressions are translated to core syntax: Expression Description _,0.1:* core syntax _*0.1 infix notation *(0.1) prefix notation These notations can be freely combined. For example, the following expressions are all equivalent: Expression Description *(1-m) prefix + infix notation _*(1-m) only infix notation _,(1,m:-):* core syntax Example 12: A mute button We would like to be able to mute the sound completely at the touch of a button, without having to change the volume. Let's add a mute stage to our mono amplifier. In order to mute the signal we just have to mutiply it by 0. We will use for that purpose a checkbox(...) , a user interface element that produces a signal which is 0 by default and 1 when it is checked. As we want to multiply the signal by 0 when the checkbox is checked we will use 1-checkbox(\"mute\") : Example 13: Vertical and horizontal Layout As can be seen in the previous example, by default, the layout of the elements is vertical. You can change this layout by using hgroup(...) and vgroup(...) . For example to make the layout horizontal you can write: s Example 14: Differentiate the volume of the two channels To differentiate the volume control of our two channels, we will parametrize monoamp with a channel number c which will be used to differentiate the name of each volume control. Note that the name c of the parameter must only have one letter to be well interpreted in the slider name \"volume %c[style:knob]\" : Example 15: Having many channels We have built a stereo amp, but suppose we wanted to generalize this construction to an arbitrary number of channels. To do so, we will introduce the par(i, N, ...) construction which allows us to put several times an expression in parallel. It is in a way the equivalent of the for() loop of a classical programming language. In our case we want to indicate the number of channels of our amplifier: Part 2: Delays and Feedbacks In this new section we will see two important notions, that of delay with the @ primitive, and that of feedback (from a looped circuit) which will require the use of the recursive composition A~B which allows to loop the outputs of A into the inputs of B, and the outputs of B into the inputs of A. Example 1: Monophonic delay of 1 second Let's start with a very simple example, a monophonic delay of 1 seconds or 44100 samples. We will use the prefix notation: Example 2: Delay of 0.1 second on the right channel To hear the delay better, let's put it only on the right channel and leave the left channel unchanged: Example 3: the bouncing of sound on a wall By combining a delay and an attenuation we can simulate the bouncing of sound on a wall: Example 4: A simple monophonic echo To simulate an echo, all we need to do is create a feedback loop. We'll use the recursive composition A~B : Example 5: A stereophonic echo Let's make a stereophonic echo with two monophonic echos in parallel: Example 6: Adding parameters We will now generalize our echo with parameters to control its duration and feedback level: Example 7: Slider for the feedback control We can now add a slider to control the level of feedback: Example 8: Freeze effect We would now like to prevent the sound level from rising indefinitely when we set the feedback level to 1. The idea is to gradually shut down the input when the feedback level exceeds a certain threshold: Part 3: Basic Oscillators By convention, in Faust, a full-scale audio signal varies between -1 and +1, but we will first start with a sawtooth signal between 0 and 1 which will then be used as a phase generator to produce different waveforms. Phase Generator The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate : Example 1: Ramp To do this we will produce an \"infinite\" ramp, which we will then transform into a periodic signal thanks to a part-decimal operation: The ramp is produced by the following program: Semantics To understand the above diagram, we will annotate it with its mathematical semantics: As can be seen in the diagram, the formula for the output signal is: y(t) = y(t-1) + 0.125 We can calculate the first values of y(t) : y(t<0)=0 . y(0) = y(-1) + 0.125 = 0.125 . y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1,000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Example 2: a phase signal How do I turn the above ramp into a sawtooth signal? By deleting the whole part of the samples in order to keep only the decimal part: 3.14159\\rightarrow 0.14159 . Let's define a function to do this: decimalpart(x) = x - int(x); We can now use this function to turn our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view, that would be perfectly correct, but we will accumulate rounding errors. To keep total accuracy, it is better to place the operation of the decimal part inside the loop, like this: process = 0.125 : (+ : decimalpart) ~ _; We can now try the whole code ( think about turning down the volume ) : In our definition of phase , the value of the step, here 0.125 , controls the frequency of the generated signal. We would like to calculate this step value as a function of the desired frequency. In order to do the conversion, we need to know the sampling frequency. It is available in the standard library as ma.SR and will be setup at start time by the underlying audio layer. To use this standard library we add the following line to the program: import(\"stdfaust.lib\"); . Suppose we want our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR , so that it takes ma.SR samples (i.e. 1 second) for the phase signal to go from 0 to 1. If we want a frequency of 440 Hz, we need a 440 times larger step so that the phase signal goes from 0 to 1, 440 times faster: phase = 440/ma.SR : (+ : decimalpart) ~ _; This definition can be generalized by replacing 440 with an f parameter: phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and changing the desired frequency to phase : process = phase(440); Example 3: Sawtooth signal generator We can now use the phase generator to produce a sawtooth signal: Example 4: Square wave generator We can also use the phase generator to produce a square wave signal: Part 4: Additive synthesis Example 1: sine wave generator The phase generator is also the basis of the sine wave generator: But now that we have seen how to create a sinusoidal oscillator from scratch, we will use the one defined in the standard Faust libraries: Example 2: a sine wave with volume control In this second example we used a horizontal slider hslider(...) to control the sound level: The first parameter is a string that indicates the name of the slider. It is followed by four numeric parameters. The second parameter 0.1 indicates the default value of the slider, i.e. the value that the slider will deliver when the program is started. Then we have the minimum value 0 , the maximum value 1 and the variation step 0.01 . Example 3: Exercise, add a frequency control As an exercise, replace, in the previous example, the frequency 440 by a horizontal slider whose name will be freq , the default value 110 , the minimum value 40 , the maximum value 8000 and the step 1 : Example 4: Frequency aliasing phenomenon beyond SR/2 A well known problem in the field of digital sound synthesis is frequency aliasing : any frequency beyond half the sampling frequency is folded in the audible spectrum: Example 5: Additive synthesis An example of an additive synthesis, where the level of each partial can be set individually: Note the use of the sum(i, n, foo(i)) construction which is equivalent to foo(0)+foo(1)+...+foo(n-1) . Example 6: Approximation of a square signal by additive synthesis We saw earlier how to produce a perfect square wave signal. This perfect square signal contains an infinite number of harmonics which, due to sampling, will fold over the audible spectrum, resulting in a less accurate, noisy sound! A square signal can be approximated by additive synthesis, by adding an infinite series of odd harmonics (see https://en.wikipedia.org/wiki/Square_wave ): As an exercise, change the number of harmonics to see the approximation improve (but do not exceed SR/2). Example 7: Approximation of a sawtooth signal by additive synthesis Similarly, a sawtooth signal can be approximated by additive synthesis, by adding an infinite series of harmonics (see https://en.wikipedia.org/wiki/Sawtooth_wave ): Example 8: Band limited oscillators The problem of aliasing can be solved using band-limited oscillators available in Faust libraries: Part 5: Subtractive synthesis Subtractive synthesis is the opposite of additive synthesis. It consists in starting from a rich sound, for example white noise, and sculpting its spectrum. Example 1: a white noise A white noise generator: Example 2: lowpass Here the noise sound is filtered with a low-pass filter that removes frequencies lower than a selected cutoff frequency: The used fi.low filter can be defined with an argument that modifies the frequency attenuation slope. Example 3: high pass Here the noise sound is filtered with a high-pass filter that removes frequencies higher than a selected cutoff frequency: The used fi.highpass filter can be defined with an argument that modifies the frequency attenuation slope. Example 4: bandpass By combining a low-pass and high-pass filter in sequence, a bandpass filter that removes frequencies lower than a selected low cutoff frequency, and higher than a selected high cutoff frequency, can be defined (using the already described fi.lowpass and fi.highpass filters): Example 5: resonant A resonant filter amplifies a selected frequency range: The used fi.resonlp filter has an argument to select the desired frequency, a Q factor to shape the frequency range, and a gain factor. Example 6: fir Here a FIR filter is used: Example 7: iir Here a IIR filter is used: Example 8: comb filter A comb filter attenuates a set of consecutives frequency bands: Example 9: Karplus Strong (1/2) Example 10: Karplus Strong (2/2) Example 11: Kisana Part 6: Synthesis by frequency modulation Example 1: frequency modulation Example 2: frequency modulation with envelops Further readings The documentation of Faust libraries is available here: https://faustlibraries.grame.fr/","title":" 2020-04-10 Faust 101 "},{"location":"workshops/2020-04-10-faust-101/#faust-101-for-the-confined","text":"The covid-19 containment gives us at least one excellent opportunity to train! If you've always wanted to get into Faust programming but didn't have the time, here's your chance! The objective of this workshop is to help you get familiar with the Faust language through very simple examples of signal processing and sound synthesis. The documentation and the examples we will use can be found here: https://faustdoc.grame.fr/workshops/2020-04-10-faust-101/ All examples will be run in the online Faust IDE: https://faustide.grame.fr If ever the sounds produced with the IDE are of poor quality, with some clicks, one can use the online editor, which is more rustic, but also lighter: https://fausteditor.grame.fr","title":"Faust 101 for the confined"},{"location":"workshops/2020-04-10-faust-101/#faust-in-a-few-words","text":"Faust is a Domain-Specific Language for real-time signal processing and synthesis (like Csound, Max/MSP, SuperCollider, PureData,. . . ). Faust is based on purely functional approach. a Faust program denotes a signal processor: a function that maps input signals to output signals. Programming in Faust is essentially combining signal processors using an algebra of 5 composition operations: <: :> : , ~ . Faust is a compiled language, the role of the Faust compiler is to synthesize the most efficient implementations. Faust offers end-users a high-level alternative to C/C++ to develop audio applications for a large variety of platforms.","title":"Faust in a few words"},{"location":"workshops/2020-04-10-faust-101/#part-1-very-simple-examples","text":"Let's start with some simple examples of Faust programs.","title":"Part 1: Very simple examples"},{"location":"workshops/2020-04-10-faust-101/#example-1-the-simplest-faust-program","text":"This is the simplest Faust program imaginable. It contains only one line of code, the definition: process = _; . This program copies the audio input to the audio output. Let's try this program using the online Faust IDE: Several lessons can be learned from this very simple example: a Faust program has at least one definition, that of the keyword process which indicates the entry point of the program. a definition always ends with a ; . A common mistake is to forget the semicolon at the end of a definition. the _ sign represents one of the primitives of the language (primitives are the predefined functions of the language). It represents an audio cable that lets the signal pass through without transforming it. This is what one calls in mathematics the identity function, the signal that enters on the left comes out on the right identically.","title":"Example 1: The simplest Faust program"},{"location":"workshops/2020-04-10-faust-101/#example-2-adding-two-signals","text":"We saw in the previous example the primitive _ . Faust has a large number of primitives, including all mathematical operations . The + primitive for instance is used to add two signals. It can therefore be used to transform a stereophonic signal (on two channels) into a monophonic signal as in the following example:","title":"Example 2: Adding two signals"},{"location":"workshops/2020-04-10-faust-101/#example-3-multiplying-two-signals","text":"The * primitive for instance is used to multiply two signals: As you can hear, multiplying the two channels of a signal between them transforms the sound quite drastically.","title":"Example 3: Multiplying two signals"},{"location":"workshops/2020-04-10-faust-101/#example-4-parallel-composition","text":"Programming in Faust consists in assembling primitive operations to form more or less complex audio circuits. To realize these assemblies, Faust has 5 composition operations: ~ , , , ; , <: , :> . Let's first look at the parallel composition represented by the comma , : We made a stereo cable and when we play the audio file, we now hear it on both speakers. It is very important to distinguish between primitives , such as _ , + or * , and composition operations such as , or : . Primitives represent operations on audio signals, whereas composition operations are used to link two audio operations together. In other words, you can write + or * alone, because they represent valid audio operations, but you can never write , or : alone because they are used to connect two audio operations. You must always write A,B or A:B . The primitives of Faust are organized in several categories. We find all the numerical functions of the C language, but applied to audio signals: Category Primitives Arithmetic + , - , * , / , ... Comparison < , == , != , <= , ... Trigonometric sin , cos , ... Log and Co. log , exp , ... Min, Max min , max , ... Selectors select2 , select3 , ... Delays and Tables @ , rdtable , ... GUI hslider() , button() , ... Here is a summary table of the five composition operators: Syntax Priority Association Description A ~ B 4 left Recursive Composition A , B 3 right Parallel Composition A : B 2 right Sequential Composition A <: B 1 right Split Composition A :> B 1 right Merge Composition","title":"Example 4: Parallel composition"},{"location":"workshops/2020-04-10-faust-101/#example-5-controlling-the-volume","text":"Let's see an example where we combine three primitives: _ , 0.1 and * , with two composition operators: , and : . The idea here is to lower the volume of the incoming signal to one tenth of its initial value. This is done by multiplying the incoming signal by 0.1 : Note that we have used parentheses in this example to clearly mark the order in which things should be done. We start by putting _ and 0.1 in parallel, and then compose them in sequence with * . But, just as in (2*3)+7 were the parentheses are not really necessary because multiplication takes precedence over addition, one could write directly process = _,0.1 : *; without the parentheses, because parallel composing takes precedence over sequential composing. The priority of the composition operators is shown in the previous table.","title":"Example 5: Controlling the volume"},{"location":"workshops/2020-04-10-faust-101/#example-6-controlling-the-volume-with-a-slider","text":"Instead of controlling the volume by editing the code, it is far more convenient to use a graphical slider. For that purpose we can use a hslider(...) , a horizontal slider. It takes five parameters. The first one is the name \"volume\" , then we have the defaut value 0.1 , the minimun value 0 , the maximum value 1 and a step value 0.1 . So here the default value is 0.1 :","title":"Example 6: Controlling the volume with a slider"},{"location":"workshops/2020-04-10-faust-101/#example-7-mono-amplifier","text":"We have written very simple programs so far, that fit into one line of code. We will now introduce additional definitions. A definition should be understood as a way of giving a name to something, which saves us from typing the definition every time and makes the program easier to understand:","title":"Example 7: Mono Amplifier"},{"location":"workshops/2020-04-10-faust-101/#example-8-stereo-amplifier","text":"Continuing in the same vein, we will define a stereo amplifier as two mono amplifiers in parallel: Note that even if the hslider volume appears several times in our code, there will only be one in the user interface:","title":"Example 8: Stereo Amplifier"},{"location":"workshops/2020-04-10-faust-101/#example-9-vertical-sliders","text":"Instead of horizontal sliders, we could use vertical sliders. Just replace hslider(...) with vslider(...) :","title":"Example 9: Vertical sliders"},{"location":"workshops/2020-04-10-faust-101/#example-10-knobs-instead-of-sliders","text":"By default sliders are ... sliders! You can change their appearance by using the metadata mechanism. Metadata is information that you put in square brackets in the slider name. For example the metadata \"...[style:knob]...\" allows you to turn the slider into a rotary knob:","title":"Example 10: Knobs instead of sliders"},{"location":"workshops/2020-04-10-faust-101/#example-11-syntactic-sugar","text":"We have used the core syntax of Faust so far. For example to multiply the incoming signal by 0.1 , we wrote _,0.1:* . For numerical expressions this notation is not always the most convenient and sometimes we would prefer to use the more traditional infix notation and write instead _*0.1 . We can also use the prefixed notation and write *(0.1) . Let's rewrite the definition of the monoamp using the prefix notation: Here is a table of equivalent notations, with the same expression in all three syntaxes. Keep in mind that infix and prefix expressions are translated to core syntax: Expression Description _,0.1:* core syntax _*0.1 infix notation *(0.1) prefix notation These notations can be freely combined. For example, the following expressions are all equivalent: Expression Description *(1-m) prefix + infix notation _*(1-m) only infix notation _,(1,m:-):* core syntax","title":"Example 11: Syntactic sugar"},{"location":"workshops/2020-04-10-faust-101/#example-12-a-mute-button","text":"We would like to be able to mute the sound completely at the touch of a button, without having to change the volume. Let's add a mute stage to our mono amplifier. In order to mute the signal we just have to mutiply it by 0. We will use for that purpose a checkbox(...) , a user interface element that produces a signal which is 0 by default and 1 when it is checked. As we want to multiply the signal by 0 when the checkbox is checked we will use 1-checkbox(\"mute\") :","title":"Example 12: A mute button"},{"location":"workshops/2020-04-10-faust-101/#example-13-vertical-and-horizontal-layout","text":"As can be seen in the previous example, by default, the layout of the elements is vertical. You can change this layout by using hgroup(...) and vgroup(...) . For example to make the layout horizontal you can write: s","title":"Example 13: Vertical and horizontal Layout"},{"location":"workshops/2020-04-10-faust-101/#example-14-differentiate-the-volume-of-the-two-channels","text":"To differentiate the volume control of our two channels, we will parametrize monoamp with a channel number c which will be used to differentiate the name of each volume control. Note that the name c of the parameter must only have one letter to be well interpreted in the slider name \"volume %c[style:knob]\" :","title":"Example 14: Differentiate the volume of the two channels"},{"location":"workshops/2020-04-10-faust-101/#example-15-having-many-channels","text":"We have built a stereo amp, but suppose we wanted to generalize this construction to an arbitrary number of channels. To do so, we will introduce the par(i, N, ...) construction which allows us to put several times an expression in parallel. It is in a way the equivalent of the for() loop of a classical programming language. In our case we want to indicate the number of channels of our amplifier:","title":"Example 15: Having many channels"},{"location":"workshops/2020-04-10-faust-101/#part-2-delays-and-feedbacks","text":"In this new section we will see two important notions, that of delay with the @ primitive, and that of feedback (from a looped circuit) which will require the use of the recursive composition A~B which allows to loop the outputs of A into the inputs of B, and the outputs of B into the inputs of A.","title":"Part 2: Delays and Feedbacks"},{"location":"workshops/2020-04-10-faust-101/#example-1-monophonic-delay-of-1-second","text":"Let's start with a very simple example, a monophonic delay of 1 seconds or 44100 samples. We will use the prefix notation:","title":"Example 1: Monophonic delay of 1 second"},{"location":"workshops/2020-04-10-faust-101/#example-2-delay-of-01-second-on-the-right-channel","text":"To hear the delay better, let's put it only on the right channel and leave the left channel unchanged:","title":"Example 2: Delay of 0.1 second on the right channel"},{"location":"workshops/2020-04-10-faust-101/#example-3-the-bouncing-of-sound-on-a-wall","text":"By combining a delay and an attenuation we can simulate the bouncing of sound on a wall:","title":"Example 3: the bouncing of sound on a wall"},{"location":"workshops/2020-04-10-faust-101/#example-4-a-simple-monophonic-echo","text":"To simulate an echo, all we need to do is create a feedback loop. We'll use the recursive composition A~B :","title":"Example 4: A simple monophonic echo"},{"location":"workshops/2020-04-10-faust-101/#example-5-a-stereophonic-echo","text":"Let's make a stereophonic echo with two monophonic echos in parallel:","title":"Example 5: A stereophonic echo"},{"location":"workshops/2020-04-10-faust-101/#example-6-adding-parameters","text":"We will now generalize our echo with parameters to control its duration and feedback level:","title":"Example 6: Adding parameters"},{"location":"workshops/2020-04-10-faust-101/#example-7-slider-for-the-feedback-control","text":"We can now add a slider to control the level of feedback:","title":"Example 7: Slider for the feedback control"},{"location":"workshops/2020-04-10-faust-101/#example-8-freeze-effect","text":"We would now like to prevent the sound level from rising indefinitely when we set the feedback level to 1. The idea is to gradually shut down the input when the feedback level exceeds a certain threshold:","title":"Example 8: Freeze effect"},{"location":"workshops/2020-04-10-faust-101/#part-3-basic-oscillators","text":"By convention, in Faust, a full-scale audio signal varies between -1 and +1, but we will first start with a sawtooth signal between 0 and 1 which will then be used as a phase generator to produce different waveforms.","title":"Part 3: Basic Oscillators"},{"location":"workshops/2020-04-10-faust-101/#phase-generator","text":"The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate :","title":"Phase Generator"},{"location":"workshops/2020-04-10-faust-101/#example-1-ramp","text":"To do this we will produce an \"infinite\" ramp, which we will then transform into a periodic signal thanks to a part-decimal operation: The ramp is produced by the following program:","title":"Example 1: Ramp"},{"location":"workshops/2020-04-10-faust-101/#semantics","text":"To understand the above diagram, we will annotate it with its mathematical semantics: As can be seen in the diagram, the formula for the output signal is: y(t) = y(t-1) + 0.125 We can calculate the first values of y(t) : y(t<0)=0 . y(0) = y(-1) + 0.125 = 0.125 . y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1,000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"Semantics"},{"location":"workshops/2020-04-10-faust-101/#example-2-a-phase-signal","text":"How do I turn the above ramp into a sawtooth signal? By deleting the whole part of the samples in order to keep only the decimal part: 3.14159\\rightarrow 0.14159 . Let's define a function to do this: decimalpart(x) = x - int(x); We can now use this function to turn our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view, that would be perfectly correct, but we will accumulate rounding errors. To keep total accuracy, it is better to place the operation of the decimal part inside the loop, like this: process = 0.125 : (+ : decimalpart) ~ _; We can now try the whole code ( think about turning down the volume ) : In our definition of phase , the value of the step, here 0.125 , controls the frequency of the generated signal. We would like to calculate this step value as a function of the desired frequency. In order to do the conversion, we need to know the sampling frequency. It is available in the standard library as ma.SR and will be setup at start time by the underlying audio layer. To use this standard library we add the following line to the program: import(\"stdfaust.lib\"); . Suppose we want our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR , so that it takes ma.SR samples (i.e. 1 second) for the phase signal to go from 0 to 1. If we want a frequency of 440 Hz, we need a 440 times larger step so that the phase signal goes from 0 to 1, 440 times faster: phase = 440/ma.SR : (+ : decimalpart) ~ _; This definition can be generalized by replacing 440 with an f parameter: phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and changing the desired frequency to phase : process = phase(440);","title":"Example 2: a phase signal"},{"location":"workshops/2020-04-10-faust-101/#example-3-sawtooth-signal-generator","text":"We can now use the phase generator to produce a sawtooth signal:","title":"Example 3: Sawtooth signal generator"},{"location":"workshops/2020-04-10-faust-101/#example-4-square-wave-generator","text":"We can also use the phase generator to produce a square wave signal:","title":"Example 4: Square wave generator"},{"location":"workshops/2020-04-10-faust-101/#part-4-additive-synthesis","text":"","title":"Part 4: Additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-1-sine-wave-generator","text":"The phase generator is also the basis of the sine wave generator: But now that we have seen how to create a sinusoidal oscillator from scratch, we will use the one defined in the standard Faust libraries:","title":"Example 1: sine wave generator"},{"location":"workshops/2020-04-10-faust-101/#example-2-a-sine-wave-with-volume-control","text":"In this second example we used a horizontal slider hslider(...) to control the sound level: The first parameter is a string that indicates the name of the slider. It is followed by four numeric parameters. The second parameter 0.1 indicates the default value of the slider, i.e. the value that the slider will deliver when the program is started. Then we have the minimum value 0 , the maximum value 1 and the variation step 0.01 .","title":"Example 2: a sine wave with volume control"},{"location":"workshops/2020-04-10-faust-101/#example-3-exercise-add-a-frequency-control","text":"As an exercise, replace, in the previous example, the frequency 440 by a horizontal slider whose name will be freq , the default value 110 , the minimum value 40 , the maximum value 8000 and the step 1 :","title":"Example 3: Exercise, add a frequency control"},{"location":"workshops/2020-04-10-faust-101/#example-4-frequency-aliasing-phenomenon-beyond-sr2","text":"A well known problem in the field of digital sound synthesis is frequency aliasing : any frequency beyond half the sampling frequency is folded in the audible spectrum:","title":"Example 4: Frequency aliasing phenomenon beyond SR/2"},{"location":"workshops/2020-04-10-faust-101/#example-5-additive-synthesis","text":"An example of an additive synthesis, where the level of each partial can be set individually: Note the use of the sum(i, n, foo(i)) construction which is equivalent to foo(0)+foo(1)+...+foo(n-1) .","title":"Example 5: Additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-6-approximation-of-a-square-signal-by-additive-synthesis","text":"We saw earlier how to produce a perfect square wave signal. This perfect square signal contains an infinite number of harmonics which, due to sampling, will fold over the audible spectrum, resulting in a less accurate, noisy sound! A square signal can be approximated by additive synthesis, by adding an infinite series of odd harmonics (see https://en.wikipedia.org/wiki/Square_wave ): As an exercise, change the number of harmonics to see the approximation improve (but do not exceed SR/2).","title":"Example 6: Approximation of a square signal by additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-7-approximation-of-a-sawtooth-signal-by-additive-synthesis","text":"Similarly, a sawtooth signal can be approximated by additive synthesis, by adding an infinite series of harmonics (see https://en.wikipedia.org/wiki/Sawtooth_wave ):","title":"Example 7: Approximation of a sawtooth signal by additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-8-band-limited-oscillators","text":"The problem of aliasing can be solved using band-limited oscillators available in Faust libraries:","title":"Example 8: Band limited oscillators"},{"location":"workshops/2020-04-10-faust-101/#part-5-subtractive-synthesis","text":"Subtractive synthesis is the opposite of additive synthesis. It consists in starting from a rich sound, for example white noise, and sculpting its spectrum.","title":"Part 5: Subtractive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-1-a-white-noise","text":"A white noise generator:","title":"Example 1: a white noise"},{"location":"workshops/2020-04-10-faust-101/#example-2-lowpass","text":"Here the noise sound is filtered with a low-pass filter that removes frequencies lower than a selected cutoff frequency: The used fi.low filter can be defined with an argument that modifies the frequency attenuation slope.","title":"Example 2: lowpass"},{"location":"workshops/2020-04-10-faust-101/#example-3-high-pass","text":"Here the noise sound is filtered with a high-pass filter that removes frequencies higher than a selected cutoff frequency: The used fi.highpass filter can be defined with an argument that modifies the frequency attenuation slope.","title":"Example 3: high pass"},{"location":"workshops/2020-04-10-faust-101/#example-4-bandpass","text":"By combining a low-pass and high-pass filter in sequence, a bandpass filter that removes frequencies lower than a selected low cutoff frequency, and higher than a selected high cutoff frequency, can be defined (using the already described fi.lowpass and fi.highpass filters):","title":"Example 4: bandpass"},{"location":"workshops/2020-04-10-faust-101/#example-5-resonant","text":"A resonant filter amplifies a selected frequency range: The used fi.resonlp filter has an argument to select the desired frequency, a Q factor to shape the frequency range, and a gain factor.","title":"Example 5: resonant"},{"location":"workshops/2020-04-10-faust-101/#example-6-fir","text":"Here a FIR filter is used:","title":"Example 6: fir"},{"location":"workshops/2020-04-10-faust-101/#example-7-iir","text":"Here a IIR filter is used:","title":"Example 7: iir"},{"location":"workshops/2020-04-10-faust-101/#example-8-comb-filter","text":"A comb filter attenuates a set of consecutives frequency bands:","title":"Example 8: comb filter"},{"location":"workshops/2020-04-10-faust-101/#example-9-karplus-strong-12","text":"","title":"Example 9: Karplus Strong (1/2)"},{"location":"workshops/2020-04-10-faust-101/#example-10-karplus-strong-22","text":"","title":"Example 10: Karplus Strong (2/2)"},{"location":"workshops/2020-04-10-faust-101/#example-11-kisana","text":"","title":"Example 11: Kisana"},{"location":"workshops/2020-04-10-faust-101/#part-6-synthesis-by-frequency-modulation","text":"","title":"Part 6: Synthesis by frequency modulation"},{"location":"workshops/2020-04-10-faust-101/#example-1-frequency-modulation","text":"","title":"Example 1: frequency modulation"},{"location":"workshops/2020-04-10-faust-101/#example-2-frequency-modulation-with-envelops","text":"","title":"Example 2: frequency modulation with envelops"},{"location":"workshops/2020-04-10-faust-101/#further-readings","text":"The documentation of Faust libraries is available here: https://faustlibraries.grame.fr/","title":"Further readings"},{"location":"workshops/2020-04-10-faust-juce/","text":"Faust For the Confined: Adding Faust DSP Support to Your JUCE Plug-ins JUCE is a well-known framework for creating audio plug-ins (i.e., VST, AU, AAX, etc.) and applications for a wide range of platforms. Faust can be used to generate ready-to-use JUCE applications and plug-ins implementing the standard user interface (UI) described in the Faust code using faust2juce . However, it is sooo easy to make professional looking UIs from scratch in JUCE that you might want to use Faust to implement the DSP portion of your plug-in and build your own UI. In this tutorial, we demonstrate how to use the Faust compiler to generate a C++ DSP object and how to interface it with your JUCE plug-in/UI. We'll cover basic examples (monophonic synth, polyphonic synth, and audio effect) as well as more advanced applications involving polyphony, etc. Simple Monophonic Synth Plug-In << Download the source of this tutorial >> In this section, we demonstrate how to use a Faust synth to build a plug-in in JUCE with a custom UI from scratch. Generating the DSP Engine First, let's implement a basic subtractive synthesizer in Faust based on a filtered sawtooth wave ( FaustSynth.dsp ): Feel free to run it in the web IDE to see how it sounds! The output of the lowpass is split into 2 signals to create a stereo object. Note that all the parameters are smoothed to prevent clicking (we want our plug-in to be clean!). Even gate is smoothed, which will apply a gentle exponential envelope when the trigger signal is sent, etc. Since Faust will not build its own UI here, the type of UI element used in this code doesn't really matter. They just serve as a point of entry to control the parameters of the audio engine we're about to generate. So nentry could be replaced by hslider or vslider , it would not make any difference. However, we encourage you to always write \"coherent\" interfaces in case someone would like to use your Faust code \"as such\" at some point. In order to turn this Faust program into a C++ DSP object usable in JUCE, we must use a Faust architecture file that will wrap the C++ code generated by the Faust compiler (that literally just contains an audio callback function). That's what faustMinimal.h (which is part of the package that you downloaded at the beginning of this tutorial) does. Actually, if you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/gui/MapUI.h\" #include \"faust/gui/meta.h\" #include \"faust/dsp/dsp.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP The faust/... files should be on your system if Faust is installed on it. If not, you can use the inlined version of the architecture file ( faustMinimalInlined.h ) which can also be found in the package that you downloaded at the beginning of this tutorial. MapUI.h will allow us to easily control the parameters of the Faust object using their declared names in the Faust code. The other includes are necessary in most cases and are just parent classes of the DSP class generated by the Faust compiler. <<includeclass>> is where the code generated by the Faust compiler gets pasted. This architecture file can be used with the Faust compiler simply by running: faust -i -a faustMinimal.h FaustSynth.dsp -o FaustSynth.h where FaustSynth.h is the name of the generated file that we will import in our JUCE project later in this tutorial. The -i option inlines the included C++ files in the generated file. Alternatively, if Faust is not installed on your system, the Faust online IDE can be used to carry out the same task by choosing source/cplusplus in the Export (truck) function. The content of the downloaded C++ file can then be copied and pasted between the BEGIN-FAUSTDSP and END-FAUSTDSP tags. We're now ready to create a new JUCE plug-in project! Creating an Empty JUCE Plug-In Project In this section, we'll assume that you're a bit familiar with JUCE . If that's not your case, don't panic and just read their Getting started with the Projucer tutorial. We also recommend you to have a look a the next few following tutorials to have a sense of how things work. They're nice and easy to read! In the Projucer, create a new Audio Plug-In, add the targets that you want, in the settings, make sure that \"Plugin is a Synth\" is enabled. In our case, we named it \"MonoSynth\" (choose this name wisely as it will impact the class names of your program). Now, place the FaustSynth.h file generated in the previous step in the Source folder of your JUCE plug-in project. Then select it in Source in your file browser and drag it to the Projucer so that it becomes visible in the Source tab: At this point, try to compile your plug-in and see if it runs. Remember that JUCE now generates a \"standalone plug-in\" by default which is super convenient to test things without having to open the plug-in in a third party application. Integrating the Faust DSP Object to The JUCE Project Let's now integrate our Faust-generated DSP object to the PluginProcessor . Declare the following elements in the private section of the MonoSynthAudioProcessor class of PluginProcessor.h : private: MapUI* fUI; dsp* fDSP; float** outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MonoSynthAudioProcessor) fUI will be used to control the parameters of the Faust DSP, and fDSP will contain the audio DSP/callback itself (that's basically the object generated by the Faust compiler). In order to declare these objects without knowing the definition of MapUI and dsp you'll also have to declare empty class definitions at the beginning of the file: class dsp; class MapUI; class MonoSynthAudioProcessor : public AudioProcessor In PluginProcessor.cpp , include FaustSynth.h at the beginning of the file in the includes section: #include \"PluginProcessor.h\" #include \"PluginEditor.h\" #include \"FaustSynth.h\" Write the following in the prepareToPlay method: void MonoSynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { outputs[channel] = new float[samplesPerBlock]; } } Here, fDSP which is the Faust DSP object is first instantiated. Then fUI which will be used to control the parameters of the DSP is instantiated. These 2 objects are bound together using the buildUserInterface method of fDSP . Finally, memory is allocated for the stereo output of the Faust object. Note that outputs is a double array (one dimension for audio channels and one dimension for audio samples/buffers). Conversly, write the following in the releaseResources method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } Here, we just free the memory allocated in the previous steps when resources are released. Let's now get into the heart of the matter: the audio callback which is implemented through the processBlock method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); fDSP->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } Here, we basically compute one full audio block of size buffer.getNumSamples() , we store it in outputs and we then link outputs to the actual audio output of processBlock ( *buffer.getWritePointer(channel,i) ). At this point, you should be able to produce sound with your plug-in! Temporarily add the following line to the prepareToPlay method to set the value of the gate parameter to one: fUI->setParamValue(\"gate\",1); Note how fUI is used here to configure the parameter of the Faust DSP using its setParamValue method which has 2 arguments: the path/name of the parameter in the Faust code, and its value. Try to compile the plug-in for your desired target (e.g., VST, AU, etc.). In our case we'll juste generate a standalone plug-in for convenience. When running the plug-in, you should now hear sound! Since we want to control the parameters of our synth from the PluginEditor , we must create a series of public methods in PluginProcessor to control each parameter of our synth. In PluginProcessor.h this will look like: public: void setFreq(float freq); void setGain(float gain); void setCutoff(float cutoff); void setGate(bool gate); and the corresponding implementation in PluginProcessor.cpp will be: void MonoSynthAudioProcessor::setFreq(float freq) { fUI->setParamValue(\"freq\",freq); } void MonoSynthAudioProcessor::setGain(float gain) { fUI->setParamValue(\"gain\",gain); } void MonoSynthAudioProcessor::setGate(bool gate) { if(gate) { fUI->setParamValue(\"gate\",1); } else { fUI->setParamValue(\"gate\",0); } } void MonoSynthAudioProcessor::setCutoff(float cutoff) { fUI->setParamValue(\"cutoff\",cutoff); } That's it for the PluginProcessor ! Easy isn't it ;)? Now, let's add a basic interface to control this synth. We add a series of sliders, button, and labels to the private section of MonoSynthAudioProcessorEditor in PluginEditor.h : private: Slider frequencySlider; Slider gainSlider; Slider cutoffSlider; ToggleButton onOffButton; Label frequencyLabel; Label gainLabel; Label cutoffLabel; Label onOffLabel; and their corresponding implementation in PluginEditor.cpp : MonoSynthAudioProcessorEditor::MonoSynthAudioProcessorEditor(MonoSynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { setSize (800, 130); addAndMakeVisible(frequencySlider); frequencySlider.setRange(50.0, 5000.0); frequencySlider.setSkewFactorFromMidPoint(500.0); frequencySlider.setValue(300); frequencySlider.onValueChange = [this] { processor.setFreq(frequencySlider.getValue()); }; addAndMakeVisible(frequencyLabel); frequencyLabel.setText(\"Frequency\", dontSendNotification); frequencyLabel.attachToComponent(&frequencySlider, true); addAndMakeVisible(gainSlider); gainSlider.setRange(0.0, 1.0); gainSlider.setValue(0.5); gainSlider.onValueChange = [this] { processor.setGain(gainSlider.getValue()); }; addAndMakeVisible(gainLabel); gainLabel.setText(\"Gain\", dontSendNotification); gainLabel.attachToComponent (&gainSlider, true); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); addAndMakeVisible(onOffButton); onOffButton.onClick = [this] { processor.setGate(onOffButton.getToggleState()); }; addAndMakeVisible(onOffLabel); onOffLabel.setText(\"On/Off\", dontSendNotification); onOffLabel.attachToComponent (&onOffButton, true); } The methods that we declared in the previous step are basically called to set the value of the parameters of our DSP engine thanks to the processor object. The resized method must be implemented so that the various UI elements that we created actually have a size: void MonoSynthAudioProcessorEditor::resized() { const int sliderLeft = 80; frequencySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); gainSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); cutoffSlider.setBounds(sliderLeft, 70, getWidth() - sliderLeft - 20, 20); onOffButton.setBounds(sliderLeft, 100, getWidth() - sliderLeft - 20, 20); } Finally, make sure that you clean the implementation of the paint method to get rid of the default ugly \"Hello World:\" void MonoSynthAudioProcessorEditor::paint (Graphics& g) { g.fillAll(getLookAndFeel().findColour (ResizableWindow::backgroundColourId)); } Compile your plug-in and run it, it should look like this: The goal of this section was just to show you how to integrate a Faust DSP object into a JUCE plug-in project and how to control it with a simple UI. Once again, JUCE is a powerful tool to implement sophisticated UI in a very simple way. You'll find all the documentation you need on their website](https://juce.com/) to start making beautiful plug-ins! Simple Audio Effect Plug-In << Download the source of this tutorial >> In this section, we demonstrate how to use a Faust effect to build a plug-in in JUCE with a custom UI from scratch. Generating the DSP Engine The steps for generating an audio effect C++ DSP object with Faust are exactly the same as for a synth ( see the previous section ) and the faustMinimal.h architecture file can be used as well. For this example, we'll be using a stereo echo: Then run something like: faust -i -a faustMinimal.h FaustEffect.dsp -o Effect/Source/FaustEffect.h Creating a New Empty JUCE Plug-In Project The steps are the same as for the mono synthesizer tutorial except that the \"Plug-in is a Synth\" checkbox shouldn't be checked this time. For this example, we decided to give a very bad and explicit name to our plug-in project: \"Effect.\"\" Finally, import the C++ file generated in the previous step (i.e., FaustEffect.h ) in your project. Integrating the Faust DSP Object to The JUCE Project Steps are also similar to the mono synthesizer tutorial here, except that an audio input should be created. So, in PluginProcessor.h , we'll have: private: MapUI* fUI; dsp* fDSP; float **inputs; float **outputs; In PluginProcessor.cpp , for the prepareToPlay and releaseResources methods: void EffectAudioProcessor::prepareToPlay (double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); inputs = new float*[2]; outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { inputs[channel] = new float[samplesPerBlock]; outputs[channel] = new float[samplesPerBlock]; } } void EffectAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] inputs[channel]; delete[] outputs[channel]; } delete [] inputs; delete [] outputs; } and the audio callback: void EffectAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); for (int channel = 0; channel < totalNumInputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { inputs[channel][i] = *buffer.getWritePointer(channel,i); } } fDSP->compute(buffer.getNumSamples(),inputs,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++){ *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } This should be relatively self-explanatory. Of course, the corresponding control methods should be created as well, etc.: void EffectAudioProcessor::setDelay(float delay) { fUI->setParamValue(\"delay\",delay); } void EffectAudioProcessor::setFeedback(float feedback) { fUI->setParamValue(\"feedback\",feedback); } On the interface side, things can be easily adapted to match this new configuration with something like this: EffectAudioProcessorEditor::EffectAudioProcessorEditor (EffectAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { // Make sure that before the constructor has finished, you've set the // editor's size to whatever you need it to be. setSize(800, 100); addAndMakeVisible (delaySlider); delaySlider.setRange(0.0, 1.0); delaySlider.setValue(0.5); delaySlider.onValueChange = [this] { processor.setDelay(delaySlider.getValue()); }; addAndMakeVisible(delayLabel); delayLabel.setText(\"Delay (s)\", dontSendNotification); delayLabel.attachToComponent (&delaySlider, true); addAndMakeVisible(feedbackSlider); feedbackSlider.setRange(0.0, 1.0); feedbackSlider.setValue(0.5); feedbackSlider.onValueChange = [this] { processor.setFeedback(feedbackSlider.getValue()); }; addAndMakeVisible(feedbackLabel); feedbackLabel.setText(\"Feedback\", dontSendNotification); feedbackLabel.attachToComponent(&feedbackSlider, true); } void EffectAudioProcessorEditor::resized() { const int sliderLeft = 80; delaySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); feedbackSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); } Try to compile your program and you should have a beautiful effect plug-in :). Creating and Using a Polyphonic Faust DSP Object << Download the source of this tutorial >> The procedure to create a polyphonic synthesizer DSP object is slightly different than for a simple monophonic synth such as the one presented at the beginning of this tutorial. Here, we'll be using the same Faust program as one used for the mono synthesizer example . To enable polyphony, we just need to configure the nvoices metadata which allows us to specify the maximum number of voices of polyphony of the DSP object that will be generated: The package downloadable at the beginning of this tutorial contains a Faust architecture file slightly different from the one used in the previous examples (mono synth and effect): faustMinimalPoly.h . If you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/misc.h\" #include \"faust/gui/UI.h\" #include \"faust/gui/JSONUIDecoder.h\" #include \"faust/dsp/dsp.h\" #include \"faust/dsp/dsp-adapter.h\" #include \"faust/gui/meta.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP #include \"faust/dsp/faust-poly-engine.h\" #include \"faust/audio/dummy-audio.h\" std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; faust-poly-engine.h contains the FaustPolyEngine class which can be used to turn a Faust C++ DSP object into a polyphonic synthesizer. In order for this class to work, an \"audio driver\" must be provided which is what the dummyaudio class available in dummy-audio.h can be used for. It also allows us to pass the sampling rate and the buffer size to FaustPolyEngine . Compile the previous Faust program using this architecture file either by using the Faust command-line compiler or web IDE: faust -i -a faustMinimalPoly.h FaustSynth.dsp -o PolySynth/Source/FaustSynth.h and integrate FaustSynth.h to a new JUCE synth plug-in project (following the same steps as in the mono synth tutorial ). In PluginProcessor.h , declare the following objects: private: audio *driver; FaustPolyEngine *faustObject; float **outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PolySynthAudioProcessor) Once again, faustObject here will be the polyphonic Faust object and driver will be used to pass the sampling rate and buffer size to the system. Don't forget the declare the corresponding empty classes at the beginning of the file: class FaustPolyEngine; class audio; class PolySynthAudioProcessor : public AudioProcessor { In PluginProcessor.cpp , first don't forget to include FaustSynth.h . Then fill prepareToPlay with the following code: void PolySynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { driver = new dummyaudio(sampleRate,samplesPerBlock); faustObject = new FaustPolyEngine(NULL,driver,NULL); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel){ outputs[channel] = new float[samplesPerBlock]; } } First, the empty audio driver is instantiated and passed to the Faust polyphonic object. Of course, we allocate memory for the audio output. Resources are freed as follows: void PolySynthAudioProcessor::releaseResources() { //delete faustObject; delete driver; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } The processBlock method works the same way as for the mono synth tutorial except that the compute method is called here directly from the faustObject ( FaustPolyEngine ). void PolySynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); faustObject->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } While the setParamValue method can now be called directly from faustObject to set the value of specific parameters of the Faust object, other polyphony-specific methods are available such as keyOn and keyOff . For an exhaustive list, you can have a look at the source of FaustPolyEngine which should just speak by itself. Our final goal for this tutorial is to create a simple plug-in with the following interface: Hence, the Faust DSP object should be controlled with a polyphonic keyboard. New methods must be created in PluginProcessor.cpp to send keyon and keyoff events from the PluginEditor to the PluginProcessor : void PolySynthAudioProcessor::keyOn(int pitch, int velocity) { faustObject->keyOn(pitch,velocity); } void PolySynthAudioProcessor::keyOff(int pitch) { faustObject->keyOff(pitch); } void PolySynthAudioProcessor::setCutoff(float cutoff) { faustObject->setParamValue(\"cutoff\",cutoff); } Don't forget to declare these methods in PluginProcessor.h , of course. keyOn will allocate a new voice, convert its pitch parameter into a frequency that will be sent automatically to the Faust freq parameter, velocity is converted to a level that will be sent to the gain parameter, and the gate parameter is set to 1. Inversely, keyOff sets gate to 0 and waits for t60 to be reached to de-allocate the current voice. keyOn returns a voice ID whose type is unsigned long . This ID can then be used to change the parameter of a specific voice. We're not using this functionality in the example presented in this tutorial but here is how this would work: unsigned long voiceID = dspFaust.keyOn(60,110); dspFaust.setVoiceParamValue(\"/synth/cutoff\",voiceID,378); Note that voices can also be allocated directly without using keyOn and keyOff with the newVoice and the deleteVoice methods: unsigned long voiceID = dspFaust.newVoice(); dspFaust.setVoiceParamValue(\"/synth/gate\",voiceID,1); // do something... dspFaust.deleteVoice(voiceID); Using setParamValue as we're doing in the current example, we can set the value of a parameter for all the voices of the DSP engine. The following implementation is extremely primitive and only the messages from the UI keyboard are processed: we're just doing this for the sake of the example. If you've never worked with keyboards and MIDI in JUCE, we strongly recommend you to read this tutorial . In PluginEditor.h , let's first add the following inheritance to the PolySynthAudioProcessorEditor class: class PolySynthAudioProcessorEditor : public AudioProcessorEditor, private MidiInputCallback, private MidiKeyboardStateListener { This is necessary to implement the MIDI callback and the keyboard (UI) listener. This inheritance requires us to implement the following methods in the private section of PluginEditor.h . We also add an instance of a UI keyboard and its associated state as well as a slider and its label to control the cutoff frequency of the lowpass: private: void handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) override; void handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) override; void handleIncomingMidiMessage(MidiInput* source, const MidiMessage& message) override; MidiKeyboardState keyboardState; MidiKeyboardComponent keyboardComponent; Slider cutoffSlider; Label cutoffLabel; In PluginEditor.cpp , we can add the keyboard and the slider to the constructor: PolySynthAudioProcessorEditor::PolySynthAudioProcessorEditor (PolySynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p), keyboardComponent (keyboardState, MidiKeyboardComponent::horizontalKeyboard) { setSize (800, 150); addAndMakeVisible(keyboardComponent); keyboardState.addListener(this); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); } and we must de-allocate the keyboard state listener in the destructor: PolySynthAudioProcessorEditor::~PolySynthAudioProcessorEditor() { keyboardState.removeListener(this); } The implementation of the setCutoff method is detailed later in this tutorial and is very similar to the one described in the previous section. We also need to define the size of the various elements in the interface (as we did before): void PolySynthAudioProcessorEditor::resized() { const int sliderLeft = 80; keyboardComponent.setBounds (10,10,getWidth()-30,100); cutoffSlider.setBounds(sliderLeft, 120, getWidth() - sliderLeft - 20, 20); } MIDI messages are retrieved from the keyboard simply by implementing the following inherited methods: void PolySynthAudioProcessorEditor::handleIncomingMidiMessage (MidiInput* source, const MidiMessage& message) {} void PolySynthAudioProcessorEditor::handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) { processor.keyOn(midiNoteNumber,int(127*velocity)); } void PolySynthAudioProcessorEditor::handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) { processor.keyOff(midiNoteNumber); } That's it folks! Try to compile and run your plug-in, it should just work. Of course, things could be significantly improved here but at this point, you should be able to sail on your own.","title":" 2020-04-10 Faust & JUCE "},{"location":"workshops/2020-04-10-faust-juce/#faust-for-the-confined-adding-faust-dsp-support-to-your-juce-plug-ins","text":"JUCE is a well-known framework for creating audio plug-ins (i.e., VST, AU, AAX, etc.) and applications for a wide range of platforms. Faust can be used to generate ready-to-use JUCE applications and plug-ins implementing the standard user interface (UI) described in the Faust code using faust2juce . However, it is sooo easy to make professional looking UIs from scratch in JUCE that you might want to use Faust to implement the DSP portion of your plug-in and build your own UI. In this tutorial, we demonstrate how to use the Faust compiler to generate a C++ DSP object and how to interface it with your JUCE plug-in/UI. We'll cover basic examples (monophonic synth, polyphonic synth, and audio effect) as well as more advanced applications involving polyphony, etc.","title":"Faust For the Confined: Adding Faust DSP Support to Your JUCE Plug-ins"},{"location":"workshops/2020-04-10-faust-juce/#simple-monophonic-synth-plug-in","text":"<< Download the source of this tutorial >> In this section, we demonstrate how to use a Faust synth to build a plug-in in JUCE with a custom UI from scratch.","title":"Simple Monophonic Synth Plug-In"},{"location":"workshops/2020-04-10-faust-juce/#generating-the-dsp-engine","text":"First, let's implement a basic subtractive synthesizer in Faust based on a filtered sawtooth wave ( FaustSynth.dsp ): Feel free to run it in the web IDE to see how it sounds! The output of the lowpass is split into 2 signals to create a stereo object. Note that all the parameters are smoothed to prevent clicking (we want our plug-in to be clean!). Even gate is smoothed, which will apply a gentle exponential envelope when the trigger signal is sent, etc. Since Faust will not build its own UI here, the type of UI element used in this code doesn't really matter. They just serve as a point of entry to control the parameters of the audio engine we're about to generate. So nentry could be replaced by hslider or vslider , it would not make any difference. However, we encourage you to always write \"coherent\" interfaces in case someone would like to use your Faust code \"as such\" at some point. In order to turn this Faust program into a C++ DSP object usable in JUCE, we must use a Faust architecture file that will wrap the C++ code generated by the Faust compiler (that literally just contains an audio callback function). That's what faustMinimal.h (which is part of the package that you downloaded at the beginning of this tutorial) does. Actually, if you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/gui/MapUI.h\" #include \"faust/gui/meta.h\" #include \"faust/dsp/dsp.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP The faust/... files should be on your system if Faust is installed on it. If not, you can use the inlined version of the architecture file ( faustMinimalInlined.h ) which can also be found in the package that you downloaded at the beginning of this tutorial. MapUI.h will allow us to easily control the parameters of the Faust object using their declared names in the Faust code. The other includes are necessary in most cases and are just parent classes of the DSP class generated by the Faust compiler. <<includeclass>> is where the code generated by the Faust compiler gets pasted. This architecture file can be used with the Faust compiler simply by running: faust -i -a faustMinimal.h FaustSynth.dsp -o FaustSynth.h where FaustSynth.h is the name of the generated file that we will import in our JUCE project later in this tutorial. The -i option inlines the included C++ files in the generated file. Alternatively, if Faust is not installed on your system, the Faust online IDE can be used to carry out the same task by choosing source/cplusplus in the Export (truck) function. The content of the downloaded C++ file can then be copied and pasted between the BEGIN-FAUSTDSP and END-FAUSTDSP tags. We're now ready to create a new JUCE plug-in project!","title":"Generating the DSP Engine"},{"location":"workshops/2020-04-10-faust-juce/#creating-an-empty-juce-plug-in-project","text":"In this section, we'll assume that you're a bit familiar with JUCE . If that's not your case, don't panic and just read their Getting started with the Projucer tutorial. We also recommend you to have a look a the next few following tutorials to have a sense of how things work. They're nice and easy to read! In the Projucer, create a new Audio Plug-In, add the targets that you want, in the settings, make sure that \"Plugin is a Synth\" is enabled. In our case, we named it \"MonoSynth\" (choose this name wisely as it will impact the class names of your program). Now, place the FaustSynth.h file generated in the previous step in the Source folder of your JUCE plug-in project. Then select it in Source in your file browser and drag it to the Projucer so that it becomes visible in the Source tab: At this point, try to compile your plug-in and see if it runs. Remember that JUCE now generates a \"standalone plug-in\" by default which is super convenient to test things without having to open the plug-in in a third party application.","title":"Creating an Empty JUCE Plug-In Project"},{"location":"workshops/2020-04-10-faust-juce/#integrating-the-faust-dsp-object-to-the-juce-project","text":"Let's now integrate our Faust-generated DSP object to the PluginProcessor . Declare the following elements in the private section of the MonoSynthAudioProcessor class of PluginProcessor.h : private: MapUI* fUI; dsp* fDSP; float** outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MonoSynthAudioProcessor) fUI will be used to control the parameters of the Faust DSP, and fDSP will contain the audio DSP/callback itself (that's basically the object generated by the Faust compiler). In order to declare these objects without knowing the definition of MapUI and dsp you'll also have to declare empty class definitions at the beginning of the file: class dsp; class MapUI; class MonoSynthAudioProcessor : public AudioProcessor In PluginProcessor.cpp , include FaustSynth.h at the beginning of the file in the includes section: #include \"PluginProcessor.h\" #include \"PluginEditor.h\" #include \"FaustSynth.h\" Write the following in the prepareToPlay method: void MonoSynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { outputs[channel] = new float[samplesPerBlock]; } } Here, fDSP which is the Faust DSP object is first instantiated. Then fUI which will be used to control the parameters of the DSP is instantiated. These 2 objects are bound together using the buildUserInterface method of fDSP . Finally, memory is allocated for the stereo output of the Faust object. Note that outputs is a double array (one dimension for audio channels and one dimension for audio samples/buffers). Conversly, write the following in the releaseResources method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } Here, we just free the memory allocated in the previous steps when resources are released. Let's now get into the heart of the matter: the audio callback which is implemented through the processBlock method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); fDSP->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } Here, we basically compute one full audio block of size buffer.getNumSamples() , we store it in outputs and we then link outputs to the actual audio output of processBlock ( *buffer.getWritePointer(channel,i) ). At this point, you should be able to produce sound with your plug-in! Temporarily add the following line to the prepareToPlay method to set the value of the gate parameter to one: fUI->setParamValue(\"gate\",1); Note how fUI is used here to configure the parameter of the Faust DSP using its setParamValue method which has 2 arguments: the path/name of the parameter in the Faust code, and its value. Try to compile the plug-in for your desired target (e.g., VST, AU, etc.). In our case we'll juste generate a standalone plug-in for convenience. When running the plug-in, you should now hear sound! Since we want to control the parameters of our synth from the PluginEditor , we must create a series of public methods in PluginProcessor to control each parameter of our synth. In PluginProcessor.h this will look like: public: void setFreq(float freq); void setGain(float gain); void setCutoff(float cutoff); void setGate(bool gate); and the corresponding implementation in PluginProcessor.cpp will be: void MonoSynthAudioProcessor::setFreq(float freq) { fUI->setParamValue(\"freq\",freq); } void MonoSynthAudioProcessor::setGain(float gain) { fUI->setParamValue(\"gain\",gain); } void MonoSynthAudioProcessor::setGate(bool gate) { if(gate) { fUI->setParamValue(\"gate\",1); } else { fUI->setParamValue(\"gate\",0); } } void MonoSynthAudioProcessor::setCutoff(float cutoff) { fUI->setParamValue(\"cutoff\",cutoff); } That's it for the PluginProcessor ! Easy isn't it ;)? Now, let's add a basic interface to control this synth. We add a series of sliders, button, and labels to the private section of MonoSynthAudioProcessorEditor in PluginEditor.h : private: Slider frequencySlider; Slider gainSlider; Slider cutoffSlider; ToggleButton onOffButton; Label frequencyLabel; Label gainLabel; Label cutoffLabel; Label onOffLabel; and their corresponding implementation in PluginEditor.cpp : MonoSynthAudioProcessorEditor::MonoSynthAudioProcessorEditor(MonoSynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { setSize (800, 130); addAndMakeVisible(frequencySlider); frequencySlider.setRange(50.0, 5000.0); frequencySlider.setSkewFactorFromMidPoint(500.0); frequencySlider.setValue(300); frequencySlider.onValueChange = [this] { processor.setFreq(frequencySlider.getValue()); }; addAndMakeVisible(frequencyLabel); frequencyLabel.setText(\"Frequency\", dontSendNotification); frequencyLabel.attachToComponent(&frequencySlider, true); addAndMakeVisible(gainSlider); gainSlider.setRange(0.0, 1.0); gainSlider.setValue(0.5); gainSlider.onValueChange = [this] { processor.setGain(gainSlider.getValue()); }; addAndMakeVisible(gainLabel); gainLabel.setText(\"Gain\", dontSendNotification); gainLabel.attachToComponent (&gainSlider, true); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); addAndMakeVisible(onOffButton); onOffButton.onClick = [this] { processor.setGate(onOffButton.getToggleState()); }; addAndMakeVisible(onOffLabel); onOffLabel.setText(\"On/Off\", dontSendNotification); onOffLabel.attachToComponent (&onOffButton, true); } The methods that we declared in the previous step are basically called to set the value of the parameters of our DSP engine thanks to the processor object. The resized method must be implemented so that the various UI elements that we created actually have a size: void MonoSynthAudioProcessorEditor::resized() { const int sliderLeft = 80; frequencySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); gainSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); cutoffSlider.setBounds(sliderLeft, 70, getWidth() - sliderLeft - 20, 20); onOffButton.setBounds(sliderLeft, 100, getWidth() - sliderLeft - 20, 20); } Finally, make sure that you clean the implementation of the paint method to get rid of the default ugly \"Hello World:\" void MonoSynthAudioProcessorEditor::paint (Graphics& g) { g.fillAll(getLookAndFeel().findColour (ResizableWindow::backgroundColourId)); } Compile your plug-in and run it, it should look like this: The goal of this section was just to show you how to integrate a Faust DSP object into a JUCE plug-in project and how to control it with a simple UI. Once again, JUCE is a powerful tool to implement sophisticated UI in a very simple way. You'll find all the documentation you need on their website](https://juce.com/) to start making beautiful plug-ins!","title":"Integrating the Faust DSP Object to The JUCE Project"},{"location":"workshops/2020-04-10-faust-juce/#simple-audio-effect-plug-in","text":"<< Download the source of this tutorial >> In this section, we demonstrate how to use a Faust effect to build a plug-in in JUCE with a custom UI from scratch.","title":"Simple Audio Effect Plug-In"},{"location":"workshops/2020-04-10-faust-juce/#generating-the-dsp-engine_1","text":"The steps for generating an audio effect C++ DSP object with Faust are exactly the same as for a synth ( see the previous section ) and the faustMinimal.h architecture file can be used as well. For this example, we'll be using a stereo echo: Then run something like: faust -i -a faustMinimal.h FaustEffect.dsp -o Effect/Source/FaustEffect.h","title":"Generating the DSP Engine"},{"location":"workshops/2020-04-10-faust-juce/#creating-a-new-empty-juce-plug-in-project","text":"The steps are the same as for the mono synthesizer tutorial except that the \"Plug-in is a Synth\" checkbox shouldn't be checked this time. For this example, we decided to give a very bad and explicit name to our plug-in project: \"Effect.\"\" Finally, import the C++ file generated in the previous step (i.e., FaustEffect.h ) in your project.","title":"Creating a New Empty JUCE Plug-In Project"},{"location":"workshops/2020-04-10-faust-juce/#integrating-the-faust-dsp-object-to-the-juce-project_1","text":"Steps are also similar to the mono synthesizer tutorial here, except that an audio input should be created. So, in PluginProcessor.h , we'll have: private: MapUI* fUI; dsp* fDSP; float **inputs; float **outputs; In PluginProcessor.cpp , for the prepareToPlay and releaseResources methods: void EffectAudioProcessor::prepareToPlay (double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); inputs = new float*[2]; outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { inputs[channel] = new float[samplesPerBlock]; outputs[channel] = new float[samplesPerBlock]; } } void EffectAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] inputs[channel]; delete[] outputs[channel]; } delete [] inputs; delete [] outputs; } and the audio callback: void EffectAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); for (int channel = 0; channel < totalNumInputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { inputs[channel][i] = *buffer.getWritePointer(channel,i); } } fDSP->compute(buffer.getNumSamples(),inputs,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++){ *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } This should be relatively self-explanatory. Of course, the corresponding control methods should be created as well, etc.: void EffectAudioProcessor::setDelay(float delay) { fUI->setParamValue(\"delay\",delay); } void EffectAudioProcessor::setFeedback(float feedback) { fUI->setParamValue(\"feedback\",feedback); } On the interface side, things can be easily adapted to match this new configuration with something like this: EffectAudioProcessorEditor::EffectAudioProcessorEditor (EffectAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { // Make sure that before the constructor has finished, you've set the // editor's size to whatever you need it to be. setSize(800, 100); addAndMakeVisible (delaySlider); delaySlider.setRange(0.0, 1.0); delaySlider.setValue(0.5); delaySlider.onValueChange = [this] { processor.setDelay(delaySlider.getValue()); }; addAndMakeVisible(delayLabel); delayLabel.setText(\"Delay (s)\", dontSendNotification); delayLabel.attachToComponent (&delaySlider, true); addAndMakeVisible(feedbackSlider); feedbackSlider.setRange(0.0, 1.0); feedbackSlider.setValue(0.5); feedbackSlider.onValueChange = [this] { processor.setFeedback(feedbackSlider.getValue()); }; addAndMakeVisible(feedbackLabel); feedbackLabel.setText(\"Feedback\", dontSendNotification); feedbackLabel.attachToComponent(&feedbackSlider, true); } void EffectAudioProcessorEditor::resized() { const int sliderLeft = 80; delaySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); feedbackSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); } Try to compile your program and you should have a beautiful effect plug-in :).","title":"Integrating the Faust DSP Object to The JUCE Project"},{"location":"workshops/2020-04-10-faust-juce/#creating-and-using-a-polyphonic-faust-dsp-object","text":"<< Download the source of this tutorial >> The procedure to create a polyphonic synthesizer DSP object is slightly different than for a simple monophonic synth such as the one presented at the beginning of this tutorial. Here, we'll be using the same Faust program as one used for the mono synthesizer example . To enable polyphony, we just need to configure the nvoices metadata which allows us to specify the maximum number of voices of polyphony of the DSP object that will be generated: The package downloadable at the beginning of this tutorial contains a Faust architecture file slightly different from the one used in the previous examples (mono synth and effect): faustMinimalPoly.h . If you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/misc.h\" #include \"faust/gui/UI.h\" #include \"faust/gui/JSONUIDecoder.h\" #include \"faust/dsp/dsp.h\" #include \"faust/dsp/dsp-adapter.h\" #include \"faust/gui/meta.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP #include \"faust/dsp/faust-poly-engine.h\" #include \"faust/audio/dummy-audio.h\" std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; faust-poly-engine.h contains the FaustPolyEngine class which can be used to turn a Faust C++ DSP object into a polyphonic synthesizer. In order for this class to work, an \"audio driver\" must be provided which is what the dummyaudio class available in dummy-audio.h can be used for. It also allows us to pass the sampling rate and the buffer size to FaustPolyEngine . Compile the previous Faust program using this architecture file either by using the Faust command-line compiler or web IDE: faust -i -a faustMinimalPoly.h FaustSynth.dsp -o PolySynth/Source/FaustSynth.h and integrate FaustSynth.h to a new JUCE synth plug-in project (following the same steps as in the mono synth tutorial ). In PluginProcessor.h , declare the following objects: private: audio *driver; FaustPolyEngine *faustObject; float **outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PolySynthAudioProcessor) Once again, faustObject here will be the polyphonic Faust object and driver will be used to pass the sampling rate and buffer size to the system. Don't forget the declare the corresponding empty classes at the beginning of the file: class FaustPolyEngine; class audio; class PolySynthAudioProcessor : public AudioProcessor { In PluginProcessor.cpp , first don't forget to include FaustSynth.h . Then fill prepareToPlay with the following code: void PolySynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { driver = new dummyaudio(sampleRate,samplesPerBlock); faustObject = new FaustPolyEngine(NULL,driver,NULL); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel){ outputs[channel] = new float[samplesPerBlock]; } } First, the empty audio driver is instantiated and passed to the Faust polyphonic object. Of course, we allocate memory for the audio output. Resources are freed as follows: void PolySynthAudioProcessor::releaseResources() { //delete faustObject; delete driver; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } The processBlock method works the same way as for the mono synth tutorial except that the compute method is called here directly from the faustObject ( FaustPolyEngine ). void PolySynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); faustObject->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } While the setParamValue method can now be called directly from faustObject to set the value of specific parameters of the Faust object, other polyphony-specific methods are available such as keyOn and keyOff . For an exhaustive list, you can have a look at the source of FaustPolyEngine which should just speak by itself. Our final goal for this tutorial is to create a simple plug-in with the following interface: Hence, the Faust DSP object should be controlled with a polyphonic keyboard. New methods must be created in PluginProcessor.cpp to send keyon and keyoff events from the PluginEditor to the PluginProcessor : void PolySynthAudioProcessor::keyOn(int pitch, int velocity) { faustObject->keyOn(pitch,velocity); } void PolySynthAudioProcessor::keyOff(int pitch) { faustObject->keyOff(pitch); } void PolySynthAudioProcessor::setCutoff(float cutoff) { faustObject->setParamValue(\"cutoff\",cutoff); } Don't forget to declare these methods in PluginProcessor.h , of course. keyOn will allocate a new voice, convert its pitch parameter into a frequency that will be sent automatically to the Faust freq parameter, velocity is converted to a level that will be sent to the gain parameter, and the gate parameter is set to 1. Inversely, keyOff sets gate to 0 and waits for t60 to be reached to de-allocate the current voice. keyOn returns a voice ID whose type is unsigned long . This ID can then be used to change the parameter of a specific voice. We're not using this functionality in the example presented in this tutorial but here is how this would work: unsigned long voiceID = dspFaust.keyOn(60,110); dspFaust.setVoiceParamValue(\"/synth/cutoff\",voiceID,378); Note that voices can also be allocated directly without using keyOn and keyOff with the newVoice and the deleteVoice methods: unsigned long voiceID = dspFaust.newVoice(); dspFaust.setVoiceParamValue(\"/synth/gate\",voiceID,1); // do something... dspFaust.deleteVoice(voiceID); Using setParamValue as we're doing in the current example, we can set the value of a parameter for all the voices of the DSP engine. The following implementation is extremely primitive and only the messages from the UI keyboard are processed: we're just doing this for the sake of the example. If you've never worked with keyboards and MIDI in JUCE, we strongly recommend you to read this tutorial . In PluginEditor.h , let's first add the following inheritance to the PolySynthAudioProcessorEditor class: class PolySynthAudioProcessorEditor : public AudioProcessorEditor, private MidiInputCallback, private MidiKeyboardStateListener { This is necessary to implement the MIDI callback and the keyboard (UI) listener. This inheritance requires us to implement the following methods in the private section of PluginEditor.h . We also add an instance of a UI keyboard and its associated state as well as a slider and its label to control the cutoff frequency of the lowpass: private: void handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) override; void handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) override; void handleIncomingMidiMessage(MidiInput* source, const MidiMessage& message) override; MidiKeyboardState keyboardState; MidiKeyboardComponent keyboardComponent; Slider cutoffSlider; Label cutoffLabel; In PluginEditor.cpp , we can add the keyboard and the slider to the constructor: PolySynthAudioProcessorEditor::PolySynthAudioProcessorEditor (PolySynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p), keyboardComponent (keyboardState, MidiKeyboardComponent::horizontalKeyboard) { setSize (800, 150); addAndMakeVisible(keyboardComponent); keyboardState.addListener(this); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); } and we must de-allocate the keyboard state listener in the destructor: PolySynthAudioProcessorEditor::~PolySynthAudioProcessorEditor() { keyboardState.removeListener(this); } The implementation of the setCutoff method is detailed later in this tutorial and is very similar to the one described in the previous section. We also need to define the size of the various elements in the interface (as we did before): void PolySynthAudioProcessorEditor::resized() { const int sliderLeft = 80; keyboardComponent.setBounds (10,10,getWidth()-30,100); cutoffSlider.setBounds(sliderLeft, 120, getWidth() - sliderLeft - 20, 20); } MIDI messages are retrieved from the keyboard simply by implementing the following inherited methods: void PolySynthAudioProcessorEditor::handleIncomingMidiMessage (MidiInput* source, const MidiMessage& message) {} void PolySynthAudioProcessorEditor::handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) { processor.keyOn(midiNoteNumber,int(127*velocity)); } void PolySynthAudioProcessorEditor::handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) { processor.keyOff(midiNoteNumber); } That's it folks! Try to compile and run your plug-in, it should just work. Of course, things could be significantly improved here but at this point, you should be able to sail on your own.","title":"Creating and Using a Polyphonic Faust DSP Object"},{"location":"workshops/2020-11-21-faust-vcvrack/","text":"Using Faust with VCV Rack VCV Rack is virtual modular synthesizer, allowing thousands of separated developed modules to be connected in patches to synthesize and process sounds. A large community of developers are providing tons of modules to be installed in the application as libraries , and a lot of them are developed as open-source projects on GitHub . In this tutorial, we'll show how to use the Faust language to generate monophonic or polyphonic modules: either using the Faust aware programmable VCV Prototype to edit/compile/test Faust DSP code or using the faust2vcvrack tool with allows to generate standalone modules to introduce module development, a quick introduction on using C++ to develop modules will be done first. Installation Get the binary version for your OS here. Install the VCV Rack SDK From Plugin Development Tutorial page and the SDK itself for your OS. Don't forget to setup the RACK_DIR variable: export RACK_DIR=<Rack SDK folder> . Compiling the VCV Prototype module Faust version The Faust compiler can be embedded in applications or plugins using libfaust , and DSP code can be edited and JIT compiled on the fly. You'll have to clone and compile the GitHub project . Be use to use the faust branch and follow the explanations given. Then you should be ready for this workshop ! The modular principle VCV Rack follows the Modular synthesizers principe explained on this Wikipedia article : Modular synthesizers are synthesizers composed of separate modules of different functions. The modules can be connected together with patch cords, a matrix patching system, or switches by the user to create a patch . The output (voltages) from the modules may function as (audio) signals, control voltages, or logic/timing conditions. Typical modules are oscillators (operate on frequency), filters (spectrum), amplifiers/gates (amplitude) and Envelope generators (dynamic control). To do that, control signals (CV) run at audio rate, and so the entire patch is triggered with audio buffers of only one sample. When described as CV signals, parameters can thus be changed in real-time by other signals coming from any module, just by connecting them. So a kind of blur between audio and control signals is part in this model and signals can be connected anywhere. Since software modules mimic real physical ones, they somewhat follow the same conventions to represent signal range, typically with [-5v...5v] or [0v..10v] values , or 1V/octave for MIDI signals. Read the voltage standard page for a more complete description. Control parameters can also be changed from the module GUI using switches, knobs.etc... Modules can be monophonic or polyphonic (up to 16 channels) , where each cable actually transport several (usually related) signals. The polyphonic model is obviously used for instruments, but can also be used for effects. Polyhonic modules have thicker cables in the GUI. Developing C++ Modules Before using Faust to develop modules, let's have a look at the standard procedure. Modules are usually created with C++ using the VCV Rack SDK that gives developers several tools to start with. Following the tutorial here , a template project can be created: Generating a template ./helper.py createplugin MyPlugin The created folder contains a Makefile that can be used to compile and install the module in your (previously installed) VCV Rack application: make && make install GUI description using SVG The module GUI is done using SVG. Developers will classically prepare the background layer with Inkscape or a similar tool, with special conventions to describe audio or CV inputs/outputs, UI items (knobs, lights, custom widgets... ). Here a example of a basic SVG template with a light , a param (like knob), an audio or CV input , and an audio or CV output : Inside the module project, the following command will decode the SVG file and generate template C++ code to create the various widget: ../helper.py createmodule MyModule res/MyModule.svg src/MyModule.cpp Adding DSP code Then C++ code will be added to implement as simple oscillator in the process function: float phase = 0.f; float freq = 440.f; void process(const ProcessArgs &args) override { // Accumulate the phase phase += freq * args.sampleTime; if (phase >= 0.5f) phase -= 1.f; // Compute the sine output float sine = std::sin(2.f * M_PI * phase); // Audio signals are typically +/-5V outputs[SINE_OUTPUT].setVoltage(5.f * sine); } The following line in plugin.cpp has to be uncommented: p->addModel(modelMyModule); and well as in plugin.hpp: extern Model* modelMyModule; And compilation and installation of the module has to be done again: make && make install Programming using the Faust aware VCV Prototype module The VCV Prototype module runs scripting languages for prototyping, learning, and live coding. It can currently be programmed using JavaScript, Lua , Vult , or PureData . A generic GUI with 6 inputs/outputs (either audio or CV signals), 6 knobs, 6 lights (RGB LEDs) or 6 switches (with RGB LEDs) is defined. Note that only monophonic examples can be coded with the prototype. Faust support thanks to libfaust embedding the Interpreter backend has been added. It allows to edit/compile/execute DSP programs on the fly, with acceptable performances (even if using the LLVM JIT would allow to generate faster code, but as the expense of a much more complicated installation procedure). Editing/compiling/executing DSP files Faust DSP files have to be loaded in VCV Prototype and edited in a external editor (Visual Studio Code, Atom...). Each time the file is saved, it will be recompiled and executed. To possibly save compilation time, the DSP machine code is saved in a cache, and possibly restored the next time the session will be loaded. The 6 audio inputs/outputs can be accessed in order in the Faust DSP which can thus use up to 6 channels. The 6 switches , knobs as well as the lights and switchLights can be connected to UI controllers using metadata: [switch:N] (with N from 1 to 6) has to be used in a button or checkbox item to connect it to the prototype interface switch number N [knob:N] (with N from 1 to 6) has to be used in a vslider , hslider or nentry item to connect it to the prototype interface knob number N. The knob [0..1] range will be mapped to the slider/nentry [min..max] range [light_red:N|light_green:N|light_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph item to connect it to the prototype interface light number N [switchlight_red:N|switchlight_green:N|switchlight_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph to connect it to the prototype interface switchLight number N So a button or checkbox UI item can use the [switch:N] metadata to be associated with the corresponding GUI switch, which color can be controlled using the switchlight_xx:N metadata. For instance: gate = button(\"gate [switch:1\") : hbargraph(\"[switchlight_red:1]\", 0, 1); can be written to describe a button which become red when pressed check = checkbox(\"check [switch:2]\") : vbargraph(\"[switchlight_red:2]\", 0, 1) : vbargraph(\"[switchlight_green:2]\", 0, 1) : vbargraph(\"[switchlight_blue:2]\", 0, 1); can be written to describe a checkbox which become white when checked Other metadata: [scale:lin|log|exp] metadata is implemented. The rack.lib Faust library contains usefull functions to convert CV signals, and can be enriched if needed. Note that only monophonic DSP programs can be described. DSP examples Here is a simple example showing how oscillators can be controlled by GUI items, associated with metadata in the DSP code: Following the VCV Prototype model, note that audio outputs are multipled by 5 to follow the [-5v..5v] range convention. The VCV Prototype standard examples ported to Faust can be seen in the examples folder: gain.dsp shows how switches and knobs can be connected using metadata , and even change color when pressed or moved: vco.dsp shows an oscillator with frequency controlled by a knob and a CV pich signal (following the 1V/octave convention): rainbow.dsp Some additional examples: synth.dsp demonstrates how to use all different VCV Prototype UI items organ.dsp demonstrates a MIDI controllable additive synthesis based organ physicalmodel.dsp demonstrates a modal synthesis based bell connected to a reverb Using faust2vcvrack The faust2vcvrack tool compiles a Faust DSP program in a folder containing the VCV Rack plugin C++ source code and a Makefile to compile it. By default the resulting C++ code is compiled and installed in the VCV Rack application: faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [additional Faust options (-vec -vs 8...)] <file.dsp> The tool is now part of the master-dev branch on GitHub, or can be used with Faust IDE , and by selecting the appropriate export targets ( vcvrack , vcvrack-poly8 , or vcvrack-poly16 ). Here are the available options: -soundfile when compiling a DSP using the 'soundfile' primitive, add required resources -source to only create the source folder -nvoices <num> to produce a polyphonic self-contained DSP with <num> voices, ready to be used with MIDI Faust DSP code classically produces audio signals in the [-1..1] range. Since VCV expects audio signals in the [-5v..5v] range, they are automatically converted in the architecture file . CV control in the [0v..10v] volts range will be mapped to the controllers [min..max] range. Polyphony support Polyphonic modules can be created using the -nvoices <num> parameter up to 16 voices. The freq/gate/gain convention can be used in the DSP code. VCV Rack follows the 1V/octave convention for MIDI pitch values, so the MIDI signals are automatically converted to freq using this convention. Gain and gates signals (using the [0v..10v] range) are converted to [0..1] values. Note that creating polyphonic effects also make sense in VCV Rack. For instance a reverb connected to a polyphonic instrument would need to be polyphonic. Thus the -nvoices <num> parameter can also be used in this case. Metadata Controllers (typically buttons , sliders , nentry or bargraph ) will be automatically transformed in GUI items (like switches, knobs or lights). But they can alternatively be connected to CV inputs/outputs using a metadata: [CV:N] can be used in input (typically sliders or nentry ) or output (typically bargraph ) controllers to connect them to CV instead of regular GUI parameters. DSP examples Here is a simple example showing how oscillators can be controlled by UI items. One switch, one button and two knobs will be created in the GUI: A polyphonic instrument with freq/gate/gain controllers associated with VC MIDI inputs, using the [CV:N] metadata, to be compiled with the -nvoices <num> option: This polyphonic instrument can then be connected to a polyphonic reverb, to be also compiled with the -nvoices <num> option:","title":" 2020-11-21 Faust & VCV Rack "},{"location":"workshops/2020-11-21-faust-vcvrack/#using-faust-with-vcv-rack","text":"VCV Rack is virtual modular synthesizer, allowing thousands of separated developed modules to be connected in patches to synthesize and process sounds. A large community of developers are providing tons of modules to be installed in the application as libraries , and a lot of them are developed as open-source projects on GitHub . In this tutorial, we'll show how to use the Faust language to generate monophonic or polyphonic modules: either using the Faust aware programmable VCV Prototype to edit/compile/test Faust DSP code or using the faust2vcvrack tool with allows to generate standalone modules to introduce module development, a quick introduction on using C++ to develop modules will be done first.","title":"Using Faust with VCV Rack"},{"location":"workshops/2020-11-21-faust-vcvrack/#installation","text":"Get the binary version for your OS here.","title":"Installation"},{"location":"workshops/2020-11-21-faust-vcvrack/#install-the-vcv-rack-sdk","text":"From Plugin Development Tutorial page and the SDK itself for your OS. Don't forget to setup the RACK_DIR variable: export RACK_DIR=<Rack SDK folder> .","title":"Install the VCV Rack SDK"},{"location":"workshops/2020-11-21-faust-vcvrack/#compiling-the-vcv-prototype-module-faust-version","text":"The Faust compiler can be embedded in applications or plugins using libfaust , and DSP code can be edited and JIT compiled on the fly. You'll have to clone and compile the GitHub project . Be use to use the faust branch and follow the explanations given. Then you should be ready for this workshop !","title":"Compiling the VCV Prototype module Faust version"},{"location":"workshops/2020-11-21-faust-vcvrack/#the-modular-principle","text":"VCV Rack follows the Modular synthesizers principe explained on this Wikipedia article : Modular synthesizers are synthesizers composed of separate modules of different functions. The modules can be connected together with patch cords, a matrix patching system, or switches by the user to create a patch . The output (voltages) from the modules may function as (audio) signals, control voltages, or logic/timing conditions. Typical modules are oscillators (operate on frequency), filters (spectrum), amplifiers/gates (amplitude) and Envelope generators (dynamic control). To do that, control signals (CV) run at audio rate, and so the entire patch is triggered with audio buffers of only one sample. When described as CV signals, parameters can thus be changed in real-time by other signals coming from any module, just by connecting them. So a kind of blur between audio and control signals is part in this model and signals can be connected anywhere. Since software modules mimic real physical ones, they somewhat follow the same conventions to represent signal range, typically with [-5v...5v] or [0v..10v] values , or 1V/octave for MIDI signals. Read the voltage standard page for a more complete description. Control parameters can also be changed from the module GUI using switches, knobs.etc... Modules can be monophonic or polyphonic (up to 16 channels) , where each cable actually transport several (usually related) signals. The polyphonic model is obviously used for instruments, but can also be used for effects. Polyhonic modules have thicker cables in the GUI.","title":"The modular principle"},{"location":"workshops/2020-11-21-faust-vcvrack/#developing-c-modules","text":"Before using Faust to develop modules, let's have a look at the standard procedure. Modules are usually created with C++ using the VCV Rack SDK that gives developers several tools to start with. Following the tutorial here , a template project can be created:","title":"Developing C++ Modules"},{"location":"workshops/2020-11-21-faust-vcvrack/#generating-a-template","text":"./helper.py createplugin MyPlugin The created folder contains a Makefile that can be used to compile and install the module in your (previously installed) VCV Rack application: make && make install","title":"Generating a template"},{"location":"workshops/2020-11-21-faust-vcvrack/#gui-description-using-svg","text":"The module GUI is done using SVG. Developers will classically prepare the background layer with Inkscape or a similar tool, with special conventions to describe audio or CV inputs/outputs, UI items (knobs, lights, custom widgets... ). Here a example of a basic SVG template with a light , a param (like knob), an audio or CV input , and an audio or CV output : Inside the module project, the following command will decode the SVG file and generate template C++ code to create the various widget: ../helper.py createmodule MyModule res/MyModule.svg src/MyModule.cpp","title":"GUI description using SVG"},{"location":"workshops/2020-11-21-faust-vcvrack/#adding-dsp-code","text":"Then C++ code will be added to implement as simple oscillator in the process function: float phase = 0.f; float freq = 440.f; void process(const ProcessArgs &args) override { // Accumulate the phase phase += freq * args.sampleTime; if (phase >= 0.5f) phase -= 1.f; // Compute the sine output float sine = std::sin(2.f * M_PI * phase); // Audio signals are typically +/-5V outputs[SINE_OUTPUT].setVoltage(5.f * sine); } The following line in plugin.cpp has to be uncommented: p->addModel(modelMyModule); and well as in plugin.hpp: extern Model* modelMyModule; And compilation and installation of the module has to be done again: make && make install","title":"Adding DSP code"},{"location":"workshops/2020-11-21-faust-vcvrack/#programming-using-the-faust-aware-vcv-prototype-module","text":"The VCV Prototype module runs scripting languages for prototyping, learning, and live coding. It can currently be programmed using JavaScript, Lua , Vult , or PureData . A generic GUI with 6 inputs/outputs (either audio or CV signals), 6 knobs, 6 lights (RGB LEDs) or 6 switches (with RGB LEDs) is defined. Note that only monophonic examples can be coded with the prototype. Faust support thanks to libfaust embedding the Interpreter backend has been added. It allows to edit/compile/execute DSP programs on the fly, with acceptable performances (even if using the LLVM JIT would allow to generate faster code, but as the expense of a much more complicated installation procedure).","title":"Programming using the Faust aware VCV Prototype module"},{"location":"workshops/2020-11-21-faust-vcvrack/#editingcompilingexecuting-dsp-files","text":"Faust DSP files have to be loaded in VCV Prototype and edited in a external editor (Visual Studio Code, Atom...). Each time the file is saved, it will be recompiled and executed. To possibly save compilation time, the DSP machine code is saved in a cache, and possibly restored the next time the session will be loaded. The 6 audio inputs/outputs can be accessed in order in the Faust DSP which can thus use up to 6 channels. The 6 switches , knobs as well as the lights and switchLights can be connected to UI controllers using metadata: [switch:N] (with N from 1 to 6) has to be used in a button or checkbox item to connect it to the prototype interface switch number N [knob:N] (with N from 1 to 6) has to be used in a vslider , hslider or nentry item to connect it to the prototype interface knob number N. The knob [0..1] range will be mapped to the slider/nentry [min..max] range [light_red:N|light_green:N|light_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph item to connect it to the prototype interface light number N [switchlight_red:N|switchlight_green:N|switchlight_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph to connect it to the prototype interface switchLight number N So a button or checkbox UI item can use the [switch:N] metadata to be associated with the corresponding GUI switch, which color can be controlled using the switchlight_xx:N metadata. For instance: gate = button(\"gate [switch:1\") : hbargraph(\"[switchlight_red:1]\", 0, 1); can be written to describe a button which become red when pressed check = checkbox(\"check [switch:2]\") : vbargraph(\"[switchlight_red:2]\", 0, 1) : vbargraph(\"[switchlight_green:2]\", 0, 1) : vbargraph(\"[switchlight_blue:2]\", 0, 1); can be written to describe a checkbox which become white when checked Other metadata: [scale:lin|log|exp] metadata is implemented. The rack.lib Faust library contains usefull functions to convert CV signals, and can be enriched if needed. Note that only monophonic DSP programs can be described.","title":"Editing/compiling/executing DSP files"},{"location":"workshops/2020-11-21-faust-vcvrack/#dsp-examples","text":"Here is a simple example showing how oscillators can be controlled by GUI items, associated with metadata in the DSP code: Following the VCV Prototype model, note that audio outputs are multipled by 5 to follow the [-5v..5v] range convention. The VCV Prototype standard examples ported to Faust can be seen in the examples folder: gain.dsp shows how switches and knobs can be connected using metadata , and even change color when pressed or moved: vco.dsp shows an oscillator with frequency controlled by a knob and a CV pich signal (following the 1V/octave convention): rainbow.dsp Some additional examples: synth.dsp demonstrates how to use all different VCV Prototype UI items organ.dsp demonstrates a MIDI controllable additive synthesis based organ physicalmodel.dsp demonstrates a modal synthesis based bell connected to a reverb","title":"DSP examples"},{"location":"workshops/2020-11-21-faust-vcvrack/#using-faust2vcvrack","text":"The faust2vcvrack tool compiles a Faust DSP program in a folder containing the VCV Rack plugin C++ source code and a Makefile to compile it. By default the resulting C++ code is compiled and installed in the VCV Rack application: faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [additional Faust options (-vec -vs 8...)] <file.dsp> The tool is now part of the master-dev branch on GitHub, or can be used with Faust IDE , and by selecting the appropriate export targets ( vcvrack , vcvrack-poly8 , or vcvrack-poly16 ). Here are the available options: -soundfile when compiling a DSP using the 'soundfile' primitive, add required resources -source to only create the source folder -nvoices <num> to produce a polyphonic self-contained DSP with <num> voices, ready to be used with MIDI Faust DSP code classically produces audio signals in the [-1..1] range. Since VCV expects audio signals in the [-5v..5v] range, they are automatically converted in the architecture file . CV control in the [0v..10v] volts range will be mapped to the controllers [min..max] range.","title":"Using faust2vcvrack"},{"location":"workshops/2020-11-21-faust-vcvrack/#polyphony-support","text":"Polyphonic modules can be created using the -nvoices <num> parameter up to 16 voices. The freq/gate/gain convention can be used in the DSP code. VCV Rack follows the 1V/octave convention for MIDI pitch values, so the MIDI signals are automatically converted to freq using this convention. Gain and gates signals (using the [0v..10v] range) are converted to [0..1] values. Note that creating polyphonic effects also make sense in VCV Rack. For instance a reverb connected to a polyphonic instrument would need to be polyphonic. Thus the -nvoices <num> parameter can also be used in this case.","title":"Polyphony support"},{"location":"workshops/2020-11-21-faust-vcvrack/#metadata","text":"Controllers (typically buttons , sliders , nentry or bargraph ) will be automatically transformed in GUI items (like switches, knobs or lights). But they can alternatively be connected to CV inputs/outputs using a metadata: [CV:N] can be used in input (typically sliders or nentry ) or output (typically bargraph ) controllers to connect them to CV instead of regular GUI parameters.","title":"Metadata"},{"location":"workshops/2020-11-21-faust-vcvrack/#dsp-examples_1","text":"Here is a simple example showing how oscillators can be controlled by UI items. One switch, one button and two knobs will be created in the GUI: A polyphonic instrument with freq/gate/gain controllers associated with VC MIDI inputs, using the [CV:N] metadata, to be compiled with the -nvoices <num> option: This polyphonic instrument can then be connected to a polyphonic reverb, to be also compiled with the -nvoices <num> option:","title":"DSP examples"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Faust Language Documentation This website centralizes all the documentation of the Faust programming language . It contains tutorials, the Faust manual, various examples, etc. It is meant to be used in tandem with the Faust Web IDE . The main Faust website can be found at the following URL: https://faust.grame.fr What is Faust? Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. Getting Started If You're In a Hurry If you\u2019re in a hurry and just wanna have a look at how Faust programs look like, you can simply check the Faust Examples . If You Wanna Get Started With Faust If you\u2019re looking for a step by step tutorial of approximately 2 hours that will walk you through writing simple Faust programs and give you an overview of what Faust can do, have a look at our Quick Start Tutorial . If You\u2019re Looking For the \"Manual\" Faust\u2019s syntax and features are thoroughly documented in the Faust Manual . This resource contains hundreds of code examples and many short tutorials. If You\u2019re Looking For the Documentation of a Function In the Faust Libraries The documentation of Faust's standard libraries is automatically generated directly from the libraries' source code. If You Prefer Video Tutorials Check out the Faust Kadenze course . If You're Looking For Something in Particular You can use the Search function of this website if you're looking for something specific. Other Resources to learn Faust","title":"Home"},{"location":"#faust-language-documentation","text":"This website centralizes all the documentation of the Faust programming language . It contains tutorials, the Faust manual, various examples, etc. It is meant to be used in tandem with the Faust Web IDE . The main Faust website can be found at the following URL: https://faust.grame.fr","title":"Faust Language Documentation"},{"location":"#what-is-faust","text":"Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc.","title":"What is Faust?"},{"location":"#getting-started","text":"","title":"Getting Started"},{"location":"#if-youre-in-a-hurry","text":"If you\u2019re in a hurry and just wanna have a look at how Faust programs look like, you can simply check the Faust Examples .","title":"If You're In a Hurry"},{"location":"#if-you-wanna-get-started-with-faust","text":"If you\u2019re looking for a step by step tutorial of approximately 2 hours that will walk you through writing simple Faust programs and give you an overview of what Faust can do, have a look at our Quick Start Tutorial .","title":"If You Wanna Get Started With Faust"},{"location":"#if-youre-looking-for-the-manual","text":"Faust\u2019s syntax and features are thoroughly documented in the Faust Manual . This resource contains hundreds of code examples and many short tutorials.","title":"If You\u2019re Looking For the \"Manual\""},{"location":"#if-youre-looking-for-the-documentation-of-a-function-in-the-faust-libraries","text":"The documentation of Faust's standard libraries is automatically generated directly from the libraries' source code.","title":"If You\u2019re Looking For the Documentation of a Function In the Faust Libraries"},{"location":"#if-you-prefer-video-tutorials","text":"Check out the Faust Kadenze course .","title":"If You Prefer Video Tutorials"},{"location":"#if-youre-looking-for-something-in-particular","text":"You can use the Search function of this website if you're looking for something specific.","title":"If You're Looking For Something in Particular"},{"location":"#other-resources-to-learn-faust","text":"","title":"Other Resources to learn Faust"},{"location":"about/","text":"The Faust Project The Faust Project has started in 2002. It is actively developed by the GRAME-CNCM Research Department . Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen, Karim Barkati, J\u00e9r\u00f4me Barth\u00e9lemy, Tim Blechmann, Tiziano Bole, Alain Bonardi, Bart Brouns, Thomas Charbonnel, Raffaele Ciavarella, Ian Clester, Julien Colafrancesco, Damien Cramet, Sarah Denoux, \u00c9tienne Gaudrin, Olivier Guillerminet, Pierre Guillot, Albert Gr\u00e4f, Christoph Hart, Agathe Herrou, Pierre Jouvelot, Stefan Kersten, Victor Lazzarini, Matthieu Leberre, Mathieu Leroi, Fernando Lopez-Lezcano, Kjetil Matheussen, Hermann Meyer, R\u00e9my Muller, Raphael Panis, Eliott Paris, Reza Payami, Laurent Pottier, Dirk Roosenburg, Sampo Savolainen, Nicolas Scaringella, Anne Sedes, Priyanka Shekar, Stephen Sinclair, Travis Skare, Julius Smith, Mike Solomon, Roman Sommer Michael Wilson. as well as our colleagues at GRAME : Dominique Fober Christophe Lebreton St\u00e9phane Letz Romain Michon Yann Orlarey We would like also to thank for their financial support: the French Ministry of Culture , the Auvergne-Rh\u00f4ne-Alpes Region , the City of Lyon , the French National Research Agency (ANR) .","title":"About"},{"location":"about/#the-faust-project","text":"The Faust Project has started in 2002. It is actively developed by the GRAME-CNCM Research Department . Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen, Karim Barkati, J\u00e9r\u00f4me Barth\u00e9lemy, Tim Blechmann, Tiziano Bole, Alain Bonardi, Bart Brouns, Thomas Charbonnel, Raffaele Ciavarella, Ian Clester, Julien Colafrancesco, Damien Cramet, Sarah Denoux, \u00c9tienne Gaudrin, Olivier Guillerminet, Pierre Guillot, Albert Gr\u00e4f, Christoph Hart, Agathe Herrou, Pierre Jouvelot, Stefan Kersten, Victor Lazzarini, Matthieu Leberre, Mathieu Leroi, Fernando Lopez-Lezcano, Kjetil Matheussen, Hermann Meyer, R\u00e9my Muller, Raphael Panis, Eliott Paris, Reza Payami, Laurent Pottier, Dirk Roosenburg, Sampo Savolainen, Nicolas Scaringella, Anne Sedes, Priyanka Shekar, Stephen Sinclair, Travis Skare, Julius Smith, Mike Solomon, Roman Sommer Michael Wilson. as well as our colleagues at GRAME : Dominique Fober Christophe Lebreton St\u00e9phane Letz Romain Michon Yann Orlarey We would like also to thank for their financial support: the French Ministry of Culture , the Auvergne-Rh\u00f4ne-Alpes Region , the City of Lyon , the French National Research Agency (ANR) .","title":"The Faust Project"},{"location":"examples/SAM/","text":"SAM","title":" SAM "},{"location":"examples/SAM/#sam","text":"","title":"SAM"},{"location":"examples/ambisonics/","text":"ambisonics fourSourcesToOcto oneSourceToStereo","title":" ambisonics "},{"location":"examples/ambisonics/#ambisonics","text":"","title":"ambisonics"},{"location":"examples/ambisonics/#foursourcestoocto","text":"","title":"fourSourcesToOcto"},{"location":"examples/ambisonics/#onesourcetostereo","text":"","title":"oneSourceToStereo"},{"location":"examples/analysis/","text":"analysis FFT dbmeter spectralLevel spectralTiltLab vumeter","title":" analysis "},{"location":"examples/analysis/#analysis","text":"","title":"analysis"},{"location":"examples/analysis/#fft","text":"","title":"FFT"},{"location":"examples/analysis/#dbmeter","text":"","title":"dbmeter"},{"location":"examples/analysis/#spectrallevel","text":"","title":"spectralLevel"},{"location":"examples/analysis/#spectraltiltlab","text":"","title":"spectralTiltLab"},{"location":"examples/analysis/#vumeter","text":"","title":"vumeter"},{"location":"examples/autodiff/","text":"autodiff noise noop ramp","title":"autodiff"},{"location":"examples/autodiff/#autodiff","text":"","title":"autodiff"},{"location":"examples/autodiff/#noise","text":"","title":"noise"},{"location":"examples/autodiff/#noop","text":"","title":"noop"},{"location":"examples/autodiff/#ramp","text":"","title":"ramp"},{"location":"examples/bela/","text":"bela AdditiveSynth AdditiveSynth_Analog FMSynth2 FMSynth2_Analog FMSynth2_FX FMSynth2_FX_Analog FXChaine2 GrainGenerator WaveSynth WaveSynth_Analog WaveSynth_FX WaveSynth_FX_Analog crossDelay2 granulator repeater simpleFX simpleFX_Analog simpleSynth simpleSynth_Analog simpleSynth_FX simpleSynth_FX_Analog trill_simple_monophonic_keyboard trill_simple_polyphonic_keyboard","title":" bela "},{"location":"examples/bela/#bela","text":"","title":"bela"},{"location":"examples/bela/#additivesynth","text":"","title":"AdditiveSynth"},{"location":"examples/bela/#additivesynth_analog","text":"","title":"AdditiveSynth_Analog"},{"location":"examples/bela/#fmsynth2","text":"","title":"FMSynth2"},{"location":"examples/bela/#fmsynth2_analog","text":"","title":"FMSynth2_Analog"},{"location":"examples/bela/#fmsynth2_fx","text":"","title":"FMSynth2_FX"},{"location":"examples/bela/#fmsynth2_fx_analog","text":"","title":"FMSynth2_FX_Analog"},{"location":"examples/bela/#fxchaine2","text":"","title":"FXChaine2"},{"location":"examples/bela/#graingenerator","text":"","title":"GrainGenerator"},{"location":"examples/bela/#wavesynth","text":"","title":"WaveSynth"},{"location":"examples/bela/#wavesynth_analog","text":"","title":"WaveSynth_Analog"},{"location":"examples/bela/#wavesynth_fx","text":"","title":"WaveSynth_FX"},{"location":"examples/bela/#wavesynth_fx_analog","text":"","title":"WaveSynth_FX_Analog"},{"location":"examples/bela/#crossdelay2","text":"","title":"crossDelay2"},{"location":"examples/bela/#granulator","text":"","title":"granulator"},{"location":"examples/bela/#repeater","text":"","title":"repeater"},{"location":"examples/bela/#simplefx","text":"","title":"simpleFX"},{"location":"examples/bela/#simplefx_analog","text":"","title":"simpleFX_Analog"},{"location":"examples/bela/#simplesynth","text":"","title":"simpleSynth"},{"location":"examples/bela/#simplesynth_analog","text":"","title":"simpleSynth_Analog"},{"location":"examples/bela/#simplesynth_fx","text":"","title":"simpleSynth_FX"},{"location":"examples/bela/#simplesynth_fx_analog","text":"","title":"simpleSynth_FX_Analog"},{"location":"examples/bela/#trill_simple_monophonic_keyboard","text":"","title":"trill_simple_monophonic_keyboard"},{"location":"examples/bela/#trill_simple_polyphonic_keyboard","text":"","title":"trill_simple_polyphonic_keyboard"},{"location":"examples/delayEcho/","text":"delayEcho echo quadEcho smoothDelay stereoEcho tapiir","title":" delayEcho "},{"location":"examples/delayEcho/#delayecho","text":"","title":"delayEcho"},{"location":"examples/delayEcho/#echo","text":"","title":"echo"},{"location":"examples/delayEcho/#quadecho","text":"","title":"quadEcho"},{"location":"examples/delayEcho/#smoothdelay","text":"","title":"smoothDelay"},{"location":"examples/delayEcho/#stereoecho","text":"","title":"stereoEcho"},{"location":"examples/delayEcho/#tapiir","text":"","title":"tapiir"},{"location":"examples/dynamic/","text":"dynamic compressor distortion gateCompressor noiseGate volume","title":" dynamic "},{"location":"examples/dynamic/#dynamic","text":"","title":"dynamic"},{"location":"examples/dynamic/#compressor","text":"","title":"compressor"},{"location":"examples/dynamic/#distortion","text":"","title":"distortion"},{"location":"examples/dynamic/#gatecompressor","text":"","title":"gateCompressor"},{"location":"examples/dynamic/#noisegate","text":"","title":"noiseGate"},{"location":"examples/dynamic/#volume","text":"","title":"volume"},{"location":"examples/filtering/","text":"filtering APF BPF DNN HPF LPF bandFilter cryBaby diodeLadder filterBank graphicEqLab highShelf korg35HPF korg35LPF lfBoost lowBoost lowCut lowShelf moogHalfLadder moogLadder moogVCF notch oberheim oberheimBPF oberheimBSF oberheimHPF oberheimLPF parametricEqLab parametricEqualizer peakNotch peakingEQ sallenKey2ndOrder sallenKey2ndOrderBPF sallenKey2ndOrderHPF sallenKey2ndOrderLPF sallenKeyOnePole sallenKeyOnePoleHPF sallenKeyOnePoleLPF spectralTilt vcfWahLab vocoder wahPedal","title":" filtering "},{"location":"examples/filtering/#filtering","text":"","title":"filtering"},{"location":"examples/filtering/#apf","text":"","title":"APF"},{"location":"examples/filtering/#bpf","text":"","title":"BPF"},{"location":"examples/filtering/#dnn","text":"","title":"DNN"},{"location":"examples/filtering/#hpf","text":"","title":"HPF"},{"location":"examples/filtering/#lpf","text":"","title":"LPF"},{"location":"examples/filtering/#bandfilter","text":"","title":"bandFilter"},{"location":"examples/filtering/#crybaby","text":"","title":"cryBaby"},{"location":"examples/filtering/#diodeladder","text":"","title":"diodeLadder"},{"location":"examples/filtering/#filterbank","text":"","title":"filterBank"},{"location":"examples/filtering/#graphiceqlab","text":"","title":"graphicEqLab"},{"location":"examples/filtering/#highshelf","text":"","title":"highShelf"},{"location":"examples/filtering/#korg35hpf","text":"","title":"korg35HPF"},{"location":"examples/filtering/#korg35lpf","text":"","title":"korg35LPF"},{"location":"examples/filtering/#lfboost","text":"","title":"lfBoost"},{"location":"examples/filtering/#lowboost","text":"","title":"lowBoost"},{"location":"examples/filtering/#lowcut","text":"","title":"lowCut"},{"location":"examples/filtering/#lowshelf","text":"","title":"lowShelf"},{"location":"examples/filtering/#mooghalfladder","text":"","title":"moogHalfLadder"},{"location":"examples/filtering/#moogladder","text":"","title":"moogLadder"},{"location":"examples/filtering/#moogvcf","text":"","title":"moogVCF"},{"location":"examples/filtering/#notch","text":"","title":"notch"},{"location":"examples/filtering/#oberheim","text":"","title":"oberheim"},{"location":"examples/filtering/#oberheimbpf","text":"","title":"oberheimBPF"},{"location":"examples/filtering/#oberheimbsf","text":"","title":"oberheimBSF"},{"location":"examples/filtering/#oberheimhpf","text":"","title":"oberheimHPF"},{"location":"examples/filtering/#oberheimlpf","text":"","title":"oberheimLPF"},{"location":"examples/filtering/#parametriceqlab","text":"","title":"parametricEqLab"},{"location":"examples/filtering/#parametricequalizer","text":"","title":"parametricEqualizer"},{"location":"examples/filtering/#peaknotch","text":"","title":"peakNotch"},{"location":"examples/filtering/#peakingeq","text":"","title":"peakingEQ"},{"location":"examples/filtering/#sallenkey2ndorder","text":"","title":"sallenKey2ndOrder"},{"location":"examples/filtering/#sallenkey2ndorderbpf","text":"","title":"sallenKey2ndOrderBPF"},{"location":"examples/filtering/#sallenkey2ndorderhpf","text":"","title":"sallenKey2ndOrderHPF"},{"location":"examples/filtering/#sallenkey2ndorderlpf","text":"","title":"sallenKey2ndOrderLPF"},{"location":"examples/filtering/#sallenkeyonepole","text":"","title":"sallenKeyOnePole"},{"location":"examples/filtering/#sallenkeyonepolehpf","text":"","title":"sallenKeyOnePoleHPF"},{"location":"examples/filtering/#sallenkeyonepolelpf","text":"","title":"sallenKeyOnePoleLPF"},{"location":"examples/filtering/#spectraltilt","text":"","title":"spectralTilt"},{"location":"examples/filtering/#vcfwahlab","text":"","title":"vcfWahLab"},{"location":"examples/filtering/#vocoder","text":"","title":"vocoder"},{"location":"examples/filtering/#wahpedal","text":"","title":"wahPedal"},{"location":"examples/gameaudio/","text":"gameaudio bubble complex_rain door fire insects rain thunder wind windchimes","title":" gameaudio "},{"location":"examples/gameaudio/#gameaudio","text":"","title":"gameaudio"},{"location":"examples/gameaudio/#bubble","text":"","title":"bubble"},{"location":"examples/gameaudio/#complex_rain","text":"","title":"complex_rain"},{"location":"examples/gameaudio/#door","text":"","title":"door"},{"location":"examples/gameaudio/#fire","text":"","title":"fire"},{"location":"examples/gameaudio/#insects","text":"","title":"insects"},{"location":"examples/gameaudio/#rain","text":"","title":"rain"},{"location":"examples/gameaudio/#thunder","text":"","title":"thunder"},{"location":"examples/gameaudio/#wind","text":"","title":"wind"},{"location":"examples/gameaudio/#windchimes","text":"","title":"windchimes"},{"location":"examples/generator/","text":"generator churchOrgan filterOsc noise noiseMetadata osc osci sawtoothLab virtualAnalog virtualAnalogLab","title":" generator "},{"location":"examples/generator/#generator","text":"","title":"generator"},{"location":"examples/generator/#churchorgan","text":"","title":"churchOrgan"},{"location":"examples/generator/#filterosc","text":"","title":"filterOsc"},{"location":"examples/generator/#noise","text":"","title":"noise"},{"location":"examples/generator/#noisemetadata","text":"","title":"noiseMetadata"},{"location":"examples/generator/#osc","text":"","title":"osc"},{"location":"examples/generator/#osci","text":"","title":"osci"},{"location":"examples/generator/#sawtoothlab","text":"","title":"sawtoothLab"},{"location":"examples/generator/#virtualanalog","text":"","title":"virtualAnalog"},{"location":"examples/generator/#virtualanaloglab","text":"","title":"virtualAnalogLab"},{"location":"examples/misc/","text":"misc UITester autopan capture drumkit matrix midiTester statespace switcher tester tester2","title":" misc "},{"location":"examples/misc/#misc","text":"","title":"misc"},{"location":"examples/misc/#uitester","text":"","title":"UITester"},{"location":"examples/misc/#autopan","text":"","title":"autopan"},{"location":"examples/misc/#capture","text":"","title":"capture"},{"location":"examples/misc/#drumkit","text":"","title":"drumkit"},{"location":"examples/misc/#matrix","text":"","title":"matrix"},{"location":"examples/misc/#miditester","text":"","title":"midiTester"},{"location":"examples/misc/#statespace","text":"","title":"statespace"},{"location":"examples/misc/#switcher","text":"","title":"switcher"},{"location":"examples/misc/#tester","text":"","title":"tester"},{"location":"examples/misc/#tester2","text":"","title":"tester2"},{"location":"examples/phasing/","text":"phasing flanger phaser phaserFlangerLab","title":" phasing "},{"location":"examples/phasing/#phasing","text":"","title":"phasing"},{"location":"examples/phasing/#flanger","text":"","title":"flanger"},{"location":"examples/phasing/#phaser","text":"","title":"phaser"},{"location":"examples/phasing/#phaserflangerlab","text":"","title":"phaserFlangerLab"},{"location":"examples/physicalModeling/","text":"physicalModeling brass brassMIDI churchBell clarinet clarinetMIDI djembeMIDI elecGuitarMIDI englishBell flute fluteMIDI frenchBell germanBell guitarMIDI karplus marimbaMIDI modularInterpInstrMIDI nylonGuitarMIDI russianBell standardBell violin violinMIDI vocalBP vocalBPMIDI vocalFOF vocalFOFMIDI","title":" physicalModeling "},{"location":"examples/physicalModeling/#physicalmodeling","text":"","title":"physicalModeling"},{"location":"examples/physicalModeling/#brass","text":"","title":"brass"},{"location":"examples/physicalModeling/#brassmidi","text":"","title":"brassMIDI"},{"location":"examples/physicalModeling/#churchbell","text":"","title":"churchBell"},{"location":"examples/physicalModeling/#clarinet","text":"","title":"clarinet"},{"location":"examples/physicalModeling/#clarinetmidi","text":"","title":"clarinetMIDI"},{"location":"examples/physicalModeling/#djembemidi","text":"","title":"djembeMIDI"},{"location":"examples/physicalModeling/#elecguitarmidi","text":"","title":"elecGuitarMIDI"},{"location":"examples/physicalModeling/#englishbell","text":"","title":"englishBell"},{"location":"examples/physicalModeling/#flute","text":"","title":"flute"},{"location":"examples/physicalModeling/#flutemidi","text":"","title":"fluteMIDI"},{"location":"examples/physicalModeling/#frenchbell","text":"","title":"frenchBell"},{"location":"examples/physicalModeling/#germanbell","text":"","title":"germanBell"},{"location":"examples/physicalModeling/#guitarmidi","text":"","title":"guitarMIDI"},{"location":"examples/physicalModeling/#karplus","text":"","title":"karplus"},{"location":"examples/physicalModeling/#marimbamidi","text":"","title":"marimbaMIDI"},{"location":"examples/physicalModeling/#modularinterpinstrmidi","text":"","title":"modularInterpInstrMIDI"},{"location":"examples/physicalModeling/#nylonguitarmidi","text":"","title":"nylonGuitarMIDI"},{"location":"examples/physicalModeling/#russianbell","text":"","title":"russianBell"},{"location":"examples/physicalModeling/#standardbell","text":"","title":"standardBell"},{"location":"examples/physicalModeling/#violin","text":"","title":"violin"},{"location":"examples/physicalModeling/#violinmidi","text":"","title":"violinMIDI"},{"location":"examples/physicalModeling/#vocalbp","text":"","title":"vocalBP"},{"location":"examples/physicalModeling/#vocalbpmidi","text":"","title":"vocalBPMIDI"},{"location":"examples/physicalModeling/#vocalfof","text":"","title":"vocalFOF"},{"location":"examples/physicalModeling/#vocalfofmidi","text":"","title":"vocalFOFMIDI"},{"location":"examples/pitchShifting/","text":"pitchShifting pitchShifter","title":" pitchShifting "},{"location":"examples/pitchShifting/#pitchshifting","text":"","title":"pitchShifting"},{"location":"examples/pitchShifting/#pitchshifter","text":"","title":"pitchShifter"},{"location":"examples/psychoacoustic/","text":"psychoacoustic harmonicExciter","title":" psychoacoustic "},{"location":"examples/psychoacoustic/#psychoacoustic","text":"","title":"psychoacoustic"},{"location":"examples/psychoacoustic/#harmonicexciter","text":"","title":"harmonicExciter"},{"location":"examples/quantizing/","text":"quantizing quantizedChords","title":"quantizing"},{"location":"examples/quantizing/#quantizing","text":"","title":"quantizing"},{"location":"examples/quantizing/#quantizedchords","text":"","title":"quantizedChords"},{"location":"examples/reverb/","text":"reverb dattorro fdnRev freeverb greyhole jprev reverbDesigner reverbTester vital_rev zitaRev zitaRevFDN","title":" reverb "},{"location":"examples/reverb/#reverb","text":"","title":"reverb"},{"location":"examples/reverb/#dattorro","text":"","title":"dattorro"},{"location":"examples/reverb/#fdnrev","text":"","title":"fdnRev"},{"location":"examples/reverb/#freeverb","text":"","title":"freeverb"},{"location":"examples/reverb/#greyhole","text":"","title":"greyhole"},{"location":"examples/reverb/#jprev","text":"","title":"jprev"},{"location":"examples/reverb/#reverbdesigner","text":"","title":"reverbDesigner"},{"location":"examples/reverb/#reverbtester","text":"","title":"reverbTester"},{"location":"examples/reverb/#vital_rev","text":"","title":"vital_rev"},{"location":"examples/reverb/#zitarev","text":"","title":"zitaRev"},{"location":"examples/reverb/#zitarevfdn","text":"","title":"zitaRevFDN"},{"location":"examples/smartKeyboard/","text":"smartKeyboard acGuitar bells bowed brass clarinet crazyGuiro drums dubDub elecGuitar fm frog harp midiOnly multiSynth toy trumpet turenas violin violin2 vocal","title":" smartKeyboard "},{"location":"examples/smartKeyboard/#smartkeyboard","text":"","title":"smartKeyboard"},{"location":"examples/smartKeyboard/#acguitar","text":"","title":"acGuitar"},{"location":"examples/smartKeyboard/#bells","text":"","title":"bells"},{"location":"examples/smartKeyboard/#bowed","text":"","title":"bowed"},{"location":"examples/smartKeyboard/#brass","text":"","title":"brass"},{"location":"examples/smartKeyboard/#clarinet","text":"","title":"clarinet"},{"location":"examples/smartKeyboard/#crazyguiro","text":"","title":"crazyGuiro"},{"location":"examples/smartKeyboard/#drums","text":"","title":"drums"},{"location":"examples/smartKeyboard/#dubdub","text":"","title":"dubDub"},{"location":"examples/smartKeyboard/#elecguitar","text":"","title":"elecGuitar"},{"location":"examples/smartKeyboard/#fm","text":"","title":"fm"},{"location":"examples/smartKeyboard/#frog","text":"","title":"frog"},{"location":"examples/smartKeyboard/#harp","text":"","title":"harp"},{"location":"examples/smartKeyboard/#midionly","text":"","title":"midiOnly"},{"location":"examples/smartKeyboard/#multisynth","text":"","title":"multiSynth"},{"location":"examples/smartKeyboard/#toy","text":"","title":"toy"},{"location":"examples/smartKeyboard/#trumpet","text":"","title":"trumpet"},{"location":"examples/smartKeyboard/#turenas","text":"","title":"turenas"},{"location":"examples/smartKeyboard/#violin","text":"","title":"violin"},{"location":"examples/smartKeyboard/#violin2","text":"","title":"violin2"},{"location":"examples/smartKeyboard/#vocal","text":"","title":"vocal"},{"location":"examples/spat/","text":"spat panpot spat","title":" spat "},{"location":"examples/spat/#spat","text":"","title":"spat"},{"location":"examples/spat/#panpot","text":"","title":"panpot"},{"location":"examples/spat/#spat_1","text":"","title":"spat"},{"location":"manual/architectures/","text":"Architecture Files A Faust program describes a signal processor , a pure DSP computation that maps input signals to output signals . It says nothing about audio drivers or controllers (like GUI, OSC, MIDI, sensors) that are going to control the DSP. This additional 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 controllers interfaces to be used. This approach allows a single Faust program to be easily deployed to a large variety of audio standards (e.g., Max/MSP externals, PD externals, VST plugins, CoreAudio applications, JACK applications, iPhone/Android, etc.): The architecture to be used is specified at compile time with the -a option. For example faust -a jack-gtk.cpp foo.dsp indicates to use the JACK GTK architecture when compiling foo.dsp . Some of these architectures are a modular combination of an audio module and one or more controller modules . Some architecture only combine an audio module with the generated DSP to create an audio engine to be controlled with an additional setParamValue/getParamValue kind of API, so that the controller part can be completeley defined externally. This is the purpose of the faust2api script explained later on. Minimal Structure of an Architecture File Before going into the details of the architecture files provided with Faust distribution, it is important to have an idea of the essential parts that compose an architecture file. Technically, an architecture file is any text file with two placeholders <<includeIntrinsic>> and <<includeclass>> . The first placeholder is currently not used, and the second one is replaced by the code generated by the FAUST compiler. Therefore, the really minimal architecture file, let's call it nullarch.cpp , is the following: <<includeIntrinsic>> <<includeclass>> This nullarch.cpp architecture has the property that faust foo.dsp and faust -a nullarch.cpp foo.dsp produce the same result. Obviously, this is not very useful, moreover the resulting cpp file doesn't compile. Here is miniarch.cpp , a minimal architecture file that contains enough information to produce a cpp file that can be successfully compiled: <<includeIntrinsic>> #define FAUSTFLOAT float class dsp {}; struct Meta { virtual void declare(const char* key, const char* value) {}; }; struct Soundfile {}; struct UI { // -- widget's layouts virtual void openTabBox(const char* label) {} virtual void openHorizontalBox(const char* label) {} virtual void openVerticalBox(const char* label) {} virtual void closeBox() {} // -- active widgets virtual void addButton(const char* label, FAUSTFLOAT* zone) {} virtual void addCheckButton(const char* label, FAUSTFLOAT* zone) {} virtual void addVerticalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addHorizontalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addNumEntry(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} // -- passive widgets virtual void addHorizontalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} virtual void addVerticalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) {} // -- metadata declarations virtual void declare(FAUSTFLOAT* zone, const char* key, const char* val) {} }; <<includeclass>> This architecture is still not very useful, but it gives an idea of what a real-life architecture file has to implement, in addition to the audio part itself. As we will see in the next section, Faust architectures are implemented using a modular approach to avoid code duplication and favor code maintenance and reuse. Audio Architecture Modules A Faust generated program has to connect to a underlying audio layer. Depending if the final program is a application or plugin, the way to connect to this audio layer will differ: applications typically use the OS audio driver API, which will be CoreAudio on macOS, ALSA on Linux, WASAPI on Windows for instance, or any kind of multi-platforms API like PortAudio or JACK . In this case a subclass of the base class audio (see later) has to be written plugins (like VST3 , Audio Unit or JUCE for instance) usually have to follow a more constrained API which imposes a life cyle , something like loading/initializing/starting/running/stopping/unloading sequence of operations. In this case the Faust generated module new/init/compute/delete methods have to be inserted in the plugin API, by calling each module function at the appropriate place. External and internal audio sample formats Audio samples are managed by the underlying audio layer, typically as 32 bits float or 64 bits double values in the [-1..1] interval. Their format is defined with the FAUSTFLOAT macro implemented in the architecture file as float by default. The DSP audio samples format is choosen at compile time, with the -single (= default), -double or -quad compilation option. Control parameters like buttons, sliders... also use the FAUSTFLOAT format. By default, the FAUSTFLOAT macro is written with the following code: #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif which gives it a value ( if not already defined ), and since the default internal format is float , nothing special has to be done in the general case. But when the DSP is compiled using the -double option, the audio inputs/outputs buffers have to be adapted , with a dsp_sample_adapter class, for instance like in the dynamic-jack-gt tool . Note that an architecture may redefine FAUSTFLOAT in double, and have the complete audio chain running in double. This has to be done before including any architecture file that would define FAUSTFLOAT itself (because of the #ifndef logic). Connection to an audio driver API An audio driver architecture typically connects a Faust program to the audio drivers. It is responsible for: allocating and releasing the audio channels and presenting the audio as non-interleaved float/double data (depending of the FAUSTFLOAT macro definition), normalized between -1.0 and 1.0 calling the DSP init method at init time, to setup the ma.SR variable possibly used in the DSP code calling the DSP compute method to handle incoming audio buffers and/or to produce audio outputs. The default compilation model uses separated audio input and output buffers not referring to the same memory locations. The -inpl (--in-place) code generation model allows us to generate code working when input and output buffers are the same (which is typically needed in some embedded devices). This option currently only works in scalar (= default) code generation mode. A Faust audio architecture module derives from an audio class can be defined as below (simplified version, see the real version here) : class audio { public: audio() {} virtual ~audio() {} /** * Init the DSP. * @param name - the DSP name to be given to the audio driven * (could appear as a JACK client for instance) * @param dsp - the dsp that will be initialized with the driver sample rate * * @return true is sucessful, false if case of driver failure. **/ virtual bool init(const char* name, dsp* dsp) = 0; /** * Start audio processing. * @return true is sucessfull, false if case of driver failure. **/ virtual bool start() = 0; /** * Stop audio processing. **/ virtual void stop() = 0; void setShutdownCallback(shutdown_callback cb, void* arg) = 0; // Return buffer size in frames. virtual int getBufferSize() = 0; // Return the driver sample rate in Hz. virtual int getSampleRate() = 0; // Return the driver hardware inputs number. virtual int getNumInputs() = 0; // Return the driver hardware outputs number. virtual int getNumOutputs() = 0; /** * @return Returns the average proportion of available CPU * being spent inside the audio callbacks (between 0.0 and 1.0). **/ virtual float getCPULoad() = 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. Here is the hierarchy of some of the supported audio drivers: Connection to a plugin audio API In the case of plugin, an audio plugin architecture has to be developed, by integrating the Faust DSP new/init/compute/delete methods in the plugin API. Here is a concrete example using the JUCE framework: a FaustPlugInAudioProcessor class, subclass of the juce::AudioProcessor has to be defined. The Faust generated C++ instance will be created in its constructor, either in monophonic of polyphonic mode (see later sections) the Faust DSP instance is initialized in the JUCE prepareToPlay method using the current sample rate value the Faust dsp compute is called in the JUCE process which receives the audio inputs/outputs buffers to be processed additional methods can possibly be implemented to handle MIDI messages or save/restore the plugin parameters state for instance. This methodology obviously has to be adapted for each supported plugin API. MIDI Architecture Modules A MIDI architecture module typically connects a Faust program to the MIDI drivers. MIDI control connects DSP parameters with MIDI messages (in both directions), and can be used to trigger polyphonic instruments. MIDI Messages in the DSP Source Code MIDI control messages are described as metadata in UI elements. They are decoded by a MidiUI class, subclass of UI , which parses incoming MIDI messages and updates the appropriate control parameters, or sends MIDI messages when the UI elements (sliders, buttons...) are moved. Defined Standard MIDI Messages A special [midi:xxx yyy...] metadata needs to be added to the UI element. The full description of supported MIDI messages is part of the Faust documentation . MIDI Classes A midi base class defining MIDI messages decoding/encoding methods has been developed. It will be used to receive and transmit MIDI messages: class midi { public: midi() {} virtual ~midi() {} // Additional timestamped API for MIDI input virtual MapUI* keyOn(double, int channel, int pitch, int velocity) { return keyOn(channel, pitch, velocity); } virtual void keyOff(double, int channel, int pitch, int velocity = 0) { keyOff(channel, pitch, velocity); } virtual void keyPress(double, int channel, int pitch, int press) { keyPress(channel, pitch, press); } virtual void chanPress(double date, int channel, int press) { chanPress(channel, press); } virtual void pitchWheel(double, int channel, int wheel) { pitchWheel(channel, wheel); } virtual void ctrlChange(double, int channel, int ctrl, int value) { ctrlChange(channel, ctrl, value); } virtual void ctrlChange14bits(double, int channel, int ctrl, int value) { ctrlChange14bits(channel, ctrl, value); } virtual void rpn(double, int channel, int ctrl, int value) { rpn(channel, ctrl, value); } virtual void progChange(double, int channel, int pgm) { progChange(channel, pgm); } virtual void sysEx(double, std::vector<unsigned char>& message) { sysEx(message); } // MIDI sync virtual void startSync(double date) {} virtual void stopSync(double date) {} virtual void clock(double date) {} // Standard MIDI API virtual MapUI* keyOn(int channel, int pitch, int velocity) { return nullptr; } virtual void keyOff(int channel, int pitch, int velocity) {} virtual void keyPress(int channel, int pitch, int press) {} virtual void chanPress(int channel, int press) {} virtual void ctrlChange(int channel, int ctrl, int value) {} virtual void ctrlChange14bits(int channel, int ctrl, int value) {} virtual void rpn(int channel, int ctrl, int value) {} virtual void pitchWheel(int channel, int wheel) {} virtual void progChange(int channel, int pgm) {} virtual void sysEx(std::vector<unsigned char>& message) {} enum MidiStatus { // channel voice messages MIDI_NOTE_OFF = 0x80, MIDI_NOTE_ON = 0x90, MIDI_CONTROL_CHANGE = 0xB0, MIDI_PROGRAM_CHANGE = 0xC0, MIDI_PITCH_BEND = 0xE0, MIDI_AFTERTOUCH = 0xD0, // aka channel pressure MIDI_POLY_AFTERTOUCH = 0xA0, // aka key pressure MIDI_CLOCK = 0xF8, MIDI_START = 0xFA, MIDI_CONT = 0xFB, MIDI_STOP = 0xFC, MIDI_SYSEX_START = 0xF0, MIDI_SYSEX_STOP = 0xF7 }; enum MidiCtrl { ALL_NOTES_OFF = 123, ALL_SOUND_OFF = 120 }; enum MidiNPN { PITCH_BEND_RANGE = 0 }; }; A pure interface for MIDI handlers that can send/receive MIDI messages to/from midi objects is defined: struct midi_interface { virtual void addMidiIn(midi* midi_dsp) = 0; virtual void removeMidiIn(midi* midi_dsp) = 0; virtual ~midi_interface() {} }; A midi_hander subclass implements actual MIDI decoding and maintains a list of MIDI aware components (classes inheriting from midi and ready to send and/or receive MIDI events) using the addMidiIn/removeMidiIn methods: class midi_handler : public midi, public midi_interface { protected: std::vector<midi*> fMidiInputs; std::string fName; MidiNRPN fNRPN; public: midi_handler(const std::string& name = \"MIDIHandler\"):fName(name) {} virtual ~midi_handler() {} void addMidiIn(midi* midi_dsp) {...} void removeMidiIn(midi* midi_dsp) {...} ... ... }; Several concrete implementations subclassing midi_handler using native APIs have been written and can be found in the faust/midi folder: Depending on the native MIDI API being used, event timestamps are either expressed in absolute time or in frames. They are converted to offsets expressed in samples relative to the beginning of the audio buffer. Connected with the MidiUI class (a subclass of UI ), they allow a given DSP to be controlled with incoming MIDI messages or possibly send MIDI messages when its internal control state changes. In the following piece of code, a MidiUI object is created and connected to a rt_midi MIDI messages handler (using the RTMidi library), then given as a parameter to the standard buildUserInterface to control DSP parameters: ... rt_midi midi_handler(\"MIDI\"); MidiUI midi_interface(&midi_handler); DSP->buildUserInterface(&midi_interface); ... UI Architecture Modules A UI architecture module links user actions (i.e., 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\u2019s values according to user actions. This association is triggered by the 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: an UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout. A Faust UI architecture module derives the UI base class: template <typename REAL> struct UIReal { UIReal() {} virtual ~UIReal() {} // -- widget's layouts virtual void openTabBox(const char* label) = 0; virtual void openHorizontalBox(const char* label) = 0; virtual void openVerticalBox(const char* label) = 0; virtual void closeBox() = 0; // -- active widgets virtual void addButton(const char* label, REAL* zone) = 0; virtual void addCheckButton(const char* label, REAL* zone) = 0; virtual void addVerticalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addHorizontalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addNumEntry(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; // -- passive widgets virtual void addHorizontalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; virtual void addVerticalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) = 0; // -- metadata declarations virtual void declare(REAL* zone, const char* key, const char* val) {} }; struct UI : public UIReal<FAUSTFLOAT> { UI() {} virtual ~UI() {} }; The FAUSTFLOAT* zone element is the primary connection point between the control interface and the dsp code. The compiled dsp Faust code will give access to all internal control value addresses used by the dsp code by calling the approriate addButton , addVerticalSlider , addNumEntry etc. methods (depending of what is described in the original Faust DSP source code). The control/UI code keeps those addresses, and will typically change their pointed values each time a control value in the dsp code has to be changed. On the dsp side, all control values are sampled once at the beginning of the compute method, so that to keep the same value during the entire audio buffer. Writing and reading the control values is typically done in two different threads: the controller (a GUI, an OSC or MIDI.etc. one) write the values, and the audio real-time thread read them in the audio callback. Since writing/reading the FAUSTFLOAT* zone element is atomic, there is no need (in general) of complex synchronization mechanism between the writer (controller) and the reader (the Faust dsp object). Here is part of the UI classes hierarchy: Active Widgets Active widgets are graphical elements controlling a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double ). Active widgets in Faust are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values. Passive Widgets Passive widgets are graphical elements reflecting values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value. Passive widgets in Faust are HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type. 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. Metadata The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT* zone, const char* key, const char* value); Here is the table of currently supported general medadata: Key Value tooltip actual string content hidden 0 or 1 unit Hz or dB scale log or exp style knob or led or numerical style radio{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} style menu{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Here acc means accelerometer and gyr means gyroscope , both use the same parameters (a mapping description) but are linked to different sensors. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\u2019white noise\u2019:0;\u2019pink noise\u2019:1;\u2019sine\u2019:2}][hidden:0]\", 0, 20, 100, 1) or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) When one or several metadata are added in the same item label, then will appear in the generated code as one or successives declare(FAUSTFLOAT* zone, const char* key, const char* value); lines before the line describing the item itself. Thus the UI managing code has to associate them with the proper item. Look at the MetaDataUI class for an example of this technique. MIDI specific metadata are described here and are decoded the MidiUI class. Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for example) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future and can possibly be adapted for a specific project. They can be decoded using the MetaDataUI class. Graphic-oriented, pure controllers, code generator UI Even if the UI architecture module is graphic-oriented, a given implementation can perfectly choose to ignore all layout information and only keep the controller ones, like the buttons, sliders, nentries, bargraphs. This is typically what is done in the MidiUI or OSCUI architectures. Note that pure code generator can also be written. The JSONUI UI architecture is an example of an architecture generating the DSP JSON description as a text file. DSP JSON Description The full description of a given compiled DSP can be generated as a JSON file, to be used at several places in the architecture system. This JSON describes the DSP with its inputs/outputs number, some metadata (filename, name, used compilation parameters, used libraries etc.) as well as its UI with a hierarchy of groups up to terminal items ( buttons , sliders , nentries , bargraphs ) with all their parameters ( type , label , shortname , address , meta , init , min , max and step values). For the following DSP program: import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq = hslider(\"freq [unit:Hz]\", 600, 20, 2000, 1); process = vgroup(\"Oscillator\", os.osc(freq) * vol) <: (_,_); The generated JSON file is then: { \"name\": \"foo\", \"filename\": \"foo.dsp\", \"version\": \"2.40.8\", \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\", \"library_list\": [], \"include_pathnames\": [\"/usr/local/share/faust\"], \"inputs\": 0, \"outputs\": 2, \"meta\": [ { \"basics.lib/name\": \"Faust Basic Element Library\" }, { \"basics.lib/version\": \"0.6\" }, { \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\" }, { \"filename\": \"foo.dsp\" }, { \"maths.lib/author\": \"GRAME\" }, { \"maths.lib/copyright\": \"GRAME\" }, { \"maths.lib/license\": \"LGPL with exception\" }, { \"maths.lib/name\": \"Faust Math Library\" }, { \"maths.lib/version\": \"2.5\" }, { \"name\": \"tes\" }, { \"oscillators.lib/name\": \"Faust Oscillator Library\" }, { \"oscillators.lib/version\": \"0.3\" }, { \"platform.lib/name\": \"Generic Platform Library\" }, { \"platform.lib/version\": \"0.2\" }, { \"signals.lib/name\": \"Faust Signal Routing Library\" }, { \"signals.lib/version\": \"0.1\" } ], \"ui\": [ { \"type\": \"vgroup\", \"label\": \"Oscillator\", \"items\": [ { \"type\": \"hslider\", \"label\": \"freq\", \"shortname\": \"freq\", \"address\": \"/Oscillator/freq\", \"meta\": [ { \"unit\": \"Hz\" } ], \"init\": 600, \"min\": 20, \"max\": 2000, \"step\": 1 }, { \"type\": \"hslider\", \"label\": \"volume\", \"shortname\": \"volume\", \"address\": \"/Oscillator/volume\", \"meta\": [ { \"unit\": \"dB\" } ], \"init\": 0, \"min\": -96, \"max\": 0, \"step\": 0.1 } ] } ] } The JSON file can be generated with faust -json foo.dsp command, or programmatically using the JSONUI UI architecture (see next Some Useful UI Classes and Tools for Developers section). Here is the description of ready-to-use UI classes, followed by classes to be used in developer code: GUI Builders Here is the description of the main GUI classes: the GTKUI class uses the GTK toolkit to create a Graphical User Interface with a proper group-based layout the QTUI class uses the QT toolkit to create a Graphical User Interface with a proper group based layout the JuceUI class uses the JUCE framework to create a Graphical User Interface with a proper group based layout Non-GUI Controllers Here is the description of the main non-GUI controller classes: the OSCUI class implements OSC remote control in both directions the httpdUI class implements HTTP remote control using the libmicrohttpd library to embed a HTTP server inside the application. Then by opening a browser on a specific URL, the GUI will appear and allow to control the distant application or plugin. The connection works in both directions the MIDIUI class implements MIDI control in both directions, and it explained more deeply later on Some Useful UI Classes and Tools for Developers Some useful UI classes and tools can possibly be reused in developer code: the MapUI class establishes a mapping beween UI items and their labels , shortname or paths , and offers a setParamValue/getParamValue API to set and get their values. It uses an helper PathBuilder class to create complete shortnames and pathnames to the leaves in the UI hierarchy. Note that the item path encodes the UI hierarchy in the form of a /group1/group2/.../label string and is the way to distinguish control that may have the same label, but different localisation in the UI tree. Using shortnames (built so that they never collide) is an alternative way to access items. The setParamValue/getParamValue API takes either labels , shortname or paths as the way to describe the control, but using shortnames or paths is the safer way to use it the extended APIUI offers setParamValue/getParamValue API similar to MapUI , with additional methods to deal with accelerometer/gyroscope kind of metadata the MetaDataUI class decodes all currently supported metadata and can be used to retrieve their values the JSONUI class allows us to generate the JSON description of a given DSP the JSONUIDecoder class is used to decode the DSP JSON description and implement its buildUserInterface and metadata methods the FUI class allows us to save and restore the parameters state as a text file the SoundUI class with the associated Soundfile class is used to implement the soundfile primitive, and load the described audio resources (typically audio files), by using different concrete implementations, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). Paths to sound files can be absolute, but it should be noted that a relative path mechanism can be set up when creating an instance of SoundUI , in order to load sound files with a more flexible strategy. the ControlSequenceUI class with the associated OSCSequenceReader class allow to control parameters change in time, using the OSC time tag format. Changing the control values will have to be mixed with audio rendering. Look at the sndfile.cpp use-case. the ValueConverter file contains several mapping classes used to map user interface values (for example a gui slider delivering values between 0 and 1) to Faust values (for example a vslider between 20 and 2000) using linear/log/exp scales. It also provides classes to handle the [acc:a b c d e] and [gyr:a b c d e] Sensors Control Metadatas . Multi-Controller and Synchronization A given DSP can perfectly be controlled by several UI classes at the same time, and they will all read and write the same DSP control memory zones. Here is an example of code using a GUI using GTKUI architecture, as well as OSC control using OSCUI : ... GTKUI gtk_interface(name, &argc, &argv); DSP->buildUserInterface(&gtk_interface); OSCUI osc_interface(name, argc, argv); DSP->buildUserInterface(&osc_interface); ... Since several controller access the same values, you may have to synchronize them, in order for instance to have the GUI sliders or buttons reflect the state that would have been changed by the OSCUI controller at reception time, of have OSC messages been sent each time UI items like sliders or buttons are moved. This synchronization mecanism is implemented in a generic way in the GUI class. First the uiItemBase class is defined as the basic synchronizable memory zone, then grouped in a list controlling the same zone from different GUI instances. The uiItemBase::modifyZone method is used to change the uiItemBase state at reception time, and uiItemBase::reflectZone will be called to reflect a new value, and can change the Widget layout for instance, or send a message (OSC, MIDI...). All classes needing to use this synchronization mechanism will have to subclass the GUI class, which keeps all of them at runtime in a static class GUI::fGuiList variable. This is the case for the previously used GTKUI and OSCUI classes. Note that when using the GUI class, the 2 following static class variables have to be defined in the code, (once in one .cpp file in the project) like in this code example: // Globals std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; Finally the static GUI::updateAllGuis() synchronization method will have to be called regularly, in the application or plugin event management loop, or in a periodic timer for instance. This is typically implemented in the GUI::run method which has to be called to start event or messages processing. In the following code, the OSCUI::run method is called first to start processing OSC messages, then the blocking GTKUI::run method, which opens the GUI window, to be closed to finally finish the application: ... // Start OSC messages processing osc_interface.run(); // Start GTK GUI as the last one, since it blocks until the opened window is closed gtk_interface.run() ... DSP Architecture Modules The Faust compiler produces a DSP module whose format will depend of the chosen backend: a C++ class with the -lang cpp option, a data structure with associated functions with the -lang c option, an LLVM IR module with the -lang llvm option, a WebAssembly binary module with the -lang wasm option, a bytecode stream with the -lang interp option... and so on. The Base dsp Class In C++, the generated class derives from a base dsp class: class dsp { public: dsp() {} virtual ~dsp() {} /* Return instance number of audio inputs */ virtual int getNumInputs() = 0; /* Return instance number of audio outputs */ virtual int getNumOutputs() = 0; /** * Trigger the ui_interface parameter with instance specific calls * to 'openTabBox', 'addButton', 'addVerticalSlider'... in order to build the UI. * * @param ui_interface - the user interface builder */ virtual void buildUserInterface(UI* ui_interface) = 0; /* Return the sample rate currently used by the instance */ virtual int getSampleRate() = 0; /** * Global init, calls the following methods: * - static class 'classInit': static tables initialization * - 'instanceInit': constants and instance state initialization * * @param sample_rate - the sampling rate in Hz */ virtual void init(int sample_rate) = 0; /** * Init instance state * * @param sample_rate - the sampling rate in Hz */ virtual void instanceInit(int sample_rate) = 0; /** * Init instance constant state * * @param sample_rate - the sampling rate in HZ */ virtual void instanceConstants(int sample_rate) = 0; /* Init default control parameters values */ virtual void instanceResetUserInterface() = 0; /* Init instance state (like delay lines..) but keep the control parameter values */ virtual void instanceClear() = 0; /** * Return a clone of the instance. * * @return a copy of the instance on success, otherwise a null pointer. */ virtual dsp* clone() = 0; /** * Trigger the Meta* parameter with instance specific calls to 'declare' * (key, value) metadata. * * @param m - the Meta* meta user */ virtual void metadata(Meta* m) = 0; /** * DSP instance computation, to be called with successive in/out audio buffers. * * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * */ virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; /** * Alternative DSP instance computation method for use by subclasses, incorporating an additional `date_usec` parameter, * which specifies the timestamp of the first sample in the audio buffers. * * @param date_usec - the timestamp in microsec given by audio driver. By convention timestamp of -1 means 'no timestamp conversion', * events already have a timestamp expressed in frames. * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * */ virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; }; The dsp class is central to the Faust architecture design: the getNumInputs , getNumOutputs methods provides information about the signal processor the buildUserInterface method creates the user interface using a given UI class object (see later) the init method (and some more specialized methods like instanceInit , instanceConstants , etc.) is called to initialize the dsp object with a given sampling rate, typically obtained from the audio architecture the compute method is called by the audio architecture to execute the actual audio processing. It takes a count number of samples to process, and inputs and outputs arrays of non-interleaved float/double samples, to be allocated and handled by the audio driver with the required dsp input and outputs channels (as given by getNumInputs and getNumOutputs ) the clone method can be used to duplicate the instance the metadata(Meta* m) method can be called with a Meta object to decode the instance global metadata (see next section) (note that FAUSTFLOAT label is typically defined to be the actual type of sample: either float or double using #define FAUSTFLOAT float in the code for instance). For a given compiled DSP program, the compiler will generate a mydsp subclass of dsp and fill the different methods (the actual name can be changed using the -cn option). For dynamic code producing backends like the LLVM IR, Cmajor or the Interpreter ones, the actual code (an LLVM module, a Cmajor module or a bytecode stream) is actually wrapped by some additional C++ code glue, to finally produces an llvm_dsp typed object (defined in the llvm-dsp.h file), a cmajorpatch_dsp typed object (defined in the cmajorpatch-dsp.h file) or an interpreter_dsp typed object (defined in interpreter-dsp.h file), ready to be used with the UI and audio C++ classes (like the C++ generated class). See the following class diagram: Global DSP metadata All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler, for instance the Faust program: declare name \"NoiseProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; import(\"stdfaust.lib\"); process = no.noise; will generate the following C++ metadata(Meta* m) method in the dsp class: void metadata(Meta* m) { m->declare(\"author\", \"MySelf\"); m->declare(\"compile_options\", \"-lang cpp -es 1 -scal -ftz 0\"); m->declare(\"copyright\", \"MyCompany\"); m->declare(\"filename\", \"metadata.dsp\"); m->declare(\"license\", \"BSD\"); m->declare(\"name\", \"NoiseProgram\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); m->declare(\"version\", \"1.00\"); } which interacts with an instance of an implementation class of the following virtual Meta class: struct Meta { virtual ~Meta() {}; virtual void declare(const char* key, const char* value) = 0; }; and are part of three different types of global metadata: metadata like compile_options or filename are automatically generated metadata like author of copyright are part of the Global Medata metadata like noises.lib/name are part of the Function Metadata Specialized subclasses of the Meta class can be implemented to decode the needed key/value pairs for a given use-case. Macro Construction of DSP Components The Faust program specification is usually entirely done in the language itself. But in some specific cases it may be useful to develop separated DSP components and combine them in a more complex setup. Since taking advantage of the huge number of already available UI and audio architecture files is important, keeping the same dsp API is preferable, so that more complex DSP can be controlled and audio rendered the usual way. Extended DSP classes will typically subclass the dsp base class and override or complete part of its API. DSP Decorator Pattern A dsp_decorator class, subclass of the root dsp class has first been defined. Following the decorator design pattern, it allows behavior to be added to an individual object, either statically or dynamically. As an example of the decorator pattern, the timed_dsp class allows to decorate a given DSP with sample accurate control capability or the mydsp_poly class for polyphonic DSPs, explained in the next sections. Combining DSP Components A few additional macro construction classes, subclasses of the root dsp class have been defined in the dsp-combiner.h header file with a five operators construction API: the dsp_sequencer class combines two DSP in sequence, assuming that the number of outputs of the first DSP equals the number of input of the second one. It somewhat mimics the sequence (that is : ) operator of the language by combining two separated C++ objects. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSPs can be individually controlled. Its compute method is overloaded to call each DSP compute in sequence, using an intermediate output buffer produced by first DSP as the input one given to the second DSP. the dsp_parallelizer class combines two DSP in parallel. It somewhat mimics the parallel (that is , ) operator of the language by combining two separated C++ objects. Its getNumInputs/getNumOutputs methods are overloaded by correctly reflecting the input/output of the resulting DSP as the sum of the two combined ones. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSP can be individually controlled. Its compute method is overloaded to call each DSP compute, where each DSP consuming and producing its own number of input/output audio buffers taken from the method parameters. This methology is followed to implement the three remaining composition operators ( split , merge , recursion ), which ends up with a C++ API to combine DSPs with the usual five operators: createDSPSequencer , createDSPParallelizer , createDSPSplitter , createDSPMerger , createDSPRecursiver to be used at C++ level to dynamically combine DSPs. And finally the createDSPCrossfader tool allows you to crossfade between two DSP modules. The crossfade parameter (as a slider) controls the mix between the two modules outputs. When Crossfade = 1 , the first DSP only is computed, when Crossfade = 0 , the second DSP only is computed, otherwise both DSPs are computed and mixed. Note that this idea of decorating or combining several C++ dsp objects can perfectly be extended in specific projects, to meet other needs: like muting some part of a graph of several DSPs for instance. But keep in mind that keeping the dsp API then allows to take profit of all already available UI and audio based classes. Sample Accurate Control DSP audio languages usually deal with several timing dimensions when treating control events and generating audio samples. For performance reasons, systems maintain separated audio rate for samples generation and control rate for asynchronous messages handling. The audio stream is most often computed by blocks, and control is updated between blocks. To smooth control parameter changes, some languages chose to interpolate parameter values between blocks. In some cases control may be more finely interleaved with audio rendering, and some languages simply choose to interleave control and sample computation at sample level. Although the Faust language permits the description of sample level algorithms (i.e., like recursive filters, etc.), Faust generated DSP are usually computed by blocks. Underlying audio architectures give a fixed size buffer over and over to the DSP compute method which consumes and produces audio samples. Control to DSP Link In the current version of the Faust generated code, the primary connection point between the control interface and the DSP code is simply a memory zone. For control inputs, the architecture layer continuously write values in this zone, which is then sampled by the DSP code at the beginning of the compute method, and used with the same values throughout the call. Because of this simple control/DSP connexion mechanism, the most recent value is used by the DSP code. Similarly for control outputs , the DSP code inside the compute method possibly writes several values at the same memory zone, and the last value only will be seen by the control architecture layer when the method finishes. Although this behaviour is satisfactory for most use-cases, some specific usages need to handle the complete stream of control values with sample accurate timing. For instance keeping all control messages and handling them at their exact position in time is critical for proper MIDI clock synchronisation. Timestamped Control The first step consists in extending the architecture control mechanism to deal with timestamped control events. Note that this requires the underlying event control layer to support this capability. The native MIDI API for instance is usually able to deliver timestamped MIDI messages. The next step is to keep all timestamped events in a time ordered data structure to be continuously written by the control side, and read by the audio side. Finally the sample computation has to take account of all queued control events, and correctly change the DSP control state at successive points in time. Slices Based DSP Computation With timestamped control messages, changing control values at precise sample indexes on the audio stream becomes possible. A generic slices based DSP rendering strategy has been implemented in the timed_dsp class. A ring-buffer is used to transmit the stream of timestamped events from the control layer to the DSP one. In the case of MIDI control for instance, the ring-buffer is written with a pair containing the timestamp expressed in samples (or microseconds) and the actual MIDI message each time one is received. In the DSP compute method, the ring-buffer will be read to handle all messages received during the previous audio block. Since control values can change several times inside the same audio block, the DSP compute cannot be called only once with the total number of frames and the complete inputs/outputs audio buffers. The following strategy has to be used: several slices are defined with control values changing between consecutive slices all control values having the same timestamp are handled together, and change the DSP control internal state. The slice is computed up to the next control parameters timestamp until the end of the given audio block is reached in the next figure, four slices with the sequence of c1, c2, c3, c4 frames are successively given to the DSP compute method, with the appropriate part of the audio input/output buffers. Control values (appearing here as [v1,v2,v3] , then [v1,v3] , then [v1] , then [v1,v2,v3] sets) are changed between slices Since timestamped control messages from the previous audio block are used in the current block, control messages are aways handled with one audio buffer latency. Note that this slices based computation model can always be directly implemented on top of the underlying audio layer, without relying on the timed_dsp wrapper class. Audio driver timestamping Some audio drivers can get the timestamp of the first sample in the audio buffers, and will typically call the DSP alternative compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) function with the correct timestamp. By convention timestamp of -1 means 'no timestamp conversion', events already have a timestamp expressed in frames (see jackaudio_midi for an example driver using timestamp expressed in frames). The timed_dsp wrapper class is an example of a DSP class actually using the timestamp information. Typical Use-Case A typical Faust program can use the MIDI clock command signal to possibly compute the Beat Per Minutes (BPM) information for any synchronization need it may have. Here is a simple example of a sinusoid generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"stdfaust.lib\"); // square signal (1/0), changing state // at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled // with MIDI start/stop messages play = checkbox(\"On/Off [midi:start][midi:stop]\"); // detect front front(x) = (x-x\u2019) != 0.0; // count number of peaks during one second freq(x) = (x-x@ma.SR) : + ~ _; process = os.osc(8*freq(front(clocker))) * play; Each received group of 24 clocks will move the time position by exactly one beat. Then it is absolutely mandatory to never loose any MIDI clock message and the standard memory zone based model with the use the last received control value semantic is not adapted. The DSP object that needs to be controlled using the sample-accurate machinery can then simply be decorated using the timed_dsp class with the following kind of code: dsp* sample_accurate_dsp = new timed_dsp(DSP); Note that the described sample accurate MIDI clock synchronization model can currently only be used at input level. Because of the simple memory zone based connection point between the control interface and the DSP code, output controls (like bargraph) cannot generate a stream of control values. Thus a reliable MIDI clock generator cannot be implemented with the current approach. Polyphonic Instruments Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping. Polyphonic ready DSP Code By convention Faust architecture files with polyphonic capabilities expect to find control parameters named freq , gain , and gate . The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the freq parameter (which should be a frequency) will be automatically computed from MIDI note numbers, gain (which should be a value between 0 and 1) from velocity and gate from keyon/keyoff events. Thus, gate can be used as a trigger signal for any envelope generator, etc. Using the mydsp_poly Class The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the poly-dsp.h file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp* objects, manage dynamic voice allocation, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold as a subclass of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global Polyphonic tabgroup. The first tab contains a Voices group, a master like component used to change parameters on all voices at the same time, with a Panic button to be used to stop running voices, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI , httpdUI , etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used. The polyphonic instrument allocation takes the DSP to be used for one voice, the desired number of voices, the dynamic voice allocation state, and the group state which controls if separated voices are displayed or not: dsp* poly = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: dsp* poly = new mydsp_poly(dsp, 8, false, true); Polyphonic Instrument With a Global Output Effect Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is generally not a good idea since it would be instantiated for each voice which would be very inefficient. A convention has been defined to use the effect = some effect; line in the DSP source code. The actual effect definition has to be extracted from the DSP code, compiled separately, and then combined using the dsp_sequencer class previously presented to connect the polyphonic DSP in sequence with a unique global effect, with something like: dsp* poly = new dsp_sequencer(new mydsp_poly(dsp, 2, true, true), new effect()); | Some helper classes like the base dsp_poly_factory class, and concrete implementations llvm_dsp_poly_factory when using the LLVM backend or interpreter_dsp_poly_factory when using the Interpreter backend can also be used to automatically handle the voice and effect part of the DSP. Controlling the Polyphonic Instrument The mydsp_poly class is also ready for MIDI control (as a class implementing the midi interface) and can react to keyOn/keyOff and pitchWheel events. Other MIDI control parameters can directly be added in the DSP source code as MIDI metadata. To receive MIDI events, the created polyphonic DSP will be automatically added to the midi_handler object when calling buildUserInterface on a MidiUI object. Deploying the Polyphonic Instrument Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. faustcaqt -midi -noices 12 inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. Polyphonic ready faust2xx scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready-to-use DSP. Custom Memory Manager In C and C++, the Faust compiler produces a class (or a struct in C), to be instantiated to create each DSP instance. The standard generation model produces a flat memory layout, where all fields (scalar and arrays) are simply consecutive in the generated code (following the compilation order). So the DSP is allocated on a single block of memory, either on the stack or the heap depending on the use-case. The following DSP program: import(\"stdfaust.lib\"); gain = hslider(\"gain\", 0.5, 0, 1, 0.01); feedback = hslider(\"feedback\", 0.8, 0, 1, 0.01); echo(del_sec, fb, g) = + ~ de.delay(50000, del_samples) * fb * g with { del_samples = del_sec * ma.SR; }; process = echo(1.6, 0.6, 0.7), echo(0.7, feedback, gain); will have the flat memory layout: int IOTA0; int fSampleRate; int iConst1; float fRec0[65536]; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float fRec1[65536]; So scalar fHslider0 and fHslider1 correspond to the gain and feedback controllers. The iConst1 and iConst2 values are typically computed once at init time using the dynamically given the fSampleRate value, and used in the DSP loop later on. The fRec0 and fRec1 arrays are used for the recursive delays and finally the shared IOTA0 index is used to access them. Here is the generated compute function: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; float fSlow0 = float(fHslider0) * float(fHslider1); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 65535] = float(input0[i0]) + 0.419999987f * fRec0[(IOTA0 - iConst1) & 65535]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 65535]); fRec1[IOTA0 & 65535] = float(input1[i0]) + fSlow0 * fRec1[(IOTA0 - iConst2) & 65535]; output1[i0] = FAUSTFLOAT(fRec1[IOTA0 & 65535]); IOTA0 = IOTA0 + 1; } } The -mem option On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. The first remark is that scalar values will typically stay in the DSP structure, and the point is to move the big array buffers ( fRec0 and fRec1 in the example) into separated memory blocks. The -mem (--memory-manager) option can be used to generate adapted code. On the previous DSP program, we now have the following generated C++ code: int IOTA0; int fSampleRate; int iConst1; float* fRec0; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float* fRec1; The two fRec0 and fRec1 arrays are becoming pointers, and will be allocated elsewhere. An external memory manager is needed to interact with the DSP code. The proposed model does the following: in a first step the generated C++ code will inform the memory allocator about its needs in terms of 1) number of separated memory zones, with 2) their size 3) access characteristics, like number of Read and Write for each frame computation. This is done be generating an additional static memoryInfo method with the complete information available, the memory manager can then define the best strategy to allocate all separated memory zones an additional memoryCreate method is generated to allocate each of the separated zones an additional memoryDestroy method is generated to deallocate each of the separated zones Here is the API for the memory manager: struct dsp_memory_manager { virtual ~dsp_memory_manager() {} /** * Inform the Memory Manager with the number of expected memory zones. * @param count - the number of memory zones */ virtual void begin(size_t count); /** * Give the Memory Manager information on a given memory zone. * @param size - the size in bytes of the memory zone * @param reads - the number of Read access to the zone used to compute one frame * @param writes - the number of Write access to the zone used to compute one frame */ virtual void info(size_t size, size_t reads, size_t writes) {} /** * Inform the Memory Manager that all memory zones have been described, * to possibly start a 'compute the best allocation strategy' step. */ virtual void end(); /** * Allocate a memory zone. * @param size - the memory zone size in bytes */ virtual void* allocate(size_t size) = 0; /** * Destroy a memory zone. * @param ptr - the memory zone pointer to be deallocated */ virtual void destroy(void* ptr) = 0; }; A class static member is added in the mydsp class, to be set with an concrete memory manager later on: dsp_memory_manager* mydsp::fManager = nullptr; The C++ generated code now contains a new memoryInfo method, which interacts with the memory manager: static void memoryInfo() { fManager->begin(3); // mydsp fManager->info(56, 9, 1); // fRec0 fManager->info(262144, 2, 1); // fRec1 fManager->info(262144, 2, 1); fManager->end(); } The begin method is first generated to inform that three separated memory zones will be needed. Then three consecutive calls to the info method are generated, one for the DSP object itself, one for each recursive delay array. The end method is then called to finish the memory layout description, and let the memory manager prepare the actual allocations. Note that the memory layout information is also available in the JSON file generated using the -json option, to possibly be used statically by the architecture machinery (that is at compile time). With the previous program, the memory layout section is: \"memory_layout\": [ { \"name\": \"mydsp\", \"type\": \"kObj_ptr\", \"size\": 0, \"size_bytes\": 56, \"read\": 9, \"write\": 1 }, { \"name\": \"IOTA0\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 7, \"write\": 1 }, { \"name\": \"iConst1\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec0\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 }, { \"name\": \"iConst2\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec1\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 } ] Finally the memoryCreate and memoryDestroy methods are generated. The memoryCreate method asks the memory manager to allocate the fRec0 and fRec1 buffers: void memoryCreate() { fRec0 = static_cast<float*>(fManager->allocate(262144)); fRec1 = static_cast<float*>(fManager->allocate(262144)); } And the memoryDestroy method asks the memory manager to destroy them: virtual memoryDestroy() { fManager->destroy(fRec0); fManager->destroy(fRec1); } Additional static create/destroy methods are generated: static mydsp* create() { mydsp* dsp = new (fManager->allocate(sizeof(mydsp))) mydsp(); dsp->memoryCreate(); return dsp; } static void destroy(dsp* dsp) { static_cast<mydsp*>(dsp)->memoryDestroy(); fManager->destroy(dsp); } Note that the so-called C++ placement new will be used to allocate the DSP object itself. Static tables When rdtable or rwtable primitives are used in the source code, the C++ class will contain a table shared by all instances of the class. By default, this table is generated as a static class array, and so allocated in the application global static memory. Taking the following DSP example: process = (waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable), (waveform {1.1,2.2,3.3,4.4,5.5,6.6,7.7}, %(7)~+(3) : rdtable); Here is the generated code in default mode: ... static int itbl0mydspSIG0[7]; static float ftbl1mydspSIG1[7]; class mydsp : public dsp { ... public: ... static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(); sig0->instanceInitmydspSIG0(sample_rate); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(); sig1->instanceInitmydspSIG1(sample_rate); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0); deletemydspSIG1(sig1); } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are static global arrays. They are filled in the classInit method. The architecture code will typically call the init method (which calls classInit ) on a given DSP, to allocate class related arrays and the DSP itself. If several DSPs are going to be allocated, calling classInit only once then the instanceInit method on each allocated DSP is the way to go. In the -mem mode, the generated C++ code is now: ... static int* itbl0mydspSIG0 = 0; static float* ftbl1mydspSIG1 = 0; class mydsp : public dsp { ... public: ... static dsp_memory_manager* fManager; static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(fManager); sig0->instanceInitmydspSIG0(sample_rate); itbl0mydspSIG0 = static_cast<int*>(fManager->allocate(28)); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(fManager); sig1->instanceInitmydspSIG1(sample_rate); ftbl1mydspSIG1 = static_cast<float*>(fManager->allocate(28)); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0, fManager); deletemydspSIG1(sig1, fManager); } static void classDestroy() { fManager->destroy(itbl0mydspSIG0); fManager->destroy(ftbl1mydspSIG1); } virtual void init(int sample_rate) {} virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are generated as static global pointers. The classInit method uses the fManager object used to allocate tables. A new classDestroy method is generated to deallocate the tables. Finally the init method is now empty, since the architecture file is supposed to use the classInit/classDestroy method once to allocate and deallocate static tables, and the instanceInit method on each allocated DSP. The memoryInfo method now has the following shape, with the two itbl0mydspSIG0 and ftbl1mydspSIG1 tables: static void memoryInfo() { fManager->begin(6); // mydspSIG0 fManager->info(4, 0, 0); // itbl0mydspSIG0 fManager->info(28, 1, 0); // mydspSIG1 fManager->info(4, 0, 0); // ftbl1mydspSIG1 fManager->info(28, 1, 0); // mydsp fManager->info(28, 0, 0); // iRec0 fManager->info(8, 3, 2); fManager->end(); } Defining and using a custom memory manager When compiled with the -mem option, the client code has to define an adapted memory_manager class for its specific needs. A cutom memory manager is implemented by subclassing the dsp_memory_manager abstract base class, and defining the begin , end , \u00ecnfo , allocate and destroy methods. Here is an example of a simple heap allocating manager (implemented in the dummy-mem.cpp architecture file): struct malloc_memory_manager : public dsp_memory_manager { virtual void begin(size_t count) { // TODO: use \u2018count\u2019 } virtual void end() { // TODO: start sorting the list of memory zones, to prepare // for the future allocations done in memoryCreate() } virtual void info(size_t size, size_t reads, size_t writes) { // TODO: use 'size', \u2018reads\u2019 and \u2018writes\u2019 // to prepare memory layout for allocation } virtual void* allocate(size_t size) { // TODO: refine the allocation scheme to take // in account what was collected in info return calloc(1, size); } virtual void destroy(void* ptr) { // TODO: refine the allocation scheme to take // in account what was collected in info free(ptr); } }; The specialized malloc_memory_manager class can now be used the following way: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // \u2018Placement new\u2019 and 'memoryCreate' are used inside the \u2018create\u2019 method dsp* DSP = mydsp::create(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // 'memoryDestroy' and memory manager 'destroy' are used to deallocate memory mydsp::destroy(); // Done once after the last DSP has been destroyed mydsp::classDestroy(); Note that the client code can still choose to allocate/deallocate the DSP instance using the regular C++ new/delete operators: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // Use regular C++ new dsp* DSP = new mydsp(); /// Allocate internal buffers DSP->memoryCreate(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP->memoryDestroy(); // Use regular C++ delete delete DSP; // Done once after the last DSP has been destroyed mydsp::classDestroy(); Or even on the stack with: ... // Allocation on the stack mydsp DSP; // Allocate internal buffers DSP.memoryCreate(); // Init the DSP instance DSP.instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP.memoryDestroy(); ... More complex custom memory allocators can be developed by refining this malloc_memory_manager example, possibly defining real-time memory allocators...etc... The OWL architecture file uses a custom OwlMemoryManager . Allocating several DSP instances In a multiple instances scheme, static data structures shared by all instances have to be allocated once at beginning using mydsp::classInit , and deallocated at the end using mydsp::classDestroy . Individual instances are then allocated with mydsp::create() and deallocated with mydsp::destroy() , possibly directly using regular new/delete , or using stack allocation as explained before. Measuring the DSP CPU The measure_dsp class defined in the faust/dsp/dsp-bench.h file allows to decorate a given DSP object and measure its compute method CPU consumption. Results are given in Megabytes/seconds (higher is better) and DSP CPU at 44,1 kHz. Here is a C++ code example of its use: static void bench(dsp* dsp, const string& name) { // Init the DSP dsp->init(48000); // Wraps it with a 'measure_dsp' decorator measure_dsp mes(dsp, 1024, 5); // Measure the CPU use mes.measure(); // Returns the Megabytes/seconds and relative standard deviation values std::pair<double, double> res = mes.getStats(); // Print the stats cout << name << \" MBytes/sec : \" << res.first << \" \" << \"(DSP CPU % : \" << (mes.getCPULoad() * 100) << \")\" << endl; } Defined in the faust/dsp/dsp-optimizer.h file, the dsp_optimizer class uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU. Here is a C++ code example of its use: static void dynamic_bench(const string& in_filename) { // Init the DSP optimizer with the in_filename to compile dsp_optimizer optimizer(in_filename, 0, nullptr, \"\", 1024); // Discover the best set of parameters tuple<double, double, double, TOption> res = optimizer.findOptimizedParameters(); cout << \"Best value for '\" << in_filename << \"' is : \" << get<0>(res) << \" MBytes/sec with \"; for (size_t i = 0; i < get<3>(res).size(); i++) { cout << get<3>(res)[i] << \" \"; } cout << endl; } This class can typically be used in tools that help developers discover the best Faust compilation parameters for a given DSP program, like the faustbench and faustbench-llvm tools. The Proxy DSP Class In some cases, a DSP may run outside of the application or plugin context, like on another machine. The proxy_dsp class allows to create a proxy DSP that will be finally connected to the real one (using an OSC or HTTP based machinery for instance), and will reflect its behaviour. It uses the previously described JSONUIDecoder class. Then the proxy_dsp can be used in place of the real DSP, and connected with UI controllers using the standard buildUserInterface to control it. The faust-osc-controller tool demonstrates this capability using an OSC connection between the real DSP and its proxy. The proxy_osc_dsp class implements a specialized proxy_dsp using the liblo OSC library to connect to a OSC controllable DSP (which is using the OSCUI class and running in another context or machine). Then the faust-osc-controller program creates a real GUI (using GTKUI in this example) and have it control the remote DSP and reflect its dynamic state (like vumeter values coming back from the real DSP). Embedded Platforms Faust has been targeting an increasing number of embedded platforms for real-time audio signal processing applications in recent years. It can now be used to program microcontrollers (i.e., ESP32 , Teensy , Pico DSP and Daisy ), mobile platforms, embedded Linux systems (i.e., Bela and Elk ), Digital Signal Processors (DSPs), and more. Specialized architecture files and faust2xx scripts have been developed. Metadata Naming Convention A specific question arises when dealing with devices without or limited screen to display any GUI, and a set of physical knobs or buttons to be connected to control parameters. The standard way is then to use metadata in control labels. Since beeing able to use the same DSP file on all devices is always desirable, a common set of metadata has been defined: [switch:N] is used to connect to switch buttons [knob:N] is used to connect to knobs A extended set of metadata will probably have to be progressively defined and standardized. Using the -uim Compiler Option On embedded platforms with limited capabilities, using the -uim option can be helpful. The C/C++ generated code then contains a static description of several caracteristics of the DSP, like the number of audio inputs/outputs , the number of controls inputs/outputs , and macros feed with the controls parameters (label, DSP field name, init, min, max, step) that can be implemented in the architecture file for various needs. For example the following DSP program: process = _*hslider(\"Gain\", 0, 0, 1, 0.01) : hbargraph(\"Vol\", 0, 1); compiled with faust -uim foo.dsp gives this additional section: #ifdef FAUST_UIMACROS #define FAUST_FILE_NAME \"foo.dsp\" #define FAUST_CLASS_NAME \"mydsp\" #define FAUST_INPUTS 1 #define FAUST_OUTPUTS 1 #define FAUST_ACTIVES 1 #define FAUST_PASSIVES 1 FAUST_ADDHORIZONTALSLIDER(\"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f); FAUST_ADDHORIZONTALBARGRAPH(\"Vol\", fHbargraph0, 0.0f, 1.0f); #define FAUST_LIST_ACTIVES(p) \\ p(HORIZONTALSLIDER, Gain, \"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f) \\ #define FAUST_LIST_PASSIVES(p) \\ p(HORIZONTALBARGRAPH, Vol, \"Vol\", fHbargraph0, 0.0, 0.0f, 1.0f, 0.0) \\ #endif The FAUST_ADDHORIZONTALSLIDER or FAUST_ADDHORIZONTALBARGRAPH macros can then be implemented to do whatever is needed with the Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f and \"Vol\", fHbargraph0, 0.0f, 1.0f parameters respectively. The more sophisticated FAUST_LIST_ACTIVES and FAUST_LIST_PASSIVES macros can possibly be used to call any p function (defined elsewhere in the architecture file) on each item. The minimal-static.cpp file demonstrates this feature. Developing a New Architecture File Developing a new architecture file typically means writing a generic file, that will be populated with the actual output of the Faust compiler, in order to produce a complete file, ready-to-be-compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the <<includeIntrinsic>> and <<includeclass>> lines that will be recognized by the Faust compiler, and replaced by the generated code. Here is an example in C++, but the same logic can be used with other languages producing textual outputs, like C, Cmajor, Rust or Dlang. Look at the minimal.cpp example located in the architecture folder: #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #include \"faust/dsp/one-sample-dsp.h\" // To be replaced by the compiler generated C++ class <<includeIntrinsic>> <<includeclass>> int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", static_cast<dsp*>(&DSP)); // Render buffers... audio.start(); audio.stop(); } Calling faust -a minimal.cpp noise.dsp -o noise.cpp will produce a ready to compile noise.cpp file: /* ------------------------------------------------------------ name: \"noise\" Code generated with Faust 2.28.0 (https://faust.grame.fr) Compilation options: -lang cpp -scal -ftz 0 ------------------------------------------------------------ */ #ifndef __mydsp_H__ #define __mydsp_H__ #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #include <algorithm> #include <cmath> #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif #ifdef __APPLE__ #define exp10f __exp10f #define exp10 __exp10 #endif class mydsp : public dsp { private: FAUSTFLOAT fHslider0; int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"filename\", \"noise.dsp\"); m->declare(\"name\", \"noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fHslider0 = FAUSTFLOAT(0.5f); } virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"noise\"); ui_interface->addHorizontalSlider(\"Volume\", &fHslider0, 0.5, 0.0, 1.0, 0.001); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = (4.65661287e-10f * float(fHslider0)); for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((fSlow0 * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); } Generally, several files to connect to the audio layer, controller layer, and possibly other (MIDI, OSC...) have to be used. One of them is the main file and include the others. The -i option can be added to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with faust ) to produce a single self-contained unique file. Then a faust2xxx script has to be written to chain the Faust compilation step and the C++ compilation one (and possibly others). Look at the Developing a faust2xx Script section. Adapting the Generated DSP Developing the adapted C++ file may require aggregating the generated mydsp class (subclass of the dsp base class defined in faust/dsp/dsp.h header) in the specific class, so something like the following would have to be written: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the fDSP 'compute' fDSP.compute(count, inputs, outputs); } // Do something specific }; or subclassing and extending it , so writing something like: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' mydsp::compute(count, inputs, outputs); } // Do something specific }; or decorating a DSP object using the decorator pattern , which is already implemented in this file , and can possibly be sub-classed like: class my_decorator : public decorator_dsp { private: // Do something specific public: my_decorator(dsp* dsp):decorator_dsp(dsp) { // Do something specific } virtual ~my_class() { // Do something specific } // Implementation of some of the methods // Override the 'instanceClear' method void instanceClear() { // Do something specific // Call the inherited 'instanceClear' decorator_dsp::instanceClear(); } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' decorator_dsp::compute(count, inputs, outputs); } // Do something specific }; // Decorates a concrete instance my_decorator DSP = new my_decorator(new mydsp()); ... Developing New UI Architectures For really new architectures, the UI base class, the GenericUI helper class or the GUI class (described before), have to be subclassed. Note that a lot of classes presented in the Some useful UI classes for developers section can also be subclassed or possibly enriched with additional code. Developing New Audio Architectures The audio base class has to be subclassed and each method implemented for the given audio hardware. In some cases the audio driver can adapt to the required number of DSP inputs/outputs (like the JACK audio system for instance which can open any number of virtual audio ports). But in general, the number of hardware audio inputs/outputs may not exactly match the DSP ones. This is the responsability of the audio driver to adapt to this situation. The dsp_adapter dsp decorator can help in this case. Developing a New Soundfile Loader Soundfiles are defined in the DSP program using the soundfile primitive . Here is a simple DSP program which uses a single tango.wav audio file and play it until its end: process = 0,_~+(1):soundfile(\"sound[url:{'tango.wav'}]\",2):!,!, The compiled C++ class has the following structure: class mydsp : public dsp { private: Soundfile* fSoundfile0; int iRec0[2]; int fSampleRate; .... with the Soundfile* fSoundfile0; field and its definition : struct Soundfile { void* fBuffers; // will correspond to a double** or float** pointer chosen at runtime int* fLength; // length of each part (so fLength[P] contains the length in frames of part P) int* fSR; // sample rate of each part (so fSR[P] contains the SR of part P) int* fOffset; // offset of each part in the global buffer (so fOffset[P] contains the offset in frames of part P) int fChannels; // max number of channels of all concatenated files int fParts; // the total number of loaded parts bool fIsDouble; // keep the sample format (float or double) }; The following buildUserInterface method in generated, containing a addSoundfile method called with the appropriate parameters extracted from the soundfile(\"sound[url:{'tango.wav'}]\",2) piece of DSP code, to be used to load the tango.wav audio file and prepare the fSoundfile0 field: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tp0\"); ui_interface->addSoundfile(\"sound\", \"{'tango.wav'}\", &fSoundfile0); ui_interface->closeBox(); } The specialized SoundUI architecture file is then used to load the required soundfiles at DSP init time, by using a SoundfileReader object. It only implements the addSoundfile method which will load all needed audio files, create and fill the fSoundfile0 object. Different concrete implementations are already written, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). A new audio file loader can be written by subclassing the SoundfileReader class. A pure memory reader could be implemented for instance to load wavetables to be used as the soundfile URL list. Look at the template MemoryReader class, as an example to be completed, with the following methods to be implemented: /** * Check the availability of a sound resource. * * @param path_name - the name of the file, or sound resource identified this way * * @return true if the sound resource is available, false otherwise. */ virtual bool checkFile(const std::string& path_name); /** * Get the channels and length values of the given sound resource. * * @param path_name - the name of the file, or sound resource identified this way * @param channels - the channels value to be filled with the sound resource * number of channels * @param length - the length value to be filled with the sound resource length in frames * */ virtual void getParamsFile(const std::string& path_name, int& channels, int& length); /** * Read one sound resource and fill the 'soundfile' structure accordingly * * @param path_name - the name of the file, or sound resource identified this way * @param part - the part number to be filled in the soundfile * @param offset - the offset value to be incremented with the actual * sound resource length in frames * @param max_chan - the maximum number of mono channels to fill * */ virtual void readFile(Soundfile* soundfile, const std::string& path_name, int part, int& offset, int max_chan); Another example to look at is WaveReader . The SoundUI architecture is then used the following way: mydsp DSP; // Here using a compiled time chosen SoundfileReader SoundUI* sound_interface = new SoundUI(); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; The SoundfileReader object can be dynamically choosen by using an alternate version of the SoundUI constructor, possibly choosing the sample format to be double when the DSP code is compiled with the -double option: mydsp DSP; // Here using a dynamically chosen custom MyMemoryReader SoundfileReader* sound_reader = new MyMemoryReader(...); SoundUI* sound_interface = new SoundUI(\"\", false, sound_reader, true); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; Other Languages Than C++ Most of the architecture files have been developed in C++ over the years. Thus they are ready to be used with the C++ backend and the one that generate C++ wrapped modules (like the LLVM, Cmajor and Interpreter backends). For other languages, specific architecture files have to be written. Here is the current situation for other backends: the C backend needs additional CGlue.h and CInterface.h files, with the minimal-c file as a simple console mode example using them the Rust backend can be used with the minimal-rs architecture, the more complex JACK jack.rs used in faust2jackrust script, or the PortAudio portaudio.rs used in faust2portaudiorust script the experimental Dlang backend can be used with the minimal.d or the dplug.d to generate DPlug plugins with the faust2dplug script. the Julia backend can be used with the minimal.jl architecture or the portaudio.jl used in faust2portaudiojulia script. The faust2xx Scripts Using faust2xx Scripts The faust2xx scripts finally combine different architecture files to generate a ready-to-use application or plugin, etc... from a Faust DSP program. They typically combine the generated DSP with an UI architecture file and an audio architecture file. Most of the also have addition options like -midi , -nvoices <num> , -effect <auto|effect.dsp> or -soundfile to generate polyphonic instruments with or without effects, or audio file support. Look at the following page for a more complete description. Developing a faust2xx Script The faust2xx script are mostly written in bash (but any scripting language can be used) and aims to produce a ready-to-use application, plugin, etc... from a DSP program. A faust2minimal template script using the C++ backend, can be used to start the process. The helper scripts, faustpath , faustoptflags , and usage.sh can be used to setup common variables: # Define some common paths . faustpath # Define compilation flags . faustoptflags # Helper file to build the 'help' option . usage.sh CXXFLAGS+=\" $MYGCCFLAGS\" # So that additional CXXFLAGS can be used # The architecture file name ARCHFILE=$FAUSTARCH/minimal.cpp # Global variables OPTIONS=\"\" FILES=\"\" The script arguments then have to be analysed, compiler options are kept in the OPTIONS variable and all DSP files in the FILES one: #------------------------------------------------------------------- # dispatch command arguments #------------------------------------------------------------------- while [ $1 ] do p=$1 if [ $p = \"-help\" ] || [ $p = \"-h\" ]; then usage faust2minimal \"[options] [Faust options] <file.dsp>\" exit fi echo \"dispatch command arguments\" if [ ${p:0:1} = \"-\" ]; then OPTIONS=\"$OPTIONS $p\" elif [[ -f \"$p\" ]] && [ ${p: -4} == \".dsp\" ]; then FILES=\"$FILES $p\" else OPTIONS=\"$OPTIONS $p\" fi shift done Each DSP file is first compiled to C++ using the faust -a command and the appropriate architecture file, then to the final executable program, here using the C++ compiler: #------------------------------------------------------------------- # compile the *.dsp files #------------------------------------------------------------------- for f in $FILES; do # compile the DSP to c++ using the architecture file echo \"compile the DSP to c++ using the architecture file\" faust -i -a $ARCHFILE $OPTIONS \"$f\" -o \"${f%.dsp}.cpp\"|| exit # compile c++ to binary echo \"compile c++ to binary\" ( $CXX $CXXFLAGS \"${f%.dsp}.cpp\" -o \"${f%.dsp}\" ) > /dev/null || exit # remove tempory files rm -f \"${f%.dsp}.cpp\" # collect binary file name for FaustWorks BINARIES=\"$BINARIES${f%.dsp};\" done echo $BINARIES The existing faust2xx scripts can be used as examples. The faust2api Model This model combining the generated DSP the audio and UI architecture components is very convenient to automatically produce ready-to-use standalone application or plugins, since the controller part (GUI, MIDI or OSC...) is directly compiled and deployed. In some cases, developers prefer to control the DSP by creating a completely new GUI (using a toolkit not supported in the standard architecture files), or even without any GUI and using another control layer. A model that only combines the generated DSP with an audio architecture file to produce an audio engine has been developed (thus gluing the blue and red parts of the three color model explained at the beginning). A generic template class DspFaust has been written in the DspFaust.h and DspFaust.cpp files. This code contains conditional compilation sections to add and initialize the appropriate audio driver (written as a subclass of the previously described base audio class), and can produce audio generators , effects , of fully MIDI and sensor controllable pophyphonic instruments . The resulting audio engine contains start and stop methods to control audio processing. It also provides a set of functions like getParamsCount, setParamValue, getParamValue etc. to access all parameters (or the additional setVoiceParamValue method function to access a single voice in a polyphonic case), and let the developer adds his own GUI or any kind of controller. Look at the faust2api script, which uses the previously described architecture files, and provide a tool to easily generate custom APIs based on one or several Faust objects. Using the -inj Option With faust2xx Scripts The compiler -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. Two examples of use are presented next. Using the template-llvm.cpp architecture The first one demonstrates how faust2xx scripts can become more dynamic by loading and compiling an arbitrary DSP at runtime. This is done using the template-llvm.cpp architecture file which uses the libfaust library and the LLVM backend to dynamically compile a foo.dsp file. So instead of producing a static binary based on a given DSP, the resulting program will be able to load and compile a DSP at runtime. This template-llvm.cpp can be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application, ready to be used to load and compile a DSP, and run it with the CoreAudio audio layer and GTK as the GUI freamework. Then faust2cagtk-llvm will ask for a DSP to compile: ./faust2cagtk-llvm <Enter a foo.dsp file> A generic polyphonic (8 voices) and MIDI controllable version can be compiled using: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp (a dummy DSP) Note that the resulting binary keeps its own control options, like: ./faust2cagtk-llvm -h ./faust2cagtk-llvm [--frequency <val>] [--buffer <val>] [--nvoices <val>] [--control <0/1>] [--group <0/1>] [--virtual-midi <0/1>] So now ./faust2cagtk-llvm --nvoices 16 starts the program with 16 voices. The technique has currently be tested with the faust2cagtk , faust2jack , faust2csvplot , and faust2plot tools. Second use-case computing the spectrogram of a set of audio files Here is a second use case where some external C++ code is used to compute the spectrogram of a set of audio files (which is something that cannot be simply done with the current version fo the Faust language) and output the spectrogram as an audio signal. A nentry controller will be used to select the currently playing spectrogram. The Faust compiler will be used to generate a C++ class which is going to be manually edited and enriched with additional code. Writting the DSP code First a fake DSP program spectral.dsp using the soundfile primitive loading two audio files and a nentry control is written: sf = soundfile(\"sound[url:{'sound1.wav';'sound2.wav'}]\",2); process = (hslider(\"Spectro\", 0, 0, 1, 1),0) : sf : !,!,_,_; The point of explicitly using soundfile primitive and a nentry control is to generate a C++ file with a prefilled DSP structure (containing the fSoundfile0 and fHslider0 fields) and code inside the buildUserInterface method. Compiling it manually with the following command: faust spectral.dsp -cn spectral -o spectral.cpp produces the following C++ code containing the spectral class: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectrogram\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); .... } }; Customizing the C++ code Now the spectral class can be manually edited and completed with additional code, to compute the two audio files spectrograms in buildUserInterface , and play them in compute . a new line Spectrogram fSpectro[2]; is added in the DSP structure a createSpectrogram(fSoundfile0, fSpectro); function is added in buildUserInterface and used to compute and fill the two spectrograms, by reading the two loaded audio files in fSoundfile0 part of the generated code in compute is removed and replaced by new code to play one of spectrograms (selected with the fHslider0 control in the GUI) using a playSpectrogram(fSpectro, count, iSlow0, outputs); function: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; Spectrogram fSpectro[2]; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectro\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); // Read 'fSoundfile0' and fill 'fSpectro' createSpectrogram(fSoundfile0, fSpectro); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); // Play 'fSpectro' indexed by 'iSlow0' by writting 'count' samples in 'outputs' playSpectrogram(fSpectro, count, iSlow0, outputs); } }; Here we assume that createSpectrogram and playSpectrogram functions are defined elsewhere and ready to be compiled. Deploying it as a Max/MSP External Using the faust2max6 Script The completed spectral.cpp file is now ready to be deployed as a Max/MSP external using the faust2max6 script and the -inj option with the following line: faust2max6 -inj spectral.cpp -soundfile spectral.dsp The two needed sound1.wav and sound2.wav audio files are embedded in the generated external, loaded at init time (since the buildUserInterface method is automatically called), and the manually added C++ code will be executed to compute the spectrograms and play them. Finally by respecting the naming coherency for the fake spectral.dsp DSP program, the generated spectral.cpp C++ file, the automatically generated spectral.maxpat Max/MSP patch will be able to build the GUI with a ready-to-use slider. Additional Ressources Several external projects are providing tools to arrange the way Faust source code is generated or used, in different languages. Preprocessing tools fpp fpp is a standalone Perl script with no dependencies which allows ANY C/C++ code in a Faust .dsp file as long as you are targeting C/C++ in scalar mode. C++ tools Using and adapting the dsp/UI/audio model in a more sophisticated way, or integrating Faust generated C++ classes in others frameworks (like JUCE). faust2hpp Convert Faust code to a header-only standalone C++ library. A collection of header files is generated as the output. A class is provided from which a DSP object can be built with methods in the style of JUCE DSP objects. faustpp A post-processor for Faust, which allows to generate with more flexibility. This is a source transformation tool based on the Faust compiler. It permits to arrange the way how Faust source is generated with greater flexibility. cookiecutter-dpf-faust A cookiecutter project template for DISTRHO plugin framework audio effect plugins using Faust for the implementation of the DSP pipeline. faustmd Static metadata generator for Faust/C++. This program builds the metadata for a Faust DSP ahead of time, rather than dynamically. The result is a block of C++ code which can be appended to the code generation. FaustCPPConverter Eyal Amir tool to facilitate the use of Faust generated C++ code in JUCE projects. JOSModules and josm_faust Julius Smith projects to facilitate the use of Faust generated C++ code in JUCE projects. Arduino tools An alternative way to use the ESP32 board with Faust, possibly easier and more versatile than the examples mentioned on the esp32 tutorial . Cmajor tools Using Faust in Cmajor A tutorial to show how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. RNBO tools Using Faust in RNBO with codebox~ A tutorial to show how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DLang tools Faust 2 Dplug Guide Explains how to use Faust in a Dplug project. Dplug Faust Example This is an example plugin using Dplug with a Faust backend. It is a stereo reverb plugin using the Freeverb demo from the Faust library. Julia tools Faust.jl Julia wrapper for the Faust compiler. Uses the Faust LLVM C API. Using Faust in Julia A tutorial to show how Faust can be used with Julia , a high-level, general-purpose dynamic programming language with features well suited for numerical analysis and computational science. Python tools FAUSTPy FAUSTPy is a Python wrapper for the FAUST DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust Ctypes A port of Marc Joliet's FaustPy from CFFI to Ctypes. Faust-Ctypes documentation is available online . An SCons Tool for FAUST This is an SCons tool for compiling FAUST programs. It adds various builders to your construction environment: Faust, FaustXML, FaustSVG, FaustSC, and FaustHaskell. Their behaviour can be modified by changing various construction variables (see \"Usage\" below). Faustwatch At the moment there is one tool present, faustwatch.py. Faustwatch is a tool that observes a .dsp file used by the dsp language Faust. faustWidgets Creates interactive widgets inside jupyter notebooks from Faust dsp files and produces a (customizable) plot. Faust Synth This is an example project for controlling a synth, programmed and compiled with Faust, through a Python script. The synth runs as a JACK client on Linux systems and the output is automatically recorded by jack_capture. DawDreamer DawDreamer is an audio-processing Python framework supporting Faust and Faust's Box API. ode2dsp ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Finite difference equations (FDEs) are rendered to Faust code. faustlab A exploratory project to wrap the Faust interpreter for use by python via the following wrapping frameworks using the RtAudio cross-platform audio driver: cyfaust: cython (faust c++ interface) cfaustt: cython (faust c interface) pyfaust: pybind11 (faust c++ interface) nanobind: nanobind (faust c++ interface) cyfaust A cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. Rust tools rust-faust A better integration of Faust for Rust. It allows to build the DSPs via build.rs and has some abstractions to make it much easier to work with params and meta of the DSPs. Faust egui Proof of concept of drawing a UI with egui and rust-faust . RustFaustExperiments Tools to compare C++ and Rust code generated from Faust. fl-tui Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs Another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. lowpass-lr4-faust-nih-plug A work-in-progress project to integrate Faust generated Rust code with NIH-plug . nih-faust-jit A plugin to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project. WebAssembly tools faust-loader Import Faust .dsp files, and get back an AudioWorklet or ScriptProcessor node. faust2cpp2wasm A drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend. Faust Compiler Microservice This is a microservice that serves a single purpose: compiling Faust code that is sent to it into WebAssembly that can then be loaded and run natively from within the web synth application. It is written in go because go is supposed to be good for this sort of thing. mosfez-faust Makes dynamic compilation of Faust on the web a little easier, and has a dev project to run values through dsp offline, and preview dsp live. It's an opinionated version of some parts of Faust for webaudio , mostly just the Web Assembly Faust compiler, wrapped up in a library with additional features. faust-wap2-playground Playground and template for Faust-based web audio experiments. Dart tools flutter_faust_ffi A basic flutter app as a proof of concept utilizing Faust's C API export with Dart's ffi methods to create cross-platform plug-ins.","title":"Architecture Files"},{"location":"manual/architectures/#architecture-files","text":"A Faust program describes a signal processor , a pure DSP computation that maps input signals to output signals . It says nothing about audio drivers or controllers (like GUI, OSC, MIDI, sensors) that are going to control the DSP. This additional 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 controllers interfaces to be used. This approach allows a single Faust program to be easily deployed to a large variety of audio standards (e.g., Max/MSP externals, PD externals, VST plugins, CoreAudio applications, JACK applications, iPhone/Android, etc.): The architecture to be used is specified at compile time with the -a option. For example faust -a jack-gtk.cpp foo.dsp indicates to use the JACK GTK architecture when compiling foo.dsp . Some of these architectures are a modular combination of an audio module and one or more controller modules . Some architecture only combine an audio module with the generated DSP to create an audio engine to be controlled with an additional setParamValue/getParamValue kind of API, so that the controller part can be completeley defined externally. This is the purpose of the faust2api script explained later on.","title":"Architecture Files"},{"location":"manual/architectures/#minimal-structure-of-an-architecture-file","text":"Before going into the details of the architecture files provided with Faust distribution, it is important to have an idea of the essential parts that compose an architecture file. Technically, an architecture file is any text file with two placeholders <<includeIntrinsic>> and <<includeclass>> . The first placeholder is currently not used, and the second one is replaced by the code generated by the FAUST compiler. Therefore, the really minimal architecture file, let's call it nullarch.cpp , is the following: <<includeIntrinsic>> <<includeclass>> This nullarch.cpp architecture has the property that faust foo.dsp and faust -a nullarch.cpp foo.dsp produce the same result. Obviously, this is not very useful, moreover the resulting cpp file doesn't compile. Here is miniarch.cpp , a minimal architecture file that contains enough information to produce a cpp file that can be successfully compiled: <<includeIntrinsic>> #define FAUSTFLOAT float class dsp {}; struct Meta { virtual void declare(const char* key, const char* value) {}; }; struct Soundfile {}; struct UI { // -- widget's layouts virtual void openTabBox(const char* label) {} virtual void openHorizontalBox(const char* label) {} virtual void openVerticalBox(const char* label) {} virtual void closeBox() {} // -- active widgets virtual void addButton(const char* label, FAUSTFLOAT* zone) {} virtual void addCheckButton(const char* label, FAUSTFLOAT* zone) {} virtual void addVerticalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addHorizontalSlider(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} virtual void addNumEntry(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) {} // -- passive widgets virtual void addHorizontalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} virtual void addVerticalBargraph(const char* label, FAUSTFLOAT* zone, FAUSTFLOAT min, FAUSTFLOAT max) {} // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) {} // -- metadata declarations virtual void declare(FAUSTFLOAT* zone, const char* key, const char* val) {} }; <<includeclass>> This architecture is still not very useful, but it gives an idea of what a real-life architecture file has to implement, in addition to the audio part itself. As we will see in the next section, Faust architectures are implemented using a modular approach to avoid code duplication and favor code maintenance and reuse.","title":"Minimal Structure of an Architecture File"},{"location":"manual/architectures/#audio-architecture-modules","text":"A Faust generated program has to connect to a underlying audio layer. Depending if the final program is a application or plugin, the way to connect to this audio layer will differ: applications typically use the OS audio driver API, which will be CoreAudio on macOS, ALSA on Linux, WASAPI on Windows for instance, or any kind of multi-platforms API like PortAudio or JACK . In this case a subclass of the base class audio (see later) has to be written plugins (like VST3 , Audio Unit or JUCE for instance) usually have to follow a more constrained API which imposes a life cyle , something like loading/initializing/starting/running/stopping/unloading sequence of operations. In this case the Faust generated module new/init/compute/delete methods have to be inserted in the plugin API, by calling each module function at the appropriate place.","title":"Audio Architecture Modules"},{"location":"manual/architectures/#external-and-internal-audio-sample-formats","text":"Audio samples are managed by the underlying audio layer, typically as 32 bits float or 64 bits double values in the [-1..1] interval. Their format is defined with the FAUSTFLOAT macro implemented in the architecture file as float by default. The DSP audio samples format is choosen at compile time, with the -single (= default), -double or -quad compilation option. Control parameters like buttons, sliders... also use the FAUSTFLOAT format. By default, the FAUSTFLOAT macro is written with the following code: #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif which gives it a value ( if not already defined ), and since the default internal format is float , nothing special has to be done in the general case. But when the DSP is compiled using the -double option, the audio inputs/outputs buffers have to be adapted , with a dsp_sample_adapter class, for instance like in the dynamic-jack-gt tool . Note that an architecture may redefine FAUSTFLOAT in double, and have the complete audio chain running in double. This has to be done before including any architecture file that would define FAUSTFLOAT itself (because of the #ifndef logic).","title":"External and internal audio sample formats"},{"location":"manual/architectures/#connection-to-an-audio-driver-api","text":"An audio driver architecture typically connects a Faust program to the audio drivers. It is responsible for: allocating and releasing the audio channels and presenting the audio as non-interleaved float/double data (depending of the FAUSTFLOAT macro definition), normalized between -1.0 and 1.0 calling the DSP init method at init time, to setup the ma.SR variable possibly used in the DSP code calling the DSP compute method to handle incoming audio buffers and/or to produce audio outputs. The default compilation model uses separated audio input and output buffers not referring to the same memory locations. The -inpl (--in-place) code generation model allows us to generate code working when input and output buffers are the same (which is typically needed in some embedded devices). This option currently only works in scalar (= default) code generation mode. A Faust audio architecture module derives from an audio class can be defined as below (simplified version, see the real version here) : class audio { public: audio() {} virtual ~audio() {} /** * Init the DSP. * @param name - the DSP name to be given to the audio driven * (could appear as a JACK client for instance) * @param dsp - the dsp that will be initialized with the driver sample rate * * @return true is sucessful, false if case of driver failure. **/ virtual bool init(const char* name, dsp* dsp) = 0; /** * Start audio processing. * @return true is sucessfull, false if case of driver failure. **/ virtual bool start() = 0; /** * Stop audio processing. **/ virtual void stop() = 0; void setShutdownCallback(shutdown_callback cb, void* arg) = 0; // Return buffer size in frames. virtual int getBufferSize() = 0; // Return the driver sample rate in Hz. virtual int getSampleRate() = 0; // Return the driver hardware inputs number. virtual int getNumInputs() = 0; // Return the driver hardware outputs number. virtual int getNumOutputs() = 0; /** * @return Returns the average proportion of available CPU * being spent inside the audio callbacks (between 0.0 and 1.0). **/ virtual float getCPULoad() = 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. Here is the hierarchy of some of the supported audio drivers:","title":"Connection to an audio driver API"},{"location":"manual/architectures/#connection-to-a-plugin-audio-api","text":"In the case of plugin, an audio plugin architecture has to be developed, by integrating the Faust DSP new/init/compute/delete methods in the plugin API. Here is a concrete example using the JUCE framework: a FaustPlugInAudioProcessor class, subclass of the juce::AudioProcessor has to be defined. The Faust generated C++ instance will be created in its constructor, either in monophonic of polyphonic mode (see later sections) the Faust DSP instance is initialized in the JUCE prepareToPlay method using the current sample rate value the Faust dsp compute is called in the JUCE process which receives the audio inputs/outputs buffers to be processed additional methods can possibly be implemented to handle MIDI messages or save/restore the plugin parameters state for instance. This methodology obviously has to be adapted for each supported plugin API.","title":"Connection to a plugin audio API"},{"location":"manual/architectures/#midi-architecture-modules","text":"A MIDI architecture module typically connects a Faust program to the MIDI drivers. MIDI control connects DSP parameters with MIDI messages (in both directions), and can be used to trigger polyphonic instruments.","title":"MIDI Architecture Modules"},{"location":"manual/architectures/#midi-messages-in-the-dsp-source-code","text":"MIDI control messages are described as metadata in UI elements. They are decoded by a MidiUI class, subclass of UI , which parses incoming MIDI messages and updates the appropriate control parameters, or sends MIDI messages when the UI elements (sliders, buttons...) are moved.","title":"MIDI Messages in the DSP Source Code"},{"location":"manual/architectures/#defined-standard-midi-messages","text":"A special [midi:xxx yyy...] metadata needs to be added to the UI element. The full description of supported MIDI messages is part of the Faust documentation .","title":"Defined Standard MIDI Messages"},{"location":"manual/architectures/#midi-classes","text":"A midi base class defining MIDI messages decoding/encoding methods has been developed. It will be used to receive and transmit MIDI messages: class midi { public: midi() {} virtual ~midi() {} // Additional timestamped API for MIDI input virtual MapUI* keyOn(double, int channel, int pitch, int velocity) { return keyOn(channel, pitch, velocity); } virtual void keyOff(double, int channel, int pitch, int velocity = 0) { keyOff(channel, pitch, velocity); } virtual void keyPress(double, int channel, int pitch, int press) { keyPress(channel, pitch, press); } virtual void chanPress(double date, int channel, int press) { chanPress(channel, press); } virtual void pitchWheel(double, int channel, int wheel) { pitchWheel(channel, wheel); } virtual void ctrlChange(double, int channel, int ctrl, int value) { ctrlChange(channel, ctrl, value); } virtual void ctrlChange14bits(double, int channel, int ctrl, int value) { ctrlChange14bits(channel, ctrl, value); } virtual void rpn(double, int channel, int ctrl, int value) { rpn(channel, ctrl, value); } virtual void progChange(double, int channel, int pgm) { progChange(channel, pgm); } virtual void sysEx(double, std::vector<unsigned char>& message) { sysEx(message); } // MIDI sync virtual void startSync(double date) {} virtual void stopSync(double date) {} virtual void clock(double date) {} // Standard MIDI API virtual MapUI* keyOn(int channel, int pitch, int velocity) { return nullptr; } virtual void keyOff(int channel, int pitch, int velocity) {} virtual void keyPress(int channel, int pitch, int press) {} virtual void chanPress(int channel, int press) {} virtual void ctrlChange(int channel, int ctrl, int value) {} virtual void ctrlChange14bits(int channel, int ctrl, int value) {} virtual void rpn(int channel, int ctrl, int value) {} virtual void pitchWheel(int channel, int wheel) {} virtual void progChange(int channel, int pgm) {} virtual void sysEx(std::vector<unsigned char>& message) {} enum MidiStatus { // channel voice messages MIDI_NOTE_OFF = 0x80, MIDI_NOTE_ON = 0x90, MIDI_CONTROL_CHANGE = 0xB0, MIDI_PROGRAM_CHANGE = 0xC0, MIDI_PITCH_BEND = 0xE0, MIDI_AFTERTOUCH = 0xD0, // aka channel pressure MIDI_POLY_AFTERTOUCH = 0xA0, // aka key pressure MIDI_CLOCK = 0xF8, MIDI_START = 0xFA, MIDI_CONT = 0xFB, MIDI_STOP = 0xFC, MIDI_SYSEX_START = 0xF0, MIDI_SYSEX_STOP = 0xF7 }; enum MidiCtrl { ALL_NOTES_OFF = 123, ALL_SOUND_OFF = 120 }; enum MidiNPN { PITCH_BEND_RANGE = 0 }; }; A pure interface for MIDI handlers that can send/receive MIDI messages to/from midi objects is defined: struct midi_interface { virtual void addMidiIn(midi* midi_dsp) = 0; virtual void removeMidiIn(midi* midi_dsp) = 0; virtual ~midi_interface() {} }; A midi_hander subclass implements actual MIDI decoding and maintains a list of MIDI aware components (classes inheriting from midi and ready to send and/or receive MIDI events) using the addMidiIn/removeMidiIn methods: class midi_handler : public midi, public midi_interface { protected: std::vector<midi*> fMidiInputs; std::string fName; MidiNRPN fNRPN; public: midi_handler(const std::string& name = \"MIDIHandler\"):fName(name) {} virtual ~midi_handler() {} void addMidiIn(midi* midi_dsp) {...} void removeMidiIn(midi* midi_dsp) {...} ... ... }; Several concrete implementations subclassing midi_handler using native APIs have been written and can be found in the faust/midi folder: Depending on the native MIDI API being used, event timestamps are either expressed in absolute time or in frames. They are converted to offsets expressed in samples relative to the beginning of the audio buffer. Connected with the MidiUI class (a subclass of UI ), they allow a given DSP to be controlled with incoming MIDI messages or possibly send MIDI messages when its internal control state changes. In the following piece of code, a MidiUI object is created and connected to a rt_midi MIDI messages handler (using the RTMidi library), then given as a parameter to the standard buildUserInterface to control DSP parameters: ... rt_midi midi_handler(\"MIDI\"); MidiUI midi_interface(&midi_handler); DSP->buildUserInterface(&midi_interface); ...","title":"MIDI Classes"},{"location":"manual/architectures/#ui-architecture-modules","text":"A UI architecture module links user actions (i.e., 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\u2019s values according to user actions. This association is triggered by the 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: an UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout. A Faust UI architecture module derives the UI base class: template <typename REAL> struct UIReal { UIReal() {} virtual ~UIReal() {} // -- widget's layouts virtual void openTabBox(const char* label) = 0; virtual void openHorizontalBox(const char* label) = 0; virtual void openVerticalBox(const char* label) = 0; virtual void closeBox() = 0; // -- active widgets virtual void addButton(const char* label, REAL* zone) = 0; virtual void addCheckButton(const char* label, REAL* zone) = 0; virtual void addVerticalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addHorizontalSlider(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; virtual void addNumEntry(const char* label, REAL* zone, REAL init, REAL min, REAL max, REAL step) = 0; // -- passive widgets virtual void addHorizontalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; virtual void addVerticalBargraph(const char* label, REAL* zone, REAL min, REAL max) = 0; // -- soundfiles virtual void addSoundfile(const char* label, const char* filename, Soundfile** sf_zone) = 0; // -- metadata declarations virtual void declare(REAL* zone, const char* key, const char* val) {} }; struct UI : public UIReal<FAUSTFLOAT> { UI() {} virtual ~UI() {} }; The FAUSTFLOAT* zone element is the primary connection point between the control interface and the dsp code. The compiled dsp Faust code will give access to all internal control value addresses used by the dsp code by calling the approriate addButton , addVerticalSlider , addNumEntry etc. methods (depending of what is described in the original Faust DSP source code). The control/UI code keeps those addresses, and will typically change their pointed values each time a control value in the dsp code has to be changed. On the dsp side, all control values are sampled once at the beginning of the compute method, so that to keep the same value during the entire audio buffer. Writing and reading the control values is typically done in two different threads: the controller (a GUI, an OSC or MIDI.etc. one) write the values, and the audio real-time thread read them in the audio callback. Since writing/reading the FAUSTFLOAT* zone element is atomic, there is no need (in general) of complex synchronization mechanism between the writer (controller) and the reader (the Faust dsp object). Here is part of the UI classes hierarchy:","title":"UI Architecture Modules"},{"location":"manual/architectures/#active-widgets","text":"Active widgets are graphical elements controlling a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double ). Active widgets in Faust are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values.","title":"Active Widgets"},{"location":"manual/architectures/#passive-widgets","text":"Passive widgets are graphical elements reflecting values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value. Passive widgets in Faust are HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char* name, FAUSTFLOAT* zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type.","title":"Passive Widgets"},{"location":"manual/architectures/#widgets-layout","text":"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.","title":"Widgets Layout"},{"location":"manual/architectures/#metadata","text":"The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT* zone, const char* key, const char* value); Here is the table of currently supported general medadata: Key Value tooltip actual string content hidden 0 or 1 unit Hz or dB scale log or exp style knob or led or numerical style radio{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} style menu{\u2019label1\u2019:v1;\u2019label2\u2019:v2...} acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Here acc means accelerometer and gyr means gyroscope , both use the same parameters (a mapping description) but are linked to different sensors. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\u2019white noise\u2019:0;\u2019pink noise\u2019:1;\u2019sine\u2019:2}][hidden:0]\", 0, 20, 100, 1) or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) When one or several metadata are added in the same item label, then will appear in the generated code as one or successives declare(FAUSTFLOAT* zone, const char* key, const char* value); lines before the line describing the item itself. Thus the UI managing code has to associate them with the proper item. Look at the MetaDataUI class for an example of this technique. MIDI specific metadata are described here and are decoded the MidiUI class. Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for example) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future and can possibly be adapted for a specific project. They can be decoded using the MetaDataUI class.","title":"Metadata"},{"location":"manual/architectures/#graphic-oriented-pure-controllers-code-generator-ui","text":"Even if the UI architecture module is graphic-oriented, a given implementation can perfectly choose to ignore all layout information and only keep the controller ones, like the buttons, sliders, nentries, bargraphs. This is typically what is done in the MidiUI or OSCUI architectures. Note that pure code generator can also be written. The JSONUI UI architecture is an example of an architecture generating the DSP JSON description as a text file.","title":"Graphic-oriented, pure controllers, code generator UI"},{"location":"manual/architectures/#dsp-json-description","text":"The full description of a given compiled DSP can be generated as a JSON file, to be used at several places in the architecture system. This JSON describes the DSP with its inputs/outputs number, some metadata (filename, name, used compilation parameters, used libraries etc.) as well as its UI with a hierarchy of groups up to terminal items ( buttons , sliders , nentries , bargraphs ) with all their parameters ( type , label , shortname , address , meta , init , min , max and step values). For the following DSP program: import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq = hslider(\"freq [unit:Hz]\", 600, 20, 2000, 1); process = vgroup(\"Oscillator\", os.osc(freq) * vol) <: (_,_); The generated JSON file is then: { \"name\": \"foo\", \"filename\": \"foo.dsp\", \"version\": \"2.40.8\", \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\", \"library_list\": [], \"include_pathnames\": [\"/usr/local/share/faust\"], \"inputs\": 0, \"outputs\": 2, \"meta\": [ { \"basics.lib/name\": \"Faust Basic Element Library\" }, { \"basics.lib/version\": \"0.6\" }, { \"compile_options\": \"-lang cpp -es 1 -mcd 16 -single -ftz 0\" }, { \"filename\": \"foo.dsp\" }, { \"maths.lib/author\": \"GRAME\" }, { \"maths.lib/copyright\": \"GRAME\" }, { \"maths.lib/license\": \"LGPL with exception\" }, { \"maths.lib/name\": \"Faust Math Library\" }, { \"maths.lib/version\": \"2.5\" }, { \"name\": \"tes\" }, { \"oscillators.lib/name\": \"Faust Oscillator Library\" }, { \"oscillators.lib/version\": \"0.3\" }, { \"platform.lib/name\": \"Generic Platform Library\" }, { \"platform.lib/version\": \"0.2\" }, { \"signals.lib/name\": \"Faust Signal Routing Library\" }, { \"signals.lib/version\": \"0.1\" } ], \"ui\": [ { \"type\": \"vgroup\", \"label\": \"Oscillator\", \"items\": [ { \"type\": \"hslider\", \"label\": \"freq\", \"shortname\": \"freq\", \"address\": \"/Oscillator/freq\", \"meta\": [ { \"unit\": \"Hz\" } ], \"init\": 600, \"min\": 20, \"max\": 2000, \"step\": 1 }, { \"type\": \"hslider\", \"label\": \"volume\", \"shortname\": \"volume\", \"address\": \"/Oscillator/volume\", \"meta\": [ { \"unit\": \"dB\" } ], \"init\": 0, \"min\": -96, \"max\": 0, \"step\": 0.1 } ] } ] } The JSON file can be generated with faust -json foo.dsp command, or programmatically using the JSONUI UI architecture (see next Some Useful UI Classes and Tools for Developers section). Here is the description of ready-to-use UI classes, followed by classes to be used in developer code:","title":"DSP JSON Description"},{"location":"manual/architectures/#gui-builders","text":"Here is the description of the main GUI classes: the GTKUI class uses the GTK toolkit to create a Graphical User Interface with a proper group-based layout the QTUI class uses the QT toolkit to create a Graphical User Interface with a proper group based layout the JuceUI class uses the JUCE framework to create a Graphical User Interface with a proper group based layout","title":"GUI Builders"},{"location":"manual/architectures/#non-gui-controllers","text":"Here is the description of the main non-GUI controller classes: the OSCUI class implements OSC remote control in both directions the httpdUI class implements HTTP remote control using the libmicrohttpd library to embed a HTTP server inside the application. Then by opening a browser on a specific URL, the GUI will appear and allow to control the distant application or plugin. The connection works in both directions the MIDIUI class implements MIDI control in both directions, and it explained more deeply later on","title":"Non-GUI Controllers"},{"location":"manual/architectures/#some-useful-ui-classes-and-tools-for-developers","text":"Some useful UI classes and tools can possibly be reused in developer code: the MapUI class establishes a mapping beween UI items and their labels , shortname or paths , and offers a setParamValue/getParamValue API to set and get their values. It uses an helper PathBuilder class to create complete shortnames and pathnames to the leaves in the UI hierarchy. Note that the item path encodes the UI hierarchy in the form of a /group1/group2/.../label string and is the way to distinguish control that may have the same label, but different localisation in the UI tree. Using shortnames (built so that they never collide) is an alternative way to access items. The setParamValue/getParamValue API takes either labels , shortname or paths as the way to describe the control, but using shortnames or paths is the safer way to use it the extended APIUI offers setParamValue/getParamValue API similar to MapUI , with additional methods to deal with accelerometer/gyroscope kind of metadata the MetaDataUI class decodes all currently supported metadata and can be used to retrieve their values the JSONUI class allows us to generate the JSON description of a given DSP the JSONUIDecoder class is used to decode the DSP JSON description and implement its buildUserInterface and metadata methods the FUI class allows us to save and restore the parameters state as a text file the SoundUI class with the associated Soundfile class is used to implement the soundfile primitive, and load the described audio resources (typically audio files), by using different concrete implementations, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). Paths to sound files can be absolute, but it should be noted that a relative path mechanism can be set up when creating an instance of SoundUI , in order to load sound files with a more flexible strategy. the ControlSequenceUI class with the associated OSCSequenceReader class allow to control parameters change in time, using the OSC time tag format. Changing the control values will have to be mixed with audio rendering. Look at the sndfile.cpp use-case. the ValueConverter file contains several mapping classes used to map user interface values (for example a gui slider delivering values between 0 and 1) to Faust values (for example a vslider between 20 and 2000) using linear/log/exp scales. It also provides classes to handle the [acc:a b c d e] and [gyr:a b c d e] Sensors Control Metadatas .","title":"Some Useful UI Classes and Tools for Developers"},{"location":"manual/architectures/#multi-controller-and-synchronization","text":"A given DSP can perfectly be controlled by several UI classes at the same time, and they will all read and write the same DSP control memory zones. Here is an example of code using a GUI using GTKUI architecture, as well as OSC control using OSCUI : ... GTKUI gtk_interface(name, &argc, &argv); DSP->buildUserInterface(&gtk_interface); OSCUI osc_interface(name, argc, argv); DSP->buildUserInterface(&osc_interface); ... Since several controller access the same values, you may have to synchronize them, in order for instance to have the GUI sliders or buttons reflect the state that would have been changed by the OSCUI controller at reception time, of have OSC messages been sent each time UI items like sliders or buttons are moved. This synchronization mecanism is implemented in a generic way in the GUI class. First the uiItemBase class is defined as the basic synchronizable memory zone, then grouped in a list controlling the same zone from different GUI instances. The uiItemBase::modifyZone method is used to change the uiItemBase state at reception time, and uiItemBase::reflectZone will be called to reflect a new value, and can change the Widget layout for instance, or send a message (OSC, MIDI...). All classes needing to use this synchronization mechanism will have to subclass the GUI class, which keeps all of them at runtime in a static class GUI::fGuiList variable. This is the case for the previously used GTKUI and OSCUI classes. Note that when using the GUI class, the 2 following static class variables have to be defined in the code, (once in one .cpp file in the project) like in this code example: // Globals std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; Finally the static GUI::updateAllGuis() synchronization method will have to be called regularly, in the application or plugin event management loop, or in a periodic timer for instance. This is typically implemented in the GUI::run method which has to be called to start event or messages processing. In the following code, the OSCUI::run method is called first to start processing OSC messages, then the blocking GTKUI::run method, which opens the GUI window, to be closed to finally finish the application: ... // Start OSC messages processing osc_interface.run(); // Start GTK GUI as the last one, since it blocks until the opened window is closed gtk_interface.run() ...","title":"Multi-Controller and Synchronization"},{"location":"manual/architectures/#dsp-architecture-modules","text":"The Faust compiler produces a DSP module whose format will depend of the chosen backend: a C++ class with the -lang cpp option, a data structure with associated functions with the -lang c option, an LLVM IR module with the -lang llvm option, a WebAssembly binary module with the -lang wasm option, a bytecode stream with the -lang interp option... and so on.","title":"DSP Architecture Modules"},{"location":"manual/architectures/#the-base-dsp-class","text":"In C++, the generated class derives from a base dsp class: class dsp { public: dsp() {} virtual ~dsp() {} /* Return instance number of audio inputs */ virtual int getNumInputs() = 0; /* Return instance number of audio outputs */ virtual int getNumOutputs() = 0; /** * Trigger the ui_interface parameter with instance specific calls * to 'openTabBox', 'addButton', 'addVerticalSlider'... in order to build the UI. * * @param ui_interface - the user interface builder */ virtual void buildUserInterface(UI* ui_interface) = 0; /* Return the sample rate currently used by the instance */ virtual int getSampleRate() = 0; /** * Global init, calls the following methods: * - static class 'classInit': static tables initialization * - 'instanceInit': constants and instance state initialization * * @param sample_rate - the sampling rate in Hz */ virtual void init(int sample_rate) = 0; /** * Init instance state * * @param sample_rate - the sampling rate in Hz */ virtual void instanceInit(int sample_rate) = 0; /** * Init instance constant state * * @param sample_rate - the sampling rate in HZ */ virtual void instanceConstants(int sample_rate) = 0; /* Init default control parameters values */ virtual void instanceResetUserInterface() = 0; /* Init instance state (like delay lines..) but keep the control parameter values */ virtual void instanceClear() = 0; /** * Return a clone of the instance. * * @return a copy of the instance on success, otherwise a null pointer. */ virtual dsp* clone() = 0; /** * Trigger the Meta* parameter with instance specific calls to 'declare' * (key, value) metadata. * * @param m - the Meta* meta user */ virtual void metadata(Meta* m) = 0; /** * DSP instance computation, to be called with successive in/out audio buffers. * * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (eiher float, double or quad) * */ virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; /** * Alternative DSP instance computation method for use by subclasses, incorporating an additional `date_usec` parameter, * which specifies the timestamp of the first sample in the audio buffers. * * @param date_usec - the timestamp in microsec given by audio driver. By convention timestamp of -1 means 'no timestamp conversion', * events already have a timestamp expressed in frames. * @param count - the number of frames to compute * @param inputs - the input audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * @param outputs - the output audio buffers as an array of non-interleaved * FAUSTFLOAT samples (either float, double or quad) * */ virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; }; The dsp class is central to the Faust architecture design: the getNumInputs , getNumOutputs methods provides information about the signal processor the buildUserInterface method creates the user interface using a given UI class object (see later) the init method (and some more specialized methods like instanceInit , instanceConstants , etc.) is called to initialize the dsp object with a given sampling rate, typically obtained from the audio architecture the compute method is called by the audio architecture to execute the actual audio processing. It takes a count number of samples to process, and inputs and outputs arrays of non-interleaved float/double samples, to be allocated and handled by the audio driver with the required dsp input and outputs channels (as given by getNumInputs and getNumOutputs ) the clone method can be used to duplicate the instance the metadata(Meta* m) method can be called with a Meta object to decode the instance global metadata (see next section) (note that FAUSTFLOAT label is typically defined to be the actual type of sample: either float or double using #define FAUSTFLOAT float in the code for instance). For a given compiled DSP program, the compiler will generate a mydsp subclass of dsp and fill the different methods (the actual name can be changed using the -cn option). For dynamic code producing backends like the LLVM IR, Cmajor or the Interpreter ones, the actual code (an LLVM module, a Cmajor module or a bytecode stream) is actually wrapped by some additional C++ code glue, to finally produces an llvm_dsp typed object (defined in the llvm-dsp.h file), a cmajorpatch_dsp typed object (defined in the cmajorpatch-dsp.h file) or an interpreter_dsp typed object (defined in interpreter-dsp.h file), ready to be used with the UI and audio C++ classes (like the C++ generated class). See the following class diagram:","title":"The Base dsp Class"},{"location":"manual/architectures/#global-dsp-metadata","text":"All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler, for instance the Faust program: declare name \"NoiseProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; import(\"stdfaust.lib\"); process = no.noise; will generate the following C++ metadata(Meta* m) method in the dsp class: void metadata(Meta* m) { m->declare(\"author\", \"MySelf\"); m->declare(\"compile_options\", \"-lang cpp -es 1 -scal -ftz 0\"); m->declare(\"copyright\", \"MyCompany\"); m->declare(\"filename\", \"metadata.dsp\"); m->declare(\"license\", \"BSD\"); m->declare(\"name\", \"NoiseProgram\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); m->declare(\"version\", \"1.00\"); } which interacts with an instance of an implementation class of the following virtual Meta class: struct Meta { virtual ~Meta() {}; virtual void declare(const char* key, const char* value) = 0; }; and are part of three different types of global metadata: metadata like compile_options or filename are automatically generated metadata like author of copyright are part of the Global Medata metadata like noises.lib/name are part of the Function Metadata Specialized subclasses of the Meta class can be implemented to decode the needed key/value pairs for a given use-case.","title":"Global DSP metadata"},{"location":"manual/architectures/#macro-construction-of-dsp-components","text":"The Faust program specification is usually entirely done in the language itself. But in some specific cases it may be useful to develop separated DSP components and combine them in a more complex setup. Since taking advantage of the huge number of already available UI and audio architecture files is important, keeping the same dsp API is preferable, so that more complex DSP can be controlled and audio rendered the usual way. Extended DSP classes will typically subclass the dsp base class and override or complete part of its API.","title":"Macro Construction of DSP Components"},{"location":"manual/architectures/#dsp-decorator-pattern","text":"A dsp_decorator class, subclass of the root dsp class has first been defined. Following the decorator design pattern, it allows behavior to be added to an individual object, either statically or dynamically. As an example of the decorator pattern, the timed_dsp class allows to decorate a given DSP with sample accurate control capability or the mydsp_poly class for polyphonic DSPs, explained in the next sections.","title":"DSP Decorator Pattern"},{"location":"manual/architectures/#combining-dsp-components","text":"A few additional macro construction classes, subclasses of the root dsp class have been defined in the dsp-combiner.h header file with a five operators construction API: the dsp_sequencer class combines two DSP in sequence, assuming that the number of outputs of the first DSP equals the number of input of the second one. It somewhat mimics the sequence (that is : ) operator of the language by combining two separated C++ objects. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSPs can be individually controlled. Its compute method is overloaded to call each DSP compute in sequence, using an intermediate output buffer produced by first DSP as the input one given to the second DSP. the dsp_parallelizer class combines two DSP in parallel. It somewhat mimics the parallel (that is , ) operator of the language by combining two separated C++ objects. Its getNumInputs/getNumOutputs methods are overloaded by correctly reflecting the input/output of the resulting DSP as the sum of the two combined ones. Its buildUserInterface method is overloaded to group the two DSP in a tabgroup, so that control parameters of both DSP can be individually controlled. Its compute method is overloaded to call each DSP compute, where each DSP consuming and producing its own number of input/output audio buffers taken from the method parameters. This methology is followed to implement the three remaining composition operators ( split , merge , recursion ), which ends up with a C++ API to combine DSPs with the usual five operators: createDSPSequencer , createDSPParallelizer , createDSPSplitter , createDSPMerger , createDSPRecursiver to be used at C++ level to dynamically combine DSPs. And finally the createDSPCrossfader tool allows you to crossfade between two DSP modules. The crossfade parameter (as a slider) controls the mix between the two modules outputs. When Crossfade = 1 , the first DSP only is computed, when Crossfade = 0 , the second DSP only is computed, otherwise both DSPs are computed and mixed. Note that this idea of decorating or combining several C++ dsp objects can perfectly be extended in specific projects, to meet other needs: like muting some part of a graph of several DSPs for instance. But keep in mind that keeping the dsp API then allows to take profit of all already available UI and audio based classes.","title":"Combining DSP Components"},{"location":"manual/architectures/#sample-accurate-control","text":"DSP audio languages usually deal with several timing dimensions when treating control events and generating audio samples. For performance reasons, systems maintain separated audio rate for samples generation and control rate for asynchronous messages handling. The audio stream is most often computed by blocks, and control is updated between blocks. To smooth control parameter changes, some languages chose to interpolate parameter values between blocks. In some cases control may be more finely interleaved with audio rendering, and some languages simply choose to interleave control and sample computation at sample level. Although the Faust language permits the description of sample level algorithms (i.e., like recursive filters, etc.), Faust generated DSP are usually computed by blocks. Underlying audio architectures give a fixed size buffer over and over to the DSP compute method which consumes and produces audio samples.","title":"Sample Accurate Control"},{"location":"manual/architectures/#control-to-dsp-link","text":"In the current version of the Faust generated code, the primary connection point between the control interface and the DSP code is simply a memory zone. For control inputs, the architecture layer continuously write values in this zone, which is then sampled by the DSP code at the beginning of the compute method, and used with the same values throughout the call. Because of this simple control/DSP connexion mechanism, the most recent value is used by the DSP code. Similarly for control outputs , the DSP code inside the compute method possibly writes several values at the same memory zone, and the last value only will be seen by the control architecture layer when the method finishes. Although this behaviour is satisfactory for most use-cases, some specific usages need to handle the complete stream of control values with sample accurate timing. For instance keeping all control messages and handling them at their exact position in time is critical for proper MIDI clock synchronisation.","title":"Control to DSP Link"},{"location":"manual/architectures/#timestamped-control","text":"The first step consists in extending the architecture control mechanism to deal with timestamped control events. Note that this requires the underlying event control layer to support this capability. The native MIDI API for instance is usually able to deliver timestamped MIDI messages. The next step is to keep all timestamped events in a time ordered data structure to be continuously written by the control side, and read by the audio side. Finally the sample computation has to take account of all queued control events, and correctly change the DSP control state at successive points in time.","title":"Timestamped Control"},{"location":"manual/architectures/#slices-based-dsp-computation","text":"With timestamped control messages, changing control values at precise sample indexes on the audio stream becomes possible. A generic slices based DSP rendering strategy has been implemented in the timed_dsp class. A ring-buffer is used to transmit the stream of timestamped events from the control layer to the DSP one. In the case of MIDI control for instance, the ring-buffer is written with a pair containing the timestamp expressed in samples (or microseconds) and the actual MIDI message each time one is received. In the DSP compute method, the ring-buffer will be read to handle all messages received during the previous audio block. Since control values can change several times inside the same audio block, the DSP compute cannot be called only once with the total number of frames and the complete inputs/outputs audio buffers. The following strategy has to be used: several slices are defined with control values changing between consecutive slices all control values having the same timestamp are handled together, and change the DSP control internal state. The slice is computed up to the next control parameters timestamp until the end of the given audio block is reached in the next figure, four slices with the sequence of c1, c2, c3, c4 frames are successively given to the DSP compute method, with the appropriate part of the audio input/output buffers. Control values (appearing here as [v1,v2,v3] , then [v1,v3] , then [v1] , then [v1,v2,v3] sets) are changed between slices Since timestamped control messages from the previous audio block are used in the current block, control messages are aways handled with one audio buffer latency. Note that this slices based computation model can always be directly implemented on top of the underlying audio layer, without relying on the timed_dsp wrapper class.","title":"Slices Based DSP Computation"},{"location":"manual/architectures/#audio-driver-timestamping","text":"Some audio drivers can get the timestamp of the first sample in the audio buffers, and will typically call the DSP alternative compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) function with the correct timestamp. By convention timestamp of -1 means 'no timestamp conversion', events already have a timestamp expressed in frames (see jackaudio_midi for an example driver using timestamp expressed in frames). The timed_dsp wrapper class is an example of a DSP class actually using the timestamp information.","title":"Audio driver timestamping"},{"location":"manual/architectures/#typical-use-case","text":"A typical Faust program can use the MIDI clock command signal to possibly compute the Beat Per Minutes (BPM) information for any synchronization need it may have. Here is a simple example of a sinusoid generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"stdfaust.lib\"); // square signal (1/0), changing state // at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled // with MIDI start/stop messages play = checkbox(\"On/Off [midi:start][midi:stop]\"); // detect front front(x) = (x-x\u2019) != 0.0; // count number of peaks during one second freq(x) = (x-x@ma.SR) : + ~ _; process = os.osc(8*freq(front(clocker))) * play; Each received group of 24 clocks will move the time position by exactly one beat. Then it is absolutely mandatory to never loose any MIDI clock message and the standard memory zone based model with the use the last received control value semantic is not adapted. The DSP object that needs to be controlled using the sample-accurate machinery can then simply be decorated using the timed_dsp class with the following kind of code: dsp* sample_accurate_dsp = new timed_dsp(DSP); Note that the described sample accurate MIDI clock synchronization model can currently only be used at input level. Because of the simple memory zone based connection point between the control interface and the DSP code, output controls (like bargraph) cannot generate a stream of control values. Thus a reliable MIDI clock generator cannot be implemented with the current approach.","title":"Typical Use-Case"},{"location":"manual/architectures/#polyphonic-instruments","text":"Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping.","title":"Polyphonic Instruments"},{"location":"manual/architectures/#polyphonic-ready-dsp-code","text":"By convention Faust architecture files with polyphonic capabilities expect to find control parameters named freq , gain , and gate . The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the freq parameter (which should be a frequency) will be automatically computed from MIDI note numbers, gain (which should be a value between 0 and 1) from velocity and gate from keyon/keyoff events. Thus, gate can be used as a trigger signal for any envelope generator, etc.","title":"Polyphonic ready DSP Code"},{"location":"manual/architectures/#using-the-mydsp_poly-class","text":"The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the poly-dsp.h file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp* objects, manage dynamic voice allocation, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold as a subclass of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global Polyphonic tabgroup. The first tab contains a Voices group, a master like component used to change parameters on all voices at the same time, with a Panic button to be used to stop running voices, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI , httpdUI , etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used. The polyphonic instrument allocation takes the DSP to be used for one voice, the desired number of voices, the dynamic voice allocation state, and the group state which controls if separated voices are displayed or not: dsp* poly = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: dsp* poly = new mydsp_poly(dsp, 8, false, true);","title":"Using the mydsp_poly Class"},{"location":"manual/architectures/#polyphonic-instrument-with-a-global-output-effect","text":"Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is generally not a good idea since it would be instantiated for each voice which would be very inefficient. A convention has been defined to use the effect = some effect; line in the DSP source code. The actual effect definition has to be extracted from the DSP code, compiled separately, and then combined using the dsp_sequencer class previously presented to connect the polyphonic DSP in sequence with a unique global effect, with something like: dsp* poly = new dsp_sequencer(new mydsp_poly(dsp, 2, true, true), new effect()); | Some helper classes like the base dsp_poly_factory class, and concrete implementations llvm_dsp_poly_factory when using the LLVM backend or interpreter_dsp_poly_factory when using the Interpreter backend can also be used to automatically handle the voice and effect part of the DSP.","title":"Polyphonic Instrument With a Global Output Effect"},{"location":"manual/architectures/#controlling-the-polyphonic-instrument","text":"The mydsp_poly class is also ready for MIDI control (as a class implementing the midi interface) and can react to keyOn/keyOff and pitchWheel events. Other MIDI control parameters can directly be added in the DSP source code as MIDI metadata. To receive MIDI events, the created polyphonic DSP will be automatically added to the midi_handler object when calling buildUserInterface on a MidiUI object.","title":"Controlling the Polyphonic Instrument"},{"location":"manual/architectures/#deploying-the-polyphonic-instrument","text":"Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. faustcaqt -midi -noices 12 inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. Polyphonic ready faust2xx scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready-to-use DSP.","title":"Deploying the Polyphonic Instrument"},{"location":"manual/architectures/#custom-memory-manager","text":"In C and C++, the Faust compiler produces a class (or a struct in C), to be instantiated to create each DSP instance. The standard generation model produces a flat memory layout, where all fields (scalar and arrays) are simply consecutive in the generated code (following the compilation order). So the DSP is allocated on a single block of memory, either on the stack or the heap depending on the use-case. The following DSP program: import(\"stdfaust.lib\"); gain = hslider(\"gain\", 0.5, 0, 1, 0.01); feedback = hslider(\"feedback\", 0.8, 0, 1, 0.01); echo(del_sec, fb, g) = + ~ de.delay(50000, del_samples) * fb * g with { del_samples = del_sec * ma.SR; }; process = echo(1.6, 0.6, 0.7), echo(0.7, feedback, gain); will have the flat memory layout: int IOTA0; int fSampleRate; int iConst1; float fRec0[65536]; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float fRec1[65536]; So scalar fHslider0 and fHslider1 correspond to the gain and feedback controllers. The iConst1 and iConst2 values are typically computed once at init time using the dynamically given the fSampleRate value, and used in the DSP loop later on. The fRec0 and fRec1 arrays are used for the recursive delays and finally the shared IOTA0 index is used to access them. Here is the generated compute function: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; float fSlow0 = float(fHslider0) * float(fHslider1); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 65535] = float(input0[i0]) + 0.419999987f * fRec0[(IOTA0 - iConst1) & 65535]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 65535]); fRec1[IOTA0 & 65535] = float(input1[i0]) + fSlow0 * fRec1[(IOTA0 - iConst2) & 65535]; output1[i0] = FAUSTFLOAT(fRec1[IOTA0 & 65535]); IOTA0 = IOTA0 + 1; } }","title":"Custom Memory Manager"},{"location":"manual/architectures/#the-mem-option","text":"On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. The first remark is that scalar values will typically stay in the DSP structure, and the point is to move the big array buffers ( fRec0 and fRec1 in the example) into separated memory blocks. The -mem (--memory-manager) option can be used to generate adapted code. On the previous DSP program, we now have the following generated C++ code: int IOTA0; int fSampleRate; int iConst1; float* fRec0; FAUSTFLOAT fHslider0; FAUSTFLOAT fHslider1; int iConst2; float* fRec1; The two fRec0 and fRec1 arrays are becoming pointers, and will be allocated elsewhere. An external memory manager is needed to interact with the DSP code. The proposed model does the following: in a first step the generated C++ code will inform the memory allocator about its needs in terms of 1) number of separated memory zones, with 2) their size 3) access characteristics, like number of Read and Write for each frame computation. This is done be generating an additional static memoryInfo method with the complete information available, the memory manager can then define the best strategy to allocate all separated memory zones an additional memoryCreate method is generated to allocate each of the separated zones an additional memoryDestroy method is generated to deallocate each of the separated zones Here is the API for the memory manager: struct dsp_memory_manager { virtual ~dsp_memory_manager() {} /** * Inform the Memory Manager with the number of expected memory zones. * @param count - the number of memory zones */ virtual void begin(size_t count); /** * Give the Memory Manager information on a given memory zone. * @param size - the size in bytes of the memory zone * @param reads - the number of Read access to the zone used to compute one frame * @param writes - the number of Write access to the zone used to compute one frame */ virtual void info(size_t size, size_t reads, size_t writes) {} /** * Inform the Memory Manager that all memory zones have been described, * to possibly start a 'compute the best allocation strategy' step. */ virtual void end(); /** * Allocate a memory zone. * @param size - the memory zone size in bytes */ virtual void* allocate(size_t size) = 0; /** * Destroy a memory zone. * @param ptr - the memory zone pointer to be deallocated */ virtual void destroy(void* ptr) = 0; }; A class static member is added in the mydsp class, to be set with an concrete memory manager later on: dsp_memory_manager* mydsp::fManager = nullptr; The C++ generated code now contains a new memoryInfo method, which interacts with the memory manager: static void memoryInfo() { fManager->begin(3); // mydsp fManager->info(56, 9, 1); // fRec0 fManager->info(262144, 2, 1); // fRec1 fManager->info(262144, 2, 1); fManager->end(); } The begin method is first generated to inform that three separated memory zones will be needed. Then three consecutive calls to the info method are generated, one for the DSP object itself, one for each recursive delay array. The end method is then called to finish the memory layout description, and let the memory manager prepare the actual allocations. Note that the memory layout information is also available in the JSON file generated using the -json option, to possibly be used statically by the architecture machinery (that is at compile time). With the previous program, the memory layout section is: \"memory_layout\": [ { \"name\": \"mydsp\", \"type\": \"kObj_ptr\", \"size\": 0, \"size_bytes\": 56, \"read\": 9, \"write\": 1 }, { \"name\": \"IOTA0\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 7, \"write\": 1 }, { \"name\": \"iConst1\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec0\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 }, { \"name\": \"iConst2\", \"type\": \"kInt32\", \"size\": 1, \"size_bytes\": 4, \"read\": 1, \"write\": 0 }, { \"name\": \"fRec1\", \"type\": \"kFloat_ptr\", \"size\": 65536, \"size_bytes\": 262144, \"read\": 2, \"write\": 1 } ] Finally the memoryCreate and memoryDestroy methods are generated. The memoryCreate method asks the memory manager to allocate the fRec0 and fRec1 buffers: void memoryCreate() { fRec0 = static_cast<float*>(fManager->allocate(262144)); fRec1 = static_cast<float*>(fManager->allocate(262144)); } And the memoryDestroy method asks the memory manager to destroy them: virtual memoryDestroy() { fManager->destroy(fRec0); fManager->destroy(fRec1); } Additional static create/destroy methods are generated: static mydsp* create() { mydsp* dsp = new (fManager->allocate(sizeof(mydsp))) mydsp(); dsp->memoryCreate(); return dsp; } static void destroy(dsp* dsp) { static_cast<mydsp*>(dsp)->memoryDestroy(); fManager->destroy(dsp); } Note that the so-called C++ placement new will be used to allocate the DSP object itself.","title":"The -mem option"},{"location":"manual/architectures/#static-tables","text":"When rdtable or rwtable primitives are used in the source code, the C++ class will contain a table shared by all instances of the class. By default, this table is generated as a static class array, and so allocated in the application global static memory. Taking the following DSP example: process = (waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable), (waveform {1.1,2.2,3.3,4.4,5.5,6.6,7.7}, %(7)~+(3) : rdtable); Here is the generated code in default mode: ... static int itbl0mydspSIG0[7]; static float ftbl1mydspSIG1[7]; class mydsp : public dsp { ... public: ... static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(); sig0->instanceInitmydspSIG0(sample_rate); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(); sig1->instanceInitmydspSIG1(sample_rate); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0); deletemydspSIG1(sig1); } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are static global arrays. They are filled in the classInit method. The architecture code will typically call the init method (which calls classInit ) on a given DSP, to allocate class related arrays and the DSP itself. If several DSPs are going to be allocated, calling classInit only once then the instanceInit method on each allocated DSP is the way to go. In the -mem mode, the generated C++ code is now: ... static int* itbl0mydspSIG0 = 0; static float* ftbl1mydspSIG1 = 0; class mydsp : public dsp { ... public: ... static dsp_memory_manager* fManager; static void classInit(int sample_rate) { mydspSIG0* sig0 = newmydspSIG0(fManager); sig0->instanceInitmydspSIG0(sample_rate); itbl0mydspSIG0 = static_cast<int*>(fManager->allocate(28)); sig0->fillmydspSIG0(7, itbl0mydspSIG0); mydspSIG1* sig1 = newmydspSIG1(fManager); sig1->instanceInitmydspSIG1(sample_rate); ftbl1mydspSIG1 = static_cast<float*>(fManager->allocate(28)); sig1->fillmydspSIG1(7, ftbl1mydspSIG1); deletemydspSIG0(sig0, fManager); deletemydspSIG1(sig1, fManager); } static void classDestroy() { fManager->destroy(itbl0mydspSIG0); fManager->destroy(ftbl1mydspSIG1); } virtual void init(int sample_rate) {} virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } ... } The two itbl0mydspSIG0 and ftbl1mydspSIG1 tables are generated as static global pointers. The classInit method uses the fManager object used to allocate tables. A new classDestroy method is generated to deallocate the tables. Finally the init method is now empty, since the architecture file is supposed to use the classInit/classDestroy method once to allocate and deallocate static tables, and the instanceInit method on each allocated DSP. The memoryInfo method now has the following shape, with the two itbl0mydspSIG0 and ftbl1mydspSIG1 tables: static void memoryInfo() { fManager->begin(6); // mydspSIG0 fManager->info(4, 0, 0); // itbl0mydspSIG0 fManager->info(28, 1, 0); // mydspSIG1 fManager->info(4, 0, 0); // ftbl1mydspSIG1 fManager->info(28, 1, 0); // mydsp fManager->info(28, 0, 0); // iRec0 fManager->info(8, 3, 2); fManager->end(); }","title":"Static tables"},{"location":"manual/architectures/#defining-and-using-a-custom-memory-manager","text":"When compiled with the -mem option, the client code has to define an adapted memory_manager class for its specific needs. A cutom memory manager is implemented by subclassing the dsp_memory_manager abstract base class, and defining the begin , end , \u00ecnfo , allocate and destroy methods. Here is an example of a simple heap allocating manager (implemented in the dummy-mem.cpp architecture file): struct malloc_memory_manager : public dsp_memory_manager { virtual void begin(size_t count) { // TODO: use \u2018count\u2019 } virtual void end() { // TODO: start sorting the list of memory zones, to prepare // for the future allocations done in memoryCreate() } virtual void info(size_t size, size_t reads, size_t writes) { // TODO: use 'size', \u2018reads\u2019 and \u2018writes\u2019 // to prepare memory layout for allocation } virtual void* allocate(size_t size) { // TODO: refine the allocation scheme to take // in account what was collected in info return calloc(1, size); } virtual void destroy(void* ptr) { // TODO: refine the allocation scheme to take // in account what was collected in info free(ptr); } }; The specialized malloc_memory_manager class can now be used the following way: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // \u2018Placement new\u2019 and 'memoryCreate' are used inside the \u2018create\u2019 method dsp* DSP = mydsp::create(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // 'memoryDestroy' and memory manager 'destroy' are used to deallocate memory mydsp::destroy(); // Done once after the last DSP has been destroyed mydsp::classDestroy(); Note that the client code can still choose to allocate/deallocate the DSP instance using the regular C++ new/delete operators: // Allocate a global static custom memory manager static malloc_memory_manager gManager; // Setup the global custom memory manager on the DSP class mydsp::fManager = &gManager; // Make the memory manager get information on all subcontainers, // static tables, DSP and arrays and prepare memory allocation mydsp::memoryInfo(); // Done once before allocating any DSP, to allocate static tables mydsp::classInit(44100); // Use regular C++ new dsp* DSP = new mydsp(); /// Allocate internal buffers DSP->memoryCreate(); // Init the DSP instance DSP->instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP->memoryDestroy(); // Use regular C++ delete delete DSP; // Done once after the last DSP has been destroyed mydsp::classDestroy(); Or even on the stack with: ... // Allocation on the stack mydsp DSP; // Allocate internal buffers DSP.memoryCreate(); // Init the DSP instance DSP.instanceInit(44100); ... ... // use the DSP ... // Deallocate internal buffers DSP.memoryDestroy(); ... More complex custom memory allocators can be developed by refining this malloc_memory_manager example, possibly defining real-time memory allocators...etc... The OWL architecture file uses a custom OwlMemoryManager .","title":"Defining and using a custom memory manager"},{"location":"manual/architectures/#allocating-several-dsp-instances","text":"In a multiple instances scheme, static data structures shared by all instances have to be allocated once at beginning using mydsp::classInit , and deallocated at the end using mydsp::classDestroy . Individual instances are then allocated with mydsp::create() and deallocated with mydsp::destroy() , possibly directly using regular new/delete , or using stack allocation as explained before.","title":"Allocating several DSP instances"},{"location":"manual/architectures/#measuring-the-dsp-cpu","text":"The measure_dsp class defined in the faust/dsp/dsp-bench.h file allows to decorate a given DSP object and measure its compute method CPU consumption. Results are given in Megabytes/seconds (higher is better) and DSP CPU at 44,1 kHz. Here is a C++ code example of its use: static void bench(dsp* dsp, const string& name) { // Init the DSP dsp->init(48000); // Wraps it with a 'measure_dsp' decorator measure_dsp mes(dsp, 1024, 5); // Measure the CPU use mes.measure(); // Returns the Megabytes/seconds and relative standard deviation values std::pair<double, double> res = mes.getStats(); // Print the stats cout << name << \" MBytes/sec : \" << res.first << \" \" << \"(DSP CPU % : \" << (mes.getCPULoad() * 100) << \")\" << endl; } Defined in the faust/dsp/dsp-optimizer.h file, the dsp_optimizer class uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU. Here is a C++ code example of its use: static void dynamic_bench(const string& in_filename) { // Init the DSP optimizer with the in_filename to compile dsp_optimizer optimizer(in_filename, 0, nullptr, \"\", 1024); // Discover the best set of parameters tuple<double, double, double, TOption> res = optimizer.findOptimizedParameters(); cout << \"Best value for '\" << in_filename << \"' is : \" << get<0>(res) << \" MBytes/sec with \"; for (size_t i = 0; i < get<3>(res).size(); i++) { cout << get<3>(res)[i] << \" \"; } cout << endl; } This class can typically be used in tools that help developers discover the best Faust compilation parameters for a given DSP program, like the faustbench and faustbench-llvm tools.","title":"Measuring the DSP CPU"},{"location":"manual/architectures/#the-proxy-dsp-class","text":"In some cases, a DSP may run outside of the application or plugin context, like on another machine. The proxy_dsp class allows to create a proxy DSP that will be finally connected to the real one (using an OSC or HTTP based machinery for instance), and will reflect its behaviour. It uses the previously described JSONUIDecoder class. Then the proxy_dsp can be used in place of the real DSP, and connected with UI controllers using the standard buildUserInterface to control it. The faust-osc-controller tool demonstrates this capability using an OSC connection between the real DSP and its proxy. The proxy_osc_dsp class implements a specialized proxy_dsp using the liblo OSC library to connect to a OSC controllable DSP (which is using the OSCUI class and running in another context or machine). Then the faust-osc-controller program creates a real GUI (using GTKUI in this example) and have it control the remote DSP and reflect its dynamic state (like vumeter values coming back from the real DSP).","title":"The Proxy DSP Class"},{"location":"manual/architectures/#embedded-platforms","text":"Faust has been targeting an increasing number of embedded platforms for real-time audio signal processing applications in recent years. It can now be used to program microcontrollers (i.e., ESP32 , Teensy , Pico DSP and Daisy ), mobile platforms, embedded Linux systems (i.e., Bela and Elk ), Digital Signal Processors (DSPs), and more. Specialized architecture files and faust2xx scripts have been developed.","title":"Embedded Platforms"},{"location":"manual/architectures/#metadata-naming-convention","text":"A specific question arises when dealing with devices without or limited screen to display any GUI, and a set of physical knobs or buttons to be connected to control parameters. The standard way is then to use metadata in control labels. Since beeing able to use the same DSP file on all devices is always desirable, a common set of metadata has been defined: [switch:N] is used to connect to switch buttons [knob:N] is used to connect to knobs A extended set of metadata will probably have to be progressively defined and standardized.","title":"Metadata Naming Convention"},{"location":"manual/architectures/#using-the-uim-compiler-option","text":"On embedded platforms with limited capabilities, using the -uim option can be helpful. The C/C++ generated code then contains a static description of several caracteristics of the DSP, like the number of audio inputs/outputs , the number of controls inputs/outputs , and macros feed with the controls parameters (label, DSP field name, init, min, max, step) that can be implemented in the architecture file for various needs. For example the following DSP program: process = _*hslider(\"Gain\", 0, 0, 1, 0.01) : hbargraph(\"Vol\", 0, 1); compiled with faust -uim foo.dsp gives this additional section: #ifdef FAUST_UIMACROS #define FAUST_FILE_NAME \"foo.dsp\" #define FAUST_CLASS_NAME \"mydsp\" #define FAUST_INPUTS 1 #define FAUST_OUTPUTS 1 #define FAUST_ACTIVES 1 #define FAUST_PASSIVES 1 FAUST_ADDHORIZONTALSLIDER(\"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f); FAUST_ADDHORIZONTALBARGRAPH(\"Vol\", fHbargraph0, 0.0f, 1.0f); #define FAUST_LIST_ACTIVES(p) \\ p(HORIZONTALSLIDER, Gain, \"Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f) \\ #define FAUST_LIST_PASSIVES(p) \\ p(HORIZONTALBARGRAPH, Vol, \"Vol\", fHbargraph0, 0.0, 0.0f, 1.0f, 0.0) \\ #endif The FAUST_ADDHORIZONTALSLIDER or FAUST_ADDHORIZONTALBARGRAPH macros can then be implemented to do whatever is needed with the Gain\", fHslider0, 0.0f, 0.0f, 1.0f, 0.01f and \"Vol\", fHbargraph0, 0.0f, 1.0f parameters respectively. The more sophisticated FAUST_LIST_ACTIVES and FAUST_LIST_PASSIVES macros can possibly be used to call any p function (defined elsewhere in the architecture file) on each item. The minimal-static.cpp file demonstrates this feature.","title":"Using the -uim Compiler Option"},{"location":"manual/architectures/#developing-a-new-architecture-file","text":"Developing a new architecture file typically means writing a generic file, that will be populated with the actual output of the Faust compiler, in order to produce a complete file, ready-to-be-compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the <<includeIntrinsic>> and <<includeclass>> lines that will be recognized by the Faust compiler, and replaced by the generated code. Here is an example in C++, but the same logic can be used with other languages producing textual outputs, like C, Cmajor, Rust or Dlang. Look at the minimal.cpp example located in the architecture folder: #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #include \"faust/dsp/one-sample-dsp.h\" // To be replaced by the compiler generated C++ class <<includeIntrinsic>> <<includeclass>> int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", static_cast<dsp*>(&DSP)); // Render buffers... audio.start(); audio.stop(); } Calling faust -a minimal.cpp noise.dsp -o noise.cpp will produce a ready to compile noise.cpp file: /* ------------------------------------------------------------ name: \"noise\" Code generated with Faust 2.28.0 (https://faust.grame.fr) Compilation options: -lang cpp -scal -ftz 0 ------------------------------------------------------------ */ #ifndef __mydsp_H__ #define __mydsp_H__ #include <iostream> #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #include <algorithm> #include <cmath> #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif #ifdef __APPLE__ #define exp10f __exp10f #define exp10 __exp10 #endif class mydsp : public dsp { private: FAUSTFLOAT fHslider0; int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"filename\", \"noise.dsp\"); m->declare(\"name\", \"noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fHslider0 = FAUSTFLOAT(0.5f); } virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"noise\"); ui_interface->addHorizontalSlider(\"Volume\", &fHslider0, 0.5, 0.0, 1.0, 0.001); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = (4.65661287e-10f * float(fHslider0)); for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((fSlow0 * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; std::cout << \"DSP size: \" << sizeof(DSP) << \" bytes\\n\"; // Activate the UI, here that only print the control paths PrintUI ui; DSP.buildUserInterface(&ui); // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); } Generally, several files to connect to the audio layer, controller layer, and possibly other (MIDI, OSC...) have to be used. One of them is the main file and include the others. The -i option can be added to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with faust ) to produce a single self-contained unique file. Then a faust2xxx script has to be written to chain the Faust compilation step and the C++ compilation one (and possibly others). Look at the Developing a faust2xx Script section.","title":"Developing a New Architecture File"},{"location":"manual/architectures/#adapting-the-generated-dsp","text":"Developing the adapted C++ file may require aggregating the generated mydsp class (subclass of the dsp base class defined in faust/dsp/dsp.h header) in the specific class, so something like the following would have to be written: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the fDSP 'compute' fDSP.compute(count, inputs, outputs); } // Do something specific }; or subclassing and extending it , so writing something like: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' mydsp::compute(count, inputs, outputs); } // Do something specific }; or decorating a DSP object using the decorator pattern , which is already implemented in this file , and can possibly be sub-classed like: class my_decorator : public decorator_dsp { private: // Do something specific public: my_decorator(dsp* dsp):decorator_dsp(dsp) { // Do something specific } virtual ~my_class() { // Do something specific } // Implementation of some of the methods // Override the 'instanceClear' method void instanceClear() { // Do something specific // Call the inherited 'instanceClear' decorator_dsp::instanceClear(); } // Override the 'compute' method void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { // Do something specific // Call the inherited 'compute' decorator_dsp::compute(count, inputs, outputs); } // Do something specific }; // Decorates a concrete instance my_decorator DSP = new my_decorator(new mydsp()); ...","title":"Adapting the Generated DSP"},{"location":"manual/architectures/#developing-new-ui-architectures","text":"For really new architectures, the UI base class, the GenericUI helper class or the GUI class (described before), have to be subclassed. Note that a lot of classes presented in the Some useful UI classes for developers section can also be subclassed or possibly enriched with additional code.","title":"Developing New UI Architectures"},{"location":"manual/architectures/#developing-new-audio-architectures","text":"The audio base class has to be subclassed and each method implemented for the given audio hardware. In some cases the audio driver can adapt to the required number of DSP inputs/outputs (like the JACK audio system for instance which can open any number of virtual audio ports). But in general, the number of hardware audio inputs/outputs may not exactly match the DSP ones. This is the responsability of the audio driver to adapt to this situation. The dsp_adapter dsp decorator can help in this case.","title":"Developing New Audio Architectures"},{"location":"manual/architectures/#developing-a-new-soundfile-loader","text":"Soundfiles are defined in the DSP program using the soundfile primitive . Here is a simple DSP program which uses a single tango.wav audio file and play it until its end: process = 0,_~+(1):soundfile(\"sound[url:{'tango.wav'}]\",2):!,!, The compiled C++ class has the following structure: class mydsp : public dsp { private: Soundfile* fSoundfile0; int iRec0[2]; int fSampleRate; .... with the Soundfile* fSoundfile0; field and its definition : struct Soundfile { void* fBuffers; // will correspond to a double** or float** pointer chosen at runtime int* fLength; // length of each part (so fLength[P] contains the length in frames of part P) int* fSR; // sample rate of each part (so fSR[P] contains the SR of part P) int* fOffset; // offset of each part in the global buffer (so fOffset[P] contains the offset in frames of part P) int fChannels; // max number of channels of all concatenated files int fParts; // the total number of loaded parts bool fIsDouble; // keep the sample format (float or double) }; The following buildUserInterface method in generated, containing a addSoundfile method called with the appropriate parameters extracted from the soundfile(\"sound[url:{'tango.wav'}]\",2) piece of DSP code, to be used to load the tango.wav audio file and prepare the fSoundfile0 field: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tp0\"); ui_interface->addSoundfile(\"sound\", \"{'tango.wav'}\", &fSoundfile0); ui_interface->closeBox(); } The specialized SoundUI architecture file is then used to load the required soundfiles at DSP init time, by using a SoundfileReader object. It only implements the addSoundfile method which will load all needed audio files, create and fill the fSoundfile0 object. Different concrete implementations are already written, either using libsndfile (with the LibsndfileReader.h file), or JUCE (with the JuceReader file). A new audio file loader can be written by subclassing the SoundfileReader class. A pure memory reader could be implemented for instance to load wavetables to be used as the soundfile URL list. Look at the template MemoryReader class, as an example to be completed, with the following methods to be implemented: /** * Check the availability of a sound resource. * * @param path_name - the name of the file, or sound resource identified this way * * @return true if the sound resource is available, false otherwise. */ virtual bool checkFile(const std::string& path_name); /** * Get the channels and length values of the given sound resource. * * @param path_name - the name of the file, or sound resource identified this way * @param channels - the channels value to be filled with the sound resource * number of channels * @param length - the length value to be filled with the sound resource length in frames * */ virtual void getParamsFile(const std::string& path_name, int& channels, int& length); /** * Read one sound resource and fill the 'soundfile' structure accordingly * * @param path_name - the name of the file, or sound resource identified this way * @param part - the part number to be filled in the soundfile * @param offset - the offset value to be incremented with the actual * sound resource length in frames * @param max_chan - the maximum number of mono channels to fill * */ virtual void readFile(Soundfile* soundfile, const std::string& path_name, int part, int& offset, int max_chan); Another example to look at is WaveReader . The SoundUI architecture is then used the following way: mydsp DSP; // Here using a compiled time chosen SoundfileReader SoundUI* sound_interface = new SoundUI(); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface; The SoundfileReader object can be dynamically choosen by using an alternate version of the SoundUI constructor, possibly choosing the sample format to be double when the DSP code is compiled with the -double option: mydsp DSP; // Here using a dynamically chosen custom MyMemoryReader SoundfileReader* sound_reader = new MyMemoryReader(...); SoundUI* sound_interface = new SoundUI(\"\", false, sound_reader, true); DSP.buildUserInterface(sound_interface); ... run the DSP ... // Finally deallocate the sound_interface and associated Soundfile resources delete sound_interface;","title":"Developing a New Soundfile Loader"},{"location":"manual/architectures/#other-languages-than-c","text":"Most of the architecture files have been developed in C++ over the years. Thus they are ready to be used with the C++ backend and the one that generate C++ wrapped modules (like the LLVM, Cmajor and Interpreter backends). For other languages, specific architecture files have to be written. Here is the current situation for other backends: the C backend needs additional CGlue.h and CInterface.h files, with the minimal-c file as a simple console mode example using them the Rust backend can be used with the minimal-rs architecture, the more complex JACK jack.rs used in faust2jackrust script, or the PortAudio portaudio.rs used in faust2portaudiorust script the experimental Dlang backend can be used with the minimal.d or the dplug.d to generate DPlug plugins with the faust2dplug script. the Julia backend can be used with the minimal.jl architecture or the portaudio.jl used in faust2portaudiojulia script.","title":"Other Languages Than C++"},{"location":"manual/architectures/#the-faust2xx-scripts","text":"","title":"The faust2xx Scripts"},{"location":"manual/architectures/#using-faust2xx-scripts","text":"The faust2xx scripts finally combine different architecture files to generate a ready-to-use application or plugin, etc... from a Faust DSP program. They typically combine the generated DSP with an UI architecture file and an audio architecture file. Most of the also have addition options like -midi , -nvoices <num> , -effect <auto|effect.dsp> or -soundfile to generate polyphonic instruments with or without effects, or audio file support. Look at the following page for a more complete description.","title":"Using faust2xx Scripts"},{"location":"manual/architectures/#developing-a-faust2xx-script","text":"The faust2xx script are mostly written in bash (but any scripting language can be used) and aims to produce a ready-to-use application, plugin, etc... from a DSP program. A faust2minimal template script using the C++ backend, can be used to start the process. The helper scripts, faustpath , faustoptflags , and usage.sh can be used to setup common variables: # Define some common paths . faustpath # Define compilation flags . faustoptflags # Helper file to build the 'help' option . usage.sh CXXFLAGS+=\" $MYGCCFLAGS\" # So that additional CXXFLAGS can be used # The architecture file name ARCHFILE=$FAUSTARCH/minimal.cpp # Global variables OPTIONS=\"\" FILES=\"\" The script arguments then have to be analysed, compiler options are kept in the OPTIONS variable and all DSP files in the FILES one: #------------------------------------------------------------------- # dispatch command arguments #------------------------------------------------------------------- while [ $1 ] do p=$1 if [ $p = \"-help\" ] || [ $p = \"-h\" ]; then usage faust2minimal \"[options] [Faust options] <file.dsp>\" exit fi echo \"dispatch command arguments\" if [ ${p:0:1} = \"-\" ]; then OPTIONS=\"$OPTIONS $p\" elif [[ -f \"$p\" ]] && [ ${p: -4} == \".dsp\" ]; then FILES=\"$FILES $p\" else OPTIONS=\"$OPTIONS $p\" fi shift done Each DSP file is first compiled to C++ using the faust -a command and the appropriate architecture file, then to the final executable program, here using the C++ compiler: #------------------------------------------------------------------- # compile the *.dsp files #------------------------------------------------------------------- for f in $FILES; do # compile the DSP to c++ using the architecture file echo \"compile the DSP to c++ using the architecture file\" faust -i -a $ARCHFILE $OPTIONS \"$f\" -o \"${f%.dsp}.cpp\"|| exit # compile c++ to binary echo \"compile c++ to binary\" ( $CXX $CXXFLAGS \"${f%.dsp}.cpp\" -o \"${f%.dsp}\" ) > /dev/null || exit # remove tempory files rm -f \"${f%.dsp}.cpp\" # collect binary file name for FaustWorks BINARIES=\"$BINARIES${f%.dsp};\" done echo $BINARIES The existing faust2xx scripts can be used as examples.","title":"Developing a faust2xx Script"},{"location":"manual/architectures/#the-faust2api-model","text":"This model combining the generated DSP the audio and UI architecture components is very convenient to automatically produce ready-to-use standalone application or plugins, since the controller part (GUI, MIDI or OSC...) is directly compiled and deployed. In some cases, developers prefer to control the DSP by creating a completely new GUI (using a toolkit not supported in the standard architecture files), or even without any GUI and using another control layer. A model that only combines the generated DSP with an audio architecture file to produce an audio engine has been developed (thus gluing the blue and red parts of the three color model explained at the beginning). A generic template class DspFaust has been written in the DspFaust.h and DspFaust.cpp files. This code contains conditional compilation sections to add and initialize the appropriate audio driver (written as a subclass of the previously described base audio class), and can produce audio generators , effects , of fully MIDI and sensor controllable pophyphonic instruments . The resulting audio engine contains start and stop methods to control audio processing. It also provides a set of functions like getParamsCount, setParamValue, getParamValue etc. to access all parameters (or the additional setVoiceParamValue method function to access a single voice in a polyphonic case), and let the developer adds his own GUI or any kind of controller. Look at the faust2api script, which uses the previously described architecture files, and provide a tool to easily generate custom APIs based on one or several Faust objects.","title":"The faust2api Model"},{"location":"manual/architectures/#using-the-inj-option-with-faust2xx-scripts","text":"The compiler -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. Two examples of use are presented next.","title":"Using the -inj Option With faust2xx Scripts"},{"location":"manual/architectures/#using-the-template-llvmcpp-architecture","text":"The first one demonstrates how faust2xx scripts can become more dynamic by loading and compiling an arbitrary DSP at runtime. This is done using the template-llvm.cpp architecture file which uses the libfaust library and the LLVM backend to dynamically compile a foo.dsp file. So instead of producing a static binary based on a given DSP, the resulting program will be able to load and compile a DSP at runtime. This template-llvm.cpp can be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application, ready to be used to load and compile a DSP, and run it with the CoreAudio audio layer and GTK as the GUI freamework. Then faust2cagtk-llvm will ask for a DSP to compile: ./faust2cagtk-llvm <Enter a foo.dsp file> A generic polyphonic (8 voices) and MIDI controllable version can be compiled using: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp (a dummy DSP) Note that the resulting binary keeps its own control options, like: ./faust2cagtk-llvm -h ./faust2cagtk-llvm [--frequency <val>] [--buffer <val>] [--nvoices <val>] [--control <0/1>] [--group <0/1>] [--virtual-midi <0/1>] So now ./faust2cagtk-llvm --nvoices 16 starts the program with 16 voices. The technique has currently be tested with the faust2cagtk , faust2jack , faust2csvplot , and faust2plot tools.","title":"Using the template-llvm.cpp architecture"},{"location":"manual/architectures/#second-use-case-computing-the-spectrogram-of-a-set-of-audio-files","text":"Here is a second use case where some external C++ code is used to compute the spectrogram of a set of audio files (which is something that cannot be simply done with the current version fo the Faust language) and output the spectrogram as an audio signal. A nentry controller will be used to select the currently playing spectrogram. The Faust compiler will be used to generate a C++ class which is going to be manually edited and enriched with additional code.","title":"Second use-case computing the spectrogram of a set of audio files"},{"location":"manual/architectures/#writting-the-dsp-code","text":"First a fake DSP program spectral.dsp using the soundfile primitive loading two audio files and a nentry control is written: sf = soundfile(\"sound[url:{'sound1.wav';'sound2.wav'}]\",2); process = (hslider(\"Spectro\", 0, 0, 1, 1),0) : sf : !,!,_,_; The point of explicitly using soundfile primitive and a nentry control is to generate a C++ file with a prefilled DSP structure (containing the fSoundfile0 and fHslider0 fields) and code inside the buildUserInterface method. Compiling it manually with the following command: faust spectral.dsp -cn spectral -o spectral.cpp produces the following C++ code containing the spectral class: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectrogram\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); .... } };","title":"Writting the DSP code"},{"location":"manual/architectures/#customizing-the-c-code","text":"Now the spectral class can be manually edited and completed with additional code, to compute the two audio files spectrograms in buildUserInterface , and play them in compute . a new line Spectrogram fSpectro[2]; is added in the DSP structure a createSpectrogram(fSoundfile0, fSpectro); function is added in buildUserInterface and used to compute and fill the two spectrograms, by reading the two loaded audio files in fSoundfile0 part of the generated code in compute is removed and replaced by new code to play one of spectrograms (selected with the fHslider0 control in the GUI) using a playSpectrogram(fSpectro, count, iSlow0, outputs); function: class spectral : public dsp { private: Soundfile* fSoundfile0; FAUSTFLOAT fHslider0; int fSampleRate; Spectrogram fSpectro[2]; public: ... virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 2; } ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"spectral\"); ui_interface->addHorizontalSlider(\"Spectro\", &fHslider0, 0.0f, 0.0f, 1.0f, 1.0f); ui_interface->addSoundfile(\"sound\", \"{'sound1.wav';'sound2.wav';}\", &fSoundfile0); // Read 'fSoundfile0' and fill 'fSpectro' createSpectrogram(fSoundfile0, fSpectro); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { int iSlow0 = int(float(fHslider0)); // Play 'fSpectro' indexed by 'iSlow0' by writting 'count' samples in 'outputs' playSpectrogram(fSpectro, count, iSlow0, outputs); } }; Here we assume that createSpectrogram and playSpectrogram functions are defined elsewhere and ready to be compiled.","title":"Customizing the C++ code"},{"location":"manual/architectures/#deploying-it-as-a-maxmsp-external-using-the-faust2max6-script","text":"The completed spectral.cpp file is now ready to be deployed as a Max/MSP external using the faust2max6 script and the -inj option with the following line: faust2max6 -inj spectral.cpp -soundfile spectral.dsp The two needed sound1.wav and sound2.wav audio files are embedded in the generated external, loaded at init time (since the buildUserInterface method is automatically called), and the manually added C++ code will be executed to compute the spectrograms and play them. Finally by respecting the naming coherency for the fake spectral.dsp DSP program, the generated spectral.cpp C++ file, the automatically generated spectral.maxpat Max/MSP patch will be able to build the GUI with a ready-to-use slider.","title":"Deploying it as a Max/MSP External Using the faust2max6 Script"},{"location":"manual/architectures/#additional-ressources","text":"Several external projects are providing tools to arrange the way Faust source code is generated or used, in different languages.","title":"Additional Ressources"},{"location":"manual/architectures/#preprocessing-tools","text":"","title":"Preprocessing tools"},{"location":"manual/architectures/#fpp","text":"fpp is a standalone Perl script with no dependencies which allows ANY C/C++ code in a Faust .dsp file as long as you are targeting C/C++ in scalar mode.","title":"fpp"},{"location":"manual/architectures/#c-tools","text":"Using and adapting the dsp/UI/audio model in a more sophisticated way, or integrating Faust generated C++ classes in others frameworks (like JUCE).","title":"C++ tools"},{"location":"manual/architectures/#faust2hpp","text":"Convert Faust code to a header-only standalone C++ library. A collection of header files is generated as the output. A class is provided from which a DSP object can be built with methods in the style of JUCE DSP objects.","title":"faust2hpp"},{"location":"manual/architectures/#faustpp","text":"A post-processor for Faust, which allows to generate with more flexibility. This is a source transformation tool based on the Faust compiler. It permits to arrange the way how Faust source is generated with greater flexibility.","title":"faustpp"},{"location":"manual/architectures/#cookiecutter-dpf-faust","text":"A cookiecutter project template for DISTRHO plugin framework audio effect plugins using Faust for the implementation of the DSP pipeline.","title":"cookiecutter-dpf-faust"},{"location":"manual/architectures/#faustmd","text":"Static metadata generator for Faust/C++. This program builds the metadata for a Faust DSP ahead of time, rather than dynamically. The result is a block of C++ code which can be appended to the code generation.","title":"faustmd"},{"location":"manual/architectures/#faustcppconverter","text":"Eyal Amir tool to facilitate the use of Faust generated C++ code in JUCE projects.","title":"FaustCPPConverter"},{"location":"manual/architectures/#josmodules-and-josm_faust","text":"Julius Smith projects to facilitate the use of Faust generated C++ code in JUCE projects.","title":"JOSModules and josm_faust"},{"location":"manual/architectures/#arduino-tools","text":"An alternative way to use the ESP32 board with Faust, possibly easier and more versatile than the examples mentioned on the esp32 tutorial .","title":"Arduino tools"},{"location":"manual/architectures/#cmajor-tools","text":"","title":"Cmajor tools"},{"location":"manual/architectures/#using-faust-in-cmajor","text":"A tutorial to show how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation.","title":"Using Faust in Cmajor"},{"location":"manual/architectures/#rnbo-tools","text":"","title":"RNBO tools"},{"location":"manual/architectures/#using-faust-in-rnbo-with-codebox","text":"A tutorial to show how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi.","title":"Using Faust in RNBO with codebox~"},{"location":"manual/architectures/#dlang-tools","text":"","title":"DLang tools"},{"location":"manual/architectures/#faust-2-dplug-guide","text":"Explains how to use Faust in a Dplug project.","title":"Faust 2 Dplug Guide"},{"location":"manual/architectures/#dplug-faust-example","text":"This is an example plugin using Dplug with a Faust backend. It is a stereo reverb plugin using the Freeverb demo from the Faust library.","title":"Dplug Faust Example"},{"location":"manual/architectures/#julia-tools","text":"","title":"Julia tools"},{"location":"manual/architectures/#faustjl","text":"Julia wrapper for the Faust compiler. Uses the Faust LLVM C API.","title":"Faust.jl"},{"location":"manual/architectures/#using-faust-in-julia","text":"A tutorial to show how Faust can be used with Julia , a high-level, general-purpose dynamic programming language with features well suited for numerical analysis and computational science.","title":"Using Faust in Julia"},{"location":"manual/architectures/#python-tools","text":"","title":"Python tools"},{"location":"manual/architectures/#faustpy","text":"FAUSTPy is a Python wrapper for the FAUST DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork .","title":"FAUSTPy"},{"location":"manual/architectures/#faust-ctypes","text":"A port of Marc Joliet's FaustPy from CFFI to Ctypes. Faust-Ctypes documentation is available online .","title":"Faust Ctypes"},{"location":"manual/architectures/#an-scons-tool-for-faust","text":"This is an SCons tool for compiling FAUST programs. It adds various builders to your construction environment: Faust, FaustXML, FaustSVG, FaustSC, and FaustHaskell. Their behaviour can be modified by changing various construction variables (see \"Usage\" below).","title":"An SCons Tool for FAUST"},{"location":"manual/architectures/#faustwatch","text":"At the moment there is one tool present, faustwatch.py. Faustwatch is a tool that observes a .dsp file used by the dsp language Faust.","title":"Faustwatch"},{"location":"manual/architectures/#faustwidgets","text":"Creates interactive widgets inside jupyter notebooks from Faust dsp files and produces a (customizable) plot.","title":"faustWidgets"},{"location":"manual/architectures/#faust-synth","text":"This is an example project for controlling a synth, programmed and compiled with Faust, through a Python script. The synth runs as a JACK client on Linux systems and the output is automatically recorded by jack_capture.","title":"Faust Synth"},{"location":"manual/architectures/#dawdreamer","text":"DawDreamer is an audio-processing Python framework supporting Faust and Faust's Box API.","title":"DawDreamer"},{"location":"manual/architectures/#ode2dsp","text":"ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Finite difference equations (FDEs) are rendered to Faust code.","title":"ode2dsp"},{"location":"manual/architectures/#faustlab","text":"A exploratory project to wrap the Faust interpreter for use by python via the following wrapping frameworks using the RtAudio cross-platform audio driver: cyfaust: cython (faust c++ interface) cfaustt: cython (faust c interface) pyfaust: pybind11 (faust c++ interface) nanobind: nanobind (faust c++ interface)","title":"faustlab"},{"location":"manual/architectures/#cyfaust","text":"A cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension.","title":"cyfaust"},{"location":"manual/architectures/#rust-tools","text":"","title":"Rust tools"},{"location":"manual/architectures/#rust-faust","text":"A better integration of Faust for Rust. It allows to build the DSPs via build.rs and has some abstractions to make it much easier to work with params and meta of the DSPs.","title":"rust-faust"},{"location":"manual/architectures/#faust-egui","text":"Proof of concept of drawing a UI with egui and rust-faust .","title":"Faust egui"},{"location":"manual/architectures/#rustfaustexperiments","text":"Tools to compare C++ and Rust code generated from Faust.","title":"RustFaustExperiments"},{"location":"manual/architectures/#fl-tui","text":"Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API.","title":"fl-tui"},{"location":"manual/architectures/#faustlive-jack-rs","text":"Another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API.","title":"faustlive-jack-rs"},{"location":"manual/architectures/#lowpass-lr4-faust-nih-plug","text":"A work-in-progress project to integrate Faust generated Rust code with NIH-plug .","title":"lowpass-lr4-faust-nih-plug"},{"location":"manual/architectures/#nih-faust-jit","text":"A plugin to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"nih-faust-jit"},{"location":"manual/architectures/#webassembly-tools","text":"","title":"WebAssembly tools"},{"location":"manual/architectures/#faust-loader","text":"Import Faust .dsp files, and get back an AudioWorklet or ScriptProcessor node.","title":"faust-loader"},{"location":"manual/architectures/#faust2cpp2wasm","text":"A drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend.","title":"faust2cpp2wasm"},{"location":"manual/architectures/#faust-compiler-microservice","text":"This is a microservice that serves a single purpose: compiling Faust code that is sent to it into WebAssembly that can then be loaded and run natively from within the web synth application. It is written in go because go is supposed to be good for this sort of thing.","title":"Faust Compiler Microservice"},{"location":"manual/architectures/#mosfez-faust","text":"Makes dynamic compilation of Faust on the web a little easier, and has a dev project to run values through dsp offline, and preview dsp live. It's an opinionated version of some parts of Faust for webaudio , mostly just the Web Assembly Faust compiler, wrapped up in a library with additional features.","title":"mosfez-faust"},{"location":"manual/architectures/#faust-wap2-playground","text":"Playground and template for Faust-based web audio experiments.","title":"faust-wap2-playground"},{"location":"manual/architectures/#dart-tools","text":"","title":"Dart tools"},{"location":"manual/architectures/#flutter_faust_ffi","text":"A basic flutter app as a proof of concept utilizing Faust's C API export with Dart's ffi methods to create cross-platform plug-ins.","title":"flutter_faust_ffi"},{"location":"manual/community/","text":"Material from the community Here is a list of additional material contributed by the community of Faust developers or users. Articles, Video and Blog Posts Generate WAMs with FaustIDE Web Audio Modules (WAM) ias a standard for Web Audio plugins and DAWs. The 2.0 version of Web Audio Modules has been released in 2021 as a group effort by a large set of people and since then, multiple plugins and hosts have been published, mostly as open source and free software. The FAUST IDE is a very popular tool for generating WAMs from existing FAUST code (and there are hundreds of source code example available for audio effects, instruments, etc.). You can generate WAMs directly from the command line using the faust2wam script . Mozzi Revisited Mozzi brings your Arduino to life by allowing it to produce much more complex and interesting growls, sweeps and chorusing atmospherics. These sounds can be quickly and easily constructed from familiar synthesis units like oscillators, delays, filters and envelopes and can be programmed with Faust . How to compile HISE and FAUST for Audio Plugin Development This video shows how you can use Faust inside HISE . More info on how to use Faust in HISE can be found on the HISE Faust forum . How to build Mod Duo plugin written in Faust This article shows how you can compile a Faust program to run on Mod Duo . Handling infinity and not-a-number (NaN) values in Faust and C++ audio programming This post by Dario Sanfilippo discusses insights gained over a few years of audio programming to implement robust Faust/C++ software, particularly when dealing with infinity and NaN values. Three ways to implement recursive circuits in the Faust language This post by Dario Sanfilippo is about the implementation of not-so-simple recursive circuits in the Faust language. Make LV2 plugins with Faust This post by Nicola Landro is about making LV2 plugins with Faust. Getting started with Faust for SuperCollider This post by Mads Kjeldgaard is about using Faust with SuperCollider . Get Started Audio Programming with the FAUST Language This post by Matt K is about starting audio Programming with Faust. Using Faust on the OWL family of devices This tutorial focus on using Faust and on features that are specific to OWL and the OpenWare firmware. I ported native guitar plugins to JavaScript (in-depth) This post by Konstantine Kutalia is porting Faust coded Kapitonov Plugins Pack in JavaScript. Using Faust with the Arduino Audio Tools Library A blog about using Faust with Arduino Audio Tools. Writing a Slew Limiter in the Faust Language A video about writing a Slew Limiter in the Faust Language by Julius Smith. Make an Eight Channel Mixer in the Faust IDE A video about making an Eight Channel Mixer in the Faust IDE by Julius Smith. Creating VSTs and more using FAUST FAUST is a programming language that enables us to quickly create cross-platform DSP code. We can easily create VST plugins, Max-Externals and more. Its high-quality built-in library of effects and tools enables us to quickly draft high quality audio processing devices. The workshop aims at getting new users started, conveying what FAUST is good for and how to use it effectively to produce high quality results quickly. Various Tools Syntax Highlighting tree-sitter-faust Tree-sitter grammar Faust. Every Faust syntax feature should be supported. The npm package is here . Syntax Highlighting Files This folder contains syntax highlighting files for various editors. Sublime Text syntax Sublime Text syntax file for the Faust programming language. Faust-Mode Major Emacs mode for the Faust programming language, featuring syntax highlighting, automatic indentation and auto-completion. Faustine Faustine allows the edition of Faust code using emacs. faust neovim plugin Plugin to edit Faust code in the hyperextensible Vim-based text editor neowim . Code Generators faust2pdex Generator of Faust wrappers for Pure Data. This software wraps the C++ code generated by Faust into a native external for Pure Data. You obtain a piece of source code that you can use with pd-lib-builder to produce a native binary with the help of make. No knowledge of C++ programming is required. Faust.quark This SuperCollider package makes it possible to create SuperCollider packages (Quarks) containing plugins written in Faust code. With this, you can distribute plugins written in Faust and make it easy for others to install, compile or uninstall them. It also contains some simple interfaces for the faust and faust2sc.py commands used behind the scenes. ode2dsp ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Features: Support linear and nonlinear systems of ODEs Support trapezoidal and backward Euler discrete-time integral approximations Approximate solutions of implicit equations using Newton's method Render finite difference equations (FDEs) to Faust code Calculate stability of ODEs and FDEs at an operating point Contributing Feel free to contribute by forking this project and creating a pull request , or by mailing the library description here .","title":"Community"},{"location":"manual/community/#material-from-the-community","text":"Here is a list of additional material contributed by the community of Faust developers or users.","title":"Material from the community"},{"location":"manual/community/#articles-video-and-blog-posts","text":"","title":"Articles, Video and Blog Posts"},{"location":"manual/community/#generate-wams-with-faustide","text":"Web Audio Modules (WAM) ias a standard for Web Audio plugins and DAWs. The 2.0 version of Web Audio Modules has been released in 2021 as a group effort by a large set of people and since then, multiple plugins and hosts have been published, mostly as open source and free software. The FAUST IDE is a very popular tool for generating WAMs from existing FAUST code (and there are hundreds of source code example available for audio effects, instruments, etc.). You can generate WAMs directly from the command line using the faust2wam script .","title":"Generate WAMs with FaustIDE"},{"location":"manual/community/#mozzi-revisited","text":"Mozzi brings your Arduino to life by allowing it to produce much more complex and interesting growls, sweeps and chorusing atmospherics. These sounds can be quickly and easily constructed from familiar synthesis units like oscillators, delays, filters and envelopes and can be programmed with Faust .","title":"Mozzi Revisited"},{"location":"manual/community/#how-to-compile-hise-and-faust-for-audio-plugin-development","text":"This video shows how you can use Faust inside HISE . More info on how to use Faust in HISE can be found on the HISE Faust forum .","title":"How to compile HISE and FAUST for Audio Plugin Development"},{"location":"manual/community/#how-to-build-mod-duo-plugin-written-in-faust","text":"This article shows how you can compile a Faust program to run on Mod Duo .","title":"How to build Mod Duo plugin written in Faust"},{"location":"manual/community/#handling-infinity-and-not-a-number-nan-values-in-faust-and-c-audio-programming","text":"This post by Dario Sanfilippo discusses insights gained over a few years of audio programming to implement robust Faust/C++ software, particularly when dealing with infinity and NaN values.","title":"Handling infinity and not-a-number (NaN) values in Faust and C++ audio programming"},{"location":"manual/community/#three-ways-to-implement-recursive-circuits-in-the-faust-language","text":"This post by Dario Sanfilippo is about the implementation of not-so-simple recursive circuits in the Faust language.","title":"Three ways to implement recursive circuits in the Faust language"},{"location":"manual/community/#make-lv2-plugins-with-faust","text":"This post by Nicola Landro is about making LV2 plugins with Faust.","title":"Make LV2 plugins with Faust"},{"location":"manual/community/#getting-started-with-faust-for-supercollider","text":"This post by Mads Kjeldgaard is about using Faust with SuperCollider .","title":"Getting started with Faust for SuperCollider"},{"location":"manual/community/#get-started-audio-programming-with-the-faust-language","text":"This post by Matt K is about starting audio Programming with Faust.","title":"Get Started Audio Programming with the FAUST Language"},{"location":"manual/community/#using-faust-on-the-owl-family-of-devices","text":"This tutorial focus on using Faust and on features that are specific to OWL and the OpenWare firmware.","title":"Using Faust on the OWL family of devices"},{"location":"manual/community/#i-ported-native-guitar-plugins-to-javascript-in-depth","text":"This post by Konstantine Kutalia is porting Faust coded Kapitonov Plugins Pack in JavaScript.","title":"I ported native guitar plugins to JavaScript (in-depth)"},{"location":"manual/community/#using-faust-with-the-arduino-audio-tools-library","text":"A blog about using Faust with Arduino Audio Tools.","title":"Using Faust with the Arduino Audio Tools Library"},{"location":"manual/community/#writing-a-slew-limiter-in-the-faust-language","text":"A video about writing a Slew Limiter in the Faust Language by Julius Smith.","title":"Writing a Slew Limiter in the Faust Language"},{"location":"manual/community/#make-an-eight-channel-mixer-in-the-faust-ide","text":"A video about making an Eight Channel Mixer in the Faust IDE by Julius Smith.","title":"Make an Eight Channel Mixer in the Faust IDE"},{"location":"manual/community/#creating-vsts-and-more-using-faust","text":"FAUST is a programming language that enables us to quickly create cross-platform DSP code. We can easily create VST plugins, Max-Externals and more. Its high-quality built-in library of effects and tools enables us to quickly draft high quality audio processing devices. The workshop aims at getting new users started, conveying what FAUST is good for and how to use it effectively to produce high quality results quickly.","title":"Creating VSTs and more using FAUST"},{"location":"manual/community/#various-tools","text":"","title":"Various Tools"},{"location":"manual/community/#syntax-highlighting","text":"","title":"Syntax Highlighting"},{"location":"manual/community/#tree-sitter-faust","text":"Tree-sitter grammar Faust. Every Faust syntax feature should be supported. The npm package is here .","title":"tree-sitter-faust"},{"location":"manual/community/#syntax-highlighting-files","text":"This folder contains syntax highlighting files for various editors.","title":"Syntax Highlighting Files"},{"location":"manual/community/#sublime-text-syntax","text":"Sublime Text syntax file for the Faust programming language.","title":"Sublime Text syntax"},{"location":"manual/community/#faust-mode","text":"Major Emacs mode for the Faust programming language, featuring syntax highlighting, automatic indentation and auto-completion.","title":"Faust-Mode"},{"location":"manual/community/#faustine","text":"Faustine allows the edition of Faust code using emacs.","title":"Faustine"},{"location":"manual/community/#faust-neovim-plugin","text":"Plugin to edit Faust code in the hyperextensible Vim-based text editor neowim .","title":"faust neovim plugin"},{"location":"manual/community/#code-generators","text":"","title":"Code Generators"},{"location":"manual/community/#faust2pdex","text":"Generator of Faust wrappers for Pure Data. This software wraps the C++ code generated by Faust into a native external for Pure Data. You obtain a piece of source code that you can use with pd-lib-builder to produce a native binary with the help of make. No knowledge of C++ programming is required.","title":"faust2pdex"},{"location":"manual/community/#faustquark","text":"This SuperCollider package makes it possible to create SuperCollider packages (Quarks) containing plugins written in Faust code. With this, you can distribute plugins written in Faust and make it easy for others to install, compile or uninstall them. It also contains some simple interfaces for the faust and faust2sc.py commands used behind the scenes.","title":"Faust.quark"},{"location":"manual/community/#ode2dsp","text":"ode2dsp is a Python library for generating ordinary differential equation (ODE) solvers in digital signal processing (DSP) languages. It automates the tedious and error-prone symbolic calculations involved in creating a DSP model of an ODE. Features: Support linear and nonlinear systems of ODEs Support trapezoidal and backward Euler discrete-time integral approximations Approximate solutions of implicit equations using Newton's method Render finite difference equations (FDEs) to Faust code Calculate stability of ODEs and FDEs at an operating point","title":"ode2dsp"},{"location":"manual/community/#contributing","text":"Feel free to contribute by forking this project and creating a pull request , or by mailing the library description here .","title":"Contributing"},{"location":"manual/compiler/","text":"Using the Faust Compiler While the Faust compiler is available in different forms (e.g., Embedded Compiler , etc.), its most \"common\" one is the command line version, which can be invoked using the faust command. It translates a Faust program into code in a wide range of languages (C, C++, Rust, LLVM IR, WebAssembly, etc.). The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. A typical call of the Faust command line compiler is: faust [OPTIONS] faustFile.dsp The Faust compiler outputs C++ code by default therefore running: faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to reroute the standard output to a file: faust noise.dsp -o noise.cpp The -a option allows us to wrap the generated code into an architecture file: faust -a alsa-gtk.cpp noise.dsp which can either be placed in the same folder as the current Faust file ( noise.dsp here) or be one of the standard Faust architectures. To compile a Faust program into an ALSA application on Linux, the following commands can be used: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Note that a wide range of faust2... compilation scripts can be used to facilitate this operation by taking a Faust file and returning the corresponding binary for your platform. Structure of the Generated Code A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0; // This method can be called to retrieve the UI description of // the Faust program and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double /*date_usec*/, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Methods are filled by the compiler with the actual code. In the case of noise.dsp : class mydsp : public dsp { private: int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"author\", \"GRAME\"); m->declare(\"filename\", \"noise\"); m->declare(\"name\", \"Noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) {} virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() {} virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((4.65661287e-10f * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; Several fine-grained initialization methods are available: the instanceInit method calls several additional initialization methods. the instanceConstants method sets the instance constant state. the instanceClear method resets the instance dynamic state (delay lines...). the instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The init method combines class static state and instance initialization. When using a single instance, calling init is the simplest way to do \"what is needed.\" When using several instances, all of them can be initialized using instanceInit , with a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. Controlling Code Generation Several options of the Faust compiler allow to control the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code. Vector Code Generation Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 or 8 simple precision floating point numbers, leading to a theoretical speedup of 4 or 8. Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular, complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size <n> controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: The corresponding compute() method generated in scalar mode is the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { int iTemp0 = int((1048576.0f * mydsp_faustpower2_f(float(input0[i])))); iVec0[(IOTA & 1023)] = iTemp0; iRec0[0] = ((iRec0[1] + iTemp0) - iVec0[((IOTA - 1000) & 1023)]); output0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[0])))); IOTA = (IOTA + 1); iRec0[1] = iRec0[0]; } } The -vec option leads to the following reorganization of the code: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; FAUSTFLOAT* fInput0 = 0; fOutput0_ptr = outputs[0]; FAUSTFLOAT* fOutput0 = 0; int iRec0_tmp[36]; int* iRec0 = &iRec0_tmp[4]; int fullcount = count; int index = 0; /* Main loop */ for (index = 0; (index <= (fullcount - 32)); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = 32; /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } /* Remaining frames */ if (index < fullcount) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = (fullcount - index); /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f * mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. With the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2 , the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! The vector code generation is built on top of the scalar code generation (see previous figure). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see figure below). This graph is stored in the class object and a topological sort is applied to it before printing the code. Parallel Code Generation Parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option . It implies that the -vec option as well as the parallel code generation are built on top of the vector code generation. The OpenMP Code Generator The --openMP (or -omp ) option , when given to the Faust compiler, will insert appropriate OpenMP directives into the C++ code. OpenMP is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure above). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region, a group of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel group until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by every thread of the parallel // team ... } In order not to have every thread doing redundantly the exact same work, OpenMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... } Adding Open MP Directives As said before, parallel code generation is built on top of vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code } Example of Parallel OpenMP Code To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder: The corresponding compute() method obtained using the -omp option looks like this: virtual void compute(int fullcount, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { float fRec0_tmp[36]; float fRec1_tmp[36]; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; #pragma omp parallel\\ firstprivate(fInput0, fInput1, fOutput0, fRec0, fRec1) { for (int index = 0; (index < fullcount); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fInput1 = &fInput1_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = min(32, (fullcount - index)); #pragma omp sections { #pragma omp section { /* Recursive loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } } #pragma omp section { /* Recursive loop 1 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } } } #pragma omp single { /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } } } } } This code requires some comments: the parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1 . The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. the top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between threads. please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. the work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). the work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. the loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. finally #pragma omp single indicates that this section will be executed by only one thread (any of them). The Scheduler Code Generator With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separate computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large sub-tree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers, and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future. Example of Parallel Scheduler Code To illustrate how Faust generates the scheduler code, let's reuse the previous example made of two 1-pole filters in parallel connected to an adder: When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; fCount = count; fIndex = 0; /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in each thread WSQ */ initTaskList(fScheduler, -1); signalAll(fScheduler); computeThread(0); syncAll(fScheduler); } void computeThread(int num_thread) { int count = fCount; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; int tasknum = 0; while ((fIndex < fCount)) { fInput0 = &fInput0_ptr[fIndex]; fInput1 = &fInput1_ptr[fIndex]; fOutput0 = &fOutput0_ptr[fIndex]; count = min(32, (fCount - fIndex)); switch (tasknum) { case 0: { /* Work Stealing task */ tasknum = getNextTask(fScheduler, num_thread); break; } case 1: { /* Last task */ fIndex = (fIndex + 32); if (fIndex < fCount) { /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in 'num_thread' WSQ */ initTaskList(fScheduler, num_thread); } tasknum = 0; break; } case 2: { /* Recursive loop 2 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 3: { /* Recursive loop 3 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 4: { /* Vectorizable loop 4 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } tasknum = 1; break; } } } }","title":"Using the Compiler"},{"location":"manual/compiler/#using-the-faust-compiler","text":"While the Faust compiler is available in different forms (e.g., Embedded Compiler , etc.), its most \"common\" one is the command line version, which can be invoked using the faust command. It translates a Faust program into code in a wide range of languages (C, C++, Rust, LLVM IR, WebAssembly, etc.). The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. A typical call of the Faust command line compiler is: faust [OPTIONS] faustFile.dsp The Faust compiler outputs C++ code by default therefore running: faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to reroute the standard output to a file: faust noise.dsp -o noise.cpp The -a option allows us to wrap the generated code into an architecture file: faust -a alsa-gtk.cpp noise.dsp which can either be placed in the same folder as the current Faust file ( noise.dsp here) or be one of the standard Faust architectures. To compile a Faust program into an ALSA application on Linux, the following commands can be used: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Note that a wide range of faust2... compilation scripts can be used to facilitate this operation by taking a Faust file and returning the corresponding binary for your platform.","title":"Using the Faust Compiler"},{"location":"manual/compiler/#structure-of-the-generated-code","text":"A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0; // This method can be called to retrieve the UI description of // the Faust program and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double /*date_usec*/, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Methods are filled by the compiler with the actual code. In the case of noise.dsp : class mydsp : public dsp { private: int iRec0[2]; int fSampleRate; public: void metadata(Meta* m) { m->declare(\"author\", \"GRAME\"); m->declare(\"filename\", \"noise\"); m->declare(\"name\", \"Noise\"); m->declare(\"noises.lib/name\", \"Faust Noise Generator Library\"); m->declare(\"noises.lib/version\", \"0.0\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) {} virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() {} virtual void instanceClear() { for (int l0 = 0; (l0 < 2); l0 = (l0 + 1)) { iRec0[l0] = 0; } } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->closeBox(); } virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = FAUSTFLOAT((4.65661287e-10f * float(iRec0[0]))); iRec0[1] = iRec0[0]; } } }; Several fine-grained initialization methods are available: the instanceInit method calls several additional initialization methods. the instanceConstants method sets the instance constant state. the instanceClear method resets the instance dynamic state (delay lines...). the instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The init method combines class static state and instance initialization. When using a single instance, calling init is the simplest way to do \"what is needed.\" When using several instances, all of them can be initialized using instanceInit , with a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type.","title":"Structure of the Generated Code"},{"location":"manual/compiler/#controlling-code-generation","text":"Several options of the Faust compiler allow to control the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code.","title":"Controlling Code Generation"},{"location":"manual/compiler/#vector-code-generation","text":"Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 or 8 simple precision floating point numbers, leading to a theoretical speedup of 4 or 8. Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular, complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size <n> controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: The corresponding compute() method generated in scalar mode is the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i = 0; (i < count); i = (i + 1)) { int iTemp0 = int((1048576.0f * mydsp_faustpower2_f(float(input0[i])))); iVec0[(IOTA & 1023)] = iTemp0; iRec0[0] = ((iRec0[1] + iTemp0) - iVec0[((IOTA - 1000) & 1023)]); output0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[0])))); IOTA = (IOTA + 1); iRec0[1] = iRec0[0]; } } The -vec option leads to the following reorganization of the code: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; FAUSTFLOAT* fInput0 = 0; fOutput0_ptr = outputs[0]; FAUSTFLOAT* fOutput0 = 0; int iRec0_tmp[36]; int* iRec0 = &iRec0_tmp[4]; int fullcount = count; int index = 0; /* Main loop */ for (index = 0; (index <= (fullcount - 32)); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = 32; /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } /* Remaining frames */ if (index < fullcount) { fInput0 = &fInput0_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = (fullcount - index); /* Vectorizable loop 0 */ /* Pre code */ iYec0_idx = ((iYec0_idx + iYec0_idx_save) & 2047); /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iYec0[((i + iYec0_idx) & 2047)] = int((1048576.0f * mydsp_faustpower2_f(float(fInput0[i])))); } /* Post code */ iYec0_idx_save = count; /* Recursive loop 1 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { iRec0_tmp[j0] = iRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { iRec0[i] = ((iRec0[(i - 1)] + iYec0[((i + iYec0_idx) & 2047)]) - iYec0[(((i + iYec0_idx) - 1000) & 2047)]); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { iRec0_perm[j] = iRec0_tmp[(count + j)]; } /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT(std::sqrt((9.53674362e-10f * float(iRec0[i])))); } } } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. With the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2 , the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! The vector code generation is built on top of the scalar code generation (see previous figure). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see figure below). This graph is stored in the class object and a topological sort is applied to it before printing the code.","title":"Vector Code Generation"},{"location":"manual/compiler/#parallel-code-generation","text":"Parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option . It implies that the -vec option as well as the parallel code generation are built on top of the vector code generation.","title":"Parallel Code Generation"},{"location":"manual/compiler/#the-openmp-code-generator","text":"The --openMP (or -omp ) option , when given to the Faust compiler, will insert appropriate OpenMP directives into the C++ code. OpenMP is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure above). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region, a group of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel group until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by every thread of the parallel // team ... } In order not to have every thread doing redundantly the exact same work, OpenMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... }","title":"The OpenMP Code Generator"},{"location":"manual/compiler/#adding-open-mp-directives","text":"As said before, parallel code generation is built on top of vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code }","title":"Adding Open MP Directives"},{"location":"manual/compiler/#example-of-parallel-openmp-code","text":"To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder: The corresponding compute() method obtained using the -omp option looks like this: virtual void compute(int fullcount, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { float fRec0_tmp[36]; float fRec1_tmp[36]; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; #pragma omp parallel\\ firstprivate(fInput0, fInput1, fOutput0, fRec0, fRec1) { for (int index = 0; (index < fullcount); index = (index + 32)) { fInput0 = &fInput0_ptr[index]; fInput1 = &fInput1_ptr[index]; fOutput0 = &fOutput0_ptr[index]; int count = min(32, (fullcount - index)); #pragma omp sections { #pragma omp section { /* Recursive loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } } #pragma omp section { /* Recursive loop 1 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } } } #pragma omp single { /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } } } } } This code requires some comments: the parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1 . The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. the top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between threads. please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. the work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). the work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. the loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. finally #pragma omp single indicates that this section will be executed by only one thread (any of them).","title":"Example of Parallel OpenMP Code"},{"location":"manual/compiler/#the-scheduler-code-generator","text":"With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separate computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large sub-tree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers, and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future.","title":"The Scheduler Code Generator"},{"location":"manual/compiler/#example-of-parallel-scheduler-code","text":"To illustrate how Faust generates the scheduler code, let's reuse the previous example made of two 1-pole filters in parallel connected to an adder: When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { fInput0_ptr = inputs[0]; fInput1_ptr = inputs[1]; fOutput0_ptr = outputs[0]; fCount = count; fIndex = 0; /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in each thread WSQ */ initTaskList(fScheduler, -1); signalAll(fScheduler); computeThread(0); syncAll(fScheduler); } void computeThread(int num_thread) { int count = fCount; FAUSTFLOAT* fInput0 = 0; FAUSTFLOAT* fInput1 = 0; FAUSTFLOAT* fOutput0 = 0; int tasknum = 0; while ((fIndex < fCount)) { fInput0 = &fInput0_ptr[fIndex]; fInput1 = &fInput1_ptr[fIndex]; fOutput0 = &fOutput0_ptr[fIndex]; count = min(32, (fCount - fIndex)); switch (tasknum) { case 0: { /* Work Stealing task */ tasknum = getNextTask(fScheduler, num_thread); break; } case 1: { /* Last task */ fIndex = (fIndex + 32); if (fIndex < fCount) { /* End task has only one input, so will be directly activated */ /* Only initialize tasks with more than one input */ initTask(fScheduler, 4, 2); /* Push ready tasks in 'num_thread' WSQ */ initTaskList(fScheduler, num_thread); } tasknum = 0; break; } case 2: { /* Recursive loop 2 */ /* Pre code */ for (int j0 = 0; (j0 < 4); j0 = (j0 + 1)) { fRec0_tmp[j0] = fRec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec0[i] = ((0.899999976f * fRec0[(i - 1)]) + (0.100000001f * float(fInput0[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec0_perm[j] = fRec0_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 3: { /* Recursive loop 3 */ /* Pre code */ for (int j1 = 0; (j1 < 4); j1 = (j1 + 1)) { fRec1_tmp[j1] = fRec1_perm[j1]; } /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fRec1[i] = ((0.899999976f * fRec1[(i - 1)]) + (0.100000001f * float(fInput1[i]))); } /* Post code */ for (int j = 0; (j < 4); j = (j + 1)) { fRec1_perm[j] = fRec1_tmp[(count + j)]; } /* One output only */ activateOneOutputTask(fScheduler, num_thread, 4, &tasknum); break; } case 4: { /* Vectorizable loop 4 */ /* Compute code */ for (int i = 0; (i < count); i = (i + 1)) { fOutput0[i] = FAUSTFLOAT((fRec0[i] + fRec1[i])); } tasknum = 1; break; } } } }","title":"Example of Parallel Scheduler Code"},{"location":"manual/debugging/","text":"Debugging the Code Looking at the generated code Using the FIR backend The FIR (Faust Imperative Representation) backend can possibly be used to look at a textual version of the intermediate imperative language. Use the make developer target to compile the FIR backend, then use faust -lang fir foo.dsp to compile a given foo.dsp file as a FIR textual output. import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq1 = hslider(\"freq1 [unit:Hz]\", 1000, 20, 3000, 1); freq2 = hslider(\"freq2 [unit:Hz]\", 200, 20, 3000, 1); process = vgroup(\"Oscillator\", os.osc(freq1) * vol, os.osc(freq2) * vol); For instance compiling the previous code with the faust -lang fir osc.dsp command will display various statistics, for example the number of operations done in the generated compute method: ======= Compute DSP begin ========== Instructions complexity : Load = 23 Store = 9 Binop = 12 [ { Int(+) = 1 } { Int(<) = 1 } { Real(*) = 3 } { Real(+) = 5 } { Real(-) = 2 } ] Mathop = 2 [ { floorf = 2 } ] Numbers = 8 Declare = 1 Cast = 2 Select = 0 Loop = 1 As well as the DSP structure memory size and layout, and read/write statistics: ======= Object memory footprint ========== Heap size int = 4 bytes Heap size int* = 0 bytes Heap size real = 48 bytes Total heap size = 68 bytes Stack size in compute = 28 bytes ======= Variable access in compute control ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 1 w_count = 0 Field = fHslider0 size = 1 r_count = 1 w_count = 0 Field = fConst2 size = 1 r_count = 0 w_count = 0 Field = fRec0 size = 2 r_count = 0 w_count = 0 Field = fConst3 size = 1 r_count = 2 w_count = 0 Field = fHslider1 size = 1 r_count = 1 w_count = 0 Field = fRec2 size = 2 r_count = 0 w_count = 0 Field = fHslider2 size = 1 r_count = 1 w_count = 0 Field = fRec3 size = 2 r_count = 0 w_count = 0 ======= Variable access in compute DSP ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 0 w_count = 0 Field = fHslider0 size = 1 r_count = 0 w_count = 0 Field = fConst2 size = 1 r_count = 1 w_count = 0 Field = fRec0 size = 2 r_count = 4 w_count = 2 Field = fConst3 size = 1 r_count = 0 w_count = 0 Field = fHslider1 size = 1 r_count = 0 w_count = 0 Field = fRec2 size = 2 r_count = 4 w_count = 2 Field = fHslider2 size = 1 r_count = 0 w_count = 0 Field = fRec3 size = 2 r_count = 4 w_count = 2 Those informations can possibly be used to detect abnormal memory consumption. Debugging the DSP Code On a computer, doing a computation that is undefined in mathematics (like val/0 or log(-1) ), and unrepresentable in floating-point arithmetic, will produce a NaN value, which has a special internal representation . Similarly, some computations will exceed the range that is representable with floating-point arithmetics, and are represented with a special INFINITY value, which value depends of the chosen type (like float , double or long double ). After being produced, those values can actually contaminate the following flow of computations (that is Nan + any value = NaN for instance) up to the point of producing incorrect indexes when used in array access, and causing memory access crashes. The Faust compiler gives error messages when the written code is not syntactically or semantically correct, and the interval computation system on signals is supposed to detect possible problematic computations at compile time, and refuse to compile the corresponding DSP code. But the interval calculation is currently quite imperfect , can misbehave, and possibly allow problematic code to be generated. Several strategies have been developed to help programmers better understand their written DSP code, and possibly analyse it, both at compile time and runtime. Debugging at compile time The -ct option Using the -ct compilation option allows to check table index range and generate safe table access code. It verifies that the signal range is compatible with the table size, and if needed, generate safe read and write indexes access code, by constraining them to stay in a given [0.. size-1] range. Note that since the signal interval calculation is imperfect, you may see false positives , and unneeded range constraining code might be generated, especially when using recursive signals where the interval calculation system will typically produce [-inf, inf] range, which is not precise enough to correctly describe the real signal range. The -me option Starting with version 2.37.0, mathematical functions which have a finite domain (like sqrt defined for positive or null values, or asin defined for values in the [-1..1] range) are checked at compile time when they actually compute values at that time , and raise an error if the program tries to compute an out-of-domain value. If those functions appear in the generated code, their domain of use can also be checked (using the interval computation system) and the -me option will display warnings if the domain of use is incorrect. Note that again because of the imperfect interval computation system, false positives may appear and should be checked. Warning messages Warning messages do not stop the compilation process, but allow to get useful informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used. Debugging at runtime The interp-tracer tool The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL , FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW , CAST_INT_OVERFLOW and DIV_BY_ZERO operations, or LOAD/STORE errors. See the complete documentation and the Advanced debugging with interp-tracer tutorial. The faust2caqt tool On macOS, the faust2caqt script has a -me option to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow, etc.) at runtime. Developers can possibly use the dsp_me_checker class to decorate a given DSP object with the math computation exception handling code. Fixing the errors These errors must then be corrected by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items. Additional Resources Note that the Faust math library contains the implementation of isnan and isinf functions that may help during development. Handling infinity and not-a-number (NaN) the right way still remains a tricky problem that is not completely handled in the current version of the compiler. Dario Sanfilippo blog post is a very helpful summary of the situation with a lot of practical solutions to write safer DSP code .","title":"Debugging the Code"},{"location":"manual/debugging/#debugging-the-code","text":"","title":"Debugging the Code"},{"location":"manual/debugging/#looking-at-the-generated-code","text":"","title":"Looking at the generated code"},{"location":"manual/debugging/#using-the-fir-backend","text":"The FIR (Faust Imperative Representation) backend can possibly be used to look at a textual version of the intermediate imperative language. Use the make developer target to compile the FIR backend, then use faust -lang fir foo.dsp to compile a given foo.dsp file as a FIR textual output. import(\"stdfaust.lib\"); vol = hslider(\"volume [unit:dB]\", 0, -96, 0, 0.1) : ba.db2linear : si.smoo; freq1 = hslider(\"freq1 [unit:Hz]\", 1000, 20, 3000, 1); freq2 = hslider(\"freq2 [unit:Hz]\", 200, 20, 3000, 1); process = vgroup(\"Oscillator\", os.osc(freq1) * vol, os.osc(freq2) * vol); For instance compiling the previous code with the faust -lang fir osc.dsp command will display various statistics, for example the number of operations done in the generated compute method: ======= Compute DSP begin ========== Instructions complexity : Load = 23 Store = 9 Binop = 12 [ { Int(+) = 1 } { Int(<) = 1 } { Real(*) = 3 } { Real(+) = 5 } { Real(-) = 2 } ] Mathop = 2 [ { floorf = 2 } ] Numbers = 8 Declare = 1 Cast = 2 Select = 0 Loop = 1 As well as the DSP structure memory size and layout, and read/write statistics: ======= Object memory footprint ========== Heap size int = 4 bytes Heap size int* = 0 bytes Heap size real = 48 bytes Total heap size = 68 bytes Stack size in compute = 28 bytes ======= Variable access in compute control ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 1 w_count = 0 Field = fHslider0 size = 1 r_count = 1 w_count = 0 Field = fConst2 size = 1 r_count = 0 w_count = 0 Field = fRec0 size = 2 r_count = 0 w_count = 0 Field = fConst3 size = 1 r_count = 2 w_count = 0 Field = fHslider1 size = 1 r_count = 1 w_count = 0 Field = fRec2 size = 2 r_count = 0 w_count = 0 Field = fHslider2 size = 1 r_count = 1 w_count = 0 Field = fRec3 size = 2 r_count = 0 w_count = 0 ======= Variable access in compute DSP ========== Field = fSampleRate size = 1 r_count = 0 w_count = 0 Field = fConst1 size = 1 r_count = 0 w_count = 0 Field = fHslider0 size = 1 r_count = 0 w_count = 0 Field = fConst2 size = 1 r_count = 1 w_count = 0 Field = fRec0 size = 2 r_count = 4 w_count = 2 Field = fConst3 size = 1 r_count = 0 w_count = 0 Field = fHslider1 size = 1 r_count = 0 w_count = 0 Field = fRec2 size = 2 r_count = 4 w_count = 2 Field = fHslider2 size = 1 r_count = 0 w_count = 0 Field = fRec3 size = 2 r_count = 4 w_count = 2 Those informations can possibly be used to detect abnormal memory consumption.","title":"Using the FIR backend"},{"location":"manual/debugging/#debugging-the-dsp-code","text":"On a computer, doing a computation that is undefined in mathematics (like val/0 or log(-1) ), and unrepresentable in floating-point arithmetic, will produce a NaN value, which has a special internal representation . Similarly, some computations will exceed the range that is representable with floating-point arithmetics, and are represented with a special INFINITY value, which value depends of the chosen type (like float , double or long double ). After being produced, those values can actually contaminate the following flow of computations (that is Nan + any value = NaN for instance) up to the point of producing incorrect indexes when used in array access, and causing memory access crashes. The Faust compiler gives error messages when the written code is not syntactically or semantically correct, and the interval computation system on signals is supposed to detect possible problematic computations at compile time, and refuse to compile the corresponding DSP code. But the interval calculation is currently quite imperfect , can misbehave, and possibly allow problematic code to be generated. Several strategies have been developed to help programmers better understand their written DSP code, and possibly analyse it, both at compile time and runtime.","title":"Debugging the DSP Code"},{"location":"manual/debugging/#debugging-at-compile-time","text":"","title":"Debugging at compile time"},{"location":"manual/debugging/#the-ct-option","text":"Using the -ct compilation option allows to check table index range and generate safe table access code. It verifies that the signal range is compatible with the table size, and if needed, generate safe read and write indexes access code, by constraining them to stay in a given [0.. size-1] range. Note that since the signal interval calculation is imperfect, you may see false positives , and unneeded range constraining code might be generated, especially when using recursive signals where the interval calculation system will typically produce [-inf, inf] range, which is not precise enough to correctly describe the real signal range.","title":"The -ct option"},{"location":"manual/debugging/#the-me-option","text":"Starting with version 2.37.0, mathematical functions which have a finite domain (like sqrt defined for positive or null values, or asin defined for values in the [-1..1] range) are checked at compile time when they actually compute values at that time , and raise an error if the program tries to compute an out-of-domain value. If those functions appear in the generated code, their domain of use can also be checked (using the interval computation system) and the -me option will display warnings if the domain of use is incorrect. Note that again because of the imperfect interval computation system, false positives may appear and should be checked.","title":"The -me option"},{"location":"manual/debugging/#warning-messages","text":"Warning messages do not stop the compilation process, but allow to get useful informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Warning messages"},{"location":"manual/debugging/#debugging-at-runtime","text":"","title":"Debugging at runtime"},{"location":"manual/debugging/#the-interp-tracer-tool","text":"The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL , FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW , CAST_INT_OVERFLOW and DIV_BY_ZERO operations, or LOAD/STORE errors. See the complete documentation and the Advanced debugging with interp-tracer tutorial.","title":"The interp-tracer tool"},{"location":"manual/debugging/#the-faust2caqt-tool","text":"On macOS, the faust2caqt script has a -me option to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow, etc.) at runtime. Developers can possibly use the dsp_me_checker class to decorate a given DSP object with the math computation exception handling code.","title":"The faust2caqt tool"},{"location":"manual/debugging/#fixing-the-errors","text":"These errors must then be corrected by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items.","title":"Fixing the errors"},{"location":"manual/debugging/#additional-resources","text":"Note that the Faust math library contains the implementation of isnan and isinf functions that may help during development. Handling infinity and not-a-number (NaN) the right way still remains a tricky problem that is not completely handled in the current version of the compiler. Dario Sanfilippo blog post is a very helpful summary of the situation with a lot of practical solutions to write safer DSP code .","title":"Additional Resources"},{"location":"manual/deploying/","text":"Deploying Faust DSP on the Web Using developments done for the Web (WebAssembly backends and libfaust library compiled in WebAssembly with Emscripten ), statically and dynamically Faust generated WebAudio nodes can be easily produced and deployed on the Web. See extended documentation here . Note : this model will soon be deprecated, better use the faustwasm package . Note : the faust2cpp2wasm tool can possibly be used as a drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend. The faustwasm package The FaustWasm library presents a convenient, high-level API that wraps around Faust compiler. This library's interface is primarily designed for TypeScript usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both Node.js and web browsers, has been compiled using Emscripten 3.1.31. The library offers functionality for compiling Faust DSP code into WebAssembly, enabling its utilization as WebAudio nodes within a standard WebAudio node graph. Moreover, it supports offline rendering scenarios. Furthermore, supplementary tools can be employed for generating SVGs from Faust DSP programs. Exporting for the Web Web targets can be exported from the Faust Editor or Faust IDE using the remote compilation service. Choose Platform = web , then Architecture with one of the following target: wasmjs allows you to export a ready to use Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. wasmjs-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. webaudiowasm allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. webaudiowasm-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. pwa allows you to export a ready to use Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. pwa-poly allows you to export a ready to use polyphonic MIDI controllable Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. Exporting WAM 2.0 plugins WAM 2.0 plugin can be exported from the Faust Editor or Faust IDE using the remote compilation service. A complete tutorial can be found here . Choose Platform = web , then Architecture with one of the following target: wam2-ts allows you to export a ready to use WAM 2.0 plugin. wam2-poly-ts allows you to export a ready to use polyphonic MIDI controllable WAM 2.0 plugin. wam2-fft-ts allows you to export a ready to use WAM 2.0 plugin using the FFT architecture presented in this paper . The faust-web-component package Tthe faust-web-component package provides two web components for embedding interactive Faust snippets in web pages: <faust-editor> displays an editor (using CodeMirror 6 ) with executable, editable Faust code, along with some bells & whistles (controls, block diagram, plots) in a side pane. This component is ideal for demonstrating some code in Faust and allowing the reader to try it out and tweak it themselves without having to leave the page, and can been tested here . <faust-widget> just shows the controls and does not allow editing, so it serves simply as a way to embed interactive DSP, and can been tested here . These components are built on top of faustwasm and faust-ui packages and is released as a npm package .","title":"Deploying on the Web"},{"location":"manual/deploying/#deploying-faust-dsp-on-the-web","text":"Using developments done for the Web (WebAssembly backends and libfaust library compiled in WebAssembly with Emscripten ), statically and dynamically Faust generated WebAudio nodes can be easily produced and deployed on the Web. See extended documentation here . Note : this model will soon be deprecated, better use the faustwasm package . Note : the faust2cpp2wasm tool can possibly be used as a drop in replacement for the wasm file generated by faust2wasm , but with Faust's C++ backend instead of its wasm backend.","title":"Deploying Faust DSP on the Web"},{"location":"manual/deploying/#the-faustwasm-package","text":"The FaustWasm library presents a convenient, high-level API that wraps around Faust compiler. This library's interface is primarily designed for TypeScript usage, although it also provides API descriptions and documentation for pure JavaScript. The WebAssembly version of the Faust Compiler, compatible with both Node.js and web browsers, has been compiled using Emscripten 3.1.31. The library offers functionality for compiling Faust DSP code into WebAssembly, enabling its utilization as WebAudio nodes within a standard WebAudio node graph. Moreover, it supports offline rendering scenarios. Furthermore, supplementary tools can be employed for generating SVGs from Faust DSP programs.","title":"The faustwasm package"},{"location":"manual/deploying/#exporting-for-the-web","text":"Web targets can be exported from the Faust Editor or Faust IDE using the remote compilation service. Choose Platform = web , then Architecture with one of the following target: wasmjs allows you to export a ready to use Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. wasmjs-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. webaudiowasm allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. webaudiowasm-poly allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a Progressive Web Application . An example of HTML and JavaScript files demonstrates how the node can be loaded and activated. pwa allows you to export a ready to use Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code. pwa-poly allows you to export a ready to use polyphonic MIDI controllable Progressive Web Application with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code.","title":"Exporting for the Web"},{"location":"manual/deploying/#exporting-wam-20-plugins","text":"WAM 2.0 plugin can be exported from the Faust Editor or Faust IDE using the remote compilation service. A complete tutorial can be found here . Choose Platform = web , then Architecture with one of the following target: wam2-ts allows you to export a ready to use WAM 2.0 plugin. wam2-poly-ts allows you to export a ready to use polyphonic MIDI controllable WAM 2.0 plugin. wam2-fft-ts allows you to export a ready to use WAM 2.0 plugin using the FFT architecture presented in this paper .","title":"Exporting WAM 2.0 plugins"},{"location":"manual/deploying/#the-faust-web-component-package","text":"Tthe faust-web-component package provides two web components for embedding interactive Faust snippets in web pages: <faust-editor> displays an editor (using CodeMirror 6 ) with executable, editable Faust code, along with some bells & whistles (controls, block diagram, plots) in a side pane. This component is ideal for demonstrating some code in Faust and allowing the reader to try it out and tweak it themselves without having to leave the page, and can been tested here . <faust-widget> just shows the controls and does not allow editing, so it serves simply as a way to embed interactive DSP, and can been tested here . These components are built on top of faustwasm and faust-ui packages and is released as a npm package .","title":"The faust-web-component package"},{"location":"manual/embedding/","text":"Embedding the Faust Compiler Using libfaust Dynamic Compilation Chain The Faust compiler uses an intermediate FIR representation (Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures ( for and while loops, if structure, etc.). To generate various output languages, several backends have been developed for C, C++, Interpreter, Java, LLVM IR, WebAssembly, etc. The Interpreter, LLVM IR and WebAssembly ones are particularly interesting since they allow the direct compilation of a DSP program into executable code in memory, bypassing the external compiler requirement. Using libfaust with the LLVM backend Libfaust with LLVM backend API The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file-based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. Creation API The libfaust library exports the following API: given a Faust source code (as a string or a file), calling the createDSPFactoryFromString or createDSPFactoryFromFile functions runs the compilation chain (Faust + LLVM JIT) and generates the prototype of the class, as a llvm_dsp_factory pointer. This factory actually contains the compiled LLVM IR for the given DSP alternatively the createCPPDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance function (corresponding to the new className of C++) instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed a unique SHA1 key of the created factory can be obtained using its getSHAKey method Saving/restoring the factory After the DSP factory has been compiled, the application or the plugin running it might need to save it and then restore it. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR : get the DSP factory LLVM IR (in textual format) as a string writeDSPFactoryToIRFile : get the DSP factory LLVM IR (in textual format) and write it to a file writeDSPFactoryToBitcode : get the DSP factory LLVM IR (in binary format) as a string writeDSPFactoryToBitcodeFile : save the DSP factory LLVM IR (in binary format) in a file writeDSPFactoryToMachine : get the DSP factory executable machine code as a string writeDSPFactoryToMachineFile : save the DSP factory executable machine code in a file To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR : create a DSP factory from a string containing the LLVM IR (in textual format) readDSPFactoryFromIRFile : create a DSP factory from a file containing the LLVM IR (in textual format) readDSPFactoryFromBitcode : create a DSP factory from a string containing the LLVM IR (in binary format) readDSPFactoryFromBitcodeFile : create a DSP factory from a file containing the LLVM IR (in binary format) readDSPFactoryFromMachine : create a DSP factory from a string containing the executable machine code readDSPFactoryFromMachineFile : create a DSP factory from a file containing the executable machine code. Typical code example More generally, a typical use of libfaust in C++ could look like: // The Faust code to compile as a string (could be in a file too) string theCode = \"import(\\\"stdfaust.lib\\\"); process = no.noise;\"; // Compiling in memory (createDSPFactoryFromFile could be used alternatively) llvm_dsp_factory* m_factory = createDSPFactoryFromString( \"faust\", theCode, argc, argv, \"\", m_errorString, optimize); // creating the DSP instance for interfacing dsp* m_dsp = m_factory->createDSPInstance(); // Creating a generic UI to interact with the DSP my_ui* m_ui = new MyUI(); // linking the interface to the DSP instance m_dsp->buildUserInterface(m_ui); // Initializing the DSP instance with the SR m_dsp->init(44100); // Hypothetical audio callback, assuming m_input/m_output are previously allocated while (...) { m_dsp->compute(128, m_input, m_output); } // Cleaning // Manually delete the DSP delete m_dsp; delete m_ui; // The factory actually keeps track of all allocated DSP (done in createDSPInstance). // So if not manually deleted, all remaining DSP will be garbaged here. deleteDSPFactory(m_factory); The first step consists in creating a DSP factory from a DSP file (using createDSPFactoryFromFile ) or string (using createDSPFactoryFromString ) with additional parameters given to the compiler. Assuming the compilation works, a factory is returned, to create a DSP instance with the factory createDSPInstance method. Note that the resulting llvm_dsp* pointer type (see faust/dsp/llvm-dsp.h header file) is a subclass of the base dsp class (see faust/dsp/dsp.h header file). Thus it can be used with any UI type to plug a GUI, MIDI or OSC controller on the DSP object, like it would be done with a DSP program compiled to a C++ class (the generated mydsp class is also a subclass of the base dsp class). This is demonstrated with the my_ui* m_ui = new MyUI(); and m_dsp->buildUserInterface(m_ui); lines where the buildUserInterface method is used to connect a controller. Then the DSP object has to be connected to an audio driver to be rendered (see the m_dsp->compute(128, m_input, m_output); block). A more complete C++ example can be found here . A example using the pure C API can be found here . Using libfaust with the Interpreter backend When compiled to embed the Interpreter backend , libfaust can also be used to generate the Faust Bytes Code (FBC) format and interpret it in memory. Libfaust with Interpreter backend API The interpreter backend (described in this paper ) has been first written to allow dynamical compilation on iOS, where Apple does not allow LLVM based JIT compilation to be deployed, but can also be used to develop testing tools . It has been defined as a typed bytecode and a virtual machine to execute it. The FIR language is simple enough to be easily translated in the typed bytecode for an interpreter, generated by a FIR to bytecode compilation pass. The virtual machine then executes the bytecode on a stack based machine. Creation API The interpreter backend API is similar to the LLVM backend API: given a FAUST source code (as a file or a string), calling the createInterpreterDSPFactory function runs the compilation chain (Faust + interpreter backend) and generates the prototype of the class, as an interpreter_dsp_factory pointer. This factory actually contains the compiled bytecode for the given DSP alternatively the createInterpreterDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createInterpreterDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance method of the factory class, corresponding to the new className of C++, instantiates an interpreter_dsp pointer, to be used as any regular Faust compiled DSP object, run and controlled through its interface. The instance contains the interpreter virtual machine loaded with the compiled bytecode, to be executed for each method. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since interpreter_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteInterpreterDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed. a unique SHA1 key of the created factory can be obtained using its getSHAKey method Saving/restoring the factory After the DSP factory has been compiled, the application or plugin may want to save/restore it in order to save Faust to interpreter bytecode compilation at next use. To get the internal factory bytecode and save it, two functions are available: writeInterpreterDSPFactoryToMachine allows to get the interpreter bytecode as a string writeInterpreterDSPFactoryToMachineFile allows to save the interpreter bytecode in a file To re-create a DSP factory from a previously saved code, two functions are available: readInterpreterDSPFactoryFromMachine allows to create a DSP factory from a string containing the interpreter bytecode readInterpreterDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the interpreter bytecode The complete API is available and documented in the installed faust/dsp/interpreter-dsp.h header. Note that only the scalar compilation mode is supported. A more complete C++ example can be found here . Performances The generated code is obviously much slower than LLVM generated native code. Measurements on various DSPs examples have been done, and the code is between 3 and more than 10 times slower than the LLVM native code. Using libfaust with the WebAssembly backend The libfaust C++ library can be compiled in WebAssembly with Emscripten , and used in the web or NodeJS platforms. A specific page on the subject is available. Additional Functions Some additional functions are available in the libfaust API: Expanding the DSP code . The expandDSPFromString / expandDSPFromFile functions can be used to generate a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string. This is a way to create self-contained version of DSP programs. Using other backends or generating auxiliary files . The generateAuxFilesFromString and generateAuxFilesFromFile functions taking a DSP source string or file can be used: to activate and use other backends (depending of which ones have been compiled in libfaust) to generate like C, C++, or Cmajor code, etc. The argv parameter has to mimic the command line like for instance: -lang cpp -vec -lv 1 to generate a C++ file in vector mode. to generate auxiliary files which can be text files SVG, XML, ps, etc. The argv parameter has to mimic the command line like for instance: -json to generate a JSON file. Sample size adaptation When compiled with the -double option, the generated code internally uses double format for samples, but also expects inputs/outputs buffers to be filled with samples in double. The dsp_sample_adapter decorator class defined in faust/dsp/dsp-adapter.h can be used to adapt the buffers. Deployment The application or plugin using libfaust can embed the library either as a statically linked component (to get a self-contained binary) or provided as a separate component to be loaded dynamically at runtime. The Faust libraries themselves usually have to be bundled separately and can be accessed at runtime using the compiler -I /path/to/libraries option in createDSPFactoryFromString/createDSPFactoryFromFile functions. Additional Resources Some papers and tutorials are available: Comment Embarquer le Compilateur Faust dans Vos Applications ? An Overview of the FAUST Developer Ecosystem Using the box API Using the signal API Use Case Examples The dynamic compilation chain has been used in several projects: FaustLive : an integrated IDE for Faust development offering on-the-fly compilation and execution features Faustgen : a generic Faust Max/MSP programmable external object Faustgen : a generic Faust PureData programmable external object The faustgen2~ object is a Faust external for Pd a.k.a. Pure Data, Miller Puckette's interactive multimedia programming environment Faust for Csound : a Csound opcode running the Faust compiler internally LibAudioStream : a framework to manipulate audio ressources through the concept of streams Faust for JUCE : a tool integrating the Faust compiler to JUCE developed by Oliver Larkin and available as part of the pMix2 project An experimental integration of Faust in Antescofo FaucK : the combination of the ChucK Programming Language and Faust libossia is a modern C++, cross-environment distributed object model for creative coding. It is used in Ossia score project Radium is a music editor with a new type of interface, including a Faust audio DSP development environment using libfaust with the LLVM and Interpreter backends Mephisto LV2 is a Just-in-Time Faust compiler embedded in an LV2 plugin, using the C API. gwion-plug is a Faust plugin for the Gwion programming language. FaustGen allows to livecode Faust in SuperCollider. It uses the libfaust LLVM C++ API. FAUSTPy is a Python wrapper for the Faust DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust.jl is Julia wrapper for the Faust compiler. It uses the libfaust LLVM C API. fl-tui is a Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs is another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. DawDreamer is an audio-processing Python framework supporting core DAW features. It uses the libfaust LLVM C API. metaSurface64 is a real-time continuous sound transformation control surface that features both its own loop generator for up to 64 voices and a multi-effects FX engine. It uses the libfaust LLVM C++ API. metaFx is a control surface for continuous sound transformations in real time, just like the metaSurface64. Like metaSurface64, it has both its own loop generator and a multi-effects FX engine, but its operation is different, especially for the management of plugin chains and pads. HISE is an open source framework for building sample based virtual instruments combining a highly performant Disk-Streaming Engine, a flexible DSP-Audio Module system and a handy Interface Designer. AMATI is a VST plugin for live-coding effects in the Faust programming language. cyfaust is a cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. nih-faust-jit ia a plugin written in Rust to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"Embedding the Compiler"},{"location":"manual/embedding/#embedding-the-faust-compiler-using-libfaust","text":"","title":"Embedding the Faust Compiler Using libfaust"},{"location":"manual/embedding/#dynamic-compilation-chain","text":"The Faust compiler uses an intermediate FIR representation (Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures ( for and while loops, if structure, etc.). To generate various output languages, several backends have been developed for C, C++, Interpreter, Java, LLVM IR, WebAssembly, etc. The Interpreter, LLVM IR and WebAssembly ones are particularly interesting since they allow the direct compilation of a DSP program into executable code in memory, bypassing the external compiler requirement.","title":"Dynamic Compilation Chain"},{"location":"manual/embedding/#using-libfaust-with-the-llvm-backend","text":"","title":"Using libfaust with the LLVM backend"},{"location":"manual/embedding/#libfaust-with-llvm-backend-api","text":"The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file-based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters.","title":"Libfaust with LLVM backend API"},{"location":"manual/embedding/#creation-api","text":"The libfaust library exports the following API: given a Faust source code (as a string or a file), calling the createDSPFactoryFromString or createDSPFactoryFromFile functions runs the compilation chain (Faust + LLVM JIT) and generates the prototype of the class, as a llvm_dsp_factory pointer. This factory actually contains the compiled LLVM IR for the given DSP alternatively the createCPPDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance function (corresponding to the new className of C++) instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed a unique SHA1 key of the created factory can be obtained using its getSHAKey method","title":"Creation API"},{"location":"manual/embedding/#savingrestoring-the-factory","text":"After the DSP factory has been compiled, the application or the plugin running it might need to save it and then restore it. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR : get the DSP factory LLVM IR (in textual format) as a string writeDSPFactoryToIRFile : get the DSP factory LLVM IR (in textual format) and write it to a file writeDSPFactoryToBitcode : get the DSP factory LLVM IR (in binary format) as a string writeDSPFactoryToBitcodeFile : save the DSP factory LLVM IR (in binary format) in a file writeDSPFactoryToMachine : get the DSP factory executable machine code as a string writeDSPFactoryToMachineFile : save the DSP factory executable machine code in a file To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR : create a DSP factory from a string containing the LLVM IR (in textual format) readDSPFactoryFromIRFile : create a DSP factory from a file containing the LLVM IR (in textual format) readDSPFactoryFromBitcode : create a DSP factory from a string containing the LLVM IR (in binary format) readDSPFactoryFromBitcodeFile : create a DSP factory from a file containing the LLVM IR (in binary format) readDSPFactoryFromMachine : create a DSP factory from a string containing the executable machine code readDSPFactoryFromMachineFile : create a DSP factory from a file containing the executable machine code.","title":"Saving/restoring the factory"},{"location":"manual/embedding/#typical-code-example","text":"More generally, a typical use of libfaust in C++ could look like: // The Faust code to compile as a string (could be in a file too) string theCode = \"import(\\\"stdfaust.lib\\\"); process = no.noise;\"; // Compiling in memory (createDSPFactoryFromFile could be used alternatively) llvm_dsp_factory* m_factory = createDSPFactoryFromString( \"faust\", theCode, argc, argv, \"\", m_errorString, optimize); // creating the DSP instance for interfacing dsp* m_dsp = m_factory->createDSPInstance(); // Creating a generic UI to interact with the DSP my_ui* m_ui = new MyUI(); // linking the interface to the DSP instance m_dsp->buildUserInterface(m_ui); // Initializing the DSP instance with the SR m_dsp->init(44100); // Hypothetical audio callback, assuming m_input/m_output are previously allocated while (...) { m_dsp->compute(128, m_input, m_output); } // Cleaning // Manually delete the DSP delete m_dsp; delete m_ui; // The factory actually keeps track of all allocated DSP (done in createDSPInstance). // So if not manually deleted, all remaining DSP will be garbaged here. deleteDSPFactory(m_factory); The first step consists in creating a DSP factory from a DSP file (using createDSPFactoryFromFile ) or string (using createDSPFactoryFromString ) with additional parameters given to the compiler. Assuming the compilation works, a factory is returned, to create a DSP instance with the factory createDSPInstance method. Note that the resulting llvm_dsp* pointer type (see faust/dsp/llvm-dsp.h header file) is a subclass of the base dsp class (see faust/dsp/dsp.h header file). Thus it can be used with any UI type to plug a GUI, MIDI or OSC controller on the DSP object, like it would be done with a DSP program compiled to a C++ class (the generated mydsp class is also a subclass of the base dsp class). This is demonstrated with the my_ui* m_ui = new MyUI(); and m_dsp->buildUserInterface(m_ui); lines where the buildUserInterface method is used to connect a controller. Then the DSP object has to be connected to an audio driver to be rendered (see the m_dsp->compute(128, m_input, m_output); block). A more complete C++ example can be found here . A example using the pure C API can be found here .","title":"Typical code example"},{"location":"manual/embedding/#using-libfaust-with-the-interpreter-backend","text":"When compiled to embed the Interpreter backend , libfaust can also be used to generate the Faust Bytes Code (FBC) format and interpret it in memory.","title":"Using libfaust with the Interpreter backend"},{"location":"manual/embedding/#libfaust-with-interpreter-backend-api","text":"The interpreter backend (described in this paper ) has been first written to allow dynamical compilation on iOS, where Apple does not allow LLVM based JIT compilation to be deployed, but can also be used to develop testing tools . It has been defined as a typed bytecode and a virtual machine to execute it. The FIR language is simple enough to be easily translated in the typed bytecode for an interpreter, generated by a FIR to bytecode compilation pass. The virtual machine then executes the bytecode on a stack based machine.","title":"Libfaust with Interpreter backend API"},{"location":"manual/embedding/#creation-api_1","text":"The interpreter backend API is similar to the LLVM backend API: given a FAUST source code (as a file or a string), calling the createInterpreterDSPFactory function runs the compilation chain (Faust + interpreter backend) and generates the prototype of the class, as an interpreter_dsp_factory pointer. This factory actually contains the compiled bytecode for the given DSP alternatively the createInterpreterDSPFactoryFromBoxes allows to create the factory from a box expression built with the box API alternatively the createInterpreterDSPFactoryFromSignals allows to create the factory from a list of outputs signals built with the signal API the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code -- that is the same source code and the same set of normalized (sorted in a canonical order) compilation options -- will return the same (reference counted) factory pointer next, the createDSPInstance method of the factory class, corresponding to the new className of C++, instantiates an interpreter_dsp pointer, to be used as any regular Faust compiled DSP object, run and controlled through its interface. The instance contains the interpreter virtual machine loaded with the compiled bytecode, to be executed for each method. When finished, delete can be used to destroy the dsp instance. Note that an instance internally needs to access its associated factory during its entire lifetime. since interpreter_dsp is a subclass of the dsp base class, an object of this type can be used with all the available audio and UI classes. In essence, this is like reusing all architecture files already developed for the static C++ class compilation scheme like OSCUI , httpdUI interfaces, etc. deleteInterpreterDSPFactory has to be explicitly used to properly decrement the reference counter when the factory is not needed anymore, that is when all associated DSP instances have been properly destroyed. a unique SHA1 key of the created factory can be obtained using its getSHAKey method","title":"Creation API"},{"location":"manual/embedding/#savingrestoring-the-factory_1","text":"After the DSP factory has been compiled, the application or plugin may want to save/restore it in order to save Faust to interpreter bytecode compilation at next use. To get the internal factory bytecode and save it, two functions are available: writeInterpreterDSPFactoryToMachine allows to get the interpreter bytecode as a string writeInterpreterDSPFactoryToMachineFile allows to save the interpreter bytecode in a file To re-create a DSP factory from a previously saved code, two functions are available: readInterpreterDSPFactoryFromMachine allows to create a DSP factory from a string containing the interpreter bytecode readInterpreterDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the interpreter bytecode The complete API is available and documented in the installed faust/dsp/interpreter-dsp.h header. Note that only the scalar compilation mode is supported. A more complete C++ example can be found here .","title":"Saving/restoring the factory"},{"location":"manual/embedding/#performances","text":"The generated code is obviously much slower than LLVM generated native code. Measurements on various DSPs examples have been done, and the code is between 3 and more than 10 times slower than the LLVM native code.","title":"Performances"},{"location":"manual/embedding/#using-libfaust-with-the-webassembly-backend","text":"The libfaust C++ library can be compiled in WebAssembly with Emscripten , and used in the web or NodeJS platforms. A specific page on the subject is available.","title":"Using libfaust with the WebAssembly backend"},{"location":"manual/embedding/#additional-functions","text":"Some additional functions are available in the libfaust API: Expanding the DSP code . The expandDSPFromString / expandDSPFromFile functions can be used to generate a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string. This is a way to create self-contained version of DSP programs. Using other backends or generating auxiliary files . The generateAuxFilesFromString and generateAuxFilesFromFile functions taking a DSP source string or file can be used: to activate and use other backends (depending of which ones have been compiled in libfaust) to generate like C, C++, or Cmajor code, etc. The argv parameter has to mimic the command line like for instance: -lang cpp -vec -lv 1 to generate a C++ file in vector mode. to generate auxiliary files which can be text files SVG, XML, ps, etc. The argv parameter has to mimic the command line like for instance: -json to generate a JSON file.","title":"Additional Functions"},{"location":"manual/embedding/#sample-size-adaptation","text":"When compiled with the -double option, the generated code internally uses double format for samples, but also expects inputs/outputs buffers to be filled with samples in double. The dsp_sample_adapter decorator class defined in faust/dsp/dsp-adapter.h can be used to adapt the buffers.","title":"Sample size adaptation"},{"location":"manual/embedding/#deployment","text":"The application or plugin using libfaust can embed the library either as a statically linked component (to get a self-contained binary) or provided as a separate component to be loaded dynamically at runtime. The Faust libraries themselves usually have to be bundled separately and can be accessed at runtime using the compiler -I /path/to/libraries option in createDSPFactoryFromString/createDSPFactoryFromFile functions.","title":"Deployment"},{"location":"manual/embedding/#additional-resources","text":"Some papers and tutorials are available: Comment Embarquer le Compilateur Faust dans Vos Applications ? An Overview of the FAUST Developer Ecosystem Using the box API Using the signal API","title":"Additional Resources"},{"location":"manual/embedding/#use-case-examples","text":"The dynamic compilation chain has been used in several projects: FaustLive : an integrated IDE for Faust development offering on-the-fly compilation and execution features Faustgen : a generic Faust Max/MSP programmable external object Faustgen : a generic Faust PureData programmable external object The faustgen2~ object is a Faust external for Pd a.k.a. Pure Data, Miller Puckette's interactive multimedia programming environment Faust for Csound : a Csound opcode running the Faust compiler internally LibAudioStream : a framework to manipulate audio ressources through the concept of streams Faust for JUCE : a tool integrating the Faust compiler to JUCE developed by Oliver Larkin and available as part of the pMix2 project An experimental integration of Faust in Antescofo FaucK : the combination of the ChucK Programming Language and Faust libossia is a modern C++, cross-environment distributed object model for creative coding. It is used in Ossia score project Radium is a music editor with a new type of interface, including a Faust audio DSP development environment using libfaust with the LLVM and Interpreter backends Mephisto LV2 is a Just-in-Time Faust compiler embedded in an LV2 plugin, using the C API. gwion-plug is a Faust plugin for the Gwion programming language. FaustGen allows to livecode Faust in SuperCollider. It uses the libfaust LLVM C++ API. FAUSTPy is a Python wrapper for the Faust DSP language. It is implemented using the CFFI and hence creates the wrapper dynamically at run-time. A updated version of the project is available on this fork . Faust.jl is Julia wrapper for the Faust compiler. It uses the libfaust LLVM C API. fl-tui is a Rust wrapper for the Faust compiler. It uses the libfaust LLVM C API. faustlive-jack-rs is another Rust wrapper for the Faust compiler, using JACK server for audio. It uses the libfaust LLVM C API. DawDreamer is an audio-processing Python framework supporting core DAW features. It uses the libfaust LLVM C API. metaSurface64 is a real-time continuous sound transformation control surface that features both its own loop generator for up to 64 voices and a multi-effects FX engine. It uses the libfaust LLVM C++ API. metaFx is a control surface for continuous sound transformations in real time, just like the metaSurface64. Like metaSurface64, it has both its own loop generator and a multi-effects FX engine, but its operation is different, especially for the management of plugin chains and pads. HISE is an open source framework for building sample based virtual instruments combining a highly performant Disk-Streaming Engine, a flexible DSP-Audio Module system and a handy Interface Designer. AMATI is a VST plugin for live-coding effects in the Faust programming language. cyfaust is a cython wrapper of the Faust interpreter and the RtAudio cross-platform audio driver, derived from the faustlab project. The objective is to end up with a minimal, modular, self-contained, cross-platform python3 extension. nih-faust-jit ia a plugin written in Rust to load Faust dsp files and JIT-compile them with LLVM. A simple GUI is provided to select which script to load and where to look for the Faust libraries that this script may import. The selected DSP script is saved as part of the plugin state and therefore is saved with your DAW project.","title":"Use Case Examples"},{"location":"manual/errors/","text":"Error messages Error messages are typically displayed in the form of compiler errors. They occur when the code cannot be successfully compiled, and typically indicate issues such as syntax errors or semantic errors. They can occur at different stages in the compilation process, possibly with the file and line number where the error occurred (when this information can be retrieved), as well as a brief description of the error. The compiler is organized in several stages: starting from the DSP source code, the parser builds an internal memory representation of the source program (typically known as an Abstract Source Tree ) made here of primitives in the Box language . A first class of errors messages are known as syntax error messages, like missing the ; character to end a line, etc. the next step is to evaluate the definition of process programe entry point. This step is basically a \u03bb-calculus interpreter with a strict evaluation. The result is \u201dflat\u201d block-diagram where everything have been expanded. The resulting block is type annoatetd to discover its number of inputs and outputs. the \u201dflat\u201d block-diagram is then translated the Signal language where signals as conceptually infinite streams of samples or control values. The box language actually implements the Faust Block Diagram Algebra , and not following the connections rules will trigger a second class of errors messages, the box connection errors . Other errors can be produced at this stage when parameters for some primitives are not of the correct type. the pattern matching meta language allows to algorithmically create and manipulate block diagrams expressions. So a third class of pattern matching coding errors can occur at this level. signal expressions are optimized, type annotated (to associate an integer or real type with each signal, but also discovering when signals are to be computed: at init time, control-rate or sample-rate..) to produce a so-called normal-form . A fourth class of parameter range errors or typing errors can occur at this level, like using delays with a non-bounded size, etc. signal expressions are then converted in FIR (Faust Imperative Representation), a representation for state based computation (memory access, arithmetic computations, control flow, etc.), to be converted into the final target language (like C/C++, LLVM IR, Rust, WebAssembly, etc.). A fifth class of backend errors can occur at this level, like non supported compilation options for a given backend, etc. Note that the current error messages system is still far from perfect, usually when the origin of the error in the DSP source cannot be properly traced. In this case the file and line number where the error occurred are not displayed, but an internal description of the expression (as a Box of a Signal) is printed. Syntax errors Those errors happen when the language syntax is not respected. Here are some examples. The following program: box1 = 1 box2 = 2; process = box1,box2; will produce the following error message: errors.dsp : 2 : ERROR : syntax error, unexpected IDENT It means that an unexpected identifier as been found line 2 of the file test.dsp. Usually, this error is due to the absence of the semi-column ; at the end of the previous line. The following program: t1 = _~(+(1); 2 process = t1 / 2147483647; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF The parser finds the end of the definition ( ; ) while searching a closing right parenthesis. The following program: process = ffunction; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF, expecting LPAR The parser was expecting a left parenthesis. It identified a keyword of the language that requires arguments. The following program: process = +)1); will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected RPAR The wrong parenthesis has been used. The following program: process = <:+; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected SPLIT The <: split operator is not correctly used, and should have been written process = _<:+; . The following program: process = foo; will produce the following error message: errors.dsp : 1 : ERROR : undefined symbol : foo This happens when an undefined name is used. Box connection errors Diagram expressions express how block expressions can be combined to create new ones. The connection rules are precisely defined for each of them and have to be followed for the program to be correct. Remember the operator priority when writing more complex expressions. The five connections rules A second category of error messages is returned when block expressions are not correctly connected. Parallel connection Combining two blocks A and B in parallel can never produce a box connection error since the 2 blocks are placed one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Sequencial connection error Combining two blocks A and B in sequence will produce a box connection error if outputs(A) != inputs(B) . So for instance the following program: A = _,_; B = _,_,_; process = A : B; will produce the following error message: ERROR : sequential composition A:B The number of outputs [2] of A must be equal to the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Split connection error Combining two blocks A and B with the split composition will produce a box connection error if the number of inputs of B is not a multiple of the number of outputs of A . So for instance the following program: A = _,_; B = _,_,_; process = A <: B; will produce the following error message: ERROR : split composition A<:B The number of outputs [2] of A must be a divisor of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Merge connection error Combining two blocks A and B with the merge composition will produce a box connection error if the number of outputs of A is not a multiple of the number of inputs of B . So for instance the following program: A = _,_; B = _,_,_; process = A :> B; will produce the following error message: ERROR : merge composition A:>B The number of outputs [2] of A must be a multiple of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs Recursive connection error Combining two blocks A and B with the recursive composition will produce a box connection error if the number of outputs of A is less than the number of inputs of B , or the number of outputs of B is more than the number of inputs of A (that is the following \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) connection rule is not respected). So for instance the following program: A = _,_; B = _,_,_; process = A ~ B; will produce the following error message: ERROR : recursive composition A~B The number of outputs [2] of A must be at least the number of inputs [3] of B. The number of inputs [2] of A must be at least the number of outputs [3] of B. Here A = _,_; has 2 inputs and 2 outputs while B = _,_,_; has 3 inputs and 3 outputs Route connection errors More complex routing between blocks can also be described using the route primitive. Two different errors can be produced in case of incorrect coding: process = route(+,8.7,(0,0),(0,1)); will produce the following error message: ERROR : invalid route expression, first two parameters should be blocks producing a value, third parameter a list of input/output pairs : route(+,8.7f,0,0,0,1) And the second one when the parameters are not actually numbers: process = route(9,8.7f,0,0,0,button(\"foo\")); will produce the following error message: ERROR : invalid route expression, parameters should be numbers : route(9,8.7f,0,0,0,button(\"foo\")) Iterative constructions Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. All par , seq , sum , prod expressions have the same form, take an identifier as first parameter, a number of iteration as an integer constant numerical expression as second parameter, then an arbitrary block-diagram as third parameter. The example code: process = par(+, 2, 8); will produce the following syntax error, since the first parameter is not an identifier: filename.dsp : xx : ERROR : syntax error, unexpected ADD, expecting IDENT The example code: process = par(i, +, 8); will produce the following error: filename.dsp : 1 : ERROR : not a constant expression of type : (0->1) : + Pattern matching errors Pattern matching mechanism allows to algorithmically create and manipulate block diagrams expressions. Pattern matching coding errors can occur at this level. Multiple symbol definition error This error happens when a symbol is defined several times in the DSP file: ERROR : [file foo.dsp : N] : multiple definitions of symbol 'foo' Since computation are done at compile time and the pattern matching language is Turing complete, even infinite loops can be produced at compile time and should be detected by the compiler. Loop detection error The following (somewhat extreme ) code: foo(x) = foo(x); process = foo; will produce the following error: ERROR : stack overflow in eval and similar kind of infinite loop errors can be produced with more complex code. [TO COMPLETE] Signal related errors Signal expressions are produced from box expressions, are type annotated and finally reduced to a normal-form. Some primitives expect their parameters to follow some constraints, like being in a specific range or being bounded for instance. The domain of mathematical functions is checked and non allowed operations are signaled. Automatic type promotion Some primitives (like route , rdtable , rwtable ...) expect arguments with an integer type, which is automatically promoted, that is the equivalent of int(exp) is internally added and is not necessary in the source code. Parameter range errors Soundfile usage error The soundfile primitive assumes the part number to stay in the [0..255] interval, so for instance the following code: process = _,0 : soundfile(\"foo.wav\", 2); will produce the following error: ERROR : out of range soundfile part number (interval(-1,1,-24) instead of interval(0,255)) in expression : length(soundfile(\"foo.wav\"),IN[0]) Delay primitive error The delay @ primitive assumes that the delay signal value is bounded, so the following expression: import(\"stdfaust.lib\"); process = @(ba.time); will produce the following error: ERROR : can't compute the min and max values of : proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1 used in delay expression : IN[0]@(proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1) (probably a recursive signal) [TO COMPLETE] Table construction errors The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The rwtable primitive can be used to implement a read/write table. Both have a size computed at compiled time The rdtable primitive assumes that the table content is produced by a processor with 0 input and one output, known at compiled time. So the following expression: process = rdtable(9, +, 4); will produce the following error, since the + is not of the correct type: ERROR : checkInit failed for type RSEVN interval(-2,2,-24) The same kind of errors will happen when read and write indexes are incorrectly defined in a rwtable primitive. Mathematical functions out of domain errors Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the -me option (see Warning messages section). Modulo primitive error The modulo % assumes that the denominator is not 0, thus the following code: process = _%0; will produce the following error: ERROR : % by 0 in IN[0] % 0 The same kind of errors will be produced for acos , asin , fmod , log10 , log , remainder and sqrt functions. FIR and backends related errors Some primitives of the language are not available in some backends. The example code: fun = ffunction(float fun(float), <fun.h>, \"\"); process = fun; compiled with the wast/wasm backends using: faust -lang wast errors.dsp will produce the following error: ERROR : calling foreign function 'fun' is not allowed in this compilation mode and the same kind of errors would happen also with foreign variables or constants. [TO COMPLETE] Compiler option errors All compiler options cannot be used with all backends. Moreover, some compiler options can not be combined. These will typically trigger errors, before any compilation actually begins. [TO COMPLETE] Warning messages Warning messages do not stop the compilation process, but allow to get usefull informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Error Messages"},{"location":"manual/errors/#error-messages","text":"Error messages are typically displayed in the form of compiler errors. They occur when the code cannot be successfully compiled, and typically indicate issues such as syntax errors or semantic errors. They can occur at different stages in the compilation process, possibly with the file and line number where the error occurred (when this information can be retrieved), as well as a brief description of the error. The compiler is organized in several stages: starting from the DSP source code, the parser builds an internal memory representation of the source program (typically known as an Abstract Source Tree ) made here of primitives in the Box language . A first class of errors messages are known as syntax error messages, like missing the ; character to end a line, etc. the next step is to evaluate the definition of process programe entry point. This step is basically a \u03bb-calculus interpreter with a strict evaluation. The result is \u201dflat\u201d block-diagram where everything have been expanded. The resulting block is type annoatetd to discover its number of inputs and outputs. the \u201dflat\u201d block-diagram is then translated the Signal language where signals as conceptually infinite streams of samples or control values. The box language actually implements the Faust Block Diagram Algebra , and not following the connections rules will trigger a second class of errors messages, the box connection errors . Other errors can be produced at this stage when parameters for some primitives are not of the correct type. the pattern matching meta language allows to algorithmically create and manipulate block diagrams expressions. So a third class of pattern matching coding errors can occur at this level. signal expressions are optimized, type annotated (to associate an integer or real type with each signal, but also discovering when signals are to be computed: at init time, control-rate or sample-rate..) to produce a so-called normal-form . A fourth class of parameter range errors or typing errors can occur at this level, like using delays with a non-bounded size, etc. signal expressions are then converted in FIR (Faust Imperative Representation), a representation for state based computation (memory access, arithmetic computations, control flow, etc.), to be converted into the final target language (like C/C++, LLVM IR, Rust, WebAssembly, etc.). A fifth class of backend errors can occur at this level, like non supported compilation options for a given backend, etc. Note that the current error messages system is still far from perfect, usually when the origin of the error in the DSP source cannot be properly traced. In this case the file and line number where the error occurred are not displayed, but an internal description of the expression (as a Box of a Signal) is printed.","title":"Error messages"},{"location":"manual/errors/#syntax-errors","text":"Those errors happen when the language syntax is not respected. Here are some examples. The following program: box1 = 1 box2 = 2; process = box1,box2; will produce the following error message: errors.dsp : 2 : ERROR : syntax error, unexpected IDENT It means that an unexpected identifier as been found line 2 of the file test.dsp. Usually, this error is due to the absence of the semi-column ; at the end of the previous line. The following program: t1 = _~(+(1); 2 process = t1 / 2147483647; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF The parser finds the end of the definition ( ; ) while searching a closing right parenthesis. The following program: process = ffunction; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected ENDDEF, expecting LPAR The parser was expecting a left parenthesis. It identified a keyword of the language that requires arguments. The following program: process = +)1); will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected RPAR The wrong parenthesis has been used. The following program: process = <:+; will produce the following error message: errors.dsp : 1 : ERROR : syntax error, unexpected SPLIT The <: split operator is not correctly used, and should have been written process = _<:+; . The following program: process = foo; will produce the following error message: errors.dsp : 1 : ERROR : undefined symbol : foo This happens when an undefined name is used.","title":"Syntax errors"},{"location":"manual/errors/#box-connection-errors","text":"Diagram expressions express how block expressions can be combined to create new ones. The connection rules are precisely defined for each of them and have to be followed for the program to be correct. Remember the operator priority when writing more complex expressions.","title":"Box connection errors"},{"location":"manual/errors/#the-five-connections-rules","text":"A second category of error messages is returned when block expressions are not correctly connected.","title":"The five connections rules"},{"location":"manual/errors/#parallel-connection","text":"Combining two blocks A and B in parallel can never produce a box connection error since the 2 blocks are placed one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B .","title":"Parallel connection"},{"location":"manual/errors/#sequencial-connection-error","text":"Combining two blocks A and B in sequence will produce a box connection error if outputs(A) != inputs(B) . So for instance the following program: A = _,_; B = _,_,_; process = A : B; will produce the following error message: ERROR : sequential composition A:B The number of outputs [2] of A must be equal to the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Sequencial connection error"},{"location":"manual/errors/#split-connection-error","text":"Combining two blocks A and B with the split composition will produce a box connection error if the number of inputs of B is not a multiple of the number of outputs of A . So for instance the following program: A = _,_; B = _,_,_; process = A <: B; will produce the following error message: ERROR : split composition A<:B The number of outputs [2] of A must be a divisor of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Split connection error"},{"location":"manual/errors/#merge-connection-error","text":"Combining two blocks A and B with the merge composition will produce a box connection error if the number of outputs of A is not a multiple of the number of inputs of B . So for instance the following program: A = _,_; B = _,_,_; process = A :> B; will produce the following error message: ERROR : merge composition A:>B The number of outputs [2] of A must be a multiple of the number of inputs [3] of B Here A = _,_; has 2 outputs while B = _,_,_; has 3 inputs","title":"Merge connection error"},{"location":"manual/errors/#recursive-connection-error","text":"Combining two blocks A and B with the recursive composition will produce a box connection error if the number of outputs of A is less than the number of inputs of B , or the number of outputs of B is more than the number of inputs of A (that is the following \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) connection rule is not respected). So for instance the following program: A = _,_; B = _,_,_; process = A ~ B; will produce the following error message: ERROR : recursive composition A~B The number of outputs [2] of A must be at least the number of inputs [3] of B. The number of inputs [2] of A must be at least the number of outputs [3] of B. Here A = _,_; has 2 inputs and 2 outputs while B = _,_,_; has 3 inputs and 3 outputs","title":"Recursive connection error"},{"location":"manual/errors/#route-connection-errors","text":"More complex routing between blocks can also be described using the route primitive. Two different errors can be produced in case of incorrect coding: process = route(+,8.7,(0,0),(0,1)); will produce the following error message: ERROR : invalid route expression, first two parameters should be blocks producing a value, third parameter a list of input/output pairs : route(+,8.7f,0,0,0,1) And the second one when the parameters are not actually numbers: process = route(9,8.7f,0,0,0,button(\"foo\")); will produce the following error message: ERROR : invalid route expression, parameters should be numbers : route(9,8.7f,0,0,0,button(\"foo\"))","title":"Route connection errors"},{"location":"manual/errors/#iterative-constructions","text":"Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. All par , seq , sum , prod expressions have the same form, take an identifier as first parameter, a number of iteration as an integer constant numerical expression as second parameter, then an arbitrary block-diagram as third parameter. The example code: process = par(+, 2, 8); will produce the following syntax error, since the first parameter is not an identifier: filename.dsp : xx : ERROR : syntax error, unexpected ADD, expecting IDENT The example code: process = par(i, +, 8); will produce the following error: filename.dsp : 1 : ERROR : not a constant expression of type : (0->1) : +","title":"Iterative constructions"},{"location":"manual/errors/#pattern-matching-errors","text":"Pattern matching mechanism allows to algorithmically create and manipulate block diagrams expressions. Pattern matching coding errors can occur at this level.","title":"Pattern matching errors"},{"location":"manual/errors/#multiple-symbol-definition-error","text":"This error happens when a symbol is defined several times in the DSP file: ERROR : [file foo.dsp : N] : multiple definitions of symbol 'foo' Since computation are done at compile time and the pattern matching language is Turing complete, even infinite loops can be produced at compile time and should be detected by the compiler.","title":"Multiple symbol definition error"},{"location":"manual/errors/#loop-detection-error","text":"The following (somewhat extreme ) code: foo(x) = foo(x); process = foo; will produce the following error: ERROR : stack overflow in eval and similar kind of infinite loop errors can be produced with more complex code. [TO COMPLETE]","title":"Loop detection error"},{"location":"manual/errors/#signal-related-errors","text":"Signal expressions are produced from box expressions, are type annotated and finally reduced to a normal-form. Some primitives expect their parameters to follow some constraints, like being in a specific range or being bounded for instance. The domain of mathematical functions is checked and non allowed operations are signaled.","title":"Signal related errors"},{"location":"manual/errors/#automatic-type-promotion","text":"Some primitives (like route , rdtable , rwtable ...) expect arguments with an integer type, which is automatically promoted, that is the equivalent of int(exp) is internally added and is not necessary in the source code.","title":"Automatic type promotion"},{"location":"manual/errors/#parameter-range-errors","text":"","title":"Parameter range errors"},{"location":"manual/errors/#soundfile-usage-error","text":"The soundfile primitive assumes the part number to stay in the [0..255] interval, so for instance the following code: process = _,0 : soundfile(\"foo.wav\", 2); will produce the following error: ERROR : out of range soundfile part number (interval(-1,1,-24) instead of interval(0,255)) in expression : length(soundfile(\"foo.wav\"),IN[0])","title":"Soundfile usage error"},{"location":"manual/errors/#delay-primitive-error","text":"The delay @ primitive assumes that the delay signal value is bounded, so the following expression: import(\"stdfaust.lib\"); process = @(ba.time); will produce the following error: ERROR : can't compute the min and max values of : proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1 used in delay expression : IN[0]@(proj0(letrec(W0 = (proj0(W0)'+1)))@0+-1) (probably a recursive signal) [TO COMPLETE]","title":"Delay primitive error"},{"location":"manual/errors/#table-construction-errors","text":"The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The rwtable primitive can be used to implement a read/write table. Both have a size computed at compiled time The rdtable primitive assumes that the table content is produced by a processor with 0 input and one output, known at compiled time. So the following expression: process = rdtable(9, +, 4); will produce the following error, since the + is not of the correct type: ERROR : checkInit failed for type RSEVN interval(-2,2,-24) The same kind of errors will happen when read and write indexes are incorrectly defined in a rwtable primitive.","title":"Table construction errors"},{"location":"manual/errors/#mathematical-functions-out-of-domain-errors","text":"Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the -me option (see Warning messages section).","title":"Mathematical functions out of domain errors"},{"location":"manual/errors/#modulo-primitive-error","text":"The modulo % assumes that the denominator is not 0, thus the following code: process = _%0; will produce the following error: ERROR : % by 0 in IN[0] % 0 The same kind of errors will be produced for acos , asin , fmod , log10 , log , remainder and sqrt functions.","title":"Modulo primitive error"},{"location":"manual/errors/#fir-and-backends-related-errors","text":"Some primitives of the language are not available in some backends. The example code: fun = ffunction(float fun(float), <fun.h>, \"\"); process = fun; compiled with the wast/wasm backends using: faust -lang wast errors.dsp will produce the following error: ERROR : calling foreign function 'fun' is not allowed in this compilation mode and the same kind of errors would happen also with foreign variables or constants. [TO COMPLETE]","title":"FIR and backends related errors"},{"location":"manual/errors/#compiler-option-errors","text":"All compiler options cannot be used with all backends. Moreover, some compiler options can not be combined. These will typically trigger errors, before any compilation actually begins. [TO COMPLETE]","title":"Compiler option errors"},{"location":"manual/errors/#warning-messages","text":"Warning messages do not stop the compilation process, but allow to get usefull informations on potential problematic code. The messages can be printed using the -wall compilation option. Mathematical out-of-domain error warning messages are displayed when both -wall and -me options are used.","title":"Warning messages"},{"location":"manual/faq/","text":"Frequently Asked Questions When to use int or float cast ? The Signal Processor Semantic section explains what a Faust program describes. In particular Faust considers two type of signals: integer signals and floating point signals . Mathematical operations either occur in the domain of integer numbers, or in the domain of floating point numbers, depending of their types, read here . Using explicit int cast or float cast may be needed to force a given computation to be done in the correct number domain. Some language primitives (like par , seq , route , soundfile , etc.) assume that their parameters are Constant Numerical Expressions of the integer type. In this case the compiler automatically does type promotion and there is no need to use int cast to have the argument be of the integer type (note that an uneeded cast will simply be ignored and will not add uneeded computation in the generated code). User interface items produce floating point signals . Depending of their use later in the computed expression, using explicit int cast may be needed also to force a given computation to be done in the correct number domain. Does select2 behaves as a standard C/C++ like if ? The short answer is no , select2 doesn't behave like the if-then-else of a traditional programming language, nor does ba.if of the standard library. To understand why, think of select2 as the tuner of a radio, it selects what you listen, but does not prevent the various radio stations from broadcasting. Actually, select2 could be easily redefined in Faust as: select2(i, x, y) = (1-i) * x + i * y; Strict vs Lazy semantics In computer science terminology, select2(i,x,y) has so-called strict semantics. This means that its three arguments i , x , y are always evaluated before select2 itself is executed, in other words, even if x or y is not selected. The standard C/C++ if-then-else has lazy semantics. The condition is always executed, but depending of the value of the condition , only the then or the else branch is executed. The strict semantics of select2 means that you cannot use it to prevent a division by 0 in an expression, or the square root of a negative number, etc... For example, the following code will not prevent a division by 0 error: select2(x == 0, 1/x, 10000); You cannot use ba.if either because it is implemented using select2 and has the same strict semantics. Therefore the following code will not prevent a division by 0 error: ba.if(x == 0, 10000, 1/x); But things are a little bit more complex... Concerning the way select2 is compiled by the Faust compiler, the strict semantic is always preserved. In particular, the type system flags problematic expressions and the stateful parts are always placed outside the if. For instance the DSP code: process = button(\"choose\"), (*(3) : +~_), (*(7):+~_) : select2; is compiled as the following C++ code, where fRec0[0] and fRec1[0] contains the computation of each branch: for (int i = 0; (i < count); i = (i + 1)) { fRec0[0] = (fRec0[1] + (3.0f * float(input0[i]))); fRec1[0] = (fRec1[1] + (7.0f * float(input1[i]))); output0[i] = FAUSTFLOAT((iSlow0 ? fRec1[0] : fRec0[0])); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } For code optimization strategies, the generated code is not fully strict on select2 . When Faust produces C++ code, the C++ compiler can decide to avoid the execution of the stateless part of the signal that is not selected (and not needed elsewhere). This doesn't change the semantics of the output signal, but it changes the strictness of the code if a division by 0 would have been executed in the stateless part. When stateless expressions are used, they are by default generated using a non-strict conditional expression. For instance the following DSP code: process = select2((+(1)~_)%10, sin:cos:sin:cos, cos:sin:cos:sin); is compiled in C/C++ as: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))) : std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))))); iRec0[1] = iRec0[0]; } where only one of the then or else branch will be effectively computed, thus saving CPU. If computing both branches is really desired, the -sts (--strict-select) option can be used to force their computation by putting them in local variables, as shown in the following generated with -sts code version of the same DSP code: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; float fThen0 = std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))); float fElse0 = std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))); output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? fElse0 : fThen0)); iRec0[1] = iRec0[0]; } to therefore preserve the strict semantic, even if a non-strict (cond) ? then : else form is used to produce the result of the select2 expression. This can be helpful for debugging purposes like testing if there is no division by 0, or producing INF or NaN values. The interp-tracer can be used for that by adding the -sts option. So again remember that select2 cannot be used to avoid computing something . For computations that need to avoid some values or ranges (like doing val/0 that would return INF , or log of a negative value that would return NaN ), the solution is to use min and max to force the arguments to be in the correct domain of values. For example, to avoid division by 0, you can write 1/max(ma.EPSILON, x) . Note that select2 is also typically used to compute rdtable/rwtable access indexes. In this case computing an array out-of-bound index, if is not used later on, is not a problem. What properties does the Faust compiler and generated code have ? [WIP] Compiler The compiler itself is turing complete because it contains a pattern matching meta-programming model. Thus a Faust DSP program can loop at compile time. For instance the following: foo = foo; process = foo; will loop and hopefully end with the message: ERROR : after 400 evaluation steps, the compiler has detected an endless evaluation cycle of 2 steps because the compiler contains an infinite loop detection heuristic. Generated code The generated code computes the sample in a finite number of operations, thus a DSP program that would loop infinitely cannot be written. It means the generated code is not turing complete. This is of course a limitation because certain classes of algorithms cannot be expressed ( TODO : Newton approximation used in diode VA model). But on the contrary it gives a strong garanty on the upper bound of CPU cost that is quite interesting to have when deploying a program in a real-time audio context. Memory footprint The DSP memory footprint is perfectly known at compile time, so the generated code always consume a finite amount of memory. Moreover the standard deployement model is to allocate the DSP a load time, init it with a given sample-rate, then execute the DSP code, be repeatedly calling the compute function to process audio buffers. CPU footprint Since the generated code computes the sample in a finite number of operations, the CPU use has an upper bound which is a very helpful property when deploying a program in a real-time audio context. Read the Does select2 behaves as a standard C/C++ like if ? for some subtle issues concerning the select2 primitive. Pattern matching and lists Strictly speaking, there are no lists in Faust. For example the expression () or NIL in Lisp, which indicates an empty list, does not exist in Faust. Similarly, the distinction in Lisp between the number 3 and the list with only one element (3) does not exist in Faust. However, list operations can be simulated (in part) using the parallel binary composition operation , and pattern matching. The parallel composition operation is right-associative. This means that the expression (1,2,3,4) is just a simplified form of the fully parenthesized expression (1,(2,(3,4))) . The same is true for (1,2,(3,4)) which is also a simplified form of the same fully parenthesized expression (1,(2,(3,4))) . You can think of pattern-matching as always being done on fully parenthesized expressions. Therefore no Faust function can ever distinguish (1,2,3,4) from (1,2,(3,4)) , because they represent the same fully parenthesized expression (1,(2,(3,4))) . This is why ba.count( ((1,2), (3,4), (5,6)) ) is not 3 but 4, and also why ba.count( ((1,2), ((3,4),5,6)) ) is not 2 but 4. Explanation: in both cases the fully parenthesized expression is ( (1,2),((3,4),(5,6)) ) . The definition of ba.count being: count((x,y)) = 1 + count(y); // rule R1 count(x) = 1; // rule R2 we have: ba.count( ((1,2),((3,4),(5,6))) ) -R1-> 1 + ba.count( ((3,4),(5,6)) ) -R1-> 1 + 1 + ba.count( (5,6) ) -R1-> 1 + 1 + 1 + ba.count( 6 ) -R2-> 1 + 1 + 1 + 1 Please note that pattern matching is not limited to parallel composition, the other composition operators (<: : :> ~) can be used too. What is the situation about Faust compiler licence and the deployed code? Q: Does the Faust license (GPL) apply somehow to the code exports that it produces as well? Or can the license of the exported code be freely chosen such that one could develop commercial software (e.g. VST plug-ins) using Faust? A: You can freely use Faust to develop commercial software. The GPL license of the compiler doesn't apply to the code generated by the compiler. The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use. Surprising effects of vgroup/hgroup on how controls and parameters work User interface widget primitives like button , vslider/hslider , vbargraph/hbargraph allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hiearchical manner using vgroup/hgroup/tgroup primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. Widgets that have the same path in the hiearchical structure will correspond to a same controller and will appear once in the GUI. For instance the following DSP code does not contain any explicit grouping mechanism: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = os.osc(freq1) + os.square(freq2), os.osc(freq1) + os.triangle(freq2); Shared freq1 and freq2 controllers So even if freq1 and freq2 controllers are used as parameters at four different places, freq1 used in os.osc(freq1) and os.square(freq1) will have the same path (like /foo/Freq1 ), be associated to a unique controller, and will finally appear once in the GUI. And this is the same mecanism for freq2 . Now if some grouping mecanism is used to better control the UI rendering, as in the following DSP code: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); The freq1 and freq2 controllers now don't have the same path in each group (like /foo/Voice1/Freq1 and /foo/Voice1/Freq2 in the first group, and /foo/Voice2/Freq1 and /foo/Voice2/Freq2 in the second group), and so four separated controllers and UI items are finally created. Four freq1 and freq2 controllers Using the relative pathname as explained in Labels as Pathnames possibly allows us to move freq1 one step higher in the hierarchical structure, thus having again a unique path (like /foo/Freq1 ) and controller: import(\"stdfaust.lib\"); freq1 = hslider(\"../Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); freq1 moved one step higher in the hierarchical structure Note that the name for a given hgroup , vgroup , or tgroup can be used more than once, and they will be merged. This can be useful when you want to define different names for different widget signals, but still want to group them. For example, this pattern can be used to separate a synth's UI design from the implementation of the synth's DSP: import (\"stdfaust.lib\"); synth(foo, bar, baz) = os.osc(foo+bar+baz); synth_ui = synth(foo, bar, baz) with { ui(x) = hgroup(\"Synth\", x); leftcol(x) = ui(vgroup(\"[0]foobar\", x)); foo = leftcol(hslider(\"[0]foo\", 100, 20, 1000, 1)); bar = leftcol(hslider(\"[1]bar\", 100, 20, 1000, 1)); baz = ui(vslider(\"[1]baz\", 100, 20, 1000, 1)); }; process = synth_ui; naming and grouping What are the rules used for partial application ? Assuming F is not an abstraction and has n+m inputs and A has n outputs, then we have the rewriting rule F(A) ==> A,bus(m):F (with bus(1) = _ and bus(n+1) = _,bus(n)) There is an exception when F is a binary operation like +,-,/,* . In this case, the rewriting rule is /(3) ==> _,3:/ . In other words, when we apply only one argument, it is the second one. Control rate versus audio rate Question: I have a question about sample rate / control rate issues. I have a Faust code that takes channel pressure messages from my keyboard as input, therefore at control rate, and outputs an expression signal at sample rate. The first part of the code can run at control rate, but I want to force it to run at sample rate (otherwise unwanted behavior will appear). Is there a simple way of forcing my pressure signal to be at sample rate (without making a smooth which may also result in unwanted behavior) . Answer: the ba.kr2ar function can be used for that purpose.","title":"Frequently Asked Questions"},{"location":"manual/faq/#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"manual/faq/#when-to-use-int-or-float-cast","text":"The Signal Processor Semantic section explains what a Faust program describes. In particular Faust considers two type of signals: integer signals and floating point signals . Mathematical operations either occur in the domain of integer numbers, or in the domain of floating point numbers, depending of their types, read here . Using explicit int cast or float cast may be needed to force a given computation to be done in the correct number domain. Some language primitives (like par , seq , route , soundfile , etc.) assume that their parameters are Constant Numerical Expressions of the integer type. In this case the compiler automatically does type promotion and there is no need to use int cast to have the argument be of the integer type (note that an uneeded cast will simply be ignored and will not add uneeded computation in the generated code). User interface items produce floating point signals . Depending of their use later in the computed expression, using explicit int cast may be needed also to force a given computation to be done in the correct number domain.","title":"When to use int or float cast ?"},{"location":"manual/faq/#does-select2-behaves-as-a-standard-cc-like-if","text":"The short answer is no , select2 doesn't behave like the if-then-else of a traditional programming language, nor does ba.if of the standard library. To understand why, think of select2 as the tuner of a radio, it selects what you listen, but does not prevent the various radio stations from broadcasting. Actually, select2 could be easily redefined in Faust as: select2(i, x, y) = (1-i) * x + i * y;","title":"Does select2 behaves as a standard C/C++ like if ?"},{"location":"manual/faq/#strict-vs-lazy-semantics","text":"In computer science terminology, select2(i,x,y) has so-called strict semantics. This means that its three arguments i , x , y are always evaluated before select2 itself is executed, in other words, even if x or y is not selected. The standard C/C++ if-then-else has lazy semantics. The condition is always executed, but depending of the value of the condition , only the then or the else branch is executed. The strict semantics of select2 means that you cannot use it to prevent a division by 0 in an expression, or the square root of a negative number, etc... For example, the following code will not prevent a division by 0 error: select2(x == 0, 1/x, 10000); You cannot use ba.if either because it is implemented using select2 and has the same strict semantics. Therefore the following code will not prevent a division by 0 error: ba.if(x == 0, 10000, 1/x);","title":"Strict vs Lazy semantics"},{"location":"manual/faq/#but-things-are-a-little-bit-more-complex","text":"Concerning the way select2 is compiled by the Faust compiler, the strict semantic is always preserved. In particular, the type system flags problematic expressions and the stateful parts are always placed outside the if. For instance the DSP code: process = button(\"choose\"), (*(3) : +~_), (*(7):+~_) : select2; is compiled as the following C++ code, where fRec0[0] and fRec1[0] contains the computation of each branch: for (int i = 0; (i < count); i = (i + 1)) { fRec0[0] = (fRec0[1] + (3.0f * float(input0[i]))); fRec1[0] = (fRec1[1] + (7.0f * float(input1[i]))); output0[i] = FAUSTFLOAT((iSlow0 ? fRec1[0] : fRec0[0])); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } For code optimization strategies, the generated code is not fully strict on select2 . When Faust produces C++ code, the C++ compiler can decide to avoid the execution of the stateless part of the signal that is not selected (and not needed elsewhere). This doesn't change the semantics of the output signal, but it changes the strictness of the code if a division by 0 would have been executed in the stateless part. When stateless expressions are used, they are by default generated using a non-strict conditional expression. For instance the following DSP code: process = select2((+(1)~_)%10, sin:cos:sin:cos, cos:sin:cos:sin); is compiled in C/C++ as: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))) : std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))))); iRec0[1] = iRec0[0]; } where only one of the then or else branch will be effectively computed, thus saving CPU. If computing both branches is really desired, the -sts (--strict-select) option can be used to force their computation by putting them in local variables, as shown in the following generated with -sts code version of the same DSP code: for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; float fThen0 = std::cos(std::sin(std::cos(std::sin(float(input0[i0]))))); float fElse0 = std::sin(std::cos(std::sin(std::cos(float(input1[i0]))))); output0[i0] = FAUSTFLOAT(((iRec0[0] % 10) ? fElse0 : fThen0)); iRec0[1] = iRec0[0]; } to therefore preserve the strict semantic, even if a non-strict (cond) ? then : else form is used to produce the result of the select2 expression. This can be helpful for debugging purposes like testing if there is no division by 0, or producing INF or NaN values. The interp-tracer can be used for that by adding the -sts option. So again remember that select2 cannot be used to avoid computing something . For computations that need to avoid some values or ranges (like doing val/0 that would return INF , or log of a negative value that would return NaN ), the solution is to use min and max to force the arguments to be in the correct domain of values. For example, to avoid division by 0, you can write 1/max(ma.EPSILON, x) . Note that select2 is also typically used to compute rdtable/rwtable access indexes. In this case computing an array out-of-bound index, if is not used later on, is not a problem.","title":"But things are a little bit more complex..."},{"location":"manual/faq/#what-properties-does-the-faust-compiler-and-generated-code-have-wip","text":"","title":"What properties does the Faust compiler and generated code have ? [WIP]"},{"location":"manual/faq/#compiler","text":"The compiler itself is turing complete because it contains a pattern matching meta-programming model. Thus a Faust DSP program can loop at compile time. For instance the following: foo = foo; process = foo; will loop and hopefully end with the message: ERROR : after 400 evaluation steps, the compiler has detected an endless evaluation cycle of 2 steps because the compiler contains an infinite loop detection heuristic.","title":"Compiler"},{"location":"manual/faq/#generated-code","text":"The generated code computes the sample in a finite number of operations, thus a DSP program that would loop infinitely cannot be written. It means the generated code is not turing complete. This is of course a limitation because certain classes of algorithms cannot be expressed ( TODO : Newton approximation used in diode VA model). But on the contrary it gives a strong garanty on the upper bound of CPU cost that is quite interesting to have when deploying a program in a real-time audio context.","title":"Generated code"},{"location":"manual/faq/#memory-footprint","text":"The DSP memory footprint is perfectly known at compile time, so the generated code always consume a finite amount of memory. Moreover the standard deployement model is to allocate the DSP a load time, init it with a given sample-rate, then execute the DSP code, be repeatedly calling the compute function to process audio buffers.","title":"Memory footprint"},{"location":"manual/faq/#cpu-footprint","text":"Since the generated code computes the sample in a finite number of operations, the CPU use has an upper bound which is a very helpful property when deploying a program in a real-time audio context. Read the Does select2 behaves as a standard C/C++ like if ? for some subtle issues concerning the select2 primitive.","title":"CPU footprint"},{"location":"manual/faq/#pattern-matching-and-lists","text":"Strictly speaking, there are no lists in Faust. For example the expression () or NIL in Lisp, which indicates an empty list, does not exist in Faust. Similarly, the distinction in Lisp between the number 3 and the list with only one element (3) does not exist in Faust. However, list operations can be simulated (in part) using the parallel binary composition operation , and pattern matching. The parallel composition operation is right-associative. This means that the expression (1,2,3,4) is just a simplified form of the fully parenthesized expression (1,(2,(3,4))) . The same is true for (1,2,(3,4)) which is also a simplified form of the same fully parenthesized expression (1,(2,(3,4))) . You can think of pattern-matching as always being done on fully parenthesized expressions. Therefore no Faust function can ever distinguish (1,2,3,4) from (1,2,(3,4)) , because they represent the same fully parenthesized expression (1,(2,(3,4))) . This is why ba.count( ((1,2), (3,4), (5,6)) ) is not 3 but 4, and also why ba.count( ((1,2), ((3,4),5,6)) ) is not 2 but 4. Explanation: in both cases the fully parenthesized expression is ( (1,2),((3,4),(5,6)) ) . The definition of ba.count being: count((x,y)) = 1 + count(y); // rule R1 count(x) = 1; // rule R2 we have: ba.count( ((1,2),((3,4),(5,6))) ) -R1-> 1 + ba.count( ((3,4),(5,6)) ) -R1-> 1 + 1 + ba.count( (5,6) ) -R1-> 1 + 1 + 1 + ba.count( 6 ) -R2-> 1 + 1 + 1 + 1 Please note that pattern matching is not limited to parallel composition, the other composition operators (<: : :> ~) can be used too.","title":"Pattern matching and lists"},{"location":"manual/faq/#what-is-the-situation-about-faust-compiler-licence-and-the-deployed-code","text":"Q: Does the Faust license (GPL) apply somehow to the code exports that it produces as well? Or can the license of the exported code be freely chosen such that one could develop commercial software (e.g. VST plug-ins) using Faust? A: You can freely use Faust to develop commercial software. The GPL license of the compiler doesn't apply to the code generated by the compiler. The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use.","title":"What is the situation about Faust compiler licence and the deployed code?"},{"location":"manual/faq/#surprising-effects-of-vgrouphgroup-on-how-controls-and-parameters-work","text":"User interface widget primitives like button , vslider/hslider , vbargraph/hbargraph allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hiearchical manner using vgroup/hgroup/tgroup primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. Widgets that have the same path in the hiearchical structure will correspond to a same controller and will appear once in the GUI. For instance the following DSP code does not contain any explicit grouping mechanism: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = os.osc(freq1) + os.square(freq2), os.osc(freq1) + os.triangle(freq2); Shared freq1 and freq2 controllers So even if freq1 and freq2 controllers are used as parameters at four different places, freq1 used in os.osc(freq1) and os.square(freq1) will have the same path (like /foo/Freq1 ), be associated to a unique controller, and will finally appear once in the GUI. And this is the same mecanism for freq2 . Now if some grouping mecanism is used to better control the UI rendering, as in the following DSP code: import(\"stdfaust.lib\"); freq1 = hslider(\"Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); The freq1 and freq2 controllers now don't have the same path in each group (like /foo/Voice1/Freq1 and /foo/Voice1/Freq2 in the first group, and /foo/Voice2/Freq1 and /foo/Voice2/Freq2 in the second group), and so four separated controllers and UI items are finally created. Four freq1 and freq2 controllers Using the relative pathname as explained in Labels as Pathnames possibly allows us to move freq1 one step higher in the hierarchical structure, thus having again a unique path (like /foo/Freq1 ) and controller: import(\"stdfaust.lib\"); freq1 = hslider(\"../Freq1\", 500, 200, 2000, 0.01); freq2 = hslider(\"Freq2\", 500, 200, 2000, 0.01); process = hgroup(\"Voice1\", os.osc(freq1) + os.square(freq2)), hgroup(\"Voice2\", os.osc(freq1) + os.triangle(freq2)); freq1 moved one step higher in the hierarchical structure Note that the name for a given hgroup , vgroup , or tgroup can be used more than once, and they will be merged. This can be useful when you want to define different names for different widget signals, but still want to group them. For example, this pattern can be used to separate a synth's UI design from the implementation of the synth's DSP: import (\"stdfaust.lib\"); synth(foo, bar, baz) = os.osc(foo+bar+baz); synth_ui = synth(foo, bar, baz) with { ui(x) = hgroup(\"Synth\", x); leftcol(x) = ui(vgroup(\"[0]foobar\", x)); foo = leftcol(hslider(\"[0]foo\", 100, 20, 1000, 1)); bar = leftcol(hslider(\"[1]bar\", 100, 20, 1000, 1)); baz = ui(vslider(\"[1]baz\", 100, 20, 1000, 1)); }; process = synth_ui; naming and grouping","title":"Surprising effects of vgroup/hgroup on how controls and parameters work"},{"location":"manual/faq/#what-are-the-rules-used-for-partial-application","text":"Assuming F is not an abstraction and has n+m inputs and A has n outputs, then we have the rewriting rule F(A) ==> A,bus(m):F (with bus(1) = _ and bus(n+1) = _,bus(n)) There is an exception when F is a binary operation like +,-,/,* . In this case, the rewriting rule is /(3) ==> _,3:/ . In other words, when we apply only one argument, it is the second one.","title":"What are the rules used for partial application ?"},{"location":"manual/faq/#control-rate-versus-audio-rate","text":"Question: I have a question about sample rate / control rate issues. I have a Faust code that takes channel pressure messages from my keyboard as input, therefore at control rate, and outputs an expression signal at sample rate. The first part of the code can run at control rate, but I want to force it to run at sample rate (otherwise unwanted behavior will appear). Is there a simple way of forcing my pressure signal to be at sample rate (without making a smooth which may also result in unwanted behavior) . Answer: the ba.kr2ar function can be used for that purpose.","title":"Control rate versus audio rate"},{"location":"manual/http/","text":"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 HTTPD 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 lists 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 4 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 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 is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open 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 that 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 here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge 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 the 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 Let's say 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 concatenating ?value=1 at 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 purely developed in C/C++. A proxy version of the user interface can then be built, and parameters can be \"set and get\" 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 for the access of 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\" .","title":"HTTP Support"},{"location":"manual/http/#http-support","text":"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 HTTPD 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 lists Faust's architectures providing HTTP support:","title":"HTTP Support"},{"location":"manual/http/#linux-faust-architectures-with-http-support","text":"Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt","title":"Linux Faust Architectures with HTTP Support"},{"location":"manual/http/#osx-faust-architectures-with-http-support","text":"Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt","title":"OSX Faust Architectures with HTTP Support"},{"location":"manual/http/#windows-faust-architectures-with-http-support","text":"Audio System Environment Jack Qt, Console PortAudio Qt","title":"Windows Faust Architectures with HTTP Support"},{"location":"manual/http/#a-simple-example","text":"To illustrate how HTTP support works, let's reuse our previous example, a simple monophonic audio mixer with 4 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 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 is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page presented in the figure below:","title":"A Simple Example"},{"location":"manual/http/#json-description-of-the-user-interface","text":"The communication between the application and the Web browser is based on several underlying URLs. The first one is http://localhost:5510/JSON that 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\" } ] }, ... ] } ] }","title":"JSON Description of the User Interface"},{"location":"manual/http/#querying-the-state-of-the-application","text":"Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge 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 the 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","title":"Querying the State of the Application"},{"location":"manual/http/#changing-the-value-of-a-widget","text":"Let's say 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 concatenating ?value=1 at 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.","title":"Changing the Value of a Widget"},{"location":"manual/http/#proxy-control-access-to-the-web-server","text":"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 purely developed in C/C++. A proxy version of the user interface can then be built, and parameters can be \"set and get\" 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 for the access of the remote parameters.","title":"Proxy Control Access to the Web Server"},{"location":"manual/http/#http-cheat-sheet","text":"Here is a summary of the various URLs used to interact with the application's Web server.","title":"HTTP Cheat Sheet"},{"location":"manual/http/#default-ports","text":"Port Description 5510 default TCP port used by the application's Web server 5511... alternative TCP ports","title":"Default Ports"},{"location":"manual/http/#command-line-options","text":"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","title":"Command Line Options"},{"location":"manual/http/#urls","text":"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","title":"URLs"},{"location":"manual/http/#json","text":"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\" .","title":"JSON"},{"location":"manual/introduction/","text":"Introduction What is Faust? Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. This manual gives an overview of the Faust programming language and of its features through various interactive examples. What is Faust Good For? Faust's syntax allows us to express any DSP algorithm as a block diagram. For example, + is considered as a valid function (and block) taking two arguments (signals) and returning one: Blocks can be easily connected together using the : \"connection\" composition: In that case, we add two signals together and then scale the result of this operation. Thus, Faust is perfect to implement time-domain algorithms that can be easily represented as block diagrams such as filters, waveguide physical models, virtual analog elements, etc. Faust is very concise , for example, here's the implementation of a one pole filter/integrator equivalent to y(n) = x(n) + a_{1}y(n-1) (where a_{1} is the pole): Codes generated by Faust are extremely optimized and usually more efficient that handwritten codes (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using divides instead of multiplies as they get automatically replaced by multiplies by the compiler when possible, etc. Faust is very generic and allows us to write code that will run on dozens of platforms. What is Faust Not (So) Good For? Despite all this, Faust does have some limitations. For instance, it doesn't allow for the efficient implementation of algorithms requiring multi-rates such as the FFT, convolution, etc. While there are tricks to go around this issue, we're fully aware that it is a big one and we're working as hard as possible on it. Faust's conciseness can sometimes become a problem too, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have the \"mental global picture\" of the algorithm to be implemented which in some cases can be hard. While the Faust compiler is relatively bug-free, it does have some limitations and might get stuck in some extreme cases that you will probably never encounter. If you do, shoot us an e-mail ! From here, you can jump to the Quick Start Tutorial section of this manual. Design Principles Since the beginning of its development in 2002, Faust has been guided by various design principles: Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations: : , ~ <: :> (see the section on Diagram Composition Operations for more details). Thanks to the concept of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plug-in formats without any change to the Faust code. Signal Processor Semantic A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. Faust considers two type of signals: integer signals s:\\mathbb{Z}\\rightarrow\\mathbb{Z} and floating point signals s:\\mathbb{Z}\\rightarrow\\mathbb{Q} . Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0 . The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produces an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Introduction"},{"location":"manual/introduction/#introduction","text":"","title":"Introduction"},{"location":"manual/introduction/#what-is-faust","text":"Faust (Functional Audio Stream) is a functional programming language for sound synthesis and audio processing with a strong focus on the design of synthesizers, musical instruments, audio effects, etc. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. It is used on stage for concerts and artistic productions, in education and research, in open source projects as well as in commercial applications. The core component of Faust is its compiler. It allows us to \"translate\" any Faust digital signal processing (DSP) specification to a wide range of non-domain specific languages such as C++, C, JAVA, LLVM IR, WebAssembly, etc. In this regard, Faust can be seen as an alternative to C++ but is much simpler and intuitive to learn. Thanks to a wrapping system called \"architectures,\" codes generated by Faust can be easily compiled into a wide variety of objects ranging from audio plug-ins to standalone applications or smartphone and web apps, etc. This manual gives an overview of the Faust programming language and of its features through various interactive examples.","title":"What is Faust?"},{"location":"manual/introduction/#what-is-faust-good-for","text":"Faust's syntax allows us to express any DSP algorithm as a block diagram. For example, + is considered as a valid function (and block) taking two arguments (signals) and returning one: Blocks can be easily connected together using the : \"connection\" composition: In that case, we add two signals together and then scale the result of this operation. Thus, Faust is perfect to implement time-domain algorithms that can be easily represented as block diagrams such as filters, waveguide physical models, virtual analog elements, etc. Faust is very concise , for example, here's the implementation of a one pole filter/integrator equivalent to y(n) = x(n) + a_{1}y(n-1) (where a_{1} is the pole): Codes generated by Faust are extremely optimized and usually more efficient that handwritten codes (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using divides instead of multiplies as they get automatically replaced by multiplies by the compiler when possible, etc. Faust is very generic and allows us to write code that will run on dozens of platforms.","title":"What is Faust Good For?"},{"location":"manual/introduction/#what-is-faust-not-so-good-for","text":"Despite all this, Faust does have some limitations. For instance, it doesn't allow for the efficient implementation of algorithms requiring multi-rates such as the FFT, convolution, etc. While there are tricks to go around this issue, we're fully aware that it is a big one and we're working as hard as possible on it. Faust's conciseness can sometimes become a problem too, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have the \"mental global picture\" of the algorithm to be implemented which in some cases can be hard. While the Faust compiler is relatively bug-free, it does have some limitations and might get stuck in some extreme cases that you will probably never encounter. If you do, shoot us an e-mail ! From here, you can jump to the Quick Start Tutorial section of this manual.","title":"What is Faust Not (So) Good For?"},{"location":"manual/introduction/#design-principles","text":"Since the beginning of its development in 2002, Faust has been guided by various design principles: Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations: : , ~ <: :> (see the section on Diagram Composition Operations for more details). Thanks to the concept of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plug-in formats without any change to the Faust code.","title":"Design Principles"},{"location":"manual/introduction/#signal-processor-semantic","text":"A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. Faust considers two type of signals: integer signals s:\\mathbb{Z}\\rightarrow\\mathbb{Z} and floating point signals s:\\mathbb{Z}\\rightarrow\\mathbb{Q} . Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0 . The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produces an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Signal Processor Semantic"},{"location":"manual/mathdoc/","text":"Mathematical Documentation The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long). Goals of the Mathdoc There are four main goals, or uses, of the Faust mathematical documentation generator: to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler, to preserve signal processors, independently from any computer language but only under a mathematical form, to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage, to give a new teaching support, as a bridge between code and formulas for signal processing. Installation Requirements faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as Latex doesn't embed SVG directly, breqn , a Latex package to handle automatic breaking of long equations, pdflatex , to compile the Latex output file. Generating the Mathdoc The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leaves the process of generating the documentation unfinished (only the source is produced). Invoking the -mdoc Option Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with -mdoc , 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a Latex file containing the formulas, SVG files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so with all needed libraries to have a self-contained DSP), svg/ contains SVG block-diagram files, tex/ contains the generated Latex file. Invoking faust2mathdoc The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all SVG files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the Latex file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ . Automatic Documentation By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a Latex file with four sections: Equations of process , gathering all formulas needed for process , Block-diagram schema of process , showing the top-level block-diagram of process , Notice of this documentation , summing up generation and conventions information, Complete listing of the input code , listing all needed input files (including libraries). Manual Documentation You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That allows you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the Latex stuff becomes up to you! Six Tags Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive\" notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to true by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections. The mdoc Top-Level Tags The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs. In addition of the four inner tags, <mdoc></mdoc> tags accept free Latex text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the Latex packages included by Faust can be found in the file architecture/latexheader.tex . An Example of Manual Mathdoc <mdoc> \\title{<metadata>name</metadata>} \\author{<metadata>author</metadata>} \\date{\\today} \\maketitle \\begin{tabular}{ll} \\hline \\textbf{name} & <metadata>name</metadata> \\\\ \\textbf{version} & <metadata>version</metadata> \\\\ \\textbf{author} & <metadata>author</metadata> \\\\ \\textbf{license} & <metadata>license</metadata> \\\\ \\textbf{copyright} & <metadata>copyright</metadata> \\\\ \\hline \\end{tabular} \\bigskip </mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; <mdoc> \\section{Presentation of the \"noise.dsp\" Faust program} This program describes a white noise generator with an interactive volume, using a random function. \\subsection{The random function} </mdoc> random = +(12345)~*(1103515245); <mdoc> The \\texttt{random} function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. <equation>random</equation> \\subsection{The noise function} </mdoc> noise = random/2147483647.0; <mdoc> The white noise then corresponds to: <equation>noise</equation> \\subsection{Just add a user interface element to play volume!} </mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); <mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: <equation>process</equation> \\section{Block-diagram schema of process} This process is illustrated on figure 1. <diagram>process</diagram> \\section{Notice of this documentation} You might be careful of certain information and naming conventions used in this documentation: <notice /> \\section{Listing of the input code} The following listing shows the input Faust code, parsed to compile this mathematical documentation. <listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> </mdoc> The -stripmdoc Option The listing of the input code contains all the mathdoc text. As it may be useless in certain cases, we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long). Localization of Mathdoc Files By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian at the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. Summary of the Mathdoc Generation Steps First, to get the full mathematical documentation done on your Faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Mathematical Documentation"},{"location":"manual/mathdoc/#mathematical-documentation","text":"The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long).","title":"Mathematical Documentation"},{"location":"manual/mathdoc/#goals-of-the-mathdoc","text":"There are four main goals, or uses, of the Faust mathematical documentation generator: to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler, to preserve signal processors, independently from any computer language but only under a mathematical form, to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage, to give a new teaching support, as a bridge between code and formulas for signal processing.","title":"Goals of the Mathdoc"},{"location":"manual/mathdoc/#installation-requirements","text":"faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as Latex doesn't embed SVG directly, breqn , a Latex package to handle automatic breaking of long equations, pdflatex , to compile the Latex output file.","title":"Installation Requirements"},{"location":"manual/mathdoc/#generating-the-mathdoc","text":"The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leaves the process of generating the documentation unfinished (only the source is produced).","title":"Generating the Mathdoc"},{"location":"manual/mathdoc/#invoking-the-mdoc-option","text":"Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with -mdoc , 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a Latex file containing the formulas, SVG files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so with all needed libraries to have a self-contained DSP), svg/ contains SVG block-diagram files, tex/ contains the generated Latex file.","title":"Invoking the -mdoc Option"},{"location":"manual/mathdoc/#invoking-faust2mathdoc","text":"The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all SVG files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the Latex file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ .","title":"Invoking faust2mathdoc"},{"location":"manual/mathdoc/#automatic-documentation","text":"By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a Latex file with four sections: Equations of process , gathering all formulas needed for process , Block-diagram schema of process , showing the top-level block-diagram of process , Notice of this documentation , summing up generation and conventions information, Complete listing of the input code , listing all needed input files (including libraries).","title":"Automatic Documentation"},{"location":"manual/mathdoc/#manual-documentation","text":"You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That allows you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the Latex stuff becomes up to you!","title":"Manual Documentation"},{"location":"manual/mathdoc/#six-tags","text":"Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive\" notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to true by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections.","title":"Six Tags"},{"location":"manual/mathdoc/#the-mdoc-top-level-tags","text":"The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs. In addition of the four inner tags, <mdoc></mdoc> tags accept free Latex text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the Latex packages included by Faust can be found in the file architecture/latexheader.tex .","title":"The mdoc Top-Level Tags"},{"location":"manual/mathdoc/#an-example-of-manual-mathdoc","text":"<mdoc> \\title{<metadata>name</metadata>} \\author{<metadata>author</metadata>} \\date{\\today} \\maketitle \\begin{tabular}{ll} \\hline \\textbf{name} & <metadata>name</metadata> \\\\ \\textbf{version} & <metadata>version</metadata> \\\\ \\textbf{author} & <metadata>author</metadata> \\\\ \\textbf{license} & <metadata>license</metadata> \\\\ \\textbf{copyright} & <metadata>copyright</metadata> \\\\ \\hline \\end{tabular} \\bigskip </mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; <mdoc> \\section{Presentation of the \"noise.dsp\" Faust program} This program describes a white noise generator with an interactive volume, using a random function. \\subsection{The random function} </mdoc> random = +(12345)~*(1103515245); <mdoc> The \\texttt{random} function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. <equation>random</equation> \\subsection{The noise function} </mdoc> noise = random/2147483647.0; <mdoc> The white noise then corresponds to: <equation>noise</equation> \\subsection{Just add a user interface element to play volume!} </mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); <mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: <equation>process</equation> \\section{Block-diagram schema of process} This process is illustrated on figure 1. <diagram>process</diagram> \\section{Notice of this documentation} You might be careful of certain information and naming conventions used in this documentation: <notice /> \\section{Listing of the input code} The following listing shows the input Faust code, parsed to compile this mathematical documentation. <listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> </mdoc>","title":"An Example of Manual Mathdoc"},{"location":"manual/mathdoc/#the-stripmdoc-option","text":"The listing of the input code contains all the mathdoc text. As it may be useless in certain cases, we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long).","title":"The -stripmdoc Option"},{"location":"manual/mathdoc/#localization-of-mathdoc-files","text":"By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian at the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work.","title":"Localization of Mathdoc Files"},{"location":"manual/mathdoc/#summary-of-the-mathdoc-generation-steps","text":"First, to get the full mathematical documentation done on your Faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Summary of the Mathdoc Generation Steps"},{"location":"manual/midi/","text":"MIDI and Polyphony Support Similarly to OSC , several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments. Configuring MIDI in Faust MIDI support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [midi:on] metadata to the standard options metadata : declare options \"[midi:on]\"; or using the -midi option in most of faust2xx scripts. MIDI control is configured in Faust using metadata in UI elements . MIDI channels from 1 to 16 can be used at reception or sending time. By convention, using the channel = 0 value (or no channel setting) means \"all channels\". That is, at reception time, MIDI messages received on all channels can be used to control a given parameter, and at sending time, the MIDI message associated to a parameter will be sent on all channels. MIDI metadata are decoded by a special architecture that parses incoming MIDI messages and updates the appropriate control parameters, or send MIDI messages when the UI elements (i.e., sliders, buttons, etc.) are moved. All MIDI configuration metadata in Faust follow the following format: [midi:xxx yyy...] This section provides a list of the most common metadata that can be used to configure of the MIDI behavior of a Faust program. Below, when a 7-bit MIDI parameter is used to drive a button or a checkbox , its maximum value (127) maps to 1 (\"on\") while its minimum value (0) maps to 0 (\"off\"). [midi:ctrl num] or [midi:ctrl num chan] Metadata The [midi:ctrl num] metadata assigns MIDI CC (control) to a specific UI element. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:ctrl num] version can receive messages on all channels, and will send on all channels. The second [midi:ctrl num chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:ctrl num chan]\",...); Where: num : the MIDI CC number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by MIDI CC 11. When CC11=0, then the frequency is 200Hz, when CC11=127, then the frequency is 1000Hz. [midi:keyon midikey] or [midi:keyon midikey chan] Metadata The [midi:keyon midikey] metadata assigns the velocity value of a key-on MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyon midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyon midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyon midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-on message is sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed. [midi:keyoff midikey] or [midi:keyoff midikey chan] Metadata The [midi:keyoff midikey] metadata assigns the velocity value of a key-off MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyoff midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyoff midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyoff midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-off message is sent. Therefore, the frequency will only be updated when MIDI key 62 is released. [midi:key midikey] or [midi:key midikey chan] Metadata The [midi:key midikey] metadata assigns the velocity value of key-on and key-off MIDI messages received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:midikey midikey] version can receive messages on all channels, and will send on all channels. The second [midi:midikey midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:key midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when key-on and key-off messages are sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed and released. [midi:keypress midikey] or [midi:keypress midikey chan] Metadata The [midi:keypress midikey] metadata assigns the pressure (after-touch) value of a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keypress midikey] version can receive messages on all channels, will send on all channels. The second [midi:keypress midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keypress midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the pressure (after-touch) values received on key 62. [midi:chanpress] or [midi:chanpress chan] Metadata The [midi:chanpress] metadata assigns the channel pressure value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:chanpress] version can receive messages on all channels, and will send on all channels. The second [midi:chanpress chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:chanpress chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the volume of a sawtooth wave oscillator is controlled by the channel pressure values. [midi:pgm] or [midi:pgm chan] Metadata The [midi:pgm] metadata assigns the program-change to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will use the UI element range. Only the values described in the UI element range will be used at reception, and can be sent. The first [midi:pgm] version can receive messages on all channels, and will send on all channels. The second [midi:pgm chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = nentry(\"foo[midi:pgm chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the instrument will be choosen in the {0,3} range. [midi:pitchwheel] or [midi:pitchwheel chan] Metadata The [midi:pitchwheel] metadata assigns the pitch-wheel value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 16383} range. When used with a button or a checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. Pitch-wheel values are typically used to control tuning, mapping the {0, 16383} MIDI range to a {-semitone, semitone} range. The ba.semi2ratio function must be used to convert semitones in a frequency multiplicative ratio. The first [midi:pitchwheel] version can receive messages on all channels, and will send on all channels. The second [midi:pitchwheel chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:pitchwheel chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the bend of a sawtooth wave oscillator is controlled by the pitch-wheel in the {-2, 2} semitone range, then converted as a frequency multiplicative ratio and multiplied by a given frequency. [midi:start] Metadata When used with a button or a checkbox, [midi:start] will trigger a value of 1 when a start MIDI message is received. Usage foo = checkbox(\"foo[midi:start]\"); [midi:stop] Metadata When used with a button or a checkbox, [midi:stop] will trigger a value of 0 when a stop MIDI message is received. Usage foo = checkbox(\"foo[midi:stop]\"); [midi:clock] Metadata When used with a button or a checkbox, [midi:clock] will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received (seen by Faust code as a square command signal, to be used to compute higher level information). Usage foo = checkbox(\"foo[midi:clock]\"); MIDI Sync MIDI clock-based synchronization can be used to slave a given Faust program using the metadata presented in the 3 past sections. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: MIDI Polyphony Support Polyphony is conveniently handled in Faust directly by Faust Architectures. Note that programming polyphonic instrument completely from scratch in Faust and without relying on architectures is also possible. In fact, this feature is indispensable if complex signal interactions between the different voices have to be described (like sympathetic strings resonance in a physical model, etc.). However, since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocation and control MIDI messages decoding and mapping. Polyphony support can be added to any Faust program (as long as the target architecture supports it) simply by adding the [nvoices:n] metadata to the standard option metadata where n is the maximum number of voices of polyphony to be allocated: declare options \"[midi:on][nvoices:12]\"; Standard Polyphony Parameters Most Faust architectures allow for the implementation of polyphonic instruments simply by using a set of \"standard user interface names.\" Hence, any Faust program declaring the freq (or key) , gain (or vel or velocity) , and gate parameter is polyphony-compatible. These 3 parameters are directly associated to key-on and key-off events and have the following behavior: When a key-on event is received, gate will be set to 1. Inversely, when a key-off event is received, gate will be set to 0. Therefore, gate is typically used to trigger an envelope, etc. freq is a frequency in Hz computed automatically in function of the value of the pitch contained in a key-on or a key-off message. Alternatively key can be used to get the raw MIDI pitch and describe the pitch to Hz conversion in the DSP code itself (for instance to implement alternative tunings). gain is a linear gain (value between 0-1) computed in function of the velocity value contained in a key-on or a key-off message. Alternatively vel or velocity can be used to get the raw MIDI velocity and describe the velocity to gain conversion in the DSP code itself (for instance to implement alternative velocity curves). Example: Simple Polyphonic Synthesizer In the following example, the standard freq , gain , and gate parameters are used to implement a simple polyphonic synth. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). In the next example, the standard key , gain , and gate parameters are used to implement a simple polyphonic synth with alternate tuning. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). The previous example can be slightly improved by adding an envelope generator and controlling it with gain and gate : Warning: Note that all the active voices of polyphony are added together without scaling! This means that the previous example will likely click if several voices are played at the same time. It is the Faust programmer's responsibility to take this into account in his code. For example, assuming that the number of active voices will always be smaller or equal to 4, the following safeguard could be added to the previous example: process = os.sawtooth(freq)*envelope : /(4); Configuring and Activating Polyphony Polyphony can be activated manually in some Faust architectures using an option/flag during compilation (e.g., typically -poly or -nvoices <num> in the faust2xx scripts). That's also how the Faust Online IDE works where a button can be used to turn polyphony on or off. However, the most standard way to activate polyphony in Faust is to declare the [nvoices:n] metadata which allows us to specify the maximum number of voices of polyphony ( n ) that will be allocated in the generated program. For example, the Faust program from the previous section could be modified such that: which when compiled running (for example): faust2jaqt faustProgram.dsp will generate a MIDI-controllable polyphonic synthesizer. Audio Effects and Polyphonic Synthesizer While audio audio effects can be added directly to the process line of a Faust synthesizer, for example: process = os.sawtooth(freq)*envelope : reverb; it is not a good practice since a new instance of that effect will be created for each active voice of polyphony. The main consequence of this would be an increased CPU cost. Similarly to process , Faust allows for the declaration of an effect line, which identifies an audio effect to be connected to the output of the polyphonic synthesizer. For example, a simple reverb can be added to the previous example simply by writing: In this case, the polyphonic part is based on process and a single instance of the effect defined in effect will be created and shared by all voices. The architecture machinery then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them. Here dm.zita_light is a stereo effect, the mono output of the os.sawtooth(freq)*envelope expression can be split into 2 signals (but would be splitted automatically if kept as a mono output). Also, be aware that this type of construction wont be visible in the corresponding block diagram that will only show what's implemented in the process line. Polyphony and Continuous Pitch Key-on and key-off MIDI messages only send the \"base pitch\" of the instance of a note. Hence, if only the freq standard parameter is used to control the frequency of the synthesizer, its pitch will always be \"quantized\" to the nearest semitone. In order to be able to do glissandi, vibrato, etc., a variable associated to the pitch-wheel needs to be declared and must interact with the \"base frequency\" value retrieved from freq as such: f = hslider(\"freq\",300,50,2000,0.01); bend = ba.semi2ratio(hslider(\"bend[midi:pitchwheel]\",0,-2,2,0.01)); freq = f*bend; // the \"final\" freq parameter to be used The bend variable is controlled by the pitch-wheel thanks to [midi:pitchwheel] metadata , then converted in a frequency ratio using the ba.semi2ratio function. bend is used as a factor multiplied to the base frequency retrieved from freq . Therefore, the default value of bend is 0 in semitones, which corresponds to the central position of the pitch wheel, and will correspond to a multiplicative ratio of 1. A value smaller than 0 will decrease the pitch and a value greater than 0 will increase it. While the above example will have the expected behavior, it is likely that clicking will happen when changing the value of bend since this parameter is not smoothed. Unfortunately, regular smoothing (through the use of si.smoo , for example) is not a good option here. This is due to the fact that instances of polyphonic voices are frozen when a voice is not being used. Since the value of bend might jump from one value to another when a voice is being reactivated/reused, continuous smoothing would probably create an \"ugly sweep\" in that case. Hence, si.polySmooth should be used in this context instead of si.smoo . This function shuts down smoothing for a given number of samples when a trigger is activated. Reusing the example from the previous section, we can implement a click-free polyphonic synthesizer with continuous pitch control: Observe the usage of si.polySmooth here: when gate=0 the signal is not smoothed, when gate=1 the signal is smoothed with a factor of 0.999 after one sample. Complete Example: Sustain Pedal and Additional Parameters Just for fun ;), we improve in this section the example from the previous one by implementing sustain pedal control as well as some modulation controlled by the modulation wheel of the MIDI keyboard. Sustain pedal control can be easily added simply by declaring a sustain parameter controlled by MIDI CC 64 (which is directly linked to the sustain pedal) and interacting with the standard gate parameter: s = hslider(\"sustain[midi:ctrl 64]\",0,0,1,1); t = button(\"gate\"); gate = t+s : min(1); Hence, gate will remain equal to 1 as long as the sustain pedal is pressed. The simple synthesizer from the previous section (which is literally just a sawtooth oscillator) can be slightly improved by processing it with a dynamically-controlled lowpass filter: MIDI CC 1 corresponds to the modulation wheel which is used here to control the cut-off frequency of the lowpass filter. Next we can add a global master, using the MIDI CC 7 standard volume control to change its level:","title":"MIDI Support"},{"location":"manual/midi/#midi-and-polyphony-support","text":"Similarly to OSC , several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments.","title":"MIDI and Polyphony Support"},{"location":"manual/midi/#configuring-midi-in-faust","text":"MIDI support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [midi:on] metadata to the standard options metadata : declare options \"[midi:on]\"; or using the -midi option in most of faust2xx scripts. MIDI control is configured in Faust using metadata in UI elements . MIDI channels from 1 to 16 can be used at reception or sending time. By convention, using the channel = 0 value (or no channel setting) means \"all channels\". That is, at reception time, MIDI messages received on all channels can be used to control a given parameter, and at sending time, the MIDI message associated to a parameter will be sent on all channels. MIDI metadata are decoded by a special architecture that parses incoming MIDI messages and updates the appropriate control parameters, or send MIDI messages when the UI elements (i.e., sliders, buttons, etc.) are moved. All MIDI configuration metadata in Faust follow the following format: [midi:xxx yyy...] This section provides a list of the most common metadata that can be used to configure of the MIDI behavior of a Faust program. Below, when a 7-bit MIDI parameter is used to drive a button or a checkbox , its maximum value (127) maps to 1 (\"on\") while its minimum value (0) maps to 0 (\"off\").","title":"Configuring MIDI in Faust"},{"location":"manual/midi/#midictrl-num-or-midictrl-num-chan-metadata","text":"The [midi:ctrl num] metadata assigns MIDI CC (control) to a specific UI element. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:ctrl num] version can receive messages on all channels, and will send on all channels. The second [midi:ctrl num chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:ctrl num chan]\",...); Where: num : the MIDI CC number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by MIDI CC 11. When CC11=0, then the frequency is 200Hz, when CC11=127, then the frequency is 1000Hz.","title":"[midi:ctrl num] or [midi:ctrl num chan] Metadata"},{"location":"manual/midi/#midikeyon-midikey-or-midikeyon-midikey-chan-metadata","text":"The [midi:keyon midikey] metadata assigns the velocity value of a key-on MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyon midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyon midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyon midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-on message is sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed.","title":"[midi:keyon midikey] or [midi:keyon midikey chan] Metadata"},{"location":"manual/midi/#midikeyoff-midikey-or-midikeyoff-midikey-chan-metadata","text":"The [midi:keyoff midikey] metadata assigns the velocity value of a key-off MIDI message received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keyoff midikey] version can receive messages on all channels, and will send on all channels. The second [midi:keyoff midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keyoff midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when a key-off message is sent. Therefore, the frequency will only be updated when MIDI key 62 is released.","title":"[midi:keyoff midikey] or [midi:keyoff midikey chan] Metadata"},{"location":"manual/midi/#midikey-midikey-or-midikey-midikey-chan-metadata","text":"The [midi:key midikey] metadata assigns the velocity value of key-on and key-off MIDI messages received on a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:midikey midikey] version can receive messages on all channels, and will send on all channels. The second [midi:midikey midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:key midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the velocity value received on key 62 when key-on and key-off messages are sent. Therefore, the frequency will only be updated when MIDI key 62 is pressed and released.","title":"[midi:key midikey] or [midi:key midikey chan] Metadata"},{"location":"manual/midi/#midikeypress-midikey-or-midikeypress-midikey-chan-metadata","text":"The [midi:keypress midikey] metadata assigns the pressure (after-touch) value of a specific midikey to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:keypress midikey] version can receive messages on all channels, will send on all channels. The second [midi:keypress midikey chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:keypress midikey chan]\",...); Where: midikey : the MIDI key number chan : optional, the MIDI channel number Example In the following example, the frequency of a sawtooth wave oscillator is controlled by the pressure (after-touch) values received on key 62.","title":"[midi:keypress midikey] or [midi:keypress midikey chan] Metadata"},{"location":"manual/midi/#midichanpress-or-midichanpress-chan-metadata","text":"The [midi:chanpress] metadata assigns the channel pressure value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 127} range. When used with a button or a checkbox, 1 will be mapped to 127, 0 will be mapped to 0. The first [midi:chanpress] version can receive messages on all channels, and will send on all channels. The second [midi:chanpress chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:chanpress chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the volume of a sawtooth wave oscillator is controlled by the channel pressure values.","title":"[midi:chanpress] or [midi:chanpress chan] Metadata"},{"location":"manual/midi/#midipgm-or-midipgm-chan-metadata","text":"The [midi:pgm] metadata assigns the program-change to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will use the UI element range. Only the values described in the UI element range will be used at reception, and can be sent. The first [midi:pgm] version can receive messages on all channels, and will send on all channels. The second [midi:pgm chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = nentry(\"foo[midi:pgm chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the instrument will be choosen in the {0,3} range.","title":"[midi:pgm] or [midi:pgm chan] Metadata"},{"location":"manual/midi/#midipitchwheel-or-midipitchwheel-chan-metadata","text":"The [midi:pitchwheel] metadata assigns the pitch-wheel value to a Faust parameter. When used in a slider/nentry or a bargraph, this metadata will map the UI element value to the {0, 16383} range. When used with a button or a checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. Pitch-wheel values are typically used to control tuning, mapping the {0, 16383} MIDI range to a {-semitone, semitone} range. The ba.semi2ratio function must be used to convert semitones in a frequency multiplicative ratio. The first [midi:pitchwheel] version can receive messages on all channels, and will send on all channels. The second [midi:pitchwheel chan] version can receive messages on chan only, and will send on the chan channel only (or all channels using the chan = 0 value). Usage foo = hslider(\"foo[midi:pitchwheel chan]\",...); Where: chan : optional, the MIDI channel number Example In the following example, the bend of a sawtooth wave oscillator is controlled by the pitch-wheel in the {-2, 2} semitone range, then converted as a frequency multiplicative ratio and multiplied by a given frequency.","title":"[midi:pitchwheel] or [midi:pitchwheel chan] Metadata"},{"location":"manual/midi/#midistart-metadata","text":"When used with a button or a checkbox, [midi:start] will trigger a value of 1 when a start MIDI message is received. Usage foo = checkbox(\"foo[midi:start]\");","title":"[midi:start] Metadata"},{"location":"manual/midi/#midistop-metadata","text":"When used with a button or a checkbox, [midi:stop] will trigger a value of 0 when a stop MIDI message is received. Usage foo = checkbox(\"foo[midi:stop]\");","title":"[midi:stop] Metadata"},{"location":"manual/midi/#midiclock-metadata","text":"When used with a button or a checkbox, [midi:clock] will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received (seen by Faust code as a square command signal, to be used to compute higher level information). Usage foo = checkbox(\"foo[midi:clock]\");","title":"[midi:clock] Metadata"},{"location":"manual/midi/#midi-sync","text":"MIDI clock-based synchronization can be used to slave a given Faust program using the metadata presented in the 3 past sections. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages:","title":"MIDI Sync"},{"location":"manual/midi/#midi-polyphony-support","text":"Polyphony is conveniently handled in Faust directly by Faust Architectures. Note that programming polyphonic instrument completely from scratch in Faust and without relying on architectures is also possible. In fact, this feature is indispensable if complex signal interactions between the different voices have to be described (like sympathetic strings resonance in a physical model, etc.). However, since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special polyphonic instrument aware architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocation and control MIDI messages decoding and mapping. Polyphony support can be added to any Faust program (as long as the target architecture supports it) simply by adding the [nvoices:n] metadata to the standard option metadata where n is the maximum number of voices of polyphony to be allocated: declare options \"[midi:on][nvoices:12]\";","title":"MIDI Polyphony Support"},{"location":"manual/midi/#standard-polyphony-parameters","text":"Most Faust architectures allow for the implementation of polyphonic instruments simply by using a set of \"standard user interface names.\" Hence, any Faust program declaring the freq (or key) , gain (or vel or velocity) , and gate parameter is polyphony-compatible. These 3 parameters are directly associated to key-on and key-off events and have the following behavior: When a key-on event is received, gate will be set to 1. Inversely, when a key-off event is received, gate will be set to 0. Therefore, gate is typically used to trigger an envelope, etc. freq is a frequency in Hz computed automatically in function of the value of the pitch contained in a key-on or a key-off message. Alternatively key can be used to get the raw MIDI pitch and describe the pitch to Hz conversion in the DSP code itself (for instance to implement alternative tunings). gain is a linear gain (value between 0-1) computed in function of the velocity value contained in a key-on or a key-off message. Alternatively vel or velocity can be used to get the raw MIDI velocity and describe the velocity to gain conversion in the DSP code itself (for instance to implement alternative velocity curves). Example: Simple Polyphonic Synthesizer In the following example, the standard freq , gain , and gate parameters are used to implement a simple polyphonic synth. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). In the next example, the standard key , gain , and gate parameters are used to implement a simple polyphonic synth with alternate tuning. Note that if you execute this code in the Faust Online IDE with polyphony mode activated, you should be able to control this simple synth with any MIDI keyboard connected to your computer. This will only work if you're using Google Chrome (most other browsers are not MIDI-compatible). The previous example can be slightly improved by adding an envelope generator and controlling it with gain and gate : Warning: Note that all the active voices of polyphony are added together without scaling! This means that the previous example will likely click if several voices are played at the same time. It is the Faust programmer's responsibility to take this into account in his code. For example, assuming that the number of active voices will always be smaller or equal to 4, the following safeguard could be added to the previous example: process = os.sawtooth(freq)*envelope : /(4);","title":"Standard Polyphony Parameters"},{"location":"manual/midi/#configuring-and-activating-polyphony","text":"Polyphony can be activated manually in some Faust architectures using an option/flag during compilation (e.g., typically -poly or -nvoices <num> in the faust2xx scripts). That's also how the Faust Online IDE works where a button can be used to turn polyphony on or off. However, the most standard way to activate polyphony in Faust is to declare the [nvoices:n] metadata which allows us to specify the maximum number of voices of polyphony ( n ) that will be allocated in the generated program. For example, the Faust program from the previous section could be modified such that: which when compiled running (for example): faust2jaqt faustProgram.dsp will generate a MIDI-controllable polyphonic synthesizer.","title":"Configuring and Activating Polyphony"},{"location":"manual/midi/#audio-effects-and-polyphonic-synthesizer","text":"While audio audio effects can be added directly to the process line of a Faust synthesizer, for example: process = os.sawtooth(freq)*envelope : reverb; it is not a good practice since a new instance of that effect will be created for each active voice of polyphony. The main consequence of this would be an increased CPU cost. Similarly to process , Faust allows for the declaration of an effect line, which identifies an audio effect to be connected to the output of the polyphonic synthesizer. For example, a simple reverb can be added to the previous example simply by writing: In this case, the polyphonic part is based on process and a single instance of the effect defined in effect will be created and shared by all voices. The architecture machinery then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them. Here dm.zita_light is a stereo effect, the mono output of the os.sawtooth(freq)*envelope expression can be split into 2 signals (but would be splitted automatically if kept as a mono output). Also, be aware that this type of construction wont be visible in the corresponding block diagram that will only show what's implemented in the process line.","title":"Audio Effects and Polyphonic Synthesizer"},{"location":"manual/midi/#polyphony-and-continuous-pitch","text":"Key-on and key-off MIDI messages only send the \"base pitch\" of the instance of a note. Hence, if only the freq standard parameter is used to control the frequency of the synthesizer, its pitch will always be \"quantized\" to the nearest semitone. In order to be able to do glissandi, vibrato, etc., a variable associated to the pitch-wheel needs to be declared and must interact with the \"base frequency\" value retrieved from freq as such: f = hslider(\"freq\",300,50,2000,0.01); bend = ba.semi2ratio(hslider(\"bend[midi:pitchwheel]\",0,-2,2,0.01)); freq = f*bend; // the \"final\" freq parameter to be used The bend variable is controlled by the pitch-wheel thanks to [midi:pitchwheel] metadata , then converted in a frequency ratio using the ba.semi2ratio function. bend is used as a factor multiplied to the base frequency retrieved from freq . Therefore, the default value of bend is 0 in semitones, which corresponds to the central position of the pitch wheel, and will correspond to a multiplicative ratio of 1. A value smaller than 0 will decrease the pitch and a value greater than 0 will increase it. While the above example will have the expected behavior, it is likely that clicking will happen when changing the value of bend since this parameter is not smoothed. Unfortunately, regular smoothing (through the use of si.smoo , for example) is not a good option here. This is due to the fact that instances of polyphonic voices are frozen when a voice is not being used. Since the value of bend might jump from one value to another when a voice is being reactivated/reused, continuous smoothing would probably create an \"ugly sweep\" in that case. Hence, si.polySmooth should be used in this context instead of si.smoo . This function shuts down smoothing for a given number of samples when a trigger is activated. Reusing the example from the previous section, we can implement a click-free polyphonic synthesizer with continuous pitch control: Observe the usage of si.polySmooth here: when gate=0 the signal is not smoothed, when gate=1 the signal is smoothed with a factor of 0.999 after one sample.","title":"Polyphony and Continuous Pitch"},{"location":"manual/midi/#complete-example-sustain-pedal-and-additional-parameters","text":"Just for fun ;), we improve in this section the example from the previous one by implementing sustain pedal control as well as some modulation controlled by the modulation wheel of the MIDI keyboard. Sustain pedal control can be easily added simply by declaring a sustain parameter controlled by MIDI CC 64 (which is directly linked to the sustain pedal) and interacting with the standard gate parameter: s = hslider(\"sustain[midi:ctrl 64]\",0,0,1,1); t = button(\"gate\"); gate = t+s : min(1); Hence, gate will remain equal to 1 as long as the sustain pedal is pressed. The simple synthesizer from the previous section (which is literally just a sawtooth oscillator) can be slightly improved by processing it with a dynamically-controlled lowpass filter: MIDI CC 1 corresponds to the modulation wheel which is used here to control the cut-off frequency of the lowpass filter. Next we can add a global master, using the MIDI CC 7 standard volume control to change its level:","title":"Complete Example: Sustain Pedal and Additional Parameters"},{"location":"manual/optimizing/","text":"Optimizing the Code Optimizing the DSP Code Faust is a Domain Specific Language helping the programmer to write very high-level and concise DSP code, while letting the compiler do the hard work of producing the best and most efficient implementation of the specification. When processing the DSP source, the compiler typing system is able to discover how the described computations are effectively separated in four main categories: computations done at compilation/specialisation time : this is the place for algorithmic signal processors definition heavily based on the lambda-calculus constitute of the language, together with its pattern-matching capabilities computations done at init time : for instance all the code that depends of the actual sample-rate, or filling of some internal tables (coded with the rdtable or rwtable language primitives) computations done at control rate : typically all code that read the current values of controllers (buttons, sliders, nentries) and update the DSP internal state which depends of them computations done at sample rate : all remaining code that process and produce the samples One can think of these four categories as different computation rates . The programmer can possibly split its DSP algorithm to distribute the needed computation in the most appropriate domain ( slower rate domain better than faster rate domain) and possibly rewrite some parts of its DSP algorithm from one domain to a slower rate one to finally obtain the most efficient code. Computations Done at Compilation/Specialisation Time Using Pattern Matching TODO : explain how pattern-matching can be used to algorithmically describe signal processors, explain the principle of defining a new DSL inside the Faust DSL (with fds.lib , physmodels.lib , wdmodels.lib as examples). Specializing the DSP Code The Faust compiler can possibly do a lot of optimizations at compile time. The DSP code can for instance be compiled for a fixed sample rate, thus doing at compile time all computation that depends of it. Since the Faust compiler will look for librairies starting from the local folder, a simple way is to locally copy the libraries/platform.lib file (which contains the SR definition), and change its definition for a fixed value like 48000 Hz. Then the DSP code has to be recompiled for the specialisation to take effect. Note that libraries/platform.lib also contains the definition of the tablesize constant which is used in various places to allocate tables for oscillators. Thus decreasing this value can save memory, for instance when compiling for embedded devices. This is the technique used in some Faust services scripts which add the -I /usr/local/share/faust/embedded/ parameter to the Faust command line to use a special version of the platform.lib file. Computations Done at Init time If not specialized with a constant value at compilation time, all computations that use the sample rate (which is accessed with the ma.SR in the DSP source code and given as parameter in the DSP init function) will be done at init time, and possibly again each time the same DSP is initialized with another sample rate. Using rdtable or rwtable TODO : explain how computations can be done at init time and how to use rdtable or rwtable to store pre-computed values. Several tabulation functions can possibly be used. Computations Done at Control Rate Parameter Smoothing Control parameters are sampled once per block, their values are considered constant during the block, and the internal state depending of them is updated and appears at the beginning of the compute method, before the sample rate DSP loop. In the following DSP code, the vol slider value is directly applied on the input audio signal: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01); process = *(vol); In the generated C++ code for compute , the vol slider value is sampled before the actual DSP loop, by reading the fHslider0 field kept in a local fSlow0 variable: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0 * float(input0[i0])); } } If the control parameter needs to be smoothed (like to avoid clicks or too abrupt changes), with the control : si.smoo kind of code, the computation rate moves from control rate to sample rate . If the previous DSP code is now changed with: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01) : si.smoo; process = *(vol); The vol slider is sampled before the actual DSP loop and multiplied by the filter fConst0 constant computed at init time, and finally used in the DSP loop in the smoothing filter: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } So the CPU usage will obviously be higher, and the need for parameter smoothing should be carefully studied. Another point to consider is the order of computation when smoothing control. In the following DSP code, the dB slider value is first converted first to a linear value, then smoothed: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : ba.db2linear : si.smoo; process = *(smoother_vol); And the generated C++ code for compute has the costly pow math function used in ba.db2linear evaluted at control rate, so once before the DSP loop: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * std::pow(1e+01f, 0.05f * float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } But if the order between ba.db2linear and si.smoo is reversed like in the following code: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : si.smoo : ba.db2linear; process = *(smoother_vol); The generated C++ code for compute now has the pow math function used in ba.db2linear evaluated at sample rate in the DSP loop, which is obviously much more costly: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * std::pow(1e+01f, 0.05f * fRec0[0])); fRec0[1] = fRec0[0]; } } So to obtain the best performances in the generated code, all costly computations have to be done on the control value (as much as possible, this may not always be the desirable behaviour), and si.smoo (or any function that moves the computation from control rate to sample rate) as the last operation. Computations Done at Sample Rate Possibly deactivating table range check with -ct option The -ct option is activated by default (starting at Faust version 2.53.4), but can possibly be removed (using -ct 0 ) to speed up the code. Read Debugging rdtable and rwtable primitives for a complete description. Using Function Tabulation The use of rdtable kind of compilation done at init time can be simplified using the ba.tabulate or ba.tabulate_chebychev functions to tabulate a given unary function fun on a given range. A table is created and filled with precomputed values, and can be used to compute fun(x) in a more efficient way (at the cost of additional static memory needed for the table). Using Fast Math Functions When costly math functions still appear in the sample rate code, the -fm compilation option can possibly be used to replace the standard versions provided by the underlying OS (like std::cos , std::tan ... in C++ for instance) with user defined ones (hopefully faster, but possibly less precise). Delay lines implementation and DSP memory size The Faust compiler automatically allocates buffers for the delay lines. At each sample calculation, the delayed signal is written to a specific location (the write position) and read from another location (the read position), the distance in samples between the read and write indexes representing the delay itself. There are two possible strategies for implementing delay lines: either the read and write indices remain the same and the delay line memory is moved after each sample calculation, or the read and write indices move themselves along the delay line (with two possible wrapping index methods). These multiple methods allow arbitration between memory consumption and the CPU cost of using the delay line. Two compiler options -mcd <n> ( -max-copy-delay ) and -dlt <n> ( --delay-line-threshold ) allow you to play with both strategies and even combine them. For very short delay lines of up to two samples, the first strategy is implemented by manually shifting the buffer. Then a shift loop is generated for delay from 2 up to -mcd <n> samples. For delays values bigger than -mcd <n> samples, the second strategy is implemented by: either using arrays of power-of-two sizes accessed using mask based index computation with delays smaller than -dlt <n> value. or using a wrapping index moved by an if based method where the increasing index is compared to the delay-line size, and wrapped to zero when reaching it. This method is used for to delay values bigger then -dlt <n> . In this strategy the first method is faster but consumes more memory (since a delay line of a given size will be extended to the next power-of-two size), and the second method is slower but consume less memory. Note that by default -mcd 16 is -dlt <INT_MAX> values are used. Here is a scheme explaining the mecanism: [ shift buffer |-mcd <N1>| wrapping power-of-two buffer |-dlt <N2>| if based wrapping buffer ] Here is an example of a Faust program with 10 delay lines in parallel, each delaying a separated input, with three ways of compiling it (using the defaut -scalar mode): When compiling with faust -mcd 20 , since 20 is larger than the size of the largest delay line, all of them are compiled with the shifted memory strategy: ... // The DSP memory layout float fVec0[11]; float fVec1[10]; float fVec2[9]; float fVec3[8]; float fVec4[7]; float fVec5[6]; float fVec6[5]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[0] = float(input9[i0]); fVec1[0] = float(input8[i0]); fVec2[0] = float(input7[i0]); fVec3[0] = float(input6[i0]); fVec4[0] = float(input5[i0]); fVec5[0] = float(input4[i0]); fVec6[0] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } for (int j2 = 8; j2 > 0; j2 = j2 - 1) { fVec2[j2] = fVec2[j2 - 1]; } for (int j3 = 7; j3 > 0; j3 = j3 - 1) { fVec3[j3] = fVec3[j3 - 1]; } for (int j4 = 6; j4 > 0; j4 = j4 - 1) { fVec4[j4] = fVec4[j4 - 1]; } for (int j5 = 5; j5 > 0; j5 = j5 - 1) { fVec5[j5] = fVec5[j5 - 1]; } for (int j6 = 4; j6 > 0; j6 = j6 - 1) { fVec6[j6] = fVec6[j6 - 1]; } for (int j7 = 3; j7 > 0; j7 = j7 - 1) { fVec7[j7] = fVec7[j7 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the very short delay lines of up to two samples by manually shifting the buffer method can be seen in those lines: ... // Delay line of 1 sample fVec8[1] = fVec8[0]; // Delay line of 2 samples fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; ... and the shift loop is generated for delay from 2 up to -mcd <n> samples method can be seen in those lines: ... output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); // Shift delay line of 10 samples for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } // Shift delay line of 9 samples for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } ... When compiled with faust -mcd 0 , all delay lines use the wrapping index second strategy with power-of-two size (since -dlt <INT_MAX> is used by default): ... // The DSP memory layout int IOTA0; float fVec0[16]; float fVec1[16]; float fVec2[16]; float fVec3[8]; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[4]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[IOTA0 & 15] = float(input9[i0]); fVec1[IOTA0 & 15] = float(input8[i0]); fVec2[IOTA0 & 15] = float(input7[i0]); fVec3[IOTA0 & 7] = float(input6[i0]); fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[IOTA0 & 3] = float(input2[i0]); fVec8[IOTA0 & 1] = float(input0[i0]); fVec9[IOTA0 & 3] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[(IOTA0 - 10) & 15] + fVec1[(IOTA0 - 9) & 15] + fVec2[(IOTA0 - 8) & 15] + fVec3[(IOTA0 - 7) & 7] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[(IOTA0 - 3) & 3] + fVec8[(IOTA0 - 1) & 1] + fVec9[(IOTA0 - 2) & 3]); IOTA0 = IOTA0 + 1; } } ... In this code example, several delay lines of various power-of-two size (2, 4, 8, 16) are generated. A unique continuously incremented IOTA0 variable is shared between all delay lines. The wrapping index code is generated with this (IOTA0 - 5) & 7 kind of code, with a power-of-two - 1 mask (so 8 - 1 = 7 here). When compiled with faust -mcd 4 -dlt 7 , a mixture of the three generation strategies is used: // The DSP memory layout ... int fVec0_widx; float fVec0[11]; int fVec1_widx; float fVec1[10]; int fVec2_widx; float fVec2[9]; int fVec3_widx; float fVec3[8]; int IOTA0; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { int fVec0_widx_tmp = fVec0_widx; fVec0[fVec0_widx_tmp] = float(input9[i0]); int fVec0_ridx_tmp0 = fVec0_widx - 10; int fVec1_widx_tmp = fVec1_widx; fVec1[fVec1_widx_tmp] = float(input8[i0]); int fVec1_ridx_tmp0 = fVec1_widx - 9; int fVec2_widx_tmp = fVec2_widx; fVec2[fVec2_widx_tmp] = float(input7[i0]); int fVec2_ridx_tmp0 = fVec2_widx - 8; int fVec3_widx_tmp = fVec3_widx; fVec3[fVec3_widx_tmp] = float(input6[i0]); int fVec3_ridx_tmp0 = fVec3_widx - 7; fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[((fVec0_ridx_tmp0 < 0) ? fVec0_ridx_tmp0 + 11 : fVec0_ridx_tmp0)] + fVec1[((fVec1_ridx_tmp0 < 0) ? fVec1_ridx_tmp0 + 10 : fVec1_ridx_tmp0)] + fVec2[((fVec2_ridx_tmp0 < 0) ? fVec2_ridx_tmp0 + 9 : fVec2_ridx_tmp0)] + fVec3[((fVec3_ridx_tmp0 < 0) ? fVec3_ridx_tmp0 + 8 : fVec3_ridx_tmp0)] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[3] + fVec8[1] + fVec9[2]); fVec0_widx_tmp = fVec0_widx_tmp + 1; fVec0_widx_tmp = ((fVec0_widx_tmp == 11) ? 0 : fVec0_widx_tmp); fVec0_widx = fVec0_widx_tmp; fVec1_widx_tmp = fVec1_widx_tmp + 1; fVec1_widx_tmp = ((fVec1_widx_tmp == 10) ? 0 : fVec1_widx_tmp); fVec1_widx = fVec1_widx_tmp; fVec2_widx_tmp = fVec2_widx_tmp + 1; fVec2_widx_tmp = ((fVec2_widx_tmp == 9) ? 0 : fVec2_widx_tmp); fVec2_widx = fVec2_widx_tmp; fVec3_widx_tmp = fVec3_widx_tmp + 1; fVec3_widx_tmp = ((fVec3_widx_tmp == 8) ? 0 : fVec3_widx_tmp); fVec3_widx = fVec3_widx_tmp; IOTA0 = IOTA0 + 1; for (int j0 = 3; j0 > 0; j0 = j0 - 1) { fVec7[j0] = fVec7[j0 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the wrapping index moved by an if based method can be recognized with the use of those fVec0_ridx_tmp0 and fVec0_widx_tmp0 kind of variables. Choosing values that use less memory can be particularly important in the context of embedded devices. Testing different combinations of the -mcd and -dlt options can help optimize CPU utilisation, to summarize: chosing a big n value for -mcd n will consume less memory but the shift loop will start to be time consuming with big delay values. This model may sometimes be better suited if the C++ or LLVM compiler correctly auto-vectorizes the code and generates more efficient SIMD code. chosing -mcd 0 will activate the wrapping index second strategy for all delay lines in the DSP code, then playing with -dlt <n> allows to arbitrate between the faster but consuming more memory method and slower but consume less memory method. chosing a combinaison of -mcd n1 and -dlt <n2> can possibly be the model to chose when a lot of delay lines with different sizes are used in the DSP code. Using the benchmark tools faustbench and faustbench-llvm allow to refine the choice of compilation options. Recursive signals In the C++ generated code, the delays lines appear as fVecXX arrays. When recursion is used in the DSP, a one sample delay is automatically added in the recursive path, and a very short delay line is allocated (appearing as fRecX arrays in the generated code). Here is the code of a recursively defined integrator: And the generated C++ code with the iRec0 buffer: ... // The DSP memory layout int iRec0[2]; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(iRec0[0]); iRec0[1] = iRec0[0]; } } ... Delay lines in recursive signals Here is an example of a Faust program with 10 recursive blocks in parallel, each using a delay line of increasing value: Since a recursive signal uses a one sample delay in its loop, a buffer is allocated to handle the delay. When a delay is used in addition to the recursive signal, a single buffer is allocated to combine the two delay sources. The generated code using faust -mcd 0 for instance is now: ... // The DSP memory layout int IOTA0; float fRec0[4]; float fRec1[4]; float fRec2[8]; float fRec3[8]; float fRec4[8]; float fRec5[8]; float fRec6[16]; float fRec7[16]; float fRec8[16]; float fRec9[16]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 3] = float(input0[i0]) + fRec0[(IOTA0 - 2) & 3]; fRec1[IOTA0 & 3] = float(input1[i0]) + fRec1[(IOTA0 - 3) & 3]; fRec2[IOTA0 & 7] = float(input2[i0]) + fRec2[(IOTA0 - 4) & 7]; fRec3[IOTA0 & 7] = float(input3[i0]) + fRec3[(IOTA0 - 5) & 7]; fRec4[IOTA0 & 7] = float(input4[i0]) + fRec4[(IOTA0 - 6) & 7]; fRec5[IOTA0 & 7] = float(input5[i0]) + fRec5[(IOTA0 - 7) & 7]; fRec6[IOTA0 & 15] = float(input6[i0]) + fRec6[(IOTA0 - 8) & 15]; fRec7[IOTA0 & 15] = float(input7[i0]) + fRec7[(IOTA0 - 9) & 15]; fRec8[IOTA0 & 15] = float(input8[i0]) + fRec8[(IOTA0 - 10) & 15]; fRec9[IOTA0 & 15] = float(input9[i0]) + fRec9[(IOTA0 - 11) & 15]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 3] + fRec1[IOTA0 & 3] + fRec2[IOTA0 & 7] + fRec3[IOTA0 & 7] + fRec4[IOTA0 & 7] + fRec5[IOTA0 & 7] + fRec6[IOTA0 & 15] + fRec7[IOTA0 & 15] + fRec8[IOTA0 & 15] + fRec9[IOTA0 & 15]); IOTA0 = IOTA0 + 1; } } ... with buffers named fRecX instead of fVecX in the previous example. The -mcd <n> and -dlt <n> options can be used with the same purpose. Managing DSP Memory Layout On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. This can be controled using the -mem compilation option and an adapted architecture file . Optimizing the C++ or LLVM Code From a given DSP program, the Faust compiler tries to generate the most efficient implementation. Optimizations can be done at DSP writing time, or later on when the target langage is generated (like C++ or LLVM IR). The generated code can have different shapes depending of compilation options, and can run faster of slower. Several programs and tools are available to help Faust programmers to test (for possible numerical or precision issues), optimize their programs by discovering the best set of options for a given DSP code, and finally compile them into native code for the target CPUs. By default the Faust compiler produces a big scalar loop in the generated mydsp::compute method. Compiler options allow to generate other code shapes , like for instance separated simpler loops connected with buffers in the so-called vectorized mode (obtained using the -vec option). The assumption is that auto-vectorizer passes in modern compilers will be able to better generate efficient SIMD code for them. In this vec option, the size of the internal buffer can be changed using the -vs value option. Moreover the computation graph can be organized in deep-first order using -dfs . Delay lines implementation can be be controlled with the -mcd size and -dlt size options, to choose for example between power-of-two sizes and mask based wrapping (faster but consumming more memory) or if based wrapping , slower but consumming less memory. Many other compilation choices are fully controllable with options. Note that the C/C++ and LLVM backends offer the greatest number of compilation options. Here are just a few of them: -clang option: when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi option: when compiled with the C++ backend, does not add the 'virtual' keyword. This option can be especially useful in embedded devices context -mapp option: simpler/faster versions of 'floor/ceil/fmod/remainder' functions (experimental) Manually testing each of them and their combination is out of reach. So several tools have been developed to automatize that process and help search the configuration space to discover the best set of compilation options (be sure to run make benchmark && sudo make devinstall in Faust toplevel folder to install the benchmark tools): faustbench The faustbench tool uses the C++ backend to generate a set of C++ files produced with different Faust compiler options. All files are then compiled in a unique binary that will measure DSP CPU of all versions of the compiled DSP. The tool is supposed to be launched in a terminal, but it can be used to generate an iOS project, ready to be launched and tested in Xcode. A more complete documentation is available on the this page . faustbench-llvm The faustbench-llvm tool uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU usage. Additional Faust compiler options can be given beside the ones that will be automatically explored by the tool. A more complete documentation is available on the this page . faust2bench The faust2bench tool allows to benchmark a given DSP program: faust2bench -h Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable So something like faust2bench -vec -lv 0 -vs 4 foo.dsp is used to produce an executable, then launching ./foo gives : ./foo ./foo : 303.599 MBytes/sec (DSP CPU % : 0.224807 at 44100 Hz) The -inj option allows to possibly inject and benchmark an external C++ class to be adapted to behave as a dsp class, like in the following adapted.cpp example. The inherited compute method is rewritten to call the external C++ limiterStereo.SetPreGain etc... code to update the controllers, and the method limiterStereo.Process which computes the DSP: #include \"faust/dsp/dsp.h\" #include \"Limiter.hpp\" struct mydsp : public dsp { Limiter<float> limiterStereo; void init(int sample_rate) { limiterStereo.SetSR(sample_rate); } int getNumInputs() { return 2; } int getNumOutputs() { return 2; } int getSampleRate() { return 44100; } void instanceInit(int sample_rate) {} void instanceConstants(int sample_rate) {} void instanceResetUserInterface() {} void instanceClear() {} void buildUserInterface(UI* ui_interface) {} dsp* clone() { return new mydsp(); } void metadata(Meta* m) {} void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { limiterStereo.SetPreGain(0.5); limiterStereo.SetAttTime(0.5); limiterStereo.SetHoldTime(0.5); limiterStereo.SetRelTime(0.5); limiterStereo.SetThreshold(0.5); limiterStereo.Process(inputs, outputs, count); } }; Using faust2bench -inj adapted.cpp dummy.dsp creates the executable to be tested with ./dummy (remember that dummy.dsp is a program that is not actually used in -inj mode). dynamic-faust The dynamic-faust tool uses the dynamic compilation chain (based on the LLVM backend), and compiles a Faust DSP source to a LLVM IR (.ll), bicode (.bc), machine code (.mc) or object code (.o) output file. This is an alternative to the C++ compilation chain, since DSP code can be compiled to object code (.o), then used and linked in a regular C++ project. A more complete documentation is available on the this page . Optimizing with any faust2xx tool All faust2xx tools compile in scalar mode by default, but can take any combination of optimal options (like -vec -fun -vs 32 -dfs -mcd 32 for instance) the previously described tools will automatically find. So by chaining the use of faustbench of faustbench-llvm to discover the best compilation options for a given DSP, then use them in the desired faust2xx tool, a CPU optimized standalone or plugin can be obtained. Note that some faust2xx tools like faust2max6 or faust2caqt can internally call the faustbench-llvm tool to discover and later on use the best possible compilation options. Compiling for Multiple CPUs On modern CPUs, compiling native code dedicated to the target processor is critical to obtain the best possible performances. When using the C++ backend, the same C++ file can be compiled with gcc of clang for each possible target CPU using the appropriate -march=cpu option. When using the LLVM backend, the same LLVM IR code can be compiled into CPU specific machine code using the dynamic-faust tool. This step will typically be done using the best compilation options automatically found with the faustbench tool or faustbench-llvm tools. A specialized tool has been developed to combine all the possible options. faust2object The faust2object tool either uses the standard C++ compiler or the LLVM dynamic compilation chain (the dynamic-faust tool) to compile a Faust DSP to object code files (.o) and wrapper C++ header files for different CPUs. The DSP name is used in the generated C++ and object code files, thus allowing to generate distinct versions of the code that can finally be linked together in a single binary. A more complete documentation is available on the this page .","title":"Optimizing the Code"},{"location":"manual/optimizing/#optimizing-the-code","text":"","title":"Optimizing the Code"},{"location":"manual/optimizing/#optimizing-the-dsp-code","text":"Faust is a Domain Specific Language helping the programmer to write very high-level and concise DSP code, while letting the compiler do the hard work of producing the best and most efficient implementation of the specification. When processing the DSP source, the compiler typing system is able to discover how the described computations are effectively separated in four main categories: computations done at compilation/specialisation time : this is the place for algorithmic signal processors definition heavily based on the lambda-calculus constitute of the language, together with its pattern-matching capabilities computations done at init time : for instance all the code that depends of the actual sample-rate, or filling of some internal tables (coded with the rdtable or rwtable language primitives) computations done at control rate : typically all code that read the current values of controllers (buttons, sliders, nentries) and update the DSP internal state which depends of them computations done at sample rate : all remaining code that process and produce the samples One can think of these four categories as different computation rates . The programmer can possibly split its DSP algorithm to distribute the needed computation in the most appropriate domain ( slower rate domain better than faster rate domain) and possibly rewrite some parts of its DSP algorithm from one domain to a slower rate one to finally obtain the most efficient code.","title":"Optimizing the DSP Code"},{"location":"manual/optimizing/#computations-done-at-compilationspecialisation-time","text":"","title":"Computations Done at Compilation/Specialisation Time"},{"location":"manual/optimizing/#using-pattern-matching","text":"TODO : explain how pattern-matching can be used to algorithmically describe signal processors, explain the principle of defining a new DSL inside the Faust DSL (with fds.lib , physmodels.lib , wdmodels.lib as examples).","title":"Using Pattern Matching"},{"location":"manual/optimizing/#specializing-the-dsp-code","text":"The Faust compiler can possibly do a lot of optimizations at compile time. The DSP code can for instance be compiled for a fixed sample rate, thus doing at compile time all computation that depends of it. Since the Faust compiler will look for librairies starting from the local folder, a simple way is to locally copy the libraries/platform.lib file (which contains the SR definition), and change its definition for a fixed value like 48000 Hz. Then the DSP code has to be recompiled for the specialisation to take effect. Note that libraries/platform.lib also contains the definition of the tablesize constant which is used in various places to allocate tables for oscillators. Thus decreasing this value can save memory, for instance when compiling for embedded devices. This is the technique used in some Faust services scripts which add the -I /usr/local/share/faust/embedded/ parameter to the Faust command line to use a special version of the platform.lib file.","title":"Specializing the DSP Code"},{"location":"manual/optimizing/#computations-done-at-init-time","text":"If not specialized with a constant value at compilation time, all computations that use the sample rate (which is accessed with the ma.SR in the DSP source code and given as parameter in the DSP init function) will be done at init time, and possibly again each time the same DSP is initialized with another sample rate.","title":"Computations Done at Init time"},{"location":"manual/optimizing/#using-rdtable-or-rwtable","text":"TODO : explain how computations can be done at init time and how to use rdtable or rwtable to store pre-computed values. Several tabulation functions can possibly be used.","title":"Using rdtable or rwtable"},{"location":"manual/optimizing/#computations-done-at-control-rate","text":"","title":"Computations Done at Control Rate"},{"location":"manual/optimizing/#parameter-smoothing","text":"Control parameters are sampled once per block, their values are considered constant during the block, and the internal state depending of them is updated and appears at the beginning of the compute method, before the sample rate DSP loop. In the following DSP code, the vol slider value is directly applied on the input audio signal: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01); process = *(vol); In the generated C++ code for compute , the vol slider value is sampled before the actual DSP loop, by reading the fHslider0 field kept in a local fSlow0 variable: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0 * float(input0[i0])); } } If the control parameter needs to be smoothed (like to avoid clicks or too abrupt changes), with the control : si.smoo kind of code, the computation rate moves from control rate to sample rate . If the previous DSP code is now changed with: import(\"stdfaust.lib\"); vol = hslider(\"Volume\", 0.5, 0, 1, 0.01) : si.smoo; process = *(vol); The vol slider is sampled before the actual DSP loop and multiplied by the filter fConst0 constant computed at init time, and finally used in the DSP loop in the smoothing filter: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } So the CPU usage will obviously be higher, and the need for parameter smoothing should be carefully studied. Another point to consider is the order of computation when smoothing control. In the following DSP code, the dB slider value is first converted first to a linear value, then smoothed: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : ba.db2linear : si.smoo; process = *(smoother_vol); And the generated C++ code for compute has the costly pow math function used in ba.db2linear evaluted at control rate, so once before the DSP loop: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * std::pow(1e+01f, 0.05f * float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * fRec0[0]); fRec0[1] = fRec0[0]; } } But if the order between ba.db2linear and si.smoo is reversed like in the following code: import(\"stdfaust.lib\"); smoother_vol = hslider(\"Volume\", -6.0, -120.0, .0, 0.01) : si.smoo : ba.db2linear; process = *(smoother_vol); The generated C++ code for compute now has the pow math function used in ba.db2linear evaluated at sample rate in the DSP loop, which is obviously much more costly: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = fConst0 * float(fHslider0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = fSlow0 + fConst1 * fRec0[1]; output0[i0] = FAUSTFLOAT(float(input0[i0]) * std::pow(1e+01f, 0.05f * fRec0[0])); fRec0[1] = fRec0[0]; } } So to obtain the best performances in the generated code, all costly computations have to be done on the control value (as much as possible, this may not always be the desirable behaviour), and si.smoo (or any function that moves the computation from control rate to sample rate) as the last operation.","title":"Parameter Smoothing"},{"location":"manual/optimizing/#computations-done-at-sample-rate","text":"","title":"Computations Done at Sample Rate"},{"location":"manual/optimizing/#possibly-deactivating-table-range-check-with-ct-option","text":"The -ct option is activated by default (starting at Faust version 2.53.4), but can possibly be removed (using -ct 0 ) to speed up the code. Read Debugging rdtable and rwtable primitives for a complete description.","title":"Possibly deactivating table range check with -ct option"},{"location":"manual/optimizing/#using-function-tabulation","text":"The use of rdtable kind of compilation done at init time can be simplified using the ba.tabulate or ba.tabulate_chebychev functions to tabulate a given unary function fun on a given range. A table is created and filled with precomputed values, and can be used to compute fun(x) in a more efficient way (at the cost of additional static memory needed for the table).","title":"Using Function Tabulation"},{"location":"manual/optimizing/#using-fast-math-functions","text":"When costly math functions still appear in the sample rate code, the -fm compilation option can possibly be used to replace the standard versions provided by the underlying OS (like std::cos , std::tan ... in C++ for instance) with user defined ones (hopefully faster, but possibly less precise).","title":"Using Fast Math Functions"},{"location":"manual/optimizing/#delay-lines-implementation-and-dsp-memory-size","text":"The Faust compiler automatically allocates buffers for the delay lines. At each sample calculation, the delayed signal is written to a specific location (the write position) and read from another location (the read position), the distance in samples between the read and write indexes representing the delay itself. There are two possible strategies for implementing delay lines: either the read and write indices remain the same and the delay line memory is moved after each sample calculation, or the read and write indices move themselves along the delay line (with two possible wrapping index methods). These multiple methods allow arbitration between memory consumption and the CPU cost of using the delay line. Two compiler options -mcd <n> ( -max-copy-delay ) and -dlt <n> ( --delay-line-threshold ) allow you to play with both strategies and even combine them. For very short delay lines of up to two samples, the first strategy is implemented by manually shifting the buffer. Then a shift loop is generated for delay from 2 up to -mcd <n> samples. For delays values bigger than -mcd <n> samples, the second strategy is implemented by: either using arrays of power-of-two sizes accessed using mask based index computation with delays smaller than -dlt <n> value. or using a wrapping index moved by an if based method where the increasing index is compared to the delay-line size, and wrapped to zero when reaching it. This method is used for to delay values bigger then -dlt <n> . In this strategy the first method is faster but consumes more memory (since a delay line of a given size will be extended to the next power-of-two size), and the second method is slower but consume less memory. Note that by default -mcd 16 is -dlt <INT_MAX> values are used. Here is a scheme explaining the mecanism: [ shift buffer |-mcd <N1>| wrapping power-of-two buffer |-dlt <N2>| if based wrapping buffer ] Here is an example of a Faust program with 10 delay lines in parallel, each delaying a separated input, with three ways of compiling it (using the defaut -scalar mode): When compiling with faust -mcd 20 , since 20 is larger than the size of the largest delay line, all of them are compiled with the shifted memory strategy: ... // The DSP memory layout float fVec0[11]; float fVec1[10]; float fVec2[9]; float fVec3[8]; float fVec4[7]; float fVec5[6]; float fVec6[5]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[0] = float(input9[i0]); fVec1[0] = float(input8[i0]); fVec2[0] = float(input7[i0]); fVec3[0] = float(input6[i0]); fVec4[0] = float(input5[i0]); fVec5[0] = float(input4[i0]); fVec6[0] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } for (int j2 = 8; j2 > 0; j2 = j2 - 1) { fVec2[j2] = fVec2[j2 - 1]; } for (int j3 = 7; j3 > 0; j3 = j3 - 1) { fVec3[j3] = fVec3[j3 - 1]; } for (int j4 = 6; j4 > 0; j4 = j4 - 1) { fVec4[j4] = fVec4[j4 - 1]; } for (int j5 = 5; j5 > 0; j5 = j5 - 1) { fVec5[j5] = fVec5[j5 - 1]; } for (int j6 = 4; j6 > 0; j6 = j6 - 1) { fVec6[j6] = fVec6[j6 - 1]; } for (int j7 = 3; j7 > 0; j7 = j7 - 1) { fVec7[j7] = fVec7[j7 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the very short delay lines of up to two samples by manually shifting the buffer method can be seen in those lines: ... // Delay line of 1 sample fVec8[1] = fVec8[0]; // Delay line of 2 samples fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; ... and the shift loop is generated for delay from 2 up to -mcd <n> samples method can be seen in those lines: ... output0[i0] = FAUSTFLOAT(fVec0[10] + fVec1[9] + fVec2[8] + fVec3[7] + fVec4[6] + fVec5[5] + fVec6[4] + fVec7[3] + fVec8[1] + fVec9[2]); // Shift delay line of 10 samples for (int j0 = 10; j0 > 0; j0 = j0 - 1) { fVec0[j0] = fVec0[j0 - 1]; } // Shift delay line of 9 samples for (int j1 = 9; j1 > 0; j1 = j1 - 1) { fVec1[j1] = fVec1[j1 - 1]; } ... When compiled with faust -mcd 0 , all delay lines use the wrapping index second strategy with power-of-two size (since -dlt <INT_MAX> is used by default): ... // The DSP memory layout int IOTA0; float fVec0[16]; float fVec1[16]; float fVec2[16]; float fVec3[8]; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[4]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fVec0[IOTA0 & 15] = float(input9[i0]); fVec1[IOTA0 & 15] = float(input8[i0]); fVec2[IOTA0 & 15] = float(input7[i0]); fVec3[IOTA0 & 7] = float(input6[i0]); fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[IOTA0 & 3] = float(input2[i0]); fVec8[IOTA0 & 1] = float(input0[i0]); fVec9[IOTA0 & 3] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[(IOTA0 - 10) & 15] + fVec1[(IOTA0 - 9) & 15] + fVec2[(IOTA0 - 8) & 15] + fVec3[(IOTA0 - 7) & 7] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[(IOTA0 - 3) & 3] + fVec8[(IOTA0 - 1) & 1] + fVec9[(IOTA0 - 2) & 3]); IOTA0 = IOTA0 + 1; } } ... In this code example, several delay lines of various power-of-two size (2, 4, 8, 16) are generated. A unique continuously incremented IOTA0 variable is shared between all delay lines. The wrapping index code is generated with this (IOTA0 - 5) & 7 kind of code, with a power-of-two - 1 mask (so 8 - 1 = 7 here). When compiled with faust -mcd 4 -dlt 7 , a mixture of the three generation strategies is used: // The DSP memory layout ... int fVec0_widx; float fVec0[11]; int fVec1_widx; float fVec1[10]; int fVec2_widx; float fVec2[9]; int fVec3_widx; float fVec3[8]; int IOTA0; float fVec4[8]; float fVec5[8]; float fVec6[8]; float fVec7[4]; float fVec8[2]; float fVec9[3]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { int fVec0_widx_tmp = fVec0_widx; fVec0[fVec0_widx_tmp] = float(input9[i0]); int fVec0_ridx_tmp0 = fVec0_widx - 10; int fVec1_widx_tmp = fVec1_widx; fVec1[fVec1_widx_tmp] = float(input8[i0]); int fVec1_ridx_tmp0 = fVec1_widx - 9; int fVec2_widx_tmp = fVec2_widx; fVec2[fVec2_widx_tmp] = float(input7[i0]); int fVec2_ridx_tmp0 = fVec2_widx - 8; int fVec3_widx_tmp = fVec3_widx; fVec3[fVec3_widx_tmp] = float(input6[i0]); int fVec3_ridx_tmp0 = fVec3_widx - 7; fVec4[IOTA0 & 7] = float(input5[i0]); fVec5[IOTA0 & 7] = float(input4[i0]); fVec6[IOTA0 & 7] = float(input3[i0]); fVec7[0] = float(input2[i0]); fVec8[0] = float(input0[i0]); fVec9[0] = float(input1[i0]); output0[i0] = FAUSTFLOAT(fVec0[((fVec0_ridx_tmp0 < 0) ? fVec0_ridx_tmp0 + 11 : fVec0_ridx_tmp0)] + fVec1[((fVec1_ridx_tmp0 < 0) ? fVec1_ridx_tmp0 + 10 : fVec1_ridx_tmp0)] + fVec2[((fVec2_ridx_tmp0 < 0) ? fVec2_ridx_tmp0 + 9 : fVec2_ridx_tmp0)] + fVec3[((fVec3_ridx_tmp0 < 0) ? fVec3_ridx_tmp0 + 8 : fVec3_ridx_tmp0)] + fVec4[(IOTA0 - 6) & 7] + fVec5[(IOTA0 - 5) & 7] + fVec6[(IOTA0 - 4) & 7] + fVec7[3] + fVec8[1] + fVec9[2]); fVec0_widx_tmp = fVec0_widx_tmp + 1; fVec0_widx_tmp = ((fVec0_widx_tmp == 11) ? 0 : fVec0_widx_tmp); fVec0_widx = fVec0_widx_tmp; fVec1_widx_tmp = fVec1_widx_tmp + 1; fVec1_widx_tmp = ((fVec1_widx_tmp == 10) ? 0 : fVec1_widx_tmp); fVec1_widx = fVec1_widx_tmp; fVec2_widx_tmp = fVec2_widx_tmp + 1; fVec2_widx_tmp = ((fVec2_widx_tmp == 9) ? 0 : fVec2_widx_tmp); fVec2_widx = fVec2_widx_tmp; fVec3_widx_tmp = fVec3_widx_tmp + 1; fVec3_widx_tmp = ((fVec3_widx_tmp == 8) ? 0 : fVec3_widx_tmp); fVec3_widx = fVec3_widx_tmp; IOTA0 = IOTA0 + 1; for (int j0 = 3; j0 > 0; j0 = j0 - 1) { fVec7[j0] = fVec7[j0 - 1]; } fVec8[1] = fVec8[0]; fVec9[2] = fVec9[1]; fVec9[1] = fVec9[0]; } } ... In this code example, the wrapping index moved by an if based method can be recognized with the use of those fVec0_ridx_tmp0 and fVec0_widx_tmp0 kind of variables. Choosing values that use less memory can be particularly important in the context of embedded devices. Testing different combinations of the -mcd and -dlt options can help optimize CPU utilisation, to summarize: chosing a big n value for -mcd n will consume less memory but the shift loop will start to be time consuming with big delay values. This model may sometimes be better suited if the C++ or LLVM compiler correctly auto-vectorizes the code and generates more efficient SIMD code. chosing -mcd 0 will activate the wrapping index second strategy for all delay lines in the DSP code, then playing with -dlt <n> allows to arbitrate between the faster but consuming more memory method and slower but consume less memory method. chosing a combinaison of -mcd n1 and -dlt <n2> can possibly be the model to chose when a lot of delay lines with different sizes are used in the DSP code. Using the benchmark tools faustbench and faustbench-llvm allow to refine the choice of compilation options.","title":"Delay lines implementation and DSP memory size"},{"location":"manual/optimizing/#recursive-signals","text":"In the C++ generated code, the delays lines appear as fVecXX arrays. When recursion is used in the DSP, a one sample delay is automatically added in the recursive path, and a very short delay line is allocated (appearing as fRecX arrays in the generated code). Here is the code of a recursively defined integrator: And the generated C++ code with the iRec0 buffer: ... // The DSP memory layout int iRec0[2]; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; output0[i0] = FAUSTFLOAT(iRec0[0]); iRec0[1] = iRec0[0]; } } ...","title":"Recursive signals"},{"location":"manual/optimizing/#delay-lines-in-recursive-signals","text":"Here is an example of a Faust program with 10 recursive blocks in parallel, each using a delay line of increasing value: Since a recursive signal uses a one sample delay in its loop, a buffer is allocated to handle the delay. When a delay is used in addition to the recursive signal, a single buffer is allocated to combine the two delay sources. The generated code using faust -mcd 0 for instance is now: ... // The DSP memory layout int IOTA0; float fRec0[4]; float fRec1[4]; float fRec2[8]; float fRec3[8]; float fRec4[8]; float fRec5[8]; float fRec6[16]; float fRec7[16]; float fRec8[16]; float fRec9[16]; int fSampleRate; ... virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* input3 = inputs[3]; FAUSTFLOAT* input4 = inputs[4]; FAUSTFLOAT* input5 = inputs[5]; FAUSTFLOAT* input6 = inputs[6]; FAUSTFLOAT* input7 = inputs[7]; FAUSTFLOAT* input8 = inputs[8]; FAUSTFLOAT* input9 = inputs[9]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[IOTA0 & 3] = float(input0[i0]) + fRec0[(IOTA0 - 2) & 3]; fRec1[IOTA0 & 3] = float(input1[i0]) + fRec1[(IOTA0 - 3) & 3]; fRec2[IOTA0 & 7] = float(input2[i0]) + fRec2[(IOTA0 - 4) & 7]; fRec3[IOTA0 & 7] = float(input3[i0]) + fRec3[(IOTA0 - 5) & 7]; fRec4[IOTA0 & 7] = float(input4[i0]) + fRec4[(IOTA0 - 6) & 7]; fRec5[IOTA0 & 7] = float(input5[i0]) + fRec5[(IOTA0 - 7) & 7]; fRec6[IOTA0 & 15] = float(input6[i0]) + fRec6[(IOTA0 - 8) & 15]; fRec7[IOTA0 & 15] = float(input7[i0]) + fRec7[(IOTA0 - 9) & 15]; fRec8[IOTA0 & 15] = float(input8[i0]) + fRec8[(IOTA0 - 10) & 15]; fRec9[IOTA0 & 15] = float(input9[i0]) + fRec9[(IOTA0 - 11) & 15]; output0[i0] = FAUSTFLOAT(fRec0[IOTA0 & 3] + fRec1[IOTA0 & 3] + fRec2[IOTA0 & 7] + fRec3[IOTA0 & 7] + fRec4[IOTA0 & 7] + fRec5[IOTA0 & 7] + fRec6[IOTA0 & 15] + fRec7[IOTA0 & 15] + fRec8[IOTA0 & 15] + fRec9[IOTA0 & 15]); IOTA0 = IOTA0 + 1; } } ... with buffers named fRecX instead of fVecX in the previous example. The -mcd <n> and -dlt <n> options can be used with the same purpose.","title":"Delay lines in recursive signals"},{"location":"manual/optimizing/#managing-dsp-memory-layout","text":"On audio boards where the memory is separated as several blocks (like SRAM, SDRAM\u2026) with different access time, it becomes important to refine the DSP memory model so that the DSP structure will not be allocated on a single block of memory, but possibly distributed on all available blocks. The idea is then to allocate parts of the DSP that are often accessed in fast memory and the other ones in slow memory. This can be controled using the -mem compilation option and an adapted architecture file .","title":"Managing DSP Memory Layout"},{"location":"manual/optimizing/#optimizing-the-c-or-llvm-code","text":"From a given DSP program, the Faust compiler tries to generate the most efficient implementation. Optimizations can be done at DSP writing time, or later on when the target langage is generated (like C++ or LLVM IR). The generated code can have different shapes depending of compilation options, and can run faster of slower. Several programs and tools are available to help Faust programmers to test (for possible numerical or precision issues), optimize their programs by discovering the best set of options for a given DSP code, and finally compile them into native code for the target CPUs. By default the Faust compiler produces a big scalar loop in the generated mydsp::compute method. Compiler options allow to generate other code shapes , like for instance separated simpler loops connected with buffers in the so-called vectorized mode (obtained using the -vec option). The assumption is that auto-vectorizer passes in modern compilers will be able to better generate efficient SIMD code for them. In this vec option, the size of the internal buffer can be changed using the -vs value option. Moreover the computation graph can be organized in deep-first order using -dfs . Delay lines implementation can be be controlled with the -mcd size and -dlt size options, to choose for example between power-of-two sizes and mask based wrapping (faster but consumming more memory) or if based wrapping , slower but consumming less memory. Many other compilation choices are fully controllable with options. Note that the C/C++ and LLVM backends offer the greatest number of compilation options. Here are just a few of them: -clang option: when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi option: when compiled with the C++ backend, does not add the 'virtual' keyword. This option can be especially useful in embedded devices context -mapp option: simpler/faster versions of 'floor/ceil/fmod/remainder' functions (experimental) Manually testing each of them and their combination is out of reach. So several tools have been developed to automatize that process and help search the configuration space to discover the best set of compilation options (be sure to run make benchmark && sudo make devinstall in Faust toplevel folder to install the benchmark tools):","title":"Optimizing the C++ or LLVM Code"},{"location":"manual/optimizing/#faustbench","text":"The faustbench tool uses the C++ backend to generate a set of C++ files produced with different Faust compiler options. All files are then compiled in a unique binary that will measure DSP CPU of all versions of the compiled DSP. The tool is supposed to be launched in a terminal, but it can be used to generate an iOS project, ready to be launched and tested in Xcode. A more complete documentation is available on the this page .","title":"faustbench"},{"location":"manual/optimizing/#faustbench-llvm","text":"The faustbench-llvm tool uses the libfaust library and its LLVM backend to dynamically compile DSP objects produced with different Faust compiler options, and then measure their DSP CPU usage. Additional Faust compiler options can be given beside the ones that will be automatically explored by the tool. A more complete documentation is available on the this page .","title":"faustbench-llvm"},{"location":"manual/optimizing/#faust2bench","text":"The faust2bench tool allows to benchmark a given DSP program: faust2bench -h Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable So something like faust2bench -vec -lv 0 -vs 4 foo.dsp is used to produce an executable, then launching ./foo gives : ./foo ./foo : 303.599 MBytes/sec (DSP CPU % : 0.224807 at 44100 Hz) The -inj option allows to possibly inject and benchmark an external C++ class to be adapted to behave as a dsp class, like in the following adapted.cpp example. The inherited compute method is rewritten to call the external C++ limiterStereo.SetPreGain etc... code to update the controllers, and the method limiterStereo.Process which computes the DSP: #include \"faust/dsp/dsp.h\" #include \"Limiter.hpp\" struct mydsp : public dsp { Limiter<float> limiterStereo; void init(int sample_rate) { limiterStereo.SetSR(sample_rate); } int getNumInputs() { return 2; } int getNumOutputs() { return 2; } int getSampleRate() { return 44100; } void instanceInit(int sample_rate) {} void instanceConstants(int sample_rate) {} void instanceResetUserInterface() {} void instanceClear() {} void buildUserInterface(UI* ui_interface) {} dsp* clone() { return new mydsp(); } void metadata(Meta* m) {} void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { limiterStereo.SetPreGain(0.5); limiterStereo.SetAttTime(0.5); limiterStereo.SetHoldTime(0.5); limiterStereo.SetRelTime(0.5); limiterStereo.SetThreshold(0.5); limiterStereo.Process(inputs, outputs, count); } }; Using faust2bench -inj adapted.cpp dummy.dsp creates the executable to be tested with ./dummy (remember that dummy.dsp is a program that is not actually used in -inj mode).","title":"faust2bench"},{"location":"manual/optimizing/#dynamic-faust","text":"The dynamic-faust tool uses the dynamic compilation chain (based on the LLVM backend), and compiles a Faust DSP source to a LLVM IR (.ll), bicode (.bc), machine code (.mc) or object code (.o) output file. This is an alternative to the C++ compilation chain, since DSP code can be compiled to object code (.o), then used and linked in a regular C++ project. A more complete documentation is available on the this page .","title":"dynamic-faust"},{"location":"manual/optimizing/#optimizing-with-any-faust2xx-tool","text":"All faust2xx tools compile in scalar mode by default, but can take any combination of optimal options (like -vec -fun -vs 32 -dfs -mcd 32 for instance) the previously described tools will automatically find. So by chaining the use of faustbench of faustbench-llvm to discover the best compilation options for a given DSP, then use them in the desired faust2xx tool, a CPU optimized standalone or plugin can be obtained. Note that some faust2xx tools like faust2max6 or faust2caqt can internally call the faustbench-llvm tool to discover and later on use the best possible compilation options.","title":"Optimizing with any faust2xx tool"},{"location":"manual/optimizing/#compiling-for-multiple-cpus","text":"On modern CPUs, compiling native code dedicated to the target processor is critical to obtain the best possible performances. When using the C++ backend, the same C++ file can be compiled with gcc of clang for each possible target CPU using the appropriate -march=cpu option. When using the LLVM backend, the same LLVM IR code can be compiled into CPU specific machine code using the dynamic-faust tool. This step will typically be done using the best compilation options automatically found with the faustbench tool or faustbench-llvm tools. A specialized tool has been developed to combine all the possible options.","title":"Compiling for Multiple CPUs"},{"location":"manual/optimizing/#faust2object","text":"The faust2object tool either uses the standard C++ compiler or the LLVM dynamic compilation chain (the dynamic-faust tool) to compile a Faust DSP to object code files (.o) and wrapper C++ header files for different CPUs. The DSP name is used in the generated C++ and object code files, thus allowing to generate distinct versions of the code that can finally be linked together in a single binary. A more complete documentation is available on the this page .","title":"faust2object"},{"location":"manual/options/","text":"Faust Compiler Options FAUST compiler version 2.74.6 usage : faust [options] file1 [file2 ...]. where options represent zero or more compiler options and fileN represents a Faust source file (.dsp extension). Input options: -a <file> wrapper architecture file. -i --inline-architecture-files inline architecture files. -A <dir> --architecture-dir <dir> add the directory <dir> to the architecture search path. -I <dir> --import-dir <dir> add the directory <dir> to the libraries search path. -L <file> --library <file> link with the LLVM module <file>. Output options: -o <file> the output file. -e --export-dsp export expanded DSP (with all included libraries). -uim --user-interface-macros add user interface macro definitions to the output code. -xml generate an XML description file. -json generate a JSON description file. -O <dir> --output-dir <dir> specify the relative directory of the generated output code and of additional generated files (SVG, XML...). Code generation options: -lang <lang> --language select output language, 'lang' should be c, cpp (default), cmajor, codebox, csharp, dlang, fir, interp, java, jax, jsfx, julia, llvm, ocpp, rust, vhdl or wast/wasm. -single --single-precision-floats use single precision floats for internal computations (default). -double --double-precision-floats use double precision floats for internal computations. -quad --quad-precision-floats use quad precision floats for internal computations. -fx --fixed-point use fixed-point for internal computations. -fx-size --fixed-point-size fixed-point number total size in bits (-1 is used to generate a unique fixpoint_t type). -es 1|0 --enable-semantics 1|0 use enable semantics when 1 (default), and simple multiplication otherwise. -lcc --local-causality-check check causality also at local level. -light --light-mode do not generate the entire DSP API. -clang --clang when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi --no-virtual when compiled with the C++ backend, does not add the 'virtual' keyword. -fp --full-parentheses always add parentheses around binops. -cir --check-integer-range check float to integer range conversion. -exp10 --generate-exp10 pow(10,x) replaced by possibly faster exp10(x). -os --one-sample generate one sample computation. -ec --external-control separated 'control' and 'compute' functions. -it --inline-table inline rdtable/rwtable code in the main class. -cm --compute-mix mix in outputs buffers. -ct --check-table check rtable/rwtable index range and generate safe access code [0/1: 1 by default]. -cn <name> --class-name <name> specify the name of the dsp class to be used instead of mydsp. -scn <name> --super-class-name <name> specify the name of the super class to be used instead of dsp. -pn <name> --process-name <name> specify the name of the dsp entry-point instead of process. -mcd <n> --max-copy-delay <n> use a copy delay up to max delay <n> and a dense delay above (ocpp only) or a ring buffer (defaut 16 samples). -mdd <n> --max-dense-delay <n> use a dense delay up to max delay <n> (if enough density) and a ring buffer delay above (ocpp only, default 1024). -mdy <n> --min-density <n> minimal density (100*number of delays/max delay) to use a dense delays (ocpp only, default 33). -dlt <n> --delay-line-threshold <n> use a mask-based ring buffer delays up to max delay <n> and a select based ring buffers above (default INT_MAX samples). -mem --memory-manager allocations done using a custom memory manager. -mem1 --memory-manager1 allocations done using a custom memory manager, using the iControl/fControl and iZone/fZone model. -mem2 --memory-manager2 use iControl/fControl, iZone/fZone model and no explicit memory manager. -mem3 --memory-manager3 use iControl/fControl, iZone/fZone model and no explicit memory manager with access as function parameters. -ftz <n> --flush-to-zero <n> code added to recursive signals [0:no (default), 1:fabs based, 2:mask based (fastest)]. -rui --range-ui whether to generate code to constraint vslider/hslider/nentry values in [min..max] range. -fui --freeze-ui whether to freeze vslider/hslider/nentry to a given value (init value by default). -inj <f> --inject <f> inject source file <f> into architecture file instead of compiling a dsp file. -scal --scalar generate non-vectorized code (default). -inpl --in-place generates code working when input and output buffers are the same (scalar mode only). -vec --vectorize generate easier to vectorize code. -vs <n> --vec-size <n> size of the vector (default 32 samples). -lv <n> --loop-variant <n> [0:fastest, fixed vector size and a remaining loop (default), 1:simple, variable vector size, 2:fixed, fixed vector size]. -omp --openmp generate OpenMP pragmas, activates --vectorize option. -pl --par-loop generate parallel loops in --openmp mode. -sch --scheduler generate tasks and use a Work Stealing scheduler, activates --vectorize option. -ocl --opencl generate tasks with OpenCL (experimental). -cuda --cuda generate tasks with CUDA (experimental). -dfs --deep-first-scheduling schedule vector loops in deep first order. -g --group-tasks group single-threaded sequential tasks together when -omp or -sch is used. -fun --fun-tasks separate tasks code as separated functions (in -vec, -sch, or -omp mode). -fm <file> --fast-math <file> use optimized versions of mathematical functions implemented in <file>, use 'faust/dsp/fastmath.cpp' when file is 'def', assume functions are defined in the architecture file when file is 'arch'. -mapp --math-approximation simpler/faster versions of 'floor/ceil/fmod/remainder' functions. -noreprc --no-reprc (Rust only) Don't force dsp struct layout to follow C ABI. -ns <name> --namespace <name> generate C++ or D code in a namespace <name>. -vhdl-trace --vhdl-trace activate trace. -vhdl-float --vhdl-float uses IEEE-754 format for samples instead of fixed point. -vhdl-components <file> --vhdl-components <file> path to a file describing custom components for the VHDL backend. -fpga-mem <n> --fpga-mem <n> FPGA block ram max size, used in -mem1/-mem2 mode. -wi <n> --widening-iterations <n> number of iterations before widening in signal bounding. -ni <n> --narrowing-iterations <n> number of iterations before stopping narrowing in signal bounding. Block diagram options: -ps --postscript print block-diagram to a postscript file. -svg --svg print block-diagram to a svg file. -sd --simplify-diagrams try to further simplify diagrams before drawing. -drf --draw-route-frame draw route frames instead of simple cables. -f <n> --fold <n> threshold to activate folding mode during block-diagram generation (default 25 elements). -fc <n> --fold-complexity <n> complexity threshold to fold an expression in folding mode (default 2). -mns <n> --max-name-size <n> threshold during block-diagram generation (default 40 char). -sn --simple-names use simple names (without arguments) during block-diagram generation. -blur --shadow-blur add a shadow blur to SVG boxes. -sc --scaled-svg automatic scalable SVG. Math doc options: -mdoc --mathdoc print math documentation of the Faust program in LaTeX format in a -mdoc folder. -mdlang <l> --mathdoc-lang <l> if translation file exists (<l> = en, fr, ...). -stripmdoc --strip-mdoc-tags strip mdoc tags when printing Faust -mdoc listings. Debug options: -d --details print compilation details. -time --compilation-time display compilation phases timing information. -flist --file-list print file list (including libraries) used to eval process. -tg --task-graph print the internal task graph in dot format. -sg --signal-graph print the internal signal graph in dot format. -norm --normalized-form print signals in normalized form and exit. -me --math-exceptions check / for 0 as denominator and remainder, fmod, sqrt, log10, log, acos, asin functions domain. -sts --strict-select generate strict code for 'selectX' even for stateless branches (both are computed). -wall --warning-all print all warnings. -t <sec> --timeout <sec> abort compilation after <sec> seconds (default 120). Information options: -h --help print this help message. -v --version print version information and embedded backends list. -libdir --libdir print directory containing the Faust libraries. -includedir --includedir print directory containing the Faust headers. -archdir --archdir print directory containing the Faust architectures. -dspdir --dspdir print directory containing the Faust dsp libraries. -pathslist --pathslist print the architectures and dsp library paths. Example: faust -a jack-gtk.cpp -o myfx.cpp myfx.dsp","title":"Compiler Options"},{"location":"manual/options/#faust-compiler-options","text":"","title":"Faust Compiler Options"},{"location":"manual/options/#faust-compiler-version-2746","text":"usage : faust [options] file1 [file2 ...]. where options represent zero or more compiler options and fileN represents a Faust source file (.dsp extension).","title":"FAUST compiler version 2.74.6"},{"location":"manual/options/#input-options","text":"-a <file> wrapper architecture file. -i --inline-architecture-files inline architecture files. -A <dir> --architecture-dir <dir> add the directory <dir> to the architecture search path. -I <dir> --import-dir <dir> add the directory <dir> to the libraries search path. -L <file> --library <file> link with the LLVM module <file>.","title":"Input options:"},{"location":"manual/options/#output-options","text":"-o <file> the output file. -e --export-dsp export expanded DSP (with all included libraries). -uim --user-interface-macros add user interface macro definitions to the output code. -xml generate an XML description file. -json generate a JSON description file. -O <dir> --output-dir <dir> specify the relative directory of the generated output code and of additional generated files (SVG, XML...).","title":"Output options:"},{"location":"manual/options/#code-generation-options","text":"-lang <lang> --language select output language, 'lang' should be c, cpp (default), cmajor, codebox, csharp, dlang, fir, interp, java, jax, jsfx, julia, llvm, ocpp, rust, vhdl or wast/wasm. -single --single-precision-floats use single precision floats for internal computations (default). -double --double-precision-floats use double precision floats for internal computations. -quad --quad-precision-floats use quad precision floats for internal computations. -fx --fixed-point use fixed-point for internal computations. -fx-size --fixed-point-size fixed-point number total size in bits (-1 is used to generate a unique fixpoint_t type). -es 1|0 --enable-semantics 1|0 use enable semantics when 1 (default), and simple multiplication otherwise. -lcc --local-causality-check check causality also at local level. -light --light-mode do not generate the entire DSP API. -clang --clang when compiled with clang/clang++, adds specific #pragma for auto-vectorization. -nvi --no-virtual when compiled with the C++ backend, does not add the 'virtual' keyword. -fp --full-parentheses always add parentheses around binops. -cir --check-integer-range check float to integer range conversion. -exp10 --generate-exp10 pow(10,x) replaced by possibly faster exp10(x). -os --one-sample generate one sample computation. -ec --external-control separated 'control' and 'compute' functions. -it --inline-table inline rdtable/rwtable code in the main class. -cm --compute-mix mix in outputs buffers. -ct --check-table check rtable/rwtable index range and generate safe access code [0/1: 1 by default]. -cn <name> --class-name <name> specify the name of the dsp class to be used instead of mydsp. -scn <name> --super-class-name <name> specify the name of the super class to be used instead of dsp. -pn <name> --process-name <name> specify the name of the dsp entry-point instead of process. -mcd <n> --max-copy-delay <n> use a copy delay up to max delay <n> and a dense delay above (ocpp only) or a ring buffer (defaut 16 samples). -mdd <n> --max-dense-delay <n> use a dense delay up to max delay <n> (if enough density) and a ring buffer delay above (ocpp only, default 1024). -mdy <n> --min-density <n> minimal density (100*number of delays/max delay) to use a dense delays (ocpp only, default 33). -dlt <n> --delay-line-threshold <n> use a mask-based ring buffer delays up to max delay <n> and a select based ring buffers above (default INT_MAX samples). -mem --memory-manager allocations done using a custom memory manager. -mem1 --memory-manager1 allocations done using a custom memory manager, using the iControl/fControl and iZone/fZone model. -mem2 --memory-manager2 use iControl/fControl, iZone/fZone model and no explicit memory manager. -mem3 --memory-manager3 use iControl/fControl, iZone/fZone model and no explicit memory manager with access as function parameters. -ftz <n> --flush-to-zero <n> code added to recursive signals [0:no (default), 1:fabs based, 2:mask based (fastest)]. -rui --range-ui whether to generate code to constraint vslider/hslider/nentry values in [min..max] range. -fui --freeze-ui whether to freeze vslider/hslider/nentry to a given value (init value by default). -inj <f> --inject <f> inject source file <f> into architecture file instead of compiling a dsp file. -scal --scalar generate non-vectorized code (default). -inpl --in-place generates code working when input and output buffers are the same (scalar mode only). -vec --vectorize generate easier to vectorize code. -vs <n> --vec-size <n> size of the vector (default 32 samples). -lv <n> --loop-variant <n> [0:fastest, fixed vector size and a remaining loop (default), 1:simple, variable vector size, 2:fixed, fixed vector size]. -omp --openmp generate OpenMP pragmas, activates --vectorize option. -pl --par-loop generate parallel loops in --openmp mode. -sch --scheduler generate tasks and use a Work Stealing scheduler, activates --vectorize option. -ocl --opencl generate tasks with OpenCL (experimental). -cuda --cuda generate tasks with CUDA (experimental). -dfs --deep-first-scheduling schedule vector loops in deep first order. -g --group-tasks group single-threaded sequential tasks together when -omp or -sch is used. -fun --fun-tasks separate tasks code as separated functions (in -vec, -sch, or -omp mode). -fm <file> --fast-math <file> use optimized versions of mathematical functions implemented in <file>, use 'faust/dsp/fastmath.cpp' when file is 'def', assume functions are defined in the architecture file when file is 'arch'. -mapp --math-approximation simpler/faster versions of 'floor/ceil/fmod/remainder' functions. -noreprc --no-reprc (Rust only) Don't force dsp struct layout to follow C ABI. -ns <name> --namespace <name> generate C++ or D code in a namespace <name>. -vhdl-trace --vhdl-trace activate trace. -vhdl-float --vhdl-float uses IEEE-754 format for samples instead of fixed point. -vhdl-components <file> --vhdl-components <file> path to a file describing custom components for the VHDL backend. -fpga-mem <n> --fpga-mem <n> FPGA block ram max size, used in -mem1/-mem2 mode. -wi <n> --widening-iterations <n> number of iterations before widening in signal bounding. -ni <n> --narrowing-iterations <n> number of iterations before stopping narrowing in signal bounding.","title":"Code generation options:"},{"location":"manual/options/#block-diagram-options","text":"-ps --postscript print block-diagram to a postscript file. -svg --svg print block-diagram to a svg file. -sd --simplify-diagrams try to further simplify diagrams before drawing. -drf --draw-route-frame draw route frames instead of simple cables. -f <n> --fold <n> threshold to activate folding mode during block-diagram generation (default 25 elements). -fc <n> --fold-complexity <n> complexity threshold to fold an expression in folding mode (default 2). -mns <n> --max-name-size <n> threshold during block-diagram generation (default 40 char). -sn --simple-names use simple names (without arguments) during block-diagram generation. -blur --shadow-blur add a shadow blur to SVG boxes. -sc --scaled-svg automatic scalable SVG.","title":"Block diagram options:"},{"location":"manual/options/#math-doc-options","text":"-mdoc --mathdoc print math documentation of the Faust program in LaTeX format in a -mdoc folder. -mdlang <l> --mathdoc-lang <l> if translation file exists (<l> = en, fr, ...). -stripmdoc --strip-mdoc-tags strip mdoc tags when printing Faust -mdoc listings.","title":"Math doc options:"},{"location":"manual/options/#debug-options","text":"-d --details print compilation details. -time --compilation-time display compilation phases timing information. -flist --file-list print file list (including libraries) used to eval process. -tg --task-graph print the internal task graph in dot format. -sg --signal-graph print the internal signal graph in dot format. -norm --normalized-form print signals in normalized form and exit. -me --math-exceptions check / for 0 as denominator and remainder, fmod, sqrt, log10, log, acos, asin functions domain. -sts --strict-select generate strict code for 'selectX' even for stateless branches (both are computed). -wall --warning-all print all warnings. -t <sec> --timeout <sec> abort compilation after <sec> seconds (default 120).","title":"Debug options:"},{"location":"manual/options/#information-options","text":"-h --help print this help message. -v --version print version information and embedded backends list. -libdir --libdir print directory containing the Faust libraries. -includedir --includedir print directory containing the Faust headers. -archdir --archdir print directory containing the Faust architectures. -dspdir --dspdir print directory containing the Faust dsp libraries. -pathslist --pathslist print the architectures and dsp library paths.","title":"Information options:"},{"location":"manual/options/#example","text":"faust -a jack-gtk.cpp -o myfx.cpp myfx.dsp","title":"Example:"},{"location":"manual/osc/","text":"OSC Support Overview Most Faust architectures provide Open Sound Control (OSC) support (the implementation is based internally on the oscpack library by Ross Bencina). This allows applications to be remotely controlled from any OSC-capable application, programming language, or hardware device. OSC support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [osc:on] metadata to the standard option metadata : declare options \"[osc:on]\"; The following tables provides a list of Faust architectures providing OSC support. Linux Faust Architectures with OSC Support Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt OSX Faust Architectures with OSC Support Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt Windows Faust Architectures with OSC Support Audio System Environment Jack Qt, Console PortAudio Qt Other Faust Architectures with OSC Support Environment Android iOS JUCE Bela Simple Example To illustrate how OSC support works let's define a very simple noise generator with a level control (we'll call it noise.dsp ): This example can be compiled as a standalone Jack Qt application with OSC support simply by running the following command: faust2jaqt -osc noise.dsp When the generated application is ran from the command line: ./noise various information is printed in the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 Hence, the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \"Foo\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host sets the destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (i.e., bargraph , etc.) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that path can be a regular expression (like /freeverb/Reverb1/* ). For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination. Automatic Port Allocation In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let say that we start noise and mixer (two Faust-generated applications with OSC support) on the same machine, we'll get the following: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and opens it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications. Discovering OSC Applications The commands oscsend and oscdump from the liblo package provide a convenient mean to experiment with OSC control and potentially debug applications with OSC support. `oscsend [hostname] [port] [address] [types] [values]`: sends OSC messages via UDP. `[types]` is a string, the letters indicates the type of the following values: `i=integer`, `f=float`, `s=string`, etc. `oscdump [port]`: receives OSC messages via UDP and dump to standard output Note that OSC messages can be sent from any OSC-compatible applications (e.g., PureData, Max/MSP, etc.). In the following examples, we'll use two separate terminal windows. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . Commands executed on terminal 1 will be preceded by T1$ . Messages received on terminal 2 will be preceded by T2: . To monitor on terminal T2 the OSC messages received on UDP port 5511, oscdump will be used: T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for Faust applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512 Discovering the OSC Interface of an Application The OSC interface of an application (the set of OSC messages we can use to control it) can be discovered by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer to this OSC message, a full description is printed in terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the OSC interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is 127.0.0.1 , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 . Widget's OSC Address Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a dmute button and a level slider: If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see, each widget has a unique OSC address obtained by concatenating the top level group label \"mixer,\" with the \"input\" group label and the widget label (see the Labels as Pathnames Section ). Please, note that blank spaces are replaced by underscores and metadata are removed during this operation. All addresses must have a common root. This is the case in our example because there is a unique horizontal group mixer containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000 Controlling the Application Via OSC Any user interface element of the application can be controlled by sending one of the previously discovered messages/addresses. For example, to set the noise level of the application to 0.2 the following message can be sent: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000 Turning Transmission ON The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For example: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS ( xmit = 2 ) mode if you need to restrict the access to your program: when the ALIAS mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements ( bargraph ) will only emit on their aliases. Filtering OSC Messages When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter Using OSC Aliases Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our previous noise example with TouchOSC on Android. The first step is to configure the TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510 . Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510 ) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of \"simple layout\". Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because the range of /1/fader1 is 0 to 1 (like the level slider), we can remove the range mapping information and write simply : import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1]\",0,0,1,0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer . Using again oscdump 5510 we can visualize the messages sent by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see, TouchOSC sends the x, y and z accelerometers in a single message, as a triplet of values ranging approximately from -9.81 to 9.81. In order to select the appropriate accelerometer, we need to concatenate to /accxyz a suffix /0 , /1 or /2 . For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: import(\"stdfaust.lib\"); process = no.noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer **_Examples of OSC Message Aliases for TouchOSC (Layout Mix2)._** OSC Cheat Sheet Default Ports Port Description 5510 default listening port 5511 default transmission port 5512 default error port 5513 alternative listening ports Command Line Options Option Description -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time Discovery Messages Message Description oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port Control Messages Message Description oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value Alias Alias Description \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc:' address]...\" alias with min , max clipping DSP with polyphonic support When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0","title":"OSC Support"},{"location":"manual/osc/#osc-support","text":"","title":"OSC Support"},{"location":"manual/osc/#overview","text":"Most Faust architectures provide Open Sound Control (OSC) support (the implementation is based internally on the oscpack library by Ross Bencina). This allows applications to be remotely controlled from any OSC-capable application, programming language, or hardware device. OSC support can be added to any Faust program (as long as the target architecture supports it: see tables below) simply by adding the [osc:on] metadata to the standard option metadata : declare options \"[osc:on]\"; The following tables provides a list of Faust architectures providing OSC support.","title":"Overview"},{"location":"manual/osc/#linux-faust-architectures-with-osc-support","text":"Audio System Environment Alsa GTK, Qt, Console Jack GTK, Qt, Console Netjack GTK, Qt, Console PortAudio GTK, Qt","title":"Linux Faust Architectures with OSC Support"},{"location":"manual/osc/#osx-faust-architectures-with-osc-support","text":"Audio System Environment CoreAudio Qt Jack Qt, Console Netjack Qt, Console PortAudio Qt","title":"OSX Faust Architectures with OSC Support"},{"location":"manual/osc/#windows-faust-architectures-with-osc-support","text":"Audio System Environment Jack Qt, Console PortAudio Qt","title":"Windows Faust Architectures with OSC Support"},{"location":"manual/osc/#other-faust-architectures-with-osc-support","text":"Environment Android iOS JUCE Bela","title":"Other Faust Architectures with OSC Support"},{"location":"manual/osc/#simple-example","text":"To illustrate how OSC support works let's define a very simple noise generator with a level control (we'll call it noise.dsp ): This example can be compiled as a standalone Jack Qt application with OSC support simply by running the following command: faust2jaqt -osc noise.dsp When the generated application is ran from the command line: ./noise various information is printed in the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 Hence, the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \"Foo\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host sets the destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (i.e., bargraph , etc.) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that path can be a regular expression (like /freeverb/Reverb1/* ). For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination.","title":"Simple Example"},{"location":"manual/osc/#automatic-port-allocation","text":"In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let say that we start noise and mixer (two Faust-generated applications with OSC support) on the same machine, we'll get the following: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and opens it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications.","title":"Automatic Port Allocation"},{"location":"manual/osc/#discovering-osc-applications","text":"The commands oscsend and oscdump from the liblo package provide a convenient mean to experiment with OSC control and potentially debug applications with OSC support. `oscsend [hostname] [port] [address] [types] [values]`: sends OSC messages via UDP. `[types]` is a string, the letters indicates the type of the following values: `i=integer`, `f=float`, `s=string`, etc. `oscdump [port]`: receives OSC messages via UDP and dump to standard output Note that OSC messages can be sent from any OSC-compatible applications (e.g., PureData, Max/MSP, etc.). In the following examples, we'll use two separate terminal windows. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . Commands executed on terminal 1 will be preceded by T1$ . Messages received on terminal 2 will be preceded by T2: . To monitor on terminal T2 the OSC messages received on UDP port 5511, oscdump will be used: T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for Faust applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512","title":"Discovering OSC Applications"},{"location":"manual/osc/#discovering-the-osc-interface-of-an-application","text":"The OSC interface of an application (the set of OSC messages we can use to control it) can be discovered by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer to this OSC message, a full description is printed in terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the OSC interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is 127.0.0.1 , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 .","title":"Discovering the OSC Interface of an Application"},{"location":"manual/osc/#widgets-osc-address","text":"Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a dmute button and a level slider: If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see, each widget has a unique OSC address obtained by concatenating the top level group label \"mixer,\" with the \"input\" group label and the widget label (see the Labels as Pathnames Section ). Please, note that blank spaces are replaced by underscores and metadata are removed during this operation. All addresses must have a common root. This is the case in our example because there is a unique horizontal group mixer containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000","title":"Widget's OSC Address"},{"location":"manual/osc/#controlling-the-application-via-osc","text":"Any user interface element of the application can be controlled by sending one of the previously discovered messages/addresses. For example, to set the noise level of the application to 0.2 the following message can be sent: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000","title":"Controlling the Application Via OSC"},{"location":"manual/osc/#turning-transmission-on","text":"The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For example: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS ( xmit = 2 ) mode if you need to restrict the access to your program: when the ALIAS mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements ( bargraph ) will only emit on their aliases.","title":"Turning Transmission ON"},{"location":"manual/osc/#filtering-osc-messages","text":"When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter","title":"Filtering OSC Messages"},{"location":"manual/osc/#using-osc-aliases","text":"Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our previous noise example with TouchOSC on Android. The first step is to configure the TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510 . Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510 ) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of \"simple layout\". Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because the range of /1/fader1 is 0 to 1 (like the level slider), we can remove the range mapping information and write simply : import(\"stdfaust.lib\"); process = no.noise*hslider(\"level[osc:/1/fader1]\",0,0,1,0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer . Using again oscdump 5510 we can visualize the messages sent by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see, TouchOSC sends the x, y and z accelerometers in a single message, as a triplet of values ranging approximately from -9.81 to 9.81. In order to select the appropriate accelerometer, we need to concatenate to /accxyz a suffix /0 , /1 or /2 . For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: import(\"stdfaust.lib\"); process = no.noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer **_Examples of OSC Message Aliases for TouchOSC (Layout Mix2)._**","title":"Using OSC Aliases"},{"location":"manual/osc/#osc-cheat-sheet","text":"","title":"OSC Cheat Sheet"},{"location":"manual/osc/#default-ports","text":"Port Description 5510 default listening port 5511 default transmission port 5512 default error port 5513 alternative listening ports","title":"Default Ports"},{"location":"manual/osc/#command-line-options","text":"Option Description -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time","title":"Command Line Options"},{"location":"manual/osc/#discovery-messages","text":"Message Description oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port","title":"Discovery Messages"},{"location":"manual/osc/#control-messages","text":"Message Description oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value","title":"Control Messages"},{"location":"manual/osc/#alias","text":"Alias Description \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc:' address]...\" alias with min , max clipping","title":"Alias"},{"location":"manual/osc/#dsp-with-polyphonic-support","text":"When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0","title":"DSP with polyphonic support"},{"location":"manual/overview/","text":"Overview of the Faust Universe While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This chapter provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust Distribution The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust architectures (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the Faust DSP Libraries (which in practice are hosted a separate Git submodule), etc. The latest stable release of the Faust distribution can be found here . It is recommended for most Faust users willing to compile the Faust compiler and libfaust from scratch. To have the latest stable development version, you can use the master branch of the Faust git repository which is hosted on GitHub. For something even more bleeding edge (to be used at your own risks), you might use the master-dev branch of the Faust git repository . master-dev is the development sub-branch of master . It is used by Faust developers to commit their changes and can be considered as \"the main development branch\". The goal is to make sure that master is always functional. Merges between master-dev and master are carried out at each stable release by the GRAME team. Also, note that pre-compiled packages of the Faust compiler and of libfaust for various platforms can be found on the of the Faust website . The Faust distribution is organized as follows: bin/ : contains the compiler and the [Faust tools](../tools) include/ : contains header files required by the Faust tools lib/ : contains the Faust libraries share/ : contains documentation, the Faust libraries and architecture files Note : you can install the Faust distribution anywhere you want, provided that the faust command is available from your PATH (requires to update your .profile if not in a standard location). The following subsections present the main tools build on top of the Faust compiler and intended to facilitate your life. Faust IDE Faust IDE is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures, but also various utilities for signal processing development. Faust Editor Faust Editor is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures. Faust Playground Faust Playground is a graphical environment to develop Faust programs with a higher level approach. It has been initially designed for kids and for pedagogical purpose. Faustgen Faustgen is a Max/MSP external that provides features similar to FaustLive. It's the ideal tool for fast prototyping in Max/MSP. Faustgen is part of the Faust project, and distributed in the Faust releases . FaustLive 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. It supports also native applications generation using the Faust online compiler. Note that FaustLive is regularly recompiled, but is no more developed, so Faust IDE is the recommended tool to use .","title":"Overview of the Faust Universe"},{"location":"manual/overview/#overview-of-the-faust-universe","text":"While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This chapter provides an overview of their role and will hopefully help you decide which one is better suited for your personal use.","title":"Overview of the Faust Universe"},{"location":"manual/overview/#the-faust-distribution","text":"The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust architectures (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the Faust DSP Libraries (which in practice are hosted a separate Git submodule), etc. The latest stable release of the Faust distribution can be found here . It is recommended for most Faust users willing to compile the Faust compiler and libfaust from scratch. To have the latest stable development version, you can use the master branch of the Faust git repository which is hosted on GitHub. For something even more bleeding edge (to be used at your own risks), you might use the master-dev branch of the Faust git repository . master-dev is the development sub-branch of master . It is used by Faust developers to commit their changes and can be considered as \"the main development branch\". The goal is to make sure that master is always functional. Merges between master-dev and master are carried out at each stable release by the GRAME team. Also, note that pre-compiled packages of the Faust compiler and of libfaust for various platforms can be found on the of the Faust website . The Faust distribution is organized as follows: bin/ : contains the compiler and the [Faust tools](../tools) include/ : contains header files required by the Faust tools lib/ : contains the Faust libraries share/ : contains documentation, the Faust libraries and architecture files Note : you can install the Faust distribution anywhere you want, provided that the faust command is available from your PATH (requires to update your .profile if not in a standard location). The following subsections present the main tools build on top of the Faust compiler and intended to facilitate your life.","title":"The Faust Distribution"},{"location":"manual/overview/#faust-ide","text":"Faust IDE is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures, but also various utilities for signal processing development.","title":"Faust IDE"},{"location":"manual/overview/#faust-editor","text":"Faust Editor is a zero-conf tool that provides all the compilation services, including binaries generation for all the supported platforms and architectures.","title":"Faust Editor"},{"location":"manual/overview/#faust-playground","text":"Faust Playground is a graphical environment to develop Faust programs with a higher level approach. It has been initially designed for kids and for pedagogical purpose.","title":"Faust Playground"},{"location":"manual/overview/#faustgen","text":"Faustgen is a Max/MSP external that provides features similar to FaustLive. It's the ideal tool for fast prototyping in Max/MSP. Faustgen is part of the Faust project, and distributed in the Faust releases .","title":"Faustgen"},{"location":"manual/overview/#faustlive","text":"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. It supports also native applications generation using the Faust online compiler. Note that FaustLive is regularly recompiled, but is no more developed, so Faust IDE is the recommended tool to use .","title":"FaustLive"},{"location":"manual/quick-start/","text":"Quick Start The goal of this section is to teach you how to use the basic elements of the Faust programming language in approximately two hours! While DSP algorithms can be easily written from scratch in Faust, we'll just show you here how to use existing elements implemented in the Faust libraries , connect them to each other, and implement basic user interfaces (UI) to control them. One of the strength of Faust lies in its libraries that implement hundreds of functions. So you should be able to go a long way after reading this section, simply by using what's already out here. This tutorial was written assuming that the reader is already familiar with basic concepts of computer music and programming. More generally, at the end of this section: your Faust development environment should be up and running, you should know enough to write basic Faust programs, you should be able to use them on different platforms. This tutorial was designed to be carried out in the Faust Online IDE (with its documentation ). If you wish to do it locally, you'll have to install Faust on your system but this step is absolutely not required, Making Sound Write the following code in the Faust Online IDE : and then click on the \"run\" button on the top left corner. Alternatively, you can also click on the \"Try it Yourself\" button of the window above if you're reading the online version of this documentation. You should now hear white noise, of course... ;) stdfaust.lib gives access to all the Faust libraries from a single point through a series of environments. For instance, we're using here the no environment which stands for noise.lib and the noise function (which is the standard white noise generator of Faust). The Faust Libraries Documentation provides more details about this system. The most fundamental element of any Faust code is the process line, which gives access to the audio inputs and outputs of the target. This system is completely dynamic and since no.noise has only one output and no input, the corresponding program will have a single output. Let's statically change the gain of the output of no.noise simply by multiplying it by a number between 0 and 1: process = no.noise*0.5; Thus, standard mathematical operations can be used in Faust just like in any other language. We'll now connect the noise generator to a resonant lowpass filter ( fi.resonlp ) by using the Faust sequential composition operator : : fi.resonlp has four arguments (in order): cut-off frequency , q , gain and its input . Note that you can have a quick look of what the arguments of a function are simply by hovering it in the online IDE. Here, we're setting the first three arguments with fixed variables. Variables don't have a type in Faust and everything is considered as a signal. The Faust compiler takes care of making the right optimizations by choosing which variable is ran at audio rate, what their types are, etc. Thus, ctFreq , q and gain could well be controlled by oscillators (i.e., signals running at audio rate) here. Since the input of the filter is not specified as an argument here (but it could, of course), it automatically becomes an \"implicit\" input/argument of fi.resonlp . The : sequential composition operator can be used to connect two elements that have the same number of outputs and inputs. Since no.noise has one output and fi.resonlp(ctFreq,q,gain) has one implicit input, we can connect them together. This is essentially the same as writing something like: While this would work, it's kind of ugly and not very \"Faustian\", so we don't do it... ;) At this point, you should be able to use and plug various elements of the Faust libraries together. The Faust libraries implement hundreds of functions and some of them have a very specialized use. Fortunately, the Faust libraries documentation contains a section on Standard Faust Libraries listing all the high level \"standard\" Faust functions organized by types. We recommend you to have a look at it now . As you do this, be aware that implicit signals in Faust can be explicitly represented with the _ character. Thus, when you see something like this in the libraries documentation: _ : aFunction(a,b) : _ it means that this function has one implicit input, one implicit output and two parameters ( a and b ). On the other hand: anotherFunction(a,b,c) : _,_ is a function that has three parameters, no implicit input and two outputs. Just for \"fun,\" try to rewrite the previous example running in the Faust online editor so that the process line looks like this: Of course, this should not affect the result. You probably noticed that we used the , Faust composition operator to express two signals in parallel . We can easily turn our filtered noise example into a stereo object using it: or we could even write this in a cleaner way: Note that this example allows us to have 2 separate filters for each channel. Since both filters currently have the same parameters, another way of writing this could be: process = no.noise : filter <: _,_; . You could think of the first form as a same noise signal splitted and then filtered on left and right channels, and the second form as the filtered noise then splitted on left and right channels. But the compiler understand that the same filtered noise will be produced on left and right channels in both cases. So the filtered noise signal can be computed only once and used on left and right channels. For the two progams, the compiler will actually generate the exact same optimized code ! This is a very powerful property of its semantically driven compilation model . Since filter,filter is considered here as a full expression, we cannot use the : operator to connect no.noise to the two filters in parallel because filter,filter has two inputs ( _,_ : filter,filter : _,_ ) and no.noise only has one output. The <: split composition operator used here takes n signals and splits them into m signals. The only rule is that m has to be a multiple of n . The merge :> composition operator can be used exactly the same way: import(\"stdfaust.lib\"); process = no.noise <: filter,filter :> _; Here we split the signal of no.noise into two signals that are connected to two filters in parallel. Finally, we merge the outputs of the filters into one signal. Note, that the previous expression could have been written as such too: import(\"stdfaust.lib\"); process = no.noise <: filter+filter; Keep in mind that splitting a signal doesn't mean that its energy get spread in each copy, for example, in the expression: the two _ both contain 1... All right, it's now time to add a basic user interface to our Faust program to make things a bit more interactive. Building a Simple User Interface In this section, we'll add a simple user interface to the code that we wrote in the previous section: Faust allows us to declare basic user interface (UI) elements to control the parameters of a Faust object. Since Faust can be used to make a wide range of elements ranging from standalone applications to audio plug-ins or API, the role of UI declarations differs a little in function of the target. For example, in the Faust Online Editor, a UI is a window with various kind of controllers (sliders, buttons, etc.). On the other hand, if you're using Faust to generate an audio engine using faust2api , then UI elements declared in your Faust code will be the parameters visible to \"the rest of the world\" and controllable through the API. An exhaustive list of the standard Faust UI elements is given in the corresponding section . Be aware that they not all supported by all the Faust targets. For example, you wont be able to declare vertical sliders if you're using the Faust Playground , etc. In the current case, we'd like to control the ctFreq , q and gain parameters of the previous program with horizontal sliders. To do this, we can write something like: The first argument of hslider is the name of the parameter as it will be displayed in the interface or used in the API (it can be different from the name of the variable associated with the UI element), the next one is the default value , then the min and max values and finally the step . To summarize: hslider(\"paramName\",default,min,max,step) . Let's now add a \"gate\" button to start and stop the sound (where gate is just the name of the button): Note that we were able to order parameters in the interface by numbering them in the parameter name field using squared brackets. Faust user interface elements run at control rate. Thus, you might have noticed that clicks are produced when moving sliders quickly. This problem can be easily solved by \"smoothing\" down the output of the sliders using the si.smoo function: Note that we're also using si.smoo on the output of the gate button to apply a exponential envelope on its signal. This is a very broad introduction to making user interface elements in Faust. You can do much more like creating groups, using knobs, different types of menus, etc. but at least you should be able to make Faust programs at this point that are controllable and sound good (or not ;) ). Final Polishing Some Faust functions already contain a built-in UI and are ready-to-be-used. These functions are all placed in demo.lib and are accessible through the dm. environment. As an example, let's add a reverb to our previous code by calling dm.zita_light (high quality feedback delay network based reverb). Since this function has two implicit inputs, we also need to split the output of the filter (otherwise you will get an error because Faust wont know how to connect things): Hopefully, you should see many more UI elements in your interface. That's it folks! At this point you should be able to use Faust standard functions , connect them together and build a simple UI at the top of them. Some Project Ideas In this section, we present a couple of project ideas that you could try to implement using Faust standard functions . Also, feel free to check the /examples folder of the Faust repository . Additive Synthesizer Make an additive synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // freqs and gains definitions go here process = os.osc(freq0)*gain0, os.osc(freq2)*gain2 :> _ // merging signals here <: dm.zita_light; // and then splitting them for stereo in FM Synthesizer Make a frequency modulation (FM) synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // carrierFreq, modulatorFreq and index definitions go here process = os.osc(carrierFreq+os.osc(modulatorFreq)*index) <: dm.zita_light; // splitting signals for stereo in Guitar Effect Chain Make a guitar effect chain: Since we're only using functions from demo.lib here, there's no need to define any UI since it is built-in in the functions that we're calling. Note that the mono output of dm.wah4_demo is split to fit the stereo input of dm.phaser2_demo . The last three effects have the same number of inputs and outputs (2x2) so no need to split or merge them. String Physical Model Based On a Comb Filter Make a string physical model based on a feedback comb filter: import(\"stdfaust.lib\"); // freq, res and gate definitions go here string(frequency,resonance,trigger) = trigger : ba.impulsify : fi.fb_fcomb(1024,del,1,resonance) with { del = ma.SR/frequency; }; process = string(freq,res,gate); Sampling rate is defined in maths.lib as SR . We're using it here to compute the length of the delay of the comb filter. with{} is a Faust primitive to attach local variables to a function. So in the current case, del is a local variable of string .","title":"Quick Start"},{"location":"manual/quick-start/#quick-start","text":"The goal of this section is to teach you how to use the basic elements of the Faust programming language in approximately two hours! While DSP algorithms can be easily written from scratch in Faust, we'll just show you here how to use existing elements implemented in the Faust libraries , connect them to each other, and implement basic user interfaces (UI) to control them. One of the strength of Faust lies in its libraries that implement hundreds of functions. So you should be able to go a long way after reading this section, simply by using what's already out here. This tutorial was written assuming that the reader is already familiar with basic concepts of computer music and programming. More generally, at the end of this section: your Faust development environment should be up and running, you should know enough to write basic Faust programs, you should be able to use them on different platforms. This tutorial was designed to be carried out in the Faust Online IDE (with its documentation ). If you wish to do it locally, you'll have to install Faust on your system but this step is absolutely not required,","title":"Quick Start"},{"location":"manual/quick-start/#making-sound","text":"Write the following code in the Faust Online IDE : and then click on the \"run\" button on the top left corner. Alternatively, you can also click on the \"Try it Yourself\" button of the window above if you're reading the online version of this documentation. You should now hear white noise, of course... ;) stdfaust.lib gives access to all the Faust libraries from a single point through a series of environments. For instance, we're using here the no environment which stands for noise.lib and the noise function (which is the standard white noise generator of Faust). The Faust Libraries Documentation provides more details about this system. The most fundamental element of any Faust code is the process line, which gives access to the audio inputs and outputs of the target. This system is completely dynamic and since no.noise has only one output and no input, the corresponding program will have a single output. Let's statically change the gain of the output of no.noise simply by multiplying it by a number between 0 and 1: process = no.noise*0.5; Thus, standard mathematical operations can be used in Faust just like in any other language. We'll now connect the noise generator to a resonant lowpass filter ( fi.resonlp ) by using the Faust sequential composition operator : : fi.resonlp has four arguments (in order): cut-off frequency , q , gain and its input . Note that you can have a quick look of what the arguments of a function are simply by hovering it in the online IDE. Here, we're setting the first three arguments with fixed variables. Variables don't have a type in Faust and everything is considered as a signal. The Faust compiler takes care of making the right optimizations by choosing which variable is ran at audio rate, what their types are, etc. Thus, ctFreq , q and gain could well be controlled by oscillators (i.e., signals running at audio rate) here. Since the input of the filter is not specified as an argument here (but it could, of course), it automatically becomes an \"implicit\" input/argument of fi.resonlp . The : sequential composition operator can be used to connect two elements that have the same number of outputs and inputs. Since no.noise has one output and fi.resonlp(ctFreq,q,gain) has one implicit input, we can connect them together. This is essentially the same as writing something like: While this would work, it's kind of ugly and not very \"Faustian\", so we don't do it... ;) At this point, you should be able to use and plug various elements of the Faust libraries together. The Faust libraries implement hundreds of functions and some of them have a very specialized use. Fortunately, the Faust libraries documentation contains a section on Standard Faust Libraries listing all the high level \"standard\" Faust functions organized by types. We recommend you to have a look at it now . As you do this, be aware that implicit signals in Faust can be explicitly represented with the _ character. Thus, when you see something like this in the libraries documentation: _ : aFunction(a,b) : _ it means that this function has one implicit input, one implicit output and two parameters ( a and b ). On the other hand: anotherFunction(a,b,c) : _,_ is a function that has three parameters, no implicit input and two outputs. Just for \"fun,\" try to rewrite the previous example running in the Faust online editor so that the process line looks like this: Of course, this should not affect the result. You probably noticed that we used the , Faust composition operator to express two signals in parallel . We can easily turn our filtered noise example into a stereo object using it: or we could even write this in a cleaner way: Note that this example allows us to have 2 separate filters for each channel. Since both filters currently have the same parameters, another way of writing this could be: process = no.noise : filter <: _,_; . You could think of the first form as a same noise signal splitted and then filtered on left and right channels, and the second form as the filtered noise then splitted on left and right channels. But the compiler understand that the same filtered noise will be produced on left and right channels in both cases. So the filtered noise signal can be computed only once and used on left and right channels. For the two progams, the compiler will actually generate the exact same optimized code ! This is a very powerful property of its semantically driven compilation model . Since filter,filter is considered here as a full expression, we cannot use the : operator to connect no.noise to the two filters in parallel because filter,filter has two inputs ( _,_ : filter,filter : _,_ ) and no.noise only has one output. The <: split composition operator used here takes n signals and splits them into m signals. The only rule is that m has to be a multiple of n . The merge :> composition operator can be used exactly the same way: import(\"stdfaust.lib\"); process = no.noise <: filter,filter :> _; Here we split the signal of no.noise into two signals that are connected to two filters in parallel. Finally, we merge the outputs of the filters into one signal. Note, that the previous expression could have been written as such too: import(\"stdfaust.lib\"); process = no.noise <: filter+filter; Keep in mind that splitting a signal doesn't mean that its energy get spread in each copy, for example, in the expression: the two _ both contain 1... All right, it's now time to add a basic user interface to our Faust program to make things a bit more interactive.","title":"Making Sound"},{"location":"manual/quick-start/#building-a-simple-user-interface","text":"In this section, we'll add a simple user interface to the code that we wrote in the previous section: Faust allows us to declare basic user interface (UI) elements to control the parameters of a Faust object. Since Faust can be used to make a wide range of elements ranging from standalone applications to audio plug-ins or API, the role of UI declarations differs a little in function of the target. For example, in the Faust Online Editor, a UI is a window with various kind of controllers (sliders, buttons, etc.). On the other hand, if you're using Faust to generate an audio engine using faust2api , then UI elements declared in your Faust code will be the parameters visible to \"the rest of the world\" and controllable through the API. An exhaustive list of the standard Faust UI elements is given in the corresponding section . Be aware that they not all supported by all the Faust targets. For example, you wont be able to declare vertical sliders if you're using the Faust Playground , etc. In the current case, we'd like to control the ctFreq , q and gain parameters of the previous program with horizontal sliders. To do this, we can write something like: The first argument of hslider is the name of the parameter as it will be displayed in the interface or used in the API (it can be different from the name of the variable associated with the UI element), the next one is the default value , then the min and max values and finally the step . To summarize: hslider(\"paramName\",default,min,max,step) . Let's now add a \"gate\" button to start and stop the sound (where gate is just the name of the button): Note that we were able to order parameters in the interface by numbering them in the parameter name field using squared brackets. Faust user interface elements run at control rate. Thus, you might have noticed that clicks are produced when moving sliders quickly. This problem can be easily solved by \"smoothing\" down the output of the sliders using the si.smoo function: Note that we're also using si.smoo on the output of the gate button to apply a exponential envelope on its signal. This is a very broad introduction to making user interface elements in Faust. You can do much more like creating groups, using knobs, different types of menus, etc. but at least you should be able to make Faust programs at this point that are controllable and sound good (or not ;) ).","title":"Building a Simple User Interface"},{"location":"manual/quick-start/#final-polishing","text":"Some Faust functions already contain a built-in UI and are ready-to-be-used. These functions are all placed in demo.lib and are accessible through the dm. environment. As an example, let's add a reverb to our previous code by calling dm.zita_light (high quality feedback delay network based reverb). Since this function has two implicit inputs, we also need to split the output of the filter (otherwise you will get an error because Faust wont know how to connect things): Hopefully, you should see many more UI elements in your interface. That's it folks! At this point you should be able to use Faust standard functions , connect them together and build a simple UI at the top of them.","title":"Final Polishing"},{"location":"manual/quick-start/#some-project-ideas","text":"In this section, we present a couple of project ideas that you could try to implement using Faust standard functions . Also, feel free to check the /examples folder of the Faust repository .","title":"Some Project Ideas"},{"location":"manual/quick-start/#additive-synthesizer","text":"Make an additive synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // freqs and gains definitions go here process = os.osc(freq0)*gain0, os.osc(freq2)*gain2 :> _ // merging signals here <: dm.zita_light; // and then splitting them for stereo in","title":"Additive Synthesizer"},{"location":"manual/quick-start/#fm-synthesizer","text":"Make a frequency modulation (FM) synthesizer using os.osc (sine wave oscillator): import(\"stdfaust.lib\"); // carrierFreq, modulatorFreq and index definitions go here process = os.osc(carrierFreq+os.osc(modulatorFreq)*index) <: dm.zita_light; // splitting signals for stereo in","title":"FM Synthesizer"},{"location":"manual/quick-start/#guitar-effect-chain","text":"Make a guitar effect chain: Since we're only using functions from demo.lib here, there's no need to define any UI since it is built-in in the functions that we're calling. Note that the mono output of dm.wah4_demo is split to fit the stereo input of dm.phaser2_demo . The last three effects have the same number of inputs and outputs (2x2) so no need to split or merge them.","title":"Guitar Effect Chain"},{"location":"manual/quick-start/#string-physical-model-based-on-a-comb-filter","text":"Make a string physical model based on a feedback comb filter: import(\"stdfaust.lib\"); // freq, res and gate definitions go here string(frequency,resonance,trigger) = trigger : ba.impulsify : fi.fb_fcomb(1024,del,1,resonance) with { del = ma.SR/frequency; }; process = string(freq,res,gate); Sampling rate is defined in maths.lib as SR . We're using it here to compute the length of the delay of the comb filter. with{} is a Faust primitive to attach local variables to a function. So in the current case, del is a local variable of string .","title":"String Physical Model Based On a Comb Filter"},{"location":"manual/remote/","text":"Remote compilation Compiling a same Faust DSP program on different platforms and targets (applications and plugins) can be a tedious task when SDKs have to be installed and configurated, or when the user want to do cross-compilation. A remote compilation service has been developed to simplify this process. It allows to send DSP source code on a cloud based infrastructure, which hosts a lot of targets and can do cross-compilation. This service is accessible: in several applications like FaustLive , Faust Editor or Faust IDE with a dedicated API explained in more details in the faustservice project and in the FaustWeb client tool with the faustremote script (part of the Faust distribution), which allows to access the remote compilation service and execute compilation requests.","title":"Remote Compilation"},{"location":"manual/remote/#remote-compilation","text":"Compiling a same Faust DSP program on different platforms and targets (applications and plugins) can be a tedious task when SDKs have to be installed and configurated, or when the user want to do cross-compilation. A remote compilation service has been developed to simplify this process. It allows to send DSP source code on a cloud based infrastructure, which hosts a lot of targets and can do cross-compilation. This service is accessible: in several applications like FaustLive , Faust Editor or Faust IDE with a dedicated API explained in more details in the faustservice project and in the FaustWeb client tool with the faustremote script (part of the Faust distribution), which allows to access the remote compilation service and execute compilation requests.","title":"Remote compilation"},{"location":"manual/soundfiles/","text":"Sound files Support Sound files can be used with the soundfile language primitive. Sound files will be fully loaded in memory at init time and will be accessed with an input read index. The length and sample rate of the sound files can be accessed to implement more sophisticated playing schemes. A more complete description of the soundfile primitive can be found here . Using sound files with the faust2xx scripts Since using sound files (actually all formats that can be read by the libsndfile library , or by JUCE if you use the faust2juce tool), have to be embedded with the generated binary (application or plugin), the -soundfile option has been added in some of the faust2xx scripts to do that. Assuming a DSP program using the soundfile primitive is written, the following commands can be used to generate binaries: faust2caqt -soundfile foo.dsp to embed the needed sound files in the application bundle on OSX faust2max6 -soundfile foo.dsp to embed the needed sound files in the Max/MSP external bundle on OSX Check the faust2xx script description page to know which one currently support the -soundfile option. The Soundfile Library They are some additional functions in the soundfiles.lib library. Three basic functions are fully documented for now. There is more code already written in the library source that allows to read sound files with different kind of interpolation. The soundfile primitive can be used in the Web platform. See the Faust Web IDE related documentation.","title":"Soundfiles Support"},{"location":"manual/soundfiles/#sound-files-support","text":"Sound files can be used with the soundfile language primitive. Sound files will be fully loaded in memory at init time and will be accessed with an input read index. The length and sample rate of the sound files can be accessed to implement more sophisticated playing schemes. A more complete description of the soundfile primitive can be found here .","title":"Sound files Support"},{"location":"manual/soundfiles/#using-sound-files-with-the-faust2xx-scripts","text":"Since using sound files (actually all formats that can be read by the libsndfile library , or by JUCE if you use the faust2juce tool), have to be embedded with the generated binary (application or plugin), the -soundfile option has been added in some of the faust2xx scripts to do that. Assuming a DSP program using the soundfile primitive is written, the following commands can be used to generate binaries: faust2caqt -soundfile foo.dsp to embed the needed sound files in the application bundle on OSX faust2max6 -soundfile foo.dsp to embed the needed sound files in the Max/MSP external bundle on OSX Check the faust2xx script description page to know which one currently support the -soundfile option.","title":"Using sound files with the faust2xx scripts"},{"location":"manual/soundfiles/#the-soundfile-library","text":"They are some additional functions in the soundfiles.lib library. Three basic functions are fully documented for now. There is more code already written in the library source that allows to read sound files with different kind of interpolation. The soundfile primitive can be used in the Web platform. See the Faust Web IDE related documentation.","title":"The Soundfile Library"},{"location":"manual/syntax/","text":"Faust Syntax Faust Program A Faust program is essentially a list of statements . These statements can be metadata declarations (either global metadata or function metadata ), imports , definitions , and documentation tags , with optional C++ style ( //... and /*...*/ ) comments. Variants Some statements ( imports , definitions ) can be preceded by a variantlist , composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision . This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308; A Simple Program Here is a short Faust program that implements of a simple noise generator (called from the noises.lib Faust library). It exhibits various kind of statements: two global metadata declarations, an imports , a comment , and a definition . We will study later how documentation statements work: The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process . Statements The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions , documentation . All statements but documentation end with a semicolon ; . Metadata Metadata allow us to add elements which are not part of the language to Faust code. These can range to the name of a Faust program, its author, to potential compilation options or user interface element customizations. There are three different types of metadata in Faust: Global Metadata : metadata global to a Faust code Function Metadata : metadata specific to a function UI Metadata : metadata specific to a UI element Note that some Global Metadata have standard names and can be used for specific tasks. Their role is described in the Standard Metadata section. Global Metadata All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; Function Metadata Metadata can be associated to a specific function. In that case, declare is followed by the name of the function, a key, and a string. For example: declare add author \"John Doe\" add = +; This is very useful when a library has several contributors and that functions potentially have different license terms, etc. Standard Metadata There exists a series of standard global metadata in Faust whose role role is described in the following table: Metadata Role declare options \"[key0:value][key1:value]\" This metadata can be used to specify various options associated to a Faust code such as the fact its polyphonic, if it should have OSC, MIDI support, etc. Specific keys usable with this metadata are described throughout this documentation. declare interface \"xxx\" Specifies an interface replacing the standard Faust UI. Imports File imports allow us to import definitions from other source files. For example import(\"maths.lib\"); imports the definitions of the maths.lib library. The most common file to be imported is the stdfaust.lib library which gives access to all the standard Faust libraries from a single point: Documentation Tags Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed in the Mathematical Documentation chapter. In this section we essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in Latex format, can be placed in between these two tags. Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. The <metadata> tags allow to reference Faust global metadatas , calling the corresponding keyword. The <notice/> empty-element tag is used to generate the conventions used in the mathematical equations. The <listing/> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies , and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved Faust code between <mdoc> sections. Definitions A definition associates an identifier with an expression. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition. Simple Definitions The syntax of a simple definition is: identifier = expression; For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245); Function Definitions Definitions with formal parameters correspond to functions definitions. For example the definition of linear2db , a function that converts linear values to decibels, is: linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x)); Definitions With Pattern Matching Moreover, formal parameters can also be full expressions representing patterns: This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Note that this last definition is a convenient alternative to the more verbose: duplicate = case { (1,x) => x; (n,x) => x, duplicate(n-1,x); }; A use case for duplicate could be to put 5 white noise generators in parallel: Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11) . The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element: count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) , the expression will be evaluated as 10 . Note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in: count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time. Expressions Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. Constant Numerical Expressions Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time . We will refer to them as constant numerical expressions in the documentation. Diagram Expressions Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. Diagram Composition Operations Five binary composition operations are available to combine block-diagrams: recursion ( ~ ), parallel ( , ), sequential ( : ), split ( <: ), merge ( :> ). One can think of each of these composition operations as a particular way to connect two block diagrams. To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a block-diagram A are expressed as \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively expressed as: [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are: Syntax Priority Association Description expression ~ expression 4 left Recursive Composition expression , expression 3 right Parallel Composition expression : expression 2 right Sequential Composition expression <: expression 1 right Split Composition expression :> expression 1 right Merge Composition Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table that gives the associativity of each numerical operator in infix expressions. Parallel Composition The parallel composition (e.g., (A,B) ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation: (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used (e.g., A,B,C,D ), Faust uses right associativity and therefore builds internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example: Oscillators in Parallel Parallel composition can be used to put 3 oscillators of different kinds and frequencies in parallel, which will result in a Faust program with 3 outputs: Example: Stereo Effect Parallel composition can be used to easily turn a mono effect into a stereo one which will result in a Faust program with 2 inputs and 2 outputs: Note that there's a better to write this last example using the par iteration : Sequential Composition The sequential composition (e.g., A:B ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Sequential composition is an associative operation: (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore builds internally the expression (A:(B:(C:D))) . Example: Sine Oscillator Since everything is considered as a signal generator in Faust, sequential composition can be simply used to pass an argument to a function: Example: Effect Chain Sequential composition can be used to create an audio effect chain. Here we're plugging a guitar distortion to an autowah: Split Composition The split composition (e.g., A<:B ) operator is used to distribute the outputs of A to the inputs of B . For the operation to be valid, the number of inputs of B must be a multiple of the number of outputs of A : \\mathrm{outputs}(A).k=\\mathrm{inputs}(B) Each input i of B is connected to the output i \\bmod k of A : A[i \\bmod k]\\rightarrow[i]B Example: Duplicating the Output of an Oscillator Split composition can be used to duplicate signals. For example, the output of the following sawtooth oscillator is duplicated 3 times in parallel. Note that this can be written in a more effective way by replacing _,_,_ with par(i,3,_) using the par iteration . Example: Connecting a Mono Effect to a Stereo One More generally, the split composition can be used to connect a block with a certain number of output to a block with a greater number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A<:B the number of inputs of B has to be a multiple of the number of outputs of A . Merge Composition The merge composition (e.g., A:>B ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : \\mathrm{outputs}(A)=k.\\mathrm{inputs}(B) Each output i of A is connected to the input i \\bmod k of B : A[i]\\rightarrow\\ [i \\bmod k]B The k incoming signals of an input of B are summed together. Example: Summing Signals Together - Additive Synthesis Merge composition can be used to sum an arbitrary number of signals together. Here's an example of a simple additive synthesizer (note that the result of the sum of the signals is divided by 3 to prevent clicking): While the resulting block diagram will look slightly different, this is mathematically equivalent to: Example: Connecting a Stereo Effect to a Mono One More generally, the merge composition can be used to connect a block with a certain number of output to a block with a smaller number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A:>B the number of outputs of A has to be a multiple of the number of inputs of B . Recursive Composition The recursive composition (e.g., A~B ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable, it requires that: \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) Each input of B is connected to the corresponding output of A via an implicit 1-sample delay: A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . Example: Timer Recursive composition can be used to implement a \"timer\" that will count each sample starting at time n=0 : The difference equation corresponding to this program is: y(n) = y(n-1) + 1 an its output signal will look like: (1,2,3,4,5,6,\\dots) . Example: One Pole Filter Recursive composition can be used to implement a one pole filter with one line of code and just a few characters: The difference equation corresponding to this program is: y(n) = x(n) + a_{1}y(n-1) Note that the one sample delay of the filter is implicit here so it doesn't have to be declared. Inputs and Outputs of an Expression The number of inputs and outputs of a Faust expression can be known at compile time simply by using inputs(expression) and outputs(expression) . For example, the number of outputs of a sine wave oscillator can be known simply by writing the following program: Note that Faust automatically simplified the expression by generating a program that just outputs 1 . This type of construction is useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,ba.selector(n-i-1,n)) with { n = outputs(expr); }; And the inputs of an expression: Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr with { n = inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction: Iterations Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. The use and role of par , seq , sum , and prod are detailed in the following sections. par Iteration The par iteration can be used to duplicate an expression in parallel. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer i is used here at each iteration to compute the value of the frequency of the current oscillator. Also, note that this example could be re-wrtitten using sum iteration (see example in the corresponding section). seq Iteration The seq iteration can be used to duplicate an expression in series. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Peak Equalizer The fi.peak_eq function of the Faust libraries implements a second order \"peak equalizer\" section (gain boost or cut near some frequency). When placed in series, it can be used to implement a full peak equalizer: Note that i is used here at each iteration to compute various elements and to format some labels. Having user interface elements with different names is a way to force their differentiation in the generated interface. sum Iteration The sum iteration can be used to duplicate an expression as a sum. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer The following example is just a slightly different version from the one presented in the par iteration section. While their block diagrams look slightly different, the generated code is exactly the same. i is used here at each iteration to compute the value of the frequency of the current oscillator. prod Iteration The prod iteration can be used to duplicate an expression as a product. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Amplitude Modulation Synthesizer The following example implements an amplitude modulation synthesizer using an arbitrary number of oscillators thanks to the prod iteration: i is used here at each iteration to compute the value of the frequency of the current oscillator. Note that the shift parameter can be used to tune the frequency drift between each oscillator. Infix Notation and Other Syntax Extensions Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in 2+3 Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar infix notation . For example if you want to multiply two numbers, say 2 and 3 , you can write directly 2*3 instead of the equivalent core-syntax expression 2,3 : * . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example _/2 is equivalent to _,2:/ which divides the incoming signal by 2 . Here are a few examples of equivalences: Infix Syntax Core Syntax 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < In case of doubts on the meaning of an infix expression, for example _*_ , it is useful to translate it to its core syntax equivalent, here _,_:* , which is equivalent to * . Infix Operators Built-in primitives that can be used in infix notation are called infix operators and are listed below. Please note that a more detailed description of these operators is available section on primitives . Comparison Operators Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression < expression 5 left less than expression <= expression 5 left less or equal expression == expression 5 left equal expression != expression 5 left different expression >= expression 5 left greater or equal expression > expression 5 left greater than Math Operators Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression + expression 6 left addition expression - expression 6 left subtraction expression * expression 7 left multiplication expression / expression 7 left division expression % expression 7 left modulo expression ^ expression 8 left power Bitwise Operators Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The priority and associativity of the bitwise operators is given here: Syntax Pri. Assoc. Description expression | expression 6 left bitwise or expression & expression 7 left bitwise and expression xor expression 7 left bitwise xor expression << expression 7 left bitwise left shift expression >> expression 7 left bitwise right shift Delay operators Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \u2019 delays the left handside expression by one sample. Syntax Pri. Assoc. Description expression @ expression 9 left variable delay expression' 10 left one-sample delay Prefix Notation Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) : Prefix Syntax Core Syntax *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Partial Application The partial application notation is a variant of the prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube), and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one: Prefix Partial Application Syntax Core Syntax +(C) \\equiv _,C : + -(C) \\equiv _,C : - <(C) \\equiv _,C : < /(C) \\equiv _,C : / For commutative operations that doesn't matter. But for non-commutative ones, it is more \"natural\" to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not to other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Example: Gain Controller The following example demonstrates the use of partial application in the context of a gain controller: ' Time Expression ' is used to express a one sample delay. For example: will delay the incoming signal by one sample. ' time expressions can be chained, so the output signal of this program: will look like: (0,0,1,1,1,1,\\dots) . The ' time expression is useful when designing filters, etc. and is equivalent to @(1) (see the @ Time Expression ). @ Time Expression @ is used to express a delay with an arbitrary number of samples. For example: will delay the incoming signal by 10 samples. A delay expressed with @ doesn't have to be fixed but it must be bounded and cannot be negative. Therefore, the values of a slider are perfectly acceptable: @ only allows for the implementation of integer delay. Thus, various fractional delay algorithms are implemented in the Faust delays.lib library. Environment Expressions Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. with Expression The with construction allows to specify a local environment : a private list of definition that will be used to evaluate the left hand expression. In the following example: the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} . letrec Expression The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows us to easily express groups of mutually recursive signals, for example: x(t) = y(t-1) + 10\\\\ y(t) = x(t-1) - 1 as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: Note the special notation 'x = y + 10 instead of x = y' + 10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelope generator with an attack and a release time (as a number of samples), and a gate signal. A possible definition could be: With the following semantics for n(t) and v(t) : n(t) = (n(t-1)+1) * (g(t) <= g(t-1))\\\\ v(t) = max(0, v(t-1) + (n(t-1)<a(t))/a(t) - (n(t-1)>=a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of \u2019letrec\u2019: x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); }; environment Expression The environment construction allows to create an explicit environment. It is like a `with' , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. In the following example an environment construction is used to group together some constant definitions: constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next section). Access Expression Definitions inside an environment can be accessed using the . construction. For example constant.pi refers to the definition of pi in the constant environment defined above . Note that environments don't have to be named. We could have written directly: environment{pi = 3.14159; e = 2.718; ... }.pi library Expression The library construct allows to create an environment by reading the definitions from a file. For example library(\"filters.lib\") represents the environment obtained by reading the file filters.lib . It works like import(\"filters.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"filters.lib\").lowpass denotes the function lowpass as defined in the file filters.lib . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of: import(\"filters.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts: fl = library(\"filters.lib\"); ... ...fl.lowpass.... ... }; In practice, that's how the stdfaust.lib library works. component Expression The component construction allows us to reuse a full Faust program (e.g., a .dsp file) as a simple expression. For example component(\"freeverb.dsp\") denotes the signal processor defined in file freeverb.dsp . Components can be used within expressions like in: ...component(\"karplus32.dsp\") : component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . component works well in tandem with explicit substitution (see next section). Explicit Substitution Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing: ...component(\"freeverb.dsp\")[foo(x) = ...;]... }; Foreign Expressions Reference to external C functions , variables and constants can be introduced using the foreign expressions mechanism. Foreign function declaration An external C function is declared by indicating its name and signature as well as the required include file. The file maths.lib of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows: asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad or fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision and asinfx in fixed-point precision. This is why the four names are provided in the signature. Signature Types Foreign functions generally expect a precise type: int or float for their parameters. Note that currently only numerical functions involving simple int and float parameters are allowed currently in Faust. No vectors, tables or data structures can be passed as parameters or returned. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float . Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate. Foreign Variables and Constants External variables and constants can also be declared with a similar syntax. In the same maths.lib file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found: SR = min(192000.0,max(1.0,fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block. Include File In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include in the generated code. Library File In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model . Applications and Abstractions Abstractions and applications are fundamental programming constructions directly inspired by Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. Abstractions Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. Let's say we want to transform a stereo reverb, dm.zita_light for instance, into a mono effect. The following expression can be written (see the sections on Split Composition and Merge Composition ): _ <: dm.zita_light :> _ The incoming mono signal is split to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that we are interested in transforming other stereo effects. We could generalize this principle by making zita_light a variable: \\(zita_light).(_ <: zita_light :> _) The resulting abstraction can then be applied to transform other effects. Note that if zita_light is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) A name can be given to the abstraction and in turn use it on dm.zita_light : Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _; Applications Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. For example, the abstraction described in the previous section can be used to transform a stereo reverb: mono(dm.zita_light) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(dm.zita_light) Replacing the variable part with the argument is called beta-reduction in Lambda-Calculus Whenever the Faust compiler find an application of an abstraction it replaces the variable part with the argument. The resulting expression is as expected: (_ <: dm.zita_light :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments). Unapplied abstractions Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: In Faust, a proper semantic has also been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: can be simply defined as: which is actually equivalent to: process(x,y) = y,x; Pattern Matching Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(reverb : harmonizer) will produce: harmonizer : freeverb Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching. Primitives The primitive signal processing operations represent the built-in functionalities of Faust, that is the atomic operations on signals provided by the language. All these primitives denote signal processors , in other words, functions transforming input signals into output signals . Numbers Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double, or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type. route Primitive The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: A is the number of input signals, as an integer constant numerical expression , automatically promoted to int B is the number of output signals, as an integer constant numerical expression , automatically promoted to int a,b / (a,b) is an input/output pair, as integers constant numerical expressions , automatically promoted to int Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: waveform Primitive The waveform primitive was designed to facilitate the use of rdtable (read table). It allows us to specify a fixed periodic signal as a list of samples as literal numbers. waveform has two outputs: a constant indicating the size (as a number of samples) of the period the periodic signal itself For example waveform{0,1,2,3} produces two outputs: the constant signal 4 and the periodic signal (0,1,2,3,0,1,2,3,0,1,\\dots) . In the following example: waveform is used to define a triangle waveform (in its most primitive form), which is then used with a rdtable controlled by a phaser to implement a triangle wave oscillator. Note that the quality of this oscillator is very low because of the low resolution of the triangle waveform. soundfile Primitive The soundfile(\"label[url:{'path1';'path2';'path3'}]\", n) primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the %i syntax, as in the label part). The soundfile(\"label[url:path]\", n) simplified syntax, or soundfile(\"label\", n) (where label is used as the soundfile path) allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: two inputs: the sound number (as a integer between 0 and 255, automatically promoted to int ), and the read index in the sound (automatically promoted to int , which will access the last sample of the sound if the read index is greater than the sound length) two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound n several more outputs for the sound channels themselves, as a integer constant numerical expression If more outputs than the actual number of channels in the sound file are used, the audio channels will be automatically duplicated up to the wanted number of outputs (so for instance, if a stereo file is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. A minimal example to play a stereo soundfile until it's end can be written with: The 0 first parameter selects the first sound in the soundfile list (which only contains one file in this example), then uses an incrementing read index signal to play the soundfile, cuts the unneeded sound length in frames and sample rate ouputs, and keeps the two actual sound outputs. Having the sound length in frames first output allows to implement sound looping, or any kind of more sophisticated read index signal. Having the sound sample rate second output allows to possibly adapt or change the reading speed. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file in the Faust repository implements the void addSoundfile(label, path, sf_zone) method, which loads the actual soundfiles using the libsndfile library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that the complete soundfile content is preloaded in memory at initialisation time when the compiled program starts. Note that a special architecture file can well decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge of actually setting up all sound memory pointers when void addSoundfile(label, path, sf_zone) is called by the buidUserInterface mechanism. C-Equivalent Primitives Most Faust primitives are analogous to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . + can be used to very simply implement a mixer: Note that this is equivalent to (see Identity Function ): The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form. It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance, -(a*b) is a partial application. It is syntactic sugar for _,(a*b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a*b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Integer Number Integer numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described mathematically as y(t)=n . Example: DC Offset of 1 Floating Point Number Floating point numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described as y(t)=n.m . Example: DC Offset of 0.5 Identity Function The identity function is expressed in Faust with the _ primitive. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x(t) Example: a Signal Passing Through In the following example, the _ primitive is used to connect the single audio input of a Faust program to its output: Cut Primitive The cut primitive is expressed in Faust with ! . It can be used to \"stop\"/terminate a signal. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} Mathematical Description: \\forall x\\in\\mathbb{S},(x)\\rightarrow () Example: Stopping a Signal In the following example, the ! primitive is used to stop one of two parallel signals: int Primitive The int primitive can be used to force the cast of a signal to int. It is of type \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} and can be described mathematically as y(t)=(int)x(t) . This primitive is useful when declaringindices to read in a table, etc. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(int)x(t) Example: Simple Cast float Primitive The float primitive can be used to force the cast of a signal to float. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(float)x(t) Example: Simple Cast Add Primitive The + primitive can be used to add two signals together. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)+x_{2}(t) Example: Simple Mixer Subtract Primitive The - primitive can be used to subtract two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)-x_{2}(t) Example: Subtracting Two Input Signals Multiply Primitive The * primitive can be used to multiply two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)*x_{2}(t) Example: Multiplying a Signal by 0.5 Divide Primitive The / primitive can be used to divide two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)/{x_{2}(t)} Example: Dividing a Signal by 2 Power Primitive The ^ primitive can be used to raise to the power of N a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)^{x_{2}(t)} Example: Power of Two of a Signal Modulo Primitive The % primitive can be used to take the modulo of a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\%{x_{2}(t)} Example: Phaser The following example uses a counter and the % primitive to implement a basic phaser: will output a signal: (0,1,2,3,4,5,6,7,8,9,0,1,2,3,4) . AND Primitive Bitwise AND can be expressed in Faust with the & primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\&{x_{2}(t)} OR Primitive Bitwise OR can be expressed in Faust with the | primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)|{x_{2}(t)} Example The following example will output 1 if the incoming signal is smaller than 0.5 or greater than 0.7 and 0 otherwise. Note that the result of this operation could be multiplied to another signal to create a condition. XOR Primitive Bitwise XOR can be expressed in Faust with the xor primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\land {x_{2}(t)} Example Left Shift Primitive Left shift can be expressed in Faust with the << primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) << {x_{2}(t)} Example Right Shift Primitive Right shift can be expressed in Faust with the >> primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >> {x_{2}(t)} Example Smaller Than Primitive The smaller than comparison can be expressed in Faust with the < primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) < {x_{2}(t)} Example The following code will output 1 if the input signal is smaller than 0.5 and 0 otherwise. Smaller or Equal Than Primitive The smaller or equal than comparison can be expressed in Faust with the <= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) <= {x_{2}(t)} Example The following code will output 1 if the input signal is smaller or equal than 0.5 and 0 otherwise. Greater Than Primitive The greater than comparison can be expressed in Faust with the > primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) > {x_{2}(t)} Example The following code will output 1 if the input signal is greater than 0.5 and 0 otherwise. Greater or Equal Than Primitive The greater or equal than comparison can be expressed in Faust with the >= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >= {x_{2}(t)} Example The following code will output 1 if the input signal is greater or equal than 0.5 and 0 otherwise. Equal to Primitive The equal to comparison can be expressed in Faust with the == primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) == {x_{2}(t)} Example Different Than Primitive The different than comparison can be expressed in Faust with the != primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) != {x_{2}(t)} Example math.h -Equivalent Primitives Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib ). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. acos Primitive Arc cosine can be expressed as acos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{acosf}(x(t)) Example asin Primitive Arc sine can be expressed as asin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{asinf}(x(t)) Example atan Primitive Arc tangent can be expressed as atan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atanf}(x(t)) Example atan2 Primitive The arc tangent of 2 signals can be expressed as atan2 in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) Example cos Primitive Cosine can be expressed as cos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{cosf}(x(t)) Example sin Primitive Sine can be expressed as sin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sinf}(x(t)) Example tan Primitive Tangent can be expressed as tan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{tanf}(x(t)) Example exp Primitive Base-e exponential can be expressed as exp in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{expf}(x(t)) Example log Primitive Base-e logarithm can be expressed as log in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{logf}(x(t)) Example log10 Primitive Base-10 logarithm can be expressed as log10 in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{log10}(x(t)) Example pow Primitive Power can be expressed as pow in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) Example sqrt Primitive Square root can be expressed as sqrt in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sqrtf}(x(t)) Example abs Primitive Absolute value can be expressed as abs in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{abs}(x(t)) (int) or y(t)=\\mathrm{fabsf}(x(t)) (float) Example min Primitive Minimum can be expressed as min in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) Example max Primitive Maximum can be expressed as max in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) Example fmod Primitive Float modulo can be expressed as fmod in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) Example remainder Primitive Float remainder can be expressed as remainder in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) Example floor Primitive Largest int can be expressed as floor in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\leq : y(t)=\\mathrm{floorf}(x(t)) Example ceil Primitive Smallest int can be expressed as ceil in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\geq : y(t)=\\mathrm{ceilf}(x(t)) Example rint Primitive Closest int (using the current rounding mode) can be expressed as rint in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{rintf}(x(t)) Example round Primitive Nearest int value (regardless of the current rounding mode) can be expressed as round in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{roundf}(x(t)) Example Delay Primitives and Modifiers Faust hosts various modifiers and primitives to define one sample or integer delay of arbitrary length. They are presented in this section. mem Primitive A 1 sample delay can be expressed as mem in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+1)=x(t),y(0)=0 Example Note that this is equivalent to process = _' (see ' Modifier ) and process = @(1) (see @ Primitive ) ' Modifier ' can be used to apply a 1 sample delay to a signal in Faust. It can be seen as syntactic sugar to the mem primitive . ' is very convenient when implementing filters and can help significantly decrease the size of the Faust code. Example @ Primitive An integer delay of N samples can be expressed as @(N) in Faust. Note that N (automatically promoted to int ) can be dynamic but that its range must be bounded. This can be done by using a UI primitive (see example below) allowing for the definition of a range such as hslider , vslider , or nentry . Note that floating point delay is also available in Faust by the mean of various fractional delay implementations available in the Faust standard libraries. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+x_{2}(t))=x_{1}(t), y(t<x_{2}(t))=0 Usage _ : @(N) : _ Where: N : the length of the delay as a number of samples Example: Static N Samples Delay Example: Dynamic N Samples Delay Table Primitives rdtable Primitive The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The table can either be implemented by using the waveform primitive (as shown in the first example) or using a function controlled by a timer (such as ba.time ) as demonstrated in the second example. The idea is that the table is created during the initialization step and before audio computation begins. Type: \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=T[r(t)] Usage rdtable(n,s,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the table content r : the read index (an int between 0 and n-1 ), automatically promoted to int Example: Basic Triangle Wave Oscillator Using the waveform Primitive In this example, a basic (and dirty) triangle wave-table is defined using the waveform . It is then used with the rdtable primitive and a phasor to implement a triangle wave oscillator: Example: Basic Triangle Wave Oscillator Using the sin Primitive and a Timer In this example, a sine table is implemented using the sin primitive and a timer ( ba.time ). The timer calls the sin function during the initialization step of the Faust program. It is then used with rdtable to implement a sine wave oscillator. rwtable Primitive The rwtable primitive can be used to implement a read/write table. It takes an audio input that can be written in the table using a write index (i.e., w below) and read using a read index (i.e., r below). Type: \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} Mathematical Description: T[w(t)]=c(t); y(t)=T[r(t)] Usage _ : rwtable(n,s,w,_,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the initial table content w : the write index (an int between 0 and n-1 ), automatically promoted to int r : the read index (an int between 0 and n-1 ), automatically promoted to int Note that the fourth argument of rwtable corresponds to the input of the table. Example: Simple Looper In this example, an input signal is written in the table when record is true (equal to 1). The read index is constantly updated to loop through the table. The table size is set to 48000, which corresponds to one second if the sampling rate is 48000 KHz. Selector Primitives Selector primitives can be used to create conditions in Faust and to implement switches to choose between several signals. select2 Primitive The select2 primitive is a \"two-way selector\". It has three input signals: s , x_0 , x_1 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other two inputs x_0(t) and x_1(t) to the output y(t) . Note Please note that select2 is not the equivalent of a traditional if-then-else construction. Like every Faust primitive, it has a strict semantics. All input signals are always computed, even when they are not selected. Therefore you can't use select2 to avoid computing something. The semantics of select2 is as follows: Type: (s,x_0,x_1)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\end{array} \\right. Usage _,_ : select2(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine and a sawtooth wave oscillator. Note that select2 could be easily implemented from scratch in Faust: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient. select3 Primitive The select3 primitive is a \"three-ways selector\". It has four input signals: s , x_0 , x_1 , x_2 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other three inputs x_0(t) , x_1(t) and x_2(t) to the output y(t) . Type: (s,x_0,x_1,x_2)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\\\ x_2(t) & \\mathrm{if\\ } s(t) = 2.\\end{array} \\right. Usage _,_,_ : select3(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one, 2 for the third one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine, a sawtooth and a triangle wave oscillator. Note that select3 could be easily implemented from scratch in Faust using Boolean primitives: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient. Specific Primitives In Faust, signals operate within a [min, max] range. The lowest(sig) primitive determines the minimum value a given sig signal can attain, while the highest(sig) primitive identifies its maximum value. However, be aware that the compiler's interval computation might not accurately estimate the true [min, max] range, often resulting in -INFINITY for the minimum value and/or INFINITY for the maximum value. User Interface Primitives and Configuration Faust user interface widgets/primitives allow for an abstract description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be discrete (e.g., button , checkbox , etc.), continuous (e.g., hslider , vslider , nentry ), and organizational (e.g., vgroup , hgroup ). Discrete and continuous elements are signal generators. For example, a button produces a signal which is 1 when the button is pressed and 0 otherwise: These signals can be freely combined with other audio signals. In fact, the following code is perfectly valid and will generate sound: Each primitive implements a specific UI element, but their appearance can also be completely modified using metadata (a little bit like HTML and CSS in the web). Therefore, hslider , vslider , and nentry ) can for example be turned into a knob, a dropdown menu, etc. This concept is further developed in the section on UI metadata . Continuous UI elements (i.e., hslider , vslider , and nentry ) must all declare a range for the parameter they're controlling. In some cases, this range is used during compilation to allocate memory and will impact the generated code. For example, in the case of: a buffer of 10 samples will be allocated for the delay implemented with the @ primitive while 20 samples will be allocated in the following example: button Primitive The button primitive implements a button. Usage button(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger checkbox Primitive The checkbox primitive implements a checkbox/toggle. Usage checkbox(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger hslider Primitive The hslider primitive implements a horizontal slider. Usage hslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example: Gain Control Example: Additive Oscillator Here is an example of a 3 oscillators instrument where the default frequency of each partial is computed using a more complex constant numerical expression . vslider Primitive The vslider primitive implements a vertical slider. Usage vslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example nentry Primitive The nentry primitive implements a \"numerical entry\". Usage nentry(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the numerical entry, a constant numerical expression min : the minimum value of the numerical entry, a constant numerical expression max : the maximum value of the numerical entry, a constant numerical expression step : the precision (step) of the numerical entry (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example hgroup Primitive The hgroup primitive implements a horizontal group. A group contains other UI elements that can also be groups. hgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage hgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. vgroup Primitive The vgroup primitive implements a vertical group. A group contains other UI elements that can also be groups. vgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage vgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. tgroup Primitive The tgroup primitive implements a \"tab group.\" Tab groups can be used to group UI elements in tabs in the interface. A group contains other UI elements that can also be groups. tgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage tgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times. vbargraph Primitive The vbargraph primitive implements a vertical bar-graph (typically a meter displaying the level of a signal). Usage vbargraph takes an input signal and outputs it while making it available to the UI. _ : vbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the vbargraph primitive: Note the use of the attach primitive here that forces the compilation of the vbargraph without using its output signal (see section on the attach primitive ). hbargraph Primitive The hbargraph primitive implements a horizontal bar-graph (typically a meter displaying the level of a signal). Usage hbargraph takes an input signal and outputs it while making it available to the UI. _ : hbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the hbargraph primitive: Note the use of the attach primitive here that forces the compilation of the hbargraph without using its output signal (see section on the attach primitive ). attach Primitive The attach primitive takes two input signals and produces one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical standpoint attach(x,y) is equivalent to 1*x+0*y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role, let's say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelope detector connected to a bargraph. The problem is that the signal of the envelope generators has no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. The examples in the hbargraph Primitive and the vbargraph Primitive illustrate well the use of attach . Variable Parts of a Label Labels can contain variable parts. These are indicated with the sign % followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example: creates 8 sliders in parallel with different names while par(i,8,hslider(\"Voice\",0.9,0,1,0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Labels as Pathnames Thanks to horizontal , vertical , and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of hslider(\"../volume\",...) would have been /h:Foo/volume , while the pathname of hslider(\"t:Fii/volume\",...) would have been /h:Foo/v:Faa/t:Fii/volume . Elements of a path are separated using / . Group types are defined with the following identifiers: Group Type Group Identifier hgroup h: vgroup v: tgroup t: Hence, the example presented in the section on the hgroup primitive can be rewritten as: which will be reflected in C++ as: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider1, 440.0f, 50.0f, 1000.0f, 0.100000001f); ui_interface->addVerticalSlider(\"gain\", &fVslider0, 0.0f, 0.0f, 1.0f, 0.00999999978f); ui_interface->closeBox(); } Note that path names are inherent to the use of tools gravitating around Faust such as OSC control or faust2api . In the case of faust2api , since no user interface is actually generated, UI elements just become a way to declare parameters of a Faust object. Therefore, there's no distinction between nentry , hslider , vslider , etc. Smoothing Despite the fact that the signal generated by user interface elements can be used in Faust with any other signals, UI elements run at a slower rate than the audio rate. This might be a source of clicking if the value of the corresponding parameter is modified while the program is running. This behavior is also amplified by the low resolution of signals generated by UI elements (as opposed to actual audio signals). For example, changing the value of the freq or gain parameters of the following code will likely create clicks (in the case of gain ) or abrupt jumps (in the case of freq ) in the signal: This problem can be easily solved in Faust by using the si.smoo function which implements an exponential smoothing by a unit-dc-gain one-pole lowpass with a pole at 0.999 ( si.smoo is just sugar for si.smooth(0.999) ). Therefore, the previous example can be rewritten as: Beware that each si.smoo that you place in your code will add some extra computation so they should be used precociously. Links to Generated Code UI elements provide a convenient entry point to the DSP process in the code generated by the Faust compiler (e.g., C++, etc.). For example, the Faust program: import(\"stdfaust.lib\"); freq = hslider(\"freq\",440,50,1000,0.1); process = os.osc(freq); will have the corresponding buildUserInterface method in C++: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"osc\"); ui_interface->addHorizontalSlider(\"freq\", &fHslider0, 440.0f, 50.0f, 1000.0f, 0.100001f); ui_interface->closeBox(); } The second argument of the addHorizontalSlider method is a pointer to the variable containing the current value of the freq parameter. The value of this pointer can be updated at any point to change the frequency of the corresponding oscillator. UI Label Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface, configure OSC and accelerometer control/mapping, etc. Since the format of the value associated to a key is relatively open, metadata constitute a flexible way for programmers to add features to the language. The Faust code: process = *(hslider(\"foo[key1: val 1][key2: val 2]\",0,0,1,0.1)); will produce the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tst\"); ui_interface->declare(&fHslider0, \"key1\", \"val 1\"); ui_interface->declare(&fHslider0, \"key2\", \"val 2\"); ui_interface->addHorizontalSlider(\"foo\", &fHslider0, 0.0f, 0.0f, 1.0f, 0.100000001f); ui_interface->closeBox(); } ... }; All metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. Metadata are architecture-specific: it is up to the architecture file to decide what to do with it. While some metadata will work with most architectures (e.g., accelerometer and OSC configuration, etc.), others might be more specific. Some of them are presented in the following sections. Ordering UI Elements The order of UI declarations in a Faust code doesn't necessarily reflect the actual order of the UI elements in the corresponding interface. Therefore, UI elements can be ordered by placing a metadata before the declaration of the name of the UI element in the label. For example, in the following declaration: gain = vslider(\"h:Oscillator/[1]gain\",0,0,1,0.01); freq = vslider(\"h:Oscillator/[0]freq\",440,50,1000,0.1); the freq parameter will be placed before gain despite the fact that gain is declared first. This system can be used to order groups as well. Ordering will be carried out on elements at the same level. For example: Note that this could also be written as: Global UI Metadata Note that global user interfaces completely replacing the one defined using the standard Faust UI primitives may be declared using global metadata . This is the case of the SmartKeyboard interface for example. In the following subsections, the standard Faust UI metadata are documented. Other types of metadata (e.g., accelerometers, OSC, etc.) are documented in the sections related to these topics. [style:knob] Metadata The [style:knob] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a knob. Example [style:menu] Metadata The [style:menu] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a drop-down menu. Usage [style:menu{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector [style:radio] Metadata The [style:radio] metadata turns a hslider or a vslider into a radio-button-menu. The orientation of the menu is determined by the type of UI element (i.e., hslider for horizontal and vslider for vertical). Usage [style:radio{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector [style:led] Metadata The [style:led] metadata turns a vbargraph or a hbargraph into a blinking LED (with varying intensity). Example: Level Display [style:numerical] Metadata The [style:numerical] metadata turns a vbargraph or a hbargraph into a numerical zone (thus the bargraph itself is no more displayed). Example: Level Display [unit:dB] Metadata The [unit:dB] metadata changes the unit of a vbargraph or a hbargraph to dB. This impacts its overall appearance by applying a rainbow color scheme, etc. Example: Level Display [unit:xx] Metadata The [unit:xx] metadata allows us to specify the unit of a UI element. The unit will be displayed right next to the current value of the parameter in the interface. Usage [unit:xx] Where: xx : the unit of the current parameter Example [scale:xx] Metadata The [scale:xx] metadata allows for the specification of a scale (different than the default linear one) to the parameter in the UI. [scale:log] can be used to change to scale to logarithmic and [scale:exp] to exponential. [tooltip:xx] Metadata The [tooltip:xx] metadata allows for the specification of a \"tooltip\" when the mouse hover a parameter in the interface. This is very convenient when implementing complex interfaces. Usage [tooltip:xx] Where: xx : a string to be used as a tooltip in the interface Example [hidden:0|1] Metadata The [hidden:0|1] metadata can be used to hide a parameter in the interface. This is convenient when controlling a parameter with a motion sensor or OSC messages and we don't want it to be visible in the interface. This feature is commonly used when making apps for Android and iOS using faust2android , faust2ios or in the Web platform. Compatibility iOS Android Web platform Sensors Control Metadatas Sensors control metadata can be used to map the built-in sensors of mobile devices to some of the parameters of a Faust program. Compatibility These metadatas are compatible with the following Faust targets and no additional step is required for them to be taken into account when the corresponding application is generated: faust2android faust2ios faust2smartkeyb Sensors control metadatas have five parameters and follow the following syntax: [acc: a b c d e] // for accelerometer [gyr: a b c d e] // for gyroscope They can be used in a Faust UI parameter declaration: parameter = nentry(\"UIparamName[acc: a b c d e]\",def,min,max,step); with: a : the accelerometer axis ( 0 : x, 1 : y, 2 : z) b : the accelerometer curve (see figure below) c : the minimum acceleration (m/s^2) d : the center acceleration (m/s^2) e : the maximum acceleration (m/s^2) def : the default/init value of the parameter min : the minimum value of the parameter max : the maximum value of the parameter step : the step of the parameter (precision) This allows for the implementation of complex linear and non-linear mappings that are summarized in this figure: For example, controlling the gain of a synthesizer using the X axis of the accelerometer can be easily done simply by writing something like: g = nentry(\"gain[acc: 0 0 -10 0 10]\",0.5,0,1,0.01); With this configuration, g = 0 when the device is standing vertically on its right side, g = 0.5 when the device is standing horizontally with screen facing up, and g = 1 when the device is standing vertically on its left side. Finally, in this slightly more complex mapping, g = 0 when the device is tilted on its right side and the value of g increases towards 1 when the device is tilted on its left side: g = nentry(\"gain[acc: 0 0 0 0 10]\",0,0,1,0.01); Complex nonlinear mappings can be implemented using this system. Widget Modulation Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: Here is a very simple example, assuming freeverb is a fully fonctional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb] Target Widgets Target widgets are specified by their label. Of course, this presupposes knowing the names of the sliders. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in: \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb] Modulators Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: [\"Wet\": * -> freeverb] Please note that the ':' sign used here is just a visual separator, it is not the sequential composition operator. To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs. Here is a complete example:","title":"Faust Syntax"},{"location":"manual/syntax/#faust-syntax","text":"","title":"Faust Syntax"},{"location":"manual/syntax/#faust-program","text":"A Faust program is essentially a list of statements . These statements can be metadata declarations (either global metadata or function metadata ), imports , definitions , and documentation tags , with optional C++ style ( //... and /*...*/ ) comments.","title":"Faust Program"},{"location":"manual/syntax/#variants","text":"Some statements ( imports , definitions ) can be preceded by a variantlist , composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision . This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308;","title":"Variants"},{"location":"manual/syntax/#a-simple-program","text":"Here is a short Faust program that implements of a simple noise generator (called from the noises.lib Faust library). It exhibits various kind of statements: two global metadata declarations, an imports , a comment , and a definition . We will study later how documentation statements work: The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process .","title":"A Simple Program"},{"location":"manual/syntax/#statements","text":"The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions , documentation . All statements but documentation end with a semicolon ; .","title":"Statements"},{"location":"manual/syntax/#metadata","text":"Metadata allow us to add elements which are not part of the language to Faust code. These can range to the name of a Faust program, its author, to potential compilation options or user interface element customizations. There are three different types of metadata in Faust: Global Metadata : metadata global to a Faust code Function Metadata : metadata specific to a function UI Metadata : metadata specific to a UI element Note that some Global Metadata have standard names and can be used for specific tasks. Their role is described in the Standard Metadata section.","title":"Metadata"},{"location":"manual/syntax/#global-metadata","text":"All global metadata declaration in Faust start with declare , followed by a key and a string. For example: declare name \"Noise\"; allows us to specify the name of a Faust program in its whole. Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\";","title":"Global Metadata"},{"location":"manual/syntax/#function-metadata","text":"Metadata can be associated to a specific function. In that case, declare is followed by the name of the function, a key, and a string. For example: declare add author \"John Doe\" add = +; This is very useful when a library has several contributors and that functions potentially have different license terms, etc.","title":"Function Metadata"},{"location":"manual/syntax/#standard-metadata","text":"There exists a series of standard global metadata in Faust whose role role is described in the following table: Metadata Role declare options \"[key0:value][key1:value]\" This metadata can be used to specify various options associated to a Faust code such as the fact its polyphonic, if it should have OSC, MIDI support, etc. Specific keys usable with this metadata are described throughout this documentation. declare interface \"xxx\" Specifies an interface replacing the standard Faust UI.","title":"Standard Metadata"},{"location":"manual/syntax/#imports","text":"File imports allow us to import definitions from other source files. For example import(\"maths.lib\"); imports the definitions of the maths.lib library. The most common file to be imported is the stdfaust.lib library which gives access to all the standard Faust libraries from a single point:","title":"Imports"},{"location":"manual/syntax/#documentation-tags","text":"Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed in the Mathematical Documentation chapter. In this section we essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in Latex format, can be placed in between these two tags. Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. The <metadata> tags allow to reference Faust global metadatas , calling the corresponding keyword. The <notice/> empty-element tag is used to generate the conventions used in the mathematical equations. The <listing/> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies , and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved Faust code between <mdoc> sections.","title":"Documentation Tags"},{"location":"manual/syntax/#definitions","text":"A definition associates an identifier with an expression. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition.","title":"Definitions"},{"location":"manual/syntax/#simple-definitions","text":"The syntax of a simple definition is: identifier = expression; For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245);","title":"Simple Definitions"},{"location":"manual/syntax/#function-definitions","text":"Definitions with formal parameters correspond to functions definitions. For example the definition of linear2db , a function that converts linear values to decibels, is: linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x));","title":"Function Definitions"},{"location":"manual/syntax/#definitions-with-pattern-matching","text":"Moreover, formal parameters can also be full expressions representing patterns: This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Note that this last definition is a convenient alternative to the more verbose: duplicate = case { (1,x) => x; (n,x) => x, duplicate(n-1,x); }; A use case for duplicate could be to put 5 white noise generators in parallel: Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11) . The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element: count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) , the expression will be evaluated as 10 . Note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in: count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time.","title":"Definitions With Pattern Matching"},{"location":"manual/syntax/#expressions","text":"Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions.","title":"Expressions"},{"location":"manual/syntax/#constant-numerical-expressions","text":"Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time . We will refer to them as constant numerical expressions in the documentation.","title":"Constant Numerical Expressions"},{"location":"manual/syntax/#diagram-expressions","text":"Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions.","title":"Diagram Expressions"},{"location":"manual/syntax/#diagram-composition-operations","text":"Five binary composition operations are available to combine block-diagrams: recursion ( ~ ), parallel ( , ), sequential ( : ), split ( <: ), merge ( :> ). One can think of each of these composition operations as a particular way to connect two block diagrams. To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a block-diagram A are expressed as \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively expressed as: [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are: Syntax Priority Association Description expression ~ expression 4 left Recursive Composition expression , expression 3 right Parallel Composition expression : expression 2 right Sequential Composition expression <: expression 1 right Split Composition expression :> expression 1 right Merge Composition Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table that gives the associativity of each numerical operator in infix expressions.","title":"Diagram Composition Operations"},{"location":"manual/syntax/#parallel-composition","text":"The parallel composition (e.g., (A,B) ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation: (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used (e.g., A,B,C,D ), Faust uses right associativity and therefore builds internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example: Oscillators in Parallel Parallel composition can be used to put 3 oscillators of different kinds and frequencies in parallel, which will result in a Faust program with 3 outputs: Example: Stereo Effect Parallel composition can be used to easily turn a mono effect into a stereo one which will result in a Faust program with 2 inputs and 2 outputs: Note that there's a better to write this last example using the par iteration :","title":"Parallel Composition"},{"location":"manual/syntax/#sequential-composition","text":"The sequential composition (e.g., A:B ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Sequential composition is an associative operation: (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore builds internally the expression (A:(B:(C:D))) . Example: Sine Oscillator Since everything is considered as a signal generator in Faust, sequential composition can be simply used to pass an argument to a function: Example: Effect Chain Sequential composition can be used to create an audio effect chain. Here we're plugging a guitar distortion to an autowah:","title":"Sequential Composition"},{"location":"manual/syntax/#split-composition","text":"The split composition (e.g., A<:B ) operator is used to distribute the outputs of A to the inputs of B . For the operation to be valid, the number of inputs of B must be a multiple of the number of outputs of A : \\mathrm{outputs}(A).k=\\mathrm{inputs}(B) Each input i of B is connected to the output i \\bmod k of A : A[i \\bmod k]\\rightarrow[i]B Example: Duplicating the Output of an Oscillator Split composition can be used to duplicate signals. For example, the output of the following sawtooth oscillator is duplicated 3 times in parallel. Note that this can be written in a more effective way by replacing _,_,_ with par(i,3,_) using the par iteration . Example: Connecting a Mono Effect to a Stereo One More generally, the split composition can be used to connect a block with a certain number of output to a block with a greater number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A<:B the number of inputs of B has to be a multiple of the number of outputs of A .","title":"Split Composition"},{"location":"manual/syntax/#merge-composition","text":"The merge composition (e.g., A:>B ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : \\mathrm{outputs}(A)=k.\\mathrm{inputs}(B) Each output i of A is connected to the input i \\bmod k of B : A[i]\\rightarrow\\ [i \\bmod k]B The k incoming signals of an input of B are summed together. Example: Summing Signals Together - Additive Synthesis Merge composition can be used to sum an arbitrary number of signals together. Here's an example of a simple additive synthesizer (note that the result of the sum of the signals is divided by 3 to prevent clicking): While the resulting block diagram will look slightly different, this is mathematically equivalent to: Example: Connecting a Stereo Effect to a Mono One More generally, the merge composition can be used to connect a block with a certain number of output to a block with a smaller number of inputs: Note that an arbitrary number of signals can be split, for example: Once again, the only rule with this is that in the expression A:>B the number of outputs of A has to be a multiple of the number of inputs of B .","title":"Merge Composition"},{"location":"manual/syntax/#recursive-composition","text":"The recursive composition (e.g., A~B ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable, it requires that: \\mathrm{outputs}(A) \\geq \\mathrm{inputs}(B) and \\mathrm{inputs}(A) \\geq \\mathrm{outputs}(B) Each input of B is connected to the corresponding output of A via an implicit 1-sample delay: A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . Example: Timer Recursive composition can be used to implement a \"timer\" that will count each sample starting at time n=0 : The difference equation corresponding to this program is: y(n) = y(n-1) + 1 an its output signal will look like: (1,2,3,4,5,6,\\dots) . Example: One Pole Filter Recursive composition can be used to implement a one pole filter with one line of code and just a few characters: The difference equation corresponding to this program is: y(n) = x(n) + a_{1}y(n-1) Note that the one sample delay of the filter is implicit here so it doesn't have to be declared.","title":"Recursive Composition"},{"location":"manual/syntax/#inputs-and-outputs-of-an-expression","text":"The number of inputs and outputs of a Faust expression can be known at compile time simply by using inputs(expression) and outputs(expression) . For example, the number of outputs of a sine wave oscillator can be known simply by writing the following program: Note that Faust automatically simplified the expression by generating a program that just outputs 1 . This type of construction is useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,ba.selector(n-i-1,n)) with { n = outputs(expr); }; And the inputs of an expression: Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr with { n = inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction:","title":"Inputs and Outputs of an Expression"},{"location":"manual/syntax/#iterations","text":"Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions. The use and role of par , seq , sum , and prod are detailed in the following sections.","title":"Iterations"},{"location":"manual/syntax/#par-iteration","text":"The par iteration can be used to duplicate an expression in parallel. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer i is used here at each iteration to compute the value of the frequency of the current oscillator. Also, note that this example could be re-wrtitten using sum iteration (see example in the corresponding section).","title":"par Iteration"},{"location":"manual/syntax/#seq-iteration","text":"The seq iteration can be used to duplicate an expression in series. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Peak Equalizer The fi.peak_eq function of the Faust libraries implements a second order \"peak equalizer\" section (gain boost or cut near some frequency). When placed in series, it can be used to implement a full peak equalizer: Note that i is used here at each iteration to compute various elements and to format some labels. Having user interface elements with different names is a way to force their differentiation in the generated interface.","title":"seq Iteration"},{"location":"manual/syntax/#sum-iteration","text":"The sum iteration can be used to duplicate an expression as a sum. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Simple Additive Synthesizer The following example is just a slightly different version from the one presented in the par iteration section. While their block diagrams look slightly different, the generated code is exactly the same. i is used here at each iteration to compute the value of the frequency of the current oscillator.","title":"sum Iteration"},{"location":"manual/syntax/#prod-iteration","text":"The prod iteration can be used to duplicate an expression as a product. Just like other types of iterations in Faust: its first argument is a variable name containing the number of the current iteration (a bit like the variable that is usually named i in a for loop) starting at 0, its second argument is the number of iterations, as an integer constant numerical expression , automatically promoted to int its third argument is the expression to be duplicated. Example: Amplitude Modulation Synthesizer The following example implements an amplitude modulation synthesizer using an arbitrary number of oscillators thanks to the prod iteration: i is used here at each iteration to compute the value of the frequency of the current oscillator. Note that the shift parameter can be used to tune the frequency drift between each oscillator.","title":"prod Iteration"},{"location":"manual/syntax/#infix-notation-and-other-syntax-extensions","text":"Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in 2+3 Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar infix notation . For example if you want to multiply two numbers, say 2 and 3 , you can write directly 2*3 instead of the equivalent core-syntax expression 2,3 : * . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example _/2 is equivalent to _,2:/ which divides the incoming signal by 2 . Here are a few examples of equivalences: Infix Syntax Core Syntax 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < In case of doubts on the meaning of an infix expression, for example _*_ , it is useful to translate it to its core syntax equivalent, here _,_:* , which is equivalent to * .","title":"Infix Notation and Other Syntax Extensions"},{"location":"manual/syntax/#infix-operators","text":"Built-in primitives that can be used in infix notation are called infix operators and are listed below. Please note that a more detailed description of these operators is available section on primitives .","title":"Infix Operators"},{"location":"manual/syntax/#comparison-operators","text":"Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression < expression 5 left less than expression <= expression 5 left less or equal expression == expression 5 left equal expression != expression 5 left different expression >= expression 5 left greater or equal expression > expression 5 left greater than","title":"Comparison Operators"},{"location":"manual/syntax/#math-operators","text":"Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. The priority and associativity of the comparison operators is given here: Syntax Pri. Assoc. Description expression + expression 6 left addition expression - expression 6 left subtraction expression * expression 7 left multiplication expression / expression 7 left division expression % expression 7 left modulo expression ^ expression 8 left power","title":"Math Operators"},{"location":"manual/syntax/#bitwise-operators","text":"Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The priority and associativity of the bitwise operators is given here: Syntax Pri. Assoc. Description expression | expression 6 left bitwise or expression & expression 7 left bitwise and expression xor expression 7 left bitwise xor expression << expression 7 left bitwise left shift expression >> expression 7 left bitwise right shift","title":"Bitwise Operators"},{"location":"manual/syntax/#delay-operators","text":"Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \u2019 delays the left handside expression by one sample. Syntax Pri. Assoc. Description expression @ expression 9 left variable delay expression' 10 left one-sample delay","title":"Delay operators"},{"location":"manual/syntax/#prefix-notation","text":"Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) : Prefix Syntax Core Syntax *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : <","title":"Prefix Notation"},{"location":"manual/syntax/#partial-application","text":"The partial application notation is a variant of the prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube), and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one: Prefix Partial Application Syntax Core Syntax +(C) \\equiv _,C : + -(C) \\equiv _,C : - <(C) \\equiv _,C : < /(C) \\equiv _,C : / For commutative operations that doesn't matter. But for non-commutative ones, it is more \"natural\" to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not to other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Example: Gain Controller The following example demonstrates the use of partial application in the context of a gain controller:","title":"Partial Application"},{"location":"manual/syntax/#time-expression","text":"' is used to express a one sample delay. For example: will delay the incoming signal by one sample. ' time expressions can be chained, so the output signal of this program: will look like: (0,0,1,1,1,1,\\dots) . The ' time expression is useful when designing filters, etc. and is equivalent to @(1) (see the @ Time Expression ).","title":"' Time Expression"},{"location":"manual/syntax/#time-expression_1","text":"@ is used to express a delay with an arbitrary number of samples. For example: will delay the incoming signal by 10 samples. A delay expressed with @ doesn't have to be fixed but it must be bounded and cannot be negative. Therefore, the values of a slider are perfectly acceptable: @ only allows for the implementation of integer delay. Thus, various fractional delay algorithms are implemented in the Faust delays.lib library.","title":"@ Time Expression"},{"location":"manual/syntax/#environment-expressions","text":"Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design.","title":"Environment Expressions"},{"location":"manual/syntax/#with-expression","text":"The with construction allows to specify a local environment : a private list of definition that will be used to evaluate the left hand expression. In the following example: the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} .","title":"with Expression"},{"location":"manual/syntax/#letrec-expression","text":"The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows us to easily express groups of mutually recursive signals, for example: x(t) = y(t-1) + 10\\\\ y(t) = x(t-1) - 1 as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: Note the special notation 'x = y + 10 instead of x = y' + 10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelope generator with an attack and a release time (as a number of samples), and a gate signal. A possible definition could be: With the following semantics for n(t) and v(t) : n(t) = (n(t-1)+1) * (g(t) <= g(t-1))\\\\ v(t) = max(0, v(t-1) + (n(t-1)<a(t))/a(t) - (n(t-1)>=a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of \u2019letrec\u2019: x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); };","title":"letrec Expression"},{"location":"manual/syntax/#environment-expression","text":"The environment construction allows to create an explicit environment. It is like a `with' , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. In the following example an environment construction is used to group together some constant definitions: constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next section).","title":"environment Expression"},{"location":"manual/syntax/#access-expression","text":"Definitions inside an environment can be accessed using the . construction. For example constant.pi refers to the definition of pi in the constant environment defined above . Note that environments don't have to be named. We could have written directly: environment{pi = 3.14159; e = 2.718; ... }.pi","title":"Access Expression"},{"location":"manual/syntax/#library-expression","text":"The library construct allows to create an environment by reading the definitions from a file. For example library(\"filters.lib\") represents the environment obtained by reading the file filters.lib . It works like import(\"filters.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"filters.lib\").lowpass denotes the function lowpass as defined in the file filters.lib . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of: import(\"filters.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts: fl = library(\"filters.lib\"); ... ...fl.lowpass.... ... }; In practice, that's how the stdfaust.lib library works.","title":"library Expression"},{"location":"manual/syntax/#component-expression","text":"The component construction allows us to reuse a full Faust program (e.g., a .dsp file) as a simple expression. For example component(\"freeverb.dsp\") denotes the signal processor defined in file freeverb.dsp . Components can be used within expressions like in: ...component(\"karplus32.dsp\") : component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . component works well in tandem with explicit substitution (see next section).","title":"component Expression"},{"location":"manual/syntax/#explicit-substitution","text":"Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing: ...component(\"freeverb.dsp\")[foo(x) = ...;]... };","title":"Explicit Substitution"},{"location":"manual/syntax/#foreign-expressions","text":"Reference to external C functions , variables and constants can be introduced using the foreign expressions mechanism.","title":"Foreign Expressions"},{"location":"manual/syntax/#foreign-function-declaration","text":"An external C function is declared by indicating its name and signature as well as the required include file. The file maths.lib of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows: asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad or fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision and asinfx in fixed-point precision. This is why the four names are provided in the signature.","title":"Foreign function declaration"},{"location":"manual/syntax/#signature","text":"","title":"Signature"},{"location":"manual/syntax/#types","text":"Foreign functions generally expect a precise type: int or float for their parameters. Note that currently only numerical functions involving simple int and float parameters are allowed currently in Faust. No vectors, tables or data structures can be passed as parameters or returned. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float . Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate.","title":"Types"},{"location":"manual/syntax/#foreign-variables-and-constants","text":"External variables and constants can also be declared with a similar syntax. In the same maths.lib file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found: SR = min(192000.0,max(1.0,fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block.","title":"Foreign Variables and Constants"},{"location":"manual/syntax/#include-file","text":"In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include in the generated code.","title":"Include File"},{"location":"manual/syntax/#library-file","text":"In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model .","title":"Library File"},{"location":"manual/syntax/#applications-and-abstractions","text":"Abstractions and applications are fundamental programming constructions directly inspired by Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically.","title":"Applications and Abstractions"},{"location":"manual/syntax/#abstractions","text":"Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. Let's say we want to transform a stereo reverb, dm.zita_light for instance, into a mono effect. The following expression can be written (see the sections on Split Composition and Merge Composition ): _ <: dm.zita_light :> _ The incoming mono signal is split to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that we are interested in transforming other stereo effects. We could generalize this principle by making zita_light a variable: \\(zita_light).(_ <: zita_light :> _) The resulting abstraction can then be applied to transform other effects. Note that if zita_light is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) A name can be given to the abstraction and in turn use it on dm.zita_light : Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _;","title":"Abstractions"},{"location":"manual/syntax/#applications","text":"Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. For example, the abstraction described in the previous section can be used to transform a stereo reverb: mono(dm.zita_light) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(dm.zita_light) Replacing the variable part with the argument is called beta-reduction in Lambda-Calculus Whenever the Faust compiler find an application of an abstraction it replaces the variable part with the argument. The resulting expression is as expected: (_ <: dm.zita_light :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments).","title":"Applications"},{"location":"manual/syntax/#unapplied-abstractions","text":"Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: In Faust, a proper semantic has also been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: can be simply defined as: which is actually equivalent to: process(x,y) = y,x;","title":"Unapplied abstractions"},{"location":"manual/syntax/#pattern-matching","text":"Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(reverb : harmonizer) will produce: harmonizer : freeverb Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching.","title":"Pattern Matching"},{"location":"manual/syntax/#primitives","text":"The primitive signal processing operations represent the built-in functionalities of Faust, that is the atomic operations on signals provided by the language. All these primitives denote signal processors , in other words, functions transforming input signals into output signals .","title":"Primitives"},{"location":"manual/syntax/#numbers","text":"Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double, or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type.","title":"Numbers"},{"location":"manual/syntax/#route-primitive","text":"The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: A is the number of input signals, as an integer constant numerical expression , automatically promoted to int B is the number of output signals, as an integer constant numerical expression , automatically promoted to int a,b / (a,b) is an input/output pair, as integers constant numerical expressions , automatically promoted to int Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: More complex expressions can be written using algorithmic constructions, like the following one to cross N signals:","title":"route Primitive"},{"location":"manual/syntax/#waveform-primitive","text":"The waveform primitive was designed to facilitate the use of rdtable (read table). It allows us to specify a fixed periodic signal as a list of samples as literal numbers. waveform has two outputs: a constant indicating the size (as a number of samples) of the period the periodic signal itself For example waveform{0,1,2,3} produces two outputs: the constant signal 4 and the periodic signal (0,1,2,3,0,1,2,3,0,1,\\dots) . In the following example: waveform is used to define a triangle waveform (in its most primitive form), which is then used with a rdtable controlled by a phaser to implement a triangle wave oscillator. Note that the quality of this oscillator is very low because of the low resolution of the triangle waveform.","title":"waveform Primitive"},{"location":"manual/syntax/#soundfile-primitive","text":"The soundfile(\"label[url:{'path1';'path2';'path3'}]\", n) primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the %i syntax, as in the label part). The soundfile(\"label[url:path]\", n) simplified syntax, or soundfile(\"label\", n) (where label is used as the soundfile path) allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: two inputs: the sound number (as a integer between 0 and 255, automatically promoted to int ), and the read index in the sound (automatically promoted to int , which will access the last sample of the sound if the read index is greater than the sound length) two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound n several more outputs for the sound channels themselves, as a integer constant numerical expression If more outputs than the actual number of channels in the sound file are used, the audio channels will be automatically duplicated up to the wanted number of outputs (so for instance, if a stereo file is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. A minimal example to play a stereo soundfile until it's end can be written with: The 0 first parameter selects the first sound in the soundfile list (which only contains one file in this example), then uses an incrementing read index signal to play the soundfile, cuts the unneeded sound length in frames and sample rate ouputs, and keeps the two actual sound outputs. Having the sound length in frames first output allows to implement sound looping, or any kind of more sophisticated read index signal. Having the sound sample rate second output allows to possibly adapt or change the reading speed. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file in the Faust repository implements the void addSoundfile(label, path, sf_zone) method, which loads the actual soundfiles using the libsndfile library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that the complete soundfile content is preloaded in memory at initialisation time when the compiled program starts. Note that a special architecture file can well decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge of actually setting up all sound memory pointers when void addSoundfile(label, path, sf_zone) is called by the buidUserInterface mechanism.","title":"soundfile Primitive"},{"location":"manual/syntax/#c-equivalent-primitives","text":"Most Faust primitives are analogous to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . + can be used to very simply implement a mixer: Note that this is equivalent to (see Identity Function ): The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form. It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance, -(a*b) is a partial application. It is syntactic sugar for _,(a*b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a*b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type.","title":"C-Equivalent Primitives"},{"location":"manual/syntax/#integer-number","text":"Integer numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described mathematically as y(t)=n . Example: DC Offset of 1","title":"Integer Number"},{"location":"manual/syntax/#floating-point-number","text":"Floating point numbers are of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} in Faust and can be described as y(t)=n.m . Example: DC Offset of 0.5","title":"Floating Point Number"},{"location":"manual/syntax/#identity-function","text":"The identity function is expressed in Faust with the _ primitive. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x(t) Example: a Signal Passing Through In the following example, the _ primitive is used to connect the single audio input of a Faust program to its output:","title":"Identity Function"},{"location":"manual/syntax/#cut-primitive","text":"The cut primitive is expressed in Faust with ! . It can be used to \"stop\"/terminate a signal. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} Mathematical Description: \\forall x\\in\\mathbb{S},(x)\\rightarrow () Example: Stopping a Signal In the following example, the ! primitive is used to stop one of two parallel signals:","title":"Cut Primitive"},{"location":"manual/syntax/#int-primitive","text":"The int primitive can be used to force the cast of a signal to int. It is of type \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} and can be described mathematically as y(t)=(int)x(t) . This primitive is useful when declaringindices to read in a table, etc. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(int)x(t) Example: Simple Cast","title":"int Primitive"},{"location":"manual/syntax/#float-primitive","text":"The float primitive can be used to force the cast of a signal to float. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=(float)x(t) Example: Simple Cast","title":"float Primitive"},{"location":"manual/syntax/#add-primitive","text":"The + primitive can be used to add two signals together. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)+x_{2}(t) Example: Simple Mixer","title":"Add Primitive"},{"location":"manual/syntax/#subtract-primitive","text":"The - primitive can be used to subtract two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)-x_{2}(t) Example: Subtracting Two Input Signals","title":"Subtract Primitive"},{"location":"manual/syntax/#multiply-primitive","text":"The * primitive can be used to multiply two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)*x_{2}(t) Example: Multiplying a Signal by 0.5","title":"Multiply Primitive"},{"location":"manual/syntax/#divide-primitive","text":"The / primitive can be used to divide two signals. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)/{x_{2}(t)} Example: Dividing a Signal by 2","title":"Divide Primitive"},{"location":"manual/syntax/#power-primitive","text":"The ^ primitive can be used to raise to the power of N a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)^{x_{2}(t)} Example: Power of Two of a Signal","title":"Power Primitive"},{"location":"manual/syntax/#modulo-primitive","text":"The % primitive can be used to take the modulo of a signal. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\%{x_{2}(t)} Example: Phaser The following example uses a counter and the % primitive to implement a basic phaser: will output a signal: (0,1,2,3,4,5,6,7,8,9,0,1,2,3,4) .","title":"Modulo Primitive"},{"location":"manual/syntax/#and-primitive","text":"Bitwise AND can be expressed in Faust with the & primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\&{x_{2}(t)}","title":"AND Primitive"},{"location":"manual/syntax/#or-primitive","text":"Bitwise OR can be expressed in Faust with the | primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)|{x_{2}(t)} Example The following example will output 1 if the incoming signal is smaller than 0.5 or greater than 0.7 and 0 otherwise. Note that the result of this operation could be multiplied to another signal to create a condition.","title":"OR Primitive"},{"location":"manual/syntax/#xor-primitive","text":"Bitwise XOR can be expressed in Faust with the xor primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t)\\land {x_{2}(t)} Example","title":"XOR Primitive"},{"location":"manual/syntax/#left-shift-primitive","text":"Left shift can be expressed in Faust with the << primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) << {x_{2}(t)} Example","title":"Left Shift Primitive"},{"location":"manual/syntax/#right-shift-primitive","text":"Right shift can be expressed in Faust with the >> primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >> {x_{2}(t)} Example","title":"Right Shift Primitive"},{"location":"manual/syntax/#smaller-than-primitive","text":"The smaller than comparison can be expressed in Faust with the < primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) < {x_{2}(t)} Example The following code will output 1 if the input signal is smaller than 0.5 and 0 otherwise.","title":"Smaller Than Primitive"},{"location":"manual/syntax/#smaller-or-equal-than-primitive","text":"The smaller or equal than comparison can be expressed in Faust with the <= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) <= {x_{2}(t)} Example The following code will output 1 if the input signal is smaller or equal than 0.5 and 0 otherwise.","title":"Smaller or Equal Than Primitive"},{"location":"manual/syntax/#greater-than-primitive","text":"The greater than comparison can be expressed in Faust with the > primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) > {x_{2}(t)} Example The following code will output 1 if the input signal is greater than 0.5 and 0 otherwise.","title":"Greater Than Primitive"},{"location":"manual/syntax/#greater-or-equal-than-primitive","text":"The greater or equal than comparison can be expressed in Faust with the >= primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) >= {x_{2}(t)} Example The following code will output 1 if the input signal is greater or equal than 0.5 and 0 otherwise.","title":"Greater or Equal Than Primitive"},{"location":"manual/syntax/#equal-to-primitive","text":"The equal to comparison can be expressed in Faust with the == primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) == {x_{2}(t)} Example","title":"Equal to Primitive"},{"location":"manual/syntax/#different-than-primitive","text":"The different than comparison can be expressed in Faust with the != primitive. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=x_{1}(t) != {x_{2}(t)} Example","title":"Different Than Primitive"},{"location":"manual/syntax/#mathh-equivalent-primitives","text":"Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib ). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it.","title":"math.h-Equivalent Primitives"},{"location":"manual/syntax/#acos-primitive","text":"Arc cosine can be expressed as acos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{acosf}(x(t)) Example","title":"acos Primitive"},{"location":"manual/syntax/#asin-primitive","text":"Arc sine can be expressed as asin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{asinf}(x(t)) Example","title":"asin Primitive"},{"location":"manual/syntax/#atan-primitive","text":"Arc tangent can be expressed as atan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atanf}(x(t)) Example","title":"atan Primitive"},{"location":"manual/syntax/#atan2-primitive","text":"The arc tangent of 2 signals can be expressed as atan2 in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) Example","title":"atan2 Primitive"},{"location":"manual/syntax/#cos-primitive","text":"Cosine can be expressed as cos in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{cosf}(x(t)) Example","title":"cos Primitive"},{"location":"manual/syntax/#sin-primitive","text":"Sine can be expressed as sin in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sinf}(x(t)) Example","title":"sin Primitive"},{"location":"manual/syntax/#tan-primitive","text":"Tangent can be expressed as tan in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{tanf}(x(t)) Example","title":"tan Primitive"},{"location":"manual/syntax/#exp-primitive","text":"Base-e exponential can be expressed as exp in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{expf}(x(t)) Example","title":"exp Primitive"},{"location":"manual/syntax/#log-primitive","text":"Base-e logarithm can be expressed as log in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{logf}(x(t)) Example","title":"log Primitive"},{"location":"manual/syntax/#log10-primitive","text":"Base-10 logarithm can be expressed as log10 in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{log10}(x(t)) Example","title":"log10 Primitive"},{"location":"manual/syntax/#pow-primitive","text":"Power can be expressed as pow in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) Example","title":"pow Primitive"},{"location":"manual/syntax/#sqrt-primitive","text":"Square root can be expressed as sqrt in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{sqrtf}(x(t)) Example","title":"sqrt Primitive"},{"location":"manual/syntax/#abs-primitive","text":"Absolute value can be expressed as abs in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{abs}(x(t)) (int) or y(t)=\\mathrm{fabsf}(x(t)) (float) Example","title":"abs Primitive"},{"location":"manual/syntax/#min-primitive","text":"Minimum can be expressed as min in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) Example","title":"min Primitive"},{"location":"manual/syntax/#max-primitive","text":"Maximum can be expressed as max in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) Example","title":"max Primitive"},{"location":"manual/syntax/#fmod-primitive","text":"Float modulo can be expressed as fmod in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) Example","title":"fmod Primitive"},{"location":"manual/syntax/#remainder-primitive","text":"Float remainder can be expressed as remainder in Faust. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) Example","title":"remainder Primitive"},{"location":"manual/syntax/#floor-primitive","text":"Largest int can be expressed as floor in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\leq : y(t)=\\mathrm{floorf}(x(t)) Example","title":"floor Primitive"},{"location":"manual/syntax/#ceil-primitive","text":"Smallest int can be expressed as ceil in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: \\geq : y(t)=\\mathrm{ceilf}(x(t)) Example","title":"ceil Primitive"},{"location":"manual/syntax/#rint-primitive","text":"Closest int (using the current rounding mode) can be expressed as rint in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{rintf}(x(t)) Example","title":"rint Primitive"},{"location":"manual/syntax/#round-primitive","text":"Nearest int value (regardless of the current rounding mode) can be expressed as round in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=\\mathrm{roundf}(x(t)) Example","title":"round Primitive"},{"location":"manual/syntax/#delay-primitives-and-modifiers","text":"Faust hosts various modifiers and primitives to define one sample or integer delay of arbitrary length. They are presented in this section.","title":"Delay Primitives and Modifiers"},{"location":"manual/syntax/#mem-primitive","text":"A 1 sample delay can be expressed as mem in Faust. Type: \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+1)=x(t),y(0)=0 Example Note that this is equivalent to process = _' (see ' Modifier ) and process = @(1) (see @ Primitive )","title":"mem Primitive"},{"location":"manual/syntax/#modifier","text":"' can be used to apply a 1 sample delay to a signal in Faust. It can be seen as syntactic sugar to the mem primitive . ' is very convenient when implementing filters and can help significantly decrease the size of the Faust code. Example","title":"' Modifier"},{"location":"manual/syntax/#primitive","text":"An integer delay of N samples can be expressed as @(N) in Faust. Note that N (automatically promoted to int ) can be dynamic but that its range must be bounded. This can be done by using a UI primitive (see example below) allowing for the definition of a range such as hslider , vslider , or nentry . Note that floating point delay is also available in Faust by the mean of various fractional delay implementations available in the Faust standard libraries. Type: \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t+x_{2}(t))=x_{1}(t), y(t<x_{2}(t))=0 Usage _ : @(N) : _ Where: N : the length of the delay as a number of samples Example: Static N Samples Delay Example: Dynamic N Samples Delay","title":"@ Primitive"},{"location":"manual/syntax/#table-primitives","text":"","title":"Table Primitives"},{"location":"manual/syntax/#rdtable-primitive","text":"The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The table can either be implemented by using the waveform primitive (as shown in the first example) or using a function controlled by a timer (such as ba.time ) as demonstrated in the second example. The idea is that the table is created during the initialization step and before audio computation begins. Type: \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} Mathematical Description: y(t)=T[r(t)] Usage rdtable(n,s,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the table content r : the read index (an int between 0 and n-1 ), automatically promoted to int Example: Basic Triangle Wave Oscillator Using the waveform Primitive In this example, a basic (and dirty) triangle wave-table is defined using the waveform . It is then used with the rdtable primitive and a phasor to implement a triangle wave oscillator: Example: Basic Triangle Wave Oscillator Using the sin Primitive and a Timer In this example, a sine table is implemented using the sin primitive and a timer ( ba.time ). The timer calls the sin function during the initialization step of the Faust program. It is then used with rdtable to implement a sine wave oscillator.","title":"rdtable Primitive"},{"location":"manual/syntax/#rwtable-primitive","text":"The rwtable primitive can be used to implement a read/write table. It takes an audio input that can be written in the table using a write index (i.e., w below) and read using a read index (i.e., r below). Type: \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} Mathematical Description: T[w(t)]=c(t); y(t)=T[r(t)] Usage _ : rwtable(n,s,w,_,r) : _ Where: n : the table size, an integer as a constant numerical expression , automatically promoted to int s : the initial table content w : the write index (an int between 0 and n-1 ), automatically promoted to int r : the read index (an int between 0 and n-1 ), automatically promoted to int Note that the fourth argument of rwtable corresponds to the input of the table. Example: Simple Looper In this example, an input signal is written in the table when record is true (equal to 1). The read index is constantly updated to loop through the table. The table size is set to 48000, which corresponds to one second if the sampling rate is 48000 KHz.","title":"rwtable Primitive"},{"location":"manual/syntax/#selector-primitives","text":"Selector primitives can be used to create conditions in Faust and to implement switches to choose between several signals.","title":"Selector Primitives"},{"location":"manual/syntax/#select2-primitive","text":"The select2 primitive is a \"two-way selector\". It has three input signals: s , x_0 , x_1 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other two inputs x_0(t) and x_1(t) to the output y(t) . Note Please note that select2 is not the equivalent of a traditional if-then-else construction. Like every Faust primitive, it has a strict semantics. All input signals are always computed, even when they are not selected. Therefore you can't use select2 to avoid computing something. The semantics of select2 is as follows: Type: (s,x_0,x_1)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\end{array} \\right. Usage _,_ : select2(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine and a sawtooth wave oscillator. Note that select2 could be easily implemented from scratch in Faust: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.","title":"select2 Primitive"},{"location":"manual/syntax/#select3-primitive","text":"The select3 primitive is a \"three-ways selector\". It has four input signals: s , x_0 , x_1 , x_2 and one output signal y . At each instant the value of the selector signal s(t) is used to dynamically route samples from the other three inputs x_0(t) , x_1(t) and x_2(t) to the output y(t) . Type: (s,x_0,x_1,x_2)\\rightarrow y Mathematical Description: y(t) = \\left\\{ \\begin{array}{ll} x_0(t) & \\mathrm{if\\ } s(t) = 0;\\\\ x_1(t) & \\mathrm{if\\ } s(t) = 1.\\\\ x_2(t) & \\mathrm{if\\ } s(t) = 2.\\end{array} \\right. Usage _,_,_ : select3(s) : _ Where: s : the selector ( 0 for the first signal, 1 for the second one, 2 for the third one), automatically promoted to int Example: Signal Selector The following example allows the user to choose between a sine, a sawtooth and a triangle wave oscillator. Note that select3 could be easily implemented from scratch in Faust using Boolean primitives: While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.","title":"select3 Primitive"},{"location":"manual/syntax/#specific-primitives","text":"In Faust, signals operate within a [min, max] range. The lowest(sig) primitive determines the minimum value a given sig signal can attain, while the highest(sig) primitive identifies its maximum value. However, be aware that the compiler's interval computation might not accurately estimate the true [min, max] range, often resulting in -INFINITY for the minimum value and/or INFINITY for the maximum value.","title":"Specific Primitives"},{"location":"manual/syntax/#user-interface-primitives-and-configuration","text":"Faust user interface widgets/primitives allow for an abstract description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be discrete (e.g., button , checkbox , etc.), continuous (e.g., hslider , vslider , nentry ), and organizational (e.g., vgroup , hgroup ). Discrete and continuous elements are signal generators. For example, a button produces a signal which is 1 when the button is pressed and 0 otherwise: These signals can be freely combined with other audio signals. In fact, the following code is perfectly valid and will generate sound: Each primitive implements a specific UI element, but their appearance can also be completely modified using metadata (a little bit like HTML and CSS in the web). Therefore, hslider , vslider , and nentry ) can for example be turned into a knob, a dropdown menu, etc. This concept is further developed in the section on UI metadata . Continuous UI elements (i.e., hslider , vslider , and nentry ) must all declare a range for the parameter they're controlling. In some cases, this range is used during compilation to allocate memory and will impact the generated code. For example, in the case of: a buffer of 10 samples will be allocated for the delay implemented with the @ primitive while 20 samples will be allocated in the following example:","title":"User Interface Primitives and Configuration"},{"location":"manual/syntax/#button-primitive","text":"The button primitive implements a button. Usage button(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger","title":"button Primitive"},{"location":"manual/syntax/#checkbox-primitive","text":"The checkbox primitive implements a checkbox/toggle. Usage checkbox(\"label\") : _ Where: label : the label (expressed as a string) of the element in the interface Example: Trigger","title":"checkbox Primitive"},{"location":"manual/syntax/#hslider-primitive","text":"The hslider primitive implements a horizontal slider. Usage hslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example: Gain Control Example: Additive Oscillator Here is an example of a 3 oscillators instrument where the default frequency of each partial is computed using a more complex constant numerical expression .","title":"hslider Primitive"},{"location":"manual/syntax/#vslider-primitive","text":"The vslider primitive implements a vertical slider. Usage vslider(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the slider, a constant numerical expression min : the minimum value of the slider, a constant numerical expression max : the maximum value of the slider, a constant numerical expression step : the precision (step) of the slider (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example","title":"vslider Primitive"},{"location":"manual/syntax/#nentry-primitive","text":"The nentry primitive implements a \"numerical entry\". Usage nentry(\"label\",init,min,max,step) : _ Where: label : the label (expressed as a string) of the element in the interface init : the initial value of the numerical entry, a constant numerical expression min : the minimum value of the numerical entry, a constant numerical expression max : the maximum value of the numerical entry, a constant numerical expression step : the precision (step) of the numerical entry (1 to count 1 by 1, 0.1 to count 0.1 by 0.1, etc.), a constant numerical expression Example","title":"nentry Primitive"},{"location":"manual/syntax/#hgroup-primitive","text":"The hgroup primitive implements a horizontal group. A group contains other UI elements that can also be groups. hgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage hgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"hgroup Primitive"},{"location":"manual/syntax/#vgroup-primitive","text":"The vgroup primitive implements a vertical group. A group contains other UI elements that can also be groups. vgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage vgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"vgroup Primitive"},{"location":"manual/syntax/#tgroup-primitive","text":"The tgroup primitive implements a \"tab group.\" Tab groups can be used to group UI elements in tabs in the interface. A group contains other UI elements that can also be groups. tgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code. Usage tgroup(\"label\",x) Where: label : the label (expressed as a string) of the element in the interface x : the encapsulated/labeled Faust code Example In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group. Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.","title":"tgroup Primitive"},{"location":"manual/syntax/#vbargraph-primitive","text":"The vbargraph primitive implements a vertical bar-graph (typically a meter displaying the level of a signal). Usage vbargraph takes an input signal and outputs it while making it available to the UI. _ : vbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the vbargraph primitive: Note the use of the attach primitive here that forces the compilation of the vbargraph without using its output signal (see section on the attach primitive ).","title":"vbargraph Primitive"},{"location":"manual/syntax/#hbargraph-primitive","text":"The hbargraph primitive implements a horizontal bar-graph (typically a meter displaying the level of a signal). Usage hbargraph takes an input signal and outputs it while making it available to the UI. _ : hbargraph(\"label\",min,max) : _ Where: min : the minimum value of the signal in the interface, a constant numerical expression max : the maximum value of the signal in the interface, a constant numerical expression Example: Simple VU Meter A simple VU meter can be implemented using the hbargraph primitive: Note the use of the attach primitive here that forces the compilation of the hbargraph without using its output signal (see section on the attach primitive ).","title":"hbargraph Primitive"},{"location":"manual/syntax/#attach-primitive","text":"The attach primitive takes two input signals and produces one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical standpoint attach(x,y) is equivalent to 1*x+0*y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role, let's say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelope detector connected to a bargraph. The problem is that the signal of the envelope generators has no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. The examples in the hbargraph Primitive and the vbargraph Primitive illustrate well the use of attach .","title":"attach Primitive"},{"location":"manual/syntax/#variable-parts-of-a-label","text":"Labels can contain variable parts. These are indicated with the sign % followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example: creates 8 sliders in parallel with different names while par(i,8,hslider(\"Voice\",0.9,0,1,0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) .","title":"Variable Parts of a Label"},{"location":"manual/syntax/#labels-as-pathnames","text":"Thanks to horizontal , vertical , and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of hslider(\"../volume\",...) would have been /h:Foo/volume , while the pathname of hslider(\"t:Fii/volume\",...) would have been /h:Foo/v:Faa/t:Fii/volume . Elements of a path are separated using / . Group types are defined with the following identifiers: Group Type Group Identifier hgroup h: vgroup v: tgroup t: Hence, the example presented in the section on the hgroup primitive can be rewritten as: which will be reflected in C++ as: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider1, 440.0f, 50.0f, 1000.0f, 0.100000001f); ui_interface->addVerticalSlider(\"gain\", &fVslider0, 0.0f, 0.0f, 1.0f, 0.00999999978f); ui_interface->closeBox(); } Note that path names are inherent to the use of tools gravitating around Faust such as OSC control or faust2api . In the case of faust2api , since no user interface is actually generated, UI elements just become a way to declare parameters of a Faust object. Therefore, there's no distinction between nentry , hslider , vslider , etc.","title":"Labels as Pathnames"},{"location":"manual/syntax/#smoothing","text":"Despite the fact that the signal generated by user interface elements can be used in Faust with any other signals, UI elements run at a slower rate than the audio rate. This might be a source of clicking if the value of the corresponding parameter is modified while the program is running. This behavior is also amplified by the low resolution of signals generated by UI elements (as opposed to actual audio signals). For example, changing the value of the freq or gain parameters of the following code will likely create clicks (in the case of gain ) or abrupt jumps (in the case of freq ) in the signal: This problem can be easily solved in Faust by using the si.smoo function which implements an exponential smoothing by a unit-dc-gain one-pole lowpass with a pole at 0.999 ( si.smoo is just sugar for si.smooth(0.999) ). Therefore, the previous example can be rewritten as: Beware that each si.smoo that you place in your code will add some extra computation so they should be used precociously.","title":"Smoothing"},{"location":"manual/syntax/#links-to-generated-code","text":"UI elements provide a convenient entry point to the DSP process in the code generated by the Faust compiler (e.g., C++, etc.). For example, the Faust program: import(\"stdfaust.lib\"); freq = hslider(\"freq\",440,50,1000,0.1); process = os.osc(freq); will have the corresponding buildUserInterface method in C++: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"osc\"); ui_interface->addHorizontalSlider(\"freq\", &fHslider0, 440.0f, 50.0f, 1000.0f, 0.100001f); ui_interface->closeBox(); } The second argument of the addHorizontalSlider method is a pointer to the variable containing the current value of the freq parameter. The value of this pointer can be updated at any point to change the frequency of the corresponding oscillator.","title":"Links to Generated Code"},{"location":"manual/syntax/#ui-label-metadata","text":"Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface, configure OSC and accelerometer control/mapping, etc. Since the format of the value associated to a key is relatively open, metadata constitute a flexible way for programmers to add features to the language. The Faust code: process = *(hslider(\"foo[key1: val 1][key2: val 2]\",0,0,1,0.1)); will produce the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"tst\"); ui_interface->declare(&fHslider0, \"key1\", \"val 1\"); ui_interface->declare(&fHslider0, \"key2\", \"val 2\"); ui_interface->addHorizontalSlider(\"foo\", &fHslider0, 0.0f, 0.0f, 1.0f, 0.100000001f); ui_interface->closeBox(); } ... }; All metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. Metadata are architecture-specific: it is up to the architecture file to decide what to do with it. While some metadata will work with most architectures (e.g., accelerometer and OSC configuration, etc.), others might be more specific. Some of them are presented in the following sections.","title":"UI Label Metadata"},{"location":"manual/syntax/#ordering-ui-elements","text":"The order of UI declarations in a Faust code doesn't necessarily reflect the actual order of the UI elements in the corresponding interface. Therefore, UI elements can be ordered by placing a metadata before the declaration of the name of the UI element in the label. For example, in the following declaration: gain = vslider(\"h:Oscillator/[1]gain\",0,0,1,0.01); freq = vslider(\"h:Oscillator/[0]freq\",440,50,1000,0.1); the freq parameter will be placed before gain despite the fact that gain is declared first. This system can be used to order groups as well. Ordering will be carried out on elements at the same level. For example: Note that this could also be written as:","title":"Ordering UI Elements"},{"location":"manual/syntax/#global-ui-metadata","text":"Note that global user interfaces completely replacing the one defined using the standard Faust UI primitives may be declared using global metadata . This is the case of the SmartKeyboard interface for example. In the following subsections, the standard Faust UI metadata are documented. Other types of metadata (e.g., accelerometers, OSC, etc.) are documented in the sections related to these topics.","title":"Global UI Metadata"},{"location":"manual/syntax/#styleknob-metadata","text":"The [style:knob] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a knob. Example","title":"[style:knob] Metadata"},{"location":"manual/syntax/#stylemenu-metadata","text":"The [style:menu] metadata turns any continuous UI element (i.e., hslider , vslider , nentry ) into a drop-down menu. Usage [style:menu{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector","title":"[style:menu] Metadata"},{"location":"manual/syntax/#styleradio-metadata","text":"The [style:radio] metadata turns a hslider or a vslider into a radio-button-menu. The orientation of the menu is determined by the type of UI element (i.e., hslider for horizontal and vslider for vertical). Usage [style:radio{'Name0':value0;'Name1':value1}] Where: NameN : the name associated to valueN valueN : the value associated to NameN Example: Selector","title":"[style:radio] Metadata"},{"location":"manual/syntax/#styleled-metadata","text":"The [style:led] metadata turns a vbargraph or a hbargraph into a blinking LED (with varying intensity). Example: Level Display","title":"[style:led] Metadata"},{"location":"manual/syntax/#stylenumerical-metadata","text":"The [style:numerical] metadata turns a vbargraph or a hbargraph into a numerical zone (thus the bargraph itself is no more displayed). Example: Level Display","title":"[style:numerical] Metadata"},{"location":"manual/syntax/#unitdb-metadata","text":"The [unit:dB] metadata changes the unit of a vbargraph or a hbargraph to dB. This impacts its overall appearance by applying a rainbow color scheme, etc. Example: Level Display","title":"[unit:dB] Metadata"},{"location":"manual/syntax/#unitxx-metadata","text":"The [unit:xx] metadata allows us to specify the unit of a UI element. The unit will be displayed right next to the current value of the parameter in the interface. Usage [unit:xx] Where: xx : the unit of the current parameter Example","title":"[unit:xx] Metadata"},{"location":"manual/syntax/#scalexx-metadata","text":"The [scale:xx] metadata allows for the specification of a scale (different than the default linear one) to the parameter in the UI. [scale:log] can be used to change to scale to logarithmic and [scale:exp] to exponential.","title":"[scale:xx] Metadata"},{"location":"manual/syntax/#tooltipxx-metadata","text":"The [tooltip:xx] metadata allows for the specification of a \"tooltip\" when the mouse hover a parameter in the interface. This is very convenient when implementing complex interfaces. Usage [tooltip:xx] Where: xx : a string to be used as a tooltip in the interface Example","title":"[tooltip:xx] Metadata"},{"location":"manual/syntax/#hidden01-metadata","text":"The [hidden:0|1] metadata can be used to hide a parameter in the interface. This is convenient when controlling a parameter with a motion sensor or OSC messages and we don't want it to be visible in the interface. This feature is commonly used when making apps for Android and iOS using faust2android , faust2ios or in the Web platform. Compatibility iOS Android Web platform","title":"[hidden:0|1] Metadata"},{"location":"manual/syntax/#sensors-control-metadatas","text":"Sensors control metadata can be used to map the built-in sensors of mobile devices to some of the parameters of a Faust program. Compatibility These metadatas are compatible with the following Faust targets and no additional step is required for them to be taken into account when the corresponding application is generated: faust2android faust2ios faust2smartkeyb Sensors control metadatas have five parameters and follow the following syntax: [acc: a b c d e] // for accelerometer [gyr: a b c d e] // for gyroscope They can be used in a Faust UI parameter declaration: parameter = nentry(\"UIparamName[acc: a b c d e]\",def,min,max,step); with: a : the accelerometer axis ( 0 : x, 1 : y, 2 : z) b : the accelerometer curve (see figure below) c : the minimum acceleration (m/s^2) d : the center acceleration (m/s^2) e : the maximum acceleration (m/s^2) def : the default/init value of the parameter min : the minimum value of the parameter max : the maximum value of the parameter step : the step of the parameter (precision) This allows for the implementation of complex linear and non-linear mappings that are summarized in this figure: For example, controlling the gain of a synthesizer using the X axis of the accelerometer can be easily done simply by writing something like: g = nentry(\"gain[acc: 0 0 -10 0 10]\",0.5,0,1,0.01); With this configuration, g = 0 when the device is standing vertically on its right side, g = 0.5 when the device is standing horizontally with screen facing up, and g = 1 when the device is standing vertically on its left side. Finally, in this slightly more complex mapping, g = 0 when the device is tilted on its right side and the value of g increases towards 1 when the device is tilted on its left side: g = nentry(\"gain[acc: 0 0 0 0 10]\",0,0,1,0.01); Complex nonlinear mappings can be implemented using this system.","title":"Sensors Control Metadatas"},{"location":"manual/syntax/#widget-modulation","text":"Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: Here is a very simple example, assuming freeverb is a fully fonctional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb]","title":"Widget Modulation"},{"location":"manual/syntax/#target-widgets","text":"Target widgets are specified by their label. Of course, this presupposes knowing the names of the sliders. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in: \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb]","title":"Target Widgets"},{"location":"manual/syntax/#modulators","text":"Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: [\"Wet\": * -> freeverb] Please note that the ':' sign used here is just a visual separator, it is not the sequential composition operator. To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 .","title":"Modulators"},{"location":"manual/syntax/#modulators-with-no-inputs","text":"Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb]","title":"Modulators with no inputs"},{"location":"manual/syntax/#modulators-with-one-input","text":"A 1->1 modulator transforms the signal produced by the widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider.","title":"Modulators with one input"},{"location":"manual/syntax/#modulators-with-two-inputs","text":"Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs. Here is a complete example:","title":"Modulators with two inputs"},{"location":"manual/tools/","text":"faust2[...] Tools While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This description provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust tools is a set of scripts that take a dsp file as input to generate various output for a lot of architectures and platforms. All the tools names are in the form faust2xx where xx is the target architecture. Use -h or -help to get more information on each specific script options, the supported platforms and possibly the required packages. Additional Faust compiler options (like -vec -lv 0 -I /path/to/lib ) can be given. For scripts that combines Faust and the C++ compiler, you can possibly use the CXXFLAGS environment variable to give additional options to the C++ compiler. Note that some of the tools are somewhat meta tools when they are based on a framework that itself can generate several formats later on. This is the case of the faust2juce script for instance. Note that using -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. The template-llvm.cpp file that uses libfaust + LLVM backend to dynamically compile a foo.dsp file is an example of this approach. It has be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application. or: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp to generate a polyphonic (8 voices), MIDI controllable faust2cagtk-llvm application. Note that libfaust and LLVM libraries still have to be added at the link stage, so a -dyn : create libfaust + LLVM backend dynamic version option has been added to the faust2cagtk tool and some others. faust2alqt Usage: faust2alqt [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa, QT Compiles Faust programs to ALSA and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2alsa Usage: faust2alsa [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to ALSA and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2alsaconsole Usage: faust2alsaconsole [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to CLI and ALSA Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -arch32 : compiles a 32 bits binary -arch64 : compiles a 64 bits binary Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2android Usage: faust2android [options] [Faust options] <file.dsp> Target platform: Android Require: Android SDK Compile a Faust program to an Android app (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/android) Options: -osc : activates OSC control -source : creates an eclipse project of the app in the current directory. -swig : regenerates the C++ and the JAVA interface for the native portion of the app. -faust : only carries out the Faust compilation and install the generated C++ file in the JNI folder. -reuse : preserves build directory and reuse it to speedup compilation. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -install : once compilation is over, installs the generated apk on the Android device connected to the computer -debug : activates verbose output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2androidunity Usage: faust2androidunity [options] [Faust options] <file1.dsp> [<file2.dsp>] Target platform: Android Unity Require: Android SDK Make sure the ANDROID_HOME environment variable is set to the sdk folder. Creates android libraries (armeabi-v7a and x86) for faust unity plugin. If you need other android architectures, open architecture/unity/Android/Application.mk and modify APP_ABI. See architecture/unity/README.md for more info (also available from the compile folder) Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -android : creates also the c# and JSON files Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2api Usage: faust2api [options] [Faust options] <file.dsp> faust2api can be used to generate Faust based dsp objects for various platforms (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/api): Output options: -ios : generates an iOS API -android : generates an Android API -coreaudio : generates an OSX CoreAudio API -alsa : generates an ALSA API -jack : generates a JACK API -portaudio : generates a PortAudio API -rtaudio : generates an RTAudio API -of : generates an openFrameworks API -juce : generates a JUCE API -dummy : generates a dummy audio API -teensy : generates a Teensy API -esp32 : generates a ESP32 API Global options: -opt native|generic : activates the best compilation options for the native or generic CPU -nvoices <num> : creates a polyphonic object with <num> voices -effect <effect.dsp> : adds an effect to the polyphonic synth (ignored if -nvoices is not specified) -effect auto : adds an effect (extracted automatically from the dsp file) to the polyphonic synth (ignored if -nvoices is not specified) -nodoc : prevents documentation from being generated -nozip : prevents generated files to be put in a zip file -target <target> : sets a name of the target folder or the zip file. Defaults to \"dsp-faust\" Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. Android specific options: -package : set the JAVA package name (e.g. '-package mypackage' will change the JAVA package name to 'mypackage.DspFaust'). The default package name is 'com.DspFaust.' -soundfile : add built-in Soundfile support to the API Options supported by iOS, CoreAudio, ALSA, JACK, PortAudio, openFrameworks and JUCE -midi : add built-in RtMidi support to the API -osc : add built-in OSC support to the API -soundfile : add built-in Soundfile support to the API JACK specific options -build : build a ready to test binary -dynamic : add libfaust/LLVM dynamic DSP compilation mode faust2bela Usage: faust2bela [options] [Faust options] <file.dsp> Target platform: Bela Compiles Faust programs to the BELA board Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Polyphonic mode means MIDI instrument with at least 1 voice. Use no arguments for a simple effect. -gui : activates a self-hosted GUI interface. Requires to have libmicrohttpd and libHTTPDFaust installed. -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI -tobela : to send C++ file into bela, and to run it Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2bench Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2caconsole Usage: faust2caconsole [options] [Faust options] <file.dsp> Target platform: MacOS Compiles Faust programs to CLI and CoreAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2cagtk Usage: faust2cagtk [options] [Faust options] <file.dsp> Target platform: MacOS Require: GTK Compiles Faust programs to CoreAudio and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2caqt Usage: faust2caqt [options] [Faust options] <file.dsp> Target platform: MacOS Require: QT Compiles Faust programs to CoreAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -opt native' to activate the best compilation options for the native CPU : -opt generic' to activate the best compilation options for a generic CPU : -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -resample : to resample soundfiles to the audio driver sample rate -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -me : to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow) -debug : to print all the build steps -nodeploy : skip self-contained application generation (using 'macdeployqt') -I include-path : add an include-directory to the generated Qt project for finding ffunction headers and such Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2cmajor Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/cmajor) Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -test : to test the resulting patch with 'cmaj render' -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2comparator Usage: faust2comparator [options] [Faust options] <file.dsp> faust2csound Usage: faust2csound [options] [Faust options] <file.dsp> Target platform: any Require: CSound Dev Kit Compiles a Faust program into a Csound opcode Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2csvplot Usage: faust2csvplot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 5 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) -bs <buffer> : change the buffer size (default is 512 frames) Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. -double : generates code with samples of type 'double'. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2daisy faust2daisy [-patch] [-midi] [-nvoices <num>] [-sr <num>] [-bs <num>] [-source] [Faust options (-vec -vs 8...)] <file.dsp> Compiles Faust programs to Daisy boards (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/daisy) Options: -patch : to compile for 4 ins/outs Patch (knob[1,2,3,4]) -pod : to compile for 2 ins/outs Pod (knob[1,3]) -patchsm : to compile for the Pod.init eurorack module -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -sr <num> : to specify sample rate -bs <num> : to specify buffer size -source : to only create the source folder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2dplug Usage: faust2dplug [options] [Faust options] <file.dsp> Require: Dplug Compiles Faust programs to Dplug plugins Options: -vendor <My Company Name> : -vendorid <FaUs> : -pluginid <PlUg> : -homepage <https://faust.grame.fr/> : -effectType <effectDynamics> : Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2dssi Usage: faust2dssi [options] [Faust options] <file.dsp> Compiles Faust programs to dssi plugins Options: -osc : activates OSC control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2esp32 Usage: faust2esp32 [options] [Faust options] <file.dsp> <file.dsp> faust2esp32 can be used to fully program the ESP32 microncontroller and to generate DSP objects that can be integrated into any ESP32 project (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/esp32) Options: -gramophone : generates for GRAME Gramophone -multi : generate for GRAME Gramophone in multi DSP mode -lib : generates a package containing an object compatible with any ESP32 project -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -main : add a 'main' entry point -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -wm8978, -es8388 or -ac101 : to choose codec driver Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2faustvst Usage: faust2faustvst [options ...] <file.dsp> Require: VST SDK Compiles Faust programs to VST plugins Options: -gui : build the plugin GUI. -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui). -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include FAUSTARCH: specify the location of the Faust VST library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake SDK: specify the location of the VST SDK Default: /usr/local/src/vstsdk SDKSRC: specify the location of the VST SDK sources Default: /usr/local/src/vstsdk/public.sdk/source/vst2.x faust2feh Usage: faust2feh <file.dsp> Compiles Faust programs to SVG and opens them with feh faust2gen Usage: faust2gen [options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to a fausgen~ patch Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events faust2ios Usage: faust2ios [options] [Faust options] <file.dsp> Target platform: iOS Compiles Faust programs to iOS applications Options: -midi : activates MIDI control -osc : activates OSC control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -xcode : to compile and keep the intermediate Xcode project -xcodeproj : to produce the intermediate Xcode project -archive : to generate the archive for Apple Store -32bits : to compile 32 bits only binary -noagc : to deactivate audio automatic gain control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jack Usage: faust2jack [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack Compiles Faust programs to JACK and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackconsole Usage: faust2jackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to CLI and JACK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackrust Usage: faust2jackrust [-source] [Faust options] <file.dsp> Compiles Faust programs to JACK and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jackserver Usage: faust2jackserver [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT (server mode) Options: -httpd : activates HTTP control -osc : activates OSC control -qrcode : activates QR code generation Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jaqt Usage: faust2jaqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -resample : to resample soundfiles to the audio driver sample rate. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2jaqtchain Usage: faust2jaqtchain [options] [Faust options] <file.dsp> Require: Jack, QT Compiles several Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2juce Usage: faust2juce [options] [Faust options] <file.dsp> Require: Juce Compiles Faust programs to JUCE standalones or plugins (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/juce) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -standalone : to produce a standalone project, otherwise a plugin project is generated -vst2sdkdir <folder> : to set directory to VST 2 SDK. -jucemodulesdir <folder> : to set JUCE modules directory to <folder>, such as ~/JUCE/modules -disable-splash-screen : to disable the JUCE splash screen (license is required). -jsynth : to use JUCE polyphonic Synthesizer instead of Faust polyphonic code -llvm : to use the LLVM compilation chain (OSX and Linux for now) -magic : to generate a project using the PluginGuiMagic GUI builder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2ladspa Usage: faust2ladspa [options] [Faust options] <file.dsp> Target platform: Linux Compiles Faust programs to LADSPA plugins Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2linuxunity Usage: faust2linuxunity [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack, Unity Compiles Faust programs to Linux x86_64 libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2lv2 -std=c++11 -fvisibility=hidden -O3 Usage: faust2lv2 [options ...] <file.dsp> Require: QT Compiles Faust programs to lv2 plugins Options: -dyn-manifest : use dynamic manifests (requires LV2 host support). -gui : build the plugin GUI (requires LV2 UI host support). -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -osx : -osx to compile on OSX -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui) -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include/faust FAUSTLIB: specify the location of the Faust LV2 library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake faust2mathdoc Usage: faust2mathdoc [options] <file.dsp> Require: svg2pdf pdflatex breqn Generate a full Faust documentation in a '*-mdoc' top directory Options: -l LANG : LANG is usually a 2-lowercase-letters language name, like en, fr, or it. -utf8 : force file.dsp to be recoded in UTF-8 before being processed faust2max6 Usage: faust2max6 [options] [Faust options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to Max6 externals using double precision samples (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/max-msp) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -soundfile-dynamic : similar to -soundfile, but using the installed libsndfile (so possibly using dynamic link). -opt native|generic : activates the best compilation options for the native or generic CPU. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -us <factor> : upsample the DSP by a factor -ds <factor> : downsample the DSP by a factor -filter <filter> : use a filter for upsampling or downsampling [0..4] -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -mc : to activate multi-channels model -native : to compile for the native CPU (otherwise the 'generic' mode is used by default) -universal : to generate a universal (arm/intel) external -nopatch : to deactivate patch generation -nopost : to disable Faust messages to Max console Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2minimal Usage: faust2minimal [options] [Faust options] <file.dsp> Compiles Faust programs to a minimal executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2netjackconsole Usage: faust2netjackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to NetJack Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2netjackqt Usage: faust2netjackqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to NetJack and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2nodejs Usage: faust2nodejs [driver] [Faust options] <file.dsp> Generate Faust-based nodejs native addons. The generated addons can embed most of the audio engines supported by Faust: ALSA, JACK, CoreAudio, RtAudio, PortAudio, etc. Since faust2nodejs essentially acts as a wrapper to faust2api, it offers the same features than this system (MIDI and OSC support, polyphony, separate effect file, etc.). The following drivers are available: -coreaudio // -alsa // -jack // -portaudio // -rtaudio // -dummy. For example, to create a native nodejs addon with a JACK audio engine, run: faust2nodjs -jack faustFile.dsp The following options are inherited directly from faust2api and can be used with faust2nodejs: Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -source : generates the source of the addon without compiling it -electronv <VERSION> : allows to specify the current version of electron if generating an addon for this framework -debug : prints compilation output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2osxiosunity Usage: faust2osxiosunity [options] [Faust options] <file.dsp> Target platform: MacOSX Require: Unity Compiles Faust programs to OSX/iOS libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -ios : create an iOS static library -universal : generate a 64/32 bits external Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info. faust2paconsole Usage: faust2paconsole [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2paqt Usage: faust2paqt [options] [Faust options] <file.dsp> Require: PortAudio, QT Compiles Faust programs to PortAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2plot Usage: faust2plot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 4 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2portaudiojulia Usage: faust2portaudiojulia [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Julia binary -osc : to activate OSC control on 5000 and 5001 ports -play <num> : to start the 'Julia' runtime with <num> threads and the generated file.jl Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2portaudiorust Usage: faust2portaudiorust [-source] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2raqt Usage: faust2raqt [options] [Faust options] <file.dsp> Require: QT Compiles Faust programs to RtAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rnbo Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rpialsaconsole Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: Alsa Compiles Faust programs to RaspberryPi - alsa console architecture Options: -osc : activates OSC control -httpd : activates HTTP control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2rpinetjackconsole Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: NetJack Compiles Faust programs to RaspberryPi - netjack-console architecture Options: -osc : activates OSC control -httpd : activates HTTP control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2sam Usage: faust2sam [options] [Faust options] <file.dsp> Target platform: ADI SHARC Audio Module board Generates inline Faust objects for the ADI SHARC Audio Module board Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2smartkeyb FAUST2SMARTKEYB - MUSICAL MOBILE APP GENERATOR faust2smartkeyb takes a Faust code as its main argument and convert it into a ready-to-use app for Android or iOS. The only two required arguments of faust2smartkeyb are a Faust file and the target platform (-android or -ios): Usage: faust2smartkeyb [options] [Faust options] <file.dsp> Target platform: iOS, Android Options: -android : generates an Android app -ios : generates an iOS app -osc : activates OSC control -debug : activate debug mode -effect : allow to specify an effect Faust file (e.g., -effect myEffect.dsp) -install : install the app on the connected device (Android only) -nvoices : specify the max number of voices -reuse : reuse the same project source -source : only generate the source (no compilation) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. More information and tutorials at: https://ccrma.stanford.edu/~rmichon/smartKeyboard faust2sndfile Usage: faust2sndfile [Faust options] <file.dsp> Require: libsndfile Process audio files with Faust DSP Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2stratus Usage: faust2stratus [options] [Faust options] <file.dsp> ... [<file.cpp> ...] Target platform: Chaos Audio Stratus pedal Compiles Faust programs for the Chaos Audio Stratus pedal with optional c++ compile for, and effect install to, the pedal Unlike most other faust2xxx scripts, this can also be used to compile effect c++ code that has been constructed elsewhere, or has been modified after being generated by the Faust compiler (e.g. where the algorithm c++ code has been 'tweaked' after generation) The script can be used to build and install multiple different effects in one go Running this script with no options except input files will result in effect libraries built for the platform upon which the script is executed, not for the pedal Options: -nocppc : Do not compile the generated c++ source files -nodocker : Do not use docker for pedal builds even if it is available -stratusbuild : Generates the c++ code locally, then builds the effect library for the Stratus pedal -stratusinstall : Generates the c++ code locally, then builds and installs the effect library for the Stratus pedal Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. the script automatically uses '-i -scn FaustDSP -light -nvi' -O and/or -o can be used, otherwise all output is in the same folder as the corresponding input faust2teensy faust2teensy [-lib] [-midi] [-nvoices <num>] [Faust options (-vec -vs 8...)] <file.dsp> Options: -lib : generates a package containing an object compatible with the Teensy audio library (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/teensy) -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. faust2unity Usage: faust2unity [options] [Faust options] <file.dsp> Target platform: Android, Linux, MacOSX, iOS, Windows Require: Unity Generates a unity package (compressed .unitypackage folder) with all available architecture libraries for faust unity plugin and the C# files required. Use arguments to generate specific architectures (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/unity) Options: -w32 : generates a Windows 32 bits library -w64 : generates a Windows 64 bits library -osx : generates a macOS library -ios : generates an iOS library -android : generates Android libraries (armeabi-v7a and x86). -linux : generates a Linux library -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -source : generates the source files (uncompressed folder) -unpacked : generates an unpacked folder with files organized like the Unity Asset hierarchy. Use this options to add specific files in the unity package (in the Assets folder, then use 'encoderunitypackage <folder>' to compress and pack it. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info. faust2vcvrack faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [Faust options] <file.dsp> Compiles Faust programs to VCV Rack modules (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/vcvrack) -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -source : to only create the source folder -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -version <1|2> : to set the plugin version, 2 by default Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2[...] Tools"},{"location":"manual/tools/#faust2-tools","text":"While in its most primitive form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This description provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. The Faust tools is a set of scripts that take a dsp file as input to generate various output for a lot of architectures and platforms. All the tools names are in the form faust2xx where xx is the target architecture. Use -h or -help to get more information on each specific script options, the supported platforms and possibly the required packages. Additional Faust compiler options (like -vec -lv 0 -I /path/to/lib ) can be given. For scripts that combines Faust and the C++ compiler, you can possibly use the CXXFLAGS environment variable to give additional options to the C++ compiler. Note that some of the tools are somewhat meta tools when they are based on a framework that itself can generate several formats later on. This is the case of the faust2juce script for instance. Note that using -inj <f> option allows to inject a pre-existing C++ file (instead of compiling a dsp file) into the architecture files machinery. Assuming that the C++ file implements a subclass of the base dsp class, the faust2xx scripts can possibly be used to produce a ready-to-use application or plugin that can take profit of all already existing UI and audio architectures. The template-llvm.cpp file that uses libfaust + LLVM backend to dynamically compile a foo.dsp file is an example of this approach. It has be used with the -inj option in faust2xx tools like: faust2cagtk -inj template-llvm.cpp faust2cagtk-llvm.dsp (a dummy DSP) to generate a monophonic faust2cagtk-llvm application. or: faust2cagtk -inj template-llvm.cpp -midi -nvoices 8 faust2cagtk-llvm.dsp to generate a polyphonic (8 voices), MIDI controllable faust2cagtk-llvm application. Note that libfaust and LLVM libraries still have to be added at the link stage, so a -dyn : create libfaust + LLVM backend dynamic version option has been added to the faust2cagtk tool and some others.","title":"faust2[...] Tools"},{"location":"manual/tools/#faust2alqt","text":"Usage: faust2alqt [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa, QT Compiles Faust programs to ALSA and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alqt"},{"location":"manual/tools/#faust2alsa","text":"Usage: faust2alsa [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to ALSA and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alsa"},{"location":"manual/tools/#faust2alsaconsole","text":"Usage: faust2alsaconsole [options] [Faust options] <file.dsp> Target platform: Linux Require: Alsa Compiles Faust programs to CLI and ALSA Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -arch32 : compiles a 32 bits binary -arch64 : compiles a 64 bits binary Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2alsaconsole"},{"location":"manual/tools/#faust2android","text":"Usage: faust2android [options] [Faust options] <file.dsp> Target platform: Android Require: Android SDK Compile a Faust program to an Android app (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/android) Options: -osc : activates OSC control -source : creates an eclipse project of the app in the current directory. -swig : regenerates the C++ and the JAVA interface for the native portion of the app. -faust : only carries out the Faust compilation and install the generated C++ file in the JNI folder. -reuse : preserves build directory and reuse it to speedup compilation. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -install : once compilation is over, installs the generated apk on the Android device connected to the computer -debug : activates verbose output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2android"},{"location":"manual/tools/#faust2androidunity","text":"Usage: faust2androidunity [options] [Faust options] <file1.dsp> [<file2.dsp>] Target platform: Android Unity Require: Android SDK Make sure the ANDROID_HOME environment variable is set to the sdk folder. Creates android libraries (armeabi-v7a and x86) for faust unity plugin. If you need other android architectures, open architecture/unity/Android/Application.mk and modify APP_ABI. See architecture/unity/README.md for more info (also available from the compile folder) Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -android : creates also the c# and JSON files Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2androidunity"},{"location":"manual/tools/#faust2api","text":"Usage: faust2api [options] [Faust options] <file.dsp> faust2api can be used to generate Faust based dsp objects for various platforms (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/api): Output options: -ios : generates an iOS API -android : generates an Android API -coreaudio : generates an OSX CoreAudio API -alsa : generates an ALSA API -jack : generates a JACK API -portaudio : generates a PortAudio API -rtaudio : generates an RTAudio API -of : generates an openFrameworks API -juce : generates a JUCE API -dummy : generates a dummy audio API -teensy : generates a Teensy API -esp32 : generates a ESP32 API Global options: -opt native|generic : activates the best compilation options for the native or generic CPU -nvoices <num> : creates a polyphonic object with <num> voices -effect <effect.dsp> : adds an effect to the polyphonic synth (ignored if -nvoices is not specified) -effect auto : adds an effect (extracted automatically from the dsp file) to the polyphonic synth (ignored if -nvoices is not specified) -nodoc : prevents documentation from being generated -nozip : prevents generated files to be put in a zip file -target <target> : sets a name of the target folder or the zip file. Defaults to \"dsp-faust\" Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. Android specific options: -package : set the JAVA package name (e.g. '-package mypackage' will change the JAVA package name to 'mypackage.DspFaust'). The default package name is 'com.DspFaust.' -soundfile : add built-in Soundfile support to the API Options supported by iOS, CoreAudio, ALSA, JACK, PortAudio, openFrameworks and JUCE -midi : add built-in RtMidi support to the API -osc : add built-in OSC support to the API -soundfile : add built-in Soundfile support to the API JACK specific options -build : build a ready to test binary -dynamic : add libfaust/LLVM dynamic DSP compilation mode","title":"faust2api"},{"location":"manual/tools/#faust2bela","text":"Usage: faust2bela [options] [Faust options] <file.dsp> Target platform: Bela Compiles Faust programs to the BELA board Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Polyphonic mode means MIDI instrument with at least 1 voice. Use no arguments for a simple effect. -gui : activates a self-hosted GUI interface. Requires to have libmicrohttpd and libHTTPDFaust installed. -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI -tobela : to send C++ file into bela, and to run it Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2bela"},{"location":"manual/tools/#faust2bench","text":"Usage: faust2bench [Faust options] <file.dsp> Compiles Faust programs to a benchmark executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2bench"},{"location":"manual/tools/#faust2caconsole","text":"Usage: faust2caconsole [options] [Faust options] <file.dsp> Target platform: MacOS Compiles Faust programs to CLI and CoreAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2caconsole"},{"location":"manual/tools/#faust2cagtk","text":"Usage: faust2cagtk [options] [Faust options] <file.dsp> Target platform: MacOS Require: GTK Compiles Faust programs to CoreAudio and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2cagtk"},{"location":"manual/tools/#faust2caqt","text":"Usage: faust2caqt [options] [Faust options] <file.dsp> Target platform: MacOS Require: QT Compiles Faust programs to CoreAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -opt native' to activate the best compilation options for the native CPU : -opt generic' to activate the best compilation options for a generic CPU : -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -resample : to resample soundfiles to the audio driver sample rate -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -me : to catch math computation exceptions (floating point exceptions and integer div-by-zero or overflow) -debug : to print all the build steps -nodeploy : skip self-contained application generation (using 'macdeployqt') -I include-path : add an include-directory to the generated Qt project for finding ffunction headers and such Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2caqt"},{"location":"manual/tools/#faust2cmajor","text":"Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/cmajor) Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -test : to test the resulting patch with 'cmaj render' -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2cmajor"},{"location":"manual/tools/#faust2comparator","text":"Usage: faust2comparator [options] [Faust options] <file.dsp>","title":"faust2comparator"},{"location":"manual/tools/#faust2csound","text":"Usage: faust2csound [options] [Faust options] <file.dsp> Target platform: any Require: CSound Dev Kit Compiles a Faust program into a Csound opcode Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2csound"},{"location":"manual/tools/#faust2csvplot","text":"Usage: faust2csvplot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 5 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) -bs <buffer> : change the buffer size (default is 512 frames) Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. -double : generates code with samples of type 'double'. -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2csvplot"},{"location":"manual/tools/#faust2daisy","text":"faust2daisy [-patch] [-midi] [-nvoices <num>] [-sr <num>] [-bs <num>] [-source] [Faust options (-vec -vs 8...)] <file.dsp> Compiles Faust programs to Daisy boards (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/daisy) Options: -patch : to compile for 4 ins/outs Patch (knob[1,2,3,4]) -pod : to compile for 2 ins/outs Pod (knob[1,3]) -patchsm : to compile for the Pod.init eurorack module -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -sr <num> : to specify sample rate -bs <num> : to specify buffer size -source : to only create the source folder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2daisy"},{"location":"manual/tools/#faust2dplug","text":"Usage: faust2dplug [options] [Faust options] <file.dsp> Require: Dplug Compiles Faust programs to Dplug plugins Options: -vendor <My Company Name> : -vendorid <FaUs> : -pluginid <PlUg> : -homepage <https://faust.grame.fr/> : -effectType <effectDynamics> : Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2dplug"},{"location":"manual/tools/#faust2dssi","text":"Usage: faust2dssi [options] [Faust options] <file.dsp> Compiles Faust programs to dssi plugins Options: -osc : activates OSC control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2dssi"},{"location":"manual/tools/#faust2esp32","text":"Usage: faust2esp32 [options] [Faust options] <file.dsp> <file.dsp> faust2esp32 can be used to fully program the ESP32 microncontroller and to generate DSP objects that can be integrated into any ESP32 project (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/esp32) Options: -gramophone : generates for GRAME Gramophone -multi : generate for GRAME Gramophone in multi DSP mode -lib : generates a package containing an object compatible with any ESP32 project -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -main : add a 'main' entry point -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -wm8978, -es8388 or -ac101 : to choose codec driver Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2esp32"},{"location":"manual/tools/#faust2faustvst","text":"Usage: faust2faustvst [options ...] <file.dsp> Require: VST SDK Compiles Faust programs to VST plugins Options: -gui : build the plugin GUI. -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui). -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include FAUSTARCH: specify the location of the Faust VST library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake SDK: specify the location of the VST SDK Default: /usr/local/src/vstsdk SDKSRC: specify the location of the VST SDK sources Default: /usr/local/src/vstsdk/public.sdk/source/vst2.x","title":"faust2faustvst"},{"location":"manual/tools/#faust2feh","text":"Usage: faust2feh <file.dsp> Compiles Faust programs to SVG and opens them with feh","title":"faust2feh"},{"location":"manual/tools/#faust2gen","text":"Usage: faust2gen [options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to a fausgen~ patch Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events","title":"faust2gen"},{"location":"manual/tools/#faust2ios","text":"Usage: faust2ios [options] [Faust options] <file.dsp> Target platform: iOS Compiles Faust programs to iOS applications Options: -midi : activates MIDI control -osc : activates OSC control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -xcode : to compile and keep the intermediate Xcode project -xcodeproj : to produce the intermediate Xcode project -archive : to generate the archive for Apple Store -32bits : to compile 32 bits only binary -noagc : to deactivate audio automatic gain control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2ios"},{"location":"manual/tools/#faust2jack","text":"Usage: faust2jack [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack Compiles Faust programs to JACK and GTK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -dyn : create libfaust + LLVM backend dynamic version -resample : to resample soundfiles to the audio driver sample rate. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jack"},{"location":"manual/tools/#faust2jackconsole","text":"Usage: faust2jackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to CLI and JACK Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackconsole"},{"location":"manual/tools/#faust2jackrust","text":"Usage: faust2jackrust [-source] [Faust options] <file.dsp> Compiles Faust programs to JACK and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackrust"},{"location":"manual/tools/#faust2jackserver","text":"Usage: faust2jackserver [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT (server mode) Options: -httpd : activates HTTP control -osc : activates OSC control -qrcode : activates QR code generation Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jackserver"},{"location":"manual/tools/#faust2jaqt","text":"Usage: faust2jaqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -preset <directory> : add a preset manager on top of GUI and save the preset files in the given directory -preset auto : add a preset manager on top of GUI and save the preset files in a system temporary directory -resample : to resample soundfiles to the audio driver sample rate. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jaqt"},{"location":"manual/tools/#faust2jaqtchain","text":"Usage: faust2jaqtchain [options] [Faust options] <file.dsp> Require: Jack, QT Compiles several Faust programs to JACK and QT Options: -httpd : activates HTTP control -osc : activates OSC control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2jaqtchain"},{"location":"manual/tools/#faust2juce","text":"Usage: faust2juce [options] [Faust options] <file.dsp> Require: Juce Compiles Faust programs to JUCE standalones or plugins (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/juce) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -standalone : to produce a standalone project, otherwise a plugin project is generated -vst2sdkdir <folder> : to set directory to VST 2 SDK. -jucemodulesdir <folder> : to set JUCE modules directory to <folder>, such as ~/JUCE/modules -disable-splash-screen : to disable the JUCE splash screen (license is required). -jsynth : to use JUCE polyphonic Synthesizer instead of Faust polyphonic code -llvm : to use the LLVM compilation chain (OSX and Linux for now) -magic : to generate a project using the PluginGuiMagic GUI builder Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2juce"},{"location":"manual/tools/#faust2ladspa","text":"Usage: faust2ladspa [options] [Faust options] <file.dsp> Target platform: Linux Compiles Faust programs to LADSPA plugins Options: -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2ladspa"},{"location":"manual/tools/#faust2linuxunity","text":"Usage: faust2linuxunity [options] [Faust options] <file.dsp> Target platform: Linux Require: Jack, Unity Compiles Faust programs to Linux x86_64 libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2linuxunity"},{"location":"manual/tools/#faust2lv2","text":"-std=c++11 -fvisibility=hidden -O3 Usage: faust2lv2 [options ...] <file.dsp> Require: QT Compiles Faust programs to lv2 plugins Options: -dyn-manifest : use dynamic manifests (requires LV2 host support). -gui : build the plugin GUI (requires LV2 UI host support). -keep : retain the build directory. -nometa : ignore metadata (author information etc.) from the Faust source -nomidicc : plugin doesn't process MIDI control data. -notuning : disable the tuning control (instruments only). -novoicectrls : no extra polyphony/tuning controls on GUI (instruments only) -nvoices N : number of synth voices (instruments only; arg must be an integer) -osx : -osx to compile on OSX -qt4, -qt5 : select the GUI toolkit (requires Qt4/5; implies -gui) -style S : select the stylesheet (arg must be Default, Blue, Grey or Salmon). Environment variables: FAUSTINC: specify the location of the Faust include directory Default: /usr/local/include/faust FAUSTLIB: specify the location of the Faust LV2 library files Default: /usr/local/share/faust QMAKE: specify the location of the qmake binary Default: qmake","title":"faust2lv2"},{"location":"manual/tools/#faust2mathdoc","text":"Usage: faust2mathdoc [options] <file.dsp> Require: svg2pdf pdflatex breqn Generate a full Faust documentation in a '*-mdoc' top directory Options: -l LANG : LANG is usually a 2-lowercase-letters language name, like en, fr, or it. -utf8 : force file.dsp to be recoded in UTF-8 before being processed","title":"faust2mathdoc"},{"location":"manual/tools/#faust2max6","text":"Usage: faust2max6 [options] [Faust options] <file.dsp> Require: Max/MSP SDK Compiles Faust programs to Max6 externals using double precision samples (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/max-msp) Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -soundfile-dynamic : similar to -soundfile, but using the installed libsndfile (so possibly using dynamic link). -opt native|generic : activates the best compilation options for the native or generic CPU. -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -us <factor> : upsample the DSP by a factor -ds <factor> : downsample the DSP by a factor -filter <filter> : use a filter for upsampling or downsampling [0..4] -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -mc : to activate multi-channels model -native : to compile for the native CPU (otherwise the 'generic' mode is used by default) -universal : to generate a universal (arm/intel) external -nopatch : to deactivate patch generation -nopost : to disable Faust messages to Max console Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2max6"},{"location":"manual/tools/#faust2minimal","text":"Usage: faust2minimal [options] [Faust options] <file.dsp> Compiles Faust programs to a minimal executable Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2minimal"},{"location":"manual/tools/#faust2netjackconsole","text":"Usage: faust2netjackconsole [options] [Faust options] <file.dsp> Require: Jack Compiles Faust programs to NetJack Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2netjackconsole"},{"location":"manual/tools/#faust2netjackqt","text":"Usage: faust2netjackqt [options] [Faust options] <file.dsp> Require: Jack, QT Compiles Faust programs to NetJack and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2netjackqt"},{"location":"manual/tools/#faust2nodejs","text":"Usage: faust2nodejs [driver] [Faust options] <file.dsp> Generate Faust-based nodejs native addons. The generated addons can embed most of the audio engines supported by Faust: ALSA, JACK, CoreAudio, RtAudio, PortAudio, etc. Since faust2nodejs essentially acts as a wrapper to faust2api, it offers the same features than this system (MIDI and OSC support, polyphony, separate effect file, etc.). The following drivers are available: -coreaudio // -alsa // -jack // -portaudio // -rtaudio // -dummy. For example, to create a native nodejs addon with a JACK audio engine, run: faust2nodjs -jack faustFile.dsp The following options are inherited directly from faust2api and can be used with faust2nodejs: Options: -osc : activates OSC control -midi : activates MIDI control -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -source : generates the source of the addon without compiling it -electronv <VERSION> : allows to specify the current version of electron if generating an addon for this framework -debug : prints compilation output Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2nodejs"},{"location":"manual/tools/#faust2osxiosunity","text":"Usage: faust2osxiosunity [options] [Faust options] <file.dsp> Target platform: MacOSX Require: Unity Compiles Faust programs to OSX/iOS libraries suitable for the Unity environment Options: -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -ios : create an iOS static library -universal : generate a 64/32 bits external Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info.","title":"faust2osxiosunity"},{"location":"manual/tools/#faust2paconsole","text":"Usage: faust2paconsole [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2paconsole"},{"location":"manual/tools/#faust2paqt","text":"Usage: faust2paqt [options] [Faust options] <file.dsp> Require: PortAudio, QT Compiles Faust programs to PortAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2paqt"},{"location":"manual/tools/#faust2plot","text":"Usage: faust2plot [options] [Faust options] <file.dsp> Compiles Faust programs to plotters, additional control parameters depend of the DSP, the following 4 options are given at runtime: -dyn : create libfaust + LLVM backend dynamic version -s <n> : start at the sample number <n> (default is 0) -n <n> : render <n> samples (default is 16) -r <rate> : change the sample rate (default is 44100 Hz) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2plot"},{"location":"manual/tools/#faust2portaudiojulia","text":"Usage: faust2portaudiojulia [options] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Julia binary -osc : to activate OSC control on 5000 and 5001 ports -play <num> : to start the 'Julia' runtime with <num> threads and the generated file.jl Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2portaudiojulia"},{"location":"manual/tools/#faust2portaudiorust","text":"Usage: faust2portaudiorust [-source] [Faust options] <file.dsp> Require: PortAudio Compiles Faust programs to PortAudio and Rust binary Options: -source : only generates the source project. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2portaudiorust"},{"location":"manual/tools/#faust2raqt","text":"Usage: faust2raqt [options] [Faust options] <file.dsp> Require: QT Compiles Faust programs to RtAudio and QT Options: -httpd : activates HTTP control -osc : activates OSC control -midi : activates MIDI control -qrcode : activates QR code generation -poly : produces a polyphonic DSP, ready to be used with MIDI events -nodeploy : skip self-contained application generation (using 'macdeployqt') Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2raqt"},{"location":"manual/tools/#faust2rnbo","text":"Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rnbo"},{"location":"manual/tools/#faust2rpialsaconsole","text":"Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: Alsa Compiles Faust programs to RaspberryPi - alsa console architecture Options: -osc : activates OSC control -httpd : activates HTTP control -arch32 : generates a 32 bit architecture. -arch64 : generates a 64 bit architecture. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rpialsaconsole"},{"location":"manual/tools/#faust2rpinetjackconsole","text":"Usage: faust2rpialsaconsole [options] [Faust options] <file.dsp> Target platform: RaspberryPi Require: NetJack Compiles Faust programs to RaspberryPi - netjack-console architecture Options: -osc : activates OSC control -httpd : activates HTTP control Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2rpinetjackconsole"},{"location":"manual/tools/#faust2sam","text":"Usage: faust2sam [options] [Faust options] <file.dsp> Target platform: ADI SHARC Audio Module board Generates inline Faust objects for the ADI SHARC Audio Module board Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2sam"},{"location":"manual/tools/#faust2smartkeyb","text":"FAUST2SMARTKEYB - MUSICAL MOBILE APP GENERATOR faust2smartkeyb takes a Faust code as its main argument and convert it into a ready-to-use app for Android or iOS. The only two required arguments of faust2smartkeyb are a Faust file and the target platform (-android or -ios): Usage: faust2smartkeyb [options] [Faust options] <file.dsp> Target platform: iOS, Android Options: -android : generates an Android app -ios : generates an iOS app -osc : activates OSC control -debug : activate debug mode -effect : allow to specify an effect Faust file (e.g., -effect myEffect.dsp) -install : install the app on the connected device (Android only) -nvoices : specify the max number of voices -reuse : reuse the same project source -source : only generate the source (no compilation) Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. More information and tutorials at: https://ccrma.stanford.edu/~rmichon/smartKeyboard","title":"faust2smartkeyb"},{"location":"manual/tools/#faust2sndfile","text":"Usage: faust2sndfile [Faust options] <file.dsp> Require: libsndfile Process audio files with Faust DSP Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2sndfile"},{"location":"manual/tools/#faust2stratus","text":"Usage: faust2stratus [options] [Faust options] <file.dsp> ... [<file.cpp> ...] Target platform: Chaos Audio Stratus pedal Compiles Faust programs for the Chaos Audio Stratus pedal with optional c++ compile for, and effect install to, the pedal Unlike most other faust2xxx scripts, this can also be used to compile effect c++ code that has been constructed elsewhere, or has been modified after being generated by the Faust compiler (e.g. where the algorithm c++ code has been 'tweaked' after generation) The script can be used to build and install multiple different effects in one go Running this script with no options except input files will result in effect libraries built for the platform upon which the script is executed, not for the pedal Options: -nocppc : Do not compile the generated c++ source files -nodocker : Do not use docker for pedal builds even if it is available -stratusbuild : Generates the c++ code locally, then builds the effect library for the Stratus pedal -stratusinstall : Generates the c++ code locally, then builds and installs the effect library for the Stratus pedal Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. the script automatically uses '-i -scn FaustDSP -light -nvi' -O and/or -o can be used, otherwise all output is in the same folder as the corresponding input","title":"faust2stratus"},{"location":"manual/tools/#faust2teensy","text":"faust2teensy [-lib] [-midi] [-nvoices <num>] [Faust options (-vec -vs 8...)] <file.dsp> Options: -lib : generates a package containing an object compatible with the Teensy audio library (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/teensy) -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2teensy"},{"location":"manual/tools/#faust2unity","text":"Usage: faust2unity [options] [Faust options] <file.dsp> Target platform: Android, Linux, MacOSX, iOS, Windows Require: Unity Generates a unity package (compressed .unitypackage folder) with all available architecture libraries for faust unity plugin and the C# files required. Use arguments to generate specific architectures (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/unity) Options: -w32 : generates a Windows 32 bits library -w64 : generates a Windows 64 bits library -osx : generates a macOS library -ios : generates an iOS library -android : generates Android libraries (armeabi-v7a and x86). -linux : generates a Linux library -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -source : generates the source files (uncompressed folder) -unpacked : generates an unpacked folder with files organized like the Unity Asset hierarchy. Use this options to add specific files in the unity package (in the Assets folder, then use 'encoderunitypackage <folder>' to compress and pack it. Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. See architecture/unity/README.md for more info.","title":"faust2unity"},{"location":"manual/tools/#faust2vcvrack","text":"faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [Faust options] <file.dsp> Compiles Faust programs to VCV Rack modules (see https://github.com/grame-cncm/faust/tree/master-dev/architecture/vcvrack) -soundfile : when compiling a DSP using the 'soundfile' primitive, add required resources -source : to only create the source folder -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -version <1|2> : to set the plugin version, 2 by default Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation.","title":"faust2vcvrack"},{"location":"qreference/1-introduction/","text":"Introduction Faust ( Functional Audio Stream ) is a functional programming language specifically designed for real-time signal processing and synthesis. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards. Design Principles Various principles have guided the design of Faust : Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled, not interpreted. The compiler translates Faust programs into equivalent C++ programs taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations ( : , ~ <: :> ). Thanks to the notion of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plugin formats without any change to the Faust code. Signal Processor Semantic A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . Faust considers two type of signals: **integer signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Z}\\)) and **floating point signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Q}\\)) Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0. The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produce an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"1 introduction"},{"location":"qreference/1-introduction/#introduction","text":"Faust ( Functional Audio Stream ) is a functional programming language specifically designed for real-time signal processing and synthesis. Faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards.","title":"Introduction"},{"location":"qreference/1-introduction/#design-principles","text":"Various principles have guided the design of Faust : Faust is a specification language . It aims at providing an adequate notation to describe signal processors from a mathematical point of view. Faust is, as much as possible, free from implementation details. Faust programs are fully compiled, not interpreted. The compiler translates Faust programs into equivalent C++ programs taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. The semantic of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be semantically driven . Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance. Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: functional programming and algebraic block-diagrams . The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a block-diagram algebra of five composition operations ( : , ~ <: :> ). Thanks to the notion of architecture , Faust programs can be easily deployed on a large variety of audio platforms and plugin formats without any change to the Faust code.","title":"Design Principles"},{"location":"qreference/1-introduction/#signal-processor-semantic","text":"A Faust program describes a signal processor . The role of a signal processor is to transforms a (possibly empty) group of input signals in order to produce a (possibly empty) group of output signals . Most audio equipments can be modeled as signal processors . They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. More precisely : A signal s is a discrete function of time s:\\mathbb{Z}\\rightarrow\\mathbb{R} . Faust considers two type of signals: **integer signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Z}\\)) and **floating point signals** (\\(s:\\mathbb{Z}\\rightarrow\\mathbb{Q}\\)) Exchanges with the outside world are, by convention, made using floating point signals. The full range is represented by sample values between -1.0 and +1.0. The value of a signal s at time t is written s(t) . The values of signals are usually needed starting from time 0 . But to take into account delay operations , negative times are possible and are always mapped to zeros. Therefore for any Faust signal s we have \\forall t<0, s(t)=0 . In operational terms this corresponds to assuming that all delay lines are signals initialized with 0 s. The set of all possible signals is \\mathbb{S}=\\mathbb{Z}\\rightarrow\\mathbb{R} . A group of n signals (a n -tuple of signals) is written (s_{1},\\ldots,s_{n})\\in \\mathbb{S}^{n} . The empty tuple , single element of \\mathbb{S}^{0} is notated () . A signal processors p , is a function from n -tuples of signals to m -tuples of signals p:\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} . The set \\mathbb{P}=\\bigcup_{n,m}\\mathbb{S}^{n}\\rightarrow\\mathbb{S}^{m} is the set of all possible signal processors. As an example, let's express the semantic of the Faust primitive + . Like any Faust expression, it is a signal processor. Its signature is \\mathbb{S}^{2}\\rightarrow\\mathbb{S} . It takes two input signals X_0 and X_1 and produce an output signal Y such that Y(t) = X_0(t)+X_1(t) . Numbers are signal processors too. For example the number 3 has signature \\mathbb{S}^{0}\\rightarrow\\mathbb{S} . It takes no input signals and produce an output signal Y such that Y(t) = 3 .","title":"Signal Processor Semantic"},{"location":"qreference/10-poly/","text":"Polyphonic support Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described\\footnote{Like sympathetic strings resonance in a physical model of a piano for instance.}. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special {\\it polyphonic instrument aware} architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping. Polyphonic ready DSP code By convention Faust architecture files with polyphonic capabilities expect to find control parameters named {\\it freq}, {\\it gain} and {\\it gate}. The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the {\\it freq} parameter (which should be a frequency) will be automatically computed from MIDI note numbers, {\\it gain} (which should be a value between 0 and 1) from velocity and {\\it gate} from {\\it keyon/keyoff} events. Thus, gate can be used as a trigger signal for any envelope generator, etc. Using the mydsp_poly class The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the {\\it faust/dsp/poly-dsp.h} file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp type of objects, manage dynamic voice allocations, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold. as a sub-class of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global {\\it Polyphonic} tabgroup. The first tab contains a {\\it Voices} group, a master like component used to change parameters on all voices at the same time, with a {\\it Panic} button to be used to stop running voices\\footnote{An internal control grouping mechanism has been defined to automatically dispatch a user interface action done on the master component on all linked voices, except for the {\\it freq}, {\\it gain} and {\\it gate} controls.}, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP (Figure fig:poly-ui ). Extended multi-voices GUI interface The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI, httpdUI, etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /0x00/0x00/vol f -10.0 /0x00/0x00/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/0x00/0x00/pan f 0.0 /Polyphonic/Voices/0x00/0x00/vol f -10.0 ... /Polyphonic/Voice1/0x00/0x00/vol f -10.0 /Polyphonic/Voice1/0x00/0x00/pan f 0.0 ... /Polyphonic/Voice2/0x00/0x00/vol f -10.0 /Polyphonic/Voice2/0x00/0x00/pan f 0.0 ... The polyphonic instrument allocation takes the DSP to be used for one voice\\footnote{The DSP object will be automatically cloned in the mydsp_poly class to create all needed voices.}, the desired number of voices, the {\\it dynamic voice allocation} state\\footnote{Voices may be always running, or dynamically started/stopped in case of MIDI control.}, and the {\\it group} state which controls if separated voices are displayed or not (Figure fig:poly-ui ): DSP = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: DSP = new mydsp_poly(dsp, 8, false, true); Controlling the polyphonic instrument The mydsp_poly class is also ready for MIDI control and can react to {\\it keyon/keyoff} and {\\it pitchwheel} messages. Other MIDI control parameters can directly be added in the DSP source code. Deploying the polyphonic instrument Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter\\footnote{-nvoices parameter takes precedence over the metadata value.}. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions. Polyphonic instrument with a global output effect Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is not a good idea since it would be instantiated for each voice which would be very inefficient. This is a typical use case for the dsp_sequencer class previously presented with the polyphonic DSP connected in sequence with a unique global effect (Figure fig:poly-ui-effect ). faustcaqt inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. A dsp_sequencer object will be created to combine the polyphonic instrument in sequence with the single output effect. Polyphonic ready {\\it faust2xx} scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready to use DSP. Polyphonic instrument with output effect GUI interface: left tab window shows the polyphonic instrument with its Integrated global output effect Starting with the 2.5.17 version, a new convention has been defined to directly integrate a global output effect inside the DSP source code itself. The effect has simply to be declared in a effect = effect_code; line in the source. Here is a more complete source code example: import(\"stdfaust.lib\"); process = pm.clarinet_ui_MIDI <: _,_; effect = dm.freeverb_demo; The architecture script then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them with the dsp_sequencer object. A new auto parameter to be used in {\\it faust2xx} script has been defined, as in the faustcaqt inst.dsp -effect auto line for example. Integrated global output effect and libfaust For developers using the libfaust library, an helper file named faust/dsp/poly-dsp-tools.h is available. It defines an API to automatically create a polyphonic instrument with an output effect, starting from a DSP source file using the effect effect = ... convention. The function createPolyDSPFactoryFromString or \\ createPolyDSPFactoryFromFile must be used to create the polyphonic DSP factory. Next, the createPolyDSPInstance function creates the polyphonic object (a subclass of dsp_poly type) to be used like a regular dsp type object. After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writePolyDSPFactoryToIRFile allows to save the polyphonic factory LLVM IR (in textual format) in a file, writePolyDSPFactoryToBitcodeFile allows to save the polyphonic factory LLVM IR (in binary format) in a file, writePolyDSPFactoryToMachineFile allows to save the polyphonic factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readPolyDSPFactoryFromIRFile allows to create a polyphonic DSP factory from a file containing the LLVM IR (in textual format), readPolyDSPFactoryFromBitcodeFile allows to create a polyphonic factory from a file containing the LLVM IR (in binary format), readPolyDSPFactoryFromMachineFile allows to create a polyphonic DSP factory from a file containing the executable machine code.","title":"10 poly"},{"location":"qreference/10-poly/#polyphonic-support","text":"Directly programing polyphonic instruments in Faust is perfectly possible. It is also needed if very complex signal interaction between the different voices have to be described\\footnote{Like sympathetic strings resonance in a physical model of a piano for instance.}. But since all voices would always be computed, this approach could be too CPU costly for simpler or more limited needs. In this case describing a single voice in a Faust DSP program and externally combining several of them with a special {\\it polyphonic instrument aware} architecture file is a better solution. Moreover, this special architecture file takes care of dynamic voice allocations and control MIDI messages decoding and mapping.","title":"Polyphonic support"},{"location":"qreference/10-poly/#polyphonic-ready-dsp-code","text":"By convention Faust architecture files with polyphonic capabilities expect to find control parameters named {\\it freq}, {\\it gain} and {\\it gate}. The metadata declare nvoices \"8\"; kind of line with a desired value of voices can be added in the source code. In the case of MIDI control, the {\\it freq} parameter (which should be a frequency) will be automatically computed from MIDI note numbers, {\\it gain} (which should be a value between 0 and 1) from velocity and {\\it gate} from {\\it keyon/keyoff} events. Thus, gate can be used as a trigger signal for any envelope generator, etc.","title":"Polyphonic ready DSP code"},{"location":"qreference/10-poly/#using-the-mydsp_poly-class","text":"The single voice has to be described by a Faust DSP program, the mydsp_poly class is then used to combine several voices and create a polyphonic ready DSP: the {\\it faust/dsp/poly-dsp.h} file contains the definition of the mydsp_poly class used to wrap the DSP voice into the polyphonic architecture. This class maintains an array of dsp type of objects, manage dynamic voice allocations, control MIDI messages decoding and mapping, mixing of all running voices, and stopping a voice when its output level decreases below a given threshold. as a sub-class of DSP, the mydsp_poly class redefines the buildUserInterface method. By convention all allocated voices are grouped in a global {\\it Polyphonic} tabgroup. The first tab contains a {\\it Voices} group, a master like component used to change parameters on all voices at the same time, with a {\\it Panic} button to be used to stop running voices\\footnote{An internal control grouping mechanism has been defined to automatically dispatch a user interface action done on the master component on all linked voices, except for the {\\it freq}, {\\it gain} and {\\it gate} controls.}, followed by one tab for each voice. Graphical User Interface components will then reflect the multi-voices structure of the new polyphonic DSP (Figure fig:poly-ui ). Extended multi-voices GUI interface The resulting polyphonic DSP object can be used as usual, connected with the needed audio driver, and possibly other UI control objects like OSCUI, httpdUI, etc. Having this new UI hierarchical view allows complete OSC control of each single voice and their control parameters, but also all voices using the master component. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /0x00/0x00/vol f -10.0 /0x00/0x00/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/0x00/0x00/pan f 0.0 /Polyphonic/Voices/0x00/0x00/vol f -10.0 ... /Polyphonic/Voice1/0x00/0x00/vol f -10.0 /Polyphonic/Voice1/0x00/0x00/pan f 0.0 ... /Polyphonic/Voice2/0x00/0x00/vol f -10.0 /Polyphonic/Voice2/0x00/0x00/pan f 0.0 ... The polyphonic instrument allocation takes the DSP to be used for one voice\\footnote{The DSP object will be automatically cloned in the mydsp_poly class to create all needed voices.}, the desired number of voices, the {\\it dynamic voice allocation} state\\footnote{Voices may be always running, or dynamically started/stopped in case of MIDI control.}, and the {\\it group} state which controls if separated voices are displayed or not (Figure fig:poly-ui ): DSP = new mydsp_poly(dsp, 2, true, true); With the following code, note that a polyphonic instrument may be used outside of a MIDI control context, so that all voices will be always running and possibly controlled with OSC messages for instance: DSP = new mydsp_poly(dsp, 8, false, true);","title":"Using the mydsp_poly class"},{"location":"qreference/10-poly/#controlling-the-polyphonic-instrument","text":"The mydsp_poly class is also ready for MIDI control and can react to {\\it keyon/keyoff} and {\\it pitchwheel} messages. Other MIDI control parameters can directly be added in the DSP source code.","title":"Controlling the polyphonic instrument"},{"location":"qreference/10-poly/#deploying-the-polyphonic-instrument","text":"Several architecture files and associated scripts have been updated to handle polyphonic instruments: As an example on OSX, the script faust2caqt foo.dsp can be used to create a polyphonic CoreAudio/QT application. The desired number of voices is either declared in a nvoices metadata or changed with the -nvoices num additional parameter\\footnote{-nvoices parameter takes precedence over the metadata value.}. MIDI control is activated using the -midi parameter. The number of allocated voices can possibly be changed at runtime using the -nvoices parameter to change the default value (so using ./foo -nvoices 16 for instance). Several other scripts have been adapted using the same conventions.","title":"Deploying the polyphonic instrument"},{"location":"qreference/10-poly/#polyphonic-instrument-with-a-global-output-effect","text":"Polyphonic instruments may be used with an output effect. Putting that effect in the main Faust code is not a good idea since it would be instantiated for each voice which would be very inefficient. This is a typical use case for the dsp_sequencer class previously presented with the polyphonic DSP connected in sequence with a unique global effect (Figure fig:poly-ui-effect ). faustcaqt inst.dsp -effect effect.dsp with inst.dsp and effect.dsp in the same folder, and the number of outputs of the instrument matching the number of inputs of the effect, has to be used. A dsp_sequencer object will be created to combine the polyphonic instrument in sequence with the single output effect. Polyphonic ready {\\it faust2xx} scripts will then compile the polyphonic instrument and the effect, combine them in sequence, and create a ready to use DSP. Polyphonic instrument with output effect GUI interface: left tab window shows the polyphonic instrument with its","title":"Polyphonic instrument with a global output effect"},{"location":"qreference/10-poly/#integrated-global-output-effect","text":"Starting with the 2.5.17 version, a new convention has been defined to directly integrate a global output effect inside the DSP source code itself. The effect has simply to be declared in a effect = effect_code; line in the source. Here is a more complete source code example: import(\"stdfaust.lib\"); process = pm.clarinet_ui_MIDI <: _,_; effect = dm.freeverb_demo; The architecture script then separates the instrument description itself (the process = ... definition) from the effect definition (the effect = ... definition), possibly adapts the instrument number of outputs to the effect number of inputs, compiles each part separately, and combines them with the dsp_sequencer object. A new auto parameter to be used in {\\it faust2xx} script has been defined, as in the faustcaqt inst.dsp -effect auto line for example.","title":"Integrated global output effect"},{"location":"qreference/10-poly/#integrated-global-output-effect-and-libfaust","text":"For developers using the libfaust library, an helper file named faust/dsp/poly-dsp-tools.h is available. It defines an API to automatically create a polyphonic instrument with an output effect, starting from a DSP source file using the effect effect = ... convention. The function createPolyDSPFactoryFromString or \\ createPolyDSPFactoryFromFile must be used to create the polyphonic DSP factory. Next, the createPolyDSPInstance function creates the polyphonic object (a subclass of dsp_poly type) to be used like a regular dsp type object. After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writePolyDSPFactoryToIRFile allows to save the polyphonic factory LLVM IR (in textual format) in a file, writePolyDSPFactoryToBitcodeFile allows to save the polyphonic factory LLVM IR (in binary format) in a file, writePolyDSPFactoryToMachineFile allows to save the polyphonic factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readPolyDSPFactoryFromIRFile allows to create a polyphonic DSP factory from a file containing the LLVM IR (in textual format), readPolyDSPFactoryFromBitcodeFile allows to create a polyphonic factory from a file containing the LLVM IR (in binary format), readPolyDSPFactoryFromMachineFile allows to create a polyphonic DSP factory from a file containing the executable machine code.","title":"Integrated global output effect and libfaust"},{"location":"qreference/11-codegeneration/","text":"Controlling the code generation Several options of the Faust compiler allow to control the generated C++ code. By default the computations are done sample by sample in a single loop. But the compiler can also generate vector and parallel code. Vector code generation Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 simple precision floating point numbers thus leading to a theoretical speedup of \\times4 . Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular too complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: // Root Mean Square of n consecutive samples RMS(n) = square : mean(n) : sqrt; // Square of a signal square(x) = x * x; // Mean of n consecutive samples of a signal // (uses fixpoint to avoid the accumulation of // rounding errors) mean(n) = float2fix : integrate(n) : fix2float : /(n); // Sliding sum of n consecutive samples integrate(n,x) = x - x@n : +~_; // Convertion between float and fix point float2fix(x) = int(x*(1<<20)); fix2float(x) = float(x)/(1<<20); // Root Mean Square of 1000 consecutive samples process = RMS(1000); The compute() method generated in scalar mode is the following: virtual void compute (int count, float** input, float** output) { float* input0 = input[0]; float* output0 = output[0]; for (int i=0; i<count; i++) { float fTemp0 = input0[i]; int iTemp1 = int(1048576*fTemp0*fTemp0); iVec0[IOTA&1023] = iTemp1; iRec0[0] = ((iVec0[IOTA&1023] + iRec0[1]) - iVec0[(IOTA-1000)&1023]); output0[i] = sqrtf(9.536744e-10f * float(iRec0[0])); // post processing iRec0[1] = iRec0[0]; IOTA = IOTA+1; } The -vec option leads to the following reorganization of the code: virtual void compute (int fullcount, float** input, float** output) { int iRec0_tmp[32+4]; int* iRec0 = &iRec0_tmp[4]; for (int index=0; index<fullcount; index+=32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* output0 = &output[0][index]; for (int i=0; i<4; i++) iRec0_tmp[i]=iRec0_perm[i]; // SECTION : 1 for (int i=0; i<count; i++) { iYec0[(iYec0_idx+i)&2047] = int(1048576*input0[i]*input0[i]); } // SECTION : 2 for (int i=0; i<count; i++) { iRec0[i] = ((iYec0[i] + iRec0[i-1]) - iYec0[(iYec0_idx+i-1000)&2047]); } // SECTION : 3 for (int i=0; i<count; i++) { output0[i] = sqrtf((9.536744e-10f * float(iRec0[i]))); } // SECTION : 4 iYec0_idx = (iYec0_idx+count)&2047; for (int i=0; i<4; i++) iRec0_perm[i]=iRec0_tmp[count+i]; } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. Using Intel icc 11.0, with the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2, the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! Faust 's stack of code generators The vector code generation is built on top of the scalar code generation (see figure fig:stack ). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. It applies some simple rules for that. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see Figure fig:loopgraph ). This graph is stored in the klass object and a topological sort is applied to it before printing the code. The result of the -vec option is a directed acyclic graph (DAG) of small computation loops Parallel code generation The parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option. It implies the -vec options as the parallel code generation is built on top of the vector code generation. The OpenMP code generator OpenMP is based on a fork-join model The --openMP (or -omp ) option given to the Faust compiler will insert appropriate OpenMP directives in the C++ code. OpenMP (http://wwww.openmp.org) is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure fig:openmp ). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region a team of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel team until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by // every thread of the parallel team ... In order not to have every thread doing redundantly the exact same work, OpemMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ... Adding OpenMP directives As said before the parallel code generation is built on top of the vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 in the DAG of Figure fig:loopgraph ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code } Example of parallel OpenMP code To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; two filters in parallel connected to an adder The corresponding compute() method obtained using the -omp option is the following: virtual void compute (int fullcount, float** input, float** output) { float fRec0_tmp[32+4]; float fRec1_tmp[32+4]; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; #pragma omp parallel firstprivate(fRec0,fRec1) { for (int index = 0; index < fullcount; index += 32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* input1 = &input[1][index]; float* output0 = &output[0][index]; #pragma omp single { for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; } // SECTION : 1 #pragma omp sections { #pragma omp section for (int i=0; i<count; i++) { fRec0[i] = ((0.1f * input1[i]) + (0.9f * fRec0[i-1])); } #pragma omp section for (int i=0; i<count; i++) { fRec1[i] = ((0.1f * input0[i]) + (0.9f * fRec1[i-1])); } } // SECTION : 2 #pragma omp for for (int i=0; i<count; i++) { output0[i] = (fRec1[i] + fRec0[i]); } // SECTION : 3 #pragma omp single { for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; } } } This code requires some comments: The parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. Variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1. The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. The top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between the threads. Please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. The work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). The work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. The loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. Finally #pragma omp single in section 3 indicates that this last section will be executed by only one thread (any of them). The scheduler code generator With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separated computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large subtree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers (only quite recent versions like GCC 4.4 start to show some improvements), and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future. Example of parallel scheduler code To illustrate how Faust generates the scheduler code, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute (int fullcount, float** input, float** output) { GetRealTime(); this->input = input; this->output = output; StartMeasure(); for (fIndex = 0; fIndex < fullcount; fIndex += 32) { fFullCount = min (32, fullcount-fIndex); TaskQueue::Init(); // Initialize end task fGraph.InitTask(1,1); // Only initialize tasks with inputs fGraph.InitTask(4,2); fIsFinished = false; fThreadPool.SignalAll(fDynamicNumThreads - 1); computeThread(0); while (!fThreadPool.IsFinished()) {} } StopMeasure(fStaticNumThreads, fDynamicNumThreads); void computeThread (int cur_thread) { float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; // Init graph state { TaskQueue taskqueue; int tasknum = -1; int count = fFullCount; // Init input and output FAUSTFLOAT* input0 = &input[0][fIndex]; FAUSTFLOAT* input1 = &input[1][fIndex]; FAUSTFLOAT* output0 = &output[0][fIndex]; int task_list_size = 2; int task_list[2] = {2,3}; taskqueue.InitTaskList(task_list_size, task_list, fDynamicNumThreads, cur_thread, tasknum); while (!fIsFinished) { switch (tasknum) { case WORK_STEALING_INDEX: { tasknum = TaskQueue::GetNextTask(cur_thread); break; } case LAST_TASK_INDEX: { fIsFinished = true; break; } // SECTION : 1 case 2: { // LOOP 0x101111680 // pre processing for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; // exec code for (int i=0; i<count; i++) { fRec0[i] = ((1.000000e-01f * (float)input1[i]) + (0.9f * fRec0[i-1])); } // post processing for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 3: { // LOOP 0x1011125e0 // pre processing for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; // exec code for (int i=0; i<count; i++) { fRec1[i] = ((1.000000e-01f * (float)input0[i]) + (0.9f * fRec1[i-1])); } // post processing for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 4: { // LOOP 0x101111580 // exec code for (int i=0; i<count; i++) { output0[i] = (FAUSTFLOAT)(fRec1[i] + fRec0[i]); } tasknum = LAST_TASK_INDEX; break; } } } }","title":"11 codegeneration"},{"location":"qreference/11-codegeneration/#controlling-the-code-generation","text":"Several options of the Faust compiler allow to control the generated C++ code. By default the computations are done sample by sample in a single loop. But the compiler can also generate vector and parallel code.","title":"Controlling the code generation"},{"location":"qreference/11-codegeneration/#vector-code-generation","text":"Modern C++ compilers are able to do autovectorization, that is to use SIMD instructions to speedup the code. These instructions can typically operate in parallel on short vectors of 4 simple precision floating point numbers thus leading to a theoretical speedup of \\times4 . Autovectorization of C/C++ programs is a difficult task. Current compilers are very sensitive to the way the code is arranged. In particular too complex loops can prevent autovectorization. The goal of the vector code generation is to rearrange the C++ code in a way that facilitates the autovectorization job of the C++ compiler. Instead of generating a single sample computation loop, it splits the computation into several simpler loops that communicates by vectors. The vector code generation is activated by passing the --vectorize (or -vec ) option to the Faust compiler. Two additional options are available: --vec-size controls the size of the vector (by default 32 samples) and --loop-variant 0/1 gives some additional control on the loops: --loop-variant 0 generates fixed-size sub-loops with a final sub-loop that processes the last samples, --loop-variant 1 generates sub-loops of variable vector size. To illustrate the difference between scalar code and vector code, let's take the computation of the RMS (Root Mean Square) value of a signal. Here is the Faust code that computes the Root Mean Square of a sliding window of 1000 samples: // Root Mean Square of n consecutive samples RMS(n) = square : mean(n) : sqrt; // Square of a signal square(x) = x * x; // Mean of n consecutive samples of a signal // (uses fixpoint to avoid the accumulation of // rounding errors) mean(n) = float2fix : integrate(n) : fix2float : /(n); // Sliding sum of n consecutive samples integrate(n,x) = x - x@n : +~_; // Convertion between float and fix point float2fix(x) = int(x*(1<<20)); fix2float(x) = float(x)/(1<<20); // Root Mean Square of 1000 consecutive samples process = RMS(1000); The compute() method generated in scalar mode is the following: virtual void compute (int count, float** input, float** output) { float* input0 = input[0]; float* output0 = output[0]; for (int i=0; i<count; i++) { float fTemp0 = input0[i]; int iTemp1 = int(1048576*fTemp0*fTemp0); iVec0[IOTA&1023] = iTemp1; iRec0[0] = ((iVec0[IOTA&1023] + iRec0[1]) - iVec0[(IOTA-1000)&1023]); output0[i] = sqrtf(9.536744e-10f * float(iRec0[0])); // post processing iRec0[1] = iRec0[0]; IOTA = IOTA+1; } The -vec option leads to the following reorganization of the code: virtual void compute (int fullcount, float** input, float** output) { int iRec0_tmp[32+4]; int* iRec0 = &iRec0_tmp[4]; for (int index=0; index<fullcount; index+=32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* output0 = &output[0][index]; for (int i=0; i<4; i++) iRec0_tmp[i]=iRec0_perm[i]; // SECTION : 1 for (int i=0; i<count; i++) { iYec0[(iYec0_idx+i)&2047] = int(1048576*input0[i]*input0[i]); } // SECTION : 2 for (int i=0; i<count; i++) { iRec0[i] = ((iYec0[i] + iRec0[i-1]) - iYec0[(iYec0_idx+i-1000)&2047]); } // SECTION : 3 for (int i=0; i<count; i++) { output0[i] = sqrtf((9.536744e-10f * float(iRec0[i]))); } // SECTION : 4 iYec0_idx = (iYec0_idx+count)&2047; for (int i=0; i<4; i++) iRec0_perm[i]=iRec0_tmp[count+i]; } While the second version of the code is more complex, it turns out to be much easier to vectorize efficiently by the C++ compiler. Using Intel icc 11.0, with the exact same compilation options: -O3 -xHost -ftz -fno-alias -fp-model fast=2, the scalar version leads to a throughput performance of 129.144 MB/s, while the vector version achieves 359.548 MB/s, a speedup of x2.8 ! Faust 's stack of code generators The vector code generation is built on top of the scalar code generation (see figure fig:stack ). Every time an expression needs to be compiled, the compiler checks if it requires a separate loop or not. It applies some simple rules for that. Expressions that are shared (and are complex enough) are good candidates to be compiled in a separate loop, as well as recursive expressions and expressions used in delay lines. The result is a directed graph in which each node is a computation loop (see Figure fig:loopgraph ). This graph is stored in the klass object and a topological sort is applied to it before printing the code. The result of the -vec option is a directed acyclic graph (DAG) of small computation loops","title":"Vector code generation"},{"location":"qreference/11-codegeneration/#parallel-code-generation","text":"The parallel code generation is activated by passing either the --openMP (or -omp ) option or the --scheduler (or -sch ) option. It implies the -vec options as the parallel code generation is built on top of the vector code generation.","title":"Parallel code generation"},{"location":"qreference/11-codegeneration/#the-openmp-code-generator","text":"OpenMP is based on a fork-join model The --openMP (or -omp ) option given to the Faust compiler will insert appropriate OpenMP directives in the C++ code. OpenMP (http://wwww.openmp.org) is a well established API that is used to explicitly define direct multi-threaded, shared memory parallelism. It is based on a fork-join model of parallelism (see figure fig:openmp ). Parallel regions are delimited by #pragma omp parallel constructs. At the entrance of a parallel region a team of parallel threads is activated. The code within a parallel region is executed by each thread of the parallel team until the end of the region. #pragma omp parallel { // the code here is executed simultaneously by // every thread of the parallel team ... In order not to have every thread doing redundantly the exact same work, OpemMP provides specific work-sharing directives. For example #pragma omp sections allows to break the work into separate, discrete sections, each section being executed by one thread: #pragma omp parallel { #pragma omp sections { #pragma omp section { // job 1 } #pragma omp section { // job 2 } ... } ...","title":"The OpenMP code generator"},{"location":"qreference/11-codegeneration/#adding-openmp-directives","text":"As said before the parallel code generation is built on top of the vector code generation. The graph of loops produced by the vector code generator is topologically sorted in order to detect the loops that can be computed in parallel. The first set S_0 (loops L1 , L2 and L3 in the DAG of Figure fig:loopgraph ) contains the loops that don't depend on any other loops, the set S_1 contains the loops that only depend on loops of S_0 , (that is loops L4 and L5 ), etc.. As all the loops of a given set S_n can be computed in parallel, the compiler will generate a sections construct with a section for each loop. #pragma omp sections { #pragma omp section for (...) { // Loop 1 } #pragma omp section for (...) { // Loop 2 } ... } If a given set contains only one loop, then the compiler checks to see if the loop can be parallelized (no recursive dependencies) or not. If it can be parallelized, it generates: #pragma omp for for (...) { // Loop code } otherwise it generates a single construct so that only one thread will execute the loop: #pragma omp single for (...) { // Loop code }","title":"Adding OpenMP directives"},{"location":"qreference/11-codegeneration/#example-of-parallel-openmp-code","text":"To illustrate how Faust uses the OpenMP directives, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; two filters in parallel connected to an adder The corresponding compute() method obtained using the -omp option is the following: virtual void compute (int fullcount, float** input, float** output) { float fRec0_tmp[32+4]; float fRec1_tmp[32+4]; float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; #pragma omp parallel firstprivate(fRec0,fRec1) { for (int index = 0; index < fullcount; index += 32) { int count = min (32, fullcount-index); float* input0 = &input[0][index]; float* input1 = &input[1][index]; float* output0 = &output[0][index]; #pragma omp single { for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; } // SECTION : 1 #pragma omp sections { #pragma omp section for (int i=0; i<count; i++) { fRec0[i] = ((0.1f * input1[i]) + (0.9f * fRec0[i-1])); } #pragma omp section for (int i=0; i<count; i++) { fRec1[i] = ((0.1f * input0[i]) + (0.9f * fRec1[i-1])); } } // SECTION : 2 #pragma omp for for (int i=0; i<count; i++) { output0[i] = (fRec1[i] + fRec0[i]); } // SECTION : 3 #pragma omp single { for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; } } } This code requires some comments: The parallel construct #pragma omp parallel is the fundamental construct that starts parallel execution. The number of parallel threads is generally the number of CPU cores but it can be controlled in several ways. Variables external to the parallel region are shared by default. The pragma firstprivate(fRec0,fRec1) indicates that each thread should have its private copy of fRec0 and fRec1. The reason is that accessing shared variables requires an indirection and is quite inefficient compared to private copies. The top level loop for (int index = 0;...)... is executed by all threads simultaneously. The subsequent work-sharing directives inside the loop will indicate how the work must be shared between the threads. Please note that an implied barrier exists at the end of each work-sharing region. All threads must have executed the barrier before any of them can continue. The work-sharing directive #pragma omp single indicates that this first section will be executed by only one thread (any of them). The work-sharing directive #pragma omp sections indicates that each corresponding #pragma omp section , here our two filters, will be executed in parallel. The loop construct #pragma omp for specifies that the iterations of the associated loop will be executed in parallel. The iterations of the loop are distributed across the parallel threads. For example, if we have two threads, the first one can compute indices between 0 and count/2 and the other one between count/2 and count. Finally #pragma omp single in section 3 indicates that this last section will be executed by only one thread (any of them).","title":"Example of parallel OpenMP code"},{"location":"qreference/11-codegeneration/#the-scheduler-code-generator","text":"With the --scheduler (or -sch ) option given to the Faust compiler, the computation graph is cut into separated computation loops (called \"tasks\"), and a \"Work Stealing Scheduler\" is used to activate and execute them following their dependencies. A pool of worked threads is created and each thread uses it's own local WSQ (Work Stealing Queue) of tasks. A WSQ is a special queue with a Push operation, a \"private\" LIFO Pop operation and a \"public\" FIFO Pop operation. Starting from a ready task, each thread follows the dependencies, possibly pushing ready sub-tasks into it's own local WSQ. When no more tasks can be activated on a given computation path, the thread pops a task from it's local WSQ. If the WSQ is empty, then the thread is allowed to \"steal\" tasks from other threads WSQ. The local LIFO Pop operation allows better cache locality and the FIFO steal Pop \"larger chuck\" of work to be done. The reason for this is that many work stealing workloads are divide-and-conquer in nature, stealing one of the oldest task implicitly also steals a (potentially) large subtree of computations that will unfold once that piece of work is stolen and run. Compared to the OpenMP model ( -omp ) the new model is worse for simple Faust programs and usually starts to behave comparable or sometimes better for \"complex enough\" Faust programs. In any case, since OpenMP does not behave so well with GCC compilers (only quite recent versions like GCC 4.4 start to show some improvements), and is unusable on OSX in real-time contexts, this new scheduler option has it's own value. We plan to improve it adding a \"pipelining\" idea in the future.","title":"The scheduler code generator"},{"location":"qreference/11-codegeneration/#example-of-parallel-scheduler-code","text":"To illustrate how Faust generates the scheduler code, here is a very simple example, two 1-pole filters in parallel connected to an adder (see figure fig:parfilter the corresponding block-diagram): filter(c) = *(1-c) : + ~ *(c); process = filter(0.9), filter(0.9) : +; When -sch option is used, the content of the additional architecture/scheduler.h file is inserted in the generated code. It contains code to deal with WSQ and thread management. The compute() and computeThread() methods are the following: virtual void compute (int fullcount, float** input, float** output) { GetRealTime(); this->input = input; this->output = output; StartMeasure(); for (fIndex = 0; fIndex < fullcount; fIndex += 32) { fFullCount = min (32, fullcount-fIndex); TaskQueue::Init(); // Initialize end task fGraph.InitTask(1,1); // Only initialize tasks with inputs fGraph.InitTask(4,2); fIsFinished = false; fThreadPool.SignalAll(fDynamicNumThreads - 1); computeThread(0); while (!fThreadPool.IsFinished()) {} } StopMeasure(fStaticNumThreads, fDynamicNumThreads); void computeThread (int cur_thread) { float* fRec0 = &fRec0_tmp[4]; float* fRec1 = &fRec1_tmp[4]; // Init graph state { TaskQueue taskqueue; int tasknum = -1; int count = fFullCount; // Init input and output FAUSTFLOAT* input0 = &input[0][fIndex]; FAUSTFLOAT* input1 = &input[1][fIndex]; FAUSTFLOAT* output0 = &output[0][fIndex]; int task_list_size = 2; int task_list[2] = {2,3}; taskqueue.InitTaskList(task_list_size, task_list, fDynamicNumThreads, cur_thread, tasknum); while (!fIsFinished) { switch (tasknum) { case WORK_STEALING_INDEX: { tasknum = TaskQueue::GetNextTask(cur_thread); break; } case LAST_TASK_INDEX: { fIsFinished = true; break; } // SECTION : 1 case 2: { // LOOP 0x101111680 // pre processing for (int i=0; i<4; i++) fRec0_tmp[i]=fRec0_perm[i]; // exec code for (int i=0; i<count; i++) { fRec0[i] = ((1.000000e-01f * (float)input1[i]) + (0.9f * fRec0[i-1])); } // post processing for (int i=0; i<4; i++) fRec0_perm[i]=fRec0_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 3: { // LOOP 0x1011125e0 // pre processing for (int i=0; i<4; i++) fRec1_tmp[i]=fRec1_perm[i]; // exec code for (int i=0; i<count; i++) { fRec1[i] = ((1.000000e-01f * (float)input0[i]) + (0.9f * fRec1[i-1])); } // post processing for (int i=0; i<4; i++) fRec1_perm[i]=fRec1_tmp[count+i]; fGraph.ActivateOneOutputTask(taskqueue, 4, tasknum); break; } case 4: { // LOOP 0x101111580 // exec code for (int i=0; i<count; i++) { output0[i] = (FAUSTFLOAT)(fRec1[i] + fRec0[i]); } tasknum = LAST_TASK_INDEX; break; } } } }","title":"Example of parallel scheduler code"},{"location":"qreference/12-mdoc/","text":"Mathematical Documentation The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long). Goals of the mathdoc There are for main goals, or uses, of this mathematical documentation: - to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler; - to preserve signal processors, independently from any computer language but only under a mathematical form; - to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage; - to give a new teaching support, as a bridge between code and formulas for signal processing. Installation requirements faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as LaTeX doesn't eat Svg directly yet... breqn , a LaTeX package to handle automatic breaking of long equations, pdflatex , to compile the LaTeX output file. Generating the mathdoc The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leave the documentation production unfinished. For example: faust2mathdoc noise.dsp Invoking the -mdoc option Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with \"-mdoc\", 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a LaTeX file containing the formulas, Svg files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so all needed libraries to have a self-contained DSP), svg/ contains Svg block-diagram files, tex/ contains the generated LaTeX file. Invoking faust2mathdoc The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all Svg files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the LaTeX file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ . Online examples To get an idea of the results of this mathematical documentation, which captures the mathematical semantic of Faust programs, you can look at two pdf files online: http://faust.grame.fr/pdf/karplus.pdf (automatic documentation), http://faust.grame.fr/pdf/noise.pdf (manual documentation). You can also generate all mdoc pdfs at once, simply invoking the make mathdoc command inside the examples/ directory: for each %.dsp file, a complete %-mdoc directory will be generated, a single allmathpdfs/ directory will gather all the generated pdf files. Automatic documentation By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a LaTeX file with four sections: - '' Equations of process '', gathering all formulas needed for process , - '' Block-diagram schema of process '', showing the top-level block-diagram of process , - '' Notice of this documentation '', summing up generation and conventions information, - '' Complete listing of the input code '', listing all needed input files (including libraries). Manual documentation You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That permits you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the LaTeX stuff becomes up to you! Six tags Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive'' notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to \"true\" by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections. The mdoc top-level tags The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs (see section \\ref{documentation}). In addition of the four inner tags, <mdoc></mdoc> tags accept free LaTeX text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the LaTeX packages included by Faust can be found in the file architecture/latexheader.tex . An example of manual mathdoc &lt;mdoc> \\title{&lt;metadata>name&lt;/metadata>} \\author{&lt;metadata>author&lt;/metadata>} \\date{\\today} \\maketitle | | | |------|------| | **name** | &lt;metadata>name&lt;/metadata> | | **version** | &lt;metadata>version&lt;/metadata> | | **author** | &lt;metadata>author&lt;/metadata> | | **license** | &lt;metadata>license&lt;/metadata> | | **copyright** | &lt;metadata>copyright&lt;/metadata> | &lt;/mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; &lt;mdoc> ## Presentation of the \"noise.dsp\" Faust program This program describes a white noise generator with an interactive volume, using a random function. ### The random function &lt;/mdoc> random = +(12345)~*(1103515245); &lt;mdoc> The random function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. &lt;equation>random&lt;/equation> ### The noise function &lt;/mdoc> noise = random/2147483647.0; &lt;mdoc> The white noise then corresponds to: &lt;equation>noise&lt;/equation> ### Just add a user interface element to play volume! &lt;/mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); &lt;mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: &lt;equation>process&lt;/equation> ## Block-diagram schema of process This process is illustrated on figure 1. &lt;diagram>process&lt;/diagram> ## Notice of this documentation You might be careful of certain information and naming conventions used in this documentation: &lt;notice /> ## Listing of the input code The following listing shows the input Faust code, parsed to compile this mathematical documentation. &lt;listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> &lt;/mdoc> The following page which gathers the four resulting pages of noise.pdf in small size. might give you an idea of the produced documentation. The -stripmdoc option As you can see on the resulting file noisemetadata.pdf on its pages 3 and 4, the listing of the input code (section\\,4) contains all the mathdoc text (here colored in grey). As it may be useless in certain cases (see Goals, section goals-of-mdoc ), we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long). Localization of mathdoc files By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian for the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. \\includepdf[pages=-, frame=true, angle=-90, scale=0.75, nup=1x2]{images/noisemetadata} Summary of the mathdoc generation steps First, to get the full mathematical documentation done on your faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"12 mdoc"},{"location":"qreference/12-mdoc/#mathematical-documentation","text":"The Faust compiler provides a mechanism to produce a self-describing documentation of the mathematical semantic of a Faust program, essentially as a pdf file. The corresponding options are -mdoc (short) or --mathdoc (long).","title":"Mathematical Documentation"},{"location":"qreference/12-mdoc/#goals-of-the-mathdoc","text":"There are for main goals, or uses, of this mathematical documentation: - to preserve the DSP source code with all the needed libraries, so that the DSP can be compiled with a more recent version of the compiler and produce the same resulting program. This is the way we allow the libraries themselves to evolve (even without maintaining compatibility with older versions), while still allowing an older program to be compiled with newer versions of the compiler; - to preserve signal processors, independently from any computer language but only under a mathematical form; - to bring some help for debugging tasks, by showing the formulas as they are really computed after the compilation stage; - to give a new teaching support, as a bridge between code and formulas for signal processing.","title":"Goals of the mathdoc"},{"location":"qreference/12-mdoc/#installation-requirements","text":"faust , of course! svg2pdf (from the Cairo 2D graphics library), to convert block-diagrams, as LaTeX doesn't eat Svg directly yet... breqn , a LaTeX package to handle automatic breaking of long equations, pdflatex , to compile the LaTeX output file.","title":"Installation requirements"},{"location":"qreference/12-mdoc/#generating-the-mathdoc","text":"The easiest way to generate the complete mathematical documentation is to call the faust2mathdoc script on a Faust file, as the -mdoc option leave the documentation production unfinished. For example: faust2mathdoc noise.dsp","title":"Generating the mathdoc"},{"location":"qreference/12-mdoc/#invoking-the-mdoc-option","text":"Calling directly faust -mdoc does only the first part of the work, generating: a top-level directory, suffixed with \"-mdoc\", 5 subdirectories ( cpp/ , pdf/ , src/ , svg/ , tex/ ), a LaTeX file containing the formulas, Svg files for block-diagrams. At this stage: cpp/ remains empty, pdf/ remains empty, src/ contains all the used Faust sources (so all needed libraries to have a self-contained DSP), svg/ contains Svg block-diagram files, tex/ contains the generated LaTeX file.","title":"Invoking the -mdoc option"},{"location":"qreference/12-mdoc/#invoking-faust2mathdoc","text":"The faust2mathdoc script calls faust --mathdoc first, then it finishes the work: moving the output C++ file into cpp/ , converting all Svg files into pdf files (you must have svg2pdf installed, from the Cairo 2D graphics library), launching pdflatex on the LaTeX file (you must have both pdflatex and the breqn package installed), moving the resulting pdf file into pdf/ .","title":"Invoking faust2mathdoc"},{"location":"qreference/12-mdoc/#online-examples","text":"To get an idea of the results of this mathematical documentation, which captures the mathematical semantic of Faust programs, you can look at two pdf files online: http://faust.grame.fr/pdf/karplus.pdf (automatic documentation), http://faust.grame.fr/pdf/noise.pdf (manual documentation). You can also generate all mdoc pdfs at once, simply invoking the make mathdoc command inside the examples/ directory: for each %.dsp file, a complete %-mdoc directory will be generated, a single allmathpdfs/ directory will gather all the generated pdf files.","title":"Online examples"},{"location":"qreference/12-mdoc/#automatic-documentation","text":"By default, when no <mdoc> tag can be found in the input Faust file, the -mdoc option automatically generates a LaTeX file with four sections: - '' Equations of process '', gathering all formulas needed for process , - '' Block-diagram schema of process '', showing the top-level block-diagram of process , - '' Notice of this documentation '', summing up generation and conventions information, - '' Complete listing of the input code '', listing all needed input files (including libraries).","title":"Automatic documentation"},{"location":"qreference/12-mdoc/#manual-documentation","text":"You can specify yourself the documentation instead of using the automatic mode, with five xml-like tags. That permits you to modify the presentation and to add your own comments, not only on process , but also about any expression you'd like to. Note that as soon as you declare an <mdoc> tag inside your Faust file, the default structure of the automatic mode is ignored, and all the LaTeX stuff becomes up to you!","title":"Manual documentation"},{"location":"qreference/12-mdoc/#six-tags","text":"Here are the six specific tags: <mdoc></mdoc> , to open a documentation field in the Faust code, <equation></equation> , to get equations of a Faust expression, <diagram></diagram> , to get the top-level block-diagram of a Faust expression, <metadata></metadata> , to reference Faust metadatas (cf. declarations), calling the corresponding keyword, <notice /> , to insert the \"adaptive'' notice all formulas actually printed, <listing [attributes] /> , to insert the listing of Faust files called. The <listing /> tag can have up to three boolean attributes (set to \"true\" by default): mdoctags for <mdoc> tags; dependencies for other files dependencies; distributed for the distribution of interleaved Faust code between <mdoc> sections.","title":"Six tags"},{"location":"qreference/12-mdoc/#the-mdoc-top-level-tags","text":"The <mdoc></mdoc> tags are the top-level delimiters for Faust mathematical documentation sections. This means that the four other documentation tags can't be used outside these pairs (see section \\ref{documentation}). In addition of the four inner tags, <mdoc></mdoc> tags accept free LaTeX text, including its standard macros (like \\section , \\emph , etc.). This allows to manage the presentation of resulting tex file directly from within the input Faust file. The complete list of the LaTeX packages included by Faust can be found in the file architecture/latexheader.tex .","title":"The mdoc top-level tags"},{"location":"qreference/12-mdoc/#an-example-of-manual-mathdoc","text":"&lt;mdoc> \\title{&lt;metadata>name&lt;/metadata>} \\author{&lt;metadata>author&lt;/metadata>} \\date{\\today} \\maketitle | | | |------|------| | **name** | &lt;metadata>name&lt;/metadata> | | **version** | &lt;metadata>version&lt;/metadata> | | **author** | &lt;metadata>author&lt;/metadata> | | **license** | &lt;metadata>license&lt;/metadata> | | **copyright** | &lt;metadata>copyright&lt;/metadata> | &lt;/mdoc> //----------------------------------------------------------------- // Noise generator and demo file for the Faust math documentation //----------------------------------------------------------------- declare name \"Noise\"; declare version \"1.1\"; declare author \"Grame\"; declare author \"Yghe\"; declare license \"BSD\"; declare copyright \"(c)GRAME 2009\"; &lt;mdoc> ## Presentation of the \"noise.dsp\" Faust program This program describes a white noise generator with an interactive volume, using a random function. ### The random function &lt;/mdoc> random = +(12345)~*(1103515245); &lt;mdoc> The random function describes a generator of random numbers, which equation follows. You should notice hereby the use of an integer arithmetic on 32 bits, relying on integer wrapping for big numbers. &lt;equation>random&lt;/equation> ### The noise function &lt;/mdoc> noise = random/2147483647.0; &lt;mdoc> The white noise then corresponds to: &lt;equation>noise&lt;/equation> ### Just add a user interface element to play volume! &lt;/mdoc> process = noise * vslider(\"Volume[style:knob]\", 0, 0, 1, 0.1); &lt;mdoc> Endly, the sound level of this program is controlled by a user slider, which gives the following equation: &lt;equation>process&lt;/equation> ## Block-diagram schema of process This process is illustrated on figure 1. &lt;diagram>process&lt;/diagram> ## Notice of this documentation You might be careful of certain information and naming conventions used in this documentation: &lt;notice /> ## Listing of the input code The following listing shows the input Faust code, parsed to compile this mathematical documentation. &lt;listing mdoctags=\"false\" dependencies=\"false\" distributed=\"true\" /> &lt;/mdoc> The following page which gathers the four resulting pages of noise.pdf in small size. might give you an idea of the produced documentation.","title":"An example of manual mathdoc"},{"location":"qreference/12-mdoc/#the-stripmdoc-option","text":"As you can see on the resulting file noisemetadata.pdf on its pages 3 and 4, the listing of the input code (section\\,4) contains all the mathdoc text (here colored in grey). As it may be useless in certain cases (see Goals, section goals-of-mdoc ), we provide an option to strip mathdoc contents directly at compilation stage: -stripmdoc (short) or --strip-mdoc-tags (long).","title":"The -stripmdoc option"},{"location":"qreference/12-mdoc/#localization-of-mathdoc-files","text":"By default, texts used by the documentator are in English, but you can specify another language (French, German and Italian for the moment), using the -mdlang (or --mathdoc-lang ) option with a two-letters argument ( en , fr , it , etc.). The faust2mathdoc script also supports this option, plus a third short form with -l : faust2mathdoc -l fr myfaustfile.dsp If you would like to contribute to the localization effort, feel free to translate the mathdoc texts from any of the mathdoctexts-*.txt files, that are in the architecture directory ( mathdoctexts-fr.txt , mathdoctexts-it.txt , etc.). As these files are dynamically loaded, just adding a new file with an appropriate name should work. \\includepdf[pages=-, frame=true, angle=-90, scale=0.75, nup=1x2]{images/noisemetadata}","title":"Localization of mathdoc files"},{"location":"qreference/12-mdoc/#summary-of-the-mathdoc-generation-steps","text":"First, to get the full mathematical documentation done on your faust file, call faust2mathdoc myfaustfile.dsp . Then, open the pdf file myfaustfile-mdoc/pdf/myfaustfile.pdf . That's all !","title":"Summary of the mathdoc generation steps"},{"location":"qreference/13-acknowledgments/","text":"Acknowledgments Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen Karim Barkati J\\'er\\^ome Barth\\'elemy Tim Blechmann Tiziano Bole Alain Bonardi Thomas Charbonnel Raffaele Ciavarella Julien Colafrancesco Damien Cramet Sarah Denoux \\'Etienne Gaudrin Olivier Guillerminet Pierre Guillot Albert Gr\\\"af Pierre Jouvelot Stefan Kersten Victor Lazzarini Matthieu Leberre Mathieu Leroi Fernando Lopez-Lezcano Kjetil Matheussen Hermann Meyer Romain Michon R\\'emy Muller Eliott Paris Reza Payami Laurent Pottier Sampo Savolainen Nicolas Scaringella Anne Sedes Priyanka Shekar Stephen Sinclair Travis Skare Julius Smith Mike Solomon Michael Wilson as well as our colleagues at GRAME: Dominique Fober Christophe Lebreton St\\'ephane Letz Romain Michon We would like also to thank for their financial support: the French Ministry of Culture the Rh\\^one-Alpes Region the City of Lyon the French National Research Agency ( ANR )","title":"13 acknowledgments"},{"location":"qreference/13-acknowledgments/#acknowledgments","text":"Many persons are contributing to the Faust project, by providing code for the compiler, architecture files, libraries, examples, documentation, scripts, bug reports, ideas, etc. We would like in particular to thank: Fons Adriaensen Karim Barkati J\\'er\\^ome Barth\\'elemy Tim Blechmann Tiziano Bole Alain Bonardi Thomas Charbonnel Raffaele Ciavarella Julien Colafrancesco Damien Cramet Sarah Denoux \\'Etienne Gaudrin Olivier Guillerminet Pierre Guillot Albert Gr\\\"af Pierre Jouvelot Stefan Kersten Victor Lazzarini Matthieu Leberre Mathieu Leroi Fernando Lopez-Lezcano Kjetil Matheussen Hermann Meyer Romain Michon R\\'emy Muller Eliott Paris Reza Payami Laurent Pottier Sampo Savolainen Nicolas Scaringella Anne Sedes Priyanka Shekar Stephen Sinclair Travis Skare Julius Smith Mike Solomon Michael Wilson as well as our colleagues at GRAME: Dominique Fober Christophe Lebreton St\\'ephane Letz Romain Michon We would like also to thank for their financial support: the French Ministry of Culture the Rh\\^one-Alpes Region the City of Lyon the French National Research Agency ( ANR )","title":"Acknowledgments"},{"location":"qreference/2-install/","text":"Compiling and installing Faust The Faust source distribution faust-2.74.6.tar.gz can be downloaded from GitHub ( https://github.com/grame-cncm/faust/releases ). Organization of the distribution The first thing is to decompress the downloaded archive. tar xzf faust-2.74.6.tar.gz The resulting faust-2.74.6/ folder should contain the following elements: architecture/ Faust libraries and architecture files benchmark tools to measure the efficiency of the generated code compiler/ sources of the Faust compiler examples/ examples of Faust programs syntax-highlighting/ & support for syntax highlighting for several editors documentation/ Faust 's documentation, including this manual tools/ tools to produce audio applications and plugins COPYING license information Makefile Makefile used to build and install Faust README instructions on how to build and install Faust Compilation Faust has no dependencies outside standard libraries. Therefore the compilation should be straightforward. There is no configuration phase, to compile the Faust compiler simply do : cd faust-2.74.6/ make If the compilation was successful you can test the compiler before installing it: [cd faust-2.74.6/] ./build/bin/faust -v It should output: FAUST Version 2.74.6 Embedded backends: DSP to C DSP to C++ DSP to Cmajor DSP to Codebox DSP to CSharp DSP to DLang DSP to Java DSP to JAX DSP to Julia DSP to JSFX DSP to old C++ DSP to Rust DSP to WebAssembly (wast/wasm) Copyright (C) 2002-2024, GRAME - Centre National de Creation Musicale. All rights reserved. Then you can also try to compile one of the examples : [cd faust-2.74.6/] ./build/bin/faust examples/generator/noise.dsp It should produce some C++ code on the standard output. Installation You can install Faust with: [cd faust-2.74.6/] sudo make install or [cd faust-2.74.6/] su make install depending on your system. Compilation of the examples Once Faust correctly installed, you can have a look at the provided examples in the examples/ folder. You can use any of the faust2... script installed on your system (go in /tools/faust2appls to get an exhaustive list) to compile the Faust codes available in this folder. For example, if you're a Mac user and you want to turn filtering/vcfWahLab.dsp into a standalone CoreAudio application with a QT interface, just run: faust2caqt filtering/vcfWahLab.dsp","title":"2 install"},{"location":"qreference/2-install/#compiling-and-installing-faust","text":"The Faust source distribution faust-2.74.6.tar.gz can be downloaded from GitHub ( https://github.com/grame-cncm/faust/releases ).","title":"Compiling and installing Faust"},{"location":"qreference/2-install/#organization-of-the-distribution","text":"The first thing is to decompress the downloaded archive. tar xzf faust-2.74.6.tar.gz The resulting faust-2.74.6/ folder should contain the following elements: architecture/ Faust libraries and architecture files benchmark tools to measure the efficiency of the generated code compiler/ sources of the Faust compiler examples/ examples of Faust programs syntax-highlighting/ & support for syntax highlighting for several editors documentation/ Faust 's documentation, including this manual tools/ tools to produce audio applications and plugins COPYING license information Makefile Makefile used to build and install Faust README instructions on how to build and install Faust","title":"Organization of the distribution"},{"location":"qreference/2-install/#compilation","text":"Faust has no dependencies outside standard libraries. Therefore the compilation should be straightforward. There is no configuration phase, to compile the Faust compiler simply do : cd faust-2.74.6/ make If the compilation was successful you can test the compiler before installing it: [cd faust-2.74.6/] ./build/bin/faust -v It should output: FAUST Version 2.74.6 Embedded backends: DSP to C DSP to C++ DSP to Cmajor DSP to Codebox DSP to CSharp DSP to DLang DSP to Java DSP to JAX DSP to Julia DSP to JSFX DSP to old C++ DSP to Rust DSP to WebAssembly (wast/wasm) Copyright (C) 2002-2024, GRAME - Centre National de Creation Musicale. All rights reserved. Then you can also try to compile one of the examples : [cd faust-2.74.6/] ./build/bin/faust examples/generator/noise.dsp It should produce some C++ code on the standard output.","title":"Compilation"},{"location":"qreference/2-install/#installation","text":"You can install Faust with: [cd faust-2.74.6/] sudo make install or [cd faust-2.74.6/] su make install depending on your system.","title":"Installation"},{"location":"qreference/2-install/#compilation-of-the-examples","text":"Once Faust correctly installed, you can have a look at the provided examples in the examples/ folder. You can use any of the faust2... script installed on your system (go in /tools/faust2appls to get an exhaustive list) to compile the Faust codes available in this folder. For example, if you're a Mac user and you want to turn filtering/vcfWahLab.dsp into a standalone CoreAudio application with a QT interface, just run: faust2caqt filtering/vcfWahLab.dsp","title":"Compilation of the examples"},{"location":"qreference/3-syntax/","text":"Faust syntax This section describes the syntax of Faust . Figure fig-syntax gives an overview of the various concepts and where they are defined in this section. Overview of Faust syntax As we will see, definitions and expressions have a central role. Faust program A Faust program is essentially a list of statements . These statements can be declarations , imports , definitions and documentation tags , with optional C++ style (//... and / ... /) comments. program ComplexDiagram( OneOrMore (NonTerminal('statement')) ).addTo() A Simple Program Here is a short Faust program that implements of a simple noise generator. It exhibits various kind of statements: two declarations , an import , a comment and a definition . We will see later on documentation statements ( sec-documentation ). declare name \"noise\"; declare copyright \"(c)GRAME 2006\"; import(\"music.lib\"); // noise level controlled by a slider process = noise * vslider(\"volume\", 0, 0, 1, 0.1); The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process . Statements The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions and documentation . All statements but documentation end with a semicolon ( ; ). statement ComplexDiagram( Choice (0, NonTerminal('declaration'), NonTerminal('fileimport'), NonTerminal('definition'), NonTerminal('documentation')) ).addTo() Declarations Meta-data declarations (for example declare name \"noise\"; ) are optional and typically used to document a Faust project. declaration ComplexDiagram( Sequence (\"declare\", NonTerminal('key'), NonTerminal('string'), ';') ).addTo() key ComplexDiagram( NonTerminal('identifier') ).addTo() Contrary to regular comments, these declarations will appear in the C++ code generated by the compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\"; Imports File imports allow to import definitions from other source files. fileimport ComplexDiagram( Sequence (\"import\", '(', NonTerminal('filename'), ')', ';') ).addTo() For example import(\"maths.lib\"); imports the definitions of the maths.lib library, a set of additional mathematical functions provided as foreign functions. Documentation Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed chapter \\ref{chapter-mdoc}. In this section we will essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in LaTeX format, can be placed in between these two tags. documentation ComplexDiagram( Sequence (\"<mdoc>\", OneOrMore (Choice (0, NonTerminal('freetext'), NonTerminal('equation'), NonTerminal('diagram'), NonTerminal('metadata'), NonTerminal('notice'), NonTerminal('listing'))), \"</mdoc>\") ).addTo() Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . equation ComplexDiagram( Sequence (\"<equation>\", NonTerminal('expression'), \"</equation>\") ).addTo() The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. diagram ComplexDiagram( Sequence (\"<diagram>\", NonTerminal('expression'), \"</diagram>\") ).addTo() Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. metadata ComplexDiagram( Sequence (\"<metadata>\", NonTerminal('keyword'), \"</metadata>\") ).addTo() The <metadata> tags allow to reference Faust metadatas (cf. declarations), calling the corresponding keyword. notice ComplexDiagram( \"<notice />\" ).addTo() The <notice /> empty-element tag is used to generate the conventions used in the mathematical equations. listing ComplexDiagram( Sequence (\"<listing\", NonTerminal('listingattribute*'), \" />\") ).addTo() listingattribute ComplexDiagram( Sequence (Choice (0, \"mdoctags\", \"dependencies\", \"distributed\"), \"=\", Choice (0, '\"true\"', '\"false\"')) ).addTo() The <listing /> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved faust code between sections. Definitions A definition associates an identifier with an expression it stands for. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition. Simple Definitions The syntax of a simple definition is: definition ComplexDiagram( Sequence (NonTerminal('identifier'), '=', NonTerminal('expression'), ';') ).addTo() For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245); Function Definitions Definitions with formal parameters correspond to functions definitions. fdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('parameter'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() For example the definition of linear2db , a function that converts linear values to decibels, is : linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x)); Definitions with pattern matching Moreover, formal parameters can also be full expressions representing patterns. pdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('pattern'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Please note that this last definition is a convenient alternative to the more verbose : duplicate = case { (1,x) => x; (n,x) => duplicate(n-1,x); }; Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11). The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element : count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) the expression will be evaluated to 10 . Please note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in : count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time. Variants Some statements (imports, definitions) can be preceded by a variantlist, composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308; Expressions Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. expression ComplexDiagram( Choice (0, NonTerminal('diagram'), NonTerminal('insouts'), NonTerminal('numerical'), NonTerminal('time'), NonTerminal('lexical'), NonTerminal('foreign'), NonTerminal('lambda')) ).addTo() Constant Numerical Expressions Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time. We will refer to them as constant numerical expressions in the documentation. Diagram Expressions Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. diagramexp ComplexDiagram( Choice (0, NonTerminal('diagcomposition'), NonTerminal('diagiteration')) ).addTo() Diagram composition operations Five binary composition operations are available to combine block-diagrams: recursion , parallel , sequential , split and merge composition. One can think of each of these composition operations as a particular way to connect two block diagrams. diagcomposition ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('~'), ',', ':', '<:', ':>'), NonTerminal('expression')) ).addTo() To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a bloc-diagram A are notated \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively notated : [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc.. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are given table table-composition . Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table infix-comparison-priority that gives the associativity of each numerical operator in infix expressions. Syntax Pri. Assoc. Description expression \\ \\sim \\ expression 4 left recursive composition expression \\ ,\\ expression 3 right parallel composition expression \\ :\\ expression 2 right sequential composition expression \\ <:\\ expression 1 right split composition expression \\ :>\\ expression 1 right merge composition Block-Diagram composition operation priorities Parallel Composition The parallel composition (A,B) (figure figure-par1 ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation : (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used : A,B,C,D , Faust uses right associativity and therefore build internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example of parallel composition (10,*) Sequential Composition The sequential composition A:B (figure figure-seq1 ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Example of sequential composition ((*,/):+) Sequential composition is an associative operation : (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore build internally the expression (A:(B:(C:D))) . Split Composition The split composition A<:B (figure figure-split1 ) operator is used to distribute the outputs of A to the inputs of B . example of split composition ((10,20) <: (+,*,/)) Each input i of B is connected to the output i \\bmod k of A : Merge Composition The merge composition A:>B (figure figure-merge1 ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : Each output i of A is connected to the input i \\bmod k of B : The k incoming signals of an input of B are summed together. example of merge composition ((10,20,30,40) :> *) Recursive Composition The recursive composition A~B (figure figure-rec1 ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable it requires that : Each input of B is connected to the corresponding output of A via an implicit 1-sample delay : A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . example of recursive composition +(12345) ~ *(1103515245) Inputs and outputs of an expression These two constructions can be used to know at compile time the number of inputs and outputs of any Faust expression. insouts ComplexDiagram( Choice (0, Sequence (\"inputs\", '(', NonTerminal('expression'), ')'), Sequence (\"outputs\", '(', NonTerminal('expression'), ')')) ).addTo() They are useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,selector(n-i-1,n)) with { n=outputs(expr); }; And the inputs of an expression : Xi(expr) = bus(n) <: par(i,n,selector(n-i-1,n)) : expr with { n=inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction. Iterations Iterations are analogous to for(...) loops and provide a convenient way to automate some complex block-diagram constructions. diagiteration ComplexDiagram( Choice (0, Sequence (\"par\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"seq\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"sum\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"prod\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')')) ).addTo() The following example shows the usage of seq to create a 10-bands filter: process = seq(i, 10, vgroup(\"band %i\", bandfilter( 1000*(1+i) ) ) ); numiter ComplexDiagram( NonTerminal('expression') ).addTo() The number of iterations must be a constant expression. Infix Notation Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in \\(2+3\\)}Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar \\emph{infix notation . For example if you want to multiply two numbers, let say 2 and 3 , you can write directly 2 3 instead of the equivalent core-syntax expression 2,3: . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example you can write /2 . It is equivalent to ,2:/ which divides the incoming signal by 2 . Examples of equivalences are given table tab-infixrules . 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < Infix and core syntax equivalences In case of doubts on the meaning of an infix expression, for example _ , it is useful to translate it to its core syntax equivalent, here ,_: , which is equivalent to * . Built-in primitives that can be used in infix notation are called infix operators and are listed in this section. Please note that a more detailed description of these operators is available section primitives . Comparison Operators Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. comparison ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '<', '<=', '>', '>=', '==', '!='), NonTerminal('expression')) ).addTo() The priority and associativity of the comparison operators is given table infix-comparison-priority . Syntax Pri. Assoc. Description expression \\ <\\ expression 5 left less than expression \\ <=\\ expression 5 left less or equal expression \\ !=\\ expression 5 left different expression \\ >=\\ expression 5 left greater or equal expression \\ >\\ expression 5 left greater than Comparison operators priorities in infix expressions Math Operators Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. math ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '+', '-', '*', '/', '%', NonTerminal('\u22c0')), NonTerminal('expression')) ).addTo() The priority and associativity of the math operators is given table infix-math-priority . Syntax Pri. Assoc. Description expression \\ +\\ expression 6 left addition expression \\ -\\ expression 6 left subtraction expression \\ *\\ expression 7 left multiplication expression \\ /\\ expression 7 left division expression \\ %\\ expression 7 left modulo expression \\ \\^\\ expression 8 left power Math operators priorities in infix expressions Bitwise operators Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. bitwise ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('|'), NonTerminal('&'), 'xor', '<<', '>>'), NonTerminal('expression')) ).addTo() The priority and associativity of the bitwise operators is given table infix-bitwise-priority . Syntax Pri. Assoc. Description expression \\ |\\ expression 6 left bitwise or expression \\ \\ expression 7 left expression \\ xor\\ expression 7 left bitwise xor expression \\ <<\\ expression 7 left bitwise left shift expression \\ >>\\ expression 7 left bitwise right shift Bitwise operators priorities in infix expressions Delay operators Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. delay ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \"'\" delays the left handside expression by one sample. The priority and associativity of the delay operators is given table infix-delay-priority . Syntax Pri. Assoc. Description expression \\ @\\ expression 9 left variable delay expression \\' 10 left one-sample delay Delay operators priorities in infix expressions Prefix Notation Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Prefix to core syntax translation rules It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) (see table tab-prefixrules ). Partial Application The partial application notation is a variant of prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube) and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one, as summarized table tab-partialrules . +(C) \\equiv _,C:* -(C) \\equiv _,C:- <(C) \\equiv _,C:< /(C) \\equiv _,C:/ Partial application of infix operators For commutative operations that doesn't matter. But for non-commutative ones, it is more ``natural'' to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter. Time expressions Time expressions are used to express delays. The notation X@10 represent the signal X delayed by 10 samples. The notation \"X'\" represent the signal X delayed by one sample and is therefore equivalent to X@1 . time ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay (automatically promoted to int ) don't have to be fixed, but it must be positive and bounded. The values of a slider are perfectly acceptable as in the following example: process = _ @ hslider(\"delay\",0, 0, 100, 1); Environment expressions Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. envexp ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), NonTerminal('definition+'), NonTerminal('}')), Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')), Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')), Sequence (NonTerminal('expression'), '.', NonTerminal('ident')), Sequence ('library', '(', NonTerminal('filename'), ')'), Sequence ('component', '(', NonTerminal('filename'), ')'), Sequence (NonTerminal('expression'), '[', OneOrMore (NonTerminal('definition')), ']')) ).addTo() With The with construction allows to specify a local environment , a private list of definition that will be used to evaluate the left hand expression withexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example : pink = f : + ~ g with { f(x) = 0.04957526213389*x - 0.06305581334498*x' + 0.01483220320740*x''; g(x) = 1.80116083982126*x - 0.80257737639225*x'; }; the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} . Letrec The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows to easily express groups of mutually recursive signals, for example: x(t)&=&y(t-1)+10; y(t)&=&x(t-1)-1; as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: letrecexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')) ).addTo() diffequation ComplexDiagram( Sequence (NonTerminal('''), NonTerminal('ident'), '=', NonTerminal('expression'), ';') ).addTo() Please remarks the special notation 'x=y+10 instead of x=y'+10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelop generator with an attack time, a release time and a gate signal. A possible definition is the following: ar(a,r,g) = v letrec { 'n = (n+1) * (g<=g'); 'v = max(0, v + (n<a)/a - (n>=a)/r) * (g<=g'); }; With the following semantics for n(t) and v(t) : n(t)&=&(n(t-1)+1) * (g(t) <= g(t-1)) v(t)&=& max(0, v(t-1) + (n(t-1) =a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of 'letrec': x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); }; Environment The environment construction allows to create an explicit environment. It is like a with , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. environment ComplexDiagram( Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example an environment construction is used to group together some constant definitions : constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next paragraph). Access Definitions inside an environment can be accessed using the '.' construction. access ComplexDiagram( Sequence (NonTerminal('expression'), '.', NonTerminal('ident')) ).addTo() For example constant.pi refers to the definition of pi in the above constant environment. Please note that environment don't have to be named. We could have written directly environment{pi = 3.14159; e = 2.718; ... }.pi Library The library construct allows to create an environment by reading the definitions from a file. library ComplexDiagram( Sequence ('library', '(', NonTerminal('filename'), ')') ).addTo() For example library(\"miscfilter.lib\") represents the environment obtained by reading the file \"miscfilter.lib\". It works like import(\"miscfilter.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"miscfilter.lib\").lowpass denotes the function lowpass as defined in the file \"miscfilter.lib\" . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of : import(\"miscfilter.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts : fl = library(\"miscfilter.lib\"); ... ...fl.lowpass.... ... }; Component The component(...) construction allows to reuse a full Faust program as a simple expression. component ComplexDiagram( Sequence ('component', '(', NonTerminal('filename'), ')') ).addTo() For example component(\"freeverb.dsp\") denotes the signal processor defined in file \"freeverb.dsp\". Components can be used within expressions like in: ...component(\"karplus32.dsp\"):component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process . Explicit substitution Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. explicitsubst ComplexDiagram( Sequence (NonTerminal('expression'), \"[\", OneOrMore (NonTerminal('definition')), \"]\") ).addTo() For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing : ...component(\"freeverb.dsp\")[foo(x) = ...;]... }; Foreign expressions Reference to external (foreign) C functions , variables and constants can be introduced using the foreign expressions mechanism. foreignexp ComplexDiagram( Choice (0, Sequence ('ffunction', '(', NonTerminal('signature'), ',', NonTerminal('includefile'), ',', NonTerminal('library'), ')'), Sequence ('fvariable', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')'), Sequence ('fconstant', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')')) ).addTo() Foreign function declaration An external C function is declared by indicating its name and signature as well as the required include file. The file \"maths.lib\" of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad and fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision, and asinhfx in fixed-point precision. This is why the four names are provided in the signature. signature ComplexDiagram( Sequence (NonTerminal('type'), NonTerminal('funnames'), '(', OneOrMore (NonTerminal('argtype'), ','), ')') ).addTo() funnames ComplexDiagram( Sequence (NonTerminal('identifier'), Optional ( Sequence ('|', NonTerminal('identifier'))), Optional ( Sequence ('|', NonTerminal('identifier')))) ).addTo() Foreign functions generally expect a precise type: ( int or float ) for their parameters. Note that currently only numerical functions involving scalar parameters are allowed. No vectors, tables or data structures can be passed as parameters or returned. During the compilation if the type of an argument is not the same as the type of the parameter, it is automatically converted to the expected one. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float. Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); type ComplexDiagram( Choice (0, 'int', 'float') ).addTo() argtype ComplexDiagram( Choice (0, 'int', 'float', 'any') ).addTo() Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate. Foreign variables and constants External variables and constants can also be declared with a similar syntax. In the same \"maths.lib\" file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found : SR = min(192000.0, max(1.0, fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block. Include file In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include... in the generated code. includefile ComplexDiagram( Choice (0, Sequence ('<', OneOrMore (NonTerminal('char')), '>'), Sequence ('\"', OneOrMore (NonTerminal('char')), '\"')) ).addTo() Library file In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model. Applications and Abstractions Abstractions and applications are fundamental programming constructions directly inspired by the Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. progexp ComplexDiagram( Choice (0, NonTerminal('abstraction'), NonTerminal('application')) ).addTo() Abstractions Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. abstraction ComplexDiagram( Choice (0, NonTerminal('lambdaabstraction'), NonTerminal('patternabstraction')) ).addTo() lambdaabstraction ComplexDiagram( Sequence (NonTerminal('\\'), '(', OneOrMore (NonTerminal('ident'), ','), ')', '.', '(', NonTerminal('expression'), ')') ).addTo() Let's say you want to transform a stereo reverb, freeverb for instance, into a mono effect. You can write the following expression: _ <: freeverb :> _ The incoming mono signal is splitted to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that you are interested in transforming other stereo effects. It can be interesting to generalize this principle by making freeverb a variable: \\(freeverb).(_ <: freeverb :> _) The resulting abstraction can then be applied to transform other effects. Note that if freeverb is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) Moreover it could be convenient to give a name to this abstraction: mono = \\(fx).(_ <: fx :> _); Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _; Applications Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. application ComplexDiagram( Sequence (NonTerminal('expression'), '(', OneOrMore (NonTerminal('expression'), ','), ')') ).addTo() For example you can apply the previous abstraction to transform your stereo harmonizer: mono(harmonizer) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(harmonizer) Whenever the Faust compiler find an application of an abstraction it replaces Replacing the variable part with the argument is called \\beta -reduction in Lambda-Calculus} the \\emph{variable part with the argument. The resulting expression is as expected: (_ <: harmonizer :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments). Unapplied abstractions Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values\\footnote{ https://en.wikipedia.org/wiki/First-class_function } which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: import(\"stdfaust.lib\"); repeat(fx) = fx : fx; process = repeat(dm.zita_light); In Faust, a proper semantic has been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: process = _,_ <: !,_,_,!; can be simply defined as: process = \\(x,y).(y,x); which is actually equivalent to: process(x,y) = y,x; Pattern Matching Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. patternabstraction ComplexDiagram( Sequence (\"case\", NonTerminal('{'), OneOrMore (NonTerminal('rule')), NonTerminal('}')) ).addTo() Rule ComplexDiagram( Sequence ('(', OneOrMore (NonTerminal('pattern'), ','), ')', \"=>\", NonTerminal('expression'), ';') ).addTo() Pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(freeverb:harmonizer) will produce: (harmonizer:freeverb) Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching. Primitives The primitive signal processing operations represent the built-in functionalities of Faust , that is the atomic operations on signals provided by the language. All these primitives denote signal processors , functions transforming input signals into output signals . primitive ComplexDiagram( Choice (0, NonTerminal('number'), NonTerminal('route'), NonTerminal('waveform'), NonTerminal('soundfile'), NonTerminal('cprimitive'), NonTerminal('mathprimitive'), NonTerminal('delayandtables'), NonTerminal('uielements'), NonTerminal('%ulation')) ).addTo() Numbers Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. int ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() float ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), Choice (0, Sequence (NonTerminal('digit+'), '.', NonTerminal('digit*')), Sequence (NonTerminal('digit*'), '.', NonTerminal('digit+'))), Optional ( NonTerminal('exponent'))) ).addTo() exponent ComplexDiagram( Sequence ('e', Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() digit ComplexDiagram( \"0--9\" ).addTo() Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type. Route Primitive The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: - <span class=\"lstinline\">A</span> is the number of input signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">B</span> is the number of output signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">a,b / (a,b)</span> is an input/output pair, as integers _constant numerical expressions_, automatically promoted to _int_ Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: process = route(2,2,1,2,2,1); In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: process = route(2,2,(1,2),(2,1)); More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: // cross 10 signals: // input 0 -> output 10, // input 1 -> output 9, // ..., // input 9 -> output 0 N = 10; r = route(N,N,par(i,N,(i+1,N-i))); process = r; Waveform Primitive A waveform is a fixed periodic signal defined by a list of samples as literal numbers. A waveform has two outputs. The first output is constant and indicates the size (number of samples) of the period. The second output is the periodic signal itself. waveform ComplexDiagram( Sequence (\"waveform\", NonTerminal('{'), OneOrMore (NonTerminal('number'), ','), NonTerminal('}')) ).addTo() For example waveform {0,1,2,3} produces two outputs, the constant signal 4 and the periodic signal 0,1,2,3,0,1,2,3,0,1 \\ldots. Please note that waveform works nicely with rdtable . Its first output, known at compile time, gives the size of the table, while the second signal gives the content of the table. Here is an example: process = waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable; Soundfile Primitive The soundfile(\"label[url:{ path1';'path2';'path3';}]\", n)' primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the '%i' syntax, as in the label part). The soundfile(\"label[url:path]\", n) , or soundfile(\"label\", n) (where label is used as the soundfile path) simplified syntax allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: - two inputs: the sound number (as a integer between 0 and 255, automatically promoted to _int_), and the read index in the sound (automatically promoted to _int_, which will access the last sample of the sound if the read index is greater than the sound length) - two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound - <span class=\"lstinline\">n</span> several more outputs for the sound channels themselves, as a integer _constant numerical expression_ If more outputs than the actual number of channels in the soundfile are used, the sound channels will be automatically duplicated up to the wanted number of outputs (so for instance if a stereo sound is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file implements the void addSoundfile(label, url, sf_zone) method, which loads the actual soundfiles using the {\\it libsndfile} library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that a special architecture file can perfectly decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge to actually setup all sound memory pointers when void addSoundfile(label, url, sf_zone) is called by the buidUserInterface mechanism. C-equivalent primitives Most Faust primitives are analogue to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form Warning: unlike other programming languages the unary operatior - only exists in limited form in Faust . It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance -(a * b) is a partial application. It is syntactic sugar for _,(a * b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a * b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Syntax Type Description n \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} integer number: y(t)=n n.m \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} floating point number: y(t)=n.m _ \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} identity function: y(t)=x(t) ! \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} cut function: \\forall x\\in\\mathbb{S},(x)\\rightarrow () int \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an int signal: y(t)=(int)x(t) float \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an float signal: y(t)=(float)x(t) + \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} addition: y(t)=x_{1}(t)+x_{2}(t) - \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} subtraction: y(t)=x_{1}(t)-x_{2}(t) * \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} multiplication: y(t)=x_{1}(t)*x_{2}(t) \\land \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=x_{1}(t)^{x_{2}(t)} / \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} division: y(t)=x_{1}(t)/x_{2}(t) % \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} modulo: y(t)=x_{1}(t)%x_{2}(t) \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} | \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise OR: y(t)=x_{1}(t)\\|x_{2}(t) xor \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise XOR: y(t)=x_{1}(t)\\land x_{2}(t) << \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift left: y(t)=x_{1}(t) << x_{2}(t) >> \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift right: y(t)=x_{1}(t) >> x_{2}(t) < \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less than: y(t)=x_{1}(t) < x_{2}(t) <= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less or equal: y(t)=x_{1}(t) <= x_{2}(t) > \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater than: y(t)=x_{1}(t) > x_{2}(t) >= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater or equal: y(t)=x_{1}(t) >= x_{2}(t) == \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} equal: y(t)=x_{1}(t) == x_{2}(t) != \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} different: y(t)=x_{1}(t) != x_{2}(t) math.h-equivalent primitives Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. Syntax Type Description acos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc cosine: y(t)=\\mathrm{acosf}(x(t)) asin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc sine: y(t)=\\mathrm{asinf}(x(t)) atan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atanf}(x(t)) atan2 \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) cos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cosine: y(t)=\\mathrm{cosf}(x(t)) sin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} sine: y(t)=\\mathrm{sinf}(x(t)) tan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} tangent: y(t)=\\mathrm{tanf}(x(t)) exp \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e exponential: y(t)=\\mathrm{expf}(x(t)) log \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e logarithm: y(t)=\\mathrm{logf}(x(t)) log10 \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-10 logarithm: y(t)=\\mathrm{log10f}(x(t)) pow \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) sqrt \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} square root: y(t)=\\mathrm{sqrtf}(x(t)) abs \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} absolute value (int): y(t)=\\mathrm{abs}(x(t)) absolute value (float): y(t)=\\mathrm{fabsf}(x(t)) min \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} minimum: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) max \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} maximum: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) fmod \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float modulo: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) remainder \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float remainder: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) floor \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} largest int \\leq : y(t)=\\mathrm{floorf}(x(t)) ceil \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} smallest int \\geq : y(t)=\\mathrm{ceilf}(x(t)) rint \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} closest int using the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) round \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} nearest int value, regardless of the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) Delay, Table, Selector primitives The following primitives allow to define delays, read-only and read-write tables and 2 or 3-ways selectors (see figure fig-delays ), and some other specific primitives. Syntax Type Description mem \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x(t),y(0)=0 prefix \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x_{2}(t),y(0)=x_{1}(0) @ \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} variable delay: y(t)=x_{1}(t-x_{2}(t)), x_{1}(t<0)=0 rdtable \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} read-only table: y(t)=T[r(t)] rwtable \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} read-write table: T[w(t)]=c(t); y(t)=T[r(t)] select2 \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} select between 2 signals: T[]={x_{0}(t),x_{1}(t)}; y(t)=T[s(t)] select3 \\mathbb{S}^{4}\\rightarrow\\mathbb{S}^{1} select between 3 signals: T[]={x_{0}(t),x_{1}(t),x_{2}(t)}; y(t)=T[s(t)] lowest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\min_{j=0}^{\\inf} x(j) highest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\max_{j=0}^{\\inf} x(j) <a name=\"fig-delays\"></a> Delays, tables and selectors primitives The size input of rdtable and rwtable are integer constant numerical expressions automatically promoted to int , and the read and write indexes are also automatically promoted to int . The delay value is automatically promoted to int . User Interface Elements Faust user interface widgets allow an abstract description of the user interface from within the Faust code. This description is independent of any GUI toolkits. It is based on buttons , checkboxes , sliders , etc. that are grouped together vertically and horizontally using appropriate grouping schemes. All these GUI elements produce signals. A button for example (see figure fig-button ) produces a signal which is 1 when the button is pressed and 0 otherwise. These signals can be freely combined with other audio signals. <a name=\"fig-button\"></a> User Interface Button Syntax Example button( str ) button(\"play\") checkbox( str ) checkbox(\"mute\") vslider( str , cur , min , max , step ) vslider(\"vol\",50,0,100,1) hslider( str , cur , min , max , step ) hslider(\"vol\",0.5,0,1,0.01) nentry( str , cur , min , max , step ) nentry(\"freq\",440,0,8000,1) vgroup( str , block-diagram ) vgroup(\"reverb\", \\ldots) hgroup( str , block-diagram ) hgroup(\"mixer\", \\ldots) tgroup( str , block-diagram ) tgroup(\"parametric\", \\ldots) vbargraph( str , min , max ) vbargraph(\"input\",0,100) hbargraph( str , min , max ) hbargraph(\"signal\",0,1.0) attach attach(x, vumeter(x)) All numerical parameters (like {\\it cur}, {\\it min}, {\\it max}, {\\it step}) are constant numerical expressions . Labels Every user interface widget has a label (a string) that identifies it and informs the user of its purpose. There are three important mechanisms associated with labels (and coded inside the string): variable parts , pathnames and metadata . Variable parts. Labels can contain variable parts. These variable parts are indicated by the sign '%' followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example par(i,8,hslider(\"Voice %i\", 0.9, 0, 1, 0.01)) creates 8 different sliders in parallel : hslider(\"Voice 0\", 0.9, 0, 1, 0.01), hslider(\"Voice 1\", 0.9, 0, 1, 0.01), ... hslider(\"Voice 7\", 0.9, 0, 1, 0.01). while par(i,8,hslider(\"Voice\", 0.9, 0, 1, 0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Pathnames. Thanks to horizontal, vertical and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated pathname obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of: hslider(\"../volume\",...) would have been \"/h:Foo/volume\" , while the pathname of: hslider(\"t:Fii/volume\",...) would have been: \"/h:Foo/v:Faa/t:Fii/volume\" . The grammar for labels with pathnames is the following: label ComplexDiagram( Sequence (NonTerminal('path'), NonTerminal('name')) ).addTo() path ComplexDiagram( Sequence (Optional ( '/'), Optional ( OneOrMore (Sequence (NonTerminal('folder'), '/')))) ).addTo() folder ComplexDiagram( Choice (0, \"..\", Sequence (Choice (0, \"h:\", \"v:\", \"t:\"), NonTerminal('name'))) ).addTo() Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface. The Faust code: process = *(hslider(\"foo [key1: val 1][key2: val 2]\", 0, 0, 1, 0.1)); will produce and the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* interface) { interface->openVerticalBox(\"m\"); interface->declare(&fslider0, \"key1\", \"val 1\"); interface->declare(&fslider0, \"key2\", \"val 2\"); interface->addHorizontalSlider(\"foo\", &fslider0, 0.0f, 0.0f, 1.0f, 0.1f); interface->closeBox(); } ... }; All the metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. It is the role of the architecture file to decide what to do with these metadata. The jack-qt.cpp architecture file for example implements the following: - \"...[style:knob]...\" creates a rotating knob instead of a regular slider or nentry. - \"...[style:led]...\" in a bargraph's label creates a small LED instead of a full bargraph - \"...[unit:dB]...\" in a bargraph's label creates a more realistic bargraph with colors ranging from green to red depending of the level of the value - \"...[unit:xx]...\" in a widget postfixes the value displayed with xx - \"...[tooltip:bla bla]...\" add a tooltip to the widget - \"...[osc:/address min max]...\" Open Sound Control message alias Moreover starting a label with a number option like in \"[1]...\" provides a convenient means to control the alphabetical order of the widgets. Attach The attach primitive takes two input signals and produce one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical point of view attach(x,y) is equivalent to 1 x+0 y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role let say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelop detector connected to a bargraph. The problem is that these envelop signals have no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled. Widget Modulation Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: modulation Here is a very simple example of widget modulation, assuming freeverb is a fully functional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb] Target Widgets Target widgets are specified by their label. Of course, this presupposes knowing the names of the widgets. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb] Modulators Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: Please note that the `':'` sign used here is just a visual separator, it is not the sequential composition operator. [\"Wet\": * -> freeverb] To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the target widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs.","title":"3 syntax"},{"location":"qreference/3-syntax/#faust-syntax","text":"This section describes the syntax of Faust . Figure fig-syntax gives an overview of the various concepts and where they are defined in this section. Overview of Faust syntax As we will see, definitions and expressions have a central role.","title":"Faust syntax"},{"location":"qreference/3-syntax/#faust-program","text":"A Faust program is essentially a list of statements . These statements can be declarations , imports , definitions and documentation tags , with optional C++ style (//... and / ... /) comments. program ComplexDiagram( OneOrMore (NonTerminal('statement')) ).addTo()","title":"Faust program"},{"location":"qreference/3-syntax/#a-simple-program","text":"Here is a short Faust program that implements of a simple noise generator. It exhibits various kind of statements: two declarations , an import , a comment and a definition . We will see later on documentation statements ( sec-documentation ). declare name \"noise\"; declare copyright \"(c)GRAME 2006\"; import(\"music.lib\"); // noise level controlled by a slider process = noise * vslider(\"volume\", 0, 0, 1, 0.1); The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process .","title":"A Simple Program"},{"location":"qreference/3-syntax/#statements","text":"The statements of a Faust program are of four kinds: metadata declarations , file imports , definitions and documentation . All statements but documentation end with a semicolon ( ; ). statement ComplexDiagram( Choice (0, NonTerminal('declaration'), NonTerminal('fileimport'), NonTerminal('definition'), NonTerminal('documentation')) ).addTo()","title":"Statements"},{"location":"qreference/3-syntax/#declarations","text":"Meta-data declarations (for example declare name \"noise\"; ) are optional and typically used to document a Faust project. declaration ComplexDiagram( Sequence (\"declare\", NonTerminal('key'), NonTerminal('string'), ';') ).addTo() key ComplexDiagram( NonTerminal('identifier') ).addTo() Contrary to regular comments, these declarations will appear in the C++ code generated by the compiler. A good practice is to start a Faust program with some standard declarations: declare name \"MyProgram\"; declare author \"MySelf\"; declare copyright \"MyCompany\"; declare version \"1.00\"; declare license \"BSD\";","title":"Declarations"},{"location":"qreference/3-syntax/#imports","text":"File imports allow to import definitions from other source files. fileimport ComplexDiagram( Sequence (\"import\", '(', NonTerminal('filename'), ')', ';') ).addTo() For example import(\"maths.lib\"); imports the definitions of the maths.lib library, a set of additional mathematical functions provided as foreign functions.","title":"Imports"},{"location":"qreference/3-syntax/#documentation","text":"Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed chapter \\ref{chapter-mdoc}. In this section we will essentially describe the documentation statements syntax. A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in LaTeX format, can be placed in between these two tags. documentation ComplexDiagram( Sequence (\"<mdoc>\", OneOrMore (Choice (0, NonTerminal('freetext'), NonTerminal('equation'), NonTerminal('diagram'), NonTerminal('metadata'), NonTerminal('notice'), NonTerminal('listing'))), \"</mdoc>\") ).addTo() Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations , graphical block-diagrams , Faust source code listing and explanation notice . equation ComplexDiagram( Sequence (\"<equation>\", NonTerminal('expression'), \"</equation>\") ).addTo() The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program. diagram ComplexDiagram( Sequence (\"<diagram>\", NonTerminal('expression'), \"</diagram>\") ).addTo() Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program. metadata ComplexDiagram( Sequence (\"<metadata>\", NonTerminal('keyword'), \"</metadata>\") ).addTo() The <metadata> tags allow to reference Faust metadatas (cf. declarations), calling the corresponding keyword. notice ComplexDiagram( \"<notice />\" ).addTo() The <notice /> empty-element tag is used to generate the conventions used in the mathematical equations. listing ComplexDiagram( Sequence (\"<listing\", NonTerminal('listingattribute*'), \" />\") ).addTo() listingattribute ComplexDiagram( Sequence (Choice (0, \"mdoctags\", \"dependencies\", \"distributed\"), \"=\", Choice (0, '\"true\"', '\"false\"')) ).addTo() The <listing /> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags , dependencies and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved faust code between sections.","title":"Documentation"},{"location":"qreference/3-syntax/#definitions","text":"A definition associates an identifier with an expression it stands for. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition.","title":"Definitions"},{"location":"qreference/3-syntax/#simple-definitions","text":"The syntax of a simple definition is: definition ComplexDiagram( Sequence (NonTerminal('identifier'), '=', NonTerminal('expression'), ';') ).addTo() For example here is the definition of random , a simple pseudo-random number generator: random = +(12345) ~ *(1103515245);","title":"Simple Definitions"},{"location":"qreference/3-syntax/#function-definitions","text":"Definitions with formal parameters correspond to functions definitions. fdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('parameter'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() For example the definition of linear2db , a function that converts linear values to decibels, is : linear2db(x) = 20*log10(x); Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction: linear2db = \\(x).(20*log10(x));","title":"Function Definitions"},{"location":"qreference/3-syntax/#definitions-with-pattern-matching","text":"Moreover, formal parameters can also be full expressions representing patterns. pdefinition ComplexDiagram( Sequence (NonTerminal('identifier'), '(', OneOrMore (NonTerminal('pattern'), ','), ')', '=', NonTerminal('expression'), ';') ).addTo() pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel: duplicate(1,x) = x; duplicate(n,x) = x, duplicate(n-1,x); Please note that this last definition is a convenient alternative to the more verbose : duplicate = case { (1,x) => x; (n,x) => duplicate(n-1,x); }; Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition : (1,2,3,5,7,11). The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element : count((x,xs)) = 1+count(xs); count(x) = 1; If we now write count(duplicate(10,666)) the expression will be evaluated to 10 . Please note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in : count(x) = 1; count((x,xs)) = 1+count(xs); the first rule will always match and the second rule will never be called. Please note that number arguments in pattern matching rules are typically constant numerical expressions , so can be the result of more complex expressions involving computations done at compile-time.","title":"Definitions with pattern matching"},{"location":"qreference/3-syntax/#variants","text":"Some statements (imports, definitions) can be preceded by a variantlist, composed of variants which can be singleprecision , doubleprecision , quadprecision or fixedpointprecision This allows some imports and definitions to be effective only for a (or several) specific float precision option in the compiler (that is either -single , -double , -quad or -fx respectively). A typical use-case is the definition of floating point constants in the maths.lib library with the following lines: singleprecision MAX = 3.402823466e+38; doubleprecision MAX = 1.7976931348623158e+308;","title":"Variants"},{"location":"qreference/3-syntax/#expressions","text":"Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions. expression ComplexDiagram( Choice (0, NonTerminal('diagram'), NonTerminal('insouts'), NonTerminal('numerical'), NonTerminal('time'), NonTerminal('lexical'), NonTerminal('foreign'), NonTerminal('lambda')) ).addTo()","title":"Expressions"},{"location":"qreference/3-syntax/#constant-numerical-expressions","text":"Some language primitives (like rdtable , rwtable , hslider etc.) take constant numbers as some of their parameters. This is the case also for expressions using pattern matching techniques. Those numbers can be directly given in the code, but can also be computed by more complex expressions which have to produce numbers at compile time. We will refer to them as constant numerical expressions in the documentation.","title":"Constant Numerical Expressions"},{"location":"qreference/3-syntax/#diagram-expressions","text":"Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions. diagramexp ComplexDiagram( Choice (0, NonTerminal('diagcomposition'), NonTerminal('diagiteration')) ).addTo()","title":"Diagram Expressions"},{"location":"qreference/3-syntax/#diagram-composition-operations","text":"Five binary composition operations are available to combine block-diagrams: recursion , parallel , sequential , split and merge composition. One can think of each of these composition operations as a particular way to connect two block diagrams. diagcomposition ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('~'), ',', ':', '<:', ':>'), NonTerminal('expression')) ).addTo() To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a bloc-diagram A are notated \\mathrm{inputs}(A) and \\mathrm{outputs}(A) . The inputs and outputs themselves are respectively notated : [0]A , [1]A , [2]A , \\ldots and A[0] , A[1] , A[2] , etc.. For each composition operation between two block-diagrams A and B we will describe the connections A[i]\\rightarrow [j]B that are created and the constraints on their relative numbers of inputs and outputs. The priority and associativity of this five operations are given table table-composition . Please note that a higher priority value means a higher priority in the evaluation order. There is a companion table infix-comparison-priority that gives the associativity of each numerical operator in infix expressions. Syntax Pri. Assoc. Description expression \\ \\sim \\ expression 4 left recursive composition expression \\ ,\\ expression 3 right parallel composition expression \\ :\\ expression 2 right sequential composition expression \\ <:\\ expression 1 right split composition expression \\ :>\\ expression 1 right merge composition Block-Diagram composition operation priorities Parallel Composition The parallel composition (A,B) (figure figure-par1 ) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B . The outputs of the resulting block-diagram are the outputs of A and B . Parallel composition is an associative operation : (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used : A,B,C,D , Faust uses right associativity and therefore build internally the expression (A,(B,(C,D))) . This organization is important to know when using pattern matching techniques on parallel compositions. Example of parallel composition (10,*) Sequential Composition The sequential composition A:B (figure figure-seq1 ) expects: \\mathrm{outputs}(A)=\\mathrm{inputs}(B) It connects each output of A to the corresponding input of B : A[i]\\rightarrow[i]B Example of sequential composition ((*,/):+) Sequential composition is an associative operation : (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D , Faust uses right associativity and therefore build internally the expression (A:(B:(C:D))) . Split Composition The split composition A<:B (figure figure-split1 ) operator is used to distribute the outputs of A to the inputs of B . example of split composition ((10,20) <: (+,*,/)) Each input i of B is connected to the output i \\bmod k of A : Merge Composition The merge composition A:>B (figure figure-merge1 ) is the dual of the split composition . The number of outputs of A must be a multiple of the number of inputs of B : Each output i of A is connected to the input i \\bmod k of B : The k incoming signals of an input of B are summed together. example of merge composition ((10,20,30,40) :> *) Recursive Composition The recursive composition A~B (figure figure-rec1 ) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections. To be applicable it requires that : Each input of B is connected to the corresponding output of A via an implicit 1-sample delay : A[i]\\stackrel{Z^{-1}}{\\rightarrow}[i]B and each output of B is connected to the corresponding input of A : B[i]\\rightarrow [i]A The inputs of the resulting block diagram are the remaining unconnected inputs of A . The outputs are all the outputs of A . example of recursive composition +(12345) ~ *(1103515245)","title":"Diagram composition operations"},{"location":"qreference/3-syntax/#inputs-and-outputs-of-an-expression","text":"These two constructions can be used to know at compile time the number of inputs and outputs of any Faust expression. insouts ComplexDiagram( Choice (0, Sequence (\"inputs\", '(', NonTerminal('expression'), ')'), Sequence (\"outputs\", '(', NonTerminal('expression'), ')')) ).addTo() They are useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression. Xo(expr) = expr <: par(i,n,selector(n-i-1,n)) with { n=outputs(expr); }; And the inputs of an expression : Xi(expr) = bus(n) <: par(i,n,selector(n-i-1,n)) : expr with { n=inputs(expr); }; For example Xi(-) will reverse the order of the two inputs of the substraction.","title":"Inputs and outputs of an expression"},{"location":"qreference/3-syntax/#iterations","text":"Iterations are analogous to for(...) loops and provide a convenient way to automate some complex block-diagram constructions. diagiteration ComplexDiagram( Choice (0, Sequence (\"par\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"seq\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"sum\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')'), Sequence (\"prod\", '(', NonTerminal('ident'), ',', NonTerminal('numiter'), ',', NonTerminal('expression'), ')')) ).addTo() The following example shows the usage of seq to create a 10-bands filter: process = seq(i, 10, vgroup(\"band %i\", bandfilter( 1000*(1+i) ) ) ); numiter ComplexDiagram( NonTerminal('expression') ).addTo() The number of iterations must be a constant expression.","title":"Iterations"},{"location":"qreference/3-syntax/#infix-notation","text":"Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in \\(2+3\\)}Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar \\emph{infix notation . For example if you want to multiply two numbers, let say 2 and 3 , you can write directly 2 3 instead of the equivalent core-syntax expression 2,3: . The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example you can write /2 . It is equivalent to ,2:/ which divides the incoming signal by 2 . Examples of equivalences are given table tab-infixrules . 2-3 \\equiv 2,3 : - 2*3 \\equiv 2,3 : * _@7 \\equiv _,7 : @ _/2 \\equiv _,2 : / A<B \\equiv A,B : < Infix and core syntax equivalences In case of doubts on the meaning of an infix expression, for example _ , it is useful to translate it to its core syntax equivalent, here ,_: , which is equivalent to * . Built-in primitives that can be used in infix notation are called infix operators and are listed in this section. Please note that a more detailed description of these operators is available section primitives .","title":"Infix Notation"},{"location":"qreference/3-syntax/#comparison-operators","text":"Comparison operators compare two signals and produce a signal that is 1 when the comparison is true and 0 when the comparison is false. comparison ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '<', '<=', '>', '>=', '==', '!='), NonTerminal('expression')) ).addTo() The priority and associativity of the comparison operators is given table infix-comparison-priority . Syntax Pri. Assoc. Description expression \\ <\\ expression 5 left less than expression \\ <=\\ expression 5 left less or equal expression \\ !=\\ expression 5 left different expression \\ >=\\ expression 5 left greater or equal expression \\ >\\ expression 5 left greater than Comparison operators priorities in infix expressions","title":"Comparison Operators"},{"location":"qreference/3-syntax/#math-operators","text":"Math operators combine two signals and produce a resulting signal by applying a numerical operation on each sample. math ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, '+', '-', '*', '/', '%', NonTerminal('\u22c0')), NonTerminal('expression')) ).addTo() The priority and associativity of the math operators is given table infix-math-priority . Syntax Pri. Assoc. Description expression \\ +\\ expression 6 left addition expression \\ -\\ expression 6 left subtraction expression \\ *\\ expression 7 left multiplication expression \\ /\\ expression 7 left division expression \\ %\\ expression 7 left modulo expression \\ \\^\\ expression 8 left power Math operators priorities in infix expressions","title":"Math Operators"},{"location":"qreference/3-syntax/#bitwise-operators","text":"Bitwise operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. bitwise ComplexDiagram( Sequence (NonTerminal('expression'), Choice (0, NonTerminal('|'), NonTerminal('&'), 'xor', '<<', '>>'), NonTerminal('expression')) ).addTo() The priority and associativity of the bitwise operators is given table infix-bitwise-priority . Syntax Pri. Assoc. Description expression \\ |\\ expression 6 left bitwise or expression \\ \\ expression 7 left expression \\ xor\\ expression 7 left bitwise xor expression \\ <<\\ expression 7 left bitwise left shift expression \\ >>\\ expression 7 left bitwise right shift Bitwise operators priorities in infix expressions","title":"Bitwise operators"},{"location":"qreference/3-syntax/#delay-operators","text":"Delay operators combine two signals and produce a resulting signal by applying a bitwise operation on each sample. delay ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay operator @ allows to delay left handside expression by the amount defined by the right handside expression. The unary operator \"'\" delays the left handside expression by one sample. The priority and associativity of the delay operators is given table infix-delay-priority . Syntax Pri. Assoc. Description expression \\ @\\ expression 9 left variable delay expression \\' 10 left one-sample delay Delay operators priorities in infix expressions","title":"Delay operators"},{"location":"qreference/3-syntax/#prefix-notation","text":"Beside infix notation , it is also possible to use prefix notation . The prefix notation is the usual mathematical notation for functions f(x,y,z,\\ldots) , but extended to infix operators . *(2,3) \\equiv 2,3 : * @(_,7) \\equiv _,7 : @ /(_,2) \\equiv _,2 : / <(A,B) \\equiv A,B : < Prefix to core syntax translation rules It consists in first having the operator, for example / , followed by its arguments between parentheses: /(2,3) (see table tab-prefixrules ).","title":"Prefix Notation"},{"location":"qreference/3-syntax/#partial-application","text":"The partial application notation is a variant of prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube) and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that \"waits\" for the remaining arguments. When doing partial application with an infix operator , it is important to note that the supplied argument is not the first argument, but always the second one, as summarized table tab-partialrules . +(C) \\equiv _,C:* -(C) \\equiv _,C:- <(C) \\equiv _,C:< /(C) \\equiv _,C:/ Partial application of infix operators For commutative operations that doesn't matter. But for non-commutative ones, it is more ``natural'' to fix the second argument. We use divide by 2 ( /(2) ) or rise to the cube ( ^(3) ) more often than the other way around. Please note that this rule only applies to infix operators, not other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter.","title":"Partial Application"},{"location":"qreference/3-syntax/#time-expressions","text":"Time expressions are used to express delays. The notation X@10 represent the signal X delayed by 10 samples. The notation \"X'\" represent the signal X delayed by one sample and is therefore equivalent to X@1 . time ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), NonTerminal('@'), NonTerminal('expression')), Sequence (NonTerminal('expression'), NonTerminal('''))) ).addTo() The delay (automatically promoted to int ) don't have to be fixed, but it must be positive and bounded. The values of a slider are perfectly acceptable as in the following example: process = _ @ hslider(\"delay\",0, 0, 100, 1);","title":"Time expressions"},{"location":"qreference/3-syntax/#environment-expressions","text":"Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use. To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures . The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design. envexp ComplexDiagram( Choice (0, Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), NonTerminal('definition+'), NonTerminal('}')), Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')), Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')), Sequence (NonTerminal('expression'), '.', NonTerminal('ident')), Sequence ('library', '(', NonTerminal('filename'), ')'), Sequence ('component', '(', NonTerminal('filename'), ')'), Sequence (NonTerminal('expression'), '[', OneOrMore (NonTerminal('definition')), ']')) ).addTo()","title":"Environment expressions"},{"location":"qreference/3-syntax/#with","text":"The with construction allows to specify a local environment , a private list of definition that will be used to evaluate the left hand expression withexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'with', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example : pink = f : + ~ g with { f(x) = 0.04957526213389*x - 0.06305581334498*x' + 0.01483220320740*x''; g(x) = 1.80116083982126*x - 0.80257737639225*x'; }; the definitions of f(x) and g(x) are local to f : + ~ g . Please note that with is left associative and has the lowest priority: f : + ~ g with {...} is equivalent to (f : + ~ g) with {...} . f : + ~ g with {...} with {...} is equivalent to ((f : + ~ g) with {...}) with {...} .","title":"With"},{"location":"qreference/3-syntax/#letrec","text":"The letrec construction is somehow similar to with , but for difference equations instead of regular definitions. It allows to easily express groups of mutually recursive signals, for example: x(t)&=&y(t-1)+10; y(t)&=&x(t-1)-1; as E letrec { 'x = y+10; 'y = x-1; } The syntax is defined by the following rules: letrecexpression ComplexDiagram( Sequence (NonTerminal('expression'), 'letrec', NonTerminal('{'), OneOrMore (NonTerminal('diffequation')), Choice (0, Skip(), Sequence ('where', OneOrMore (NonTerminal('definition')))), NonTerminal('}')) ).addTo() diffequation ComplexDiagram( Sequence (NonTerminal('''), NonTerminal('ident'), '=', NonTerminal('expression'), ';') ).addTo() Please remarks the special notation 'x=y+10 instead of x=y'+10 . It makes syntactically impossible to write non-sensical equations like x=x+1 . Here is a more involved example. Let say we want to define an envelop generator with an attack time, a release time and a gate signal. A possible definition is the following: ar(a,r,g) = v letrec { 'n = (n+1) * (g<=g'); 'v = max(0, v + (n<a)/a - (n>=a)/r) * (g<=g'); }; With the following semantics for n(t) and v(t) : n(t)&=&(n(t-1)+1) * (g(t) <= g(t-1)) v(t)&=& max(0, v(t-1) + (n(t-1) =a(t))/r(t)) * (g(t)<=g(t-1)) In order to factor some expressions common to several recursive definitions, we can use the clause where followed by one or more definitions. These definitions will only be visible to the recursive equations of the letrec , but not to the outside world, unlike the recursive definitions themselves. For instance in the previous example we can factorize (g<=g) leading to the following expression: ar(a,r,g) = v letrec { 'n = (n+1) * c; 'v = max(0, v + (n<a)/a - (n>=a)/r) * c; where c = g<=g'; }; Please note that letrec is essentially syntactic sugar. Here is an example of 'letrec': x,y letrec { x = defx; y = defy; z = defz; where f = deff; g = defg; }; and its translation as done internally by the compiler: x,y with { x = BODY : _,!,!; y = BODY : !,_,!; z = BODY : !,!,_; BODY = \\(x,y,z).((defx,defy,defz) with {f=deff; g=defg;}) ~ (_,_,_); };","title":"Letrec"},{"location":"qreference/3-syntax/#environment","text":"The environment construction allows to create an explicit environment. It is like a with , but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy. environment ComplexDiagram( Sequence ('environment', NonTerminal('{'), OneOrMore (NonTerminal('definition')), NonTerminal('}')) ).addTo() In the following example an environment construction is used to group together some constant definitions : constant = environment { pi = 3.14159; e = 2.718; ... }; The . construction allows to access the definitions of an environment (see next paragraph).","title":"Environment"},{"location":"qreference/3-syntax/#access","text":"Definitions inside an environment can be accessed using the '.' construction. access ComplexDiagram( Sequence (NonTerminal('expression'), '.', NonTerminal('ident')) ).addTo() For example constant.pi refers to the definition of pi in the above constant environment. Please note that environment don't have to be named. We could have written directly environment{pi = 3.14159; e = 2.718; ... }.pi","title":"Access"},{"location":"qreference/3-syntax/#library","text":"The library construct allows to create an environment by reading the definitions from a file. library ComplexDiagram( Sequence ('library', '(', NonTerminal('filename'), ')') ).addTo() For example library(\"miscfilter.lib\") represents the environment obtained by reading the file \"miscfilter.lib\". It works like import(\"miscfilter.lib\") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library(\"miscfilter.lib\").lowpass denotes the function lowpass as defined in the file \"miscfilter.lib\" . To avoid name conflicts when importing libraries it is recommended to prefer library to import . So instead of : import(\"miscfilter.lib\"); ... ...lowpass.... ... }; the following will ensure an absence of conflicts : fl = library(\"miscfilter.lib\"); ... ...fl.lowpass.... ... };","title":"Library"},{"location":"qreference/3-syntax/#component","text":"The component(...) construction allows to reuse a full Faust program as a simple expression. component ComplexDiagram( Sequence ('component', '(', NonTerminal('filename'), ')') ).addTo() For example component(\"freeverb.dsp\") denotes the signal processor defined in file \"freeverb.dsp\". Components can be used within expressions like in: ...component(\"karplus32.dsp\"):component(\"freeverb.dsp\")... Please note that component(\"freeverb.dsp\") is equivalent to library(\"freeverb.dsp\").process .","title":"Component"},{"location":"qreference/3-syntax/#explicit-substitution","text":"Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it. explicitsubst ComplexDiagram( Sequence (NonTerminal('expression'), \"[\", OneOrMore (NonTerminal('definition')), \"]\") ).addTo() For example we can create a customized version of component(\"freeverb.dsp\") , with a different definition of foo(x) , by writing : ...component(\"freeverb.dsp\")[foo(x) = ...;]... };","title":"Explicit substitution"},{"location":"qreference/3-syntax/#foreign-expressions","text":"Reference to external (foreign) C functions , variables and constants can be introduced using the foreign expressions mechanism. foreignexp ComplexDiagram( Choice (0, Sequence ('ffunction', '(', NonTerminal('signature'), ',', NonTerminal('includefile'), ',', NonTerminal('library'), ')'), Sequence ('fvariable', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')'), Sequence ('fconstant', '(', NonTerminal('type'), NonTerminal('identifier'), ',', NonTerminal('includefile'), ')')) ).addTo()","title":"Foreign expressions"},{"location":"qreference/3-syntax/#foreign-function-declaration","text":"An external C function is declared by indicating its name and signature as well as the required include file. The file \"maths.lib\" of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh is defined as follows asinh = ffunction(float asinhf|asinh|asinhl|asinfx(float), <math.h>, \"\"); The signature part of a foreign function, float asinhf|asinh|asinhl|asinfx(float) in our previous example, describes the prototype of the C function: its return type, function names and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double, quad and fixed-point), it is possible to give a different function name for each floating point precision using a signature with up to four function names. In our example, the asinh function is called asinhf in single precision, asinh in double precision, asinhl in quad precision, and asinhfx in fixed-point precision. This is why the four names are provided in the signature. signature ComplexDiagram( Sequence (NonTerminal('type'), NonTerminal('funnames'), '(', OneOrMore (NonTerminal('argtype'), ','), ')') ).addTo() funnames ComplexDiagram( Sequence (NonTerminal('identifier'), Optional ( Sequence ('|', NonTerminal('identifier'))), Optional ( Sequence ('|', NonTerminal('identifier')))) ).addTo() Foreign functions generally expect a precise type: ( int or float ) for their parameters. Note that currently only numerical functions involving scalar parameters are allowed. No vectors, tables or data structures can be passed as parameters or returned. During the compilation if the type of an argument is not the same as the type of the parameter, it is automatically converted to the expected one. Some foreign functions are polymorphic and can accept either int or float arguments. In this case, the polymorphism can be indicated by using the type any instead or int or float. Here is as an example the C function sizeof that returns the size of its argument: sizeof = ffunction(int sizeof(any), \"\",\"\"); type ComplexDiagram( Choice (0, 'int', 'float') ).addTo() argtype ComplexDiagram( Choice (0, 'int', 'float', 'any') ).addTo() Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter). Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case the compiler generates code to call the function at sample rate.","title":"Foreign function declaration"},{"location":"qreference/3-syntax/#foreign-variables-and-constants","text":"External variables and constants can also be declared with a similar syntax. In the same \"maths.lib\" file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found : SR = min(192000.0, max(1.0, fconstant(int fSamplingFreq, <math.h>))); BS = fvariable(int count, <math.h>); Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are computed once, during the initialization period. Foreign variables are considered to vary at block speed. This means that expressions depending of external variables are computed every block.","title":"Foreign variables and constants"},{"location":"qreference/3-syntax/#include-file","text":"In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include... in the generated code. includefile ComplexDiagram( Choice (0, Sequence ('<', OneOrMore (NonTerminal('char')), '>'), Sequence ('\"', OneOrMore (NonTerminal('char')), '\"')) ).addTo()","title":"Include file"},{"location":"qreference/3-syntax/#library-file","text":"In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model.","title":"Library file"},{"location":"qreference/3-syntax/#applications-and-abstractions","text":"Abstractions and applications are fundamental programming constructions directly inspired by the Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically. progexp ComplexDiagram( Choice (0, NonTerminal('abstraction'), NonTerminal('application')) ).addTo()","title":"Applications and Abstractions"},{"location":"qreference/3-syntax/#abstractions","text":"Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts. abstraction ComplexDiagram( Choice (0, NonTerminal('lambdaabstraction'), NonTerminal('patternabstraction')) ).addTo() lambdaabstraction ComplexDiagram( Sequence (NonTerminal('\\'), '(', OneOrMore (NonTerminal('ident'), ','), ')', '.', '(', NonTerminal('expression'), ')') ).addTo() Let's say you want to transform a stereo reverb, freeverb for instance, into a mono effect. You can write the following expression: _ <: freeverb :> _ The incoming mono signal is splitted to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output. Imagine now that you are interested in transforming other stereo effects. It can be interesting to generalize this principle by making freeverb a variable: \\(freeverb).(_ <: freeverb :> _) The resulting abstraction can then be applied to transform other effects. Note that if freeverb is a perfectly valid variable name, a more neutral name would probably be easier to read like: \\(fx).(_ <: fx :> _) Moreover it could be convenient to give a name to this abstraction: mono = \\(fx).(_ <: fx :> _); Or even use a more traditional, but equivalent, notation: mono(fx) = _ <: fx :> _;","title":"Abstractions"},{"location":"qreference/3-syntax/#applications","text":"Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments. application ComplexDiagram( Sequence (NonTerminal('expression'), '(', OneOrMore (NonTerminal('expression'), ','), ')') ).addTo() For example you can apply the previous abstraction to transform your stereo harmonizer: mono(harmonizer) The compiler will start by replacing mono by its definition: \\(fx).(_ <: fx :> _)(harmonizer) Whenever the Faust compiler find an application of an abstraction it replaces Replacing the variable part with the argument is called \\beta -reduction in Lambda-Calculus} the \\emph{variable part with the argument. The resulting expression is as expected: (_ <: harmonizer :> _) Note that the arguments given to the primitive or function in applications are reduced to their block normal form (that is the flat equivalent block) before the actual application. Thus if the number of outputs of the argument block does not mach the needed number of arguments, the application will be treated as partial application and the missing arguments will be replaced by one or several _ (to complete the number of missing arguments).","title":"Applications"},{"location":"qreference/3-syntax/#unapplied-abstractions","text":"Usually, lambda abstractions are supposed to be applied on arguments, using beta-reduction in Lambda-Calculus. Functional languages generally treat them as first-class values\\footnote{ https://en.wikipedia.org/wiki/First-class_function } which give these languages high-order programming capabilities. Another way of looking at abstractions in Faust is as a means of routing or placing blocks that are given as parameters. For example, the following abstraction repeat(fx) = fx : fx; could be used to duplicate an effect and route input signals to be successively processed by that effect: import(\"stdfaust.lib\"); repeat(fx) = fx : fx; process = repeat(dm.zita_light); In Faust, a proper semantic has been given to unapplied abstractions : when a lambda-abstraction is not applied to parameters, it indicates how to route input signals . This is a convenient way to work with signals by explicitly naming them , to be used in the lambda abstraction body with their parameter name . For instance a stereo crossing block written in the core syntax: process = _,_ <: !,_,_,!; can be simply defined as: process = \\(x,y).(y,x); which is actually equivalent to: process(x,y) = y,x;","title":"Unapplied abstractions"},{"location":"qreference/3-syntax/#pattern-matching","text":"Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically. patternabstraction ComplexDiagram( Sequence (\"case\", NonTerminal('{'), OneOrMore (NonTerminal('rule')), NonTerminal('}')) ).addTo() Rule ComplexDiagram( Sequence ('(', OneOrMore (NonTerminal('pattern'), ','), ')', \"=>\", NonTerminal('expression'), ';') ).addTo() Pattern ComplexDiagram( Choice (0, NonTerminal('ident'), NonTerminal('expression')) ).addTo() For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application: case{(x:y) => y:x; (x) => x;}(freeverb:harmonizer) will produce: (harmonizer:freeverb) Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching.","title":"Pattern Matching"},{"location":"qreference/3-syntax/#primitives","text":"The primitive signal processing operations represent the built-in functionalities of Faust , that is the atomic operations on signals provided by the language. All these primitives denote signal processors , functions transforming input signals into output signals . primitive ComplexDiagram( Choice (0, NonTerminal('number'), NonTerminal('route'), NonTerminal('waveform'), NonTerminal('soundfile'), NonTerminal('cprimitive'), NonTerminal('mathprimitive'), NonTerminal('delayandtables'), NonTerminal('uielements'), NonTerminal('%ulation')) ).addTo()","title":"Primitives"},{"location":"qreference/3-syntax/#numbers","text":"Faust considers two types of numbers: integers and floats . Integers are implemented as signed 32-bits integers, and floats are implemented either with a simple, double or extended precision depending of the compiler options. Floats are available in decimal or scientific notation. int ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() float ComplexDiagram( Sequence (Optional ( Choice (0, '+', '-')), Choice (0, Sequence (NonTerminal('digit+'), '.', NonTerminal('digit*')), Sequence (NonTerminal('digit*'), '.', NonTerminal('digit+'))), Optional ( NonTerminal('exponent'))) ).addTo() exponent ComplexDiagram( Sequence ('e', Optional ( Choice (0, '+', '-')), NonTerminal('digit+')) ).addTo() digit ComplexDiagram( \"0--9\" ).addTo() Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} that transforms an empty tuple of signals () into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=0.95 . Operations on integer numbers follow the standard C semantic for +, -, * operations and can possibly overflow if the result cannot be represented as a 32-bits integer. The / operation is treated separately and cast both of its arguments to floats before doing the division, and thus the result takes the float type.","title":"Numbers"},{"location":"qreference/3-syntax/#route-primitive","text":"The route primitive facilitates the routing of signals in Faust. It has the following syntax: route(A,B,a,b,c,d,...) route(A,B,(a,b),(c,d),...) where: - <span class=\"lstinline\">A</span> is the number of input signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">B</span> is the number of output signals, as an integer _constant numerical expression_, automatically promoted to _int_ - <span class=\"lstinline\">a,b / (a,b)</span> is an input/output pair, as integers _constant numerical expressions_, automatically promoted to _int_ Inputs are numbered from 1 to A and outputs are numbered from 1 to B . There can be any number of input/output pairs after the declaration of A and B . For example, crossing two signals can be carried out with: process = route(2,2,1,2,2,1); In that case, route has 2 inputs and 2 outputs. The first input (1) is connected to the second output (2) and the second input (2) is connected to the first output (1). Note that parenthesis can be optionally used to define a pair, so the previous example can also be written as: process = route(2,2,(1,2),(2,1)); More complex expressions can be written using algorithmic constructions, like the following one to cross N signals: // cross 10 signals: // input 0 -> output 10, // input 1 -> output 9, // ..., // input 9 -> output 0 N = 10; r = route(N,N,par(i,N,(i+1,N-i))); process = r;","title":"Route Primitive"},{"location":"qreference/3-syntax/#waveform-primitive","text":"A waveform is a fixed periodic signal defined by a list of samples as literal numbers. A waveform has two outputs. The first output is constant and indicates the size (number of samples) of the period. The second output is the periodic signal itself. waveform ComplexDiagram( Sequence (\"waveform\", NonTerminal('{'), OneOrMore (NonTerminal('number'), ','), NonTerminal('}')) ).addTo() For example waveform {0,1,2,3} produces two outputs, the constant signal 4 and the periodic signal 0,1,2,3,0,1,2,3,0,1 \\ldots. Please note that waveform works nicely with rdtable . Its first output, known at compile time, gives the size of the table, while the second signal gives the content of the table. Here is an example: process = waveform {10,20,30,40,50,60,70}, %(7)~+(3) : rdtable;","title":"Waveform Primitive"},{"location":"qreference/3-syntax/#soundfile-primitive","text":"The soundfile(\"label[url:{ path1';'path2';'path3';}]\", n)' primitive allows access to a list of externally defined sound resources, described as a label followed by the list of their filename, or complete paths (possibly using the '%i' syntax, as in the label part). The soundfile(\"label[url:path]\", n) , or soundfile(\"label\", n) (where label is used as the soundfile path) simplified syntax allows to use a single file. All sound resources are concatenated in a single data structure, and each item can be accessed and used independently. A soundfile has: - two inputs: the sound number (as a integer between 0 and 255, automatically promoted to _int_), and the read index in the sound (automatically promoted to _int_, which will access the last sample of the sound if the read index is greater than the sound length) - two fixed outputs: the first one is the length in samples of the currently accessed sound, the second one is the nominal sample rate in Hz of the currently accessed sound - <span class=\"lstinline\">n</span> several more outputs for the sound channels themselves, as a integer _constant numerical expression_ If more outputs than the actual number of channels in the soundfile are used, the sound channels will be automatically duplicated up to the wanted number of outputs (so for instance if a stereo sound is used with four output channels, the same group of two channels will be duplicated). If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample. Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file implements the void addSoundfile(label, url, sf_zone) method, which loads the actual soundfiles using the {\\it libsndfile} library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. Note that a special architecture file can perfectly decide to access and use sound resources created by another means (that is, not directly loaded from a soundfile). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge to actually setup all sound memory pointers when void addSoundfile(label, url, sf_zone) is called by the buidUserInterface mechanism.","title":"Soundfile Primitive"},{"location":"qreference/3-syntax/#c-equivalent-primitives","text":"Most Faust primitives are analogue to their C counterpart but adapted to signal processing. For example + is a function of type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} that transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)+x_{2}(t) . The function - has type \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} and transforms a pair of signals (x_1,x_2) into a 1-tuple of signals (y) such that \\forall t\\in\\mathbb{N}, y(t)=x_{1}(t)-x_{2}(t) . Please be aware that the unary - only exists in a limited form Warning: unlike other programming languages the unary operatior - only exists in limited form in Faust . It can be used with numbers: -0.5 and variables: -myvar , but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance -(a * b) is a partial application. It is syntactic sugar for _,(a * b) : - . If you want to negate a complex term in parenthesis, you'll have to use 0 - (a * b) instead. The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. For instance 1/2 using int type arguments will correctly result in 0.5 in float type. Logical and shift primitives use the int type. Syntax Type Description n \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} integer number: y(t)=n n.m \\mathbb{S}^{0}\\rightarrow\\mathbb{S}^{1} floating point number: y(t)=n.m _ \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} identity function: y(t)=x(t) ! \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{0} cut function: \\forall x\\in\\mathbb{S},(x)\\rightarrow () int \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an int signal: y(t)=(int)x(t) float \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cast into an float signal: y(t)=(float)x(t) + \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} addition: y(t)=x_{1}(t)+x_{2}(t) - \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} subtraction: y(t)=x_{1}(t)-x_{2}(t) * \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} multiplication: y(t)=x_{1}(t)*x_{2}(t) \\land \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=x_{1}(t)^{x_{2}(t)} / \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} division: y(t)=x_{1}(t)/x_{2}(t) % \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} modulo: y(t)=x_{1}(t)%x_{2}(t) \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} | \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise OR: y(t)=x_{1}(t)\\|x_{2}(t) xor \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} bitwise XOR: y(t)=x_{1}(t)\\land x_{2}(t) << \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift left: y(t)=x_{1}(t) << x_{2}(t) >> \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arith. shift right: y(t)=x_{1}(t) >> x_{2}(t) < \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less than: y(t)=x_{1}(t) < x_{2}(t) <= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} less or equal: y(t)=x_{1}(t) <= x_{2}(t) > \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater than: y(t)=x_{1}(t) > x_{2}(t) >= \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} greater or equal: y(t)=x_{1}(t) >= x_{2}(t) == \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} equal: y(t)=x_{1}(t) == x_{2}(t) != \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} different: y(t)=x_{1}(t) != x_{2}(t)","title":"C-equivalent primitives"},{"location":"qreference/3-syntax/#mathh-equivalent-primitives","text":"Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file maths.lib). The primitives may use the int type for their arguments, but will automatically use the float type when the actual computation requires it. Syntax Type Description acos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc cosine: y(t)=\\mathrm{acosf}(x(t)) asin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc sine: y(t)=\\mathrm{asinf}(x(t)) atan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atanf}(x(t)) atan2 \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} arc tangent: y(t)=\\mathrm{atan2f}(x_{1}(t), x_{2}(t)) cos \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} cosine: y(t)=\\mathrm{cosf}(x(t)) sin \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} sine: y(t)=\\mathrm{sinf}(x(t)) tan \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} tangent: y(t)=\\mathrm{tanf}(x(t)) exp \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e exponential: y(t)=\\mathrm{expf}(x(t)) log \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-e logarithm: y(t)=\\mathrm{logf}(x(t)) log10 \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} base-10 logarithm: y(t)=\\mathrm{log10f}(x(t)) pow \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} power: y(t)=\\mathrm{powf}(x_{1}(t),x_{2}(t)) sqrt \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} square root: y(t)=\\mathrm{sqrtf}(x(t)) abs \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} absolute value (int): y(t)=\\mathrm{abs}(x(t)) absolute value (float): y(t)=\\mathrm{fabsf}(x(t)) min \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} minimum: y(t)=\\mathrm{min}(x_{1}(t),x_{2}(t)) max \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} maximum: y(t)=\\mathrm{max}(x_{1}(t),x_{2}(t)) fmod \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float modulo: y(t)=\\mathrm{fmodf}(x_{1}(t),x_{2}(t)) remainder \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} float remainder: y(t)=\\mathrm{remainderf}(x_{1}(t),x_{2}(t)) floor \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} largest int \\leq : y(t)=\\mathrm{floorf}(x(t)) ceil \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} smallest int \\geq : y(t)=\\mathrm{ceilf}(x(t)) rint \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} closest int using the current rounding mode: y(t)=\\mathrm{rintf}(x(t)) round \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} nearest int value, regardless of the current rounding mode: y(t)=\\mathrm{rintf}(x(t))","title":"math.h-equivalent primitives"},{"location":"qreference/3-syntax/#delay-table-selector-primitives","text":"The following primitives allow to define delays, read-only and read-write tables and 2 or 3-ways selectors (see figure fig-delays ), and some other specific primitives. Syntax Type Description mem \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x(t),y(0)=0 prefix \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} 1-sample delay: y(t+1)=x_{2}(t),y(0)=x_{1}(0) @ \\mathbb{S}^{2}\\rightarrow\\mathbb{S}^{1} variable delay: y(t)=x_{1}(t-x_{2}(t)), x_{1}(t<0)=0 rdtable \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} read-only table: y(t)=T[r(t)] rwtable \\mathbb{S}^{5}\\rightarrow\\mathbb{S}^{1} read-write table: T[w(t)]=c(t); y(t)=T[r(t)] select2 \\mathbb{S}^{3}\\rightarrow\\mathbb{S}^{1} select between 2 signals: T[]={x_{0}(t),x_{1}(t)}; y(t)=T[s(t)] select3 \\mathbb{S}^{4}\\rightarrow\\mathbb{S}^{1} select between 3 signals: T[]={x_{0}(t),x_{1}(t),x_{2}(t)}; y(t)=T[s(t)] lowest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\min_{j=0}^{\\inf} x(j) highest \\mathbb{S}^{1}\\rightarrow\\mathbb{S}^{1} y(t)=\\max_{j=0}^{\\inf} x(j) <a name=\"fig-delays\"></a> Delays, tables and selectors primitives The size input of rdtable and rwtable are integer constant numerical expressions automatically promoted to int , and the read and write indexes are also automatically promoted to int . The delay value is automatically promoted to int .","title":"Delay, Table, Selector primitives"},{"location":"qreference/3-syntax/#user-interface-elements","text":"Faust user interface widgets allow an abstract description of the user interface from within the Faust code. This description is independent of any GUI toolkits. It is based on buttons , checkboxes , sliders , etc. that are grouped together vertically and horizontally using appropriate grouping schemes. All these GUI elements produce signals. A button for example (see figure fig-button ) produces a signal which is 1 when the button is pressed and 0 otherwise. These signals can be freely combined with other audio signals. <a name=\"fig-button\"></a> User Interface Button Syntax Example button( str ) button(\"play\") checkbox( str ) checkbox(\"mute\") vslider( str , cur , min , max , step ) vslider(\"vol\",50,0,100,1) hslider( str , cur , min , max , step ) hslider(\"vol\",0.5,0,1,0.01) nentry( str , cur , min , max , step ) nentry(\"freq\",440,0,8000,1) vgroup( str , block-diagram ) vgroup(\"reverb\", \\ldots) hgroup( str , block-diagram ) hgroup(\"mixer\", \\ldots) tgroup( str , block-diagram ) tgroup(\"parametric\", \\ldots) vbargraph( str , min , max ) vbargraph(\"input\",0,100) hbargraph( str , min , max ) hbargraph(\"signal\",0,1.0) attach attach(x, vumeter(x)) All numerical parameters (like {\\it cur}, {\\it min}, {\\it max}, {\\it step}) are constant numerical expressions .","title":"User Interface Elements"},{"location":"qreference/3-syntax/#labels","text":"Every user interface widget has a label (a string) that identifies it and informs the user of its purpose. There are three important mechanisms associated with labels (and coded inside the string): variable parts , pathnames and metadata . Variable parts. Labels can contain variable parts. These variable parts are indicated by the sign '%' followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example par(i,8,hslider(\"Voice %i\", 0.9, 0, 1, 0.01)) creates 8 different sliders in parallel : hslider(\"Voice 0\", 0.9, 0, 1, 0.01), hslider(\"Voice 1\", 0.9, 0, 1, 0.01), ... hslider(\"Voice 7\", 0.9, 0, 1, 0.01). while par(i,8,hslider(\"Voice\", 0.9, 0, 1, 0.01)) would have created only one slider and duplicated its output 8 times. The variable part can have an optional format digit. For example \"Voice %2i\" would indicate to use two digits when inserting the value of i in the string. An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example \"feedback (%%)\" will result in \"feedback (%)\" . The variable name can be enclosed in curly brackets to clearly separate it from the rest of the string, as in par(i,8,hslider(\"Voice %{i}\", 0.9, 0, 1, 0.01)) . Pathnames. Thanks to horizontal, vertical and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated pathname obtained by concatenating the labels of all its surrounding groups with its own label. In the following example: hgroup(\"Foo\", ... vgroup(\"Faa\", ... hslider(\"volume\",...) ... ) ... ) the volume slider has pathname /h:Foo/v:Faa/volume . In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label. In our previous example the pathname of: hslider(\"../volume\",...) would have been \"/h:Foo/volume\" , while the pathname of: hslider(\"t:Fii/volume\",...) would have been: \"/h:Foo/v:Faa/t:Fii/volume\" . The grammar for labels with pathnames is the following: label ComplexDiagram( Sequence (NonTerminal('path'), NonTerminal('name')) ).addTo() path ComplexDiagram( Sequence (Optional ( '/'), Optional ( OneOrMore (Sequence (NonTerminal('folder'), '/')))) ).addTo() folder ComplexDiagram( Choice (0, \"..\", Sequence (Choice (0, \"h:\", \"v:\", \"t:\"), NonTerminal('name'))) ).addTo() Metadata Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface. The Faust code: process = *(hslider(\"foo [key1: val 1][key2: val 2]\", 0, 0, 1, 0.1)); will produce and the corresponding C++ code: class mydsp : public dsp { ... virtual void buildUserInterface(UI* interface) { interface->openVerticalBox(\"m\"); interface->declare(&fslider0, \"key1\", \"val 1\"); interface->declare(&fslider0, \"key2\", \"val 2\"); interface->addHorizontalSlider(\"foo\", &fslider0, 0.0f, 0.0f, 1.0f, 0.1f); interface->closeBox(); } ... }; All the metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata. It is the role of the architecture file to decide what to do with these metadata. The jack-qt.cpp architecture file for example implements the following: - \"...[style:knob]...\" creates a rotating knob instead of a regular slider or nentry. - \"...[style:led]...\" in a bargraph's label creates a small LED instead of a full bargraph - \"...[unit:dB]...\" in a bargraph's label creates a more realistic bargraph with colors ranging from green to red depending of the level of the value - \"...[unit:xx]...\" in a widget postfixes the value displayed with xx - \"...[tooltip:bla bla]...\" add a tooltip to the widget - \"...[osc:/address min max]...\" Open Sound Control message alias Moreover starting a label with a number option like in \"[1]...\" provides a convenient means to control the alphabetical order of the widgets.","title":"Labels"},{"location":"qreference/3-syntax/#attach","text":"The attach primitive takes two input signals and produce one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical point of view attach(x,y) is equivalent to 1 x+0 y , which is in turn equivalent to x , but it tells the compiler not to optimize-out y . To illustrate this role let say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelop detector connected to a bargraph. The problem is that these envelop signals have no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled.","title":"Attach"},{"location":"qreference/3-syntax/#widget-modulation","text":"Widget modulation acts on the widgets of an existing Faust expression, but without requiring any manual modifications of the expression's code. This operation is done directly by the compiler, according to a list of target widgets and associated modulators . Target widgets are specified by their label, as used in the graphical user interface. Modulators are Faust expressions that describe how to transform the signal produced by widgets. The syntax of a widget modulation is the following: modulation Here is a very simple example of widget modulation, assuming freeverb is a fully functional reverb with a \"Wet\" slider: [\"Wet\" -> freeverb] The resulting circuit will have three inputs instead of two. The additional input is for the \"Wet\" widget. It acts on the values produced by the widget inside the freeverb expression. By default, the additional input signal, and the widget signal are multiplied together. In the following example, an external LFO is connected to this additional input: lfo(10, 0.5), _, _ : [\"Wet\" -> freeverb]","title":"Widget Modulation"},{"location":"qreference/3-syntax/#target-widgets","text":"Target widgets are specified by their label. Of course, this presupposes knowing the names of the widgets. But as these names appear on the user interface, it's easy enough. If several widgets have the same name, adding the names of some (not necessarily all) of the surrounding groups, as in \"h:group/h:subgroup/label\" can help distinguish them. Multiple targets can be indicated in the same widget modulation expression as in: [\"Wet\", \"Damp\", \"RoomSize\" -> freeverb]","title":"Target Widgets"},{"location":"qreference/3-syntax/#modulators","text":"Modulators are Faust expressions, with exactly one output and at most two inputs that describe how to transform the signals produced by widgets. By default, when nothing is specified, the modulator is a multiplication. This is why our previous example is equivalent to: Please note that the `':'` sign used here is just a visual separator, it is not the sequential composition operator. [\"Wet\": * -> freeverb] To indicate that the modulation signal should be added, instead of multiplied, one could write: [\"Wet\": + -> freeverb] Multiplications and addition are examples of 2->1 modulators, but two other types are allowed: 0->1 and 1->1 . Modulators with no inputs Modulators with no inputs 0->1 completely replace the target widget (it won't appear anymore in the user interface). Let's say that we want to remove the \"Damp\" slider and replace it with the constant 0.5 , we can write: [\"Damp\": 0.5 -> freeverb] Modulators with one input A 1->1 modulator transforms the signal produced by the target widget without the help of an external input. Our previous example could be written as: [\"Wet\": *(lfo(10, 0.5)) -> freeverb] If lfo had its user interface, it would be added to the freeverb interface, at the same level as the \"Wet\" slider. Modulators with two inputs Modulators with two inputs, like * or + , are used to combine the signal produced by the target widget with an external signal. The first input is connected to the widget, the second one is connected to the external signal. As we have already seen, our example could be written as: lfo(10, 0.5), _, _ : [\"Wet\": * -> freeverb] The main difference with the previous case is that if lfo had a user interface, it would be added outside of the freeverb interface. Please note that only 2->1 modulators result in additional inputs.","title":"Modulators"},{"location":"qreference/4-compiler/","text":"Invoking the Faust compiler The Faust compiler is invoked using the faust command. It translate Faust programs into C++ code. The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. compiler ComplexDiagram( Sequence (\"faust\", NonTerminal('options'), OneOrMore (NonTerminal('file'))) ).addTo() For example faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to choose the output file: faust noise.dsp -o noise.cpp . The option -a allows to choose the architecture file: faust -a alsa-gtk.cpp noise.dsp . To compile a Faust program into an ALSA application on Linux you can use the following commands: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise Structure of the generated code A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0 // This method can be called to retrieve // the UI description of the Faust program // and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Here is the class generated with the command faust noise.dsp . Methods are filled by the compiler with the actual code. Several fine-grained initialization methods are available. The instanceInit method calls several additional initialization methods. The instanceConstants method sets the instance constant state. The instanceClear method resets the instance dynamic state (delay lines...). The instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The classInit static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once. Finally the init method combines class static state and instance initialization. When using a single instance, then calling init is the simplest way to do what is needed. When using several instances, then all of them can be initialized using instanceInit , whith a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSampleRate; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; Compilation options Compilation options are listed in the following table : \\small \\tablefirsthead{ Short & Long & Description \\tablehead{ Short & Long & Description \\tabletail{ \\multicolumn{3}{|r|}{\\small\\sl continued on next page} \\tablelasttail{ -h & --help & print the help message -v & --version & print version information -d & --details & print compilation details -tg & --task-graph & draw a graph of all internal computation loops as a .dot (graphviz) file. -sg & --signal-graph & draw a graph of all internal signal expressions as a .dot (graphviz) file. -ps & --postscript & generate block-diagram postscript files -svg & --svg & generate block-diagram svg files -blur & --shadow-blur & add a blur to boxes shadows -sd & --simplify-diagrams & simplify block-diagram before drawing them -f n & --fold n & max complexity of svg diagrams before splitting into several files (default 25 boxes) -mns n & --max-name-size n & max character size used in svg diagram labels -sn & --simple-names & use simple names (without arguments) for block-diagram (default max size : 40 chars) -xml & --xml & generate an additional description file in xml format -uim & --user-interface-macros & add user interface macro definitions to the C++ code -flist & --file-list & list all the source files and libraries implied in a compilation -norm & --normalized-form & prints the internal signals in normalized form and exits -lb & --left-balanced & generate left-balanced expressions -mb & --mid-balanced & generate mid-balanced expressions (default) -rb & --right-balanced & generate right-balanced expressions -lt & --less-temporaries & generate less temporaries in compiling delays -mcd n & --max-copy-delay n & threshold between copy and ring buffer delays (default 16 samples) -vec & --vectorize & generate easier to vectorize code -vs n & --vec-size n & size of the vector (default 32 samples) when -vec -lv n & --loop-variant n & loop variant [0:fastest (default), 1:simple] when -vec -dfs & --deepFirstScheduling & schedule vector loops in deep first order when -vec -omp & --openMP & generate parallel code using OpenMP (implies -vec) -sch & --scheduler & generate parallel code using threads directly (implies -vec) -g & --groupTasks & group sequential tasks together when -omp or -sch is used -single & --single-precision-floats & use floats for internal computations (default) -double & --double-precision-floats & use doubles for internal computations -quad & --quad-precision-floats & use extended for internal computations -mdoc & --mathdoc & generates the full mathematical description of a Faust program -mdlang l & --mathdoc-lang l & choose the language of the mathematical description ( l = en, fr, ...) -stripmdoc & --strip-mdoc-tags & remove documentation tags when printing Faust listings -cn name & --class-name name & name of the dsp class to be used instead of 'mydsp' -t time & --timeout time & time out of time seconds (default 600) for the compiler to abort -a file & & architecture file to use -o file & & C++ output file","title":"4 compiler"},{"location":"qreference/4-compiler/#invoking-the-faust-compiler","text":"The Faust compiler is invoked using the faust command. It translate Faust programs into C++ code. The generated code can be wrapped into an optional architecture file allowing to directly produce a fully operational program. compiler ComplexDiagram( Sequence (\"faust\", NonTerminal('options'), OneOrMore (NonTerminal('file'))) ).addTo() For example faust noise.dsp will compile noise.dsp and output the corresponding C++ code on the standard output. The option -o allows to choose the output file: faust noise.dsp -o noise.cpp . The option -a allows to choose the architecture file: faust -a alsa-gtk.cpp noise.dsp . To compile a Faust program into an ALSA application on Linux you can use the following commands: faust -a alsa-gtk.cpp noise.dsp -o noise.cpp g++ -lpthread -lasound `pkg-config --cflags --libs gtk+-2.0` noise.cpp -o noise","title":"Invoking the Faust compiler"},{"location":"qreference/4-compiler/#structure-of-the-generated-code","text":"A Faust DSP C++ class derives from the base dsp class defined as below (a similar structure is used for languages other than C++): class dsp { public: dsp() {} virtual ~dsp() {} // Returns the number of inputs of the Faust program virtual int getNumInputs() = 0; // Returns the number of outputs of the Faust program virtual int getNumOutputs() = 0 // This method can be called to retrieve // the UI description of the Faust program // and its associated fields virtual void buildUserInterface(UI* ui_interface) = 0; // Returns the current sampling rate virtual int getSampleRate() = 0; // Init methods virtual void init(int sample_rate) = 0; virtual void instanceInit(int sample_rate) = 0; virtual void instanceConstants(int sample_rate) = 0; virtual void instanceResetUserInterface() = 0; virtual void instanceClear() = 0; // Returns a clone of the instance virtual dsp* clone() = 0; // Retrieve the global metadata of the Faust program virtual void metadata(Meta* m) = 0; // Compute one audio buffer virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0; // Compute a time-stamped audio buffer virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { compute(count, inputs, outputs); } }; Here is the class generated with the command faust noise.dsp . Methods are filled by the compiler with the actual code. Several fine-grained initialization methods are available. The instanceInit method calls several additional initialization methods. The instanceConstants method sets the instance constant state. The instanceClear method resets the instance dynamic state (delay lines...). The instanceResetUserInterface method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. The classInit static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once. Finally the init method combines class static state and instance initialization. When using a single instance, then calling init is the simplest way to do what is needed. When using several instances, then all of them can be initialized using instanceInit , whith a single call to classInit to initialize the static shared state. The compute method takes the number of frames to process, and inputs and outputs buffers as arrays of separated mono channels. Note that by default inputs and outputs buffers are supposed to be distinct memory zones, so one cannot safely write compute(count, inputs, inputs) . The -inpl compilation option can be used for that, but only in scalar mode for now. By default the generated code process float type samples. This can be changed using the -double option (or even -quad in some backends). The FAUSTFLOAT type used in the compute method is defined in architecture files, and can be float or double , depending of the audio driver layer. Sample adaptation may have to be used between the DSP sample type and the audio driver sample type. class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSampleRate; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int sample_rate) { } virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int sample_rate) { classInit(sample_rate); instanceInit(sample_rate); } virtual void instanceInit(int sample_rate) { instanceConstants(sample_rate); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSampleRate; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } };","title":"Structure of the generated code"},{"location":"qreference/4-compiler/#compilation-options","text":"Compilation options are listed in the following table : \\small \\tablefirsthead{ Short & Long & Description \\tablehead{ Short & Long & Description \\tabletail{ \\multicolumn{3}{|r|}{\\small\\sl continued on next page} \\tablelasttail{ -h & --help & print the help message -v & --version & print version information -d & --details & print compilation details -tg & --task-graph & draw a graph of all internal computation loops as a .dot (graphviz) file. -sg & --signal-graph & draw a graph of all internal signal expressions as a .dot (graphviz) file. -ps & --postscript & generate block-diagram postscript files -svg & --svg & generate block-diagram svg files -blur & --shadow-blur & add a blur to boxes shadows -sd & --simplify-diagrams & simplify block-diagram before drawing them -f n & --fold n & max complexity of svg diagrams before splitting into several files (default 25 boxes) -mns n & --max-name-size n & max character size used in svg diagram labels -sn & --simple-names & use simple names (without arguments) for block-diagram (default max size : 40 chars) -xml & --xml & generate an additional description file in xml format -uim & --user-interface-macros & add user interface macro definitions to the C++ code -flist & --file-list & list all the source files and libraries implied in a compilation -norm & --normalized-form & prints the internal signals in normalized form and exits -lb & --left-balanced & generate left-balanced expressions -mb & --mid-balanced & generate mid-balanced expressions (default) -rb & --right-balanced & generate right-balanced expressions -lt & --less-temporaries & generate less temporaries in compiling delays -mcd n & --max-copy-delay n & threshold between copy and ring buffer delays (default 16 samples) -vec & --vectorize & generate easier to vectorize code -vs n & --vec-size n & size of the vector (default 32 samples) when -vec -lv n & --loop-variant n & loop variant [0:fastest (default), 1:simple] when -vec -dfs & --deepFirstScheduling & schedule vector loops in deep first order when -vec -omp & --openMP & generate parallel code using OpenMP (implies -vec) -sch & --scheduler & generate parallel code using threads directly (implies -vec) -g & --groupTasks & group sequential tasks together when -omp or -sch is used -single & --single-precision-floats & use floats for internal computations (default) -double & --double-precision-floats & use doubles for internal computations -quad & --quad-precision-floats & use extended for internal computations -mdoc & --mathdoc & generates the full mathematical description of a Faust program -mdlang l & --mathdoc-lang l & choose the language of the mathematical description ( l = en, fr, ...) -stripmdoc & --strip-mdoc-tags & remove documentation tags when printing Faust listings -cn name & --class-name name & name of the dsp class to be used instead of 'mydsp' -t time & --timeout time & time out of time seconds (default 600) for the compiler to abort -a file & & architecture file to use -o file & & C++ output file","title":"Compilation options"},{"location":"qreference/5-libfaust/","text":"Embedding the Faust compiler using libfaust The dynamic compilation chain allows developers to embed the Faust compiler technology directly in their application or plugins. Thanks to the awesome LLVM technology combined with libfaust, the library version of the Faust compiler, Faust DSP programs can directly be compiled and executed on the fly at full speed. Dynamic compilation chain The Faust compiler uses an intermediate FIR representation ( Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures (for and while loops, if structure etc.). To generate various output languages, several backends have been developed: for C, C++, Java, JavaScript, asm.js, and LLVM IR. The native LLVM based compilation chain is particularly interesting: it provides direct compilation of a DSP source into executable code in memory, bypassing the external compiler requirement. LLVM LLVM (formerly Low Level Virtual Machine) is a compiler infrastructure, designed for compile-time, link-time, run-time optimization of programs written in arbitrary programming languages. Executable code is produced dynamically using a {\\it Just In Time} compiler from a specific code representation, called LLVM IR. Clang, the LLVM native C/C++/Objective- C compiler is a front-end for LLVM Compiler. It can, for instance, convert a C or C++ source file into LLVM IR code. Domain-specific languages like Faust can easily target the LLVM IR. This has been done by developing an LLVM IR backend in the Faust compiler. Compiling in memory The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. The Faust compiler has been packaged as an embeddable library called libfaust, published with an associated API that imitates the concept of oriented-object languages, like C++. Given a Faust source code (as a file or a string), calling the createDSPFactoryXXX function runs the compilation chain ( Faust + LLVM JIT) and generates the {\\it prototype} of the class, as a llvm_dsp_factory pointer. class llvm_dsp_factory { public: /* Return Factory name */ std::string getName(); /* Return Factory LLVM target */ std::string getTarget(); /* Return Factory SHA key */ std::string getSHAKey(); /* Return Factory expanded DSP code */ std::string getDSPCode(); /* Create a new DSP instance, to be deleted with C++ 'delete' */ llvm_dsp* createDSPInstance(); /* Set a custom memory manager to be used when creating instances */ void setMemoryManager(dsp_memory_manager* manager); /* Return the currently set custom memory manager */ dsp_memory_manager* getMemoryManager(); }; Note that the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code, that is same source code and same set of {\\it normalized} (= sorted in a canonical order) compilations options, will return the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly decrement the reference counter when the factory is no more needed. You can get a unique SHA1 key of the created factory using its getSHAKey method. Next, the createDSPInstance function, corresponding to the new className of C++, instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, use delete to destroy the dsp instance. class llvm_dsp : public dsp { public: int getNumInputs(); int getNumOutputs(); void buildUserInterface(UI* ui_interface); int getSampleRate(); void init(int sample_rate); void instanceInit(int sample_rate); void instanceConstants(int sample_rate); void instanceResetUserInterface(); void instanceClear(); llvm_dsp* clone(); void metadata(Meta* m); void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs); }; Since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all already available audio and UI classes, in essence reusing all architecture files already developed for the static C++ class compilation scheme (like OSCUI, httpdUI interfaces etc.), look at Developing a new architecture file section. Saving/restoring the factory After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR allows to get the DSP factory LLVM IR (in textual format) as a string, writeDSPFactoryToIRFile allows to save the DSP factory LLVM IR (in textual format) in a file, writeDSPFactoryToBitcode allows to get the DSP factory LLVM IR (in binary format) as a string, writeDSPFactoryToBitcodeFile allows to save the DSP factory LLVM IR (in binary format) in a file, writeDSPFactoryToMachine allows to get the DSP factory executable machine code as a string, writeDSPFactoryToMachineFile allows to save the DSP factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR allows to create a DSP factory from a string containing the LLVM IR (in textual format), readDSPFactoryFromIRFile allows to create a DSP factory from a file containing the LLVM IR (in textual format), readDSPFactoryFromBitcode allows to create a DSP factory from a string containing the LLVM IR (in binary format), readDSPFactoryFromBitcodeFile allows to create a DSP factory from a file containing the LLVM IR (in binary format), readDSPFactoryFromMachine allows to create a DSP factory from a string containing the executable machine code, readDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the executable machine code. Additional functions Some additional functions are available in the libfaust API: expandDSPFromString/expandDSPFromFile creates a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string, generateAuxFilesFromString/generateAuxFilesFromFile : from a DSP source string or file, generates auxiliary files: SVG, XML, ps... depending of the argv parameters. Using the libfaust library The libfaust library is part of the Faust tree. You'll have to compile and install it. Then look at the installed faust/dsp/llvm-dsp.h header for a complete description of the API. Note that faust/dsp/llvm-c-dsp.h is a pure C version of the same API. The additional functions are available in the faust/dsp/libfaust.h header and their C version is in faust/dsp/libfaust-c.h . Use case examples The dynamic compilation chain has been used in several projects: FaustLive, an integrated IDE for Faust development Faustgen, an external object for Cycling Max/MSP language Csound6, see this demo video LibAudioStream, a framework to manipulate audio ressources through the concept of streams Oliver Larkin JUCE framework integration and pMix2 project an experimental version of Antescofo FaucK: the combination of the Chuck language and Faust","title":"5 libfaust"},{"location":"qreference/5-libfaust/#embedding-the-faust-compiler-using-libfaust","text":"The dynamic compilation chain allows developers to embed the Faust compiler technology directly in their application or plugins. Thanks to the awesome LLVM technology combined with libfaust, the library version of the Faust compiler, Faust DSP programs can directly be compiled and executed on the fly at full speed.","title":"Embedding the Faust  compiler using libfaust"},{"location":"qreference/5-libfaust/#dynamic-compilation-chain","text":"The Faust compiler uses an intermediate FIR representation ( Faust Imperative Representation), which can be translated to several output languages. The FIR language describes the computation performed on the samples in a generic manner. It contains primitives to read and write variables and arrays, do arithmetic operations, and define the necessary control structures (for and while loops, if structure etc.). To generate various output languages, several backends have been developed: for C, C++, Java, JavaScript, asm.js, and LLVM IR. The native LLVM based compilation chain is particularly interesting: it provides direct compilation of a DSP source into executable code in memory, bypassing the external compiler requirement.","title":"Dynamic compilation chain"},{"location":"qreference/5-libfaust/#llvm","text":"LLVM (formerly Low Level Virtual Machine) is a compiler infrastructure, designed for compile-time, link-time, run-time optimization of programs written in arbitrary programming languages. Executable code is produced dynamically using a {\\it Just In Time} compiler from a specific code representation, called LLVM IR. Clang, the LLVM native C/C++/Objective- C compiler is a front-end for LLVM Compiler. It can, for instance, convert a C or C++ source file into LLVM IR code. Domain-specific languages like Faust can easily target the LLVM IR. This has been done by developing an LLVM IR backend in the Faust compiler.","title":"LLVM"},{"location":"qreference/5-libfaust/#compiling-in-memory","text":"The complete chain goes from the Faust DSP source code, compiled in LLVM IR using the LLVM backend, to finally produce the executable code using the LLVM JIT. All steps take place in memory, getting rid of the classical file based approaches. Pointers to executable functions can be retrieved from the resulting LLVM module and the code directly called with the appropriate parameters. The Faust compiler has been packaged as an embeddable library called libfaust, published with an associated API that imitates the concept of oriented-object languages, like C++. Given a Faust source code (as a file or a string), calling the createDSPFactoryXXX function runs the compilation chain ( Faust + LLVM JIT) and generates the {\\it prototype} of the class, as a llvm_dsp_factory pointer. class llvm_dsp_factory { public: /* Return Factory name */ std::string getName(); /* Return Factory LLVM target */ std::string getTarget(); /* Return Factory SHA key */ std::string getSHAKey(); /* Return Factory expanded DSP code */ std::string getDSPCode(); /* Create a new DSP instance, to be deleted with C++ 'delete' */ llvm_dsp* createDSPInstance(); /* Set a custom memory manager to be used when creating instances */ void setMemoryManager(dsp_memory_manager* manager); /* Return the currently set custom memory manager */ dsp_memory_manager* getMemoryManager(); }; Note that the library keeps an internal cache of all allocated factories so that the compilation of the same DSP code, that is same source code and same set of {\\it normalized} (= sorted in a canonical order) compilations options, will return the same (reference counted) factory pointer. You will have to explicitly use deleteDSPFactory to properly decrement the reference counter when the factory is no more needed. You can get a unique SHA1 key of the created factory using its getSHAKey method. Next, the createDSPInstance function, corresponding to the new className of C++, instantiates a llvm_dsp pointer to be used through its interface, connected to the audio chain and controller interfaces. When finished, use delete to destroy the dsp instance. class llvm_dsp : public dsp { public: int getNumInputs(); int getNumOutputs(); void buildUserInterface(UI* ui_interface); int getSampleRate(); void init(int sample_rate); void instanceInit(int sample_rate); void instanceConstants(int sample_rate); void instanceResetUserInterface(); void instanceClear(); llvm_dsp* clone(); void metadata(Meta* m); void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs); }; Since llvm_dsp is a subclass of the dsp base class, an object of this type can be used with all already available audio and UI classes, in essence reusing all architecture files already developed for the static C++ class compilation scheme (like OSCUI, httpdUI interfaces etc.), look at Developing a new architecture file section.","title":"Compiling in memory"},{"location":"qreference/5-libfaust/#savingrestoring-the-factory","text":"After the DSP factory has been compiled, your application or plugin may want to save/restore it in order to save Faust to LLVM IR compilation or even JIT compilation time at next use. To get the internal factory compiled code, several functions are available: writeDSPFactoryToIR allows to get the DSP factory LLVM IR (in textual format) as a string, writeDSPFactoryToIRFile allows to save the DSP factory LLVM IR (in textual format) in a file, writeDSPFactoryToBitcode allows to get the DSP factory LLVM IR (in binary format) as a string, writeDSPFactoryToBitcodeFile allows to save the DSP factory LLVM IR (in binary format) in a file, writeDSPFactoryToMachine allows to get the DSP factory executable machine code as a string, writeDSPFactoryToMachineFile allows to save the DSP factory executable machine code in a file. To re-create a DSP factory from a previously saved code, several functions are available: readDSPFactoryFromIR allows to create a DSP factory from a string containing the LLVM IR (in textual format), readDSPFactoryFromIRFile allows to create a DSP factory from a file containing the LLVM IR (in textual format), readDSPFactoryFromBitcode allows to create a DSP factory from a string containing the LLVM IR (in binary format), readDSPFactoryFromBitcodeFile allows to create a DSP factory from a file containing the LLVM IR (in binary format), readDSPFactoryFromMachine allows to create a DSP factory from a string containing the executable machine code, readDSPFactoryFromMachineFile allows to create a DSP factory from a file containing the executable machine code.","title":"Saving/restoring the factory"},{"location":"qreference/5-libfaust/#additional-functions","text":"Some additional functions are available in the libfaust API: expandDSPFromString/expandDSPFromFile creates a self-contained DSP source string where all needed librairies have been included. All compilations options are normalized and included as a comment in the expanded string, generateAuxFilesFromString/generateAuxFilesFromFile : from a DSP source string or file, generates auxiliary files: SVG, XML, ps... depending of the argv parameters.","title":"Additional functions"},{"location":"qreference/5-libfaust/#using-the-libfaust-library","text":"The libfaust library is part of the Faust tree. You'll have to compile and install it. Then look at the installed faust/dsp/llvm-dsp.h header for a complete description of the API. Note that faust/dsp/llvm-c-dsp.h is a pure C version of the same API. The additional functions are available in the faust/dsp/libfaust.h header and their C version is in faust/dsp/libfaust-c.h .","title":"Using the libfaust library"},{"location":"qreference/5-libfaust/#use-case-examples","text":"The dynamic compilation chain has been used in several projects: FaustLive, an integrated IDE for Faust development Faustgen, an external object for Cycling Max/MSP language Csound6, see this demo video LibAudioStream, a framework to manipulate audio ressources through the concept of streams Oliver Larkin JUCE framework integration and pMix2 project an experimental version of Antescofo FaucK: the combination of the Chuck language and Faust","title":"Use case examples"},{"location":"qreference/6-audio/","text":"Architecture files 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 vsti-poly.cpp VSTi polyphonic 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 Some of the available architectures. The main available architecture files are listed table tab:availablearch . 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. 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 { public: audio() {} virtual ~audio() {} virtual bool init(const char*, dsp*) = 0; virtual bool start() = 0; virtual void stop() = 0; virtual void shutdown(shutdown_callback cb, void* arg) {} virtual int getBufferSize() = 0; virtual int getSampleRate() = 0; virtual int getNumInputs() = 0; virtual int getNumOutputs() = 0; virtual float getCPULoad() { return 0.f; } }; 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 tab:aarch gives some of the audio architectures currently available for various operating systems. Audio system Operating system Alsa Linux CoreAudio Mac OS X, iOS JACK Linux, Mac OS X, Windows PortAudio Linux, Mac OS X, Windows OSC 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 Some of Faust audio architectures. 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 tab:ui ). #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif class UI { public: UI() {} virtual ~UI() {} -- 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; -- active widgets virtual void addButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addCheckButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addVerticalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addHorizontalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addNumEntry(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; -- passive widgets virtual void addHorizontalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; virtual void addVerticalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; -- metadata declarations virtual void declare(FAUSTFLOAT*, const char*, const char*) {} }; UI, the root user interface class 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, using the FAUSTFLOAT macro type (defined at compile time as either float or double). The widget currently considered are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values. 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 HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type. 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. UI Comment console a textual command line UI GTKUI a GTK-based GUI QTGUI a multi-platform QT-based GUI FUI a file-based UI to store and recall modules states OSCUI OSC control (see section osc ) httpdUI HTTP control (see section http ) ... ... Some of the available UI architectures. Metadata The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT zone, const char key, const char* value) Here is the table of currently supported general medatada (look at section osc for OSC specific metadata and section midi for MIDI specific metadata): Key Value tooltip actual string content hidden 0 or 1 size actual value unit Hz or dB scale log or exp style knob or led or numerical style radio{\\'label1\\':v1;\\'label2\\':v2... } style menu{\\'label1\\':v1;\\'label2\\':v2... } acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Supported medatada. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\\'white noise\\':0;\\'pink noise\\':1;\\'sine\\':2 ][hidden:0]\", 0, 20, 100, 1)} or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for exemple) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future. Developing a new architecture file Developing a new architecture file typically means writing a generic C++ file, that will be populated with the actual output of the Faust compiler, in order to produce a complete C++ file, ready to be compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the < > and < > lines that will be looked at by the Faust compiler, and replaced by the generated C++ class. Look at the minimal.cpp example located in the architecture folder: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //------------------------------------------------- // FAUST generated signal processor //------------------------------------------------- <<includeIntrinsic>> <<includeclass>> int main(int argc, char *argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); Calling faust -a minimal.cpp noise.dsp -a noise.cpp will produce a ready to compile noise.cpp file: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //--------------------------------------------------- // FAUST generated signal processor //-------------------------------------------------- #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSamplingFreq; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int samplingFreq) { } virtual void instanceConstants(int samplingFreq) { fSamplingFreq = samplingFreq; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int samplingFreq) { classInit(samplingFreq); instanceInit(samplingFreq); } virtual void instanceInit(int samplingFreq) { instanceConstants(samplingFreq); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSamplingFreq; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"acc\", \"0 0 -10 0 10\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); You can possibly add the -i option to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with \"faust\"). Then you will have to write a faust2xxx script that will chain the Faust compilation step and the C++ compilation one. Look at scripts in the tools/faust2appls folder for real examples. Developing the adapted C++ file may require \"aggregating\" the generated mydsp class (subclass of dsp base class defined in faust/dsp/dsp.h header) in your specific class, or \"subclassing\" and extend it. So you will have to write something like: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific fDSP.compute(count, inputs, outputs); } // Do something specific }; or: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific compute(count, inputs, outputs); } // Do something specific }; This way your architecture file will be adapted to any \"shape\" of the generated code. That is, depending if you generate purely scalar, or vector code (using the -vec option), or any other option, the generated mydsp class will always be correctly inserted in the final C++ file. Look for instance at csound.cpp and unity.cpp architecture files in the architecture folder for real examples.","title":"6 audio"},{"location":"qreference/6-audio/#architecture-files","text":"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 vsti-poly.cpp VSTi polyphonic 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 Some of the available architectures. The main available architecture files are listed table tab:availablearch . 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.","title":"Architecture files"},{"location":"qreference/6-audio/#audio-architecture-modules","text":"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 { public: audio() {} virtual ~audio() {} virtual bool init(const char*, dsp*) = 0; virtual bool start() = 0; virtual void stop() = 0; virtual void shutdown(shutdown_callback cb, void* arg) {} virtual int getBufferSize() = 0; virtual int getSampleRate() = 0; virtual int getNumInputs() = 0; virtual int getNumOutputs() = 0; virtual float getCPULoad() { return 0.f; } }; 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 tab:aarch gives some of the audio architectures currently available for various operating systems. Audio system Operating system Alsa Linux CoreAudio Mac OS X, iOS JACK Linux, Mac OS X, Windows PortAudio Linux, Mac OS X, Windows OSC 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 Some of Faust audio architectures.","title":"Audio architecture modules"},{"location":"qreference/6-audio/#ui-architecture-modules","text":"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 tab:ui ). #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif class UI { public: UI() {} virtual ~UI() {} -- 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; -- active widgets virtual void addButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addCheckButton(const char* l, FAUSTFLOAT* z) = 0; virtual void addVerticalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addHorizontalSlider(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; virtual void addNumEntry(const char* l, FAUSTFLOAT* z, FAUSTFLOAT init, FAUSTFLOAT min, FAUSTFLOAT max, FAUSTFLOAT step) = 0; -- passive widgets virtual void addHorizontalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; virtual void addVerticalBargraph(const char* l, FAUSTFLOAT* z, FAUSTFLOAT min, FAUSTFLOAT max) = 0; -- metadata declarations virtual void declare(FAUSTFLOAT*, const char*, const char*) {} }; UI, the root user interface class","title":"UI architecture modules"},{"location":"qreference/6-audio/#active-widgets","text":"Active widgets are graphical elements that control a parameter value. They are initialized with the widget name and a pointer to the linked value, using the FAUSTFLOAT macro type (defined at compile time as either float or double). The widget currently considered are Button , CheckButton , VerticalSlider , HorizontalSlider and NumEntry . A GUI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each active widget. Additional parameters are available for Slider and NumEntry : the init , min , max and step values.","title":"Active widgets"},{"location":"qreference/6-audio/#passive-widgets","text":"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 HorizontalBarGraph and VerticalBarGraph . A UI architecture must implement a method addXxx(const char name, FAUSTFLOAT zone, ...) for each passive widget. Additional parameters are available, depending on the passive widget type.","title":"Passive widgets"},{"location":"qreference/6-audio/#widgets-layout","text":"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. UI Comment console a textual command line UI GTKUI a GTK-based GUI QTGUI a multi-platform QT-based GUI FUI a file-based UI to store and recall modules states OSCUI OSC control (see section osc ) httpdUI HTTP control (see section http ) ... ... Some of the available UI architectures.","title":"Widgets layout"},{"location":"qreference/6-audio/#metadata","text":"The Faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT zone, const char key, const char* value) Here is the table of currently supported general medatada (look at section osc for OSC specific metadata and section midi for MIDI specific metadata): Key Value tooltip actual string content hidden 0 or 1 size actual value unit Hz or dB scale log or exp style knob or led or numerical style radio{\\'label1\\':v1;\\'label2\\':v2... } style menu{\\'label1\\':v1;\\'label2\\':v2... } acc axe curve amin amid amax gyr axe curve amin amid amax screencolor red or green or blue or white Supported medatada. Some typical example where several metadata are defined could be: nentry(\"freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu{\\'white noise\\':0;\\'pink noise\\':1;\\'sine\\':2 ][hidden:0]\", 0, 20, 100, 1)} or: vslider(\"freq [unit:dB][style:knob][gyr:0 0 -30 0 30]\", 0, 20, 100, 1) Note that medatada are not supported in all architecture files. Some of them like ( acc or gyr for exemple) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future.","title":"Metadata"},{"location":"qreference/6-audio/#developing-a-new-architecture-file","text":"Developing a new architecture file typically means writing a generic C++ file, that will be populated with the actual output of the Faust compiler, in order to produce a complete C++ file, ready to be compiled as a standalone application or plugin. The architecture to be used is specified at compile time with the -a option. It must contain the < > and < > lines that will be looked at by the Faust compiler, and replaced by the generated C++ class. Look at the minimal.cpp example located in the architecture folder: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //------------------------------------------------- // FAUST generated signal processor //------------------------------------------------- <<includeIntrinsic>> <<includeclass>> int main(int argc, char *argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); Calling faust -a minimal.cpp noise.dsp -a noise.cpp will produce a ready to compile noise.cpp file: #include \"faust/gui/PrintUI.h\" #include \"faust/gui/meta.h\" #include \"faust/audio/dummy-audio.h\" using std::max; using std::min; //--------------------------------------------------- // FAUST generated signal processor //-------------------------------------------------- #ifndef FAUSTFLOAT #define FAUSTFLOAT float #endif #ifndef FAUSTCLASS #define FAUSTCLASS mydsp #endif class mydsp : public dsp { private: FAUSTFLOAT fslider0; int iRec0[2]; int fSamplingFreq; public: virtual void metadata(Meta* m) { m->declare(\"name\", \"Noise\"); m->declare(\"version\", \"1.1\"); m->declare(\"author\", \"Grame\"); m->declare(\"license\", \"BSD\"); m->declare(\"copyright\", \"(c)GRAME 2009\"); } virtual int getNumInputs() { return 0; } virtual int getNumOutputs() { return 1; } static void classInit(int samplingFreq) { } virtual void instanceConstants(int samplingFreq) { fSamplingFreq = samplingFreq; } virtual void instanceResetUserInterface() { fslider0 = 0.5f; } virtual void instanceClear() { for (int i=0; i<2; i++) iRec0[i] = 0; } virtual void init(int samplingFreq) { classInit(samplingFreq); instanceInit(samplingFreq); } virtual void instanceInit(int samplingFreq) { instanceConstants(samplingFreq); instanceResetUserInterface(); instanceClear(); } virtual mydsp* clone() { return new mydsp(); } virtual int getSampleRate() { return fSamplingFreq; } virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"Noise\"); ui_interface->declare(&fslider0, \"acc\", \"0 0 -10 0 10\"); ui_interface->declare(&fslider0, \"style\", \"knob\"); ui_interface->addVerticalSlider(\"Volume\", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f); ui_interface->closeBox(); } virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) { float fSlow0 = (4.656613e-10f * float(fslider0)); FAUSTFLOAT* output0 = output[0]; for (int i=0; i<count; i++) { iRec0[0] = ((1103515245 * iRec0[1]) + 12345); output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]); // post processing iRec0[1] = iRec0[0]; } } }; int main(int argc, char* argv[]) { mydsp DSP; PrintUI ui; // Activate the UI // (here that only prints the control paths) DSP.buildUserInterface(&ui); // Allocate the audio driver to render // 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", &DSP); // Render buffers... audio.start(); audio.stop(); You can possibly add the -i option to actually inline all #include \"faust/xxx/yyy\" headers (all files starting with \"faust\"). Then you will have to write a faust2xxx script that will chain the Faust compilation step and the C++ compilation one. Look at scripts in the tools/faust2appls folder for real examples. Developing the adapted C++ file may require \"aggregating\" the generated mydsp class (subclass of dsp base class defined in faust/dsp/dsp.h header) in your specific class, or \"subclassing\" and extend it. So you will have to write something like: class my_class : public base_interface { private: mydsp fDSP; public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific fDSP.compute(count, inputs, outputs); } // Do something specific }; or: class my_class : public mydsp { private: // Do something specific public: my_class() { // Do something specific } virtual ~my_class() { // Do something specific } // Do something specific void my_compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs,....) { // Do something specific compute(count, inputs, outputs); } // Do something specific }; This way your architecture file will be adapted to any \"shape\" of the generated code. That is, depending if you generate purely scalar, or vector code (using the -vec option), or any other option, the generated mydsp class will always be correctly inserted in the final C++ file. Look for instance at csound.cpp and unity.cpp architecture files in the architecture folder for real examples.","title":"Developing a new architecture file"},{"location":"qreference/7-osc/","text":"OSC support Most Faust architectures provide Open Sound Control (OSC) support \\footnote{The implementation is based internally on the oscpack library by Ross Bencina}. This allows Faust applications to be remotely controlled from any OSC capable application, programming language, or hardware device. OSC support can be activated using the -osc option when building the application with the appropriate faust2xxx command. The following table (table tab:oscarch ) lists Faust 's architectures which provide OSC support. Audio system Environment OSC support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with OSC support. A simple example To illustrate how OSC support works let's define a very simple noise generator with a level control: noise.dsp process = library(\"music.lib\").noise * hslider(\"level\", 0, 0, 1, 0.01); We are going to compile this example as a standalone Jack QT application with OSC support using the command: faust2jaqt -osc noise.dsp When we start the application from the command line: ./noise we get various information on the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 As we can see the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \\\"Foo\\\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host set sthe destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (bargraph) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements (bargraph) are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that 'path' can be a regular expression (like \"/freeverb/Reverb1/*\"). -bundle 0|1 activates the bundle mode where all transmitted values are sent in a single message, to be used together with the -xmit option. For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination. Automatic port allocation In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let's say that we start two applications noise and mixer on the same machine, here is what we get: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and open it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications. Discovering OSC applications The commands oscsend oscsend hostname port address types values : send OpenSound Control message via UDP. types is a string, the letters indicates the type of the following values: i=integer, f=float, s=string,... Send OpenSound Control message via UDP. and oscdump oscdump port : receive OpenSound Control messages via UDP and dump to standard output from the liblo package provide a convenient mean to experiment with OSC control. For the experiment let's use two additional terminals. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . We will indicate by T1$ the command types on terminal T1 and by T2: the messages received on terminal T2. To monitor on terminal T2 the OSC messages received on UDP port 5511 we will use oscdump : T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for FAUST applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512 Discovering the OSC interface of an application Once we have an application we can discover its OSC interface (the set of OSC messages we can use to control it) by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer of the osc messages understood by the application, a full description is available on terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the osc interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is \"127.0.0.1\" , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 . Widget's OSC address Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example mix4.dsp , a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see each widget has a unique OSC address obtained by concatenating the top level group label \"mixer\", with the \"input\" group label and the widget label. Please note that in this operation whites spaces are replaced by underscores and metadata are removed. All addresses must have a common root. This is the case in our example because there is a unique horizontal group \"mixer\" containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000 Controlling the application via OSC We can control any user interface element of the application by sending one of the previously discovered messages. For example to set the noise level of the application to 0.2 we send: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000 Turning transmission ON The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For examples: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS (xmit = 2) mode if you need restricted access to your program: when ALIAS is mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements (bargraph) will only emit on their aliases. Filtering OSC messages When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter the unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter Using OSC aliases Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our noise example with touchOSC on Android. The first step is to configure TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510. Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of simple layout. Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: \\marginpar{ Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages. process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because here the range of /1/fader1 is 0 to 1 like the level slider we can remove the range mapping information and write simply : process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1]\", 0, 0, 1, 0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer. Using again oscdump 5510 we can visualize the messages send by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see TouchOSC send the x, y and z accelerometers in a single message, as a triplet of values ranging approximatively from -9.81 to 9.81 . In order to select the appropriate accelerometer we need to concatenate to /accxyz a suffix /0, /1 or /2. For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: process = library(\"music.lib\").noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer Examples of OSC message aliases for TouchOSC (layout Mix2). OSC cheat sheet Default ports 5510 default listening port 5511 default transmission port 5512 default error port 5513... alternative listening ports Command line options -port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time Discovery messages oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port Control messages oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value Alias \"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc: address ]...\" alias with min , max clipping DSP with polyphonic support When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used.","title":"7 osc"},{"location":"qreference/7-osc/#osc-support","text":"Most Faust architectures provide Open Sound Control (OSC) support \\footnote{The implementation is based internally on the oscpack library by Ross Bencina}. This allows Faust applications to be remotely controlled from any OSC capable application, programming language, or hardware device. OSC support can be activated using the -osc option when building the application with the appropriate faust2xxx command. The following table (table tab:oscarch ) lists Faust 's architectures which provide OSC support. Audio system Environment OSC support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with OSC support.","title":"OSC support"},{"location":"qreference/7-osc/#a-simple-example","text":"To illustrate how OSC support works let's define a very simple noise generator with a level control: noise.dsp process = library(\"music.lib\").noise * hslider(\"level\", 0, 0, 1, 0.01); We are going to compile this example as a standalone Jack QT application with OSC support using the command: faust2jaqt -osc noise.dsp When we start the application from the command line: ./noise we get various information on the standard output, including: Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 As we can see the OSC module makes use of three different UDP ports: 5510 is the listening port number: control messages should be addressed to this port. 5511 is the output port number: control messages sent by the application and answers to query messages are sent to this port. 5512 is the error port number: used for asynchronous error notifications. Note that if a declare name \\\"Foo\\\"; line is present in the DSP program, Foo will be used as the OSC root name, otherwise the DSP filename will be used instead. These OSC parameters can be changed from the command line using one of the following options: -port number sets the port number used by the application to receive messages. -outport number sets the port number used by the application to transmit messages. -errport number sets the port number used by the application to transmit error messages. -desthost host set sthe destination host for the messages sent by the application. Note that the destination address can be changed with the first incoming message: first received packet from another host sets the destination address to this host. -xmit 0|1|2 turns transmission OFF, ALL, or ALIAS (default OFF). When transmission is OFF, input elements can be controlled using their addresses or aliases (if present). When transmission is ALL, input elements can be controlled using their addresses or aliases (if present), user's actions and output elements (bargraph) are transmitted as OSC messages as well as aliases (if present). When transmission is ALIAS, input elements can only be controlled using their aliases, user's actions and output elements (bargraph) are transmitted as aliases only. -xmitfilter path allows to filter output messages. Note that 'path' can be a regular expression (like \"/freeverb/Reverb1/*\"). -bundle 0|1 activates the bundle mode where all transmitted values are sent in a single message, to be used together with the -xmit option. For example: ./noise -xmit 1 -desthost 192.168.1.104 -outport 6000 will run noise with transmission mode ON, using 192.168.1.104 on port 6000 as destination.","title":"A simple example"},{"location":"qreference/7-osc/#automatic-port-allocation","text":"In order to address each application individually, only one application can be listening on a single port at one time. Therefore when the default incoming port 5510 is already opened by some other application, an application will automatically try increasing port numbers until it finds an available port. Let's say that we start two applications noise and mixer on the same machine, here is what we get: $ ./noise & ... Faust OSC version 0.93 application 'noise' is running on UDP ports 5510, 5511, 5512 $ ./mixer ... Faust OSC version 0.93 application 'mixer' is running on UDP ports 5513, 5511, 5512 The mixer application fails to open the default incoming port 5510 because it is already opened by noise . Therefore it tries to find an available port starting from 5513 and open it. Please note that the two outcoming ports 5511 and 5512 are shared by all running applications.","title":"Automatic port allocation"},{"location":"qreference/7-osc/#discovering-osc-applications","text":"The commands oscsend oscsend hostname port address types values : send OpenSound Control message via UDP. types is a string, the letters indicates the type of the following values: i=integer, f=float, s=string,... Send OpenSound Control message via UDP. and oscdump oscdump port : receive OpenSound Control messages via UDP and dump to standard output from the liblo package provide a convenient mean to experiment with OSC control. For the experiment let's use two additional terminals. The first one will be used to send OSC messages to the noise application using oscsend . The second terminal will be used to monitor the messages sent by the application using oscdump . We will indicate by T1$ the command types on terminal T1 and by T2: the messages received on terminal T2. To monitor on terminal T2 the OSC messages received on UDP port 5511 we will use oscdump : T2$ oscdump 5511 Once set we can use the hello message to scan UDP ports for FAUST applications. For example: T1$ oscsend localhost 5510 \"/*\" s hello gives us the root message address, the network and the UDP ports used by the noise application: T2: /noise siii \"192.168.1.102\" 5510 5511 5512","title":"Discovering OSC applications"},{"location":"qreference/7-osc/#discovering-the-osc-interface-of-an-application","text":"Once we have an application we can discover its OSC interface (the set of OSC messages we can use to control it) by sending the get message to the root: T1$ oscsend localhost 5510 /noise s get As an answer of the osc messages understood by the application, a full description is available on terminal T2: T2: /noise sF \"xmit\" #F T2: /noise ss \"desthost\" \"127.0.0.1\" T2: /noise si \"outport\" 5511 T2: /noise si \"errport\" 5512 T2: /noise/level fff 0.000000 0.000000 1.000000 The root of the osc interface is /noise . Transmission is OFF, xmit is set to false. The destination host for sending messages is \"127.0.0.1\" , the output port is 5511 and the error port is 5512 . The application has only one user interface element: /noise/level with current value 0.0 , minimal value 0.0 and maximal value 1.0 .","title":"Discovering the OSC interface of an application"},{"location":"qreference/7-osc/#widgets-osc-address","text":"Each widget of an application has a unique OSC address obtained by concatenating the labels of it's surrounding groups with its own label. There are potential conflicts between widget's labels and the OSC address space. An OSC symbolic name is an ASCII string consisting of a restricted set of printable characters. Therefore to ensure compatibility spaces are replaced by underscores and some other characters (asterisk, comma, forward, question mark, open bracket, close bracket, open curly brace, close curly brace) are replaced by hyphens. Here is as an example mix4.dsp , a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); If we query this application: T1$ oscsend localhost 5510 \"/*\" s get We get a full description of its OSC interface on terminal T2: T2: /mixer sF \"xmit\" #F T2: /mixer ss \"desthost\" \"127.0.0.1\" T2: /mixer si \"outport\" 5511 T2: /mixer si \"errport\" 5512 T2: /mixer/input_0/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/level fff 0.0000 0.0000 1.0000 T2: /mixer/input_3/mute fff 0.0000 0.0000 1.0000 As we can see each widget has a unique OSC address obtained by concatenating the top level group label \"mixer\", with the \"input\" group label and the widget label. Please note that in this operation whites spaces are replaced by underscores and metadata are removed. All addresses must have a common root. This is the case in our example because there is a unique horizontal group \"mixer\" containing all widgets. If a common root is missing as in the following code: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = par(i, 4, input(i)) :> _; then a default vertical group is automatically create by the Faust compiler using the name of the file mix4 as label: T2: /mix4 sF \"xmit\" #F T2: /mix4 ss \"desthost\" \"127.0.0.1\" T2: /mix4 si \"outport\" 5511 T2: /mix4 si \"errport\" 5512 T2: /mix4/input_0/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_0/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_1/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_2/mute fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/level fff 0.0000 0.0000 1.0000 T2: /mix4/input_3/mute fff 0.0000 0.0000 1.0000","title":"Widget's OSC address"},{"location":"qreference/7-osc/#controlling-the-application-via-osc","text":"We can control any user interface element of the application by sending one of the previously discovered messages. For example to set the noise level of the application to 0.2 we send: T1$ oscsend localhost 5510 /noise/level f 0.2 If we now query /noise/level we get, as expected, the value 0.2 : T1$ oscsend localhost 5510 /noise/level s get T2: /noise/level fff 0.2000 0.0000 1.0000","title":"Controlling the application via OSC"},{"location":"qreference/7-osc/#turning-transmission-on","text":"The xmit message at the root level is used to control the realtime transmission of OSC messages corresponding to user interface's actions. For examples: T1$ oscsend localhost 5510 /noise si xmit 1 turns transmission in ALL mode. Now if we move the level slider we get a bunch of messages: T2: /noise/level f 0.024000 T2: /noise/level f 0.032000 T2: /noise/level f 0.105000 T2: /noise/level f 0.250000 T2: /noise/level f 0.258000 T2: /noise/level f 0.185000 T2: /noise/level f 0.145000 T2: /noise/level f 0.121000 T2: /noise/level f 0.105000 T2: /noise/level f 0.008000 T2: /noise/level f 0.000000 This feature can be typically used for automation to record and replay actions on the user interface, or to remote control from one application to another. It can be turned OFF any time using: T1$ oscsend localhost 5510 /noise si xmit 0 Use the ALIAS (xmit = 2) mode if you need restricted access to your program: when ALIAS is mode is used, only aliases of input elements (sliders, buttons...) can be used to control them, and output elements (bargraph) will only emit on their aliases.","title":"Turning transmission ON"},{"location":"qreference/7-osc/#filtering-osc-messages","text":"When the transmission of OSC messages is ON, all the user interface elements are sent through the OSC connection. T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.1 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.25 T2: /harpe/level f 0.024000 T2: /harpe/hand f 0.44 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.78 T2: /noise/level f 0.145000 T2: /harpe/hand f 0.99 We can choose to filter the unwanted parameters (or group of parameters). For example: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter /harpe/level As a result, we will receive: T2: /harpe/hand f 0.1 T2: /harpe/hand f 0.25 T2: /harpe/hand f 0.44 T2: /harpe/hand f 0.78 To reset the filter, send: T1$ oscsend localhost 5510 /harpe si xmit 1 xmitfilter","title":"Filtering OSC messages"},{"location":"qreference/7-osc/#using-osc-aliases","text":"Aliases are a convenient mechanism to control a Faust application from a preexisting set of OSC messages. Let's say we want to control our noise example with touchOSC on Android. The first step is to configure TouchOSC host to 192.168.1.102 (the host running our noise application) and outgoing port to 5510. Then we can use oscdump 5510 (after quitting the noise application in order to free port 5510) to visualize the OSC messages sent by TouchOSC. Let's use for that the left slider of simple layout. Here is what we get: T2: /1/fader1 f 0.000000 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.004975 T2: /1/fader1 f 0.008125 T2: /1/fader1 f 0.017473 T2: /1/fader1 f 0.032499 T2: /1/fader1 f 0.051032 T2: ... T2: /1/fader1 f 0.993289 T2: /1/fader1 f 1.000000 We can associate this OSC message to the noise level slider by inserting the metadata [osc:/1/fader1 0 1] into the slider's label: \\marginpar{ Several osc aliases can be inserted into a single label allowing the same widget to be controlled by several OSC messages. process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1 0 1]\",0,0,1,0.01); Because here the range of /1/fader1 is 0 to 1 like the level slider we can remove the range mapping information and write simply : process = library(\"music.lib\").noise * hslider(\"level[osc:/1/fader1]\", 0, 0, 1, 0.01); TouchOSC can also send accelerometer data by enabling Settings/Options/Accelerometer. Using again oscdump 5510 we can visualize the messages send by TouchOSC: T2: ... T2: /accxyz fff -0.147842 0.019752 9.694721 T2: /accxyz fff -0.157419 0.016161 9.686341 T2: /accxyz fff -0.167594 0.012570 9.683948 T2: ... As we can see TouchOSC send the x, y and z accelerometers in a single message, as a triplet of values ranging approximatively from -9.81 to 9.81 . In order to select the appropriate accelerometer we need to concatenate to /accxyz a suffix /0, /1 or /2. For example /accxyz/0 will correspond to x, /accxyz/1 to y, etc. We also need to define a mapping because the ranges are different: process = library(\"music.lib\").noise * hslider(\"level[osc:/accxyz/0 0 9.81]\",0,0,1,0.01); alias description [osc:/1/rotary1 0 1] top left rotary knob [osc:/1/rotary2 0 1] middle left rotary knob [osc:/1/rotary3 0 1] bottom left rotary knob [osc:/1/push1 0 1] bottom left push button [osc:/1/push2 0 1] bottom center left push button [osc:/1/toggle1 0 1] top center left toggle button [osc:/1/toggle2 0 1] middle center left toggle button [osc:/1/fader1 0 1] center left vertical fader [osc:/1/toggle3 0 1] top center right toggle button [osc:/1/toggle4 0 1] middle center right toggle button [osc:/1/fader2 0 1] center right vertical toggle button [osc:/1/rotary4 0 1] top right rotary knob [osc:/1/rotary5 0 1] middle right rotary knob [osc:/1/rotary6 0 1] bottom right rotary knob [osc:/1/push3 0 1] bottom center right push button [osc:/1/push4 0 1] bottom right push button [osc:/1/fader3 0 1] bottom horizontal fader [osc:/accxyz/0 -10 10] x accelerometer [osc:/accxyz/1 -10 10] y accelerometer [osc:/accxyz/2 -10 10] z accelerometer Examples of OSC message aliases for TouchOSC (layout Mix2).","title":"Using OSC aliases"},{"location":"qreference/7-osc/#osc-cheat-sheet","text":"","title":"OSC cheat sheet"},{"location":"qreference/7-osc/#default-ports","text":"5510 default listening port 5511 default transmission port 5512 default error port 5513... alternative listening ports","title":"Default ports"},{"location":"qreference/7-osc/#command-line-options","text":"-port n set the port number used by the application to receive messages -outport n set the port number used by the application to transmit messages -errport n set the port number used by the application to transmit error messages -desthost h set the destination host for the messages sent by the application -xmit 0|1|2 turn transmission OFF, ALL or ALIAS (default OFF) -xmitfilter s filter the Faust paths at emission time","title":"Command line options"},{"location":"qreference/7-osc/#discovery-messages","text":"oscsend host port \"/*\" s hello discover if any OSC application is listening on port port oscsend host port \"/*\" s get query OSC interface of application listening on port port oscsend host port \"/*\" s json query JSON description of application listening on port port","title":"Discovery messages"},{"location":"qreference/7-osc/#control-messages","text":"oscsend host port \"/*\" si xmit 0|1|2 set transmission mode oscsend host port widget s get get widget's value oscsend host port widget f v set widget's value","title":"Control messages"},{"location":"qreference/7-osc/#alias","text":"\"...[osc: address lo hi ]...\" alias with lo \\rightarrow min , hi \\rightarrow max mapping \"...[osc: address ]...\" alias with min , max clipping","title":"Alias"},{"location":"qreference/7-osc/#dsp-with-polyphonic-support","text":"When the DSP code is compiled in polyphonic mode, the generated program will create a more complex hierarchy to possibly access and control individual voices. The following OSC messages reflect the same DSP code either compiled normally, or in polyphonic mode (only part of the OSC hierarchies are displayed here): // Mono mode /Organ/vol f -10.0 /Organ/pan f 0.0 // Polyphonic mode /Polyphonic/Voices/Organ/pan f 0.0 /Polyphonic/Voices/Organ/vol f -10.0 ... /Polyphonic/Voice1/Organ/vol f -10.0 /Polyphonic/Voice1/Organ/pan f 0.0 ... /Polyphonic/Voice2/Organ/vol f -10.0 /Polyphonic/Voice2/Organ/pan f 0.0 Note that to save space on the screen, the /Polyphonic/VoiceX/xxx syntax is used when the number of allocated voices is less than 8, then the /Polyphonic/VX/xxx syntax is used when more voices are used.","title":"DSP with polyphonic support"},{"location":"qreference/8-http/","text":"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 HTTPD can be freely combined. While OSC support is installed by default when Faust is build, this is not the case for HTTP. That's because it depends on 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. The HTTP support can be activated using the -httpd option when building the audio application with the appropriate faust2xxx command. The following table (table tab:httparch ) lists Faust 's architectures which provide HTTP support. Audio system Environment HTTP support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with HTTP support. A simple example To illustrate how HTTP support works let's reuse our previous mix4.dsp example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); We are going to compile this example as a standalone Jack QT application with HTTP support using the command: faust2jaqt -httpd mix4.dsp Th effect of the -httpd is to embed a small Web server into the application, which purpose is to serve an HTML page representing its user interface. This page makes use of JavaScript and SVG and is quite similar to the native QT interface. When we start the application from the command line: ./mix4 we get various information on the standard output, including: Faust httpd server version 0.72 is running on TCP port 5510 As we can see the embedded Web server is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page reproduced figure fig:mix4-http . User interface of mix4 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 that return 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\" } ] }, ... ] } ] Quering the state of the application Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge an 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 query 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 the 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 Muting input 1 by forging the appropriate URL Let's say that we want to mute input 1 of our mixer. We can use for that purpose the URL http://localhost:5510/mixer/input_1/mute?value=1 obtained by concatenating ?value=1 at the end of the widget URL. All widgets can be controlled similarly. For example http://localhost:5510/mixer/input_3/level?value=0.7 will sets 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 purely be developed in C/C++, then build a proxy version of the use interface, and set and get parameters using HTTP requests. This mode can be started dynamically using the _ -server URL _ parameter. Assuming an application with HTTP support is running remotely on the given URL, the control application will fetch its json description, use it to dynamically build the user interface, and allow to access 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 5510 default TCP port used by the application's Web server 5511... alternative TCP ports Command line options -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 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 \\subsubsection*{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 is either a group (of items) or a widget. \\subsubsection*{Groups} A group is essentially a list of items with a specific layout: { \"type\": <type>, \"label\": <label>, \"items\": [ <item>, <item>,...] The defines the layout. It can be either \"vgroup\" , \"hgroup\" or \"tgroup\" \\subsubsection*{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 : \"button\" , \"checkbox\" , \"nentry\" , \"vslider\" , \"hslider\" , \"vbargraph\" or \"hbargraph\" .","title":"8 http"},{"location":"qreference/8-http/#http-support","text":"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 HTTPD can be freely combined. While OSC support is installed by default when Faust is build, this is not the case for HTTP. That's because it depends on 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. The HTTP support can be activated using the -httpd option when building the audio application with the appropriate faust2xxx command. The following table (table tab:httparch ) lists Faust 's architectures which provide HTTP support. Audio system Environment HTTP support Linux Alsa GTK, Qt, Console yes Jack GTK, Qt, Console yes Netjack GTK, Qt, Console yes PortAudio GTK, Qt yes Mac OS X CoreAudio Qt yes Jack Qt, Console yes Netjack Qt, Console yes PortAudio Qt yes Windows Jack Qt, Console yes PortAudio Qt yes Faust architectures with HTTP support.","title":"HTTP support"},{"location":"qreference/8-http/#a-simple-example","text":"To illustrate how HTTP support works let's reuse our previous mix4.dsp example, a very simplified monophonic audio mixer with 4 inputs and one output. For each input we have a mute button and a level slider: input(v) = vgroup(\"input %v\", *(1-checkbox(\"mute\")) : *(vslider(\"level\", 0, 0, 1, 0.01))); process = hgroup(\"mixer\", par(i, 4, input(i)) :> _); We are going to compile this example as a standalone Jack QT application with HTTP support using the command: faust2jaqt -httpd mix4.dsp Th effect of the -httpd is to embed a small Web server into the application, which purpose is to serve an HTML page representing its user interface. This page makes use of JavaScript and SVG and is quite similar to the native QT interface. When we start the application from the command line: ./mix4 we get various information on the standard output, including: Faust httpd server version 0.72 is running on TCP port 5510 As we can see the embedded Web server is running by default on TCP port 5510. The entry point is http://localhost:5510 . It can be open from any recent browser and it produces the page reproduced figure fig:mix4-http . User interface of mix4","title":"A simple example"},{"location":"qreference/8-http/#json-description-of-the-user-interface","text":"The communication between the application and the Web browser is based on several underlying URLs. The first one is http://localhost:5510/JSON that return 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\" } ] }, ... ] } ]","title":"JSON description of the user interface"},{"location":"qreference/8-http/#quering-the-state-of-the-application","text":"Each widget has a unique \"address\" field that can be used to query its value. In our example here the level of the input 0 has the address /mixer/input_0/level . The address can be used to forge an 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 query 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 the 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","title":"Quering the state of the application"},{"location":"qreference/8-http/#changing-the-value-of-a-widget","text":"Muting input 1 by forging the appropriate URL Let's say that we want to mute input 1 of our mixer. We can use for that purpose the URL http://localhost:5510/mixer/input_1/mute?value=1 obtained by concatenating ?value=1 at the end of the widget URL. All widgets can be controlled similarly. For example http://localhost:5510/mixer/input_3/level?value=0.7 will sets the input 3 level to 0.7.","title":"Changing the value of a widget"},{"location":"qreference/8-http/#proxy-control-access-to-the-web-server","text":"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 purely be developed in C/C++, then build a proxy version of the use interface, and set and get parameters using HTTP requests. This mode can be started dynamically using the _ -server URL _ parameter. Assuming an application with HTTP support is running remotely on the given URL, the control application will fetch its json description, use it to dynamically build the user interface, and allow to access the remote parameters.","title":"Proxy control access to the Web server"},{"location":"qreference/8-http/#http-cheat-sheet","text":"Here is a summary of the various URLs used to interact with the application's Web server.","title":"HTTP cheat sheet"},{"location":"qreference/8-http/#default-ports","text":"5510 default TCP port used by the application's Web server 5511... alternative TCP ports","title":"Default ports"},{"location":"qreference/8-http/#command-line-options","text":"-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","title":"Command line options"},{"location":"qreference/8-http/#urls","text":"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","title":"URLs"},{"location":"qreference/8-http/#json","text":"\\subsubsection*{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 is either a group (of items) or a widget. \\subsubsection*{Groups} A group is essentially a list of items with a specific layout: { \"type\": <type>, \"label\": <label>, \"items\": [ <item>, <item>,...] The defines the layout. It can be either \"vgroup\" , \"hgroup\" or \"tgroup\" \\subsubsection*{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 : \"button\" , \"checkbox\" , \"nentry\" , \"vslider\" , \"hslider\" , \"vbargraph\" or \"hbargraph\" .","title":"JSON"},{"location":"qreference/9-midi/","text":"MIDI support Similarly to OSC, several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments. MIDI messages description in the dsp source code MIDI control messages are described as metadata in UI elements. They are decoded by a special architecture MidiUI class that will parse incoming MIDI messages and update the appropriate control parameters, or send MIDI messages when the UI elements (sliders, buttons...) are moved. Description of the possible standard MIDI messages Below, when a 7-bit MIDI parameter is used to drive a button or checkbox, its maximum value 127 maps to 1 (\"on\") while its minimum value 0 maps to 0 (\"off\"). A special [midi:xxx yyy...] metadata needs to be added in the UI element description. The more usual MIDI messages can be used as described here: [midi:ctrl num] in a slider or bargraph will map the UI element value to (0, 127) range. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyon pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyoff pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-off velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:key pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0. Note-on and note-off events will be handled, [midi:keypress pitch] in a slider or bargraph will register the UI element's state-variable to be driven by the MIDI key-pressure (an integer between 0 and 127) from MIDI key, [midi:pgm num] in a slider or bargraph will map the UI element value to the progchange value, so progchange message with the same num value will be sent. When used with a button or checkbox, 1 will send the progchange message with num value, 0 will send nothing, [midi:chanpress num] in a slider or bargraph will map the UI element value to the chanpress value, so chanpress message with the same num value will be sent. When used with a button or checkbox, 1 will send the chanpress message with num value, 0 will send nothing, [midi:pitchwheel] in a slider or bargraph will map the UI element value to (0,16383) range. When used with a button or checkbox, 1 will be mapped to 16383, 0 will be mapped to 0. A simple example An example with a volume slider controlled with MIDI ctrlchange 7 messages : //----------------------------------------------- // Volume MIDI control in dB //----------------------------------------------- import(\"music.lib\"); smooth(c) = *(1-c) : +~*(c); gain = vslider(\"Volume [midi:ctrl 7]\", 0, -70, +4, 0.1) : db2linear : smooth(0.999); process = *(gain); A complete testing example named midi_tester.dsp is available in the Faust distribution examples folder. MIDI messages testing example The MIDI support can be activated using the -midi option when building the audio application with the appropriate faust2xxx command. The following table (table tab:midiarch ) lists Faust 's architectures which provide MIDI support. Audio system Environment HTTP support Linux Alsa Qt yes Jack Qt yes Mac OS X CoreAudio Qt yes Jack Qt yes Faust architectures with HTTP support. MIDI synchronization MIDI clock based synchronization can be used to slave a given Faust program. The following three messages need to be used: [midi:start] in a button or checkbox will trigger a value of 1 when a start MIDI message is received [midi:stop] in a button or checkbox will trigger a value of 0 when a stop MIDI message is received [midi:clock] in a button or checkbox will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received, seen by Faust code as a square command signal, to be used to compute higher level information. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"music.lib\"); // square signal (1/0), changing state at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled with MIDI start/stop messages play = checkbox(\"ON/OFF [midi:start] [midi:stop]\"); // detect front front(x) = (x-x') != 0.0; // count number of peaks during one second freq(x) = (x-x@SR) : + ~ _; process = osc(8*freq(front(clocker))) * play;","title":"9 midi"},{"location":"qreference/9-midi/#midi-support","text":"Similarly to OSC, several Faust architectures also provide MIDI support. This allows Faust applications to be controlled from any MIDI device (or to control MIDI devices). MIDI is also the preferable way to control Polyphonic instruments.","title":"MIDI support"},{"location":"qreference/9-midi/#midi-messages-description-in-the-dsp-source-code","text":"MIDI control messages are described as metadata in UI elements. They are decoded by a special architecture MidiUI class that will parse incoming MIDI messages and update the appropriate control parameters, or send MIDI messages when the UI elements (sliders, buttons...) are moved.","title":"MIDI messages description in the dsp source code"},{"location":"qreference/9-midi/#description-of-the-possible-standard-midi-messages","text":"Below, when a 7-bit MIDI parameter is used to drive a button or checkbox, its maximum value 127 maps to 1 (\"on\") while its minimum value 0 maps to 0 (\"off\"). A special [midi:xxx yyy...] metadata needs to be added in the UI element description. The more usual MIDI messages can be used as described here: [midi:ctrl num] in a slider or bargraph will map the UI element value to (0, 127) range. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyon pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:keyoff pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-off velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0, [midi:key pitch] in a slider or bargraph will register the UI element's state-variable to be driven by MIDI note-on velocity (an integer between 0 and 127) of the specified key between 0 and 127. When used with a button or checkbox, 1 will be mapped to 127, 0 will be mapped to 0. Note-on and note-off events will be handled, [midi:keypress pitch] in a slider or bargraph will register the UI element's state-variable to be driven by the MIDI key-pressure (an integer between 0 and 127) from MIDI key, [midi:pgm num] in a slider or bargraph will map the UI element value to the progchange value, so progchange message with the same num value will be sent. When used with a button or checkbox, 1 will send the progchange message with num value, 0 will send nothing, [midi:chanpress num] in a slider or bargraph will map the UI element value to the chanpress value, so chanpress message with the same num value will be sent. When used with a button or checkbox, 1 will send the chanpress message with num value, 0 will send nothing, [midi:pitchwheel] in a slider or bargraph will map the UI element value to (0,16383) range. When used with a button or checkbox, 1 will be mapped to 16383, 0 will be mapped to 0.","title":"Description of the possible standard MIDI messages"},{"location":"qreference/9-midi/#a-simple-example","text":"An example with a volume slider controlled with MIDI ctrlchange 7 messages : //----------------------------------------------- // Volume MIDI control in dB //----------------------------------------------- import(\"music.lib\"); smooth(c) = *(1-c) : +~*(c); gain = vslider(\"Volume [midi:ctrl 7]\", 0, -70, +4, 0.1) : db2linear : smooth(0.999); process = *(gain); A complete testing example named midi_tester.dsp is available in the Faust distribution examples folder. MIDI messages testing example The MIDI support can be activated using the -midi option when building the audio application with the appropriate faust2xxx command. The following table (table tab:midiarch ) lists Faust 's architectures which provide MIDI support. Audio system Environment HTTP support Linux Alsa Qt yes Jack Qt yes Mac OS X CoreAudio Qt yes Jack Qt yes Faust architectures with HTTP support.","title":"A simple example"},{"location":"qreference/9-midi/#midi-synchronization","text":"MIDI clock based synchronization can be used to slave a given Faust program. The following three messages need to be used: [midi:start] in a button or checkbox will trigger a value of 1 when a start MIDI message is received [midi:stop] in a button or checkbox will trigger a value of 0 when a stop MIDI message is received [midi:clock] in a button or checkbox will deliver a sequence of successive 1 and 0 values each time a clock MIDI message is received, seen by Faust code as a square command signal, to be used to compute higher level information. A typical Faust program will then use the MIDI clock stream to possibly compute the BPM information, or for any synchronization need it may have. Here is a simple example of a sinus generated which a frequency controlled by the MIDI clock stream, and starting/stopping when receiving the MIDI start/stop messages: import(\"music.lib\"); // square signal (1/0), changing state at each received clock clocker = checkbox(\"MIDI clock[midi:clock]\"); // ON/OFF button controlled with MIDI start/stop messages play = checkbox(\"ON/OFF [midi:start] [midi:stop]\"); // detect front front(x) = (x-x') != 0.0; // count number of peaks during one second freq(x) = (x-x@SR) : + ~ _; process = osc(8*freq(front(clocker))) * play;","title":"MIDI synchronization"},{"location":"tutorials/basic-osc/","text":"Making a Sine Oscillator From Scratch and Additive Synthesis Goals Implementing a sine oscillator from scratch in Faust Understand the relation between the sine function and the generated sound Use multiple sine oscillator to implement an additive synthesizer Use SmartKeyboard to produce polyphonic mobile apps to control this synth Sine Function in Faust The sine function in Faust works like on a calculator: will output 0 . To verify this, you could click on the truck (export function) in the Faust Online IDE and then choose misc/csv to get a table containing the first n samples output by the program. will output 1 . Note that stdfaust.lib is imported here in order to use ma.pi . will output 0 . Implementing a Phasor What is needed to \"print\" a full sine wave? -> We need to create a series of numbers (vector) going from 0 to 2pi, in other words, draw a line. First let's create a \"counter\" in Faust: Don't forget that you can always print the output of a Faust program by using the in the Faust Online IDE misc/csv The current counter counts one by one. Instead we'd like to count slower 0.01 by 0.01. Now, we want to reset the counter back to 0 when it reaches 1. This can be done easily using the ma.frac function: Note the use of ma.frac in the loop here to prevent numerical errors. Try to run the program (play button in the editor) and it should make sound! What are we generating here? -> A sawtooth wave . How do we change the pitch of the sawtooth wave? -> We should increment the counter faster or slower. Try different values (e.g., 0.001, 0.1, etc.). Instead of controlling the increment of the counter, we'd like to control the frequency of the sawtooth wave. To do that, we need to know the number of values of the wave processed by the computer in one second. That's what we call the sampling rate . This value changes in function of the context of the program so it can be retrieved with ma.SR . A sampling rate of 44100 corresponds to a frequency of 44100 Hz. If we want a frequency of 440, what increment do we need to put in our counter? -> freq/ma.SR In the end, we get: A this point feel free to plot the output of the Faust program using misc/csv in the export function of the online editor. The freq parameter can be controlled dynamically: The code can be cleaned up by placing our phasor in a function: Generating a Sine Wave Almost there! Now we want our phasor to go from 0 to 2pi so that we can plug it to the sin function: Note that we created an osc function in order to have a cleaner code. Additive Synthesis A sine wave generates what we call a pure tone . More complex sounds can be produced by adding multiple sine waves together to create harmonics . The frequency and the gain of each harmonic will determine the timbre of the sound . Using this technique, it is possible to \"sculpt\" a sound. A simple organ synthesizer can be implemented using additive synthesis: This is what we call a harmonic series . Making a Synthesizer In order to use this synthesizer with a keyboard, we need to be able to turn the sound on and off and also to control its volume: An envelope could be added to make it sound more natural: This synth can be controlled with a MIDI keyboard. Turn it Into an Android App Use the export function of the Faust editor and choose android/smartkeyb install the app on the phone and have fun! This could also be turned into an app always making sound and controllable with accelerometers: import(\"stdfaust.lib\"); f = hslider(\"freq[acc: 0 0 -10 0 10]\",1000,50,2000,0.01) : si.smoo; phasor(freq) = (+(freq/ma.SR) ~ ma.frac); osc(freq) = sin(phasor(freq)*2*ma.PI); organ(freq) = (osc(freq) + osc(freq*2) + osc(freq*3))/3; process = organ(f); In that case, export with android/android .","title":"Making a Sine Oscillator From Scratch"},{"location":"tutorials/basic-osc/#making-a-sine-oscillator-from-scratch-and-additive-synthesis","text":"","title":"Making a Sine Oscillator From Scratch and Additive Synthesis"},{"location":"tutorials/basic-osc/#goals","text":"Implementing a sine oscillator from scratch in Faust Understand the relation between the sine function and the generated sound Use multiple sine oscillator to implement an additive synthesizer Use SmartKeyboard to produce polyphonic mobile apps to control this synth","title":"Goals"},{"location":"tutorials/basic-osc/#sine-function-in-faust","text":"The sine function in Faust works like on a calculator: will output 0 . To verify this, you could click on the truck (export function) in the Faust Online IDE and then choose misc/csv to get a table containing the first n samples output by the program. will output 1 . Note that stdfaust.lib is imported here in order to use ma.pi . will output 0 .","title":"Sine Function in Faust"},{"location":"tutorials/basic-osc/#implementing-a-phasor","text":"What is needed to \"print\" a full sine wave? -> We need to create a series of numbers (vector) going from 0 to 2pi, in other words, draw a line. First let's create a \"counter\" in Faust: Don't forget that you can always print the output of a Faust program by using the in the Faust Online IDE misc/csv The current counter counts one by one. Instead we'd like to count slower 0.01 by 0.01. Now, we want to reset the counter back to 0 when it reaches 1. This can be done easily using the ma.frac function: Note the use of ma.frac in the loop here to prevent numerical errors. Try to run the program (play button in the editor) and it should make sound! What are we generating here? -> A sawtooth wave . How do we change the pitch of the sawtooth wave? -> We should increment the counter faster or slower. Try different values (e.g., 0.001, 0.1, etc.). Instead of controlling the increment of the counter, we'd like to control the frequency of the sawtooth wave. To do that, we need to know the number of values of the wave processed by the computer in one second. That's what we call the sampling rate . This value changes in function of the context of the program so it can be retrieved with ma.SR . A sampling rate of 44100 corresponds to a frequency of 44100 Hz. If we want a frequency of 440, what increment do we need to put in our counter? -> freq/ma.SR In the end, we get: A this point feel free to plot the output of the Faust program using misc/csv in the export function of the online editor. The freq parameter can be controlled dynamically: The code can be cleaned up by placing our phasor in a function:","title":"Implementing a Phasor"},{"location":"tutorials/basic-osc/#generating-a-sine-wave","text":"Almost there! Now we want our phasor to go from 0 to 2pi so that we can plug it to the sin function: Note that we created an osc function in order to have a cleaner code.","title":"Generating a Sine Wave"},{"location":"tutorials/basic-osc/#additive-synthesis","text":"A sine wave generates what we call a pure tone . More complex sounds can be produced by adding multiple sine waves together to create harmonics . The frequency and the gain of each harmonic will determine the timbre of the sound . Using this technique, it is possible to \"sculpt\" a sound. A simple organ synthesizer can be implemented using additive synthesis: This is what we call a harmonic series .","title":"Additive Synthesis"},{"location":"tutorials/basic-osc/#making-a-synthesizer","text":"In order to use this synthesizer with a keyboard, we need to be able to turn the sound on and off and also to control its volume: An envelope could be added to make it sound more natural: This synth can be controlled with a MIDI keyboard.","title":"Making a Synthesizer"},{"location":"tutorials/basic-osc/#turn-it-into-an-android-app","text":"Use the export function of the Faust editor and choose android/smartkeyb install the app on the phone and have fun! This could also be turned into an app always making sound and controllable with accelerometers: import(\"stdfaust.lib\"); f = hslider(\"freq[acc: 0 0 -10 0 10]\",1000,50,2000,0.01) : si.smoo; phasor(freq) = (+(freq/ma.SR) ~ ma.frac); osc(freq) = sin(phasor(freq)*2*ma.PI); organ(freq) = (osc(freq) + osc(freq*2) + osc(freq*3))/3; process = organ(f); In that case, export with android/android .","title":"Turn it Into an Android App"},{"location":"tutorials/box-api/","text":"Using the box API The box API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the box API, and take profit of part of the Faust compiler infrastructure. Faust compiler structure The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated into a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends. Accessing the box stage A new intermediate public entry point has been created in the Semantic Phase , after the Evaluation, lambda-calculus step to allow the creation of a box expression, then beneficiate of all remaining parts of the compilation chain. The box API (or the C box API version) allows to programmatically create the box expression, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the signal API allows to access another stage in the compilation stage. Compiling box expressions To use the box API, the following steps must be taken: creating a global compilation context using the createLibContext function creating a box expression using the box API, progressively building more complex expressions by combining simpler ones compiling the box expression using the createCPPDSPFactoryFromBoxes function to create a DSP factory (or createDSPFactoryFromBoxes to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromBoxes to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used. Tools Let's first define a compile function, which uses the createCPPDSPFactoryFromBoxes function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\ Examples For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps). All presented C++ examples (as well as some more) are defined in the box-tester tool, to be compiled with make box-tester in the tools/benchmark folder. Expression generating constant signals Let's create a program generating a parallel construction of 7 and 3.14 constant values. Here is the Faust DSP code: The following code creates a box expression, containing a box boxPar(boxInt(7), boxReal(3.14)) expression, then compile it and display the C++ class: static void test1() { COMPILER ( Box box = boxPar(boxInt(7), boxReal(3.14)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(7); output1[i0] = FAUSTFLOAT(3.1400001f); } } Doing some mathematical operations on an input signal Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with boxWire() expression, then transformed using the boxAdd and boxSeq operators to produce one output: static void test2() { COMPILER ( Box box = boxSeq(boxPar(boxWire(), boxReal(3.14)), boxAdd()); compile(\"test2\", box); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((float(input0[i0]) + 3.1400001f)); } } In the published API, most operators are exported as simple no-argument operators, using the language core-syntax . The prefix notation has been added for each relevant operator, and can be used with additional multi-argument versions. So the previous example can be written in a simpler way with the following code, which will produce the exact same C++: static void test3() { COMPILER ( Box box = boxAdd(boxWire(), boxReal(3.14)); compile(\"test3\", box); ) } Defining a delay expression Here is a simple program delaying the first input: The prefix-notation boxDelay(x, y) operator is used to delay the boxWire() first parameter with the second boxInt(7) : static void test6() { COMPILER ( Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test3\", test6); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(fVec0[7]); for (int j0 = 7; (j0 > 0); j0 = (j0 - 1)) { fVec0[j0] = fVec0[(j0 - 1)]; } } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code shows how to compile in vector mode: static void test7() { createLibContext(); Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test7\", box, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; float fYec0_tmp[40]; float* fYec0 = &fYec0_tmp[8]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 8); j0 = (j0 + 1)) { fYec0_tmp[j0] = fYec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[i] = float(input0[i]); } /* Post code */ for (int j1 = 0; (j1 < 8); j1 = (j1 + 1)) { fYec0_perm[j1] = fYec0_tmp[(vsize + j1)]; } /* Vectorizable loop 1 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec0[(i - 7)]); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test8() { COMPILER ( Box box = boxSplit(boxWire(), boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxMul(boxDelay(boxWire(), boxReal(3000)), boxReal(1.5)))); compile(\"test8\", box); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Equivalent box expressions It is really important to note that syntactically equivalent box expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( Box b1 = boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)); Box box = boxPar(b1, b1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( Box box = boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5))); compile(\"equivalent2\", box); ) } It can be a property to remember when creating a DSL on top of the box API. Using User Interface items User Interface items can be used, as in the following example, with a hslider : Built with the following code: static void test8() { COMPILER ( Box box = boxMul(boxWire(), boxHSlider(\"Freq [midi:ctrl 7][style:knob]\", boxReal(100), boxReal(100), boxReal(2000), boxReal(1))); compile(\"test8\", box); ) } The buildUserInterface method is generated, using the fHslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->declare(&fHslider0, \"midi\", \"ctrl 7\"); ui_interface->declare(&fHslider0, \"style\", \"knob\"); ui_interface->addHorizontalSlider(\"Freq\", &fHslider0, FAUSTFLOAT(100.0f), FAUSTFLOAT(100.0f), FAUSTFLOAT(2000.0f), FAUSTFLOAT(1.0f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((fSlow0 * float(input0[i0]))); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the box API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( Box box = boxMul(boxVSlider(\"h:Oscillator/freq\", boxReal(440), boxReal(50), boxReal(1000), boxReal(0.1)), boxVSlider(\"h:Oscillator/gain\", boxReal(0), boxReal(0), boxReal(1), boxReal(0.01))); compile(\"test9\", box); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); } Defining recursive signals Recursive signals can be defined using the boxRec expression. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( Box box = boxRec(boxAdd(), boxWire()); compile(\"test10\", box); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Accessing the global context In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the box language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Box SR() { return boxMin(boxReal(192000.0), boxMax(boxReal(1.0), boxFConst(SType::kSInt, \"fSampleFreq\", \"<math.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return boxFVar(SType::kSInt, \"count\", \"<math.h>\"); } So the following DSP program: Can be written at the box API level with: static void test11() { COMPILER ( Box box = boxPar(SR(), BS()); compile(\"test11\", box); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } } Creating tables Read only and read/write tables can be created. The read only table signal is created with boxReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxReadOnlyTable(boxInt(10), boxInt(1), boxIntCast(boxWire())); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with boxWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxWriteReadTable(boxInt(10), boxInt(1), boxIntCast(boxWire()), boxIntCast(boxWire()), boxIntCast(boxWire())); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } } Creating waveforms The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with boxWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(boxReal(100*i)); } Box box = boxWaveform(waveform); // the size and the waveform content compile(\"test12\", box); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } } Creating soundfile The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with boxSoundfile . Thus the following DSP code: Will be created using the box API with: static void test19() { COMPILER ( Box box = boxSoundfile(\"sound[url:{'tango.wav'}]\", boxInt(2), boxInt(0), boxInt(0)); compile(\"test19\", box); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; } Using the DSPToBoxes function Complete DSP programs can be compiled to boxes using the DSPToBoxes function, which takes a DSP program as a string, and returns the number of inputs/outputs and the created box: static void test25(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the oscillator Box osc = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = os.osc(440);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Compile it dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", osc, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } The resulting box expression can possibly be reused in a more complex construction, as in the following example, where a filter is created using the DSPToBoxes function, then called with a slider to control its frequency, and the actual input: static void test26(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the filter without parameter Box filter = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = fi.lowpass(5);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Create the filter parameters and connect Box cutoff = boxHSlider(\"cutoff\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box cutoffAndInput = boxPar(cutoff, boxWire()); Box filteredInput = boxSeq(cutoffAndInput, filter); bool res = getBoxType(filteredInput, &inputs, &outputs); std::cout << \"getBoxType inputs: \" << inputs << \" outputs: \" << outputs << std::endl; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", filteredInput, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } Note that the getBoxType function can be used to retrieve a given box number of inputs and outputs. Defining more complex expressions: phasor and oscillator More complex signal expressions can be defined, creating boxes using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Box decimalpart() { return boxSub(boxWire(), boxIntCast(boxWire())); } static Box phasor(Box f) { return boxSeq(boxDiv(f, SR()), boxRec(boxSplit(boxAdd(), decimalpart()), boxWire())); } And the main function combining them: static void test17() { COMPILER ( Box box = phasor(boxReal(440)); compile(\"test17\", box); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Box osc(Box f) { return boxSin(boxMul(boxMul(boxReal(2.0), boxReal(3.141592653)), phasor(f))); } static void test18() { COMPILER ( Box box = boxPar(osc(boxReal(440)), osc(boxReal(440))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } } Using the generated code Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromBoxes (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromBoxes (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory); Connecting the audio layer Audio drivers allow you to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop(); Connecting the controller layer Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual. Example with audio rendering and GUI control Here is a more complete example, first with the DSP code: Then with the C++ code using the box API: // Using the Interpreter backend. static void test22(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Generating the signals as an intermediate step The boxesToSignals function allows you to compile a box in a list of signals, to be used with the signal API . The following example shows how the two steps (box => signals then signals => DSP factory) can be chained, rewriting the previous code as: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); // Compile the 'box' to 'signals' tvec signals = boxesToSignals(box, error_msg); // Then compile the 'signals' to a DSP factory factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Polyphonic MIDI controllable simple synthesizer Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the box API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Box freq = boxNumEntry(\"freq\", boxReal(100), boxReal(100), boxReal(3000), boxReal(0.01)); Box gate = boxButton(\"gate\"); Box gain = boxNumEntry(\"gain\", boxReal(0.5), boxReal(0), boxReal(1), boxReal(0.01)); Box organ = boxMul(gate, boxAdd(boxMul(osc(freq), gain), boxMul(osc(boxMul(freq, boxInt(2))), gain))); // Stereo Box box = boxPar(organ, organ); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Examples with the C API The box API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create box expressions, where the LLVM backend is used with the C version createCDSPFactoryFromBoxes function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Box decimalpart() { return CboxSubAux(CboxWire(), CboxIntCastAux(CboxWire())); } static Box phasor(Box f) { return CboxSeq(CboxDivAux(f, SR()), CboxRec(CboxSplit(CboxAdd(), decimalpart()), CboxWire())); } static void test1() { createLibContext(); { Box box = phasor(CboxReal(2000)); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test1\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Box freq = CboxVSlider(\"h:Oscillator/freq\", CboxReal(440), CboxReal(50), CboxReal(1000), CboxReal(0.1)); Box gain = CboxVSlider(\"h:Oscillator/gain\", CboxReal(0), CboxReal(0), CboxReal(1), CboxReal(0.011)); Box box = CboxMulAux(freq, CboxMulAux(gain, CboxWire())); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test3\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the box-tester-c tool, to be compiled with make box-tester-c in the tools/benchmark folder.","title":"Using the box API"},{"location":"tutorials/box-api/#using-the-box-api","text":"The box API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the box API, and take profit of part of the Faust compiler infrastructure.","title":"Using the box API"},{"location":"tutorials/box-api/#faust-compiler-structure","text":"The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated into a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends.","title":"Faust compiler structure"},{"location":"tutorials/box-api/#accessing-the-box-stage","text":"A new intermediate public entry point has been created in the Semantic Phase , after the Evaluation, lambda-calculus step to allow the creation of a box expression, then beneficiate of all remaining parts of the compilation chain. The box API (or the C box API version) allows to programmatically create the box expression, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the signal API allows to access another stage in the compilation stage.","title":"Accessing the box stage"},{"location":"tutorials/box-api/#compiling-box-expressions","text":"To use the box API, the following steps must be taken: creating a global compilation context using the createLibContext function creating a box expression using the box API, progressively building more complex expressions by combining simpler ones compiling the box expression using the createCPPDSPFactoryFromBoxes function to create a DSP factory (or createDSPFactoryFromBoxes to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromBoxes to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used.","title":"Compiling box expressions"},{"location":"tutorials/box-api/#tools","text":"Let's first define a compile function, which uses the createCPPDSPFactoryFromBoxes function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\","title":"Tools"},{"location":"tutorials/box-api/#examples","text":"For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps). All presented C++ examples (as well as some more) are defined in the box-tester tool, to be compiled with make box-tester in the tools/benchmark folder.","title":"Examples"},{"location":"tutorials/box-api/#expression-generating-constant-signals","text":"Let's create a program generating a parallel construction of 7 and 3.14 constant values. Here is the Faust DSP code: The following code creates a box expression, containing a box boxPar(boxInt(7), boxReal(3.14)) expression, then compile it and display the C++ class: static void test1() { COMPILER ( Box box = boxPar(boxInt(7), boxReal(3.14)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(7); output1[i0] = FAUSTFLOAT(3.1400001f); } }","title":"Expression generating constant signals"},{"location":"tutorials/box-api/#doing-some-mathematical-operations-on-an-input-signal","text":"Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with boxWire() expression, then transformed using the boxAdd and boxSeq operators to produce one output: static void test2() { COMPILER ( Box box = boxSeq(boxPar(boxWire(), boxReal(3.14)), boxAdd()); compile(\"test2\", box); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((float(input0[i0]) + 3.1400001f)); } } In the published API, most operators are exported as simple no-argument operators, using the language core-syntax . The prefix notation has been added for each relevant operator, and can be used with additional multi-argument versions. So the previous example can be written in a simpler way with the following code, which will produce the exact same C++: static void test3() { COMPILER ( Box box = boxAdd(boxWire(), boxReal(3.14)); compile(\"test3\", box); ) }","title":"Doing some mathematical operations on an input signal"},{"location":"tutorials/box-api/#defining-a-delay-expression","text":"Here is a simple program delaying the first input: The prefix-notation boxDelay(x, y) operator is used to delay the boxWire() first parameter with the second boxInt(7) : static void test6() { COMPILER ( Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test3\", test6); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(fVec0[7]); for (int j0 = 7; (j0 > 0); j0 = (j0 - 1)) { fVec0[j0] = fVec0[(j0 - 1)]; } } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code shows how to compile in vector mode: static void test7() { createLibContext(); Box box = boxDelay(boxWire(), boxInt(7)); compile(\"test7\", box, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; float fYec0_tmp[40]; float* fYec0 = &fYec0_tmp[8]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ for (int j0 = 0; (j0 < 8); j0 = (j0 + 1)) { fYec0_tmp[j0] = fYec0_perm[j0]; } /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[i] = float(input0[i]); } /* Post code */ for (int j1 = 0; (j1 < 8); j1 = (j1 + 1)) { fYec0_perm[j1] = fYec0_tmp[(vsize + j1)]; } /* Vectorizable loop 1 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec0[(i - 7)]); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test8() { COMPILER ( Box box = boxSplit(boxWire(), boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxMul(boxDelay(boxWire(), boxReal(3000)), boxReal(1.5)))); compile(\"test8\", box); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } }","title":"Defining a delay expression"},{"location":"tutorials/box-api/#equivalent-box-expressions","text":"It is really important to note that syntactically equivalent box expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( Box b1 = boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)); Box box = boxPar(b1, b1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( Box box = boxPar(boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5)), boxAdd(boxDelay(boxWire(), boxReal(500)), boxReal(0.5))); compile(\"equivalent2\", box); ) } It can be a property to remember when creating a DSL on top of the box API.","title":"Equivalent box expressions"},{"location":"tutorials/box-api/#using-user-interface-items","text":"User Interface items can be used, as in the following example, with a hslider : Built with the following code: static void test8() { COMPILER ( Box box = boxMul(boxWire(), boxHSlider(\"Freq [midi:ctrl 7][style:knob]\", boxReal(100), boxReal(100), boxReal(2000), boxReal(1))); compile(\"test8\", box); ) } The buildUserInterface method is generated, using the fHslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->declare(&fHslider0, \"midi\", \"ctrl 7\"); ui_interface->declare(&fHslider0, \"style\", \"knob\"); ui_interface->addHorizontalSlider(\"Freq\", &fHslider0, FAUSTFLOAT(100.0f), FAUSTFLOAT(100.0f), FAUSTFLOAT(2000.0f), FAUSTFLOAT(1.0f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fHslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT((fSlow0 * float(input0[i0]))); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the box API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( Box box = boxMul(boxVSlider(\"h:Oscillator/freq\", boxReal(440), boxReal(50), boxReal(1000), boxReal(0.1)), boxVSlider(\"h:Oscillator/gain\", boxReal(0), boxReal(0), boxReal(1), boxReal(0.01))); compile(\"test9\", box); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); }","title":"Using User Interface items"},{"location":"tutorials/box-api/#defining-recursive-signals","text":"Recursive signals can be defined using the boxRec expression. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( Box box = boxRec(boxAdd(), boxWire()); compile(\"test10\", box); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } }","title":"Defining recursive signals"},{"location":"tutorials/box-api/#accessing-the-global-context","text":"In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the box language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Box SR() { return boxMin(boxReal(192000.0), boxMax(boxReal(1.0), boxFConst(SType::kSInt, \"fSampleFreq\", \"<math.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return boxFVar(SType::kSInt, \"count\", \"<math.h>\"); } So the following DSP program: Can be written at the box API level with: static void test11() { COMPILER ( Box box = boxPar(SR(), BS()); compile(\"test11\", box); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } }","title":"Accessing the global context"},{"location":"tutorials/box-api/#creating-tables","text":"Read only and read/write tables can be created. The read only table signal is created with boxReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxReadOnlyTable(boxInt(10), boxInt(1), boxIntCast(boxWire())); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with boxWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( Box box = boxWriteReadTable(boxInt(10), boxInt(1), boxIntCast(boxWire()), boxIntCast(boxWire()), boxIntCast(boxWire())); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } }","title":"Creating tables"},{"location":"tutorials/box-api/#creating-waveforms","text":"The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with boxWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(boxReal(100*i)); } Box box = boxWaveform(waveform); // the size and the waveform content compile(\"test12\", box); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } }","title":"Creating waveforms"},{"location":"tutorials/box-api/#creating-soundfile","text":"The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with boxSoundfile . Thus the following DSP code: Will be created using the box API with: static void test19() { COMPILER ( Box box = boxSoundfile(\"sound[url:{'tango.wav'}]\", boxInt(2), boxInt(0), boxInt(0)); compile(\"test19\", box); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; }","title":"Creating soundfile"},{"location":"tutorials/box-api/#using-the-dsptoboxes-function","text":"Complete DSP programs can be compiled to boxes using the DSPToBoxes function, which takes a DSP program as a string, and returns the number of inputs/outputs and the created box: static void test25(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the oscillator Box osc = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = os.osc(440);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Compile it dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", osc, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } The resulting box expression can possibly be reused in a more complex construction, as in the following example, where a filter is created using the DSPToBoxes function, then called with a slider to control its frequency, and the actual input: static void test26(int argc, char* argv[]) { createLibContext(); { int inputs = 0; int outputs = 0; string error_msg; // Create the filter without parameter Box filter = DSPToBoxes(\"import(\\\"stdfaust.lib\\\"); process = fi.lowpass(5);\", argc, (const char**)argv, &inputs, &outputs, error_msg); // Create the filter parameters and connect Box cutoff = boxHSlider(\"cutoff\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box cutoffAndInput = boxPar(cutoff, boxWire()); Box filteredInput = boxSeq(cutoffAndInput, filter); bool res = getBoxType(filteredInput, &inputs, &outputs); std::cout << \"getBoxType inputs: \" << inputs << \" outputs: \" << outputs << std::endl; dsp_factory_base* factory = createCPPDSPFactoryFromBoxes(\"FaustDSP\", filteredInput, argc, (const char**)argv, error_msg); if (factory) { factory->write(&cout); delete(factory); } else { cerr << error_msg; } } destroyLibContext(); } Note that the getBoxType function can be used to retrieve a given box number of inputs and outputs.","title":"Using the DSPToBoxes function"},{"location":"tutorials/box-api/#defining-more-complex-expressions-phasor-and-oscillator","text":"More complex signal expressions can be defined, creating boxes using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Box decimalpart() { return boxSub(boxWire(), boxIntCast(boxWire())); } static Box phasor(Box f) { return boxSeq(boxDiv(f, SR()), boxRec(boxSplit(boxAdd(), decimalpart()), boxWire())); } And the main function combining them: static void test17() { COMPILER ( Box box = phasor(boxReal(440)); compile(\"test17\", box); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Box osc(Box f) { return boxSin(boxMul(boxMul(boxReal(2.0), boxReal(3.141592653)), phasor(f))); } static void test18() { COMPILER ( Box box = boxPar(osc(boxReal(440)), osc(boxReal(440))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } }","title":"Defining more complex expressions: phasor and oscillator"},{"location":"tutorials/box-api/#using-the-generated-code","text":"Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromBoxes (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromBoxes (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory);","title":"Using the generated code"},{"location":"tutorials/box-api/#connecting-the-audio-layer","text":"Audio drivers allow you to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop();","title":"Connecting the audio layer"},{"location":"tutorials/box-api/#connecting-the-controller-layer","text":"Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual.","title":"Connecting the controller layer"},{"location":"tutorials/box-api/#example-with-audio-rendering-and-gui-control","text":"Here is a more complete example, first with the DSP code: Then with the C++ code using the box API: // Using the Interpreter backend. static void test22(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Example with audio rendering and GUI control"},{"location":"tutorials/box-api/#generating-the-signals-as-an-intermediate-step","text":"The boxesToSignals function allows you to compile a box in a list of signals, to be used with the signal API . The following example shows how the two steps (box => signals then signals => DSP factory) can be chained, rewriting the previous code as: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { Box sl1 = boxHSlider(\"v:Oscillator/Freq1\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box sl2 = boxHSlider(\"v:Oscillator/Freq2\", boxReal(300), boxReal(100), boxReal(2000), boxReal(0.01)); Box box = boxPar(osc(sl1), osc(sl2)); // Compile the 'box' to 'signals' tvec signals = boxesToSignals(box, error_msg); // Then compile the 'signals' to a DSP factory factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Generating the signals as an intermediate step"},{"location":"tutorials/box-api/#polyphonic-midi-controllable-simple-synthesizer","text":"Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the box API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Box freq = boxNumEntry(\"freq\", boxReal(100), boxReal(100), boxReal(3000), boxReal(0.01)); Box gate = boxButton(\"gate\"); Box gain = boxNumEntry(\"gain\", boxReal(0.5), boxReal(0), boxReal(1), boxReal(0.01)); Box organ = boxMul(gate, boxAdd(boxMul(osc(freq), gain), boxMul(osc(boxMul(freq, boxInt(2))), gain))); // Stereo Box box = boxPar(organ, organ); factory = createInterpreterDSPFactoryFromBoxes(\"FaustDSP\", box, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Polyphonic MIDI controllable simple synthesizer"},{"location":"tutorials/box-api/#examples-with-the-c-api","text":"The box API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create box expressions, where the LLVM backend is used with the C version createCDSPFactoryFromBoxes function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Box decimalpart() { return CboxSubAux(CboxWire(), CboxIntCastAux(CboxWire())); } static Box phasor(Box f) { return CboxSeq(CboxDivAux(f, SR()), CboxRec(CboxSplit(CboxAdd(), decimalpart()), CboxWire())); } static void test1() { createLibContext(); { Box box = phasor(CboxReal(2000)); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test1\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Box freq = CboxVSlider(\"h:Oscillator/freq\", CboxReal(440), CboxReal(50), CboxReal(1000), CboxReal(0.1)); Box gain = CboxVSlider(\"h:Oscillator/gain\", CboxReal(0), CboxReal(0), CboxReal(1), CboxReal(0.011)); Box box = CboxMulAux(freq, CboxMulAux(gain, CboxWire())); char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromBoxes(\"test3\", box, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the box-tester-c tool, to be compiled with make box-tester-c in the tools/benchmark folder.","title":"Examples with the C API"},{"location":"tutorials/cmajor/","text":"Using Faust in Cmajor In this tutorial, we present how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. Compiling Faust DSP to cmajor code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for Cmajor users who want to discover Faust. Installing the required packages Download the cmaj package and install to have it in your PATH. Using command line tools Generating Cmajor code Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The Cmajor code can be generated using: faust -lang cmajor osc.dsp -o osc.cmajor This will generate a mydsp processor included in a namespace faust {...} with a set of methods to manipulate it. This API basically mimics the one defined for the C++ backend . Looking at the generated code The generated code contains input event definition for the three sliders defined in the DSP source code: input event float32 eventfHslider1 [[ name: \"freq1\", group: \"/v:Oscillator/freq1\", min: 20.0f, max: 3000.0f, init: 1000.0f, step: 1.0f, meta_unit0: \"Hz\" ]]; input event float32 eventfHslider2 [[ name: \"freq2\", group: \"/v:Oscillator/freq2\", min: 20.0f, max: 3000.0f, init: 200.0f, step: 1.0f, meta_unit1: \"Hz\" ]]; input event float32 eventfHslider0 [[ name: \"volume\", group: \"/v:Oscillator/volume\", min: 0.0f, max: 1.0f, init: 0.5f, step: 0.01f ]]; The needed main function executes the DSP sample generation code: void main() { // DSP loop running forever... loop { if (fUpdated) { fUpdated = false; control(); } // Computes one sample fRec1[0] = fControl[1] + fRec1[1] - floor (fControl[1] + fRec1[1]); output0 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec1[0]))); fRec2[0] = fControl[2] + fRec2[1] - floor (fControl[2] + fRec2[1]); output1 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec2[0]))); fRec1[1] = fRec1[0]; fRec2[1] = fRec2[0]; // Moves all streams forward by one 'tick' advance(); } } Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is inlined on the Cmajor loop block. We cannot directly play the generated osc.cmajor file since the cmaj program expects a osc.cmajorpatch to execute. A simple solution is to use the following command: cmaj create --name=osc osc to create an osc folder with default osc.cmajor and osc.cmajorpatch files. Then using the command: faust -lang cmajor osc.dsp -o osc/osc.cmajor allows to simply replace the default osc.cmajor with our own Faust generated version. The patchfile can now be compiled and executed using the cmaj program: cmaj play osc/osc.cmajorpatch The three declared sliders are automatically created and can be used to change the two channels frequencies and their volume. The Cmajor processor code can directly be used in a more complex Cmajor program, possibly connected to other Faust generated or Cmajor hand-written processors. Note that the generated processor name can simply be changed using the Faust compiler -cn <name> option, so that several Faust generated processors can be distinguished by their names: faust -lang cmajor -cn osc osc.dsp -o osc/osc.cmajor Using the faust2cmajor tool The faust2cmajor tool allows to automate calling the Faust compiler with the right options and interacting with the cmaj program: faust2cmajor -h Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. So the following command: faust2cmajor -play osc.dsp will directly compile the osc.dsp file, generate the osc.cmajor and osc.cmajorpatch files: { \"CmajorVersion\": 1, \"ID\": \"grame.cmajor.osc\", \"version\": \"1.0\", \"name\": \"osc\", \"description\": \"Cmajor example\", \"category\": \"synth\", \"manufacturer\": \"GRAME\", \"website\": \"https://faust.grame.fr\", \"isInstrument\": false, \"source\": \"osc.cmajor\" } And activate the cmaj program to run the processor. The following polyphonic ready instrument DSP can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 organ.dsp Note that the generated GUI is empty, since the generated processor cannot automatically reflects its controls in the main graph. The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 -effect auto clarinet.dsp Here again the generated GUI is empty. Generating the Cmajor output using faustremote A possibility is to use the faustremote script to convert a local DSP with the following commands: faustremote cmajor cmajor foo.dsp unzip binary.zip Using the Faust Web IDE Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Cmajor code. Generating the Cmajor output The output as a Cmajor program can directly be generated using the Platform = cmajor and Architecture = cmajor export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The program can be executed using cmaj play foo/foo.cmajorpatch command or possibly converted as a JUCE plugin . Exporting the code Generating the Cmajor output in polyphonic mode DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = cmajor and Architecture = cmajor-poly export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin . Generating the Cmajor output in polyphonic mode with a global effect DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = cmajor and Architecture = cmajor-poly-effect export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin . Generating the Cmajor output from a Faust DSP program found in the web Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a Cmajor program as already showed basic Examples have been compiled to Cmajor here examples of the faustplayground platform can be found here and possibly converted. They have been compiled to Cmajor here . Experimental Faust in Cmajor integration With the release of the Cmajor source code , an experimental Faust in Cmajor integration can be tested starting with Cmajor 1.0.2616 release . Known limitations The Cmajor language generates some usefull API when the patch is exported in C++ or JavaScript. For example the getInputEndpoints/getOutputEndpoints and getEndpointHandle functions allow an external piece of code to enumerate and access all endpoints, to possibly control the program or build a GUI. But unfortunately those functions are not part of the language itself . Thus there is no way we know of: to write a generic Cmajor program that would automatically connect some endpoints (assuming they would use some kind of MIDI describing metadata) to MIDI messages to write a generic Cmajor program that would automatically wraps a voice generated from a Faust DSP program in a polyphonic and MIDI aware program, and expose the voice set of parameters at the main graph level, to be controlled globally for all voices We think the language would gain expressive power by having some kind of reflexivity .","title":"Using Faust in Cmajor"},{"location":"tutorials/cmajor/#using-faust-in-cmajor","text":"In this tutorial, we present how Faust can be used with Cmajor , a C like procedural high-performance language especially designed for audio processing, and with dynamic JIT based compilation. Compiling Faust DSP to cmajor code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net.","title":"Using Faust in Cmajor"},{"location":"tutorials/cmajor/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for Cmajor users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/cmajor/#installing-the-required-packages","text":"Download the cmaj package and install to have it in your PATH.","title":"Installing the required packages"},{"location":"tutorials/cmajor/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/cmajor/#generating-cmajor-code","text":"Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The Cmajor code can be generated using: faust -lang cmajor osc.dsp -o osc.cmajor This will generate a mydsp processor included in a namespace faust {...} with a set of methods to manipulate it. This API basically mimics the one defined for the C++ backend .","title":"Generating Cmajor code"},{"location":"tutorials/cmajor/#looking-at-the-generated-code","text":"The generated code contains input event definition for the three sliders defined in the DSP source code: input event float32 eventfHslider1 [[ name: \"freq1\", group: \"/v:Oscillator/freq1\", min: 20.0f, max: 3000.0f, init: 1000.0f, step: 1.0f, meta_unit0: \"Hz\" ]]; input event float32 eventfHslider2 [[ name: \"freq2\", group: \"/v:Oscillator/freq2\", min: 20.0f, max: 3000.0f, init: 200.0f, step: 1.0f, meta_unit1: \"Hz\" ]]; input event float32 eventfHslider0 [[ name: \"volume\", group: \"/v:Oscillator/volume\", min: 0.0f, max: 1.0f, init: 0.5f, step: 0.01f ]]; The needed main function executes the DSP sample generation code: void main() { // DSP loop running forever... loop { if (fUpdated) { fUpdated = false; control(); } // Computes one sample fRec1[0] = fControl[1] + fRec1[1] - floor (fControl[1] + fRec1[1]); output0 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec1[0]))); fRec2[0] = fControl[2] + fRec2[1] - floor (fControl[2] + fRec2[1]); output1 <- float32 (fControl[0] * ftbl0mydspSIG0.at (int32 (65536.0f * fRec2[0]))); fRec1[1] = fRec1[0]; fRec2[1] = fRec2[0]; // Moves all streams forward by one 'tick' advance(); } } Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is inlined on the Cmajor loop block. We cannot directly play the generated osc.cmajor file since the cmaj program expects a osc.cmajorpatch to execute. A simple solution is to use the following command: cmaj create --name=osc osc to create an osc folder with default osc.cmajor and osc.cmajorpatch files. Then using the command: faust -lang cmajor osc.dsp -o osc/osc.cmajor allows to simply replace the default osc.cmajor with our own Faust generated version. The patchfile can now be compiled and executed using the cmaj program: cmaj play osc/osc.cmajorpatch The three declared sliders are automatically created and can be used to change the two channels frequencies and their volume. The Cmajor processor code can directly be used in a more complex Cmajor program, possibly connected to other Faust generated or Cmajor hand-written processors. Note that the generated processor name can simply be changed using the Faust compiler -cn <name> option, so that several Faust generated processors can be distinguished by their names: faust -lang cmajor -cn osc osc.dsp -o osc/osc.cmajor","title":"Looking at the generated code"},{"location":"tutorials/cmajor/#using-the-faust2cmajor-tool","text":"The faust2cmajor tool allows to automate calling the Faust compiler with the right options and interacting with the cmaj program: faust2cmajor -h Usage: faust2cmajor [options] [Faust options] <file.dsp> Compiles Faust programs to Cmajor Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -juce : to create a JUCE project -dsp : to create a 'dsp' compatible subclass -play : to start the 'cmaj' runtime with the generated Cmajor file Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. So the following command: faust2cmajor -play osc.dsp will directly compile the osc.dsp file, generate the osc.cmajor and osc.cmajorpatch files: { \"CmajorVersion\": 1, \"ID\": \"grame.cmajor.osc\", \"version\": \"1.0\", \"name\": \"osc\", \"description\": \"Cmajor example\", \"category\": \"synth\", \"manufacturer\": \"GRAME\", \"website\": \"https://faust.grame.fr\", \"isInstrument\": false, \"source\": \"osc.cmajor\" } And activate the cmaj program to run the processor. The following polyphonic ready instrument DSP can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 organ.dsp Note that the generated GUI is empty, since the generated processor cannot automatically reflects its controls in the main graph. The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a MIDI ready cmajor instrument: The following command then opens the cmaj program and MDI events can be sent to control the instrument: faust2cmajor -play -midi -nvoices 16 -effect auto clarinet.dsp Here again the generated GUI is empty.","title":"Using the faust2cmajor tool"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-using-faustremote","text":"A possibility is to use the faustremote script to convert a local DSP with the following commands: faustremote cmajor cmajor foo.dsp unzip binary.zip","title":"Generating the Cmajor output using faustremote"},{"location":"tutorials/cmajor/#using-the-faust-web-ide","text":"Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Cmajor code.","title":"Using the Faust Web IDE"},{"location":"tutorials/cmajor/#generating-the-cmajor-output","text":"The output as a Cmajor program can directly be generated using the Platform = cmajor and Architecture = cmajor export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The program can be executed using cmaj play foo/foo.cmajorpatch command or possibly converted as a JUCE plugin . Exporting the code","title":"Generating the Cmajor output"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-in-polyphonic-mode","text":"DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = cmajor and Architecture = cmajor-poly export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin .","title":"Generating the Cmajor output in polyphonic mode"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-in-polyphonic-mode-with-a-global-effect","text":"DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = cmajor and Architecture = cmajor-poly-effect export options. The resulting foo folder is self-contained, containing the foo.cmajor and foo.cmajorpatch files. The instrument can be executed using cmaj play foo/foo.cmajorpatch command and played with a MIDI device or possibly converted as a JUCE plugin .","title":"Generating the Cmajor output in polyphonic mode with a global effect"},{"location":"tutorials/cmajor/#generating-the-cmajor-output-from-a-faust-dsp-program-found-in-the-web","text":"Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a Cmajor program as already showed basic Examples have been compiled to Cmajor here examples of the faustplayground platform can be found here and possibly converted. They have been compiled to Cmajor here .","title":"Generating the Cmajor output from a Faust DSP program found in the web"},{"location":"tutorials/cmajor/#experimental-faust-in-cmajor-integration","text":"With the release of the Cmajor source code , an experimental Faust in Cmajor integration can be tested starting with Cmajor 1.0.2616 release .","title":"Experimental Faust in Cmajor integration"},{"location":"tutorials/cmajor/#known-limitations","text":"The Cmajor language generates some usefull API when the patch is exported in C++ or JavaScript. For example the getInputEndpoints/getOutputEndpoints and getEndpointHandle functions allow an external piece of code to enumerate and access all endpoints, to possibly control the program or build a GUI. But unfortunately those functions are not part of the language itself . Thus there is no way we know of: to write a generic Cmajor program that would automatically connect some endpoints (assuming they would use some kind of MIDI describing metadata) to MIDI messages to write a generic Cmajor program that would automatically wraps a voice generated from a Faust DSP program in a polyphonic and MIDI aware program, and expose the voice set of parameters at the main graph level, to be controlled globally for all voices We think the language would gain expressive power by having some kind of reflexivity .","title":"Known limitations"},{"location":"tutorials/debugging/","text":"Advanced debugging with interp-tracer Some general informations are given here on how to debug the Faust DSP code. This tutorial aims to better explain how the interp-tracer tool can be used to debug code at runtime. The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL, FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW, CAST_INT_OVERFLOW, NEGATIVE_BITSHIFT and DIV_BY_ZERO operations, or LOAD/STORE errors. Debugging out-of-domain computations Using the -trace 4 option allows to exit at first error and write FBC (Faust Byte Code) trace as a DumpCode-foo.txt file, and the program memory layout as DumpMem-fooXXX.txt file. The following debug.dsp DSP program: process = hslider(\"foo\", 0.5, -1, 1, 0.01) : log; will produce out-of-domain values as soon at the slider value is 0 or below, with the following trace written on the console: -------- Interpreter 'NaN' trace start -------- opcode 202 kLogf int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 2 kLoadReal int 0 real 0 offset1 1 offset2 0 name fHslider0 Stack [Int: 0] [REAL: -4,605170] opcode 279 kCondBranch int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: -4,605170] opcode 46 kLTInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 1 offset2 0 name count Stack [Int: 16] [REAL: -4,605170] opcode 7 kStoreInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 33 kAddInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] -------- Interpreter 'NaN' trace end -------- The trace contains the stack of Faust Byte Code (FBC) instructions executed by the interpreter, with the latest instructions executed before the actual error, here the kLogf operation. The names of the fields in the DSP structure are also visible, here fHslider0 . Looking at the generated C++ can help understand the control flow: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = std::log(float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } The generated DumpMem-debug22419.txt file contains the content of the interpreter Virtual Machine REAL (float/double depending on the -single/-double compilation option) memory array, and INT (integer) memory array. DSP name: debug ================================= REAL memory: 3 0 defaultsound 0 1 fHslider0 -0.01 2 fSlow0 -4.60517 ================================= INT memory: 3 0 44100 1 count 16 2 i0 16 Debugging rdtable and rwtable primitives The rdtable primitive uses a read index, and the rwtable primitive uses a read index and a write index. The table size is known at compile time, and read/write indexes must stay inside the table to avoid memory access crashes at runtime. The -ct option can be used to check table index range and generate safe table access code. For the following DSP table.dsp program: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; integrator = +(1) ~ _; rdx = integrator%(SIZE*2); wdx = integrator%(SIZE*2); }; the generated code with the -ct 0 option will produce: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 32; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with incorrect table access code in the compute method, where the iTemp0 read and write indexes may exceed the table size of 16. Executing interp-tracer -trace 4 -ct 0 table.dsp generates the following trace on the console, showing memory read/write access errors: -------- Interpreter crash trace start -------- assertStoreRealHeap array: fIntHeapSize 17 index 16 size 16 name ftbl0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 15] [REAL: 0,000000] opcode 24 kLoadInput int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 6 offset2 0 name i0 Stack [Int: 16] [REAL: 0,000000] opcode 7 kStoreInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 16] [REAL: 0,000000] opcode 41 kRemInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 11 kLoadIndexedInt int 0 real 0 offset1 0 offset2 2 name iRec0 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 32 real 0 offset1 -1 offset2 -1 -------- Interpreter crash trace end -------- With the -ct 1 option, the generated code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0] % 32, 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } where the iTemp0 read and write index is now constrained to stay in the [0..15] range and the code will not crash at runtime anymore. The DSP program was indeed incorrect with the indexes wrapping at 32 samples boundaries. It can be rewritten as: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) : %(SIZE)) ~ _; rdx = index; wdx = index; }; and the generated C++ code with the -ct 1 option (and using the -wall option to print warning messages on the console) is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = (iRec0[1] + 1) % 16; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0], 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with the warning messages: WARNING : RDTbl read index [0:inf] is outside of table size (16) in read(write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0) WARNING : WRTbl write index [0:inf] is outside of table size (16) in write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]) The range test code checks if the read or write index interval is inside the [0..size-1] range, and only generates constraining code when needed. But since the signal interval calculation is currently imperfect, unneeded range constraining code might be generated ! This is actually the case in the generated code, and can be tested using interp-tracer -trace 4 -ct 0 table.dsp , which does not generate constraining code, but does not show any problem. If one is absolutely sure of the stay in range property, then adding constraining code can be deactivated using -ct 0 and the generated code will be faster. The hope is to improve the signal interval calculation model, so that the index constraining code will not be needed anymore. Note that the DSP program can be rewritten this way: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) ~ _) : %(SIZE); rdx = index; wdx = index; }; in this case the signal interval is correct and the generated C++ code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 16; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } without any added range constraining code. Note that -ct 1 option is the default, so safe code is always generated. Debugging the select2 primitive The select2 primitive has a strict semantic, but for code optimization strategies, the generated code is not fully strict . For the following DSP program: process = select2(button(\"gate\"), branch1, branch2) with { branch1 = (hslider(\"foo\", 0.5, 0, 1, 0.01):log); branch2 = (hslider(\"bar\", 0.5, -1, 1, 0.01):sqrt); }; the generated C++ is using the ((cond) ? then : else) form which actually only computes one of the then or else branch depending of the button(\"gate\") condition: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = ((int(float(fButton0))) ? std::sqrt(float(fHslider1)) : std::log(float(fHslider0))); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } Thus executing it with interp-tracer -trace 4 debug.dsp allows it to detect one falling branch when the condition is in a given state. To force computation of both branches, the -sts (--strict-select) option can be used. The generated C++ is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fThen0 = std::log(float(fHslider0)); float fElse0 = std::sqrt(float(fHslider1)); float fSlow0 = ((int(float(fButton0))) ? fElse0 : fThen0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } where intermediate fThen0 and fElse0 created variables force the actual computation of both branches. Then executing interp-tracer -trace 4 -sts debug.dsp will reveal the out-of-bounds calculation on both branches, for both states of the condition. Debugging using test signals Effects DSP programs usually need to be fed with standardized test input signals to possibly trigger abnormal behavior. The interp-tracer tool has an -input option to connect an impulse program (defined with the process = 1-1'; ), then a noise program (defined with the import(\"stdfaust.lib\"); process = no.noise; ) to all inputs of the tested DSP. So something like the interp-tracer -trace 4 -input debug.dsp command has to be used. More specialized test input signals can be used by directly modifying the debug.dsp code, then running the DSP code normally (that is not using the -input option anymore). So writing something like: process = test_signal <: effect; to connect a given mono test_signal to all inputs of the effect program. Correcting the program The interp-tracer tool helps finding programming errors. But obviously, the detected errors must then be corrected: by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items by checking mathematical function domains by checking indexes when using by rdtable\\rwtable primitives ...","title":"Advanced debugging with interp-tracer"},{"location":"tutorials/debugging/#advanced-debugging-with-interp-tracer","text":"Some general informations are given here on how to debug the Faust DSP code. This tutorial aims to better explain how the interp-tracer tool can be used to debug code at runtime. The interp-tracer tool runs and instruments the compiled program using the Interpreter backend. Various statistics on the code are collected and displayed while running and/or when closing the application, typically FP_SUBNORMAL, FP_INFINITE and FP_NAN values, or INTEGER_OVERFLOW, CAST_INT_OVERFLOW, NEGATIVE_BITSHIFT and DIV_BY_ZERO operations, or LOAD/STORE errors.","title":"Advanced debugging with interp-tracer"},{"location":"tutorials/debugging/#debugging-out-of-domain-computations","text":"Using the -trace 4 option allows to exit at first error and write FBC (Faust Byte Code) trace as a DumpCode-foo.txt file, and the program memory layout as DumpMem-fooXXX.txt file. The following debug.dsp DSP program: process = hslider(\"foo\", 0.5, -1, 1, 0.01) : log; will produce out-of-domain values as soon at the slider value is 0 or below, with the following trace written on the console: -------- Interpreter 'NaN' trace start -------- opcode 202 kLogf int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 2 kLoadReal int 0 real 0 offset1 1 offset2 0 name fHslider0 Stack [Int: 0] [REAL: -4,605170] opcode 279 kCondBranch int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: -4,605170] opcode 46 kLTInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 3 kLoadInt int 0 real 0 offset1 1 offset2 0 name count Stack [Int: 16] [REAL: -4,605170] opcode 7 kStoreInt int 0 real 0 offset1 2 offset2 0 name i0 Stack [Int: 1] [REAL: -4,605170] opcode 33 kAddInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: -4,605170] -------- Interpreter 'NaN' trace end -------- The trace contains the stack of Faust Byte Code (FBC) instructions executed by the interpreter, with the latest instructions executed before the actual error, here the kLogf operation. The names of the fields in the DSP structure are also visible, here fHslider0 . Looking at the generated C++ can help understand the control flow: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = std::log(float(fHslider0)); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } The generated DumpMem-debug22419.txt file contains the content of the interpreter Virtual Machine REAL (float/double depending on the -single/-double compilation option) memory array, and INT (integer) memory array. DSP name: debug ================================= REAL memory: 3 0 defaultsound 0 1 fHslider0 -0.01 2 fSlow0 -4.60517 ================================= INT memory: 3 0 44100 1 count 16 2 i0 16","title":"Debugging out-of-domain computations"},{"location":"tutorials/debugging/#debugging-rdtable-and-rwtable-primitives","text":"The rdtable primitive uses a read index, and the rwtable primitive uses a read index and a write index. The table size is known at compile time, and read/write indexes must stay inside the table to avoid memory access crashes at runtime. The -ct option can be used to check table index range and generate safe table access code. For the following DSP table.dsp program: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; integrator = +(1) ~ _; rdx = integrator%(SIZE*2); wdx = integrator%(SIZE*2); }; the generated code with the -ct 0 option will produce: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 32; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with incorrect table access code in the compute method, where the iTemp0 read and write indexes may exceed the table size of 16. Executing interp-tracer -trace 4 -ct 0 table.dsp generates the following trace on the console, showing memory read/write access errors: -------- Interpreter crash trace start -------- assertStoreRealHeap array: fIntHeapSize 17 index 16 size 16 name ftbl0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 15] [REAL: 0,000000] opcode 24 kLoadInput int 0 real 0 offset1 0 offset2 0 Stack [Int: 16] [REAL: 0,000000] opcode 3 kLoadInt int 0 real 0 offset1 6 offset2 0 name i0 Stack [Int: 16] [REAL: 0,000000] opcode 7 kStoreInt int 0 real 0 offset1 7 offset2 0 name iTemp0 Stack [Int: 16] [REAL: 0,000000] opcode 41 kRemInt int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 11 kLoadIndexedInt int 0 real 0 offset1 0 offset2 2 name iRec0 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 0 real 0 offset1 -1 offset2 -1 Stack [Int: 0] [REAL: 0,000000] opcode 1 kInt32Value int 32 real 0 offset1 -1 offset2 -1 -------- Interpreter crash trace end -------- With the -ct 1 option, the generated code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0] % 32, 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } where the iTemp0 read and write index is now constrained to stay in the [0..15] range and the code will not crash at runtime anymore. The DSP program was indeed incorrect with the indexes wrapping at 32 samples boundaries. It can be rewritten as: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) : %(SIZE)) ~ _; rdx = index; wdx = index; }; and the generated C++ code with the -ct 1 option (and using the -wall option to print warning messages on the console) is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = (iRec0[1] + 1) % 16; int iTemp0 = std::max<int>(0, std::min<int>(iRec0[0], 15)); ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } with the warning messages: WARNING : RDTbl read index [0:inf] is outside of table size (16) in read(write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0) WARNING : WRTbl write index [0:inf] is outside of table size (16) in write(TABLE(16,0.0f),proj0(letrec(W0 = ((proj0(W0)'+1)%16)))@0,IN[0]) The range test code checks if the read or write index interval is inside the [0..size-1] range, and only generates constraining code when needed. But since the signal interval calculation is currently imperfect, unneeded range constraining code might be generated ! This is actually the case in the generated code, and can be tested using interp-tracer -trace 4 -ct 0 table.dsp , which does not generate constraining code, but does not show any problem. If one is absolutely sure of the stay in range property, then adding constraining code can be deactivated using -ct 0 and the generated code will be faster. The hope is to improve the signal interval calculation model, so that the index constraining code will not be needed anymore. Note that the DSP program can be rewritten this way: process = rwtable(SIZE, 0.0, rdx, _, wdx) with { SIZE = 16; index = (+(1) ~ _) : %(SIZE); rdx = index; wdx = index; }; in this case the signal interval is correct and the generated C++ code is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { iRec0[0] = iRec0[1] + 1; int iTemp0 = iRec0[0] % 16; ftbl0[iTemp0] = float(input0[i0]); output0[i0] = FAUSTFLOAT(ftbl0[iTemp0]); iRec0[1] = iRec0[0]; } } without any added range constraining code. Note that -ct 1 option is the default, so safe code is always generated.","title":"Debugging rdtable and rwtable primitives"},{"location":"tutorials/debugging/#debugging-the-select2-primitive","text":"The select2 primitive has a strict semantic, but for code optimization strategies, the generated code is not fully strict . For the following DSP program: process = select2(button(\"gate\"), branch1, branch2) with { branch1 = (hslider(\"foo\", 0.5, 0, 1, 0.01):log); branch2 = (hslider(\"bar\", 0.5, -1, 1, 0.01):sqrt); }; the generated C++ is using the ((cond) ? then : else) form which actually only computes one of the then or else branch depending of the button(\"gate\") condition: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = ((int(float(fButton0))) ? std::sqrt(float(fHslider1)) : std::log(float(fHslider0))); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } Thus executing it with interp-tracer -trace 4 debug.dsp allows it to detect one falling branch when the condition is in a given state. To force computation of both branches, the -sts (--strict-select) option can be used. The generated C++ is now: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* output0 = outputs[0]; float fThen0 = std::log(float(fHslider0)); float fElse0 = std::sqrt(float(fHslider1)); float fSlow0 = ((int(float(fButton0))) ? fElse0 : fThen0); for (int i0 = 0; i0 < count; i0 = i0 + 1) { output0[i0] = FAUSTFLOAT(fSlow0); } } where intermediate fThen0 and fElse0 created variables force the actual computation of both branches. Then executing interp-tracer -trace 4 -sts debug.dsp will reveal the out-of-bounds calculation on both branches, for both states of the condition.","title":"Debugging the select2 primitive"},{"location":"tutorials/debugging/#debugging-using-test-signals","text":"Effects DSP programs usually need to be fed with standardized test input signals to possibly trigger abnormal behavior. The interp-tracer tool has an -input option to connect an impulse program (defined with the process = 1-1'; ), then a noise program (defined with the import(\"stdfaust.lib\"); process = no.noise; ) to all inputs of the tested DSP. So something like the interp-tracer -trace 4 -input debug.dsp command has to be used. More specialized test input signals can be used by directly modifying the debug.dsp code, then running the DSP code normally (that is not using the -input option anymore). So writing something like: process = test_signal <: effect; to connect a given mono test_signal to all inputs of the effect program.","title":"Debugging using test signals"},{"location":"tutorials/debugging/#correcting-the-program","text":"The interp-tracer tool helps finding programming errors. But obviously, the detected errors must then be corrected: by carefully checking signal range, like verifying the min/max values in vslider/hslider/nentry user-interface items by checking mathematical function domains by checking indexes when using by rdtable\\rwtable primitives ...","title":"Correcting the program"},{"location":"tutorials/esp32/","text":"DSP on the ESP32 With Faust The ESP32 is a cheap microcontroller providing built-in Bluetooth and Wifi support, many GPIOs and analog inputs, etc. It's extremely low price (a few dollars) makes it very attractive and it is being used in an increasing number of boards. A wide range of \"unknown/secret\" development boards targeting audio applications are based on the ESP32 and can be found on Alibaba/AliExpress. While most of them target the development of \"intelligent speakers\" (e.g., Alexa, etc.), they host all the components to carry out real-time DSP applications and can therefore be used to develop digital musical instruments, effect processors, synthesizer hardware, etc. The TTGO T-Audio or the ESP32 Audio Dev Kit are good examples of such boards. The TTGO T-Audio (left) and the ESP32 Audio Dev Kit (right) They both host relatively good quality audio codecs with stereo in and out and built-in amplifier, battery circuit, external RAM, and various motion sensors (only for the TTGO T-Audio), all that for less than $15!! Since these boards don't run any OS, very low audio latency can be achieved (i.e., buffer size of 8 samples, etc.). Compared to the Teensy 3.6/4.0 and their respective audio shields , these boards are MUCH cheaper, they're more powerful than the Teensy 3.6 (dual core with a much higher clock) and most importantly, they have enough RAM to run DSP algorithms with a large memory footprint such as reverbs, echos, etc. (which is relatively limited on the Teensy 3.6 and 4.0). Finally, the ESP32 ecosystem is entirely open source (including its loader)! In many ways, they can compete with much more expensive dedicated audio platforms such as the BELA (<$150), etc. The Faust distribution now comes with faust2esp32 , a tool to program ESP32-based boards with Faust. faust2esp32 is still under development and its current version allows to generate DSP engines that can be used in ESP32 projects to carry out sound synthesis and processing tasks. While the mechanism ( i2s ) used to communicate between the ESP32 and the audio codec is the same on all boards, the brand and the type of audio codecs used on ESP32-based boards varies quite a lot. faust2esp32 supports a few audio codecs which can be listed by running faust2esp32 -h or by looking at the faust2esp32 doc . DSP engines produced by faust2esp32 are compatible with both the C++ and the Arduino development environment of the ESP32. The two following sections walk you through starting a new ESP32 project and adding Faust audio support to it using both methods. Using the ESP32 C++ Development Environment The final source code of this tutorial can be found here . Programming the ESP32 with its native C++ environment offers many advantages. In particular, it allows for a very fine tuning of the board configuration and compilation options. For example, if your DSP algorithm will have a large memory footprint, you might have no other option since external RAM will have to be activated (see Using the External RAM of the ESP32 section). In this short tutorial, we walk you through the steps of making a C++ project from scratch with audio DSP support for the TTGO T-Audio board (the procedure should be more or less the same for similar types of boards). Starting a New ESP32 Project Information on how to configure your ESP32 C++ development environment can be found in this tutorial (read it until the end of step 4). Once your environment is up and running, copy the ESP32 hello_world example project somewhere on your system. Then run make , which should automatically prompt the ESP32 configuration panel. Make some modifications if needed (i.e., serial flasher config as specified in the ESP32 get started tutorial, etc.). Once you exit the menu, compilation should start and complete without any issue. Since the DSP engine that we're about to generate with faust2esp32 uses C++, the main file of the current project should be modified to use C++ as well. To do so, just rename main/hello_world_main.c to main/main.cpp (or any other name you'd like, of course, as long as you use the cpp extension). Then, make sure the basic structure of your program looks like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" extern \"C\" { void app_main(void); } void app_main(void) { while(1) { vTaskDelay(1000 / portTICK_PERIOD_MS); } } Here, the infinite while loop gets ran in the main thread/task and is updated every second. Update the CMakeLists.txt file at the root of the project to change the project name (e.g., project(FaustTutorial) ). Similarly, update the CMakeLists.txt file in main to set the right file for the component source (e.g., set(COMPONENT_SRCS \"main.cpp\") ). Run make again to be sure that your program still compiles and that you didn't break anything. Making a Simple DSP Engine Let's now write a simple Faust program (the usual one haha) implementing a band limited sawtooth wave with smoothed control: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.sawtooth(freq)*gain; Save it in a file called FaustSawtooth.dsp (this will define the name of the corresponding DSP engine) and compile it using faust2esp32 by running the following command: faust2esp32 -lib FaustSawtooth.dsp -lib asks to generate a C++ DSP engine here as opposed to a complete firmware. Note: the current version of faust2esp32 only allows to generate DSP engines (not complete ESP32 programs) so the -lib option is not really necessary here. Alternatively, this could be done by selecting the ESP32 target in the Faust compilation service in the online IDE . In both cases, a .zip package containing a set of C++ files will be returned. In the current example, FaustSawtooth.[cpp/h] implement the Faust DSP object produced from FaustSawtooth.dsp and WM8978.[cpp/h] is the object corresponding to the audio codec of your board. Note: in the current version of faust2esp32 , the only supported audio codecs are the WM8978 ( -WM8978 option) which is that of the TTGO T-Audio board and the AC101 ( -AC101 option). All these files should be placed in the main folder of the project. After that, they should be included to main.cpp as follows: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } Configuring the Audio Codec Next, the WM8978 object (which corresponds to the audio codec, i.e., audio interface on the board) should be instantiated and configured in app_main : WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); Once again, the current version of faust2esp32 only provides support for the Wolfson WM8978 present on the TTGO T-Audio and the AC101, but we're working at adding new codecs from other manufacturers, etc. The procedure should be similar with other codecs. The present configuration activates the mic input, deactivates the amp for the speaker, sets the headphone gain to 40, etc. Please refer to the WM8978 object documentation for more information. Note that each of these commands will be called \"in real-time\" at start-up so the configuration of the audio codec is progressively done and should be carried out before sending any audio buffer to it. Instantiating the Faust DSP Engine After configuring the audio codec, the Faust DSP object produced in the previous step and included in main.cpp should be instantiated in app_main as well: int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); The constructor of FaustSawtooth takes two arguments: the sampling rate (48kHz here) and the block size (8 here). Calling the constructor will configure the object, allocate memory for it, etc. but in order to start computation, the start() method needs to be called. Since ESP32 firmwares are based on freertos , audio is computed in its own high priority task and calling start() will launch this task. Note that this task can be removed and audio computation stopped at any time simply by calling stop() . Finally, the setParamValue method of the FaustSawtooth object can be called at any point to change the value of one of the parameter of the Faust object (here, two parameters were declared: freq and gain ). For example, the frequency of the generated sawtooth could be randomly changed at every sample by calling the following line in the while loop at the bottom of app_main : faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); At this point, main.cpp should look like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } void app_main(void) { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); while(1) { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); vTaskDelay(1000 / portTICK_PERIOD_MS); } } Try to recompile the firmware and upload it to your board. If headphones are connected to it, you should hear a sawtooth wave whose frequency changes randomly every second. Using the External RAM of the ESP32 Some DSP algorithms might require a large amount of memory allocation (e.g., wave tables, delays, etc.). In that case, the object generated by Faust might not fit in the built-in RAM of the ESP32 and it might be necessary to use the external RAM module (SRAM) of the board. In order to test this, we first need to write a Faust program that will need a large amount of memory. Replacing the sawtooth wave of the previous example by a sine wave should do it since the default sine wave oscillator of Faust ( os.osc ) is based on a wave table of size 65536: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.osc(freq)*gain; You can then follow the same steps as the ones described in the Making a Simple DSP Engine section to integrate this Faust program to your C++ ESP32 project. If you try to compile your firmware again (i.e., make ), you should get the following error during linking : [...]/xtensa-esp32-elf/bin/ld: hello-world.elf section `.dram0.bss' will not fit in region `dram0_0_seg' [...]/xtensa-esp32-elf/bin/ld: DRAM segment data does not fit. [...]/xtensa-esp32-elf/bin/ld: region `dram0_0_seg' overflowed by 93408 bytes collect2: error: ld returned 1 exit status To solve this problem, the external RAM can be integrated to the memory map of the ESP32. To do so, run make menuconfig and navigate to Component Config/ESP32-specific . Then activate Support for external RAM, SPI-Connected RAM by highlighting this zone and pressing the y key. Enter the SPI RAM config/SPI RAM access method menu and choose Integrate RAM into ESP32 memory map . Then select Allow .bss segment placed in external memory and press the y key to activate this function. Finally, open FaustSawtooth.cpp (even though we're trying to synthesize a sine wave now, i.e., the name of this file might differ in your case) and search for static float ftbl0mydspSIG0 which is the static table that will be filled with the sine wave table. This section of the C++ code generated by the Faust compiler will always contain large tables requiring lots of memory. You now want to add the EXT_RAM_ATTR attribute next to the table definition: static float ftbl0mydspSIG0[65536] EXT_RAM_ATTR; It indicates the C++ compiler that this static table should be placed in the external memory rather than in the built-in one. In case your Faust program is doing something else than synthesizing a sine wave, you might have to put this attribute in each table definition. Note: We're currently modifying the Faust compiler to automatize this process when a specific option is given to it. Finally, try to recompile your firmware and it should all work nicely now! Using the Arduino Development Environment The final source code of this tutorial can be found here . The Arduino development environment can also be used to program the ESP32. The steps to use a Faust-generated DSP engine in that context are quite similar to that of the C++ environment described in the previous section . First, make sure that the esp32 package is installed in the Arduino Boards Manager ( Tools/Board/Boards Manager ). Next, create a new empty project and save it. You can then follow the same steps as the one described in the Making a Simple DSP Engine section of the previous tutorial, however you should place the FaustSawtooth.[cpp/h] and WM8978.[cpp/h] files in the same folder as the one containing the .ino file of your project. Hence, the tree of your project folder should now look like this: esp32Tuto.ino FaustSawtooth.cpp FaustSawtooth.h WM8978.cpp WM8978.h You can then edit your Arduino program as follows: #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth(48000,8); void setup() { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); faustSawtooth.start(); } void loop() { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); delay(1000); } and the resulting firmware should have the same effect as the one presented in the previous C++ tutorial . You can refer to the Configuring the Audio Codec section to get more information of what the WM8978 lines are doing, etc.","title":"DSP on the ESP-32 With Faust"},{"location":"tutorials/esp32/#dsp-on-the-esp32-with-faust","text":"The ESP32 is a cheap microcontroller providing built-in Bluetooth and Wifi support, many GPIOs and analog inputs, etc. It's extremely low price (a few dollars) makes it very attractive and it is being used in an increasing number of boards. A wide range of \"unknown/secret\" development boards targeting audio applications are based on the ESP32 and can be found on Alibaba/AliExpress. While most of them target the development of \"intelligent speakers\" (e.g., Alexa, etc.), they host all the components to carry out real-time DSP applications and can therefore be used to develop digital musical instruments, effect processors, synthesizer hardware, etc. The TTGO T-Audio or the ESP32 Audio Dev Kit are good examples of such boards. The TTGO T-Audio (left) and the ESP32 Audio Dev Kit (right) They both host relatively good quality audio codecs with stereo in and out and built-in amplifier, battery circuit, external RAM, and various motion sensors (only for the TTGO T-Audio), all that for less than $15!! Since these boards don't run any OS, very low audio latency can be achieved (i.e., buffer size of 8 samples, etc.). Compared to the Teensy 3.6/4.0 and their respective audio shields , these boards are MUCH cheaper, they're more powerful than the Teensy 3.6 (dual core with a much higher clock) and most importantly, they have enough RAM to run DSP algorithms with a large memory footprint such as reverbs, echos, etc. (which is relatively limited on the Teensy 3.6 and 4.0). Finally, the ESP32 ecosystem is entirely open source (including its loader)! In many ways, they can compete with much more expensive dedicated audio platforms such as the BELA (<$150), etc. The Faust distribution now comes with faust2esp32 , a tool to program ESP32-based boards with Faust. faust2esp32 is still under development and its current version allows to generate DSP engines that can be used in ESP32 projects to carry out sound synthesis and processing tasks. While the mechanism ( i2s ) used to communicate between the ESP32 and the audio codec is the same on all boards, the brand and the type of audio codecs used on ESP32-based boards varies quite a lot. faust2esp32 supports a few audio codecs which can be listed by running faust2esp32 -h or by looking at the faust2esp32 doc . DSP engines produced by faust2esp32 are compatible with both the C++ and the Arduino development environment of the ESP32. The two following sections walk you through starting a new ESP32 project and adding Faust audio support to it using both methods.","title":"DSP on the ESP32 With Faust"},{"location":"tutorials/esp32/#using-the-esp32-c-development-environment","text":"The final source code of this tutorial can be found here . Programming the ESP32 with its native C++ environment offers many advantages. In particular, it allows for a very fine tuning of the board configuration and compilation options. For example, if your DSP algorithm will have a large memory footprint, you might have no other option since external RAM will have to be activated (see Using the External RAM of the ESP32 section). In this short tutorial, we walk you through the steps of making a C++ project from scratch with audio DSP support for the TTGO T-Audio board (the procedure should be more or less the same for similar types of boards).","title":"Using the ESP32 C++ Development Environment"},{"location":"tutorials/esp32/#starting-a-new-esp32-project","text":"Information on how to configure your ESP32 C++ development environment can be found in this tutorial (read it until the end of step 4). Once your environment is up and running, copy the ESP32 hello_world example project somewhere on your system. Then run make , which should automatically prompt the ESP32 configuration panel. Make some modifications if needed (i.e., serial flasher config as specified in the ESP32 get started tutorial, etc.). Once you exit the menu, compilation should start and complete without any issue. Since the DSP engine that we're about to generate with faust2esp32 uses C++, the main file of the current project should be modified to use C++ as well. To do so, just rename main/hello_world_main.c to main/main.cpp (or any other name you'd like, of course, as long as you use the cpp extension). Then, make sure the basic structure of your program looks like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" extern \"C\" { void app_main(void); } void app_main(void) { while(1) { vTaskDelay(1000 / portTICK_PERIOD_MS); } } Here, the infinite while loop gets ran in the main thread/task and is updated every second. Update the CMakeLists.txt file at the root of the project to change the project name (e.g., project(FaustTutorial) ). Similarly, update the CMakeLists.txt file in main to set the right file for the component source (e.g., set(COMPONENT_SRCS \"main.cpp\") ). Run make again to be sure that your program still compiles and that you didn't break anything.","title":"Starting a New ESP32 Project"},{"location":"tutorials/esp32/#making-a-simple-dsp-engine","text":"Let's now write a simple Faust program (the usual one haha) implementing a band limited sawtooth wave with smoothed control: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.sawtooth(freq)*gain; Save it in a file called FaustSawtooth.dsp (this will define the name of the corresponding DSP engine) and compile it using faust2esp32 by running the following command: faust2esp32 -lib FaustSawtooth.dsp -lib asks to generate a C++ DSP engine here as opposed to a complete firmware. Note: the current version of faust2esp32 only allows to generate DSP engines (not complete ESP32 programs) so the -lib option is not really necessary here. Alternatively, this could be done by selecting the ESP32 target in the Faust compilation service in the online IDE . In both cases, a .zip package containing a set of C++ files will be returned. In the current example, FaustSawtooth.[cpp/h] implement the Faust DSP object produced from FaustSawtooth.dsp and WM8978.[cpp/h] is the object corresponding to the audio codec of your board. Note: in the current version of faust2esp32 , the only supported audio codecs are the WM8978 ( -WM8978 option) which is that of the TTGO T-Audio board and the AC101 ( -AC101 option). All these files should be placed in the main folder of the project. After that, they should be included to main.cpp as follows: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); }","title":"Making a Simple DSP Engine"},{"location":"tutorials/esp32/#configuring-the-audio-codec","text":"Next, the WM8978 object (which corresponds to the audio codec, i.e., audio interface on the board) should be instantiated and configured in app_main : WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); Once again, the current version of faust2esp32 only provides support for the Wolfson WM8978 present on the TTGO T-Audio and the AC101, but we're working at adding new codecs from other manufacturers, etc. The procedure should be similar with other codecs. The present configuration activates the mic input, deactivates the amp for the speaker, sets the headphone gain to 40, etc. Please refer to the WM8978 object documentation for more information. Note that each of these commands will be called \"in real-time\" at start-up so the configuration of the audio codec is progressively done and should be carried out before sending any audio buffer to it.","title":"Configuring the Audio Codec"},{"location":"tutorials/esp32/#instantiating-the-faust-dsp-engine","text":"After configuring the audio codec, the Faust DSP object produced in the previous step and included in main.cpp should be instantiated in app_main as well: int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); The constructor of FaustSawtooth takes two arguments: the sampling rate (48kHz here) and the block size (8 here). Calling the constructor will configure the object, allocate memory for it, etc. but in order to start computation, the start() method needs to be called. Since ESP32 firmwares are based on freertos , audio is computed in its own high priority task and calling start() will launch this task. Note that this task can be removed and audio computation stopped at any time simply by calling stop() . Finally, the setParamValue method of the FaustSawtooth object can be called at any point to change the value of one of the parameter of the Faust object (here, two parameters were declared: freq and gain ). For example, the frequency of the generated sawtooth could be randomly changed at every sample by calling the following line in the while loop at the bottom of app_main : faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); At this point, main.cpp should look like this: #include <stdio.h> #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"esp_system.h\" #include \"esp_spi_flash.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" extern \"C\" { void app_main(void); } void app_main(void) { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); int SR = 48000; int BS = 8; FaustSawtooth faustSawtooth(SR,BS); faustSawtooth.start(); while(1) { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); vTaskDelay(1000 / portTICK_PERIOD_MS); } } Try to recompile the firmware and upload it to your board. If headphones are connected to it, you should hear a sawtooth wave whose frequency changes randomly every second.","title":"Instantiating the Faust DSP Engine"},{"location":"tutorials/esp32/#using-the-external-ram-of-the-esp32","text":"Some DSP algorithms might require a large amount of memory allocation (e.g., wave tables, delays, etc.). In that case, the object generated by Faust might not fit in the built-in RAM of the ESP32 and it might be necessary to use the external RAM module (SRAM) of the board. In order to test this, we first need to write a Faust program that will need a large amount of memory. Replacing the sawtooth wave of the previous example by a sine wave should do it since the default sine wave oscillator of Faust ( os.osc ) is based on a wave table of size 65536: import(\"stdfaust.lib\"); freq = nentry(\"freq\",440,20,20000,0.01) : si.smoo; gain = nentry(\"gain\",1,0,1,0.01) : si.smoo; process = os.osc(freq)*gain; You can then follow the same steps as the ones described in the Making a Simple DSP Engine section to integrate this Faust program to your C++ ESP32 project. If you try to compile your firmware again (i.e., make ), you should get the following error during linking : [...]/xtensa-esp32-elf/bin/ld: hello-world.elf section `.dram0.bss' will not fit in region `dram0_0_seg' [...]/xtensa-esp32-elf/bin/ld: DRAM segment data does not fit. [...]/xtensa-esp32-elf/bin/ld: region `dram0_0_seg' overflowed by 93408 bytes collect2: error: ld returned 1 exit status To solve this problem, the external RAM can be integrated to the memory map of the ESP32. To do so, run make menuconfig and navigate to Component Config/ESP32-specific . Then activate Support for external RAM, SPI-Connected RAM by highlighting this zone and pressing the y key. Enter the SPI RAM config/SPI RAM access method menu and choose Integrate RAM into ESP32 memory map . Then select Allow .bss segment placed in external memory and press the y key to activate this function. Finally, open FaustSawtooth.cpp (even though we're trying to synthesize a sine wave now, i.e., the name of this file might differ in your case) and search for static float ftbl0mydspSIG0 which is the static table that will be filled with the sine wave table. This section of the C++ code generated by the Faust compiler will always contain large tables requiring lots of memory. You now want to add the EXT_RAM_ATTR attribute next to the table definition: static float ftbl0mydspSIG0[65536] EXT_RAM_ATTR; It indicates the C++ compiler that this static table should be placed in the external memory rather than in the built-in one. In case your Faust program is doing something else than synthesizing a sine wave, you might have to put this attribute in each table definition. Note: We're currently modifying the Faust compiler to automatize this process when a specific option is given to it. Finally, try to recompile your firmware and it should all work nicely now!","title":"Using the External RAM of the ESP32"},{"location":"tutorials/esp32/#using-the-arduino-development-environment","text":"The final source code of this tutorial can be found here . The Arduino development environment can also be used to program the ESP32. The steps to use a Faust-generated DSP engine in that context are quite similar to that of the C++ environment described in the previous section . First, make sure that the esp32 package is installed in the Arduino Boards Manager ( Tools/Board/Boards Manager ). Next, create a new empty project and save it. You can then follow the same steps as the one described in the Making a Simple DSP Engine section of the previous tutorial, however you should place the FaustSawtooth.[cpp/h] and WM8978.[cpp/h] files in the same folder as the one containing the .ino file of your project. Hence, the tree of your project folder should now look like this: esp32Tuto.ino FaustSawtooth.cpp FaustSawtooth.h WM8978.cpp WM8978.h You can then edit your Arduino program as follows: #include \"freertos/FreeRTOS.h\" #include \"freertos/task.h\" #include \"WM8978.h\" #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth(48000,8); void setup() { WM8978 wm8978; wm8978.init(); wm8978.addaCfg(1,1); wm8978.inputCfg(1,0,0); wm8978.outputCfg(1,0); wm8978.micGain(30); wm8978.auxGain(0); wm8978.lineinGain(0); wm8978.spkVolSet(0); wm8978.hpVolSet(40,40); wm8978.i2sCfg(2,0); faustSawtooth.start(); } void loop() { faustSawtooth.setParamValue(\"freq\",rand()%(2000-50 + 1) + 50); delay(1000); } and the resulting firmware should have the same effect as the one presented in the previous C++ tutorial . You can refer to the Configuring the Audio Codec section to get more information of what the WM8978 lines are doing, etc.","title":"Using the Arduino Development Environment"},{"location":"tutorials/jsfx/","text":"Using Faust in JSFX In this tutorial, we present how Faust can be used with JSFX , a scripting language used in Reaper . The JSFX engine is integrated in Reaper by default, and can also be found as a plugin opcode for Csound, as well as a set of standalone projects : ysfx , jsusfx . The JSFX language is based on Cockos EEL2 open-source programming language. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for JSFX users who want to discover Faust. Using command line tools Generating JSFX code Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The JSFX code can be generated using faust -lang jsfx osc.dsp -o osc.jsfx This will generate JSFX code that follows the standard JSFX file structure: @init // init section @block // control section @slider // called when a control value changes @sample // audio computation section This code can be directly imported in Reaper or placed in Reaper Effects directory. Generated JSFX plugin in Reaper The generated code is fully self-contained and can be directly imported as a Reaper JSFX audio plugin, on any supported platform. At the top of the generated file, a few lines are dedicated to report file description and metadata. Then, the initialization starts with: Sliders Inputs and outputs slider1:fHslider0=1000<20,3000,1>hslider_freq10 slider2:fHslider2=200<20,3000,1>hslider_freq20 slider3:fHslider1=0<-96,0,0.1>hslider_volume0 out_pin:output0 out_pin:output1 In JSFX, sliders are the only available controls that match Faust controls. It has been decided that buttons and checkboxes are thus represented as 0-1 sliders in JSFX. Next, the @init section starts with all required functions - including math functions missing in JSFX and memory management functions. These functions will always be included in generated JSFX code, since the rest of the code requires it. The @init section then defines a few constants (bitmasks for MIDI processing, and useful constants for processing like number of voices nvoices ). The actual DSP part starts right after these constants. Global tables are then allocated, here the table where sine waveform will be computed: ftbl0mydspSIG0 = MEMORY.alloc_memory(65536); And the structure of our DSP class is defined. Since JSFX is not a real object oriented programming language, we use indexes inside memory chunks to access DSP object members. Each object itself is represented as an address in JSFX preallocated memory. The dsp. fields indicate the position of members inside the object memory. // DSP struct memory layout dsp.memory = MEMORY.alloc_memory(0); ddsp.size = 24; dsp.iVec1 = 0; dsp.fHslider0 = 2; dsp.fSampleRate = 3; dsp.fConst1 = 4; dsp.fRec1 = 5; dsp.fConst2 = 7; dsp.fConst3 = 8; dsp.fHslider1 = 9; dsp.fRec2 = 10; dsp.fHslider2 = 12; dsp.fRec3 = 13; dsp.iVec0 = 15; dsp.iRec0 = 17; dsp.fSlow0 = 19; dsp.fSlow1 = 20; dsp.fSlow2 = 21; dsp.output0 = 22; dsp.output1 = 23; The next part consists in two functions used to create DSP objects, allocate their memory and initialize their states. One object represents one voice. If an object has no [nvoices] metadata, or if [nvoices:1] , only one object will be created. The create_instance function allocates memory, then init_instances precomputes object state, including constants and everything that doesn't need to be computed at runtime. Finally, the @init section defines the control function. This function corresponds to the computation happening just before the audio loop in the C++ backend. These correspond to the computations related to controls and MIDI. In JSFX sandboxed context, we don't need to call it on every loop, thus it has been pushed outside of @block . Moreover, this computation must be accessible from both @slider and @block . The current implementation will trigger a call to control function everytime a slider value changes, or everytime a MIDI input event happens. By default, the @block section is empty. It will be filled with code if MIDI is somehow enabled: by associating MIDI input to a control in slider metadata [keyon:64] by setting polyphonic mode with declare options [\"nvoices:4\"] The former will actually connect MIDI key or ctrl to the slider, while the latter will connect MIDI note inputs to sliders named freq , key , vel , gain , gate , and will convert the MIDI value to whatever it is supposed to represent: frequency for freq , raw MIDI note number for \"key\" (...). The @block section contains a condition so that it will only call the control function when MIDI events occur. The \u0300 @slider section only calls control , and is itself only computed when a slider value changes. Finally, the @sample section is where the magic happens. It will loop through the different objects and compute the audio output. This section is represented in JSFX as a block of code called for every single sample. At the bottom of generated code, object outputs are summed in JSFX special variables spl0 , spl1 (...), which are the actual outputs of a JSFX plugin. MIDI basic example Basic MIDI inputs can be retrieved with controls (Faust sliders) if specific metadata are added to the control name. The available MIDI inputs are: keyon keyoff key (both keyon and keyoff) ctrl See MIDI for more information about MIDI metadata syntax. The generated code will contain a @block section that connects MIDI CC input (for CC 10 and 11) to relevant control values. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == CC) ? ( midi_event += 1; (msg2 == 0xa) ? (fHslider1 = midi_scale(msg3, 0.0000000000000000, 127.0000000000000000, 1.0000000000000000)); (msg2 == 0xb) ? (fHslider0 = midi_scale(msg3, 50.0000000000000000, 1000.0000000000000000, 0.1000000000000000)); ); ); (midi_event > 0) ? (control()); MIDI polyphonic example As explained in the MIDI documentation, Faust supports MIDI polyphonic audio plugins. These plugins respond to MIDI note inputs with three different data: key or frequency velocity or gain a gate used to trigger an envelope Be careful that key will be a value between 0-127 while frequency will be converted to cycle per seconds. Same mechanism applies to velocity (0-127) versus gain (0-1). The following code shows the basic mechanism of the MIDI polyphonic instrument that compiles for JSFX. In this JSFX backend, polyphonic voices use a voice stealing mechanism, allowing a new voice to steal the oldest one if no voice is free. The generated code contains a filled @block section that is used to look for MIDI input notes midirecv , thus performing expected actions: a NOTE ON message looks for an available voice (or steals the oldest one if necessary) and sets its controls a NOTE OFF message looks for the voice that is playing its key to turn its gate off. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == NOTE_ON) ? ( midi_event += 1; voice_idx = get_oldest_voice(); sort_voices(voice_idx); obj = get_dsp(voice_idx); obj[dsp.key_id] = msg2; obj[dsp.gate] = 1; obj[dsp.fCheckbox0] = 1; obj[dsp.fHslider1] = midi_scale(msg3, 0.0000000000000000, 1.0000000000000000, 0.0100000000000000); obj[dsp.fHslider0] = limit(mtof(msg2), 0.0000000000000000, 10000.0000000000000000); ); // NOTE ON condition off (status == NOTE_OFF) ? ( midi_event += 1; voice_idx = 0; while(voice_idx < nvoices) ( obj = get_dsp(voice_idx); (obj[dsp.key_id] == msg2 && obj[dsp.gate] > 0) ? ( obj[dsp.gate] = 0; obj[dsp.fCheckbox0] = 0; voice_idx = nvoices; ); voice_idx += 1; ); // end of while ); // end of condition ); (midi_event > 0) ? (control()); Using the Faust Web IDE Generating a JSFX file The JSFX backend is available on the Faust web IDE . In order to export a Faust program as JSFX code, you will need to click on the \"export/compile to specific target\" button (on the left side, below \"Save as\"). Then, you need to choose jsfx both as the platform and architecture, and click compile . This will allow your to download a binary.zip file, containing the resulting jsfx file and your original dsp file. Generating a JSFX file in polyphonic mode The declare options \"[midi:on][nvoices:n]\"; coding convention can be used in the DSP code to activate MIDI and polyphonic mode. Limitations As JSFX is a sandboxed environment, this backend cannot match the full Faust potential. Some features are missing, some others might come in the future. First, only three controls are available: sliders: hslider, vslider, nentry button checkbox All of these are mapped to sliders in JSFX. On the MIDI side, this backend does not support program changes, neither channel press, or pitchweel. As described before, the available MIDI is key, keyon, keyoff, ctrl and polyphonic mode.","title":"Using Faust in JSFX"},{"location":"tutorials/jsfx/#using-faust-in-jsfx","text":"In this tutorial, we present how Faust can be used with JSFX , a scripting language used in Reaper . The JSFX engine is integrated in Reaper by default, and can also be found as a plugin opcode for Csound, as well as a set of standalone projects : ysfx , jsusfx . The JSFX language is based on Cockos EEL2 open-source programming language.","title":"Using Faust in JSFX"},{"location":"tutorials/jsfx/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for JSFX users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/jsfx/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/jsfx/#generating-jsfx-code","text":"Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The JSFX code can be generated using faust -lang jsfx osc.dsp -o osc.jsfx This will generate JSFX code that follows the standard JSFX file structure: @init // init section @block // control section @slider // called when a control value changes @sample // audio computation section This code can be directly imported in Reaper or placed in Reaper Effects directory. Generated JSFX plugin in Reaper The generated code is fully self-contained and can be directly imported as a Reaper JSFX audio plugin, on any supported platform. At the top of the generated file, a few lines are dedicated to report file description and metadata. Then, the initialization starts with: Sliders Inputs and outputs slider1:fHslider0=1000<20,3000,1>hslider_freq10 slider2:fHslider2=200<20,3000,1>hslider_freq20 slider3:fHslider1=0<-96,0,0.1>hslider_volume0 out_pin:output0 out_pin:output1 In JSFX, sliders are the only available controls that match Faust controls. It has been decided that buttons and checkboxes are thus represented as 0-1 sliders in JSFX. Next, the @init section starts with all required functions - including math functions missing in JSFX and memory management functions. These functions will always be included in generated JSFX code, since the rest of the code requires it. The @init section then defines a few constants (bitmasks for MIDI processing, and useful constants for processing like number of voices nvoices ). The actual DSP part starts right after these constants. Global tables are then allocated, here the table where sine waveform will be computed: ftbl0mydspSIG0 = MEMORY.alloc_memory(65536); And the structure of our DSP class is defined. Since JSFX is not a real object oriented programming language, we use indexes inside memory chunks to access DSP object members. Each object itself is represented as an address in JSFX preallocated memory. The dsp. fields indicate the position of members inside the object memory. // DSP struct memory layout dsp.memory = MEMORY.alloc_memory(0); ddsp.size = 24; dsp.iVec1 = 0; dsp.fHslider0 = 2; dsp.fSampleRate = 3; dsp.fConst1 = 4; dsp.fRec1 = 5; dsp.fConst2 = 7; dsp.fConst3 = 8; dsp.fHslider1 = 9; dsp.fRec2 = 10; dsp.fHslider2 = 12; dsp.fRec3 = 13; dsp.iVec0 = 15; dsp.iRec0 = 17; dsp.fSlow0 = 19; dsp.fSlow1 = 20; dsp.fSlow2 = 21; dsp.output0 = 22; dsp.output1 = 23; The next part consists in two functions used to create DSP objects, allocate their memory and initialize their states. One object represents one voice. If an object has no [nvoices] metadata, or if [nvoices:1] , only one object will be created. The create_instance function allocates memory, then init_instances precomputes object state, including constants and everything that doesn't need to be computed at runtime. Finally, the @init section defines the control function. This function corresponds to the computation happening just before the audio loop in the C++ backend. These correspond to the computations related to controls and MIDI. In JSFX sandboxed context, we don't need to call it on every loop, thus it has been pushed outside of @block . Moreover, this computation must be accessible from both @slider and @block . The current implementation will trigger a call to control function everytime a slider value changes, or everytime a MIDI input event happens. By default, the @block section is empty. It will be filled with code if MIDI is somehow enabled: by associating MIDI input to a control in slider metadata [keyon:64] by setting polyphonic mode with declare options [\"nvoices:4\"] The former will actually connect MIDI key or ctrl to the slider, while the latter will connect MIDI note inputs to sliders named freq , key , vel , gain , gate , and will convert the MIDI value to whatever it is supposed to represent: frequency for freq , raw MIDI note number for \"key\" (...). The @block section contains a condition so that it will only call the control function when MIDI events occur. The \u0300 @slider section only calls control , and is itself only computed when a slider value changes. Finally, the @sample section is where the magic happens. It will loop through the different objects and compute the audio output. This section is represented in JSFX as a block of code called for every single sample. At the bottom of generated code, object outputs are summed in JSFX special variables spl0 , spl1 (...), which are the actual outputs of a JSFX plugin.","title":"Generating JSFX code"},{"location":"tutorials/jsfx/#midi-basic-example","text":"Basic MIDI inputs can be retrieved with controls (Faust sliders) if specific metadata are added to the control name. The available MIDI inputs are: keyon keyoff key (both keyon and keyoff) ctrl See MIDI for more information about MIDI metadata syntax. The generated code will contain a @block section that connects MIDI CC input (for CC 10 and 11) to relevant control values. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == CC) ? ( midi_event += 1; (msg2 == 0xa) ? (fHslider1 = midi_scale(msg3, 0.0000000000000000, 127.0000000000000000, 1.0000000000000000)); (msg2 == 0xb) ? (fHslider0 = midi_scale(msg3, 50.0000000000000000, 1000.0000000000000000, 0.1000000000000000)); ); ); (midi_event > 0) ? (control());","title":"MIDI basic example"},{"location":"tutorials/jsfx/#midi-polyphonic-example","text":"As explained in the MIDI documentation, Faust supports MIDI polyphonic audio plugins. These plugins respond to MIDI note inputs with three different data: key or frequency velocity or gain a gate used to trigger an envelope Be careful that key will be a value between 0-127 while frequency will be converted to cycle per seconds. Same mechanism applies to velocity (0-127) versus gain (0-1). The following code shows the basic mechanism of the MIDI polyphonic instrument that compiles for JSFX. In this JSFX backend, polyphonic voices use a voice stealing mechanism, allowing a new voice to steal the oldest one if no voice is free. The generated code contains a filled @block section that is used to look for MIDI input notes midirecv , thus performing expected actions: a NOTE ON message looks for an available voice (or steals the oldest one if necessary) and sets its controls a NOTE OFF message looks for the voice that is playing its key to turn its gate off. @block midi_event = 0; while (midirecv(mpos, msg1, msg2, msg3)) ( status = msg1&0xF0; channel = msg1&0x0F; (status == NOTE_ON) ? ( midi_event += 1; voice_idx = get_oldest_voice(); sort_voices(voice_idx); obj = get_dsp(voice_idx); obj[dsp.key_id] = msg2; obj[dsp.gate] = 1; obj[dsp.fCheckbox0] = 1; obj[dsp.fHslider1] = midi_scale(msg3, 0.0000000000000000, 1.0000000000000000, 0.0100000000000000); obj[dsp.fHslider0] = limit(mtof(msg2), 0.0000000000000000, 10000.0000000000000000); ); // NOTE ON condition off (status == NOTE_OFF) ? ( midi_event += 1; voice_idx = 0; while(voice_idx < nvoices) ( obj = get_dsp(voice_idx); (obj[dsp.key_id] == msg2 && obj[dsp.gate] > 0) ? ( obj[dsp.gate] = 0; obj[dsp.fCheckbox0] = 0; voice_idx = nvoices; ); voice_idx += 1; ); // end of while ); // end of condition ); (midi_event > 0) ? (control());","title":"MIDI polyphonic example"},{"location":"tutorials/jsfx/#using-the-faust-web-ide","text":"","title":"Using the Faust Web IDE"},{"location":"tutorials/jsfx/#generating-a-jsfx-file","text":"The JSFX backend is available on the Faust web IDE . In order to export a Faust program as JSFX code, you will need to click on the \"export/compile to specific target\" button (on the left side, below \"Save as\"). Then, you need to choose jsfx both as the platform and architecture, and click compile . This will allow your to download a binary.zip file, containing the resulting jsfx file and your original dsp file.","title":"Generating a JSFX file"},{"location":"tutorials/jsfx/#generating-a-jsfx-file-in-polyphonic-mode","text":"The declare options \"[midi:on][nvoices:n]\"; coding convention can be used in the DSP code to activate MIDI and polyphonic mode.","title":"Generating a JSFX file in polyphonic mode"},{"location":"tutorials/jsfx/#limitations","text":"As JSFX is a sandboxed environment, this backend cannot match the full Faust potential. Some features are missing, some others might come in the future. First, only three controls are available: sliders: hslider, vslider, nentry button checkbox All of these are mapped to sliders in JSFX. On the MIDI side, this backend does not support program changes, neither channel press, or pitchweel. As described before, the available MIDI is key, keyon, keyoff, ctrl and polyphonic mode.","title":"Limitations"},{"location":"tutorials/julia/","text":"Using Faust in Julia In this tutorial, we present how Faust can be used in Julia , a high-level, high-performance, dynamic programming language. While it is a general-purpose language and can be used to write any application, many of its features are well suited for numerical analysis and computational science. An integration of the libfaust compiler in Julia has been firstly developed by Cora Johnson-Roberson , and will be covered by the last section of the tutorial . Then a Julia backend has been added in a second step in the Faust compiler. It allows to generate ready to use Julia code from any Faust DSP program. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section and third section are better suited for Julia users who want to discover Faust. Installing the required packages Be sure to have the julia command available in your PATH, as explained here . With a fresh Julia install, all required packages are decribed in the packages.jl file: in case you have an installed Faust version, it can be installed with the julia packages.jl command done in the architecture/julia folder of the Faust repository of directly downloaded, and executed with the julia packages.jl command Using command line tools Generating Julia code Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The Julia code can be generated using: faust -lang julia osc.dsp -o osc.jl This will generate a mydsp{T} data structure, as a subtype of the abstract type dsp , with a set of methods to manipulate it. The generated API simply follows the one defined for the base dsp type. This API basically mimics the one defined for the C++ backend . The resulting file is not self-contained and so cannot be directly compiled using the julia program: julia osc.jl ERROR: LoadError: UndefVarError: dsp not defined ... Some additional types like FAUSTFLOAT , dsp , Meta and UI have to be defined in a so-called architecture files . The Julia specific ones are described here . A simple one named minimal.jl can be used for that with the following command: faust -lang julia osc.dsp -a julia/minimal.jl -o osc.jl Now the resulting foo.jl file is self-contained and can be executed with: julia -i osc.jl (here -i to stay in interactive mode) Which compiles the Julia code, executes it and produces: Application name: osc getNumInputs: 0 getNumOutputs: 2 Path/UIZone dictionary: Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) With the name of the application, the number of input/output channels, the set of controller paths with their range, and a display of the first samples of the computed outputs (using the powerful Plots.jl package), and showing here the effect of the si.smoo at the beginning of the signals: Displaying the outputs Looking at the generated code A mydsp{T} data structure, as a subtype of the abstract type dsp is generated, and contains the field definitions with their types, as well as a constructor initializing them: mutable struct mydsp{T} <: dsp fSampleRate::Int32 fConst1::T fHslider0::FAUSTFLOAT fConst2::T fRec0::Vector{T} fConst3::T fHslider1::FAUSTFLOAT fRec2::Vector{T} fHslider2::FAUSTFLOAT fRec3::Vector{T} iVec0::Vector{Int32} iRec1::Vector{Int32} ftbl0mydspSIG0::Vector{T} mydsp{T}() where {T} = begin dsp = new{T}() dsp.fRec0 = zeros(T, 2) dsp.fRec2 = zeros(T, 2) dsp.fRec3 = zeros(T, 2) dsp.iVec0 = zeros(Int32, 2) dsp.iRec1 = zeros(Int32, 2) dsp.ftbl0mydspSIG0 = zeros(T, 65536) dsp end end Note that the structure is parametrized with a {T} type to be given at initialization time. The const REAL = Float32 or const REAL = Float64 line is generated depending of the -single (default), or -double option given at compilation time, and can be used for that. Several access methods are generated: function getNumInputs(dsp::mydsp{T}) where {T} return Int32(0) end function getNumOutputs(dsp::mydsp{T}) where {T} return Int32(2) end Several initialiation methods like init! , initanceInit! , instanceResetUserInterface! etc. are generated, here is one of them: function instanceResetUserInterface!(dsp::mydsp{T}) where {T} dsp.fHslider0 = FAUSTFLOAT(0.0f0) dsp.fHslider1 = FAUSTFLOAT(1000.0f0) dsp.fHslider2 = FAUSTFLOAT(200.0f0) end The buildUserInterface! method uses a UI subtype to build a controller, which could be a Graphical User Interface (for instance using GTK ), or an OSC controller: function buildUserInterface!(dsp::mydsp{T}, ui_interface::UI) where {T} openVerticalBox!(ui_interface, \"Oscillator\") declare!(ui_interface, :fHslider1, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq1\", :fHslider1, FAUSTFLOAT(1000.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider2, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq2\", :fHslider2, FAUSTFLOAT(500.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider0, \"unit\", \"dB\") addHorizontalSlider!(ui_interface, \"volume\", :fHslider0, FAUSTFLOAT(0.0f0), FAUSTFLOAT(-96.0f0), FAUSTFLOAT(0.0f0), FAUSTFLOAT(0.1f0)) closeBox!(ui_interface) end The DSP structure fields to access are simply described with their name (actually a Symbol in Julia terminology), and can later be used with the standard setproperty! and getproperty access methods, like in the setParamValue! and getParamValue methods written in the MapUI architecture. And finally the compute! method that processes and input buffer with count frames to produce an output buffer: @inbounds function compute!(dsp::mydsp, count::Int32, inputs, outputs) output0 = @inbounds @view outputs[:, 1] output1 = @inbounds @view outputs[:, 2] fSlow0::Float32 = (dsp.fConst1 * pow(10.0f0, (0.0500000007f0 * Float32(dsp.fHslider0)))) fSlow1::Float32 = (dsp.fConst3 * Float32(dsp.fHslider1)) fSlow2::Float32 = (dsp.fConst3 * Float32(dsp.fHslider2)) @inbounds for i0 in 0:count-1 dsp.fRec0[1] = (fSlow0 + (dsp.fConst2 * dsp.fRec0[2])) dsp.fRec2[1] = (fSlow1 + (dsp.fRec2[2] - floor((fSlow1 + dsp.fRec2[2])))) output0[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec2[1]))+1])) dsp.fRec3[1] = (fSlow2 + (dsp.fRec3[2] - floor((fSlow2 + dsp.fRec3[2])))) output1[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec3[1]))+1])) dsp.fRec0[2] = dsp.fRec0[1] dsp.fRec2[2] = dsp.fRec2[1] dsp.fRec3[2] = dsp.fRec3[1] end end Note that not all generated methods are presented in this short presentation. Look at the generated osc.jl file to see all of them. Using the generated code Some globals have to be defined: # Testing samplerate = Int32(44100) block_size = Int32(16) The DSP object has to be created and initialized, here using the generated REAL type alias: # Init DSP my_dsp = mydsp{REAL}() init!(my_dsp, samplerate) His name can be extracted from the DSP metadata using the following code: # Retrieve the application name mutable struct NameMeta <: Meta name::String end function declare!(m::NameMeta, key::String, value::String) if (key == \"name\") m.name = value; end end) m = NameMeta(\"\") metadata!(my_dsp, m) println(\"Application name: \", m.name, \"\\n\") The number of inputs/outputs can be printed: println(\"getNumInputs: \", getNumInputs(my_dsp)) println(\"getNumOutputs: \", getNumOutputs(my_dsp), \"\\n\") Information on all controllers can be retrieved using the MapUI type: # Create a MapUI controller map_ui = MapUI(my_dsp) buildUserInterface!(my_dsp, map_ui) # Print all zones println(\"Path/UIZone dictionary: \", getZoneMap(map_ui), \"\\n\") And finally one buffer can be processed with the following code, here giving FAUSTFLOAT as the actual type for external samples: inputs = zeros(FAUSTFLOAT, block_size, getNumInputs(my_dsp)) outputs = zeros(FAUSTFLOAT, block_size, getNumOutputs(my_dsp)) compute!(my_dsp, block_size, inputs, outputs) println(\"One computed output buffer: \", outputs) Now the osc.jl can possibly be directly integrated in a larger project, or customized using an adapted new architecture file. The faust2portaudiojulia tool The Faust DSP program can be compiled and run with the more sophisticated faust2portaudiojulia tool which will render it using the PortAudio.jl package to access the audio driver, OpenSoundControl.jl package for OSC control, and GTK.jl package for the Graphical User Interface. The faust2portaudiojulia tool use this portaudio_gtk.jl architecture file. When used the following way: faust2portaudiojulia osc.dsp It creates an osc.jl file that can simply be executed using: julia osc.jl So the stereo program generating sinewaves at 1000 Hz and 200 Hz by default is now playing, without any interface to control it. Now using the following command: faust2portaudiojulia -play 2 osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and GTK GUI (and with 2 threads needed for GTK and audio). Note that the GUI is still quite simple: The GTK based controller The following command: faust2portaudiojulia -play 2 -osc osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and OSC control (and with 2 threads needed for OSC and audio). Now the application starts with an OSC controller running on ports 5000 and 5001: getNumInputs: 0 getNumOutputs: 2 Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 500.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) Faust OSC application 'Oscillator' is running on UDP ports 5000, 5001 Direct OSC commands can be sent, as explained here . So for instance to change both channel frequencies: oscsend localhost 5000 /Oscillator/freq1 f 400 oscsend localhost 5000 /Oscillator/freq2 f 960 You can possibly use the faust-osc-controller tool to remotely control the Julia program, with the following command: faust-osc-controller /Oscillator -port 5001 -outport 5000 -xmit 1 The faust-osc-controller OSC controller And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the faust2portaudiojulia -play 2 -oscc osc.dsp command. Using the Faust Web IDE Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Julia code, or possibly as working audio applications. Generating the pure Julia output The output of the Julia backend can directly be generated using the Platform = source and Architecture = julia export options. As previously explained, the resulting file is not self-contained, but shows the code which has to be wrapped with adapted Julia architecture files. Exporting the code Generating a minimal working Julia file The Platform = julia and Architecture = julia export options allow to generate a self-contained file using the minimal.jl architecture, to be by started with the following command: julia -i foo.jl (here -i to stay in interactive mode) Generating an audio application controllable with GTK or OSC based interfaces The Platform = julia and Architecture = portaudiojulia export options allow to generate a self-contained file using the portaudio_gtk.jl architecture. The following command starts the program with the GTK control interface: julia -t 2 foo.jl -gtk The following command starts the program with the OSC control interface, ready to receive OSC commands or controlled with the faust-osc-controller tool as previously explained: julia -t 2 foo.jl -osc And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the following command: julia -t 2 foo.jl -oscc Using the Faust.jl Julia package The Julia ecosystem contains over 4,000 packages that are registered in the General registry . A Faust.lj package initially developed by Cora Johnson-Roberson , has been forked and extended here . It allows the use of the libfaust library and the Julia Faust backend. The Visual Studio Code application can be configurated with a Julia extension . It is a very convenient way to edit, compile and test Julia + Faust code. Installing the forked Faust.jl package In VS Code, you can enter the package mode . Pkg comes with a REPL. Enter the Pkg REPL by pressing ] from the Julia REPL and install the Faust package with: pkg> add https://github.com/sletz/Faust.jl To get back to the Julia REPL, press backspace or ^C, then load the Faust package with: julia> using Faust Assuming a working Julia environment is setup, the following commands can be used. Using the libfaust compiler # Create a DSP factory. dsp = compile(\"\"\" import(\"stdfaust.lib\"); freq = hslider(\"freq\", 440, 20, 20000, 1); gain = hslider(\"gain\", 0.25, 0, 1, 0.001); process = os.oscs(freq) * gain; \"\"\") # Initialize DSP instance and controls. init!(dsp; block_size=1024, samplerate=48000) # Compute one block of audio. compute!(dsp) By default, programs are compiled as single-precision; you can give -double or other arguments to the compiler like so: compile(\"process = _;\"; name=\"passthrough\", argv=[\"-double\", \"-vec\"]) Each call to compute! will calculate block_size samples and return the output as a matrix of (block_size, n_channels). If the program takes input, set dsp.inputs to a (block_size, n_channels) matrix before calling compute! : passthrough = init!(compile(\"process = _,_;\")) x = rand(Float32, 256, 2) passthrough.inputs = x @test compute!(passthrough) == x After calling init! , any UI elements declared in your code will have their path names and ranges available via dsp.ui.ranges . julia> dsp.ui.ranges Dict{String, Faust.UIRange} with 2 entries: \"/score/gain\" => UIRange(0.25, 0.0, 1.0, 0.001) \"/score/freq\" => UIRange(440.0, 20.0, 20000.0, 1.0) julia> ctrl = dsp.ui.ranges[\"/score/freq\"]; (ctrl.min, ctrl.max) (20.0f0, 20000.0f0) One can then set the values of these params like: setparams!(dsp, Dict(\"/score/freq\" => 220.0f0)) Displaying signals Julia offers a lot of packages to display signals, for example with the following commands ( coded here ) to display the outputs buffers: # Define a block of DSP code julia> code = \"\"\"import(\"stdfaust.lib\"); process = os.osc(500), os.sawtooth(1000);\"\"\" # Compile the DSP, compute one block of audio and display the outputs julia> compileFaustString(code) # Compile the DSP, with additional compiler arguments and display the outputs julia> compileFaustString(code; argv=[\"-double\", \"-vec\"]) # Compile the DSP, with a larger block_size and display the outputs julia> compileFaustString(code; block_size=50000) With the following result in VS code: Using Julia in VS code More sophisticated analysis can be done, like this example , or this projet to experiment using NNs in Faust .","title":"Using Faust in Julia"},{"location":"tutorials/julia/#using-faust-in-julia","text":"In this tutorial, we present how Faust can be used in Julia , a high-level, high-performance, dynamic programming language. While it is a general-purpose language and can be used to write any application, many of its features are well suited for numerical analysis and computational science. An integration of the libfaust compiler in Julia has been firstly developed by Cora Johnson-Roberson , and will be covered by the last section of the tutorial . Then a Julia backend has been added in a second step in the Faust compiler. It allows to generate ready to use Julia code from any Faust DSP program.","title":"Using Faust in Julia"},{"location":"tutorials/julia/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section and third section are better suited for Julia users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/julia/#installing-the-required-packages","text":"Be sure to have the julia command available in your PATH, as explained here . With a fresh Julia install, all required packages are decribed in the packages.jl file: in case you have an installed Faust version, it can be installed with the julia packages.jl command done in the architecture/julia folder of the Faust repository of directly downloaded, and executed with the julia packages.jl command","title":"Installing the required packages"},{"location":"tutorials/julia/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/julia/#generating-julia-code","text":"Assuming you've compiled and installed the faust compiler from the master-dev branch , starting from the following DSP osc.dsp program: The Julia code can be generated using: faust -lang julia osc.dsp -o osc.jl This will generate a mydsp{T} data structure, as a subtype of the abstract type dsp , with a set of methods to manipulate it. The generated API simply follows the one defined for the base dsp type. This API basically mimics the one defined for the C++ backend . The resulting file is not self-contained and so cannot be directly compiled using the julia program: julia osc.jl ERROR: LoadError: UndefVarError: dsp not defined ... Some additional types like FAUSTFLOAT , dsp , Meta and UI have to be defined in a so-called architecture files . The Julia specific ones are described here . A simple one named minimal.jl can be used for that with the following command: faust -lang julia osc.dsp -a julia/minimal.jl -o osc.jl Now the resulting foo.jl file is self-contained and can be executed with: julia -i osc.jl (here -i to stay in interactive mode) Which compiles the Julia code, executes it and produces: Application name: osc getNumInputs: 0 getNumOutputs: 2 Path/UIZone dictionary: Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) With the name of the application, the number of input/output channels, the set of controller paths with their range, and a display of the first samples of the computed outputs (using the powerful Plots.jl package), and showing here the effect of the si.smoo at the beginning of the signals: Displaying the outputs","title":"Generating Julia code"},{"location":"tutorials/julia/#looking-at-the-generated-code","text":"A mydsp{T} data structure, as a subtype of the abstract type dsp is generated, and contains the field definitions with their types, as well as a constructor initializing them: mutable struct mydsp{T} <: dsp fSampleRate::Int32 fConst1::T fHslider0::FAUSTFLOAT fConst2::T fRec0::Vector{T} fConst3::T fHslider1::FAUSTFLOAT fRec2::Vector{T} fHslider2::FAUSTFLOAT fRec3::Vector{T} iVec0::Vector{Int32} iRec1::Vector{Int32} ftbl0mydspSIG0::Vector{T} mydsp{T}() where {T} = begin dsp = new{T}() dsp.fRec0 = zeros(T, 2) dsp.fRec2 = zeros(T, 2) dsp.fRec3 = zeros(T, 2) dsp.iVec0 = zeros(Int32, 2) dsp.iRec1 = zeros(Int32, 2) dsp.ftbl0mydspSIG0 = zeros(T, 65536) dsp end end Note that the structure is parametrized with a {T} type to be given at initialization time. The const REAL = Float32 or const REAL = Float64 line is generated depending of the -single (default), or -double option given at compilation time, and can be used for that. Several access methods are generated: function getNumInputs(dsp::mydsp{T}) where {T} return Int32(0) end function getNumOutputs(dsp::mydsp{T}) where {T} return Int32(2) end Several initialiation methods like init! , initanceInit! , instanceResetUserInterface! etc. are generated, here is one of them: function instanceResetUserInterface!(dsp::mydsp{T}) where {T} dsp.fHslider0 = FAUSTFLOAT(0.0f0) dsp.fHslider1 = FAUSTFLOAT(1000.0f0) dsp.fHslider2 = FAUSTFLOAT(200.0f0) end The buildUserInterface! method uses a UI subtype to build a controller, which could be a Graphical User Interface (for instance using GTK ), or an OSC controller: function buildUserInterface!(dsp::mydsp{T}, ui_interface::UI) where {T} openVerticalBox!(ui_interface, \"Oscillator\") declare!(ui_interface, :fHslider1, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq1\", :fHslider1, FAUSTFLOAT(1000.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider2, \"unit\", \"Hz\") addHorizontalSlider!(ui_interface, \"freq2\", :fHslider2, FAUSTFLOAT(500.0f0), FAUSTFLOAT(20.0f0), FAUSTFLOAT(3000.0f0), FAUSTFLOAT(1.0f0)) declare!(ui_interface, :fHslider0, \"unit\", \"dB\") addHorizontalSlider!(ui_interface, \"volume\", :fHslider0, FAUSTFLOAT(0.0f0), FAUSTFLOAT(-96.0f0), FAUSTFLOAT(0.0f0), FAUSTFLOAT(0.1f0)) closeBox!(ui_interface) end The DSP structure fields to access are simply described with their name (actually a Symbol in Julia terminology), and can later be used with the standard setproperty! and getproperty access methods, like in the setParamValue! and getParamValue methods written in the MapUI architecture. And finally the compute! method that processes and input buffer with count frames to produce an output buffer: @inbounds function compute!(dsp::mydsp, count::Int32, inputs, outputs) output0 = @inbounds @view outputs[:, 1] output1 = @inbounds @view outputs[:, 2] fSlow0::Float32 = (dsp.fConst1 * pow(10.0f0, (0.0500000007f0 * Float32(dsp.fHslider0)))) fSlow1::Float32 = (dsp.fConst3 * Float32(dsp.fHslider1)) fSlow2::Float32 = (dsp.fConst3 * Float32(dsp.fHslider2)) @inbounds for i0 in 0:count-1 dsp.fRec0[1] = (fSlow0 + (dsp.fConst2 * dsp.fRec0[2])) dsp.fRec2[1] = (fSlow1 + (dsp.fRec2[2] - floor((fSlow1 + dsp.fRec2[2])))) output0[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec2[1]))+1])) dsp.fRec3[1] = (fSlow2 + (dsp.fRec3[2] - floor((fSlow2 + dsp.fRec3[2])))) output1[i0+1] = FAUSTFLOAT((dsp.fRec0[1] * dsp.ftbl0mydspSIG0[trunc(Int32, (65536.0f0 * dsp.fRec3[1]))+1])) dsp.fRec0[2] = dsp.fRec0[1] dsp.fRec2[2] = dsp.fRec2[1] dsp.fRec3[2] = dsp.fRec3[1] end end Note that not all generated methods are presented in this short presentation. Look at the generated osc.jl file to see all of them.","title":"Looking at the generated code"},{"location":"tutorials/julia/#using-the-generated-code","text":"Some globals have to be defined: # Testing samplerate = Int32(44100) block_size = Int32(16) The DSP object has to be created and initialized, here using the generated REAL type alias: # Init DSP my_dsp = mydsp{REAL}() init!(my_dsp, samplerate) His name can be extracted from the DSP metadata using the following code: # Retrieve the application name mutable struct NameMeta <: Meta name::String end function declare!(m::NameMeta, key::String, value::String) if (key == \"name\") m.name = value; end end) m = NameMeta(\"\") metadata!(my_dsp, m) println(\"Application name: \", m.name, \"\\n\") The number of inputs/outputs can be printed: println(\"getNumInputs: \", getNumInputs(my_dsp)) println(\"getNumOutputs: \", getNumOutputs(my_dsp), \"\\n\") Information on all controllers can be retrieved using the MapUI type: # Create a MapUI controller map_ui = MapUI(my_dsp) buildUserInterface!(my_dsp, map_ui) # Print all zones println(\"Path/UIZone dictionary: \", getZoneMap(map_ui), \"\\n\") And finally one buffer can be processed with the following code, here giving FAUSTFLOAT as the actual type for external samples: inputs = zeros(FAUSTFLOAT, block_size, getNumInputs(my_dsp)) outputs = zeros(FAUSTFLOAT, block_size, getNumOutputs(my_dsp)) compute!(my_dsp, block_size, inputs, outputs) println(\"One computed output buffer: \", outputs) Now the osc.jl can possibly be directly integrated in a larger project, or customized using an adapted new architecture file.","title":"Using the generated code"},{"location":"tutorials/julia/#the-faust2portaudiojulia-tool","text":"The Faust DSP program can be compiled and run with the more sophisticated faust2portaudiojulia tool which will render it using the PortAudio.jl package to access the audio driver, OpenSoundControl.jl package for OSC control, and GTK.jl package for the Graphical User Interface. The faust2portaudiojulia tool use this portaudio_gtk.jl architecture file. When used the following way: faust2portaudiojulia osc.dsp It creates an osc.jl file that can simply be executed using: julia osc.jl So the stereo program generating sinewaves at 1000 Hz and 200 Hz by default is now playing, without any interface to control it. Now using the following command: faust2portaudiojulia -play 2 osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and GTK GUI (and with 2 threads needed for GTK and audio). Note that the GUI is still quite simple: The GTK based controller The following command: faust2portaudiojulia -play 2 -osc osc.dsp Will create the osc.jl file, directly execute it using Julia , with PortAudio based audio rendering and OSC control (and with 2 threads needed for OSC and audio). Now the application starts with an OSC controller running on ports 5000 and 5001: getNumInputs: 0 getNumOutputs: 2 Dict{String, UIZone}(\"/Oscillator/volume\" => UIZone(:fHslider0, 0.0f0, -96.0f0, 0.0f0, 0.1f0), \"/Oscillator/freq2\" => UIZone(:fHslider2, 500.0f0, 20.0f0, 3000.0f0, 1.0f0), \"/Oscillator/freq1\" => UIZone(:fHslider1, 1000.0f0, 20.0f0, 3000.0f0, 1.0f0)) Faust OSC application 'Oscillator' is running on UDP ports 5000, 5001 Direct OSC commands can be sent, as explained here . So for instance to change both channel frequencies: oscsend localhost 5000 /Oscillator/freq1 f 400 oscsend localhost 5000 /Oscillator/freq2 f 960 You can possibly use the faust-osc-controller tool to remotely control the Julia program, with the following command: faust-osc-controller /Oscillator -port 5001 -outport 5000 -xmit 1 The faust-osc-controller OSC controller And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the faust2portaudiojulia -play 2 -oscc osc.dsp command.","title":"The faust2portaudiojulia tool"},{"location":"tutorials/julia/#using-the-faust-web-ide","text":"Faust DSP program can be written, tested in the Faust Web IDE and generated as embeddable Julia code, or possibly as working audio applications.","title":"Using the Faust Web IDE"},{"location":"tutorials/julia/#generating-the-pure-julia-output","text":"The output of the Julia backend can directly be generated using the Platform = source and Architecture = julia export options. As previously explained, the resulting file is not self-contained, but shows the code which has to be wrapped with adapted Julia architecture files. Exporting the code","title":"Generating the pure Julia output"},{"location":"tutorials/julia/#generating-a-minimal-working-julia-file","text":"The Platform = julia and Architecture = julia export options allow to generate a self-contained file using the minimal.jl architecture, to be by started with the following command: julia -i foo.jl (here -i to stay in interactive mode)","title":"Generating a minimal working Julia file"},{"location":"tutorials/julia/#generating-an-audio-application-controllable-with-gtk-or-osc-based-interfaces","text":"The Platform = julia and Architecture = portaudiojulia export options allow to generate a self-contained file using the portaudio_gtk.jl architecture. The following command starts the program with the GTK control interface: julia -t 2 foo.jl -gtk The following command starts the program with the OSC control interface, ready to receive OSC commands or controlled with the faust-osc-controller tool as previously explained: julia -t 2 foo.jl -osc And finally the faust-osc-controller tool can be automatically started along the OSC receiver with the following command: julia -t 2 foo.jl -oscc","title":"Generating an audio application controllable with GTK or OSC based interfaces"},{"location":"tutorials/julia/#using-the-faustjl-julia-package","text":"The Julia ecosystem contains over 4,000 packages that are registered in the General registry . A Faust.lj package initially developed by Cora Johnson-Roberson , has been forked and extended here . It allows the use of the libfaust library and the Julia Faust backend. The Visual Studio Code application can be configurated with a Julia extension . It is a very convenient way to edit, compile and test Julia + Faust code.","title":"Using the Faust.jl Julia package"},{"location":"tutorials/julia/#installing-the-forked-faustjl-package","text":"In VS Code, you can enter the package mode . Pkg comes with a REPL. Enter the Pkg REPL by pressing ] from the Julia REPL and install the Faust package with: pkg> add https://github.com/sletz/Faust.jl To get back to the Julia REPL, press backspace or ^C, then load the Faust package with: julia> using Faust Assuming a working Julia environment is setup, the following commands can be used.","title":"Installing the forked Faust.jl package"},{"location":"tutorials/julia/#using-the-libfaust-compiler","text":"# Create a DSP factory. dsp = compile(\"\"\" import(\"stdfaust.lib\"); freq = hslider(\"freq\", 440, 20, 20000, 1); gain = hslider(\"gain\", 0.25, 0, 1, 0.001); process = os.oscs(freq) * gain; \"\"\") # Initialize DSP instance and controls. init!(dsp; block_size=1024, samplerate=48000) # Compute one block of audio. compute!(dsp) By default, programs are compiled as single-precision; you can give -double or other arguments to the compiler like so: compile(\"process = _;\"; name=\"passthrough\", argv=[\"-double\", \"-vec\"]) Each call to compute! will calculate block_size samples and return the output as a matrix of (block_size, n_channels). If the program takes input, set dsp.inputs to a (block_size, n_channels) matrix before calling compute! : passthrough = init!(compile(\"process = _,_;\")) x = rand(Float32, 256, 2) passthrough.inputs = x @test compute!(passthrough) == x After calling init! , any UI elements declared in your code will have their path names and ranges available via dsp.ui.ranges . julia> dsp.ui.ranges Dict{String, Faust.UIRange} with 2 entries: \"/score/gain\" => UIRange(0.25, 0.0, 1.0, 0.001) \"/score/freq\" => UIRange(440.0, 20.0, 20000.0, 1.0) julia> ctrl = dsp.ui.ranges[\"/score/freq\"]; (ctrl.min, ctrl.max) (20.0f0, 20000.0f0) One can then set the values of these params like: setparams!(dsp, Dict(\"/score/freq\" => 220.0f0))","title":"Using the libfaust compiler"},{"location":"tutorials/julia/#displaying-signals","text":"Julia offers a lot of packages to display signals, for example with the following commands ( coded here ) to display the outputs buffers: # Define a block of DSP code julia> code = \"\"\"import(\"stdfaust.lib\"); process = os.osc(500), os.sawtooth(1000);\"\"\" # Compile the DSP, compute one block of audio and display the outputs julia> compileFaustString(code) # Compile the DSP, with additional compiler arguments and display the outputs julia> compileFaustString(code; argv=[\"-double\", \"-vec\"]) # Compile the DSP, with a larger block_size and display the outputs julia> compileFaustString(code; block_size=50000) With the following result in VS code: Using Julia in VS code More sophisticated analysis can be done, like this example , or this projet to experiment using NNs in Faust .","title":"Displaying signals"},{"location":"tutorials/rnbo/","text":"Using Faust in RNBO with codebox~ In this tutorial, we present how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DSP programs can be compiled to the internal codebox~ sample level scripting language. Compiling Faust DSP to codebox~ code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net. Who is this tutorial for? The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for RNBO users who want to discover Faust. Using command line tools Generating codebox~ code Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The codebox~ code can be generated using the following line (note the use of -double option, the default sample format in RNBO/codebox~): faust -lang codebox -double osc.dsp -o osc.codebox This will generate a series of functions to init, update parameters and compute audio frames. Looking at the generated code The generated code contains a sequence of parameters definitions with their min, max, step and default values: // Params @param({min: 2e+01, max: 3e+03, step: 0.1}) freq1 = 1e+03; @param({min: 2e+01, max: 3e+03, step: 0.1}) freq2 = 2e+02; @param({min: -96.0, max: 0.0, step: 0.1}) volume = 0.0; Next the declaration of the DSP structure using the @state decorator, creating a state that persists across the lifetime of the codebox object. Scalar and arrays with the proper type are created: // Fields @state fSampleRate_cb : Int = 0; @state fConst1_cb : number = 0; @state fHslider0_cb : number = 0; @state fConst2_cb : number = 0; @state iVec0_cb = new FixedIntArray(2); @state fRec0_cb = new FixedDoubleArray(2); @state fConst3_cb : number = 0; @state fHslider1_cb : number = 0; @state fRec2_cb = new FixedDoubleArray(2); @state fHslider2_cb : number = 0; @state fRec3_cb = new FixedDoubleArray(2); @state iVec1_cb = new FixedIntArray(2); @state iRec1_cb = new FixedIntArray(2); @state ftbl0mydspSIG0_cb = new FixedDoubleArray(65536); @state fUpdated : Int = 0; @state fControl_cb = new FixedDoubleArray(3); Next the DSP init code, which is added in dspsetup , only available in codebox~ where it will be called each time audio is turned on in Max (which is basically every time the audio state is toggled, or the sample rate or vector size is changed). Here the DSP state is initialized using the RNBO current sample rate: // Init function dspsetup() { fUpdated = true; for (let l2_re0_cb : Int = 0; (l2_re0_cb < 2); l2_re0_cb = (l2_re0_cb + 1)) { iVec1_cb[l2_re0_cb] = 0; } for (let l3_re0_cb : Int = 0; (l3_re0_cb < 2); l3_re0_cb = (l3_re0_cb + 1)) { iRec1_cb[l3_re0_cb] = 0; } for (let i1_re0_cb : Int = 0; (i1_re0_cb < 65536); i1_re0_cb = (i1_re0_cb + 1)) { iVec1_cb[0] = 1; iRec1_cb[0] = ((iVec1_cb[1] + iRec1_cb[1]) % 65536); ftbl0mydspSIG0_cb[i1_re0_cb] = sin((9.587379924285257e-05 * iRec1_cb[0])); iVec1_cb[1] = iVec1_cb[0]; iRec1_cb[1] = iRec1_cb[0]; } fHslider0_cb = 0.0; fHslider1_cb = 1e+03; fHslider2_cb = 2e+02; ... ... fSampleRate_cb = samplerate(); let fConst0_cb : number = min(1.92e+05, max(1.0, fSampleRate_cb)); fConst1_cb = (44.1 / fConst0_cb); fConst2_cb = (1.0 - fConst1_cb); fConst3_cb = (1.0 / fConst0_cb); } Parameters handling is separated in two functions: control is called each time a parameter has changed: // Control function control() { fControl_cb[0] = (fConst1_cb * pow(1e+01, (0.05 * fHslider0_cb))); fControl_cb[1] = (fConst3_cb * fHslider1_cb); fControl_cb[2] = (fConst3_cb * fHslider2_cb); } And the actual change is triggered when at least one parameter has changed, controlled by the state of fUpdated global variable: // Update parameters function update(freq1,freq2,volume) { fUpdated = int(fUpdated) | (freq1 != fHslider1_cb); fHslider1_cb = freq1; fUpdated = int(fUpdated) | (freq2 != fHslider2_cb); fHslider2_cb = freq2; fUpdated = int(fUpdated) | (volume != fHslider0_cb); fHslider0_cb = volume; if (fUpdated) { fUpdated = false; control(); } } Finally compute process the audio inputs and produces audio outputs: // Update parameters / Compute one frame function compute() { iVec0_cb[0] = 1; fRec0_cb[0] = (fControl_cb[0] + (fConst2_cb * fRec0_cb[1])); let iTemp0_cb : Int = (1 - iVec0_cb[1]); let fTemp1_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[1] + fRec2_cb[1])); fRec2_cb[0] = (fTemp1_cb - floor(fTemp1_cb)); output0_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec2_cb[0])), 65535))]); let fTemp2_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[2] + fRec3_cb[1])); fRec3_cb[0] = (fTemp2_cb - floor(fTemp2_cb)); output1_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec3_cb[0])), 65535))]); iVec0_cb[1] = iVec0_cb[0]; fRec0_cb[1] = fRec0_cb[0]; fRec2_cb[1] = fRec2_cb[0]; fRec3_cb[1] = fRec3_cb[0]; return [output0_cb,output1_cb]; } With this code in place, the following sequence of operations is done at each sample: // Update parameters update(freq1,freq2,volume); // Compute one frame outputs = compute(); // Write the outputs out1 = outputs[0]; out2 = outputs[1]; Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is done in compute . Testing the generated codebox~ code To be tested, the generated code has to be pasted in a codebox~ component in an encompassing RNBO patch, with additional patching to add the needed audio inputs/outputs and control parameters. Thus a more integrated and simpler model is to use the faust2rnbo tool. Using the faust2rnbo tool The faust2rnbo tool transforms a Faust DSP program into a RNBO patch containing a rnbo~ object and including the codebox code (generated using the codebox backend ) as a subpatch. Needed audio inputs/outputs and parameters (with the proper name, default, min and max values) are automatically added in the patch. Additional options allow to generate a special version of the RNBO patch used in the testing infrastructure. The code is written in Python and uses the very powerful py2max library to generate the maxpat JSON format. faust2rnbo -h Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file (and possibly file_effect.rnbopat) -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. The resulting patch contains: an audio adc~ input automatically connected to the rnbo~ object (when the DSP has audio inputs) an audio dac~ output automatically connected with the rnbo~ object. So the following command: faust2rnbo osc.dsp will directly compile the osc.dsp file and generate the osc.maxpat file, that can be opened in Max/MSP, with the following user-interface: Generated RNBO patch and with the rnbo~ subpatcher containing the codebox object as well as the parameter control machinery: rnbo~ subpatcher with parameter control machinery (after manual editing) Note that the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other contexts as explained on this page . So faust2rnbo -sp osc.dsp will create both osc.maxpat and osc.rnbopat files. In this case the main patch uses the patchername/paramname parameter naming convention: Generated RNBO patch in -sp mode and the subpatcher contains a p object to load and use the osc.rnbopat file: rnbo~ subpatcher with parameter control machinery in p mode Bargraph handling In Faust, bargraph are typically used to analyze audio signals where computed values are sent at control rate. This cannot be directly done in the RNBO model where only audio signals can be sent from the codebox code. So additional audio outputs are created for bargraph, and will be sampled (using snapshot~ and change ) and be connected to param objects, like input controllers. So for instance the following example: compiled with faust2rnbo will create a subpatcher with 2 audio inputs and 4 audio outputs (2 real ones and 2 used for bargraph), and the user-interface: rnbo~ subpatcher with additional audio outputs for bargraph and the main patch with parameters displaying the bargraph values: RNBO main patch displaying bargraph values MIDI control Control of parameters with MIDI can be activated using the -midi option, or using the declare options \"[midi:on]\"; syntax in the DSP code. The patch will then contain midiin/midiout objects at global level and specialized ctlin/notein etc. objects in the codebox subpatcher with the appropriate scale object to map the MIDI message range on the target parameter range. So for instance the MIDI augmented example: can now be controlled with MIDI volume (ctrl 7), ctrl 1 and ctrl 2 for each channel frequency. Modification done on the parameters in the GUI will be sent as MIDI output messages. And the following command: faust2rnbo -midi osc.dsp will compile a osc.maxpat file containing additional midiin/midiout objects, with the following user-interface: Generated RNBO patch with MIDI control Polyphonic instruments When the DSP follows the polyphonic ready instrument convention, it can be activated in MIDI controllable polyphonic mode. So the following DSP program: compiled with the command: faust2rnbo -midi -nvoices 12 organ.dsp will create a patch containing a rnbo~ object with 12 voices, and with a notein object added in the subpatcher correctly connected to the appropriate freq/gain/gate aware parameters. Additional mapping depending of the convention used to describe the pitch (freq or key) or gain (gain or velocity) will be added when needed, with the generated user-interface: Generated polyphonic RNBO patch with MIDI control In the DSP, note that the master slider can be controlled using the crl 7 (= Volume) MIDI message. Note that here again, the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other context. Polyphonic instruments with an effect The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a polyphonic MIDI ready patch: To be compiled with the following: faust2rnbo -midi -nvoices 16 -effect auto organ2.dsp with the generated user-interface and the polyphonic DSP rnbo~ object, using the p abstraction model to load and activate the polyphonic instrument (as a organ2.rnbopat file), connected to the global effect (as a organ2_effect.rnbopat file). Having a single rnbo~ object with the two embedded subpachers is mandatory to properly create the exported project: Generated polyphonic RNBO patch with MIDI control and the rnbo~ subpather: rnbo~ subpatcher with the polyphonic instrument and global effect as p abstractions Using the Faust Web IDE Faust DSP programs can be written, tested in the Faust Web IDE and generated as RNBO patches. Generating a RNBO patch The output as a RNBO patch can directly be generated using the Platform = rnbo and Architecture = rnbo export options. The resulting foo folder is self-contained, containing the foo.maxpat file.to be opened with Max/MSP. Exporting the code Generating the RNBO patch in polyphonic mode DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = rnbo and Architecture = rnbo-poly export options. The resulting foo folder is self-contained, containing the foo.maxpat file to be opened with Max/MSP. Generating the RNBO patch in polyphonic mode with a global effect DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = rnbo and Architecture = rnbo-poly-effect export options. The resulting foo folder is self-contained, containing the foo.maxpat , foo.rnbopat and foo_effect.rnbopat files (using the p abstraction model), with foo.maxpat file to be opened with Max/MSP. Generating the RNBO patch from a Faust DSP program found in the web Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a RNBO patch as already showed. examples of the faustplayground platform can be found here and possibly converted.","title":"Using Faust in RNBO with codebox~"},{"location":"tutorials/rnbo/#using-faust-in-rnbo-with-codebox","text":"In this tutorial, we present how Faust can be used with RNBO , a library and toolchain that can take Max-like patches, export them as portable code, and directly compile that code to targets like a VST, a Max External, or a Raspberry Pi. DSP programs can be compiled to the internal codebox~ sample level scripting language. Compiling Faust DSP to codebox~ code will allow to take profit of hundreds of DSP building blocks implemented in the Faust Libraries , ready to use Examples , any DSP program developed in more than 200 projects listed in the Powered By Faust page, or Faust DSP programs found on the net.","title":"Using Faust in RNBO with codebox~"},{"location":"tutorials/rnbo/#who-is-this-tutorial-for","text":"The first section assumes a working Faust compiler installed on the machine, so is more designed for regular Faust users. The second section is better suited for RNBO users who want to discover Faust.","title":"Who is this tutorial for?"},{"location":"tutorials/rnbo/#using-command-line-tools","text":"","title":"Using command line tools"},{"location":"tutorials/rnbo/#generating-codebox-code","text":"Assuming you've installed the faust compiler , starting from the following DSP osc.dsp program: The codebox~ code can be generated using the following line (note the use of -double option, the default sample format in RNBO/codebox~): faust -lang codebox -double osc.dsp -o osc.codebox This will generate a series of functions to init, update parameters and compute audio frames.","title":"Generating codebox~ code"},{"location":"tutorials/rnbo/#looking-at-the-generated-code","text":"The generated code contains a sequence of parameters definitions with their min, max, step and default values: // Params @param({min: 2e+01, max: 3e+03, step: 0.1}) freq1 = 1e+03; @param({min: 2e+01, max: 3e+03, step: 0.1}) freq2 = 2e+02; @param({min: -96.0, max: 0.0, step: 0.1}) volume = 0.0; Next the declaration of the DSP structure using the @state decorator, creating a state that persists across the lifetime of the codebox object. Scalar and arrays with the proper type are created: // Fields @state fSampleRate_cb : Int = 0; @state fConst1_cb : number = 0; @state fHslider0_cb : number = 0; @state fConst2_cb : number = 0; @state iVec0_cb = new FixedIntArray(2); @state fRec0_cb = new FixedDoubleArray(2); @state fConst3_cb : number = 0; @state fHslider1_cb : number = 0; @state fRec2_cb = new FixedDoubleArray(2); @state fHslider2_cb : number = 0; @state fRec3_cb = new FixedDoubleArray(2); @state iVec1_cb = new FixedIntArray(2); @state iRec1_cb = new FixedIntArray(2); @state ftbl0mydspSIG0_cb = new FixedDoubleArray(65536); @state fUpdated : Int = 0; @state fControl_cb = new FixedDoubleArray(3); Next the DSP init code, which is added in dspsetup , only available in codebox~ where it will be called each time audio is turned on in Max (which is basically every time the audio state is toggled, or the sample rate or vector size is changed). Here the DSP state is initialized using the RNBO current sample rate: // Init function dspsetup() { fUpdated = true; for (let l2_re0_cb : Int = 0; (l2_re0_cb < 2); l2_re0_cb = (l2_re0_cb + 1)) { iVec1_cb[l2_re0_cb] = 0; } for (let l3_re0_cb : Int = 0; (l3_re0_cb < 2); l3_re0_cb = (l3_re0_cb + 1)) { iRec1_cb[l3_re0_cb] = 0; } for (let i1_re0_cb : Int = 0; (i1_re0_cb < 65536); i1_re0_cb = (i1_re0_cb + 1)) { iVec1_cb[0] = 1; iRec1_cb[0] = ((iVec1_cb[1] + iRec1_cb[1]) % 65536); ftbl0mydspSIG0_cb[i1_re0_cb] = sin((9.587379924285257e-05 * iRec1_cb[0])); iVec1_cb[1] = iVec1_cb[0]; iRec1_cb[1] = iRec1_cb[0]; } fHslider0_cb = 0.0; fHslider1_cb = 1e+03; fHslider2_cb = 2e+02; ... ... fSampleRate_cb = samplerate(); let fConst0_cb : number = min(1.92e+05, max(1.0, fSampleRate_cb)); fConst1_cb = (44.1 / fConst0_cb); fConst2_cb = (1.0 - fConst1_cb); fConst3_cb = (1.0 / fConst0_cb); } Parameters handling is separated in two functions: control is called each time a parameter has changed: // Control function control() { fControl_cb[0] = (fConst1_cb * pow(1e+01, (0.05 * fHslider0_cb))); fControl_cb[1] = (fConst3_cb * fHslider1_cb); fControl_cb[2] = (fConst3_cb * fHslider2_cb); } And the actual change is triggered when at least one parameter has changed, controlled by the state of fUpdated global variable: // Update parameters function update(freq1,freq2,volume) { fUpdated = int(fUpdated) | (freq1 != fHslider1_cb); fHslider1_cb = freq1; fUpdated = int(fUpdated) | (freq2 != fHslider2_cb); fHslider2_cb = freq2; fUpdated = int(fUpdated) | (volume != fHslider0_cb); fHslider0_cb = volume; if (fUpdated) { fUpdated = false; control(); } } Finally compute process the audio inputs and produces audio outputs: // Update parameters / Compute one frame function compute() { iVec0_cb[0] = 1; fRec0_cb[0] = (fControl_cb[0] + (fConst2_cb * fRec0_cb[1])); let iTemp0_cb : Int = (1 - iVec0_cb[1]); let fTemp1_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[1] + fRec2_cb[1])); fRec2_cb[0] = (fTemp1_cb - floor(fTemp1_cb)); output0_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec2_cb[0])), 65535))]); let fTemp2_cb : number = ((iTemp0_cb) ? 0.0 : (fControl_cb[2] + fRec3_cb[1])); fRec3_cb[0] = (fTemp2_cb - floor(fTemp2_cb)); output1_cb = (fRec0_cb[0] * ftbl0mydspSIG0_cb[max(0, min(int((65536.0 * fRec3_cb[0])), 65535))]); iVec0_cb[1] = iVec0_cb[0]; fRec0_cb[1] = fRec0_cb[0]; fRec2_cb[1] = fRec2_cb[0]; fRec3_cb[1] = fRec3_cb[0]; return [output0_cb,output1_cb]; } With this code in place, the following sequence of operations is done at each sample: // Update parameters update(freq1,freq2,volume); // Compute one frame outputs = compute(); // Write the outputs out1 = outputs[0]; out2 = outputs[1]; Note that the generated code uses the so-called scalar code generation model , the default one, where the compiled sample generation code is done in compute .","title":"Looking at the generated code"},{"location":"tutorials/rnbo/#testing-the-generated-codebox-code","text":"To be tested, the generated code has to be pasted in a codebox~ component in an encompassing RNBO patch, with additional patching to add the needed audio inputs/outputs and control parameters. Thus a more integrated and simpler model is to use the faust2rnbo tool.","title":"Testing the generated codebox~ code"},{"location":"tutorials/rnbo/#using-the-faust2rnbo-tool","text":"The faust2rnbo tool transforms a Faust DSP program into a RNBO patch containing a rnbo~ object and including the codebox code (generated using the codebox backend ) as a subpatch. Needed audio inputs/outputs and parameters (with the proper name, default, min and max values) are automatically added in the patch. Additional options allow to generate a special version of the RNBO patch used in the testing infrastructure. The code is written in Python and uses the very powerful py2max library to generate the maxpat JSON format. faust2rnbo -h Usage: faust2rnbo [options] [Faust options] <file.dsp> Compiles Faust programs to RNBO patches Options: -midi : activates MIDI control -nvoices <num> : produces a polyphonic DSP with <num> voices, ready to be used with MIDI events -effect <effect.dsp> : generates a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC -effect auto : generates a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC -compile : to trigger C++ compilation at load time -test : to generate special 'RB_XX' prefix for parameters (for testing) -sp : to generate codebox subpatcher as a file.rnbopat file (and possibly file_effect.rnbopat) -cpp_path <path> : to set C++ export folder -cpp_filename <filename> : to set C++ export filename Faust options : any option (e.g. -vec -vs 8...). See the Faust compiler documentation. The resulting patch contains: an audio adc~ input automatically connected to the rnbo~ object (when the DSP has audio inputs) an audio dac~ output automatically connected with the rnbo~ object. So the following command: faust2rnbo osc.dsp will directly compile the osc.dsp file and generate the osc.maxpat file, that can be opened in Max/MSP, with the following user-interface: Generated RNBO patch and with the rnbo~ subpatcher containing the codebox object as well as the parameter control machinery: rnbo~ subpatcher with parameter control machinery (after manual editing) Note that the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other contexts as explained on this page . So faust2rnbo -sp osc.dsp will create both osc.maxpat and osc.rnbopat files. In this case the main patch uses the patchername/paramname parameter naming convention: Generated RNBO patch in -sp mode and the subpatcher contains a p object to load and use the osc.rnbopat file: rnbo~ subpatcher with parameter control machinery in p mode","title":"Using the faust2rnbo tool"},{"location":"tutorials/rnbo/#bargraph-handling","text":"In Faust, bargraph are typically used to analyze audio signals where computed values are sent at control rate. This cannot be directly done in the RNBO model where only audio signals can be sent from the codebox code. So additional audio outputs are created for bargraph, and will be sampled (using snapshot~ and change ) and be connected to param objects, like input controllers. So for instance the following example: compiled with faust2rnbo will create a subpatcher with 2 audio inputs and 4 audio outputs (2 real ones and 2 used for bargraph), and the user-interface: rnbo~ subpatcher with additional audio outputs for bargraph and the main patch with parameters displaying the bargraph values: RNBO main patch displaying bargraph values","title":"Bargraph handling"},{"location":"tutorials/rnbo/#midi-control","text":"Control of parameters with MIDI can be activated using the -midi option, or using the declare options \"[midi:on]\"; syntax in the DSP code. The patch will then contain midiin/midiout objects at global level and specialized ctlin/notein etc. objects in the codebox subpatcher with the appropriate scale object to map the MIDI message range on the target parameter range. So for instance the MIDI augmented example: can now be controlled with MIDI volume (ctrl 7), ctrl 1 and ctrl 2 for each channel frequency. Modification done on the parameters in the GUI will be sent as MIDI output messages. And the following command: faust2rnbo -midi osc.dsp will compile a osc.maxpat file containing additional midiin/midiout objects, with the following user-interface: Generated RNBO patch with MIDI control","title":"MIDI control"},{"location":"tutorials/rnbo/#polyphonic-instruments","text":"When the DSP follows the polyphonic ready instrument convention, it can be activated in MIDI controllable polyphonic mode. So the following DSP program: compiled with the command: faust2rnbo -midi -nvoices 12 organ.dsp will create a patch containing a rnbo~ object with 12 voices, and with a notein object added in the subpatcher correctly connected to the appropriate freq/gain/gate aware parameters. Additional mapping depending of the convention used to describe the pitch (freq or key) or gain (gain or velocity) will be added when needed, with the generated user-interface: Generated polyphonic RNBO patch with MIDI control In the DSP, note that the master slider can be controlled using the crl 7 (= Volume) MIDI message. Note that here again, the rnbo~ object subpatcher can be generated using the -sp option and possibly used in other context.","title":"Polyphonic instruments"},{"location":"tutorials/rnbo/#polyphonic-instruments-with-an-effect","text":"The following polyphonic ready instrument DSP, with an integrated effect , can be converted to a polyphonic MIDI ready patch: To be compiled with the following: faust2rnbo -midi -nvoices 16 -effect auto organ2.dsp with the generated user-interface and the polyphonic DSP rnbo~ object, using the p abstraction model to load and activate the polyphonic instrument (as a organ2.rnbopat file), connected to the global effect (as a organ2_effect.rnbopat file). Having a single rnbo~ object with the two embedded subpachers is mandatory to properly create the exported project: Generated polyphonic RNBO patch with MIDI control and the rnbo~ subpather: rnbo~ subpatcher with the polyphonic instrument and global effect as p abstractions","title":"Polyphonic instruments with an effect"},{"location":"tutorials/rnbo/#using-the-faust-web-ide","text":"Faust DSP programs can be written, tested in the Faust Web IDE and generated as RNBO patches.","title":"Using the Faust Web IDE"},{"location":"tutorials/rnbo/#generating-a-rnbo-patch","text":"The output as a RNBO patch can directly be generated using the Platform = rnbo and Architecture = rnbo export options. The resulting foo folder is self-contained, containing the foo.maxpat file.to be opened with Max/MSP. Exporting the code","title":"Generating a RNBO patch"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-in-polyphonic-mode","text":"DSP programs following the polyphonic freq/gate/gain convention can be generated using the Platform = rnbo and Architecture = rnbo-poly export options. The resulting foo folder is self-contained, containing the foo.maxpat file to be opened with Max/MSP.","title":"Generating the RNBO patch in polyphonic mode"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-in-polyphonic-mode-with-a-global-effect","text":"DSP programs following the polyphonic freq/gate/gain convention with and an integrated effect can be generated using the Platform = rnbo and Architecture = rnbo-poly-effect export options. The resulting foo folder is self-contained, containing the foo.maxpat , foo.rnbopat and foo_effect.rnbopat files (using the p abstraction model), with foo.maxpat file to be opened with Max/MSP.","title":"Generating the RNBO patch in polyphonic mode with a global effect"},{"location":"tutorials/rnbo/#generating-the-rnbo-patch-from-a-faust-dsp-program-found-in-the-web","text":"Faust DSP programs found on the Web can also be converted: for instance the fverb listed on the Powered By Faust page. The DSP content can simply be loaded using the https://faustide.grame.fr/?code=URL syntax, so with the following URL: https://faustide.grame.fr/?code=https://raw.githubusercontent.com/jpcima/fverb/master/fverb.dsp , tested in the Faust Web IDE, then converted in a RNBO patch as already showed. examples of the faustplayground platform can be found here and possibly converted.","title":"Generating the RNBO patch from a Faust DSP program found in the web"},{"location":"tutorials/signal-api/","text":"Using the signal API The signal API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the signal API, and take profit of part of the Faust compiler infrastructure. Faust compiler structure The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated in a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends. Accessing the signal stage A new intermediate public entry point has been created in the Semantic Phase to allow the creation of a signal set (as a list of output signals), then beneficiate of all remaining parts of the compilation chain. The signal API (or the C signal API version) allows to programmatically create the list of output signals, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the box API allows to access another stage in the compilation stage. Compiling signal expressions To use the signal API, the following steps must be taken: creating a global compilation context using the createLibContext function creating signals outputs using the signal API, progressively building more complex expressions by combining simpler ones compiling the list of outputs using the createCPPDSPFactoryFromSignals function to create a DSP factory (or createDSPFactoryFromSignals to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromSignals to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used. Tools Let's first define a compile function, which uses the createCPPDSPFactoryFromSignals function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromSignals(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\ Examples For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps) and clearly shows how each output signal expression has to be created. All presented C++ examples (as well as some more) are defined in the signal-tester tool, to be compiled with make signal-tester in the tools/benchmark folder. Simple constant signal Let's create a program generating the 0.5 constant value. Here is the Faust DSP code: The following code creates a vector of output signals (with the tvec type), containing the single sigReal(0.5) signal, then compile it and display the C++ class: static void test1() { COMPILER ( tvec signals; signals.push_back(sigReal(0.5)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(0.5f); } } Doing some mathematical operations on an input signal Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with sigInput(0) signal, then transformed using sigAdd and sigMul signal operators to produce two outputs: static void test2() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(in1, sigReal(0.5))); signals.push_back(sigMul(in1, sigReal(1.5))); compile(\"test2\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); output0[i0] = FAUSTFLOAT((fTemp0 + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fTemp0)); } } Note that accessing input N is simply done using the sigInput(N) expression. Defining delayed signals Here is a simple program using a signal input and doing mathematical operations on it, then delaying the signals: The sigDelay(x, y) operator is used to delay the x first parameter with the second y parameter, here with constant values: static void test3() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); compile(\"test3\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; fVec1[(IOTA & 511)] = (fTemp0 + 0.5f); output0[i0] = FAUSTFLOAT(fVec1[((IOTA - 500) & 511)]); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code show how to compile in vector mode: static void test5() { createLibContext(); tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); // Vector compilation compile(\"test5\", signals, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; FAUSTFLOAT* output1_ptr = outputs[1]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; FAUSTFLOAT* output1 = &output1_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ fYec0_idx = ((fYec0_idx + fYec0_idx_save) & 4095); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[((i + fYec0_idx) & 4095)] = float(input0[i]); } /* Post code */ fYec0_idx_save = vsize; /* Vectorizable loop 1 */ /* Pre code */ fYec1_idx = ((fYec1_idx + fYec1_idx_save) & 1023); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec1[((i + fYec1_idx) & 1023)] = (float(input0[i]) + 0.5f); } /* Post code */ fYec1_idx_save = vsize; /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec1[(((i + fYec1_idx) - 500) & 1023)]); } /* Vectorizable loop 3 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output1[i] = FAUSTFLOAT((1.5f * fYec0[(((i + fYec0_idx) - 3000) & 4095)])); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test4() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(sigDelay(in1, sigInt(500)), sigReal(0.5))); signals.push_back(sigMul(sigDelay(in1, sigInt(3000)), sigReal(1.5))); compile(\"test4\", signals); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Equivalent signal expressions It is really important to note that syntactically equivalent signal expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( tvec signals; Signal s1 = sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) signals.push_back(s1); signals.push_back(s1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( tvec signals; signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); compile(\"equivalent2\", signals); ) } It can be a property to remember when creating a DSL on top of the signal API. Using User Interface items User Interface items can be used, as in the following example, with a vslider : Built with the following code: static void test8() { COMPILER ( tvec signals; Signal in1 = sigInput(0); Signal s = sigVSlider(\"Vol\", sigReal(0.5), sigReal(0.), sigReal(1.), sigReal(0.01)); signals.push_back(sigMul(s, sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500)))); compile(\"test8\", signals); ) } The buildUserInterface method is generated, using the fVslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->addVerticalSlider(\"Vol\", &fVslider0, FAUSTFLOAT(0.5f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.00999999978f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fVslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[(IOTA & 511)] = (float(input0[i0]) + 0.5f); output0[i0] = FAUSTFLOAT((fSlow0 * fVec0[((IOTA - 500) & 511)])); IOTA = (IOTA + 1); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the signal API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( tvec signals; Signal freq = sigVSlider(\"h:Oscillator/freq\", sigReal(440), sigReal(50), sigReal(1000), sigReal(0.1)); Signal gain = sigVSlider(\"h:Oscillator/gain\", sigReal(0), sigReal(0), sigReal(1), sigReal(0.011)); signals.push_back(sigMul(freq, sigMul(gain, sigInput(0)))); compile(\"test9\", signals); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); } Defining recursive signals Recursive signals can be defined using the sigRecursion function to build the recursion, and the sigSelf function to refer to the recursive signal itself. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursion(sigAdd(sigSelf(), in1))); compile(\"test10\", signals); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } The same equivalent code can be defined using the more general sigRecursionN and sigSelfN functions which allow to build a list of (possibly mutually dependent) recursive signals: static void test10bis() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursionN(sigAdd(sigSelfN(0), in1))); compile(\"test10\", signals); ) } Here is an example of the definition of mutually dependent recursive signals: static void test10ter() { COMPILER ( Signal in0 = sigInput(0); Signal in1 = sigInput(1); tvec ins; ins.push_back(sigAdd(sigMul(sigSelfN(1), sigReal(0.5)), in0)); ins.push_back(sigAdd(sigMul(sigSelfN(0), sigReal(0.9)), in1)); tvec outs = sigRecursionN(ins); compile(\"test10ter\", outs); ) } With the following compute method: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = float(input0[i0]) + 0.5f * fRec1[1]; fRec1[0] = float(input1[i0]) + 0.9f * fRec0[1]; output0[i0] = FAUSTFLOAT(fRec0[0]); output1[i0] = FAUSTFLOAT(fRec1[0]); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } } Accessing the global context In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the signal language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Signal SR() { return sigMin(sigReal(192000.0), sigMax(sigReal(1.0), sigFConst(SType::kSInt, \"fSampleFreq\", \"<dummy.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return sigFVar(SType::kSInt, \"count\", \"<dummy.h>\"); } So the following DSP program: Can be written at the signal API level with: static void test11() { COMPILER ( tvec signals; signals.push_back(SR()); signals.push_back(BS()); compile(\"test11\", signals); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } } Creating tables Read only and read/write tables can be created. The read only table signal is created with sigReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigReadOnlyTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)))); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with sigWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigWriteReadTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)), sigIntCast(sigInput(1)), sigIntCast(sigInput(2)))); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } } Creating waveforms The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with sigWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(sigReal(100*i)); } tvec signals; signals.push_back(sigInt(waveform.size())); // the waveform size signals.push_back(sigWaveform(waveform)); // the waveform content compile(\"test12\", signals); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } } Creating soundfile The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with sigSoundfile , but cannot be used directly. It has to be used with: sigSoundfileLength to access the sound length in frames sigSoundfileRate to access the sound rate in Hz sigSoundfileBuffer to access the actual samples Thus the following DSP code: Will be created using the signal API with: static void test19() { COMPILER ( tvec signals; // Soundfile definition Signal sf = sigSoundfile(\"sound[url:{'tango.wav'}]\"); // Simple read index of 0 to simplify the code Signal rdx = sigInt(0); // Part 0 Signal part = sigInt(0); // Wrapped index to avoid reading outside the buffer Signal wridx = sigIntCast(sigMax(sigInt(0), sigMin(rdx, sigSub(sigSoundfileLength(sf, sigInt(0)), sigInt(1))))); // Accessing part 0 signals.push_back(sigSoundfileLength(sf, part)); // Accessing part 0 signals.push_back(sigSoundfileRate(sf, part)); // Accessing chan 0 and part 0, with a wrapped read index signals.push_back(sigSoundfileBuffer(sf, sigInt(0), part, wridx)); compile(\"test19\", signals); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; } Defining more complex expressions: phasor and oscillator More complex signal expressions can be defined, creating signals using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Signal decimalpart(Signal x) { return sigSub(x, sigIntCast(x)); } static Signal phasor(Signal f) { return sigRecursion(decimalpart(sigAdd(sigSelf(), sigDiv(f, SR())))); } And the main function combining them: static void test17() { COMPILER ( tvec signals; signals.push_back(phasor(sigReal(440.0))); compile(\"test17\", signals); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Signal osc(Signal f) { return sigSin(sigMul(phasor(f), sigMul(sigReal(2.0), sigReal(3.141592653)))); } static void test18() { COMPILER ( tvec signals; signals.push_back(osc(sigReal(440.0))); signals.push_back(osc(sigReal(440.0))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } } Using the generated code Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromSignals (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromSignals (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory); Connecting the audio layer Audio drivers allow to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop(); Connecting the controller layer Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual. Example with audio rendering and GUI control Here is a more complete example, first with the DSP code: Then with the C++ code using the signal API: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq1\", sigReal(300), sigReal(100), sigReal(2000), sigReal(0.01)))); signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq2\", sigReal(500), sigReal(100), sigReal(2000), sigReal(0.01)))); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Polyphonic MIDI controllable simple synthesizer Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the signal API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Signal freq = sigNumEntry(\"freq\", sigReal(100), sigReal(100), sigReal(3000), sigReal(0.01)); Signal gate = sigButton(\"gate\"); Signal gain = sigNumEntry(\"gain\", sigReal(0.5), sigReal(0), sigReal(1), sigReal(0.01)); Signal organ = sigMul(gate, sigAdd(sigMul(osc(freq), gain), sigMul(osc(sigMul(freq, sigInt(2))), gain))); // Stereo signals.push_back(organ); signals.push_back(organ); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } } Examples with the C API The signal API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create signals, where the LLVM backend is used with the C version createCDSPFactoryFromSignals function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Signal decimalpart(Signal x) { return CsigSub(x, CsigIntCast(x)); } static Signal phasor(Signal f) { return CsigRecursion(decimalpart(CsigAdd(CsigSelf(), CsigDiv(f, SR())))); } static void test1() { createLibContext(); { Signal signals[2]; signals[0] = phasor(CsigReal(2000)); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test1\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Signal signals[2]; Signal freq = CsigVSlider(\"h:Oscillator/freq\", CsigReal(440), CsigReal(50), CsigReal(1000), CsigReal(0.1)); Signal gain = CsigVSlider(\"h:Oscillator/gain\", CsigReal(0), CsigReal(0), CsigReal(1), CsigReal(0.011)); signals[0] = CsigMul(freq, CsigMul(gain, CsigInput(0))); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test3\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the signal-tester-c tool, to be compiled with make signal-tester-c in the tools/benchmark folder. Creating a signal language based on this API Generating complex expressions by directly using the signal API can quickly become really tricky and unpracticable. So a language created on top of the signal API is usually needed. This is exactly what the Block Diagram Algebra is all about, and the entire Faust language itself. But some other approaches can possibly be tested. The Elementary audio language for instance is built over a similar signal language and uses JavaScript as the upper layer language to help create a complex list of output signals programmatically. Other approaches using graphical based tools could certainly be tested.","title":"Using the signal API"},{"location":"tutorials/signal-api/#using-the-signal-api","text":"The signal API opens an intermediate access inside the Faust compilation chain . In this tutorial, we present it with examples of code. The goal is to show how new audio DSP languages (textual or graphical) could be built on top of the signal API, and take profit of part of the Faust compiler infrastructure.","title":"Using the signal API"},{"location":"tutorials/signal-api/#faust-compiler-structure","text":"The Faust compiler is composed of several steps: The compilation chain Starting from the DSP source code, the Semantic Phase produces signals as conceptually infinite streams of samples or control values. Those signals are then compiled in imperative code (C/C++, LLVM IR, WebAssembly, etc.) in the Code Generation Phase . The Semantic Phase itself is composed of several steps: The semantic phase The initial DSP code using the Block Diagram Algebra (BDA) is translated in a flat circuit in normal form in the Evaluation, lambda-calculus step. The list of output signals is produced by the Symbolic Propagation step. Each output signal is then simplified and a set of optimizations are done (normal form computation and simplification, delay line sharing, typing, etc.) to finally produce a list of output signals in normal form . The Code Generation Phase translates the signals in an intermediate representation named FIR (Faust Imperative Representation) which is then converted to the final target language (C/C++, LLVM IR, WebAssembly,etc.) with a set of backends.","title":"Faust compiler structure"},{"location":"tutorials/signal-api/#accessing-the-signal-stage","text":"A new intermediate public entry point has been created in the Semantic Phase to allow the creation of a signal set (as a list of output signals), then beneficiate of all remaining parts of the compilation chain. The signal API (or the C signal API version) allows to programmatically create the list of output signals, then compile it to create a ready-to-use DSP as a C++ class, or LLVM, Interpreter or WebAssembly factories, to be used with all existing architecture files. Several optimizations done at the signal stage will be demonstrated looking at the generated C++ code. Note that the box API allows to access another stage in the compilation stage.","title":"Accessing the signal stage"},{"location":"tutorials/signal-api/#compiling-signal-expressions","text":"To use the signal API, the following steps must be taken: creating a global compilation context using the createLibContext function creating signals outputs using the signal API, progressively building more complex expressions by combining simpler ones compiling the list of outputs using the createCPPDSPFactoryFromSignals function to create a DSP factory (or createDSPFactoryFromSignals to generate a LLVM embedding factory, or createInterpreterDSPFactoryFromSignals to generate an Interpreter embedding factory) finally destroying the compilation context using the destroyLibContext function The DSP factories allow the creation of DSP instances, to be used with audio and UI architecture files, outside of the compilation process itself . The DSP instances and factory will finally have to be deallocated when no more used.","title":"Compiling signal expressions"},{"location":"tutorials/signal-api/#tools","text":"Let's first define a compile function, which uses the createCPPDSPFactoryFromSignals function and print the generated C++ class: static void compile(const string& name, tvec signals, int argc = 0, const char* argv[] = nullptr) { string error_msg; dsp_factory_base* factory = createCPPDSPFactoryFromSignals(name, signals, argc, argv, error_msg); if (factory) { // Print the C++ class factory->write(&cout); delete(factory); } else { cerr << error_msg; } } A macro to wrap all the needed steps: #define COMPILER(exp) \\ { \\ createLibContext(); \\ exp \\ destroyLibContext(); \\ } \\","title":"Tools"},{"location":"tutorials/signal-api/#examples","text":"For each example, the equivalent Faust DSP program and SVG diagram is given as helpers. The SVG diagram shows the result of the compilation propagate step (so before any of the signal normalization steps) and clearly shows how each output signal expression has to be created. All presented C++ examples (as well as some more) are defined in the signal-tester tool, to be compiled with make signal-tester in the tools/benchmark folder.","title":"Examples"},{"location":"tutorials/signal-api/#simple-constant-signal","text":"Let's create a program generating the 0.5 constant value. Here is the Faust DSP code: The following code creates a vector of output signals (with the tvec type), containing the single sigReal(0.5) signal, then compile it and display the C++ class: static void test1() { COMPILER ( tvec signals; signals.push_back(sigReal(0.5)); compile(\"test1\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(0.5f); } }","title":"Simple constant signal"},{"location":"tutorials/signal-api/#doing-some-mathematical-operations-on-an-input-signal","text":"Here is a simple program doing a mathematical operation on an signal input: The first audio input is created with sigInput(0) signal, then transformed using sigAdd and sigMul signal operators to produce two outputs: static void test2() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(in1, sigReal(0.5))); signals.push_back(sigMul(in1, sigReal(1.5))); compile(\"test2\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); output0[i0] = FAUSTFLOAT((fTemp0 + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fTemp0)); } } Note that accessing input N is simply done using the sigInput(N) expression.","title":"Doing some mathematical operations on an input signal"},{"location":"tutorials/signal-api/#defining-delayed-signals","text":"Here is a simple program using a signal input and doing mathematical operations on it, then delaying the signals: The sigDelay(x, y) operator is used to delay the x first parameter with the second y parameter, here with constant values: static void test3() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); compile(\"test3\", signals); ) } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; fVec1[(IOTA & 511)] = (fTemp0 + 0.5f); output0[i0] = FAUSTFLOAT(fVec1[((IOTA - 500) & 511)]); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } } Several options of the Faust compiler allow control of the generated C++ code. By default computation is done sample by sample in a single loop. But the compiler can also generate vector and parallel code . The following code show how to compile in vector mode: static void test5() { createLibContext(); tvec signals; Signal in1 = sigInput(0); signals.push_back(sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500))); signals.push_back(sigDelay(sigMul(in1, sigReal(1.5)), sigInt(3000))); // Vector compilation compile(\"test5\", signals, 3, (const char* []){ \"-vec\", \"-lv\", \"1\" }); destroyLibContext(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0_ptr = inputs[0]; FAUSTFLOAT* output0_ptr = outputs[0]; FAUSTFLOAT* output1_ptr = outputs[1]; for (int vindex = 0; (vindex < count); vindex = (vindex + 32)) { FAUSTFLOAT* input0 = &input0_ptr[vindex]; FAUSTFLOAT* output0 = &output0_ptr[vindex]; FAUSTFLOAT* output1 = &output1_ptr[vindex]; int vsize = std::min<int>(32, (count - vindex)); /* Vectorizable loop 0 */ /* Pre code */ fYec0_idx = ((fYec0_idx + fYec0_idx_save) & 4095); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec0[((i + fYec0_idx) & 4095)] = float(input0[i]); } /* Post code */ fYec0_idx_save = vsize; /* Vectorizable loop 1 */ /* Pre code */ fYec1_idx = ((fYec1_idx + fYec1_idx_save) & 1023); /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { fYec1[((i + fYec1_idx) & 1023)] = (float(input0[i]) + 0.5f); } /* Post code */ fYec1_idx_save = vsize; /* Vectorizable loop 2 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output0[i] = FAUSTFLOAT(fYec1[(((i + fYec1_idx) - 500) & 1023)]); } /* Vectorizable loop 3 */ /* Compute code */ for (int i = 0; (i < vsize); i = (i + 1)) { output1[i] = FAUSTFLOAT((1.5f * fYec0[(((i + fYec0_idx) - 3000) & 4095)])); } } } And can possibly be faster if the C++ compiler can auto-vectorize it. If the delay operators are used on the input signal before the mathematical operations, then a single delay line will be created, taking the maximum size of both delay lines: And built with the following code: static void test4() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigAdd(sigDelay(in1, sigInt(500)), sigReal(0.5))); signals.push_back(sigMul(sigDelay(in1, sigInt(3000)), sigReal(1.5))); compile(\"test4\", signals); ) } In the compute method, the single fVec0 delay line is read at 2 differents indexes: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { float fTemp0 = float(input0[i0]); fVec0[(IOTA & 4095)] = fTemp0; output0[i0] = FAUSTFLOAT((fVec0[((IOTA - 500) & 4095)] + 0.5f)); output1[i0] = FAUSTFLOAT((1.5f * fVec0[((IOTA - 3000) & 4095)])); IOTA = (IOTA + 1); } }","title":"Defining delayed signals"},{"location":"tutorials/signal-api/#equivalent-signal-expressions","text":"It is really important to note that syntactically equivalent signal expressions will be internally represented by the same memory structure (using hash consing), thus treated in the same way in the further compilation steps. So the following code where the s1 variable is created to define the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression, then used in both outputs: static void equivalent1() { COMPILER ( tvec signals; Signal s1 = sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) signals.push_back(s1); signals.push_back(s1); compile(\"equivalent1\", signals); ) } Will behave exactly the same as the following code, where the sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5)) expression is used twice: static void equivalent2() { COMPILER ( tvec signals; signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); signals.push_back(sigAdd(sigDelay(sigInput(0), sigInt(500)), sigReal(0.5))); compile(\"equivalent2\", signals); ) } It can be a property to remember when creating a DSL on top of the signal API.","title":"Equivalent signal expressions"},{"location":"tutorials/signal-api/#using-user-interface-items","text":"User Interface items can be used, as in the following example, with a vslider : Built with the following code: static void test8() { COMPILER ( tvec signals; Signal in1 = sigInput(0); Signal s = sigVSlider(\"Vol\", sigReal(0.5), sigReal(0.), sigReal(1.), sigReal(0.01)); signals.push_back(sigMul(s, sigDelay(sigAdd(in1, sigReal(0.5)), sigInt(500)))); compile(\"test8\", signals); ) } The buildUserInterface method is generated, using the fVslider0 variable: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openVerticalBox(\"test8\"); ui_interface->addVerticalSlider(\"Vol\", &fVslider0, FAUSTFLOAT(0.5f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.00999999978f)); ui_interface->closeBox(); } The compute method is then: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; float fSlow0 = float(fVslider0); for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fVec0[(IOTA & 511)] = (float(input0[i0]) + 0.5f); output0[i0] = FAUSTFLOAT((fSlow0 * fVec0[((IOTA - 500) & 511)])); IOTA = (IOTA + 1); } } User Interface layout can be described with hgroup , or vgroup or tgroup . With the signal API, the layout can be defined using the labels-as-pathnames syntax, as in the following example: Built with the following code: static void test9() { COMPILER ( tvec signals; Signal freq = sigVSlider(\"h:Oscillator/freq\", sigReal(440), sigReal(50), sigReal(1000), sigReal(0.1)); Signal gain = sigVSlider(\"h:Oscillator/gain\", sigReal(0), sigReal(0), sigReal(1), sigReal(0.011)); signals.push_back(sigMul(freq, sigMul(gain, sigInput(0)))); compile(\"test9\", signals); ) } The buildUserInterface method is generated with the expected openHorizontalBox call: virtual void buildUserInterface(UI* ui_interface) { ui_interface->openHorizontalBox(\"Oscillator\"); ui_interface->addVerticalSlider(\"freq\", &fVslider0, FAUSTFLOAT(440.0f), FAUSTFLOAT(50.0f), FAUSTFLOAT(1000.0f), FAUSTFLOAT(0.100000001f)); ui_interface->addVerticalSlider(\"gain\", &fVslider1, FAUSTFLOAT(0.0f), FAUSTFLOAT(0.0f), FAUSTFLOAT(1.0f), FAUSTFLOAT(0.0109999999f)); ui_interface->closeBox(); }","title":"Using User Interface items"},{"location":"tutorials/signal-api/#defining-recursive-signals","text":"Recursive signals can be defined using the sigRecursion function to build the recursion, and the sigSelf function to refer to the recursive signal itself. A one sample delay is automatically created to produce a valid computation. Here is a simple example: Built with the following code: static void test10() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursion(sigAdd(sigSelf(), in1))); compile(\"test10\", signals); ) } The compute method shows the fRec0 variable that keeps the delayed signal: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (float(input0[i0]) + fRec0[1]); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } The same equivalent code can be defined using the more general sigRecursionN and sigSelfN functions which allow to build a list of (possibly mutually dependent) recursive signals: static void test10bis() { COMPILER ( tvec signals; Signal in1 = sigInput(0); signals.push_back(sigRecursionN(sigAdd(sigSelfN(0), in1))); compile(\"test10\", signals); ) } Here is an example of the definition of mutually dependent recursive signals: static void test10ter() { COMPILER ( Signal in0 = sigInput(0); Signal in1 = sigInput(1); tvec ins; ins.push_back(sigAdd(sigMul(sigSelfN(1), sigReal(0.5)), in0)); ins.push_back(sigAdd(sigMul(sigSelfN(0), sigReal(0.9)), in1)); tvec outs = sigRecursionN(ins); compile(\"test10ter\", outs); ) } With the following compute method: virtual void compute(int count, FAUSTFLOAT** RESTRICT inputs, FAUSTFLOAT** RESTRICT outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; i0 < count; i0 = i0 + 1) { fRec0[0] = float(input0[i0]) + 0.5f * fRec1[1]; fRec1[0] = float(input1[i0]) + 0.9f * fRec0[1]; output0[i0] = FAUSTFLOAT(fRec0[0]); output1[i0] = FAUSTFLOAT(fRec1[0]); fRec0[1] = fRec0[0]; fRec1[1] = fRec1[0]; } }","title":"Defining recursive signals"},{"location":"tutorials/signal-api/#accessing-the-global-context","text":"In Faust, the underlying audio engine sample rate and buffer size is accessed using the foreign function and constant mechanism. The values can also be used in the signal language with the following helper functions: // Reproduce the 'SR' definition in platform.lib // SR = min(192000.0, max(1.0, fconstant(int fSampleFreq, <dummy.h>))); inline Signal SR() { return sigMin(sigReal(192000.0), sigMax(sigReal(1.0), sigFConst(SType::kSInt, \"fSampleFreq\", \"<dummy.h>\"))); } // Reproduce the 'BS' definition in platform.lib // BS = fvariable(int count, <dummy.h>); inline Signal BS() { return sigFVar(SType::kSInt, \"count\", \"<dummy.h>\"); } So the following DSP program: Can be written at the signal API level with: static void test11() { COMPILER ( tvec signals; signals.push_back(SR()); signals.push_back(BS()); compile(\"test11\", signals); ) } And the resulting C++ class contains: virtual void instanceConstants(int sample_rate) { fSampleRate = sample_rate; fConst0 = std::min<float>(192000.0f, std::max<float>(1.0f, float(fSampleRate))); } and: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; int iSlow0 = count; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(fConst0); output1[i0] = FAUSTFLOAT(iSlow0); } }","title":"Accessing the global context"},{"location":"tutorials/signal-api/#creating-tables","text":"Read only and read/write tables can be created. The read only table signal is created with sigReadOnlyTable and takes: a size first argument a content second argument a read index third argument (between 0 and size-1) and produces the indexed table content as its single output. The following simple DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigReadOnlyTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)))); compile(\"test20\", signals); ) } The resulting C++ code contains the itbl0mydspSIG0 static table definition: static int itbl0mydspSIG0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that access the itbl0mydspSIG0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(itbl0mydspSIG0[int(float(input0[i0]))]); } } The read/write table signal is created with sigWriteReadTable and takes: a size first argument a content second argument a write index a third argument (between 0 and size-1) the input of the table as fourth argument a read index as fifth argument (between 0 and size-1) and produces the indexed table content as its single output. The following DSP example: Can be written with the code: static void test20() { COMPILER ( tvec signals; signals.push_back(sigWriteReadTable(sigInt(10), sigInt(1), sigIntCast(sigInput(0)), sigIntCast(sigInput(1)), sigIntCast(sigInput(2)))); compile(\"test21\", signals); ) } The resulting C++ code contains the itbl0 definition as a field in the mydsp class: int itbl0[10]; The table filling code that will be called once at init time: void fillmydspSIG0(int count, int* table) { for (int i1 = 0; (i1 < count); i1 = (i1 + 1)) { table[i1] = 1; } } An the compute method that reads and writes in the itbl0 table: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* input0 = inputs[0]; FAUSTFLOAT* input1 = inputs[1]; FAUSTFLOAT* input2 = inputs[2]; FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { itbl0[int(float(input0[i0]))] = int(float(input1[i0])); output0[i0] = FAUSTFLOAT(itbl0[int(float(input2[i0]))]); } }","title":"Creating tables"},{"location":"tutorials/signal-api/#creating-waveforms","text":"The following DSP program defining a waveform: Can be written with the code, where the size of the waveform is the first output, and the waveform content itself is the second output created with sigWaveform , to follow the waveform semantic : static void test12() { COMPILER ( tvec waveform; // Fill the waveform content vector for (int i = 0; i < 5; i++) { waveform.push_back(sigReal(100*i)); } tvec signals; signals.push_back(sigInt(waveform.size())); // the waveform size signals.push_back(sigWaveform(waveform)); // the waveform content compile(\"test12\", signals); ) } With the resulting C++ code, where the fmydspWave0 waveform is defined as a static table: const static float fmydspWave0[5] = {0.0f,100.0f,200.0f,300.0f,400.0f}; And using in the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(5); output1[i0] = FAUSTFLOAT(fmydspWave0[fmydspWave0_idx]); fmydspWave0_idx = ((1 + fmydspWave0_idx) % 5); } }","title":"Creating waveforms"},{"location":"tutorials/signal-api/#creating-soundfile","text":"The soundfile primitive allows the access of a list of externally defined sound resources, described as the list of their filename, or complete paths. It takes: the sound number (as a integer between 0 and 255 as a constant numerical expression ) the read index in the sound (which will access the last sample of the sound if the read index is greater than the sound length) The generated block has: two fixed outputs: the first one is the currently accessed sound length in frames, the second one is the currently accessed sound nominal sample rate several more outputs for the sound channels themselves, as a constant numerical expression The soundfile block is created with sigSoundfile , but cannot be used directly. It has to be used with: sigSoundfileLength to access the sound length in frames sigSoundfileRate to access the sound rate in Hz sigSoundfileBuffer to access the actual samples Thus the following DSP code: Will be created using the signal API with: static void test19() { COMPILER ( tvec signals; // Soundfile definition Signal sf = sigSoundfile(\"sound[url:{'tango.wav'}]\"); // Simple read index of 0 to simplify the code Signal rdx = sigInt(0); // Part 0 Signal part = sigInt(0); // Wrapped index to avoid reading outside the buffer Signal wridx = sigIntCast(sigMax(sigInt(0), sigMin(rdx, sigSub(sigSoundfileLength(sf, sigInt(0)), sigInt(1))))); // Accessing part 0 signals.push_back(sigSoundfileLength(sf, part)); // Accessing part 0 signals.push_back(sigSoundfileRate(sf, part)); // Accessing chan 0 and part 0, with a wrapped read index signals.push_back(sigSoundfileBuffer(sf, sigInt(0), part, wridx)); compile(\"test19\", signals); ) } And the following compute method is generated: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; FAUSTFLOAT* output2 = outputs[2]; Soundfile* fSoundfile0ca = fSoundfile0; int* fSoundfile0ca_le0 = fSoundfile0ca->fLength; int iSlow0 = fSoundfile0ca_le0[0]; int* fSoundfile0ca_ra0 = fSoundfile0ca->fSR; int iSlow1 = fSoundfile0ca_ra0[0]; int iSlow2 = std::max<int>(0, std::min<int>(0, (iSlow0 + -1))); int* fSoundfile0ca_of0 = fSoundfile0ca->fOffset; float** fSoundfile0ca_bu0 = static_cast<float**>(fSoundfile0ca->fBuffers); float* fSoundfile0ca_bu_ch0 = fSoundfile0ca_bu0[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { output0[i0] = FAUSTFLOAT(iSlow0); output1[i0] = FAUSTFLOAT(iSlow1); output2[i0] = FAUSTFLOAT(fSoundfile0ca_bu_ch0[(fSoundfile0ca_of0[0] + iSlow2)]); } fSoundfile0 = fSoundfile0ca; }","title":"Creating soundfile"},{"location":"tutorials/signal-api/#defining-more-complex-expressions-phasor-and-oscillator","text":"More complex signal expressions can be defined, creating signals using auxiliary definitions. So the following DSP program: Can be built using the following helper functions, here written in C: static Signal decimalpart(Signal x) { return sigSub(x, sigIntCast(x)); } static Signal phasor(Signal f) { return sigRecursion(decimalpart(sigAdd(sigSelf(), sigDiv(f, SR())))); } And the main function combining them: static void test17() { COMPILER ( tvec signals; signals.push_back(phasor(sigReal(440.0))); compile(\"test17\", signals); ) } Which produces the following compute method: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); output0[i0] = FAUSTFLOAT(fRec0[0]); fRec0[1] = fRec0[0]; } } Now the following oscillator: Can be built with: static Signal osc(Signal f) { return sigSin(sigMul(phasor(f), sigMul(sigReal(2.0), sigReal(3.141592653)))); } static void test18() { COMPILER ( tvec signals; signals.push_back(osc(sigReal(440.0))); signals.push_back(osc(sigReal(440.0))); compile(\"test18\", signals); ) } Which produces the following compute method, where one can see that since the same oscillator signal is used on both outputs, it is actually computed once and copied twice: virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) { FAUSTFLOAT* output0 = outputs[0]; FAUSTFLOAT* output1 = outputs[1]; for (int i0 = 0; (i0 < count); i0 = (i0 + 1)) { fRec0[0] = (fConst0 + (fRec0[1] - float(int((fConst0 + fRec0[1]))))); float fTemp0 = std::sin((6.28318548f * fRec0[0])); output0[i0] = FAUSTFLOAT(fTemp0); output1[i0] = FAUSTFLOAT(fTemp0); fRec0[1] = fRec0[0]; } }","title":"Defining more complex expressions: phasor and oscillator"},{"location":"tutorials/signal-api/#using-the-generated-code","text":"Using the LLVM or Interpreter backends allows to generate and execute the compiled DSP on the fly. The LLVM backend can be used with createDSPFactoryFromSignals (see llvm-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; llvm_dsp_factory* factory = createDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteDSPFactory(factory); The Interpreter backend can be used with createInterpreterDSPFactoryFromSignals (see interpreter-dsp.h ) to produce a DSP factory, then a DSP instance: string error_msg; interpreter_dsp_factory* factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, \"\", error_msg); // Check factory dsp* dsp = factory->createDSPInstance(); // Check dsp ... // Use dsp ... // Delete dsp and factory delete dsp; deleteInterpreterDSPFactory(factory);","title":"Using the generated code"},{"location":"tutorials/signal-api/#connecting-the-audio-layer","text":"Audio drivers allow to render the DSP instance. Here is a simple code example using the dummyaudio audio driver: // Allocate the audio driver to render 5 buffers of 512 frames dummyaudio audio(5); audio.init(\"Test\", dsp); // Render buffers... audio.start(); audio.stop(); A more involved example using the JACK audio driver: // Allocate the JACK audio driver jackaudio audio; audio.init(\"Test\", dsp); // Start real-time processing audio.start(); .... audio.stop();","title":"Connecting the audio layer"},{"location":"tutorials/signal-api/#connecting-the-controller-layer","text":"Controllers can be connected to the DSP instance using GUI architectures. Here is a code example using the GTKUI interface: GUI* interface = new GTKUI(\"Test\", &argc, &argv); dsp->buildUserInterface(interface); interface->run(); And all other standard controllers (MIDI, OSC, etc.) can be used as usual.","title":"Connecting the controller layer"},{"location":"tutorials/signal-api/#example-with-audio-rendering-and-gui-control","text":"Here is a more complete example, first with the DSP code: Then with the C++ code using the signal API: // Using the Interpreter backend. static void test23(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq1\", sigReal(300), sigReal(100), sigReal(2000), sigReal(0.01)))); signals.push_back(osc(sigHSlider(\"v:Oscillator/Freq2\", sigReal(500), sigReal(100), sigReal(2000), sigReal(0.01)))); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate audio driver jackaudio audio; audio.init(\"Test\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Start real-time processing audio.start(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Example with audio rendering and GUI control"},{"location":"tutorials/signal-api/#polyphonic-midi-controllable-simple-synthesizer","text":"Here is a MIDI controllable simple synthesizer, first with the DSP code: Then with the C++ code using the signal API: // Simple polyphonic DSP. static void test24(int argc, char* argv[]) { interpreter_dsp_factory* factory = nullptr; string error_msg; createLibContext(); { tvec signals; // Follow the freq/gate/gain convention, // see: https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters Signal freq = sigNumEntry(\"freq\", sigReal(100), sigReal(100), sigReal(3000), sigReal(0.01)); Signal gate = sigButton(\"gate\"); Signal gain = sigNumEntry(\"gain\", sigReal(0.5), sigReal(0), sigReal(1), sigReal(0.01)); Signal organ = sigMul(gate, sigAdd(sigMul(osc(freq), gain), sigMul(osc(sigMul(freq, sigInt(2))), gain))); // Stereo signals.push_back(organ); signals.push_back(organ); factory = createInterpreterDSPFactoryFromSignals(\"FaustDSP\", signals, 0, nullptr, error_msg); } destroyLibContext(); // Use factory outside of the createLibContext/destroyLibContext scope if (factory) { dsp* dsp = factory->createDSPInstance(); assert(dsp); // Allocate polyphonic DSP dsp = new mydsp_poly(dsp, 8, true, true); // Allocate MIDI/audio driver jackaudio_midi audio; audio.init(\"Organ\", dsp); // Create GUI GTKUI gtk_ui = GTKUI(\"Organ\", &argc, &argv); dsp->buildUserInterface(&gtk_ui); // Create MIDI controller MidiUI midi_ui = MidiUI(&audio); dsp->buildUserInterface(&midi_ui); // Start real-time processing audio.start(); // Start MIDI midi_ui.run(); // Start GUI gtk_ui.run(); // Cleanup audio.stop(); delete dsp; deleteInterpreterDSPFactory(factory); } else { cerr << error_msg; } }","title":"Polyphonic MIDI controllable simple synthesizer"},{"location":"tutorials/signal-api/#examples-with-the-c-api","text":"The signal API is also available as a pure C API . Here is one of the previous example rewritten using the C API to create signals, where the LLVM backend is used with the C version createCDSPFactoryFromSignals function (see llvm-dsp-c.h ) to produce a DSP factory, then a DSP instance: /* import(\"stdfaust.lib\"); process = phasor(440) with { decimalpart(x) = x-int(x); phasor(f) = f/ma.SR : (+ : decimalpart) ~ _; }; */ static Signal decimalpart(Signal x) { return CsigSub(x, CsigIntCast(x)); } static Signal phasor(Signal f) { return CsigRecursion(decimalpart(CsigAdd(CsigSelf(), CsigDiv(f, SR())))); } static void test1() { createLibContext(); { Signal signals[2]; signals[0] = phasor(CsigReal(2000)); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test1\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); // Render audio render(dsp); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } Here is an example using controllers and the PrintUI architecture to display their parameters: /* import(\"stdfaust.lib\"); freq = vslider(\"h:Oscillator/freq\", 440, 50, 1000, 0.1); gain = vslider(\"h:Oscillator/gain\", 0, 0, 1, 0.01); process = freq * gain; */ static void test3() { createLibContext(); { Signal signals[2]; Signal freq = CsigVSlider(\"h:Oscillator/freq\", CsigReal(440), CsigReal(50), CsigReal(1000), CsigReal(0.1)); Signal gain = CsigVSlider(\"h:Oscillator/gain\", CsigReal(0), CsigReal(0), CsigReal(1), CsigReal(0.011)); signals[0] = CsigMul(freq, CsigMul(gain, CsigInput(0))); signals[1] = NULL; // Null terminated array char error_msg[4096]; llvm_dsp_factory* factory = createCDSPFactoryFromSignals(\"test3\", signals, 0, NULL, \"\", error_msg, -1); if (factory) { llvm_dsp* dsp = createCDSPInstance(factory); assert(dsp); printf(\"=================UI=================\\n\"); // Defined in PrintCUI.h metadataCDSPInstance(dsp, &mglue); buildUserInterfaceCDSPInstance(dsp, &uglue); // Cleanup deleteCDSPInstance(dsp); deleteCDSPFactory(factory); } else { printf(\"Cannot create factory : %s\\n\", error_msg); } } destroyLibContext(); } All presented C examples (as well as some more) are defined in the signal-tester-c tool, to be compiled with make signal-tester-c in the tools/benchmark folder.","title":"Examples with the C API"},{"location":"tutorials/signal-api/#creating-a-signal-language-based-on-this-api","text":"Generating complex expressions by directly using the signal API can quickly become really tricky and unpracticable. So a language created on top of the signal API is usually needed. This is exactly what the Block Diagram Algebra is all about, and the entire Faust language itself. But some other approaches can possibly be tested. The Elementary audio language for instance is built over a similar signal language and uses JavaScript as the upper layer language to help create a complex list of output signals programmatically. Other approaches using graphical based tools could certainly be tested.","title":"Creating a signal language based on this API"},{"location":"tutorials/summation/","text":"RMS and Summation in Faust In this tutorial, we present different programming techniques to compute the sum of n consecutive samples in Faust. Such sums are typically used when computing the RMS value of a signal. It is therefore in the RMS context that we will present them. We will not use any predefined function, only Faust primitives, so that you can see all the details. The text is intended for beginners, but with some basic knowledge of Faust. If this is not your case have a look at the various documentations on this website. RMS value The computation of the RMS (Root Mean Square) value of a signal is defined by the following Faust expression: ^(2) : summation : /(n) : sqrt where n is the number of consecutive samples considered. This expression involves several steps: First, we take the square of the signal: ^(2) . This is the S of RMS. Then we sum the n consecutive samples: summation and divide this sum by n to get the mean value: /(n) . This is the M of RMS. Finally, we take the square root sqrt . This is the R of RMS. In other words, RMS is written S:M:R in Faust (leaving the summation function undefined for the moment): RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; }; In the following paragraphs, we will introduce 4 different techniques to write this summation function. We will assume that the audio samples are between -1 and 1. Sliding Sum Let's start with the sliding sum approach, probably the simplest way to efficiently add n consecutive samples. First, let's recall that we can add up all the samples of a signal s , from time 0 to the present time, with the following expression: s : +~_ . The trick for adding only the last n samples is to subtract from this sum the same sum but as it was n samples earlier. For example, in order to keep only the sum of the last 10 samples, we just have to subtract from the sum of all samples (s:+~_) the value of this same sum 10 samples ago (s:+~_ : @(10)) : (s:+~_), (s:+~_ : @(10)) : - This expression can be further simplified by factoring s:+~_ . We then get: s : +~_ <: _, @(10) : - From a mathematical point of view, this is perfectly correct but poses problems when computed using floating-point numbers. Unlike mathematical numbers, floating-point numbers have a limited precision (23 bits in single precision). When calculating the RMS value, we only add positive numbers. Therefore the sum will increase forever. But at some point, when the sum exceeds 2^{23} \u200b, the least significant bit will be higher than any number between 0 \u200b and 1 \u200b. Therefore adding such a small number will be exactly like adding 0, and the sum will never evolve anymore. Fortunately, the problem can be solved easily. We just have to swap the integration and the difference parts: s <: _, @(10) : - : +~_ This new formulation is identical to the previous one from a mathematical point of view. But now, the sum will always stay between -10\u200b and +10 \u200b\u200b, and the accuracy problems are only on the least significant bits. If the roundoff error due to quantization is modeled as a uniformly distributed random number between -q/2 and q/2, then its variance (mean square) is q^2/12, and this value increases linearly over time in a running sum (see \"Wiener process\"). Thus, we expect the roundoff error in a running-sum rms calculator to grow proportional to the square root of time. We can now complete the definition of RMS: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = _ <: _, @(n) : - : +~_; }; Fix-Point Sliding Sum While the previous solution works very well with typical signals over practical time spans, the roundoff error continues to grow slowly. To avoid a gradual loss of precision, we can use a fix-point encoding of the samples, so that the subtraction after delay is always exact. Let's say that we want a sliding sum of 10 values between 0 and 1. We know that this sum will never exceed 2^4 \u200b\u200b\u200b. We could therefore use up to 27 bits (31-4) to code the fractional part of values. The conversions are straightforward. To convert floating-point values to fix-point we can use the following expression: *(2^27):int . To convert back from fix-point to floating-point we can use the inverse expression: float:/(2^27) . We can now complete the definition of RMS. As we can see in the summation definition below, we first convert the samples to fix-point, do the summation on integers, then convert the result back to floating-point: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = float2fix(16) : _ <: _, @(n) : - : +~_ : fix2float(16); float2fix(p) = *(2^p) : int; fix2float(p) = float : /(2^p); }; Obviously this is correct only if we let enough bits for the integral part. Here we have 15 bits (31-16), enough for n up to 32000 samples. Block Sum Sliding sums have a nice and smooth behavior because an updated sum is produced every sample. But they require a large delay line (larger than n \u200b)\u200b\u200b, and can have precision problems. In this third approach, we will use a summation by blocks. The summation will be exact, will not require a large delay line, but will be only updated once per block of n samples. The code is a little bit more involved. It will require a phase signal: 0,1,2,3,\\ldots,n-1,0,1\\ldots \u200b,\u200b\u200b\u200b and a capture (sample and hold) operation. Let's start with a simplified version derived from: s:+~_ . Remind that _ is the identity function and is equivalent to *(1) . We can therefore rewrite the previous expression s:+~*(1) . Now, imagine that instead of 1 we have a boolean b as in: s:~*(b) . When b is 1 the input sample is added to the previous sum, but when b is 0 the input sample is added to 0 , and the sum is reset to be the input sample. In our case, we want to reset the sum after every block of n samples, that is, every time phase returns to 0 . This can be written: s:+~*(phase!=0) . Note that we can't use the output of this expression directly. It only represents the sum we are looking for when phase==(n-1) . That is why we need an additional capture stage to sample the sum and hold it while the next block is processed. Let's say that b indicates when to capture the input value, then: select2(b)~_ will do the job. When b is 0 , it reproduces the feedback signal, and when b is 1 , it captures the input signal. Here is the full implementation: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = + ~ *(phase != 0) : capture(phase==(n-1)); phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; }; Overlapping Block Sum As we mentioned, the block sum has the disadvantage of producing a new value only once per block. If the blocks are large, this can be a problem. In this fourth approach, we will see how to overlap the produced values. For example, we would like to compute the sum of the last 1000 samples, but with a new result every 250 samples (i.e., an overlap of 75%). The principle will be to sum small blocks of 250 samples, keep the last four sums, and add them together to produce, every 250 samples, a new sum of the last 1000 samples. Let's call w the size of a small block, and c the number of small blocks in a large block of n samples (i.e., n=c*w )\u200b. Instead of computing sums of n samples as with: + ~ *(phase != 0) , we compute sums of w samples: + ~ *(phase%w != 0) . Instead of having one capture every n samples: capture(phase == (n-1)) , we need c captures in parallel at 1*w-1 , 2*w-1 , etc.: par(i,c, capture( phase == (w*(i+1) - 1) )) Here is the full code: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; c = 4; // number of overlaps summation = + ~ *(phase%w != 0) <: par(i, c, capture( phase == (w*(i+1) - 1) )) :> _ with { w = n/c; }; phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; }; Comparing all the solutions Using the Faust IDE, we can easily compare all these solutions. To encapsulate all the definitions and select the RMS implementation, we will use an environment. If you are not familiar with the concept of environment, it is a way to group definitions. The screen shot of the Faust IDE below shows the RMS values of testsource according to the 4 methods: Sliding Sum , Fix-Point Sliding Sum , Block Sum , and Overlapping Block Sum .","title":"RMS and Summation in Faust"},{"location":"tutorials/summation/#rms-and-summation-in-faust","text":"In this tutorial, we present different programming techniques to compute the sum of n consecutive samples in Faust. Such sums are typically used when computing the RMS value of a signal. It is therefore in the RMS context that we will present them. We will not use any predefined function, only Faust primitives, so that you can see all the details. The text is intended for beginners, but with some basic knowledge of Faust. If this is not your case have a look at the various documentations on this website.","title":"RMS and Summation in Faust"},{"location":"tutorials/summation/#rms-value","text":"The computation of the RMS (Root Mean Square) value of a signal is defined by the following Faust expression: ^(2) : summation : /(n) : sqrt where n is the number of consecutive samples considered. This expression involves several steps: First, we take the square of the signal: ^(2) . This is the S of RMS. Then we sum the n consecutive samples: summation and divide this sum by n to get the mean value: /(n) . This is the M of RMS. Finally, we take the square root sqrt . This is the R of RMS. In other words, RMS is written S:M:R in Faust (leaving the summation function undefined for the moment): RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; }; In the following paragraphs, we will introduce 4 different techniques to write this summation function. We will assume that the audio samples are between -1 and 1.","title":"RMS value"},{"location":"tutorials/summation/#sliding-sum","text":"Let's start with the sliding sum approach, probably the simplest way to efficiently add n consecutive samples. First, let's recall that we can add up all the samples of a signal s , from time 0 to the present time, with the following expression: s : +~_ . The trick for adding only the last n samples is to subtract from this sum the same sum but as it was n samples earlier. For example, in order to keep only the sum of the last 10 samples, we just have to subtract from the sum of all samples (s:+~_) the value of this same sum 10 samples ago (s:+~_ : @(10)) : (s:+~_), (s:+~_ : @(10)) : - This expression can be further simplified by factoring s:+~_ . We then get: s : +~_ <: _, @(10) : - From a mathematical point of view, this is perfectly correct but poses problems when computed using floating-point numbers. Unlike mathematical numbers, floating-point numbers have a limited precision (23 bits in single precision). When calculating the RMS value, we only add positive numbers. Therefore the sum will increase forever. But at some point, when the sum exceeds 2^{23} \u200b, the least significant bit will be higher than any number between 0 \u200b and 1 \u200b. Therefore adding such a small number will be exactly like adding 0, and the sum will never evolve anymore. Fortunately, the problem can be solved easily. We just have to swap the integration and the difference parts: s <: _, @(10) : - : +~_ This new formulation is identical to the previous one from a mathematical point of view. But now, the sum will always stay between -10\u200b and +10 \u200b\u200b, and the accuracy problems are only on the least significant bits. If the roundoff error due to quantization is modeled as a uniformly distributed random number between -q/2 and q/2, then its variance (mean square) is q^2/12, and this value increases linearly over time in a running sum (see \"Wiener process\"). Thus, we expect the roundoff error in a running-sum rms calculator to grow proportional to the square root of time. We can now complete the definition of RMS: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = _ <: _, @(n) : - : +~_; };","title":"Sliding Sum"},{"location":"tutorials/summation/#fix-point-sliding-sum","text":"While the previous solution works very well with typical signals over practical time spans, the roundoff error continues to grow slowly. To avoid a gradual loss of precision, we can use a fix-point encoding of the samples, so that the subtraction after delay is always exact. Let's say that we want a sliding sum of 10 values between 0 and 1. We know that this sum will never exceed 2^4 \u200b\u200b\u200b. We could therefore use up to 27 bits (31-4) to code the fractional part of values. The conversions are straightforward. To convert floating-point values to fix-point we can use the following expression: *(2^27):int . To convert back from fix-point to floating-point we can use the inverse expression: float:/(2^27) . We can now complete the definition of RMS. As we can see in the summation definition below, we first convert the samples to fix-point, do the summation on integers, then convert the result back to floating-point: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = float2fix(16) : _ <: _, @(n) : - : +~_ : fix2float(16); float2fix(p) = *(2^p) : int; fix2float(p) = float : /(2^p); }; Obviously this is correct only if we let enough bits for the integral part. Here we have 15 bits (31-16), enough for n up to 32000 samples.","title":"Fix-Point Sliding Sum"},{"location":"tutorials/summation/#block-sum","text":"Sliding sums have a nice and smooth behavior because an updated sum is produced every sample. But they require a large delay line (larger than n \u200b)\u200b\u200b, and can have precision problems. In this third approach, we will use a summation by blocks. The summation will be exact, will not require a large delay line, but will be only updated once per block of n samples. The code is a little bit more involved. It will require a phase signal: 0,1,2,3,\\ldots,n-1,0,1\\ldots \u200b,\u200b\u200b\u200b and a capture (sample and hold) operation. Let's start with a simplified version derived from: s:+~_ . Remind that _ is the identity function and is equivalent to *(1) . We can therefore rewrite the previous expression s:+~*(1) . Now, imagine that instead of 1 we have a boolean b as in: s:~*(b) . When b is 1 the input sample is added to the previous sum, but when b is 0 the input sample is added to 0 , and the sum is reset to be the input sample. In our case, we want to reset the sum after every block of n samples, that is, every time phase returns to 0 . This can be written: s:+~*(phase!=0) . Note that we can't use the output of this expression directly. It only represents the sum we are looking for when phase==(n-1) . That is why we need an additional capture stage to sample the sum and hold it while the next block is processed. Let's say that b indicates when to capture the input value, then: select2(b)~_ will do the job. When b is 0 , it reproduces the feedback signal, and when b is 1 , it captures the input signal. Here is the full implementation: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; summation = + ~ *(phase != 0) : capture(phase==(n-1)); phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; };","title":"Block Sum"},{"location":"tutorials/summation/#overlapping-block-sum","text":"As we mentioned, the block sum has the disadvantage of producing a new value only once per block. If the blocks are large, this can be a problem. In this fourth approach, we will see how to overlap the produced values. For example, we would like to compute the sum of the last 1000 samples, but with a new result every 250 samples (i.e., an overlap of 75%). The principle will be to sum small blocks of 250 samples, keep the last four sums, and add them together to produce, every 250 samples, a new sum of the last 1000 samples. Let's call w the size of a small block, and c the number of small blocks in a large block of n samples (i.e., n=c*w )\u200b. Instead of computing sums of n samples as with: + ~ *(phase != 0) , we compute sums of w samples: + ~ *(phase%w != 0) . Instead of having one capture every n samples: capture(phase == (n-1)) , we need c captures in parallel at 1*w-1 , 2*w-1 , etc.: par(i,c, capture( phase == (w*(i+1) - 1) )) Here is the full code: RMS(n) = S:M:R with { S = ^(2); M = summation : /(n); R = sqrt; c = 4; // number of overlaps summation = + ~ *(phase%w != 0) <: par(i, c, capture( phase == (w*(i+1) - 1) )) :> _ with { w = n/c; }; phase = 1 : (+,n:%)~_; capture(b) = select2(b)~_; };","title":"Overlapping Block Sum"},{"location":"tutorials/summation/#comparing-all-the-solutions","text":"Using the Faust IDE, we can easily compare all these solutions. To encapsulate all the definitions and select the RMS implementation, we will use an environment. If you are not familiar with the concept of environment, it is a way to group definitions. The screen shot of the Faust IDE below shows the RMS values of testsource according to the 4 methods: Sliding Sum , Fix-Point Sliding Sum , Block Sum , and Overlapping Block Sum .","title":"Comparing all the solutions"},{"location":"tutorials/teensy/","text":"DSP on the Teensy With Faust Introduction The Teensy is a development board series based on a microcontroller and distributed by PJRC . The Teensys 3.(2+) are based on an ARM Cortex-M4 providing plenty of computational power for real-time audio signal processing applications. In particular, the Cortex-M4 used on the Teensy 3.6 (MK66FX1M0VMD18) hosts a Floating Point Unit (FPU) and has a clock of 180MHz (overclockable at 240MHz). Also, PJRC recently released the Teensy 4.0 which is based on a Cortex-M7 (FPU) with a clock of 600MHz and much more memory than the 3.6. When combined with their respective audio shields (also distributed by PJRC), the Teensy 3.6/4.0 can be used to synthesize and process sound with advanced algorithms, etc. This paper provides a survey on the performances of such system when used with Faust-generated DSP objects. The Teensy and Its Audio Shield Using this type of chip for embedded real-time audio DSP presents a wide range of advantages: low power consumption (i.e., can be easily powered by a battery), bare-metal: the lack of operating system allows for the use of very low block sizes (i.e., as low as 8 samples on the Teensy) and therefore extremely low latency, very short boot time (<1s), etc. The Teensy/ Teensyduino comes with an Audio Library that can be used to synthesize sound directly on the Teensy. It uses a patching paradigm where DSP objects can be connected together using virtual patch chords. An online tool provides a user interface to this system and allows for the implementation of sound processing algorithms in a \"Max/MSP way.\" Various elements can be used as the input and the output of the system (e.g., built-in Teensy DAC/ADC, audio shield, etc.). More information and tutorials can be found on the Audio Library webpage . The current DSP objects of the Teensy Audio Library can be used to implement simple algorithms but their scope is relatively limited (i.e., basic oscillators, filters, etc.). faust2teensy can be used to implement new objects for the Teensy Audio Library using Faust. Since Faust is currently not able to produce fixed-point DSP C++ code, generated object use floating point arithmetic internally. The main consequence is that this system will only work efficiently if it's used on a Teensy board hosting an FPU. Hence, we strongly recommend you to use the Teensy 3.6/4.0 for this (things will work on the 3.2, but computational power will be extremely limited). This tutorial walks you through the steps of synthesizing sound with Faust on the Teensy. Band-Limited Sawtooth Oscillator on the Teensy The source code of the section can be downloaded here The Teensy Audio Library doesn't come with any band-limited sawtooth wave oscillator (which are crucial to the implementation of good quality virtual analog synthesizer). The Faust libraries come with a wide range of band-limited oscillators that can be easily ported to the Teensy. The following program ( FaustSawtooth.dsp ) implements a sawtooth wave oscillator with controllable gain and frequency: si.smoo is used to interpolate the values of the freq and gain parameters to prevent clicks and abrupt changes. This Faust program can be turned into an object for the Teensy Audio Library simply by running the following command in a terminal: faust2teensy -lib FaustSawtooth.dsp which will generate a zip file containing a .cpp and a .h file in return. Alternatively, the Faust online compilation service can be used through the Faust Web IDE to carry out this task (Export(Truck)/source/teensy). The generated package should contain a file called FaustSawtooth.cpp and FaustSawtooth.h . Create a new project in the Arduino/Teensyduino software (e.g., call it faustSawtooth ) and place FaustSawtooth.cpp and FaustSawtooth.h in the same folder (whose name should probably be /faustSawtooth ) than faustSawtooth.ino . Replace the content of the Arduino program with the following: #include <Audio.h> #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,0,out,1); void setup() { AudioMemory(2); audioShield.enable(); audioShield.volume(0.1); } void loop() { faustSawtooth.setParamValue(\"freq\",random(50,1000)); delay(50); } First, the header file ( .h ) of the object generated with faust2teensy is included. An instance of FaustSawtooth is then created. Since the Teensy (3.6/4.0) that we're using for this tutorial is equipped with a Teensy Audio Shied, we also create an instance of AudioOutputI2S and AudioControlSGTL5000 . We then connect the Faust object to the 2 outputs of the audio shield using AudioConnection s. Note that if the Faust object had a stereo output (i.e., process = os.sawtooth(freq)*gain <: _,_ ), the following should have been written instead: AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,1,out,1); The number of inputs and outputs of objects generated with faust2teensy corresponds to the number inputs and outputs of the Faust program. 2 bytes of memory are allocated in setup() . Note that if the Faust object had audio inputs, this number should probably be greater (i.e., typically 6 for stereo in and stereo out). audioShield.enable() activates the audio shield and audioShield.volume(0.1) sets the gain of the headphone output (this step is optional). The value of the freq and gain parameters can be set using the setParamValue method. Note that for larger Faust objects, parameter paths might be used instead. Here, the value of freq is randomly generated every 50ms. After making these changes, you should be able to compile and upload your sketch to the Teensy 4.0. Special Note About the Teensy 3.6 Before this program can be compiled and uploaded to the Teensy 3.6, some modifications need to be made to the configuration file used by the compilation script used by Teensyduino ( boards.txt ). You should be able to find it in hardware/teensy/avr in the source of the Arduino software (its location will vary depending on the platform your using). The most important thing to do here is to use g++ instead of gcc for linking, so: teensy36.build.command.linker=arm-none-eabi-gcc should become: teensy36.build.command.linker=arm-none-eabi-g++ in boards.txt . Beware that on older versions of Teensyduino, these changes should be made directly to platform.txt . After making these changes, you should be able to compile and upload your sketch to the Teensy 3.6. Audio Effect The source code of the section can be downloaded here The same procedure as the one described in the previous section can be followed to generate audio effects for the Teensy Audio Library. dm.zita_light implements a high quality stereo feedback delay network reverb. It hosts its own user interface elements/parameters to control its dry/wet mix ( Dry/Wet Mix ) and its level in dB ( Level ). A simple Faust program ( FaustZita.dsp ) calling this effect could look like that: The corresponding Teensy Audio Library object can be generated by running: faust2teensy -lib FaustZita.dsp and finally called in a Teensy program: #include <Audio.h> #include \"FaustZita.h\" FaustZita faustZita; AudioInputI2S in; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(in,0,faustZita,0); AudioConnection patchCord1(in,1,faustZita,1); AudioConnection patchCord2(faustZita,0,out,0); AudioConnection patchCord3(faustZita,1,out,1); void setup() { AudioMemory(6); audioShield.enable(); faustZita.setParamValue(\"level\",0); } void loop() { float dw = analogRead(A0)/512 - 1; faustZita.setParamValue(\"dryWet\",dw); delay(10); } Note that in this example, a potentiometer connected to the Analog Input 0 of the Teensy is used to control the dry/wet mix of the reverb. Additional Configuration for Low Audio Latency Thanks to its bare-metal architecture, the Teensy allows for extremely low audio latency which would be more or less impossible to achieve if an operating system was used. Audio latency is mostly determined by the block size of the system. The default block size of the Teensy Audio Library is 128 samples but it can be cranked down to 8 samples (only if Faust DSP objects are used exclusively) without impacting performances too much (see the corresponding SMC paper ). Block size is set by a C++ macro ( AUDIO_BLOCK_SAMPLES ) that can be overridden before compilation by passing it as an argument to the C++ compiler by substituting the following line in boards.txt (see previous section): teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 3.6, and: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 4.0. Similarly, the sampling rate (44100KHz by default) can be set using the AUDIO_SAMPLE_RATE_EXACT macro. Note that computing the \"exact\" sampling rate compatible with the clock of your Teensy might be a bit tricky. For example, AUDIO_SAMPLE_RATE_EXACT is 44117.64706 by default and not 44100, etc. Warning!!! In the latest version of the Teensy Audio Library, a \"weird\" correction to the code of the built-in freeverb function has been made an will prevent you from using a block size of 8 samples. Here's a fix to this problem that should be made in the installed version of effect_freeverb.cpp : 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0, #if AUDIO_BLOCK_SAMPLES > 8 0, 0, 0, 0, 0, 0, 0, 0, #endif #if AUDIO_BLOCK_SAMPLES > 16 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, #endif Notes About Computational Power and Memory Footprint While the Teensy 3.6 is relatively powerful and can be used to run complex DSP algorithm (up to 90 Faust sine waves in parallel), it doesn't have a lot of RAM. For that reason, algorithms with a large memory footprint (e.g., anything using delay a lot such a reverbs, wave table oscillators, etc.) might have to be adapted to be run on the Teensy. For example, the default Faust sine wave oscillator uses a table of 65536 samples which is to big to be loaded in the Teensy RAM. Hence, its definition should be adapted, e.g.: osc(freq) = rdtable(tablesize, os.sinwaveform(tablesize), int(os.phasor(tablesize,freq))) with{ tablesize = 1 << 15; // instead of 1 << 16 }; Similarly, the maximum size of the delay lines of some reverb algorithms might be too big and should be adjusted. Using the -dlt option can help, see the Managing DSP Memory Size section.","title":"DSP on the Teensy With Faust"},{"location":"tutorials/teensy/#dsp-on-the-teensy-with-faust","text":"","title":"DSP on the Teensy With Faust"},{"location":"tutorials/teensy/#introduction","text":"The Teensy is a development board series based on a microcontroller and distributed by PJRC . The Teensys 3.(2+) are based on an ARM Cortex-M4 providing plenty of computational power for real-time audio signal processing applications. In particular, the Cortex-M4 used on the Teensy 3.6 (MK66FX1M0VMD18) hosts a Floating Point Unit (FPU) and has a clock of 180MHz (overclockable at 240MHz). Also, PJRC recently released the Teensy 4.0 which is based on a Cortex-M7 (FPU) with a clock of 600MHz and much more memory than the 3.6. When combined with their respective audio shields (also distributed by PJRC), the Teensy 3.6/4.0 can be used to synthesize and process sound with advanced algorithms, etc. This paper provides a survey on the performances of such system when used with Faust-generated DSP objects. The Teensy and Its Audio Shield Using this type of chip for embedded real-time audio DSP presents a wide range of advantages: low power consumption (i.e., can be easily powered by a battery), bare-metal: the lack of operating system allows for the use of very low block sizes (i.e., as low as 8 samples on the Teensy) and therefore extremely low latency, very short boot time (<1s), etc. The Teensy/ Teensyduino comes with an Audio Library that can be used to synthesize sound directly on the Teensy. It uses a patching paradigm where DSP objects can be connected together using virtual patch chords. An online tool provides a user interface to this system and allows for the implementation of sound processing algorithms in a \"Max/MSP way.\" Various elements can be used as the input and the output of the system (e.g., built-in Teensy DAC/ADC, audio shield, etc.). More information and tutorials can be found on the Audio Library webpage . The current DSP objects of the Teensy Audio Library can be used to implement simple algorithms but their scope is relatively limited (i.e., basic oscillators, filters, etc.). faust2teensy can be used to implement new objects for the Teensy Audio Library using Faust. Since Faust is currently not able to produce fixed-point DSP C++ code, generated object use floating point arithmetic internally. The main consequence is that this system will only work efficiently if it's used on a Teensy board hosting an FPU. Hence, we strongly recommend you to use the Teensy 3.6/4.0 for this (things will work on the 3.2, but computational power will be extremely limited). This tutorial walks you through the steps of synthesizing sound with Faust on the Teensy.","title":"Introduction"},{"location":"tutorials/teensy/#band-limited-sawtooth-oscillator-on-the-teensy","text":"The source code of the section can be downloaded here The Teensy Audio Library doesn't come with any band-limited sawtooth wave oscillator (which are crucial to the implementation of good quality virtual analog synthesizer). The Faust libraries come with a wide range of band-limited oscillators that can be easily ported to the Teensy. The following program ( FaustSawtooth.dsp ) implements a sawtooth wave oscillator with controllable gain and frequency: si.smoo is used to interpolate the values of the freq and gain parameters to prevent clicks and abrupt changes. This Faust program can be turned into an object for the Teensy Audio Library simply by running the following command in a terminal: faust2teensy -lib FaustSawtooth.dsp which will generate a zip file containing a .cpp and a .h file in return. Alternatively, the Faust online compilation service can be used through the Faust Web IDE to carry out this task (Export(Truck)/source/teensy). The generated package should contain a file called FaustSawtooth.cpp and FaustSawtooth.h . Create a new project in the Arduino/Teensyduino software (e.g., call it faustSawtooth ) and place FaustSawtooth.cpp and FaustSawtooth.h in the same folder (whose name should probably be /faustSawtooth ) than faustSawtooth.ino . Replace the content of the Arduino program with the following: #include <Audio.h> #include \"FaustSawtooth.h\" FaustSawtooth faustSawtooth; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,0,out,1); void setup() { AudioMemory(2); audioShield.enable(); audioShield.volume(0.1); } void loop() { faustSawtooth.setParamValue(\"freq\",random(50,1000)); delay(50); } First, the header file ( .h ) of the object generated with faust2teensy is included. An instance of FaustSawtooth is then created. Since the Teensy (3.6/4.0) that we're using for this tutorial is equipped with a Teensy Audio Shied, we also create an instance of AudioOutputI2S and AudioControlSGTL5000 . We then connect the Faust object to the 2 outputs of the audio shield using AudioConnection s. Note that if the Faust object had a stereo output (i.e., process = os.sawtooth(freq)*gain <: _,_ ), the following should have been written instead: AudioConnection patchCord0(faustSawtooth,0,out,0); AudioConnection patchCord1(faustSawtooth,1,out,1); The number of inputs and outputs of objects generated with faust2teensy corresponds to the number inputs and outputs of the Faust program. 2 bytes of memory are allocated in setup() . Note that if the Faust object had audio inputs, this number should probably be greater (i.e., typically 6 for stereo in and stereo out). audioShield.enable() activates the audio shield and audioShield.volume(0.1) sets the gain of the headphone output (this step is optional). The value of the freq and gain parameters can be set using the setParamValue method. Note that for larger Faust objects, parameter paths might be used instead. Here, the value of freq is randomly generated every 50ms. After making these changes, you should be able to compile and upload your sketch to the Teensy 4.0.","title":"Band-Limited Sawtooth Oscillator on the Teensy"},{"location":"tutorials/teensy/#special-note-about-the-teensy-36","text":"Before this program can be compiled and uploaded to the Teensy 3.6, some modifications need to be made to the configuration file used by the compilation script used by Teensyduino ( boards.txt ). You should be able to find it in hardware/teensy/avr in the source of the Arduino software (its location will vary depending on the platform your using). The most important thing to do here is to use g++ instead of gcc for linking, so: teensy36.build.command.linker=arm-none-eabi-gcc should become: teensy36.build.command.linker=arm-none-eabi-g++ in boards.txt . Beware that on older versions of Teensyduino, these changes should be made directly to platform.txt . After making these changes, you should be able to compile and upload your sketch to the Teensy 3.6.","title":"Special Note About the Teensy 3.6"},{"location":"tutorials/teensy/#audio-effect","text":"The source code of the section can be downloaded here The same procedure as the one described in the previous section can be followed to generate audio effects for the Teensy Audio Library. dm.zita_light implements a high quality stereo feedback delay network reverb. It hosts its own user interface elements/parameters to control its dry/wet mix ( Dry/Wet Mix ) and its level in dB ( Level ). A simple Faust program ( FaustZita.dsp ) calling this effect could look like that: The corresponding Teensy Audio Library object can be generated by running: faust2teensy -lib FaustZita.dsp and finally called in a Teensy program: #include <Audio.h> #include \"FaustZita.h\" FaustZita faustZita; AudioInputI2S in; AudioOutputI2S out; AudioControlSGTL5000 audioShield; AudioConnection patchCord0(in,0,faustZita,0); AudioConnection patchCord1(in,1,faustZita,1); AudioConnection patchCord2(faustZita,0,out,0); AudioConnection patchCord3(faustZita,1,out,1); void setup() { AudioMemory(6); audioShield.enable(); faustZita.setParamValue(\"level\",0); } void loop() { float dw = analogRead(A0)/512 - 1; faustZita.setParamValue(\"dryWet\",dw); delay(10); } Note that in this example, a potentiometer connected to the Analog Input 0 of the Teensy is used to control the dry/wet mix of the reverb.","title":"Audio Effect"},{"location":"tutorials/teensy/#additional-configuration-for-low-audio-latency","text":"Thanks to its bare-metal architecture, the Teensy allows for extremely low audio latency which would be more or less impossible to achieve if an operating system was used. Audio latency is mostly determined by the block size of the system. The default block size of the Teensy Audio Library is 128 samples but it can be cranked down to 8 samples (only if Faust DSP objects are used exclusively) without impacting performances too much (see the corresponding SMC paper ). Block size is set by a C++ macro ( AUDIO_BLOCK_SAMPLES ) that can be overridden before compilation by passing it as an argument to the C++ compiler by substituting the following line in boards.txt (see previous section): teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy36.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 3.6, and: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 with: teensy40.build.flags.defs=-D__MK66FX1M0__ -DTEENSYDUINO=146 -DAUDIO_BLOCK_SAMPLES=8 on the Teensy 4.0. Similarly, the sampling rate (44100KHz by default) can be set using the AUDIO_SAMPLE_RATE_EXACT macro. Note that computing the \"exact\" sampling rate compatible with the clock of your Teensy might be a bit tricky. For example, AUDIO_SAMPLE_RATE_EXACT is 44117.64706 by default and not 44100, etc.","title":"Additional Configuration for Low Audio Latency"},{"location":"tutorials/teensy/#warning","text":"In the latest version of the Teensy Audio Library, a \"weird\" correction to the code of the built-in freeverb function has been made an will prevent you from using a block size of 8 samples. Here's a fix to this problem that should be made in the installed version of effect_freeverb.cpp : 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0, #if AUDIO_BLOCK_SAMPLES > 8 0, 0, 0, 0, 0, 0, 0, 0, #endif #if AUDIO_BLOCK_SAMPLES > 16 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, #endif","title":"Warning!!!"},{"location":"tutorials/teensy/#notes-about-computational-power-and-memory-footprint","text":"While the Teensy 3.6 is relatively powerful and can be used to run complex DSP algorithm (up to 90 Faust sine waves in parallel), it doesn't have a lot of RAM. For that reason, algorithms with a large memory footprint (e.g., anything using delay a lot such a reverbs, wave table oscillators, etc.) might have to be adapted to be run on the Teensy. For example, the default Faust sine wave oscillator uses a table of 65536 samples which is to big to be loaded in the Teensy RAM. Hence, its definition should be adapted, e.g.: osc(freq) = rdtable(tablesize, os.sinwaveform(tablesize), int(os.phasor(tablesize,freq))) with{ tablesize = 1 << 15; // instead of 1 << 16 }; Similarly, the maximum size of the delay lines of some reverb algorithms might be too big and should be adjusted. Using the -dlt option can help, see the Managing DSP Memory Size section.","title":"Notes About Computational Power and Memory Footprint"},{"location":"tutorials/unity/","text":"Faust and Unity TODO","title":"Faust and Unity"},{"location":"tutorials/unity/#faust-and-unity","text":"TODO","title":"Faust and Unity"},{"location":"workshops/2018-12-01-paw/","text":"Building a Simple MIDI Synthesizer We are going to build a MIDI synthesizer from scratch (without using the Faust libraries). Phase Generator The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate: Ramp In order to produce the above signal we need first to produce a ramp signal using the following Faust program: You can think of a Faust program as a description of an audio circuit where 0.125 , + and _ are primitives of the language (predefined elementary audio components), and the other two signs: : and ~ are used to connect together these audio components. Semantics To understand the above diagram let's annotate it with its mathematical semantics. As we can see in the diagram, the formula of the output signal is: y(t) = y(t-1) + 0.125 We can compute the first values of y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Phase Signal How can we transform the above ramp into sawtooth signal ? By removing the integer part of the samples in order to keep only the decimal (fractional) part ( 3.14159 -> 0.14159 ). Let's define a function to do that: decimalpart(x) = x - int(x); We can now use that function to transform our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view that would be perfectly correct, but we will accumulate rounding errors. To keep full precision it is better to place the decimal part operation inside the loop: process = 0.125 : (+ : decimalpart) ~ _; We can now listen the produced signal. Just copy and past decimalpart and process definitions into the Faust Web IDE . Controlling the Frequency of the Phase Signal Let's first rearrange our code: In our phase definition the step value, here 0.125 controls the frequency of the generated signal. We would like to compute this step value according to the desired frequency. In order to do the conversion we need to know the sampling rate. It is available from the standard library as ma.SR . Let say we would like our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR so that is will take ma.SR samples (i.e. 1 second) for the phase signal to reach 1. If we want a frequency of 440 Hz, we need a step 440 times bigger for the phase signal to reach 1 440 times faster. phase = 440/ma.SR : (+ : decimalpart) ~ _; We can generalize this definition by replacing 440 by a parameter f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and by indicating the desired frequency when we use phase : process = phase(440); Creating a Sine Wave Oscillator The next step is to transform above phase generator into a sine wave generator. We will use the sin primitive that computes the sine of x (measured in radians). Therefore we start for the phase signal, we multiply it by 2PI to obtain radiants, and compute the sine. The full program is the following: Controlling the Frequency and Gain of the Oscillator The next step is to add some controls on the frequency and gain of the oscillator. We can replace the fixed frequency 440 by a user interface slider: process = osc(hslider(\"freq\", 440, 20, 10000, 1)); and add a gain to control the output level of the oscillator: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01); Adding a Gate Button In order to prepare our MIDI synthesizer we need to add a gate button so that the sound is only when we press it: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01) * button(\"gate\"); Adding an Envelope Generator It is a good idea to also add an envelop generator. Here we will use a predefined ADSR in the Standard Faust library. Improving the Timbre Instead of playing pure sine waves tones, let's improve the timbre with simple additive synthesis: Running as a Polyphonic MIDI Synth To control the synthesizer using MIDI you need to use Chrome. The polyphonic MIDI mode is activated using the drop down menu Poly Voices on the left side of the editor. Choose Computer Keyboard as MIDI input to play notes with the computer keyboard, or plug a MIDI keyboard. Adding a Global Effect A global effect can be added by providing a definition for effect . // Common effect effect = dm.zita_light;","title":" 2018-12-01 PAW "},{"location":"workshops/2018-12-01-paw/#building-a-simple-midi-synthesizer","text":"We are going to build a MIDI synthesizer from scratch (without using the Faust libraries).","title":"Building a Simple MIDI Synthesizer"},{"location":"workshops/2018-12-01-paw/#phase-generator","text":"The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate:","title":"Phase Generator"},{"location":"workshops/2018-12-01-paw/#ramp","text":"In order to produce the above signal we need first to produce a ramp signal using the following Faust program: You can think of a Faust program as a description of an audio circuit where 0.125 , + and _ are primitives of the language (predefined elementary audio components), and the other two signs: : and ~ are used to connect together these audio components.","title":"Ramp"},{"location":"workshops/2018-12-01-paw/#semantics","text":"To understand the above diagram let's annotate it with its mathematical semantics. As we can see in the diagram, the formula of the output signal is: y(t) = y(t-1) + 0.125 We can compute the first values of y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"Semantics"},{"location":"workshops/2018-12-01-paw/#phase-signal","text":"How can we transform the above ramp into sawtooth signal ? By removing the integer part of the samples in order to keep only the decimal (fractional) part ( 3.14159 -> 0.14159 ). Let's define a function to do that: decimalpart(x) = x - int(x); We can now use that function to transform our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view that would be perfectly correct, but we will accumulate rounding errors. To keep full precision it is better to place the decimal part operation inside the loop: process = 0.125 : (+ : decimalpart) ~ _; We can now listen the produced signal. Just copy and past decimalpart and process definitions into the Faust Web IDE .","title":"Phase Signal"},{"location":"workshops/2018-12-01-paw/#controlling-the-frequency-of-the-phase-signal","text":"Let's first rearrange our code: In our phase definition the step value, here 0.125 controls the frequency of the generated signal. We would like to compute this step value according to the desired frequency. In order to do the conversion we need to know the sampling rate. It is available from the standard library as ma.SR . Let say we would like our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR so that is will take ma.SR samples (i.e. 1 second) for the phase signal to reach 1. If we want a frequency of 440 Hz, we need a step 440 times bigger for the phase signal to reach 1 440 times faster. phase = 440/ma.SR : (+ : decimalpart) ~ _; We can generalize this definition by replacing 440 by a parameter f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and by indicating the desired frequency when we use phase : process = phase(440);","title":"Controlling the Frequency of the Phase Signal"},{"location":"workshops/2018-12-01-paw/#creating-a-sine-wave-oscillator","text":"The next step is to transform above phase generator into a sine wave generator. We will use the sin primitive that computes the sine of x (measured in radians). Therefore we start for the phase signal, we multiply it by 2PI to obtain radiants, and compute the sine. The full program is the following:","title":"Creating a Sine Wave Oscillator"},{"location":"workshops/2018-12-01-paw/#controlling-the-frequency-and-gain-of-the-oscillator","text":"The next step is to add some controls on the frequency and gain of the oscillator. We can replace the fixed frequency 440 by a user interface slider: process = osc(hslider(\"freq\", 440, 20, 10000, 1)); and add a gain to control the output level of the oscillator: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01);","title":"Controlling the Frequency and Gain of the Oscillator"},{"location":"workshops/2018-12-01-paw/#adding-a-gate-button","text":"In order to prepare our MIDI synthesizer we need to add a gate button so that the sound is only when we press it: process = osc(hslider(\"freq\", 440, 20, 10000, 1)) * hslider(\"gain\", 0.5, 0, 1, 0.01) * button(\"gate\");","title":"Adding a Gate Button"},{"location":"workshops/2018-12-01-paw/#adding-an-envelope-generator","text":"It is a good idea to also add an envelop generator. Here we will use a predefined ADSR in the Standard Faust library.","title":"Adding an Envelope Generator"},{"location":"workshops/2018-12-01-paw/#improving-the-timbre","text":"Instead of playing pure sine waves tones, let's improve the timbre with simple additive synthesis:","title":"Improving the Timbre"},{"location":"workshops/2018-12-01-paw/#running-as-a-polyphonic-midi-synth","text":"To control the synthesizer using MIDI you need to use Chrome. The polyphonic MIDI mode is activated using the drop down menu Poly Voices on the left side of the editor. Choose Computer Keyboard as MIDI input to play notes with the computer keyboard, or plug a MIDI keyboard.","title":"Running as a Polyphonic MIDI Synth"},{"location":"workshops/2018-12-01-paw/#adding-a-global-effect","text":"A global effect can be added by providing a definition for effect . // Common effect effect = dm.zita_light;","title":"Adding a Global Effect"},{"location":"workshops/2020-03-24-faust-citi/","text":"Faust workshop at CITI L'objectif de ce workshop est de se familiariser avec le langage Faust \u00e0 travers des exemples simples de synth\u00e8se sonore. Tous les exemples seront execut\u00e9 dans l'IDE Faust en ligne https://faustide.grame.fr . Si jamais les sons produits avec l'IDE sont de mauvaise qualit\u00e9, avec des clics, on peut utiliser l'\u00e9diteur en ligne, plus rustique, mais aussi plus l\u00e9ger https://fausteditor.grame.fr Signal en dent de scie Par convention, en Faust, un signal audio \u00e0 pleine \u00e9chelle varie entre -1 et +1. Mais dans un premier temps nous allons commencer par un signal en dent de scie entre 0 et 1 qui nous servira par la suite de g\u00e9n\u00e9rateur de phase pour produire diff\u00e9rentes formes d'onde. G\u00e9n\u00e9rateur de Phase La premi\u00e8re \u00e9tape consiste \u00e0 construire un g\u00e9n\u00e9rateur de phase qui produit un signal p\u00e9riodique en dents de scie entre 0 et 1. Voici le signal que nous voulons g\u00e9n\u00e9rer : Rampe Pour cela nous allons produire une rampe \"infinie\", que nous transformerons ensuite en un signal p\u00e9riodique gr\u00e2ce \u00e0 une op\u00e9ration partie-decimale : La rampe est produite par le programme suivant : S\u00e9mantique Dans l'exemple pr\u00e9c\u00e9dent, 0,125 , + et _ sont des primitives du langage. Les deux autres signes : : et ~ sont des op\u00e9rateurs de cablage. Ils sont utilis\u00e9s pour relier entre elles les expressions du langage. Pour comprendre le diagramme ci-dessus, nous allons l'annoter avec sa s\u00e9mantique math\u00e9matique : Comme on peut le voir dans le diagramme, la formule du signal de sortie est : y(t) = y(t-1) + 0.125 On peut calculer les premi\u00e8res valeurs de y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Signal de phase Comment transformer la rampe ci-dessus en signal en dents de scie ? En supprimant la partie enti\u00e8re des \u00e9chantillons afin de ne garder que la partie d\u00e9cimale (fractionnaire) ( 3.14159 -> 0.14159 ). D\u00e9finissons une fonction pour faire cela : decimalpart(x) = x - int(x); Nous pouvons maintenant utiliser cette fonction pour transformer notre rampe en dents de scie. Il est alors tentant d'\u00e9crire : process = 0.125 : + ~ _ : decimalpart; D'un point de vue math\u00e9matique, ce serait parfaitement correct, mais nous allons accumuler les erreurs d'arrondi. Pour conserver une pr\u00e9cision totale, il est pr\u00e9f\u00e9rable de placer l'op\u00e9ration de la partie d\u00e9cimale \u00e0 l'int\u00e9rieur de la boucle comme ceci : process = 0.125 : (+ : decimalpart) ~ _; On peut maintenant essayer l'ensemble du code ( pensez \u00e0 baisser le volume ) : Dans notre d\u00e9finition de la phase , la valeur du pas, ici 0,125 , contr\u00f4le la fr\u00e9quence du signal g\u00e9n\u00e9r\u00e9. Nous aimerions calculer cette valeur de pas en fonction de la fr\u00e9quence souhait\u00e9e. Afin de faire la conversion, nous devons conna\u00eetre la fr\u00e9quence d'\u00e9chantillonnage. Elle est disponible dans la biblioth\u00e8que standard sous le nom de ma.SR . Pour utiliser cette biblioth\u00e8que standard nous ajoutons au programme la ligne suivante : import(\"stdfaust.lib\"); Supposons que nous voulions que notre signal de phase ait une fr\u00e9quence de 1 Hz, alors le pas devrait \u00eatre tr\u00e8s petit 1/ma.SR , afin qu'il faille ma.SR \u00e9chantillons (c'est \u00e0 dire 1 seconde) pour que le signal de phase passe de 0 \u00e0 1. Si nous voulons une fr\u00e9quence de 440 Hz, nous avons besoin d'un pas 440 fois plus grand pour que le signal de phase passe de 0 \u00e0 1 440 fois plus vite : phase = 440/ma.SR : (+ : decimalpart) ~ _; On peut g\u00e9n\u00e9raliser cette d\u00e9finition en rempla\u00e7ant 440 par un param\u00e8tre f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; et en passant la fr\u00e9quence souhait\u00e9e \u00e0 phase : process = phase(440); Generateur de signal en dent de scie Nous pouvons maintenant nous servir du g\u00e9n\u00e9rateur de phase pour produire un signal en dent de scie : Generateur de signal carr\u00e9 Nous pouvons \u00e9galement nous servir du g\u00e9n\u00e9rateurr de phase pour produire un signal carr\u00e9 : Synth\u00e8se additive Exemple 1 : g\u00e9n\u00e9rateur sinusoidal Le g\u00e9n\u00e9rateur de phase est \u00e9galement \u00e0 la base de l'oscillateur sinusoidal : Mais maintenant que nous avons vu comment cr\u00e9er de toutes pi\u00e8ces un oscillateur sinusoidal, nous allons utiliser celui qui est d\u00e9fini dans la libraries standard de Faust : Exemple 2 : une onde sinusoidale avec controle de volume Dans ce deuxi\u00e8me exemple on a utilis\u00e9 un slider horizontal hslider(...) pour r\u00e9gler le niveau sonore : Le premier param\u00e8tre est une chaine de caract\u00e8re qui indique le nom du slider. Il est suivi de quatre param\u00e8tres num\u00e9riques. Le deuxi\u00e8me param\u00e8tre 0.1 indique la valeur par d\u00e9faut du slider, c'est \u00e0 dire la valeur que va d\u00e9livrer le slider quand on lance le programme. Ensuite nous avons la valeur minimale 0 , la valeur maximale 1 et le pas de variation 0.01 . Exemple 3 : Exercice, ajouter un contr\u00f4le de fr\u00e9quence A titre d'exercice, remplacer, dans l'exemple pr\u00e9c\u00e9dent, la fr\u00e9quence 440 par un slider horizontal dont le nom sera \"freq\" , la valeur par d\u00e9faut 110 , la valeur minimale 40 , la valeur maximale 8000 et le pas 1 . Exemple 4 : Ph\u00e9nom\u00e8ne de repliement de fr\u00e9quence au-del\u00e0 de SR/2 Un probl\u00e8me bien connu dans le domaine de la synth\u00e8se num\u00e9rique du son est celui du repliement de fr\u00e9quence : toute fr\u00e9quence au dela de la moiti\u00e9 de la fr\u00e9quence d'\u00e9chatillonnage se retrouve repli\u00e9e dans le spectre audible : Exemple 5 : Synth\u00e8se additive Un exemple de synth\u00e8se additive ou le niveau de chaque partiel peut \u00eatre r\u00e9gl\u00e9 individuellement : A noter l'utilisation de la construction sum(i, n, foo(i)) qui est equivalente \u00e0 foo(0)+foo(1)+...+foo(n-1) . Exemple 6 : Approximation d'un signal carr\u00e9 par synth\u00e8se additive Nous avons vu pr\u00e9c\u00e9demment comment produire une signal carr\u00e9 parfait. Ce signal carr\u00e9 parfait comporte une infinit\u00e9 d'harmoniques qui, du fait de l'\u00e9chantillonnage, vont se replier sur le spectre audible, ce qui va donner un son bruit\u00e9 moins fid\u00e8le ! On peut approximer un signal carr\u00e9 par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques impaires (voir https://fr.wikipedia.org/wiki/Signal_carr\u00e9 ) : A titre d'excercice, faire varier le nombre d'harmoniques pour voir l'approximation s'am\u00e9liorer (mais sans d\u00e9passer SR/2). Exemple 7 : Approximation d'un signal en dent de scie par synth\u00e8se additive De m\u00eame on peut approximer un signal en dent de scie par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques (voir https://fr.wikipedia.org/wiki/Signal_en_dents_de_scie ) : Synth\u00e8se soustractive La synth\u00e8se soustractive proc\u00e8de \u00e0 l'inverse de la synth\u00e8se additive. Elle consiste \u00e0 partir d'un son riche, par exemple un bruit blanc, et \u00e0 sculpter son spectre. Exemple 1 : un bruit blanc Un bruit blanc : Exemple 2 : lowpass Exemple 3 : high pass Exemple 4 : bandpass Exemple 5 : resonnant Exemple 6 : fir Exemple 7 : iir Exemple 8 : filtre en peigne Exemple 9 : Karplus Strong (1/2) Exemple 10 : Karplus Strong (2/2) Exemple 11 : Kisana Synth\u00e8se par modulation de fr\u00e9quence Exemple 1 : fm1 Exemple 2 : fm2","title":" 2020-03-24 CITI "},{"location":"workshops/2020-03-24-faust-citi/#faust-workshop-at-citi","text":"L'objectif de ce workshop est de se familiariser avec le langage Faust \u00e0 travers des exemples simples de synth\u00e8se sonore. Tous les exemples seront execut\u00e9 dans l'IDE Faust en ligne https://faustide.grame.fr . Si jamais les sons produits avec l'IDE sont de mauvaise qualit\u00e9, avec des clics, on peut utiliser l'\u00e9diteur en ligne, plus rustique, mais aussi plus l\u00e9ger https://fausteditor.grame.fr","title":"Faust workshop at CITI"},{"location":"workshops/2020-03-24-faust-citi/#signal-en-dent-de-scie","text":"Par convention, en Faust, un signal audio \u00e0 pleine \u00e9chelle varie entre -1 et +1. Mais dans un premier temps nous allons commencer par un signal en dent de scie entre 0 et 1 qui nous servira par la suite de g\u00e9n\u00e9rateur de phase pour produire diff\u00e9rentes formes d'onde.","title":"Signal en dent de scie"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-phase","text":"La premi\u00e8re \u00e9tape consiste \u00e0 construire un g\u00e9n\u00e9rateur de phase qui produit un signal p\u00e9riodique en dents de scie entre 0 et 1. Voici le signal que nous voulons g\u00e9n\u00e9rer :","title":"G\u00e9n\u00e9rateur de Phase"},{"location":"workshops/2020-03-24-faust-citi/#rampe","text":"Pour cela nous allons produire une rampe \"infinie\", que nous transformerons ensuite en un signal p\u00e9riodique gr\u00e2ce \u00e0 une op\u00e9ration partie-decimale : La rampe est produite par le programme suivant :","title":"Rampe"},{"location":"workshops/2020-03-24-faust-citi/#semantique","text":"Dans l'exemple pr\u00e9c\u00e9dent, 0,125 , + et _ sont des primitives du langage. Les deux autres signes : : et ~ sont des op\u00e9rateurs de cablage. Ils sont utilis\u00e9s pour relier entre elles les expressions du langage. Pour comprendre le diagramme ci-dessus, nous allons l'annoter avec sa s\u00e9mantique math\u00e9matique : Comme on peut le voir dans le diagramme, la formule du signal de sortie est : y(t) = y(t-1) + 0.125 On peut calculer les premi\u00e8res valeurs de y(t) : y(t<0)=0 y(0) = y(-1) + 0.125 = 0.125 y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1.000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"S\u00e9mantique"},{"location":"workshops/2020-03-24-faust-citi/#signal-de-phase","text":"Comment transformer la rampe ci-dessus en signal en dents de scie ? En supprimant la partie enti\u00e8re des \u00e9chantillons afin de ne garder que la partie d\u00e9cimale (fractionnaire) ( 3.14159 -> 0.14159 ). D\u00e9finissons une fonction pour faire cela : decimalpart(x) = x - int(x); Nous pouvons maintenant utiliser cette fonction pour transformer notre rampe en dents de scie. Il est alors tentant d'\u00e9crire : process = 0.125 : + ~ _ : decimalpart; D'un point de vue math\u00e9matique, ce serait parfaitement correct, mais nous allons accumuler les erreurs d'arrondi. Pour conserver une pr\u00e9cision totale, il est pr\u00e9f\u00e9rable de placer l'op\u00e9ration de la partie d\u00e9cimale \u00e0 l'int\u00e9rieur de la boucle comme ceci : process = 0.125 : (+ : decimalpart) ~ _; On peut maintenant essayer l'ensemble du code ( pensez \u00e0 baisser le volume ) : Dans notre d\u00e9finition de la phase , la valeur du pas, ici 0,125 , contr\u00f4le la fr\u00e9quence du signal g\u00e9n\u00e9r\u00e9. Nous aimerions calculer cette valeur de pas en fonction de la fr\u00e9quence souhait\u00e9e. Afin de faire la conversion, nous devons conna\u00eetre la fr\u00e9quence d'\u00e9chantillonnage. Elle est disponible dans la biblioth\u00e8que standard sous le nom de ma.SR . Pour utiliser cette biblioth\u00e8que standard nous ajoutons au programme la ligne suivante : import(\"stdfaust.lib\"); Supposons que nous voulions que notre signal de phase ait une fr\u00e9quence de 1 Hz, alors le pas devrait \u00eatre tr\u00e8s petit 1/ma.SR , afin qu'il faille ma.SR \u00e9chantillons (c'est \u00e0 dire 1 seconde) pour que le signal de phase passe de 0 \u00e0 1. Si nous voulons une fr\u00e9quence de 440 Hz, nous avons besoin d'un pas 440 fois plus grand pour que le signal de phase passe de 0 \u00e0 1 440 fois plus vite : phase = 440/ma.SR : (+ : decimalpart) ~ _; On peut g\u00e9n\u00e9raliser cette d\u00e9finition en rempla\u00e7ant 440 par un param\u00e8tre f : phase(f) = f/ma.SR : (+ : decimalpart) ~ _; et en passant la fr\u00e9quence souhait\u00e9e \u00e0 phase : process = phase(440);","title":"Signal de phase"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-signal-en-dent-de-scie","text":"Nous pouvons maintenant nous servir du g\u00e9n\u00e9rateur de phase pour produire un signal en dent de scie :","title":"Generateur de signal en dent de scie"},{"location":"workshops/2020-03-24-faust-citi/#generateur-de-signal-carre","text":"Nous pouvons \u00e9galement nous servir du g\u00e9n\u00e9rateurr de phase pour produire un signal carr\u00e9 :","title":"Generateur de signal carr\u00e9"},{"location":"workshops/2020-03-24-faust-citi/#synthese-additive","text":"","title":"Synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-generateur-sinusoidal","text":"Le g\u00e9n\u00e9rateur de phase est \u00e9galement \u00e0 la base de l'oscillateur sinusoidal : Mais maintenant que nous avons vu comment cr\u00e9er de toutes pi\u00e8ces un oscillateur sinusoidal, nous allons utiliser celui qui est d\u00e9fini dans la libraries standard de Faust :","title":"Exemple 1 : g\u00e9n\u00e9rateur sinusoidal"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-une-onde-sinusoidale-avec-controle-de-volume","text":"Dans ce deuxi\u00e8me exemple on a utilis\u00e9 un slider horizontal hslider(...) pour r\u00e9gler le niveau sonore : Le premier param\u00e8tre est une chaine de caract\u00e8re qui indique le nom du slider. Il est suivi de quatre param\u00e8tres num\u00e9riques. Le deuxi\u00e8me param\u00e8tre 0.1 indique la valeur par d\u00e9faut du slider, c'est \u00e0 dire la valeur que va d\u00e9livrer le slider quand on lance le programme. Ensuite nous avons la valeur minimale 0 , la valeur maximale 1 et le pas de variation 0.01 .","title":"Exemple 2 : une onde sinusoidale avec controle de volume"},{"location":"workshops/2020-03-24-faust-citi/#exemple-3-exercice-ajouter-un-controle-de-frequence","text":"A titre d'exercice, remplacer, dans l'exemple pr\u00e9c\u00e9dent, la fr\u00e9quence 440 par un slider horizontal dont le nom sera \"freq\" , la valeur par d\u00e9faut 110 , la valeur minimale 40 , la valeur maximale 8000 et le pas 1 .","title":"Exemple 3 : Exercice, ajouter un contr\u00f4le de fr\u00e9quence"},{"location":"workshops/2020-03-24-faust-citi/#exemple-4-phenomene-de-repliement-de-frequence-au-dela-de-sr2","text":"Un probl\u00e8me bien connu dans le domaine de la synth\u00e8se num\u00e9rique du son est celui du repliement de fr\u00e9quence : toute fr\u00e9quence au dela de la moiti\u00e9 de la fr\u00e9quence d'\u00e9chatillonnage se retrouve repli\u00e9e dans le spectre audible :","title":"Exemple 4 : Ph\u00e9nom\u00e8ne de repliement de fr\u00e9quence au-del\u00e0 de SR/2"},{"location":"workshops/2020-03-24-faust-citi/#exemple-5-synthese-additive","text":"Un exemple de synth\u00e8se additive ou le niveau de chaque partiel peut \u00eatre r\u00e9gl\u00e9 individuellement : A noter l'utilisation de la construction sum(i, n, foo(i)) qui est equivalente \u00e0 foo(0)+foo(1)+...+foo(n-1) .","title":"Exemple 5 : Synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-6-approximation-dun-signal-carre-par-synthese-additive","text":"Nous avons vu pr\u00e9c\u00e9demment comment produire une signal carr\u00e9 parfait. Ce signal carr\u00e9 parfait comporte une infinit\u00e9 d'harmoniques qui, du fait de l'\u00e9chantillonnage, vont se replier sur le spectre audible, ce qui va donner un son bruit\u00e9 moins fid\u00e8le ! On peut approximer un signal carr\u00e9 par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques impaires (voir https://fr.wikipedia.org/wiki/Signal_carr\u00e9 ) : A titre d'excercice, faire varier le nombre d'harmoniques pour voir l'approximation s'am\u00e9liorer (mais sans d\u00e9passer SR/2).","title":"Exemple 6 : Approximation d'un signal carr\u00e9 par synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-7-approximation-dun-signal-en-dent-de-scie-par-synthese-additive","text":"De m\u00eame on peut approximer un signal en dent de scie par synth\u00e8se additive, en additionnant une serie infinie d'harmoniques (voir https://fr.wikipedia.org/wiki/Signal_en_dents_de_scie ) :","title":"Exemple 7 : Approximation d'un signal en dent de scie par synth\u00e8se additive"},{"location":"workshops/2020-03-24-faust-citi/#synthese-soustractive","text":"La synth\u00e8se soustractive proc\u00e8de \u00e0 l'inverse de la synth\u00e8se additive. Elle consiste \u00e0 partir d'un son riche, par exemple un bruit blanc, et \u00e0 sculpter son spectre.","title":"Synth\u00e8se soustractive"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-un-bruit-blanc","text":"Un bruit blanc :","title":"Exemple 1 : un bruit blanc"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-lowpass","text":"","title":"Exemple 2 : lowpass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-3-high-pass","text":"","title":"Exemple 3 : high pass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-4-bandpass","text":"","title":"Exemple 4 : bandpass"},{"location":"workshops/2020-03-24-faust-citi/#exemple-5-resonnant","text":"","title":"Exemple 5 : resonnant"},{"location":"workshops/2020-03-24-faust-citi/#exemple-6-fir","text":"","title":"Exemple 6 : fir"},{"location":"workshops/2020-03-24-faust-citi/#exemple-7-iir","text":"","title":"Exemple 7 : iir"},{"location":"workshops/2020-03-24-faust-citi/#exemple-8-filtre-en-peigne","text":"","title":"Exemple 8 : filtre en peigne"},{"location":"workshops/2020-03-24-faust-citi/#exemple-9-karplus-strong-12","text":"","title":"Exemple 9 : Karplus Strong (1/2)"},{"location":"workshops/2020-03-24-faust-citi/#exemple-10-karplus-strong-22","text":"","title":"Exemple 10 : Karplus Strong (2/2)"},{"location":"workshops/2020-03-24-faust-citi/#exemple-11-kisana","text":"","title":"Exemple 11 : Kisana"},{"location":"workshops/2020-03-24-faust-citi/#synthese-par-modulation-de-frequence","text":"","title":"Synth\u00e8se par modulation de fr\u00e9quence"},{"location":"workshops/2020-03-24-faust-citi/#exemple-1-fm1","text":"","title":"Exemple 1 : fm1"},{"location":"workshops/2020-03-24-faust-citi/#exemple-2-fm2","text":"","title":"Exemple 2 : fm2"},{"location":"workshops/2020-04-10-faust-101/","text":"Faust 101 for the confined The covid-19 containment gives us at least one excellent opportunity to train! If you've always wanted to get into Faust programming but didn't have the time, here's your chance! The objective of this workshop is to help you get familiar with the Faust language through very simple examples of signal processing and sound synthesis. The documentation and the examples we will use can be found here: https://faustdoc.grame.fr/workshops/2020-04-10-faust-101/ All examples will be run in the online Faust IDE: https://faustide.grame.fr If ever the sounds produced with the IDE are of poor quality, with some clicks, one can use the online editor, which is more rustic, but also lighter: https://fausteditor.grame.fr Faust in a few words Faust is a Domain-Specific Language for real-time signal processing and synthesis (like Csound, Max/MSP, SuperCollider, PureData,. . . ). Faust is based on purely functional approach. a Faust program denotes a signal processor: a function that maps input signals to output signals. Programming in Faust is essentially combining signal processors using an algebra of 5 composition operations: <: :> : , ~ . Faust is a compiled language, the role of the Faust compiler is to synthesize the most efficient implementations. Faust offers end-users a high-level alternative to C/C++ to develop audio applications for a large variety of platforms. Part 1: Very simple examples Let's start with some simple examples of Faust programs. Example 1: The simplest Faust program This is the simplest Faust program imaginable. It contains only one line of code, the definition: process = _; . This program copies the audio input to the audio output. Let's try this program using the online Faust IDE: Several lessons can be learned from this very simple example: a Faust program has at least one definition, that of the keyword process which indicates the entry point of the program. a definition always ends with a ; . A common mistake is to forget the semicolon at the end of a definition. the _ sign represents one of the primitives of the language (primitives are the predefined functions of the language). It represents an audio cable that lets the signal pass through without transforming it. This is what one calls in mathematics the identity function, the signal that enters on the left comes out on the right identically. Example 2: Adding two signals We saw in the previous example the primitive _ . Faust has a large number of primitives, including all mathematical operations . The + primitive for instance is used to add two signals. It can therefore be used to transform a stereophonic signal (on two channels) into a monophonic signal as in the following example: Example 3: Multiplying two signals The * primitive for instance is used to multiply two signals: As you can hear, multiplying the two channels of a signal between them transforms the sound quite drastically. Example 4: Parallel composition Programming in Faust consists in assembling primitive operations to form more or less complex audio circuits. To realize these assemblies, Faust has 5 composition operations: ~ , , , ; , <: , :> . Let's first look at the parallel composition represented by the comma , : We made a stereo cable and when we play the audio file, we now hear it on both speakers. It is very important to distinguish between primitives , such as _ , + or * , and composition operations such as , or : . Primitives represent operations on audio signals, whereas composition operations are used to link two audio operations together. In other words, you can write + or * alone, because they represent valid audio operations, but you can never write , or : alone because they are used to connect two audio operations. You must always write A,B or A:B . The primitives of Faust are organized in several categories. We find all the numerical functions of the C language, but applied to audio signals: Category Primitives Arithmetic + , - , * , / , ... Comparison < , == , != , <= , ... Trigonometric sin , cos , ... Log and Co. log , exp , ... Min, Max min , max , ... Selectors select2 , select3 , ... Delays and Tables @ , rdtable , ... GUI hslider() , button() , ... Here is a summary table of the five composition operators: Syntax Priority Association Description A ~ B 4 left Recursive Composition A , B 3 right Parallel Composition A : B 2 right Sequential Composition A <: B 1 right Split Composition A :> B 1 right Merge Composition Example 5: Controlling the volume Let's see an example where we combine three primitives: _ , 0.1 and * , with two composition operators: , and : . The idea here is to lower the volume of the incoming signal to one tenth of its initial value. This is done by multiplying the incoming signal by 0.1 : Note that we have used parentheses in this example to clearly mark the order in which things should be done. We start by putting _ and 0.1 in parallel, and then compose them in sequence with * . But, just as in (2*3)+7 were the parentheses are not really necessary because multiplication takes precedence over addition, one could write directly process = _,0.1 : *; without the parentheses, because parallel composing takes precedence over sequential composing. The priority of the composition operators is shown in the previous table. Example 6: Controlling the volume with a slider Instead of controlling the volume by editing the code, it is far more convenient to use a graphical slider. For that purpose we can use a hslider(...) , a horizontal slider. It takes five parameters. The first one is the name \"volume\" , then we have the defaut value 0.1 , the minimun value 0 , the maximum value 1 and a step value 0.1 . So here the default value is 0.1 : Example 7: Mono Amplifier We have written very simple programs so far, that fit into one line of code. We will now introduce additional definitions. A definition should be understood as a way of giving a name to something, which saves us from typing the definition every time and makes the program easier to understand: Example 8: Stereo Amplifier Continuing in the same vein, we will define a stereo amplifier as two mono amplifiers in parallel: Note that even if the hslider volume appears several times in our code, there will only be one in the user interface: Example 9: Vertical sliders Instead of horizontal sliders, we could use vertical sliders. Just replace hslider(...) with vslider(...) : Example 10: Knobs instead of sliders By default sliders are ... sliders! You can change their appearance by using the metadata mechanism. Metadata is information that you put in square brackets in the slider name. For example the metadata \"...[style:knob]...\" allows you to turn the slider into a rotary knob: Example 11: Syntactic sugar We have used the core syntax of Faust so far. For example to multiply the incoming signal by 0.1 , we wrote _,0.1:* . For numerical expressions this notation is not always the most convenient and sometimes we would prefer to use the more traditional infix notation and write instead _*0.1 . We can also use the prefixed notation and write *(0.1) . Let's rewrite the definition of the monoamp using the prefix notation: Here is a table of equivalent notations, with the same expression in all three syntaxes. Keep in mind that infix and prefix expressions are translated to core syntax: Expression Description _,0.1:* core syntax _*0.1 infix notation *(0.1) prefix notation These notations can be freely combined. For example, the following expressions are all equivalent: Expression Description *(1-m) prefix + infix notation _*(1-m) only infix notation _,(1,m:-):* core syntax Example 12: A mute button We would like to be able to mute the sound completely at the touch of a button, without having to change the volume. Let's add a mute stage to our mono amplifier. In order to mute the signal we just have to mutiply it by 0. We will use for that purpose a checkbox(...) , a user interface element that produces a signal which is 0 by default and 1 when it is checked. As we want to multiply the signal by 0 when the checkbox is checked we will use 1-checkbox(\"mute\") : Example 13: Vertical and horizontal Layout As can be seen in the previous example, by default, the layout of the elements is vertical. You can change this layout by using hgroup(...) and vgroup(...) . For example to make the layout horizontal you can write: s Example 14: Differentiate the volume of the two channels To differentiate the volume control of our two channels, we will parametrize monoamp with a channel number c which will be used to differentiate the name of each volume control. Note that the name c of the parameter must only have one letter to be well interpreted in the slider name \"volume %c[style:knob]\" : Example 15: Having many channels We have built a stereo amp, but suppose we wanted to generalize this construction to an arbitrary number of channels. To do so, we will introduce the par(i, N, ...) construction which allows us to put several times an expression in parallel. It is in a way the equivalent of the for() loop of a classical programming language. In our case we want to indicate the number of channels of our amplifier: Part 2: Delays and Feedbacks In this new section we will see two important notions, that of delay with the @ primitive, and that of feedback (from a looped circuit) which will require the use of the recursive composition A~B which allows to loop the outputs of A into the inputs of B, and the outputs of B into the inputs of A. Example 1: Monophonic delay of 1 second Let's start with a very simple example, a monophonic delay of 1 seconds or 44100 samples. We will use the prefix notation: Example 2: Delay of 0.1 second on the right channel To hear the delay better, let's put it only on the right channel and leave the left channel unchanged: Example 3: the bouncing of sound on a wall By combining a delay and an attenuation we can simulate the bouncing of sound on a wall: Example 4: A simple monophonic echo To simulate an echo, all we need to do is create a feedback loop. We'll use the recursive composition A~B : Example 5: A stereophonic echo Let's make a stereophonic echo with two monophonic echos in parallel: Example 6: Adding parameters We will now generalize our echo with parameters to control its duration and feedback level: Example 7: Slider for the feedback control We can now add a slider to control the level of feedback: Example 8: Freeze effect We would now like to prevent the sound level from rising indefinitely when we set the feedback level to 1. The idea is to gradually shut down the input when the feedback level exceeds a certain threshold: Part 3: Basic Oscillators By convention, in Faust, a full-scale audio signal varies between -1 and +1, but we will first start with a sawtooth signal between 0 and 1 which will then be used as a phase generator to produce different waveforms. Phase Generator The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate : Example 1: Ramp To do this we will produce an \"infinite\" ramp, which we will then transform into a periodic signal thanks to a part-decimal operation: The ramp is produced by the following program: Semantics To understand the above diagram, we will annotate it with its mathematical semantics: As can be seen in the diagram, the formula for the output signal is: y(t) = y(t-1) + 0.125 We can calculate the first values of y(t) : y(t<0)=0 . y(0) = y(-1) + 0.125 = 0.125 . y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1,000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ... Example 2: a phase signal How do I turn the above ramp into a sawtooth signal? By deleting the whole part of the samples in order to keep only the decimal part: 3.14159\\rightarrow 0.14159 . Let's define a function to do this: decimalpart(x) = x - int(x); We can now use this function to turn our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view, that would be perfectly correct, but we will accumulate rounding errors. To keep total accuracy, it is better to place the operation of the decimal part inside the loop, like this: process = 0.125 : (+ : decimalpart) ~ _; We can now try the whole code ( think about turning down the volume ) : In our definition of phase , the value of the step, here 0.125 , controls the frequency of the generated signal. We would like to calculate this step value as a function of the desired frequency. In order to do the conversion, we need to know the sampling frequency. It is available in the standard library as ma.SR and will be setup at start time by the underlying audio layer. To use this standard library we add the following line to the program: import(\"stdfaust.lib\"); . Suppose we want our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR , so that it takes ma.SR samples (i.e. 1 second) for the phase signal to go from 0 to 1. If we want a frequency of 440 Hz, we need a 440 times larger step so that the phase signal goes from 0 to 1, 440 times faster: phase = 440/ma.SR : (+ : decimalpart) ~ _; This definition can be generalized by replacing 440 with an f parameter: phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and changing the desired frequency to phase : process = phase(440); Example 3: Sawtooth signal generator We can now use the phase generator to produce a sawtooth signal: Example 4: Square wave generator We can also use the phase generator to produce a square wave signal: Part 4: Additive synthesis Example 1: sine wave generator The phase generator is also the basis of the sine wave generator: But now that we have seen how to create a sinusoidal oscillator from scratch, we will use the one defined in the standard Faust libraries: Example 2: a sine wave with volume control In this second example we used a horizontal slider hslider(...) to control the sound level: The first parameter is a string that indicates the name of the slider. It is followed by four numeric parameters. The second parameter 0.1 indicates the default value of the slider, i.e. the value that the slider will deliver when the program is started. Then we have the minimum value 0 , the maximum value 1 and the variation step 0.01 . Example 3: Exercise, add a frequency control As an exercise, replace, in the previous example, the frequency 440 by a horizontal slider whose name will be freq , the default value 110 , the minimum value 40 , the maximum value 8000 and the step 1 : Example 4: Frequency aliasing phenomenon beyond SR/2 A well known problem in the field of digital sound synthesis is frequency aliasing : any frequency beyond half the sampling frequency is folded in the audible spectrum: Example 5: Additive synthesis An example of an additive synthesis, where the level of each partial can be set individually: Note the use of the sum(i, n, foo(i)) construction which is equivalent to foo(0)+foo(1)+...+foo(n-1) . Example 6: Approximation of a square signal by additive synthesis We saw earlier how to produce a perfect square wave signal. This perfect square signal contains an infinite number of harmonics which, due to sampling, will fold over the audible spectrum, resulting in a less accurate, noisy sound! A square signal can be approximated by additive synthesis, by adding an infinite series of odd harmonics (see https://en.wikipedia.org/wiki/Square_wave ): As an exercise, change the number of harmonics to see the approximation improve (but do not exceed SR/2). Example 7: Approximation of a sawtooth signal by additive synthesis Similarly, a sawtooth signal can be approximated by additive synthesis, by adding an infinite series of harmonics (see https://en.wikipedia.org/wiki/Sawtooth_wave ): Example 8: Band limited oscillators The problem of aliasing can be solved using band-limited oscillators available in Faust libraries: Part 5: Subtractive synthesis Subtractive synthesis is the opposite of additive synthesis. It consists in starting from a rich sound, for example white noise, and sculpting its spectrum. Example 1: a white noise A white noise generator: Example 2: lowpass Here the noise sound is filtered with a low-pass filter that removes frequencies lower than a selected cutoff frequency: The used fi.low filter can be defined with an argument that modifies the frequency attenuation slope. Example 3: high pass Here the noise sound is filtered with a high-pass filter that removes frequencies higher than a selected cutoff frequency: The used fi.highpass filter can be defined with an argument that modifies the frequency attenuation slope. Example 4: bandpass By combining a low-pass and high-pass filter in sequence, a bandpass filter that removes frequencies lower than a selected low cutoff frequency, and higher than a selected high cutoff frequency, can be defined (using the already described fi.lowpass and fi.highpass filters): Example 5: resonant A resonant filter amplifies a selected frequency range: The used fi.resonlp filter has an argument to select the desired frequency, a Q factor to shape the frequency range, and a gain factor. Example 6: fir Here a FIR filter is used: Example 7: iir Here a IIR filter is used: Example 8: comb filter A comb filter attenuates a set of consecutives frequency bands: Example 9: Karplus Strong (1/2) Example 10: Karplus Strong (2/2) Example 11: Kisana Part 6: Synthesis by frequency modulation Example 1: frequency modulation Example 2: frequency modulation with envelops Further readings The documentation of Faust libraries is available here: https://faustlibraries.grame.fr/","title":" 2020-04-10 Faust 101 "},{"location":"workshops/2020-04-10-faust-101/#faust-101-for-the-confined","text":"The covid-19 containment gives us at least one excellent opportunity to train! If you've always wanted to get into Faust programming but didn't have the time, here's your chance! The objective of this workshop is to help you get familiar with the Faust language through very simple examples of signal processing and sound synthesis. The documentation and the examples we will use can be found here: https://faustdoc.grame.fr/workshops/2020-04-10-faust-101/ All examples will be run in the online Faust IDE: https://faustide.grame.fr If ever the sounds produced with the IDE are of poor quality, with some clicks, one can use the online editor, which is more rustic, but also lighter: https://fausteditor.grame.fr","title":"Faust 101 for the confined"},{"location":"workshops/2020-04-10-faust-101/#faust-in-a-few-words","text":"Faust is a Domain-Specific Language for real-time signal processing and synthesis (like Csound, Max/MSP, SuperCollider, PureData,. . . ). Faust is based on purely functional approach. a Faust program denotes a signal processor: a function that maps input signals to output signals. Programming in Faust is essentially combining signal processors using an algebra of 5 composition operations: <: :> : , ~ . Faust is a compiled language, the role of the Faust compiler is to synthesize the most efficient implementations. Faust offers end-users a high-level alternative to C/C++ to develop audio applications for a large variety of platforms.","title":"Faust in a few words"},{"location":"workshops/2020-04-10-faust-101/#part-1-very-simple-examples","text":"Let's start with some simple examples of Faust programs.","title":"Part 1: Very simple examples"},{"location":"workshops/2020-04-10-faust-101/#example-1-the-simplest-faust-program","text":"This is the simplest Faust program imaginable. It contains only one line of code, the definition: process = _; . This program copies the audio input to the audio output. Let's try this program using the online Faust IDE: Several lessons can be learned from this very simple example: a Faust program has at least one definition, that of the keyword process which indicates the entry point of the program. a definition always ends with a ; . A common mistake is to forget the semicolon at the end of a definition. the _ sign represents one of the primitives of the language (primitives are the predefined functions of the language). It represents an audio cable that lets the signal pass through without transforming it. This is what one calls in mathematics the identity function, the signal that enters on the left comes out on the right identically.","title":"Example 1: The simplest Faust program"},{"location":"workshops/2020-04-10-faust-101/#example-2-adding-two-signals","text":"We saw in the previous example the primitive _ . Faust has a large number of primitives, including all mathematical operations . The + primitive for instance is used to add two signals. It can therefore be used to transform a stereophonic signal (on two channels) into a monophonic signal as in the following example:","title":"Example 2: Adding two signals"},{"location":"workshops/2020-04-10-faust-101/#example-3-multiplying-two-signals","text":"The * primitive for instance is used to multiply two signals: As you can hear, multiplying the two channels of a signal between them transforms the sound quite drastically.","title":"Example 3: Multiplying two signals"},{"location":"workshops/2020-04-10-faust-101/#example-4-parallel-composition","text":"Programming in Faust consists in assembling primitive operations to form more or less complex audio circuits. To realize these assemblies, Faust has 5 composition operations: ~ , , , ; , <: , :> . Let's first look at the parallel composition represented by the comma , : We made a stereo cable and when we play the audio file, we now hear it on both speakers. It is very important to distinguish between primitives , such as _ , + or * , and composition operations such as , or : . Primitives represent operations on audio signals, whereas composition operations are used to link two audio operations together. In other words, you can write + or * alone, because they represent valid audio operations, but you can never write , or : alone because they are used to connect two audio operations. You must always write A,B or A:B . The primitives of Faust are organized in several categories. We find all the numerical functions of the C language, but applied to audio signals: Category Primitives Arithmetic + , - , * , / , ... Comparison < , == , != , <= , ... Trigonometric sin , cos , ... Log and Co. log , exp , ... Min, Max min , max , ... Selectors select2 , select3 , ... Delays and Tables @ , rdtable , ... GUI hslider() , button() , ... Here is a summary table of the five composition operators: Syntax Priority Association Description A ~ B 4 left Recursive Composition A , B 3 right Parallel Composition A : B 2 right Sequential Composition A <: B 1 right Split Composition A :> B 1 right Merge Composition","title":"Example 4: Parallel composition"},{"location":"workshops/2020-04-10-faust-101/#example-5-controlling-the-volume","text":"Let's see an example where we combine three primitives: _ , 0.1 and * , with two composition operators: , and : . The idea here is to lower the volume of the incoming signal to one tenth of its initial value. This is done by multiplying the incoming signal by 0.1 : Note that we have used parentheses in this example to clearly mark the order in which things should be done. We start by putting _ and 0.1 in parallel, and then compose them in sequence with * . But, just as in (2*3)+7 were the parentheses are not really necessary because multiplication takes precedence over addition, one could write directly process = _,0.1 : *; without the parentheses, because parallel composing takes precedence over sequential composing. The priority of the composition operators is shown in the previous table.","title":"Example 5: Controlling the volume"},{"location":"workshops/2020-04-10-faust-101/#example-6-controlling-the-volume-with-a-slider","text":"Instead of controlling the volume by editing the code, it is far more convenient to use a graphical slider. For that purpose we can use a hslider(...) , a horizontal slider. It takes five parameters. The first one is the name \"volume\" , then we have the defaut value 0.1 , the minimun value 0 , the maximum value 1 and a step value 0.1 . So here the default value is 0.1 :","title":"Example 6: Controlling the volume with a slider"},{"location":"workshops/2020-04-10-faust-101/#example-7-mono-amplifier","text":"We have written very simple programs so far, that fit into one line of code. We will now introduce additional definitions. A definition should be understood as a way of giving a name to something, which saves us from typing the definition every time and makes the program easier to understand:","title":"Example 7: Mono Amplifier"},{"location":"workshops/2020-04-10-faust-101/#example-8-stereo-amplifier","text":"Continuing in the same vein, we will define a stereo amplifier as two mono amplifiers in parallel: Note that even if the hslider volume appears several times in our code, there will only be one in the user interface:","title":"Example 8: Stereo Amplifier"},{"location":"workshops/2020-04-10-faust-101/#example-9-vertical-sliders","text":"Instead of horizontal sliders, we could use vertical sliders. Just replace hslider(...) with vslider(...) :","title":"Example 9: Vertical sliders"},{"location":"workshops/2020-04-10-faust-101/#example-10-knobs-instead-of-sliders","text":"By default sliders are ... sliders! You can change their appearance by using the metadata mechanism. Metadata is information that you put in square brackets in the slider name. For example the metadata \"...[style:knob]...\" allows you to turn the slider into a rotary knob:","title":"Example 10: Knobs instead of sliders"},{"location":"workshops/2020-04-10-faust-101/#example-11-syntactic-sugar","text":"We have used the core syntax of Faust so far. For example to multiply the incoming signal by 0.1 , we wrote _,0.1:* . For numerical expressions this notation is not always the most convenient and sometimes we would prefer to use the more traditional infix notation and write instead _*0.1 . We can also use the prefixed notation and write *(0.1) . Let's rewrite the definition of the monoamp using the prefix notation: Here is a table of equivalent notations, with the same expression in all three syntaxes. Keep in mind that infix and prefix expressions are translated to core syntax: Expression Description _,0.1:* core syntax _*0.1 infix notation *(0.1) prefix notation These notations can be freely combined. For example, the following expressions are all equivalent: Expression Description *(1-m) prefix + infix notation _*(1-m) only infix notation _,(1,m:-):* core syntax","title":"Example 11: Syntactic sugar"},{"location":"workshops/2020-04-10-faust-101/#example-12-a-mute-button","text":"We would like to be able to mute the sound completely at the touch of a button, without having to change the volume. Let's add a mute stage to our mono amplifier. In order to mute the signal we just have to mutiply it by 0. We will use for that purpose a checkbox(...) , a user interface element that produces a signal which is 0 by default and 1 when it is checked. As we want to multiply the signal by 0 when the checkbox is checked we will use 1-checkbox(\"mute\") :","title":"Example 12: A mute button"},{"location":"workshops/2020-04-10-faust-101/#example-13-vertical-and-horizontal-layout","text":"As can be seen in the previous example, by default, the layout of the elements is vertical. You can change this layout by using hgroup(...) and vgroup(...) . For example to make the layout horizontal you can write: s","title":"Example 13: Vertical and horizontal Layout"},{"location":"workshops/2020-04-10-faust-101/#example-14-differentiate-the-volume-of-the-two-channels","text":"To differentiate the volume control of our two channels, we will parametrize monoamp with a channel number c which will be used to differentiate the name of each volume control. Note that the name c of the parameter must only have one letter to be well interpreted in the slider name \"volume %c[style:knob]\" :","title":"Example 14: Differentiate the volume of the two channels"},{"location":"workshops/2020-04-10-faust-101/#example-15-having-many-channels","text":"We have built a stereo amp, but suppose we wanted to generalize this construction to an arbitrary number of channels. To do so, we will introduce the par(i, N, ...) construction which allows us to put several times an expression in parallel. It is in a way the equivalent of the for() loop of a classical programming language. In our case we want to indicate the number of channels of our amplifier:","title":"Example 15: Having many channels"},{"location":"workshops/2020-04-10-faust-101/#part-2-delays-and-feedbacks","text":"In this new section we will see two important notions, that of delay with the @ primitive, and that of feedback (from a looped circuit) which will require the use of the recursive composition A~B which allows to loop the outputs of A into the inputs of B, and the outputs of B into the inputs of A.","title":"Part 2: Delays and Feedbacks"},{"location":"workshops/2020-04-10-faust-101/#example-1-monophonic-delay-of-1-second","text":"Let's start with a very simple example, a monophonic delay of 1 seconds or 44100 samples. We will use the prefix notation:","title":"Example 1: Monophonic delay of 1 second"},{"location":"workshops/2020-04-10-faust-101/#example-2-delay-of-01-second-on-the-right-channel","text":"To hear the delay better, let's put it only on the right channel and leave the left channel unchanged:","title":"Example 2: Delay of 0.1 second on the right channel"},{"location":"workshops/2020-04-10-faust-101/#example-3-the-bouncing-of-sound-on-a-wall","text":"By combining a delay and an attenuation we can simulate the bouncing of sound on a wall:","title":"Example 3: the bouncing of sound on a wall"},{"location":"workshops/2020-04-10-faust-101/#example-4-a-simple-monophonic-echo","text":"To simulate an echo, all we need to do is create a feedback loop. We'll use the recursive composition A~B :","title":"Example 4: A simple monophonic echo"},{"location":"workshops/2020-04-10-faust-101/#example-5-a-stereophonic-echo","text":"Let's make a stereophonic echo with two monophonic echos in parallel:","title":"Example 5: A stereophonic echo"},{"location":"workshops/2020-04-10-faust-101/#example-6-adding-parameters","text":"We will now generalize our echo with parameters to control its duration and feedback level:","title":"Example 6: Adding parameters"},{"location":"workshops/2020-04-10-faust-101/#example-7-slider-for-the-feedback-control","text":"We can now add a slider to control the level of feedback:","title":"Example 7: Slider for the feedback control"},{"location":"workshops/2020-04-10-faust-101/#example-8-freeze-effect","text":"We would now like to prevent the sound level from rising indefinitely when we set the feedback level to 1. The idea is to gradually shut down the input when the feedback level exceeds a certain threshold:","title":"Example 8: Freeze effect"},{"location":"workshops/2020-04-10-faust-101/#part-3-basic-oscillators","text":"By convention, in Faust, a full-scale audio signal varies between -1 and +1, but we will first start with a sawtooth signal between 0 and 1 which will then be used as a phase generator to produce different waveforms.","title":"Part 3: Basic Oscillators"},{"location":"workshops/2020-04-10-faust-101/#phase-generator","text":"The first step is to build a phase generator that produces a periodic sawtooth signal between 0 and 1. Here is the signal we want to generate :","title":"Phase Generator"},{"location":"workshops/2020-04-10-faust-101/#example-1-ramp","text":"To do this we will produce an \"infinite\" ramp, which we will then transform into a periodic signal thanks to a part-decimal operation: The ramp is produced by the following program:","title":"Example 1: Ramp"},{"location":"workshops/2020-04-10-faust-101/#semantics","text":"To understand the above diagram, we will annotate it with its mathematical semantics: As can be seen in the diagram, the formula for the output signal is: y(t) = y(t-1) + 0.125 We can calculate the first values of y(t) : y(t<0)=0 . y(0) = y(-1) + 0.125 = 0.125 . y(1) = y(0) + 0.125 = 2*0.125 = 0.250 y(2) = y(1) + 0.125 = 3*0.125 = 0.375 ... y(6) = y(5) + 0.125 = 7*0.125 = 0.875 y(7) = y(6) + 0.125 = 8*0.125 = 1,000 y(8) = y(7) + 0.125 = 9*0.125 = 1.125 ...","title":"Semantics"},{"location":"workshops/2020-04-10-faust-101/#example-2-a-phase-signal","text":"How do I turn the above ramp into a sawtooth signal? By deleting the whole part of the samples in order to keep only the decimal part: 3.14159\\rightarrow 0.14159 . Let's define a function to do this: decimalpart(x) = x - int(x); We can now use this function to turn our ramp into a sawtooth. It is then tempting to write: process = 0.125 : + ~ _ : decimalpart; From a mathematical point of view, that would be perfectly correct, but we will accumulate rounding errors. To keep total accuracy, it is better to place the operation of the decimal part inside the loop, like this: process = 0.125 : (+ : decimalpart) ~ _; We can now try the whole code ( think about turning down the volume ) : In our definition of phase , the value of the step, here 0.125 , controls the frequency of the generated signal. We would like to calculate this step value as a function of the desired frequency. In order to do the conversion, we need to know the sampling frequency. It is available in the standard library as ma.SR and will be setup at start time by the underlying audio layer. To use this standard library we add the following line to the program: import(\"stdfaust.lib\"); . Suppose we want our phase signal to have a frequency of 1 Hz, then the step should be very small 1/ma.SR , so that it takes ma.SR samples (i.e. 1 second) for the phase signal to go from 0 to 1. If we want a frequency of 440 Hz, we need a 440 times larger step so that the phase signal goes from 0 to 1, 440 times faster: phase = 440/ma.SR : (+ : decimalpart) ~ _; This definition can be generalized by replacing 440 with an f parameter: phase(f) = f/ma.SR : (+ : decimalpart) ~ _; and changing the desired frequency to phase : process = phase(440);","title":"Example 2: a phase signal"},{"location":"workshops/2020-04-10-faust-101/#example-3-sawtooth-signal-generator","text":"We can now use the phase generator to produce a sawtooth signal:","title":"Example 3: Sawtooth signal generator"},{"location":"workshops/2020-04-10-faust-101/#example-4-square-wave-generator","text":"We can also use the phase generator to produce a square wave signal:","title":"Example 4: Square wave generator"},{"location":"workshops/2020-04-10-faust-101/#part-4-additive-synthesis","text":"","title":"Part 4: Additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-1-sine-wave-generator","text":"The phase generator is also the basis of the sine wave generator: But now that we have seen how to create a sinusoidal oscillator from scratch, we will use the one defined in the standard Faust libraries:","title":"Example 1: sine wave generator"},{"location":"workshops/2020-04-10-faust-101/#example-2-a-sine-wave-with-volume-control","text":"In this second example we used a horizontal slider hslider(...) to control the sound level: The first parameter is a string that indicates the name of the slider. It is followed by four numeric parameters. The second parameter 0.1 indicates the default value of the slider, i.e. the value that the slider will deliver when the program is started. Then we have the minimum value 0 , the maximum value 1 and the variation step 0.01 .","title":"Example 2: a sine wave with volume control"},{"location":"workshops/2020-04-10-faust-101/#example-3-exercise-add-a-frequency-control","text":"As an exercise, replace, in the previous example, the frequency 440 by a horizontal slider whose name will be freq , the default value 110 , the minimum value 40 , the maximum value 8000 and the step 1 :","title":"Example 3: Exercise, add a frequency control"},{"location":"workshops/2020-04-10-faust-101/#example-4-frequency-aliasing-phenomenon-beyond-sr2","text":"A well known problem in the field of digital sound synthesis is frequency aliasing : any frequency beyond half the sampling frequency is folded in the audible spectrum:","title":"Example 4: Frequency aliasing phenomenon beyond SR/2"},{"location":"workshops/2020-04-10-faust-101/#example-5-additive-synthesis","text":"An example of an additive synthesis, where the level of each partial can be set individually: Note the use of the sum(i, n, foo(i)) construction which is equivalent to foo(0)+foo(1)+...+foo(n-1) .","title":"Example 5: Additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-6-approximation-of-a-square-signal-by-additive-synthesis","text":"We saw earlier how to produce a perfect square wave signal. This perfect square signal contains an infinite number of harmonics which, due to sampling, will fold over the audible spectrum, resulting in a less accurate, noisy sound! A square signal can be approximated by additive synthesis, by adding an infinite series of odd harmonics (see https://en.wikipedia.org/wiki/Square_wave ): As an exercise, change the number of harmonics to see the approximation improve (but do not exceed SR/2).","title":"Example 6: Approximation of a square signal by additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-7-approximation-of-a-sawtooth-signal-by-additive-synthesis","text":"Similarly, a sawtooth signal can be approximated by additive synthesis, by adding an infinite series of harmonics (see https://en.wikipedia.org/wiki/Sawtooth_wave ):","title":"Example 7: Approximation of a sawtooth signal by additive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-8-band-limited-oscillators","text":"The problem of aliasing can be solved using band-limited oscillators available in Faust libraries:","title":"Example 8: Band limited oscillators"},{"location":"workshops/2020-04-10-faust-101/#part-5-subtractive-synthesis","text":"Subtractive synthesis is the opposite of additive synthesis. It consists in starting from a rich sound, for example white noise, and sculpting its spectrum.","title":"Part 5: Subtractive synthesis"},{"location":"workshops/2020-04-10-faust-101/#example-1-a-white-noise","text":"A white noise generator:","title":"Example 1: a white noise"},{"location":"workshops/2020-04-10-faust-101/#example-2-lowpass","text":"Here the noise sound is filtered with a low-pass filter that removes frequencies lower than a selected cutoff frequency: The used fi.low filter can be defined with an argument that modifies the frequency attenuation slope.","title":"Example 2: lowpass"},{"location":"workshops/2020-04-10-faust-101/#example-3-high-pass","text":"Here the noise sound is filtered with a high-pass filter that removes frequencies higher than a selected cutoff frequency: The used fi.highpass filter can be defined with an argument that modifies the frequency attenuation slope.","title":"Example 3: high pass"},{"location":"workshops/2020-04-10-faust-101/#example-4-bandpass","text":"By combining a low-pass and high-pass filter in sequence, a bandpass filter that removes frequencies lower than a selected low cutoff frequency, and higher than a selected high cutoff frequency, can be defined (using the already described fi.lowpass and fi.highpass filters):","title":"Example 4: bandpass"},{"location":"workshops/2020-04-10-faust-101/#example-5-resonant","text":"A resonant filter amplifies a selected frequency range: The used fi.resonlp filter has an argument to select the desired frequency, a Q factor to shape the frequency range, and a gain factor.","title":"Example 5: resonant"},{"location":"workshops/2020-04-10-faust-101/#example-6-fir","text":"Here a FIR filter is used:","title":"Example 6: fir"},{"location":"workshops/2020-04-10-faust-101/#example-7-iir","text":"Here a IIR filter is used:","title":"Example 7: iir"},{"location":"workshops/2020-04-10-faust-101/#example-8-comb-filter","text":"A comb filter attenuates a set of consecutives frequency bands:","title":"Example 8: comb filter"},{"location":"workshops/2020-04-10-faust-101/#example-9-karplus-strong-12","text":"","title":"Example 9: Karplus Strong (1/2)"},{"location":"workshops/2020-04-10-faust-101/#example-10-karplus-strong-22","text":"","title":"Example 10: Karplus Strong (2/2)"},{"location":"workshops/2020-04-10-faust-101/#example-11-kisana","text":"","title":"Example 11: Kisana"},{"location":"workshops/2020-04-10-faust-101/#part-6-synthesis-by-frequency-modulation","text":"","title":"Part 6: Synthesis by frequency modulation"},{"location":"workshops/2020-04-10-faust-101/#example-1-frequency-modulation","text":"","title":"Example 1: frequency modulation"},{"location":"workshops/2020-04-10-faust-101/#example-2-frequency-modulation-with-envelops","text":"","title":"Example 2: frequency modulation with envelops"},{"location":"workshops/2020-04-10-faust-101/#further-readings","text":"The documentation of Faust libraries is available here: https://faustlibraries.grame.fr/","title":"Further readings"},{"location":"workshops/2020-04-10-faust-juce/","text":"Faust For the Confined: Adding Faust DSP Support to Your JUCE Plug-ins JUCE is a well-known framework for creating audio plug-ins (i.e., VST, AU, AAX, etc.) and applications for a wide range of platforms. Faust can be used to generate ready-to-use JUCE applications and plug-ins implementing the standard user interface (UI) described in the Faust code using faust2juce . However, it is sooo easy to make professional looking UIs from scratch in JUCE that you might want to use Faust to implement the DSP portion of your plug-in and build your own UI. In this tutorial, we demonstrate how to use the Faust compiler to generate a C++ DSP object and how to interface it with your JUCE plug-in/UI. We'll cover basic examples (monophonic synth, polyphonic synth, and audio effect) as well as more advanced applications involving polyphony, etc. Simple Monophonic Synth Plug-In << Download the source of this tutorial >> In this section, we demonstrate how to use a Faust synth to build a plug-in in JUCE with a custom UI from scratch. Generating the DSP Engine First, let's implement a basic subtractive synthesizer in Faust based on a filtered sawtooth wave ( FaustSynth.dsp ): Feel free to run it in the web IDE to see how it sounds! The output of the lowpass is split into 2 signals to create a stereo object. Note that all the parameters are smoothed to prevent clicking (we want our plug-in to be clean!). Even gate is smoothed, which will apply a gentle exponential envelope when the trigger signal is sent, etc. Since Faust will not build its own UI here, the type of UI element used in this code doesn't really matter. They just serve as a point of entry to control the parameters of the audio engine we're about to generate. So nentry could be replaced by hslider or vslider , it would not make any difference. However, we encourage you to always write \"coherent\" interfaces in case someone would like to use your Faust code \"as such\" at some point. In order to turn this Faust program into a C++ DSP object usable in JUCE, we must use a Faust architecture file that will wrap the C++ code generated by the Faust compiler (that literally just contains an audio callback function). That's what faustMinimal.h (which is part of the package that you downloaded at the beginning of this tutorial) does. Actually, if you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/gui/MapUI.h\" #include \"faust/gui/meta.h\" #include \"faust/dsp/dsp.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP The faust/... files should be on your system if Faust is installed on it. If not, you can use the inlined version of the architecture file ( faustMinimalInlined.h ) which can also be found in the package that you downloaded at the beginning of this tutorial. MapUI.h will allow us to easily control the parameters of the Faust object using their declared names in the Faust code. The other includes are necessary in most cases and are just parent classes of the DSP class generated by the Faust compiler. <<includeclass>> is where the code generated by the Faust compiler gets pasted. This architecture file can be used with the Faust compiler simply by running: faust -i -a faustMinimal.h FaustSynth.dsp -o FaustSynth.h where FaustSynth.h is the name of the generated file that we will import in our JUCE project later in this tutorial. The -i option inlines the included C++ files in the generated file. Alternatively, if Faust is not installed on your system, the Faust online IDE can be used to carry out the same task by choosing source/cplusplus in the Export (truck) function. The content of the downloaded C++ file can then be copied and pasted between the BEGIN-FAUSTDSP and END-FAUSTDSP tags. We're now ready to create a new JUCE plug-in project! Creating an Empty JUCE Plug-In Project In this section, we'll assume that you're a bit familiar with JUCE . If that's not your case, don't panic and just read their Getting started with the Projucer tutorial. We also recommend you to have a look a the next few following tutorials to have a sense of how things work. They're nice and easy to read! In the Projucer, create a new Audio Plug-In, add the targets that you want, in the settings, make sure that \"Plugin is a Synth\" is enabled. In our case, we named it \"MonoSynth\" (choose this name wisely as it will impact the class names of your program). Now, place the FaustSynth.h file generated in the previous step in the Source folder of your JUCE plug-in project. Then select it in Source in your file browser and drag it to the Projucer so that it becomes visible in the Source tab: At this point, try to compile your plug-in and see if it runs. Remember that JUCE now generates a \"standalone plug-in\" by default which is super convenient to test things without having to open the plug-in in a third party application. Integrating the Faust DSP Object to The JUCE Project Let's now integrate our Faust-generated DSP object to the PluginProcessor . Declare the following elements in the private section of the MonoSynthAudioProcessor class of PluginProcessor.h : private: MapUI* fUI; dsp* fDSP; float** outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MonoSynthAudioProcessor) fUI will be used to control the parameters of the Faust DSP, and fDSP will contain the audio DSP/callback itself (that's basically the object generated by the Faust compiler). In order to declare these objects without knowing the definition of MapUI and dsp you'll also have to declare empty class definitions at the beginning of the file: class dsp; class MapUI; class MonoSynthAudioProcessor : public AudioProcessor In PluginProcessor.cpp , include FaustSynth.h at the beginning of the file in the includes section: #include \"PluginProcessor.h\" #include \"PluginEditor.h\" #include \"FaustSynth.h\" Write the following in the prepareToPlay method: void MonoSynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { outputs[channel] = new float[samplesPerBlock]; } } Here, fDSP which is the Faust DSP object is first instantiated. Then fUI which will be used to control the parameters of the DSP is instantiated. These 2 objects are bound together using the buildUserInterface method of fDSP . Finally, memory is allocated for the stereo output of the Faust object. Note that outputs is a double array (one dimension for audio channels and one dimension for audio samples/buffers). Conversly, write the following in the releaseResources method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } Here, we just free the memory allocated in the previous steps when resources are released. Let's now get into the heart of the matter: the audio callback which is implemented through the processBlock method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); fDSP->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } Here, we basically compute one full audio block of size buffer.getNumSamples() , we store it in outputs and we then link outputs to the actual audio output of processBlock ( *buffer.getWritePointer(channel,i) ). At this point, you should be able to produce sound with your plug-in! Temporarily add the following line to the prepareToPlay method to set the value of the gate parameter to one: fUI->setParamValue(\"gate\",1); Note how fUI is used here to configure the parameter of the Faust DSP using its setParamValue method which has 2 arguments: the path/name of the parameter in the Faust code, and its value. Try to compile the plug-in for your desired target (e.g., VST, AU, etc.). In our case we'll juste generate a standalone plug-in for convenience. When running the plug-in, you should now hear sound! Since we want to control the parameters of our synth from the PluginEditor , we must create a series of public methods in PluginProcessor to control each parameter of our synth. In PluginProcessor.h this will look like: public: void setFreq(float freq); void setGain(float gain); void setCutoff(float cutoff); void setGate(bool gate); and the corresponding implementation in PluginProcessor.cpp will be: void MonoSynthAudioProcessor::setFreq(float freq) { fUI->setParamValue(\"freq\",freq); } void MonoSynthAudioProcessor::setGain(float gain) { fUI->setParamValue(\"gain\",gain); } void MonoSynthAudioProcessor::setGate(bool gate) { if(gate) { fUI->setParamValue(\"gate\",1); } else { fUI->setParamValue(\"gate\",0); } } void MonoSynthAudioProcessor::setCutoff(float cutoff) { fUI->setParamValue(\"cutoff\",cutoff); } That's it for the PluginProcessor ! Easy isn't it ;)? Now, let's add a basic interface to control this synth. We add a series of sliders, button, and labels to the private section of MonoSynthAudioProcessorEditor in PluginEditor.h : private: Slider frequencySlider; Slider gainSlider; Slider cutoffSlider; ToggleButton onOffButton; Label frequencyLabel; Label gainLabel; Label cutoffLabel; Label onOffLabel; and their corresponding implementation in PluginEditor.cpp : MonoSynthAudioProcessorEditor::MonoSynthAudioProcessorEditor(MonoSynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { setSize (800, 130); addAndMakeVisible(frequencySlider); frequencySlider.setRange(50.0, 5000.0); frequencySlider.setSkewFactorFromMidPoint(500.0); frequencySlider.setValue(300); frequencySlider.onValueChange = [this] { processor.setFreq(frequencySlider.getValue()); }; addAndMakeVisible(frequencyLabel); frequencyLabel.setText(\"Frequency\", dontSendNotification); frequencyLabel.attachToComponent(&frequencySlider, true); addAndMakeVisible(gainSlider); gainSlider.setRange(0.0, 1.0); gainSlider.setValue(0.5); gainSlider.onValueChange = [this] { processor.setGain(gainSlider.getValue()); }; addAndMakeVisible(gainLabel); gainLabel.setText(\"Gain\", dontSendNotification); gainLabel.attachToComponent (&gainSlider, true); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); addAndMakeVisible(onOffButton); onOffButton.onClick = [this] { processor.setGate(onOffButton.getToggleState()); }; addAndMakeVisible(onOffLabel); onOffLabel.setText(\"On/Off\", dontSendNotification); onOffLabel.attachToComponent (&onOffButton, true); } The methods that we declared in the previous step are basically called to set the value of the parameters of our DSP engine thanks to the processor object. The resized method must be implemented so that the various UI elements that we created actually have a size: void MonoSynthAudioProcessorEditor::resized() { const int sliderLeft = 80; frequencySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); gainSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); cutoffSlider.setBounds(sliderLeft, 70, getWidth() - sliderLeft - 20, 20); onOffButton.setBounds(sliderLeft, 100, getWidth() - sliderLeft - 20, 20); } Finally, make sure that you clean the implementation of the paint method to get rid of the default ugly \"Hello World:\" void MonoSynthAudioProcessorEditor::paint (Graphics& g) { g.fillAll(getLookAndFeel().findColour (ResizableWindow::backgroundColourId)); } Compile your plug-in and run it, it should look like this: The goal of this section was just to show you how to integrate a Faust DSP object into a JUCE plug-in project and how to control it with a simple UI. Once again, JUCE is a powerful tool to implement sophisticated UI in a very simple way. You'll find all the documentation you need on their website](https://juce.com/) to start making beautiful plug-ins! Simple Audio Effect Plug-In << Download the source of this tutorial >> In this section, we demonstrate how to use a Faust effect to build a plug-in in JUCE with a custom UI from scratch. Generating the DSP Engine The steps for generating an audio effect C++ DSP object with Faust are exactly the same as for a synth ( see the previous section ) and the faustMinimal.h architecture file can be used as well. For this example, we'll be using a stereo echo: Then run something like: faust -i -a faustMinimal.h FaustEffect.dsp -o Effect/Source/FaustEffect.h Creating a New Empty JUCE Plug-In Project The steps are the same as for the mono synthesizer tutorial except that the \"Plug-in is a Synth\" checkbox shouldn't be checked this time. For this example, we decided to give a very bad and explicit name to our plug-in project: \"Effect.\"\" Finally, import the C++ file generated in the previous step (i.e., FaustEffect.h ) in your project. Integrating the Faust DSP Object to The JUCE Project Steps are also similar to the mono synthesizer tutorial here, except that an audio input should be created. So, in PluginProcessor.h , we'll have: private: MapUI* fUI; dsp* fDSP; float **inputs; float **outputs; In PluginProcessor.cpp , for the prepareToPlay and releaseResources methods: void EffectAudioProcessor::prepareToPlay (double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); inputs = new float*[2]; outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { inputs[channel] = new float[samplesPerBlock]; outputs[channel] = new float[samplesPerBlock]; } } void EffectAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] inputs[channel]; delete[] outputs[channel]; } delete [] inputs; delete [] outputs; } and the audio callback: void EffectAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); for (int channel = 0; channel < totalNumInputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { inputs[channel][i] = *buffer.getWritePointer(channel,i); } } fDSP->compute(buffer.getNumSamples(),inputs,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++){ *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } This should be relatively self-explanatory. Of course, the corresponding control methods should be created as well, etc.: void EffectAudioProcessor::setDelay(float delay) { fUI->setParamValue(\"delay\",delay); } void EffectAudioProcessor::setFeedback(float feedback) { fUI->setParamValue(\"feedback\",feedback); } On the interface side, things can be easily adapted to match this new configuration with something like this: EffectAudioProcessorEditor::EffectAudioProcessorEditor (EffectAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { // Make sure that before the constructor has finished, you've set the // editor's size to whatever you need it to be. setSize(800, 100); addAndMakeVisible (delaySlider); delaySlider.setRange(0.0, 1.0); delaySlider.setValue(0.5); delaySlider.onValueChange = [this] { processor.setDelay(delaySlider.getValue()); }; addAndMakeVisible(delayLabel); delayLabel.setText(\"Delay (s)\", dontSendNotification); delayLabel.attachToComponent (&delaySlider, true); addAndMakeVisible(feedbackSlider); feedbackSlider.setRange(0.0, 1.0); feedbackSlider.setValue(0.5); feedbackSlider.onValueChange = [this] { processor.setFeedback(feedbackSlider.getValue()); }; addAndMakeVisible(feedbackLabel); feedbackLabel.setText(\"Feedback\", dontSendNotification); feedbackLabel.attachToComponent(&feedbackSlider, true); } void EffectAudioProcessorEditor::resized() { const int sliderLeft = 80; delaySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); feedbackSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); } Try to compile your program and you should have a beautiful effect plug-in :). Creating and Using a Polyphonic Faust DSP Object << Download the source of this tutorial >> The procedure to create a polyphonic synthesizer DSP object is slightly different than for a simple monophonic synth such as the one presented at the beginning of this tutorial. Here, we'll be using the same Faust program as one used for the mono synthesizer example . To enable polyphony, we just need to configure the nvoices metadata which allows us to specify the maximum number of voices of polyphony of the DSP object that will be generated: The package downloadable at the beginning of this tutorial contains a Faust architecture file slightly different from the one used in the previous examples (mono synth and effect): faustMinimalPoly.h . If you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/misc.h\" #include \"faust/gui/UI.h\" #include \"faust/gui/JSONUIDecoder.h\" #include \"faust/dsp/dsp.h\" #include \"faust/dsp/dsp-adapter.h\" #include \"faust/gui/meta.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP #include \"faust/dsp/faust-poly-engine.h\" #include \"faust/audio/dummy-audio.h\" std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; faust-poly-engine.h contains the FaustPolyEngine class which can be used to turn a Faust C++ DSP object into a polyphonic synthesizer. In order for this class to work, an \"audio driver\" must be provided which is what the dummyaudio class available in dummy-audio.h can be used for. It also allows us to pass the sampling rate and the buffer size to FaustPolyEngine . Compile the previous Faust program using this architecture file either by using the Faust command-line compiler or web IDE: faust -i -a faustMinimalPoly.h FaustSynth.dsp -o PolySynth/Source/FaustSynth.h and integrate FaustSynth.h to a new JUCE synth plug-in project (following the same steps as in the mono synth tutorial ). In PluginProcessor.h , declare the following objects: private: audio *driver; FaustPolyEngine *faustObject; float **outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PolySynthAudioProcessor) Once again, faustObject here will be the polyphonic Faust object and driver will be used to pass the sampling rate and buffer size to the system. Don't forget the declare the corresponding empty classes at the beginning of the file: class FaustPolyEngine; class audio; class PolySynthAudioProcessor : public AudioProcessor { In PluginProcessor.cpp , first don't forget to include FaustSynth.h . Then fill prepareToPlay with the following code: void PolySynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { driver = new dummyaudio(sampleRate,samplesPerBlock); faustObject = new FaustPolyEngine(NULL,driver,NULL); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel){ outputs[channel] = new float[samplesPerBlock]; } } First, the empty audio driver is instantiated and passed to the Faust polyphonic object. Of course, we allocate memory for the audio output. Resources are freed as follows: void PolySynthAudioProcessor::releaseResources() { //delete faustObject; delete driver; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } The processBlock method works the same way as for the mono synth tutorial except that the compute method is called here directly from the faustObject ( FaustPolyEngine ). void PolySynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); faustObject->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } While the setParamValue method can now be called directly from faustObject to set the value of specific parameters of the Faust object, other polyphony-specific methods are available such as keyOn and keyOff . For an exhaustive list, you can have a look at the source of FaustPolyEngine which should just speak by itself. Our final goal for this tutorial is to create a simple plug-in with the following interface: Hence, the Faust DSP object should be controlled with a polyphonic keyboard. New methods must be created in PluginProcessor.cpp to send keyon and keyoff events from the PluginEditor to the PluginProcessor : void PolySynthAudioProcessor::keyOn(int pitch, int velocity) { faustObject->keyOn(pitch,velocity); } void PolySynthAudioProcessor::keyOff(int pitch) { faustObject->keyOff(pitch); } void PolySynthAudioProcessor::setCutoff(float cutoff) { faustObject->setParamValue(\"cutoff\",cutoff); } Don't forget to declare these methods in PluginProcessor.h , of course. keyOn will allocate a new voice, convert its pitch parameter into a frequency that will be sent automatically to the Faust freq parameter, velocity is converted to a level that will be sent to the gain parameter, and the gate parameter is set to 1. Inversely, keyOff sets gate to 0 and waits for t60 to be reached to de-allocate the current voice. keyOn returns a voice ID whose type is unsigned long . This ID can then be used to change the parameter of a specific voice. We're not using this functionality in the example presented in this tutorial but here is how this would work: unsigned long voiceID = dspFaust.keyOn(60,110); dspFaust.setVoiceParamValue(\"/synth/cutoff\",voiceID,378); Note that voices can also be allocated directly without using keyOn and keyOff with the newVoice and the deleteVoice methods: unsigned long voiceID = dspFaust.newVoice(); dspFaust.setVoiceParamValue(\"/synth/gate\",voiceID,1); // do something... dspFaust.deleteVoice(voiceID); Using setParamValue as we're doing in the current example, we can set the value of a parameter for all the voices of the DSP engine. The following implementation is extremely primitive and only the messages from the UI keyboard are processed: we're just doing this for the sake of the example. If you've never worked with keyboards and MIDI in JUCE, we strongly recommend you to read this tutorial . In PluginEditor.h , let's first add the following inheritance to the PolySynthAudioProcessorEditor class: class PolySynthAudioProcessorEditor : public AudioProcessorEditor, private MidiInputCallback, private MidiKeyboardStateListener { This is necessary to implement the MIDI callback and the keyboard (UI) listener. This inheritance requires us to implement the following methods in the private section of PluginEditor.h . We also add an instance of a UI keyboard and its associated state as well as a slider and its label to control the cutoff frequency of the lowpass: private: void handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) override; void handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) override; void handleIncomingMidiMessage(MidiInput* source, const MidiMessage& message) override; MidiKeyboardState keyboardState; MidiKeyboardComponent keyboardComponent; Slider cutoffSlider; Label cutoffLabel; In PluginEditor.cpp , we can add the keyboard and the slider to the constructor: PolySynthAudioProcessorEditor::PolySynthAudioProcessorEditor (PolySynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p), keyboardComponent (keyboardState, MidiKeyboardComponent::horizontalKeyboard) { setSize (800, 150); addAndMakeVisible(keyboardComponent); keyboardState.addListener(this); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); } and we must de-allocate the keyboard state listener in the destructor: PolySynthAudioProcessorEditor::~PolySynthAudioProcessorEditor() { keyboardState.removeListener(this); } The implementation of the setCutoff method is detailed later in this tutorial and is very similar to the one described in the previous section. We also need to define the size of the various elements in the interface (as we did before): void PolySynthAudioProcessorEditor::resized() { const int sliderLeft = 80; keyboardComponent.setBounds (10,10,getWidth()-30,100); cutoffSlider.setBounds(sliderLeft, 120, getWidth() - sliderLeft - 20, 20); } MIDI messages are retrieved from the keyboard simply by implementing the following inherited methods: void PolySynthAudioProcessorEditor::handleIncomingMidiMessage (MidiInput* source, const MidiMessage& message) {} void PolySynthAudioProcessorEditor::handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) { processor.keyOn(midiNoteNumber,int(127*velocity)); } void PolySynthAudioProcessorEditor::handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) { processor.keyOff(midiNoteNumber); } That's it folks! Try to compile and run your plug-in, it should just work. Of course, things could be significantly improved here but at this point, you should be able to sail on your own.","title":" 2020-04-10 Faust & JUCE "},{"location":"workshops/2020-04-10-faust-juce/#faust-for-the-confined-adding-faust-dsp-support-to-your-juce-plug-ins","text":"JUCE is a well-known framework for creating audio plug-ins (i.e., VST, AU, AAX, etc.) and applications for a wide range of platforms. Faust can be used to generate ready-to-use JUCE applications and plug-ins implementing the standard user interface (UI) described in the Faust code using faust2juce . However, it is sooo easy to make professional looking UIs from scratch in JUCE that you might want to use Faust to implement the DSP portion of your plug-in and build your own UI. In this tutorial, we demonstrate how to use the Faust compiler to generate a C++ DSP object and how to interface it with your JUCE plug-in/UI. We'll cover basic examples (monophonic synth, polyphonic synth, and audio effect) as well as more advanced applications involving polyphony, etc.","title":"Faust For the Confined: Adding Faust DSP Support to Your JUCE Plug-ins"},{"location":"workshops/2020-04-10-faust-juce/#simple-monophonic-synth-plug-in","text":"<< Download the source of this tutorial >> In this section, we demonstrate how to use a Faust synth to build a plug-in in JUCE with a custom UI from scratch.","title":"Simple Monophonic Synth Plug-In"},{"location":"workshops/2020-04-10-faust-juce/#generating-the-dsp-engine","text":"First, let's implement a basic subtractive synthesizer in Faust based on a filtered sawtooth wave ( FaustSynth.dsp ): Feel free to run it in the web IDE to see how it sounds! The output of the lowpass is split into 2 signals to create a stereo object. Note that all the parameters are smoothed to prevent clicking (we want our plug-in to be clean!). Even gate is smoothed, which will apply a gentle exponential envelope when the trigger signal is sent, etc. Since Faust will not build its own UI here, the type of UI element used in this code doesn't really matter. They just serve as a point of entry to control the parameters of the audio engine we're about to generate. So nentry could be replaced by hslider or vslider , it would not make any difference. However, we encourage you to always write \"coherent\" interfaces in case someone would like to use your Faust code \"as such\" at some point. In order to turn this Faust program into a C++ DSP object usable in JUCE, we must use a Faust architecture file that will wrap the C++ code generated by the Faust compiler (that literally just contains an audio callback function). That's what faustMinimal.h (which is part of the package that you downloaded at the beginning of this tutorial) does. Actually, if you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/gui/MapUI.h\" #include \"faust/gui/meta.h\" #include \"faust/dsp/dsp.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP The faust/... files should be on your system if Faust is installed on it. If not, you can use the inlined version of the architecture file ( faustMinimalInlined.h ) which can also be found in the package that you downloaded at the beginning of this tutorial. MapUI.h will allow us to easily control the parameters of the Faust object using their declared names in the Faust code. The other includes are necessary in most cases and are just parent classes of the DSP class generated by the Faust compiler. <<includeclass>> is where the code generated by the Faust compiler gets pasted. This architecture file can be used with the Faust compiler simply by running: faust -i -a faustMinimal.h FaustSynth.dsp -o FaustSynth.h where FaustSynth.h is the name of the generated file that we will import in our JUCE project later in this tutorial. The -i option inlines the included C++ files in the generated file. Alternatively, if Faust is not installed on your system, the Faust online IDE can be used to carry out the same task by choosing source/cplusplus in the Export (truck) function. The content of the downloaded C++ file can then be copied and pasted between the BEGIN-FAUSTDSP and END-FAUSTDSP tags. We're now ready to create a new JUCE plug-in project!","title":"Generating the DSP Engine"},{"location":"workshops/2020-04-10-faust-juce/#creating-an-empty-juce-plug-in-project","text":"In this section, we'll assume that you're a bit familiar with JUCE . If that's not your case, don't panic and just read their Getting started with the Projucer tutorial. We also recommend you to have a look a the next few following tutorials to have a sense of how things work. They're nice and easy to read! In the Projucer, create a new Audio Plug-In, add the targets that you want, in the settings, make sure that \"Plugin is a Synth\" is enabled. In our case, we named it \"MonoSynth\" (choose this name wisely as it will impact the class names of your program). Now, place the FaustSynth.h file generated in the previous step in the Source folder of your JUCE plug-in project. Then select it in Source in your file browser and drag it to the Projucer so that it becomes visible in the Source tab: At this point, try to compile your plug-in and see if it runs. Remember that JUCE now generates a \"standalone plug-in\" by default which is super convenient to test things without having to open the plug-in in a third party application.","title":"Creating an Empty JUCE Plug-In Project"},{"location":"workshops/2020-04-10-faust-juce/#integrating-the-faust-dsp-object-to-the-juce-project","text":"Let's now integrate our Faust-generated DSP object to the PluginProcessor . Declare the following elements in the private section of the MonoSynthAudioProcessor class of PluginProcessor.h : private: MapUI* fUI; dsp* fDSP; float** outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MonoSynthAudioProcessor) fUI will be used to control the parameters of the Faust DSP, and fDSP will contain the audio DSP/callback itself (that's basically the object generated by the Faust compiler). In order to declare these objects without knowing the definition of MapUI and dsp you'll also have to declare empty class definitions at the beginning of the file: class dsp; class MapUI; class MonoSynthAudioProcessor : public AudioProcessor In PluginProcessor.cpp , include FaustSynth.h at the beginning of the file in the includes section: #include \"PluginProcessor.h\" #include \"PluginEditor.h\" #include \"FaustSynth.h\" Write the following in the prepareToPlay method: void MonoSynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { outputs[channel] = new float[samplesPerBlock]; } } Here, fDSP which is the Faust DSP object is first instantiated. Then fUI which will be used to control the parameters of the DSP is instantiated. These 2 objects are bound together using the buildUserInterface method of fDSP . Finally, memory is allocated for the stereo output of the Faust object. Note that outputs is a double array (one dimension for audio channels and one dimension for audio samples/buffers). Conversly, write the following in the releaseResources method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } Here, we just free the memory allocated in the previous steps when resources are released. Let's now get into the heart of the matter: the audio callback which is implemented through the processBlock method of MonoSynthAudioProcessor : void MonoSynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); fDSP->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } Here, we basically compute one full audio block of size buffer.getNumSamples() , we store it in outputs and we then link outputs to the actual audio output of processBlock ( *buffer.getWritePointer(channel,i) ). At this point, you should be able to produce sound with your plug-in! Temporarily add the following line to the prepareToPlay method to set the value of the gate parameter to one: fUI->setParamValue(\"gate\",1); Note how fUI is used here to configure the parameter of the Faust DSP using its setParamValue method which has 2 arguments: the path/name of the parameter in the Faust code, and its value. Try to compile the plug-in for your desired target (e.g., VST, AU, etc.). In our case we'll juste generate a standalone plug-in for convenience. When running the plug-in, you should now hear sound! Since we want to control the parameters of our synth from the PluginEditor , we must create a series of public methods in PluginProcessor to control each parameter of our synth. In PluginProcessor.h this will look like: public: void setFreq(float freq); void setGain(float gain); void setCutoff(float cutoff); void setGate(bool gate); and the corresponding implementation in PluginProcessor.cpp will be: void MonoSynthAudioProcessor::setFreq(float freq) { fUI->setParamValue(\"freq\",freq); } void MonoSynthAudioProcessor::setGain(float gain) { fUI->setParamValue(\"gain\",gain); } void MonoSynthAudioProcessor::setGate(bool gate) { if(gate) { fUI->setParamValue(\"gate\",1); } else { fUI->setParamValue(\"gate\",0); } } void MonoSynthAudioProcessor::setCutoff(float cutoff) { fUI->setParamValue(\"cutoff\",cutoff); } That's it for the PluginProcessor ! Easy isn't it ;)? Now, let's add a basic interface to control this synth. We add a series of sliders, button, and labels to the private section of MonoSynthAudioProcessorEditor in PluginEditor.h : private: Slider frequencySlider; Slider gainSlider; Slider cutoffSlider; ToggleButton onOffButton; Label frequencyLabel; Label gainLabel; Label cutoffLabel; Label onOffLabel; and their corresponding implementation in PluginEditor.cpp : MonoSynthAudioProcessorEditor::MonoSynthAudioProcessorEditor(MonoSynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { setSize (800, 130); addAndMakeVisible(frequencySlider); frequencySlider.setRange(50.0, 5000.0); frequencySlider.setSkewFactorFromMidPoint(500.0); frequencySlider.setValue(300); frequencySlider.onValueChange = [this] { processor.setFreq(frequencySlider.getValue()); }; addAndMakeVisible(frequencyLabel); frequencyLabel.setText(\"Frequency\", dontSendNotification); frequencyLabel.attachToComponent(&frequencySlider, true); addAndMakeVisible(gainSlider); gainSlider.setRange(0.0, 1.0); gainSlider.setValue(0.5); gainSlider.onValueChange = [this] { processor.setGain(gainSlider.getValue()); }; addAndMakeVisible(gainLabel); gainLabel.setText(\"Gain\", dontSendNotification); gainLabel.attachToComponent (&gainSlider, true); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); addAndMakeVisible(onOffButton); onOffButton.onClick = [this] { processor.setGate(onOffButton.getToggleState()); }; addAndMakeVisible(onOffLabel); onOffLabel.setText(\"On/Off\", dontSendNotification); onOffLabel.attachToComponent (&onOffButton, true); } The methods that we declared in the previous step are basically called to set the value of the parameters of our DSP engine thanks to the processor object. The resized method must be implemented so that the various UI elements that we created actually have a size: void MonoSynthAudioProcessorEditor::resized() { const int sliderLeft = 80; frequencySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); gainSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); cutoffSlider.setBounds(sliderLeft, 70, getWidth() - sliderLeft - 20, 20); onOffButton.setBounds(sliderLeft, 100, getWidth() - sliderLeft - 20, 20); } Finally, make sure that you clean the implementation of the paint method to get rid of the default ugly \"Hello World:\" void MonoSynthAudioProcessorEditor::paint (Graphics& g) { g.fillAll(getLookAndFeel().findColour (ResizableWindow::backgroundColourId)); } Compile your plug-in and run it, it should look like this: The goal of this section was just to show you how to integrate a Faust DSP object into a JUCE plug-in project and how to control it with a simple UI. Once again, JUCE is a powerful tool to implement sophisticated UI in a very simple way. You'll find all the documentation you need on their website](https://juce.com/) to start making beautiful plug-ins!","title":"Integrating the Faust DSP Object to The JUCE Project"},{"location":"workshops/2020-04-10-faust-juce/#simple-audio-effect-plug-in","text":"<< Download the source of this tutorial >> In this section, we demonstrate how to use a Faust effect to build a plug-in in JUCE with a custom UI from scratch.","title":"Simple Audio Effect Plug-In"},{"location":"workshops/2020-04-10-faust-juce/#generating-the-dsp-engine_1","text":"The steps for generating an audio effect C++ DSP object with Faust are exactly the same as for a synth ( see the previous section ) and the faustMinimal.h architecture file can be used as well. For this example, we'll be using a stereo echo: Then run something like: faust -i -a faustMinimal.h FaustEffect.dsp -o Effect/Source/FaustEffect.h","title":"Generating the DSP Engine"},{"location":"workshops/2020-04-10-faust-juce/#creating-a-new-empty-juce-plug-in-project","text":"The steps are the same as for the mono synthesizer tutorial except that the \"Plug-in is a Synth\" checkbox shouldn't be checked this time. For this example, we decided to give a very bad and explicit name to our plug-in project: \"Effect.\"\" Finally, import the C++ file generated in the previous step (i.e., FaustEffect.h ) in your project.","title":"Creating a New Empty JUCE Plug-In Project"},{"location":"workshops/2020-04-10-faust-juce/#integrating-the-faust-dsp-object-to-the-juce-project_1","text":"Steps are also similar to the mono synthesizer tutorial here, except that an audio input should be created. So, in PluginProcessor.h , we'll have: private: MapUI* fUI; dsp* fDSP; float **inputs; float **outputs; In PluginProcessor.cpp , for the prepareToPlay and releaseResources methods: void EffectAudioProcessor::prepareToPlay (double sampleRate, int samplesPerBlock) { fDSP = new mydsp(); fDSP->init(sampleRate); fUI = new MapUI(); fDSP->buildUserInterface(fUI); inputs = new float*[2]; outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel) { inputs[channel] = new float[samplesPerBlock]; outputs[channel] = new float[samplesPerBlock]; } } void EffectAudioProcessor::releaseResources() { delete fDSP; delete fUI; for (int channel = 0; channel < 2; ++channel) { delete[] inputs[channel]; delete[] outputs[channel]; } delete [] inputs; delete [] outputs; } and the audio callback: void EffectAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); for (int channel = 0; channel < totalNumInputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { inputs[channel][i] = *buffer.getWritePointer(channel,i); } } fDSP->compute(buffer.getNumSamples(),inputs,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++){ *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } This should be relatively self-explanatory. Of course, the corresponding control methods should be created as well, etc.: void EffectAudioProcessor::setDelay(float delay) { fUI->setParamValue(\"delay\",delay); } void EffectAudioProcessor::setFeedback(float feedback) { fUI->setParamValue(\"feedback\",feedback); } On the interface side, things can be easily adapted to match this new configuration with something like this: EffectAudioProcessorEditor::EffectAudioProcessorEditor (EffectAudioProcessor& p) : AudioProcessorEditor(&p), processor(p) { // Make sure that before the constructor has finished, you've set the // editor's size to whatever you need it to be. setSize(800, 100); addAndMakeVisible (delaySlider); delaySlider.setRange(0.0, 1.0); delaySlider.setValue(0.5); delaySlider.onValueChange = [this] { processor.setDelay(delaySlider.getValue()); }; addAndMakeVisible(delayLabel); delayLabel.setText(\"Delay (s)\", dontSendNotification); delayLabel.attachToComponent (&delaySlider, true); addAndMakeVisible(feedbackSlider); feedbackSlider.setRange(0.0, 1.0); feedbackSlider.setValue(0.5); feedbackSlider.onValueChange = [this] { processor.setFeedback(feedbackSlider.getValue()); }; addAndMakeVisible(feedbackLabel); feedbackLabel.setText(\"Feedback\", dontSendNotification); feedbackLabel.attachToComponent(&feedbackSlider, true); } void EffectAudioProcessorEditor::resized() { const int sliderLeft = 80; delaySlider.setBounds(sliderLeft, 10, getWidth() - sliderLeft - 20, 20); feedbackSlider.setBounds(sliderLeft, 40, getWidth() - sliderLeft - 20, 20); } Try to compile your program and you should have a beautiful effect plug-in :).","title":"Integrating the Faust DSP Object to The JUCE Project"},{"location":"workshops/2020-04-10-faust-juce/#creating-and-using-a-polyphonic-faust-dsp-object","text":"<< Download the source of this tutorial >> The procedure to create a polyphonic synthesizer DSP object is slightly different than for a simple monophonic synth such as the one presented at the beginning of this tutorial. Here, we'll be using the same Faust program as one used for the mono synthesizer example . To enable polyphony, we just need to configure the nvoices metadata which allows us to specify the maximum number of voices of polyphony of the DSP object that will be generated: The package downloadable at the beginning of this tutorial contains a Faust architecture file slightly different from the one used in the previous examples (mono synth and effect): faustMinimalPoly.h . If you open it, you'll see: #include <cmath> #include <cstring> #include \"faust/misc.h\" #include \"faust/gui/UI.h\" #include \"faust/gui/JSONUIDecoder.h\" #include \"faust/dsp/dsp.h\" #include \"faust/dsp/dsp-adapter.h\" #include \"faust/gui/meta.h\" // BEGIN-FAUSTDSP <<includeIntrinsic>> <<includeclass>> // END-FAUSTDSP #include \"faust/dsp/faust-poly-engine.h\" #include \"faust/audio/dummy-audio.h\" std::list<GUI*> GUI::fGuiList; ztimedmap GUI::gTimedZoneMap; faust-poly-engine.h contains the FaustPolyEngine class which can be used to turn a Faust C++ DSP object into a polyphonic synthesizer. In order for this class to work, an \"audio driver\" must be provided which is what the dummyaudio class available in dummy-audio.h can be used for. It also allows us to pass the sampling rate and the buffer size to FaustPolyEngine . Compile the previous Faust program using this architecture file either by using the Faust command-line compiler or web IDE: faust -i -a faustMinimalPoly.h FaustSynth.dsp -o PolySynth/Source/FaustSynth.h and integrate FaustSynth.h to a new JUCE synth plug-in project (following the same steps as in the mono synth tutorial ). In PluginProcessor.h , declare the following objects: private: audio *driver; FaustPolyEngine *faustObject; float **outputs; //============================================================================== JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PolySynthAudioProcessor) Once again, faustObject here will be the polyphonic Faust object and driver will be used to pass the sampling rate and buffer size to the system. Don't forget the declare the corresponding empty classes at the beginning of the file: class FaustPolyEngine; class audio; class PolySynthAudioProcessor : public AudioProcessor { In PluginProcessor.cpp , first don't forget to include FaustSynth.h . Then fill prepareToPlay with the following code: void PolySynthAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) { driver = new dummyaudio(sampleRate,samplesPerBlock); faustObject = new FaustPolyEngine(NULL,driver,NULL); outputs = new float*[2]; for (int channel = 0; channel < 2; ++channel){ outputs[channel] = new float[samplesPerBlock]; } } First, the empty audio driver is instantiated and passed to the Faust polyphonic object. Of course, we allocate memory for the audio output. Resources are freed as follows: void PolySynthAudioProcessor::releaseResources() { //delete faustObject; delete driver; for (int channel = 0; channel < 2; ++channel) { delete[] outputs[channel]; } delete [] outputs; } The processBlock method works the same way as for the mono synth tutorial except that the compute method is called here directly from the faustObject ( FaustPolyEngine ). void PolySynthAudioProcessor::processBlock (AudioBuffer<float>& buffer, MidiBuffer& midiMessages) { ScopedNoDenormals noDenormals; auto totalNumInputChannels = getTotalNumInputChannels(); auto totalNumOutputChannels = getTotalNumOutputChannels(); faustObject->compute(buffer.getNumSamples(),NULL,outputs); for (int channel = 0; channel < totalNumOutputChannels; ++channel) { for (int i = 0; i < buffer.getNumSamples(); i++) { *buffer.getWritePointer(channel,i) = outputs[channel][i]; } } } While the setParamValue method can now be called directly from faustObject to set the value of specific parameters of the Faust object, other polyphony-specific methods are available such as keyOn and keyOff . For an exhaustive list, you can have a look at the source of FaustPolyEngine which should just speak by itself. Our final goal for this tutorial is to create a simple plug-in with the following interface: Hence, the Faust DSP object should be controlled with a polyphonic keyboard. New methods must be created in PluginProcessor.cpp to send keyon and keyoff events from the PluginEditor to the PluginProcessor : void PolySynthAudioProcessor::keyOn(int pitch, int velocity) { faustObject->keyOn(pitch,velocity); } void PolySynthAudioProcessor::keyOff(int pitch) { faustObject->keyOff(pitch); } void PolySynthAudioProcessor::setCutoff(float cutoff) { faustObject->setParamValue(\"cutoff\",cutoff); } Don't forget to declare these methods in PluginProcessor.h , of course. keyOn will allocate a new voice, convert its pitch parameter into a frequency that will be sent automatically to the Faust freq parameter, velocity is converted to a level that will be sent to the gain parameter, and the gate parameter is set to 1. Inversely, keyOff sets gate to 0 and waits for t60 to be reached to de-allocate the current voice. keyOn returns a voice ID whose type is unsigned long . This ID can then be used to change the parameter of a specific voice. We're not using this functionality in the example presented in this tutorial but here is how this would work: unsigned long voiceID = dspFaust.keyOn(60,110); dspFaust.setVoiceParamValue(\"/synth/cutoff\",voiceID,378); Note that voices can also be allocated directly without using keyOn and keyOff with the newVoice and the deleteVoice methods: unsigned long voiceID = dspFaust.newVoice(); dspFaust.setVoiceParamValue(\"/synth/gate\",voiceID,1); // do something... dspFaust.deleteVoice(voiceID); Using setParamValue as we're doing in the current example, we can set the value of a parameter for all the voices of the DSP engine. The following implementation is extremely primitive and only the messages from the UI keyboard are processed: we're just doing this for the sake of the example. If you've never worked with keyboards and MIDI in JUCE, we strongly recommend you to read this tutorial . In PluginEditor.h , let's first add the following inheritance to the PolySynthAudioProcessorEditor class: class PolySynthAudioProcessorEditor : public AudioProcessorEditor, private MidiInputCallback, private MidiKeyboardStateListener { This is necessary to implement the MIDI callback and the keyboard (UI) listener. This inheritance requires us to implement the following methods in the private section of PluginEditor.h . We also add an instance of a UI keyboard and its associated state as well as a slider and its label to control the cutoff frequency of the lowpass: private: void handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) override; void handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) override; void handleIncomingMidiMessage(MidiInput* source, const MidiMessage& message) override; MidiKeyboardState keyboardState; MidiKeyboardComponent keyboardComponent; Slider cutoffSlider; Label cutoffLabel; In PluginEditor.cpp , we can add the keyboard and the slider to the constructor: PolySynthAudioProcessorEditor::PolySynthAudioProcessorEditor (PolySynthAudioProcessor& p) : AudioProcessorEditor(&p), processor(p), keyboardComponent (keyboardState, MidiKeyboardComponent::horizontalKeyboard) { setSize (800, 150); addAndMakeVisible(keyboardComponent); keyboardState.addListener(this); addAndMakeVisible(cutoffSlider); cutoffSlider.setRange(50.0, 10000.0); cutoffSlider.setValue(5000.0); cutoffSlider.onValueChange = [this] { processor.setCutoff(cutoffSlider.getValue()); }; addAndMakeVisible(cutoffLabel); cutoffLabel.setText(\"Cutoff\", dontSendNotification); cutoffLabel.attachToComponent(&cutoffSlider, true); } and we must de-allocate the keyboard state listener in the destructor: PolySynthAudioProcessorEditor::~PolySynthAudioProcessorEditor() { keyboardState.removeListener(this); } The implementation of the setCutoff method is detailed later in this tutorial and is very similar to the one described in the previous section. We also need to define the size of the various elements in the interface (as we did before): void PolySynthAudioProcessorEditor::resized() { const int sliderLeft = 80; keyboardComponent.setBounds (10,10,getWidth()-30,100); cutoffSlider.setBounds(sliderLeft, 120, getWidth() - sliderLeft - 20, 20); } MIDI messages are retrieved from the keyboard simply by implementing the following inherited methods: void PolySynthAudioProcessorEditor::handleIncomingMidiMessage (MidiInput* source, const MidiMessage& message) {} void PolySynthAudioProcessorEditor::handleNoteOn(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float velocity) { processor.keyOn(midiNoteNumber,int(127*velocity)); } void PolySynthAudioProcessorEditor::handleNoteOff(MidiKeyboardState*, int midiChannel, int midiNoteNumber, float /*velocity*/) { processor.keyOff(midiNoteNumber); } That's it folks! Try to compile and run your plug-in, it should just work. Of course, things could be significantly improved here but at this point, you should be able to sail on your own.","title":"Creating and Using a Polyphonic Faust DSP Object"},{"location":"workshops/2020-11-21-faust-vcvrack/","text":"Using Faust with VCV Rack VCV Rack is virtual modular synthesizer, allowing thousands of separated developed modules to be connected in patches to synthesize and process sounds. A large community of developers are providing tons of modules to be installed in the application as libraries , and a lot of them are developed as open-source projects on GitHub . In this tutorial, we'll show how to use the Faust language to generate monophonic or polyphonic modules: either using the Faust aware programmable VCV Prototype to edit/compile/test Faust DSP code or using the faust2vcvrack tool with allows to generate standalone modules to introduce module development, a quick introduction on using C++ to develop modules will be done first. Installation Get the binary version for your OS here. Install the VCV Rack SDK From Plugin Development Tutorial page and the SDK itself for your OS. Don't forget to setup the RACK_DIR variable: export RACK_DIR=<Rack SDK folder> . Compiling the VCV Prototype module Faust version The Faust compiler can be embedded in applications or plugins using libfaust , and DSP code can be edited and JIT compiled on the fly. You'll have to clone and compile the GitHub project . Be use to use the faust branch and follow the explanations given. Then you should be ready for this workshop ! The modular principle VCV Rack follows the Modular synthesizers principe explained on this Wikipedia article : Modular synthesizers are synthesizers composed of separate modules of different functions. The modules can be connected together with patch cords, a matrix patching system, or switches by the user to create a patch . The output (voltages) from the modules may function as (audio) signals, control voltages, or logic/timing conditions. Typical modules are oscillators (operate on frequency), filters (spectrum), amplifiers/gates (amplitude) and Envelope generators (dynamic control). To do that, control signals (CV) run at audio rate, and so the entire patch is triggered with audio buffers of only one sample. When described as CV signals, parameters can thus be changed in real-time by other signals coming from any module, just by connecting them. So a kind of blur between audio and control signals is part in this model and signals can be connected anywhere. Since software modules mimic real physical ones, they somewhat follow the same conventions to represent signal range, typically with [-5v...5v] or [0v..10v] values , or 1V/octave for MIDI signals. Read the voltage standard page for a more complete description. Control parameters can also be changed from the module GUI using switches, knobs.etc... Modules can be monophonic or polyphonic (up to 16 channels) , where each cable actually transport several (usually related) signals. The polyphonic model is obviously used for instruments, but can also be used for effects. Polyhonic modules have thicker cables in the GUI. Developing C++ Modules Before using Faust to develop modules, let's have a look at the standard procedure. Modules are usually created with C++ using the VCV Rack SDK that gives developers several tools to start with. Following the tutorial here , a template project can be created: Generating a template ./helper.py createplugin MyPlugin The created folder contains a Makefile that can be used to compile and install the module in your (previously installed) VCV Rack application: make && make install GUI description using SVG The module GUI is done using SVG. Developers will classically prepare the background layer with Inkscape or a similar tool, with special conventions to describe audio or CV inputs/outputs, UI items (knobs, lights, custom widgets... ). Here a example of a basic SVG template with a light , a param (like knob), an audio or CV input , and an audio or CV output : Inside the module project, the following command will decode the SVG file and generate template C++ code to create the various widget: ../helper.py createmodule MyModule res/MyModule.svg src/MyModule.cpp Adding DSP code Then C++ code will be added to implement as simple oscillator in the process function: float phase = 0.f; float freq = 440.f; void process(const ProcessArgs &args) override { // Accumulate the phase phase += freq * args.sampleTime; if (phase >= 0.5f) phase -= 1.f; // Compute the sine output float sine = std::sin(2.f * M_PI * phase); // Audio signals are typically +/-5V outputs[SINE_OUTPUT].setVoltage(5.f * sine); } The following line in plugin.cpp has to be uncommented: p->addModel(modelMyModule); and well as in plugin.hpp: extern Model* modelMyModule; And compilation and installation of the module has to be done again: make && make install Programming using the Faust aware VCV Prototype module The VCV Prototype module runs scripting languages for prototyping, learning, and live coding. It can currently be programmed using JavaScript, Lua , Vult , or PureData . A generic GUI with 6 inputs/outputs (either audio or CV signals), 6 knobs, 6 lights (RGB LEDs) or 6 switches (with RGB LEDs) is defined. Note that only monophonic examples can be coded with the prototype. Faust support thanks to libfaust embedding the Interpreter backend has been added. It allows to edit/compile/execute DSP programs on the fly, with acceptable performances (even if using the LLVM JIT would allow to generate faster code, but as the expense of a much more complicated installation procedure). Editing/compiling/executing DSP files Faust DSP files have to be loaded in VCV Prototype and edited in a external editor (Visual Studio Code, Atom...). Each time the file is saved, it will be recompiled and executed. To possibly save compilation time, the DSP machine code is saved in a cache, and possibly restored the next time the session will be loaded. The 6 audio inputs/outputs can be accessed in order in the Faust DSP which can thus use up to 6 channels. The 6 switches , knobs as well as the lights and switchLights can be connected to UI controllers using metadata: [switch:N] (with N from 1 to 6) has to be used in a button or checkbox item to connect it to the prototype interface switch number N [knob:N] (with N from 1 to 6) has to be used in a vslider , hslider or nentry item to connect it to the prototype interface knob number N. The knob [0..1] range will be mapped to the slider/nentry [min..max] range [light_red:N|light_green:N|light_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph item to connect it to the prototype interface light number N [switchlight_red:N|switchlight_green:N|switchlight_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph to connect it to the prototype interface switchLight number N So a button or checkbox UI item can use the [switch:N] metadata to be associated with the corresponding GUI switch, which color can be controlled using the switchlight_xx:N metadata. For instance: gate = button(\"gate [switch:1\") : hbargraph(\"[switchlight_red:1]\", 0, 1); can be written to describe a button which become red when pressed check = checkbox(\"check [switch:2]\") : vbargraph(\"[switchlight_red:2]\", 0, 1) : vbargraph(\"[switchlight_green:2]\", 0, 1) : vbargraph(\"[switchlight_blue:2]\", 0, 1); can be written to describe a checkbox which become white when checked Other metadata: [scale:lin|log|exp] metadata is implemented. The rack.lib Faust library contains usefull functions to convert CV signals, and can be enriched if needed. Note that only monophonic DSP programs can be described. DSP examples Here is a simple example showing how oscillators can be controlled by GUI items, associated with metadata in the DSP code: Following the VCV Prototype model, note that audio outputs are multipled by 5 to follow the [-5v..5v] range convention. The VCV Prototype standard examples ported to Faust can be seen in the examples folder: gain.dsp shows how switches and knobs can be connected using metadata , and even change color when pressed or moved: vco.dsp shows an oscillator with frequency controlled by a knob and a CV pich signal (following the 1V/octave convention): rainbow.dsp Some additional examples: synth.dsp demonstrates how to use all different VCV Prototype UI items organ.dsp demonstrates a MIDI controllable additive synthesis based organ physicalmodel.dsp demonstrates a modal synthesis based bell connected to a reverb Using faust2vcvrack The faust2vcvrack tool compiles a Faust DSP program in a folder containing the VCV Rack plugin C++ source code and a Makefile to compile it. By default the resulting C++ code is compiled and installed in the VCV Rack application: faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [additional Faust options (-vec -vs 8...)] <file.dsp> The tool is now part of the master-dev branch on GitHub, or can be used with Faust IDE , and by selecting the appropriate export targets ( vcvrack , vcvrack-poly8 , or vcvrack-poly16 ). Here are the available options: -soundfile when compiling a DSP using the 'soundfile' primitive, add required resources -source to only create the source folder -nvoices <num> to produce a polyphonic self-contained DSP with <num> voices, ready to be used with MIDI Faust DSP code classically produces audio signals in the [-1..1] range. Since VCV expects audio signals in the [-5v..5v] range, they are automatically converted in the architecture file . CV control in the [0v..10v] volts range will be mapped to the controllers [min..max] range. Polyphony support Polyphonic modules can be created using the -nvoices <num> parameter up to 16 voices. The freq/gate/gain convention can be used in the DSP code. VCV Rack follows the 1V/octave convention for MIDI pitch values, so the MIDI signals are automatically converted to freq using this convention. Gain and gates signals (using the [0v..10v] range) are converted to [0..1] values. Note that creating polyphonic effects also make sense in VCV Rack. For instance a reverb connected to a polyphonic instrument would need to be polyphonic. Thus the -nvoices <num> parameter can also be used in this case. Metadata Controllers (typically buttons , sliders , nentry or bargraph ) will be automatically transformed in GUI items (like switches, knobs or lights). But they can alternatively be connected to CV inputs/outputs using a metadata: [CV:N] can be used in input (typically sliders or nentry ) or output (typically bargraph ) controllers to connect them to CV instead of regular GUI parameters. DSP examples Here is a simple example showing how oscillators can be controlled by UI items. One switch, one button and two knobs will be created in the GUI: A polyphonic instrument with freq/gate/gain controllers associated with VC MIDI inputs, using the [CV:N] metadata, to be compiled with the -nvoices <num> option: This polyphonic instrument can then be connected to a polyphonic reverb, to be also compiled with the -nvoices <num> option:","title":" 2020-11-21 Faust & VCV Rack "},{"location":"workshops/2020-11-21-faust-vcvrack/#using-faust-with-vcv-rack","text":"VCV Rack is virtual modular synthesizer, allowing thousands of separated developed modules to be connected in patches to synthesize and process sounds. A large community of developers are providing tons of modules to be installed in the application as libraries , and a lot of them are developed as open-source projects on GitHub . In this tutorial, we'll show how to use the Faust language to generate monophonic or polyphonic modules: either using the Faust aware programmable VCV Prototype to edit/compile/test Faust DSP code or using the faust2vcvrack tool with allows to generate standalone modules to introduce module development, a quick introduction on using C++ to develop modules will be done first.","title":"Using Faust with VCV Rack"},{"location":"workshops/2020-11-21-faust-vcvrack/#installation","text":"Get the binary version for your OS here.","title":"Installation"},{"location":"workshops/2020-11-21-faust-vcvrack/#install-the-vcv-rack-sdk","text":"From Plugin Development Tutorial page and the SDK itself for your OS. Don't forget to setup the RACK_DIR variable: export RACK_DIR=<Rack SDK folder> .","title":"Install the VCV Rack SDK"},{"location":"workshops/2020-11-21-faust-vcvrack/#compiling-the-vcv-prototype-module-faust-version","text":"The Faust compiler can be embedded in applications or plugins using libfaust , and DSP code can be edited and JIT compiled on the fly. You'll have to clone and compile the GitHub project . Be use to use the faust branch and follow the explanations given. Then you should be ready for this workshop !","title":"Compiling the VCV Prototype module Faust version"},{"location":"workshops/2020-11-21-faust-vcvrack/#the-modular-principle","text":"VCV Rack follows the Modular synthesizers principe explained on this Wikipedia article : Modular synthesizers are synthesizers composed of separate modules of different functions. The modules can be connected together with patch cords, a matrix patching system, or switches by the user to create a patch . The output (voltages) from the modules may function as (audio) signals, control voltages, or logic/timing conditions. Typical modules are oscillators (operate on frequency), filters (spectrum), amplifiers/gates (amplitude) and Envelope generators (dynamic control). To do that, control signals (CV) run at audio rate, and so the entire patch is triggered with audio buffers of only one sample. When described as CV signals, parameters can thus be changed in real-time by other signals coming from any module, just by connecting them. So a kind of blur between audio and control signals is part in this model and signals can be connected anywhere. Since software modules mimic real physical ones, they somewhat follow the same conventions to represent signal range, typically with [-5v...5v] or [0v..10v] values , or 1V/octave for MIDI signals. Read the voltage standard page for a more complete description. Control parameters can also be changed from the module GUI using switches, knobs.etc... Modules can be monophonic or polyphonic (up to 16 channels) , where each cable actually transport several (usually related) signals. The polyphonic model is obviously used for instruments, but can also be used for effects. Polyhonic modules have thicker cables in the GUI.","title":"The modular principle"},{"location":"workshops/2020-11-21-faust-vcvrack/#developing-c-modules","text":"Before using Faust to develop modules, let's have a look at the standard procedure. Modules are usually created with C++ using the VCV Rack SDK that gives developers several tools to start with. Following the tutorial here , a template project can be created:","title":"Developing C++ Modules"},{"location":"workshops/2020-11-21-faust-vcvrack/#generating-a-template","text":"./helper.py createplugin MyPlugin The created folder contains a Makefile that can be used to compile and install the module in your (previously installed) VCV Rack application: make && make install","title":"Generating a template"},{"location":"workshops/2020-11-21-faust-vcvrack/#gui-description-using-svg","text":"The module GUI is done using SVG. Developers will classically prepare the background layer with Inkscape or a similar tool, with special conventions to describe audio or CV inputs/outputs, UI items (knobs, lights, custom widgets... ). Here a example of a basic SVG template with a light , a param (like knob), an audio or CV input , and an audio or CV output : Inside the module project, the following command will decode the SVG file and generate template C++ code to create the various widget: ../helper.py createmodule MyModule res/MyModule.svg src/MyModule.cpp","title":"GUI description using SVG"},{"location":"workshops/2020-11-21-faust-vcvrack/#adding-dsp-code","text":"Then C++ code will be added to implement as simple oscillator in the process function: float phase = 0.f; float freq = 440.f; void process(const ProcessArgs &args) override { // Accumulate the phase phase += freq * args.sampleTime; if (phase >= 0.5f) phase -= 1.f; // Compute the sine output float sine = std::sin(2.f * M_PI * phase); // Audio signals are typically +/-5V outputs[SINE_OUTPUT].setVoltage(5.f * sine); } The following line in plugin.cpp has to be uncommented: p->addModel(modelMyModule); and well as in plugin.hpp: extern Model* modelMyModule; And compilation and installation of the module has to be done again: make && make install","title":"Adding DSP code"},{"location":"workshops/2020-11-21-faust-vcvrack/#programming-using-the-faust-aware-vcv-prototype-module","text":"The VCV Prototype module runs scripting languages for prototyping, learning, and live coding. It can currently be programmed using JavaScript, Lua , Vult , or PureData . A generic GUI with 6 inputs/outputs (either audio or CV signals), 6 knobs, 6 lights (RGB LEDs) or 6 switches (with RGB LEDs) is defined. Note that only monophonic examples can be coded with the prototype. Faust support thanks to libfaust embedding the Interpreter backend has been added. It allows to edit/compile/execute DSP programs on the fly, with acceptable performances (even if using the LLVM JIT would allow to generate faster code, but as the expense of a much more complicated installation procedure).","title":"Programming using the Faust aware VCV Prototype module"},{"location":"workshops/2020-11-21-faust-vcvrack/#editingcompilingexecuting-dsp-files","text":"Faust DSP files have to be loaded in VCV Prototype and edited in a external editor (Visual Studio Code, Atom...). Each time the file is saved, it will be recompiled and executed. To possibly save compilation time, the DSP machine code is saved in a cache, and possibly restored the next time the session will be loaded. The 6 audio inputs/outputs can be accessed in order in the Faust DSP which can thus use up to 6 channels. The 6 switches , knobs as well as the lights and switchLights can be connected to UI controllers using metadata: [switch:N] (with N from 1 to 6) has to be used in a button or checkbox item to connect it to the prototype interface switch number N [knob:N] (with N from 1 to 6) has to be used in a vslider , hslider or nentry item to connect it to the prototype interface knob number N. The knob [0..1] range will be mapped to the slider/nentry [min..max] range [light_red:N|light_green:N|light_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph item to connect it to the prototype interface light number N [switchlight_red:N|switchlight_green:N|switchlight_blue:N] (with N from 1 to 6) has to be used in a vbargraph or hbargraph to connect it to the prototype interface switchLight number N So a button or checkbox UI item can use the [switch:N] metadata to be associated with the corresponding GUI switch, which color can be controlled using the switchlight_xx:N metadata. For instance: gate = button(\"gate [switch:1\") : hbargraph(\"[switchlight_red:1]\", 0, 1); can be written to describe a button which become red when pressed check = checkbox(\"check [switch:2]\") : vbargraph(\"[switchlight_red:2]\", 0, 1) : vbargraph(\"[switchlight_green:2]\", 0, 1) : vbargraph(\"[switchlight_blue:2]\", 0, 1); can be written to describe a checkbox which become white when checked Other metadata: [scale:lin|log|exp] metadata is implemented. The rack.lib Faust library contains usefull functions to convert CV signals, and can be enriched if needed. Note that only monophonic DSP programs can be described.","title":"Editing/compiling/executing DSP files"},{"location":"workshops/2020-11-21-faust-vcvrack/#dsp-examples","text":"Here is a simple example showing how oscillators can be controlled by GUI items, associated with metadata in the DSP code: Following the VCV Prototype model, note that audio outputs are multipled by 5 to follow the [-5v..5v] range convention. The VCV Prototype standard examples ported to Faust can be seen in the examples folder: gain.dsp shows how switches and knobs can be connected using metadata , and even change color when pressed or moved: vco.dsp shows an oscillator with frequency controlled by a knob and a CV pich signal (following the 1V/octave convention): rainbow.dsp Some additional examples: synth.dsp demonstrates how to use all different VCV Prototype UI items organ.dsp demonstrates a MIDI controllable additive synthesis based organ physicalmodel.dsp demonstrates a modal synthesis based bell connected to a reverb","title":"DSP examples"},{"location":"workshops/2020-11-21-faust-vcvrack/#using-faust2vcvrack","text":"The faust2vcvrack tool compiles a Faust DSP program in a folder containing the VCV Rack plugin C++ source code and a Makefile to compile it. By default the resulting C++ code is compiled and installed in the VCV Rack application: faust2vcvrack [-soundfile] [-source] [-nvoices <num>] [additional Faust options (-vec -vs 8...)] <file.dsp> The tool is now part of the master-dev branch on GitHub, or can be used with Faust IDE , and by selecting the appropriate export targets ( vcvrack , vcvrack-poly8 , or vcvrack-poly16 ). Here are the available options: -soundfile when compiling a DSP using the 'soundfile' primitive, add required resources -source to only create the source folder -nvoices <num> to produce a polyphonic self-contained DSP with <num> voices, ready to be used with MIDI Faust DSP code classically produces audio signals in the [-1..1] range. Since VCV expects audio signals in the [-5v..5v] range, they are automatically converted in the architecture file . CV control in the [0v..10v] volts range will be mapped to the controllers [min..max] range.","title":"Using faust2vcvrack"},{"location":"workshops/2020-11-21-faust-vcvrack/#polyphony-support","text":"Polyphonic modules can be created using the -nvoices <num> parameter up to 16 voices. The freq/gate/gain convention can be used in the DSP code. VCV Rack follows the 1V/octave convention for MIDI pitch values, so the MIDI signals are automatically converted to freq using this convention. Gain and gates signals (using the [0v..10v] range) are converted to [0..1] values. Note that creating polyphonic effects also make sense in VCV Rack. For instance a reverb connected to a polyphonic instrument would need to be polyphonic. Thus the -nvoices <num> parameter can also be used in this case.","title":"Polyphony support"},{"location":"workshops/2020-11-21-faust-vcvrack/#metadata","text":"Controllers (typically buttons , sliders , nentry or bargraph ) will be automatically transformed in GUI items (like switches, knobs or lights). But they can alternatively be connected to CV inputs/outputs using a metadata: [CV:N] can be used in input (typically sliders or nentry ) or output (typically bargraph ) controllers to connect them to CV instead of regular GUI parameters.","title":"Metadata"},{"location":"workshops/2020-11-21-faust-vcvrack/#dsp-examples_1","text":"Here is a simple example showing how oscillators can be controlled by UI items. One switch, one button and two knobs will be created in the GUI: A polyphonic instrument with freq/gate/gain controllers associated with VC MIDI inputs, using the [CV:N] metadata, to be compiled with the -nvoices <num> option: This polyphonic instrument can then be connected to a polyphonic reverb, to be also compiled with the -nvoices <num> option:","title":"DSP examples"}]}
\ No newline at end of file
diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz
index 64a12aa6b6e0c010a5aa7aa6f7d66cf628d85ae2..9799043fbcff8fe1d8a4aec61421f967184a2ac9 100644
GIT binary patch
delta 13
Ucmb=gXP58h;3zD;I+48s03FT*ivR!s

delta 13
Ucmb=gXP58h;9x2`Gm*Ul02=`W5C8xG

diff --git a/mkdocs/docs/manual/deploying.md b/mkdocs/docs/manual/deploying.md
index 0be90da9c6..9661a0bbdc 100644
--- a/mkdocs/docs/manual/deploying.md
+++ b/mkdocs/docs/manual/deploying.md
@@ -17,13 +17,13 @@ The library offers functionality for compiling Faust DSP code into WebAssembly,
 
 Web targets can be exported from the [Faust Editor](https://fausteditor.grame.fr) or [Faust IDE](https://faustide.grame.fr) using the remote compilation service. Choose `Platform = web`, then `Architecture` with one of the following target:
 
-- `wasmjs` allows you to export a ready to use Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.
+- `wasmjs` allows you to export a ready to use Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.
 
-- `wasmjs-poly` allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in the application. An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.
+- `wasmjs-poly` allows you to export a ready to use polyphonic MIDI controllable Web audio node to be integrated in an application. An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.
 
-- `webaudiowasm` allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a [Progressive Web Application](https://en.wikipedia.org/wiki/Progressive_web_app). An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.
+- `webaudiowasm` allows you to export a ready to use Web audio node with a prebuilt GUI, that can be installed as a [Progressive Web Application](https://en.wikipedia.org/wiki/Progressive_web_app). An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.
 
-- `webaudiowasm-poly` allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a [Progressive Web Application](https://en.wikipedia.org/wiki/Progressive_web_app). An example of HTML and JavaScript files demonstrate how the node can be loaded and activated.
+- `webaudiowasm-poly` allows you to export a ready to use polyphonic MIDI controllable Web audio node with a prebuilt GUI, that can be installed as a [Progressive Web Application](https://en.wikipedia.org/wiki/Progressive_web_app). An example of HTML and JavaScript files demonstrates how the node can be loaded and activated.
 
 - `pwa` allows you to export a ready to use [Progressive Web Application](https://en.wikipedia.org/wiki/Progressive_web_app) with a prebuilt GUI, directly usable in the page, and that can possibly be installed and run on smartphone or tablet using the QR Code.