README.md
1# faust2juce
2
3The **faust2juce** tool transforms a Faust DSP program into a fully working JUCE standalone application or plugin, which can possibly be controlled with MIDI or OSC messages. Polyphonic instruments are automatically created from polyphonic aware Faust DSP code, which contains interface parameters with the following `freq`, `gain` and `gate` names. The metadata **declare nvoices "8";** kind of line with a desired value of voices can be added in the source code. See [Creating polyphonic instruments](https://faustdoc.grame.fr/manual/midi/#midi-polyphony-support).
4
5Polyphonic synthesiser can be created using JUCE Synthesiser model or Faust own polyphonic architecture file (using the `mydsp_poly` class). The `-jsynth` parameter has to be used to choose the JUCE model.
6
7**faust2juce** uses several UI interfaces, subclasses of the base UI class (defined in the architecture/faust/gui/UI.h header) to link to various JUCE components:
8
9 - `JuceGUI.h`: contains the main JuceGUI class (and additional helpers classes) to display Faust UI components (buttons, sliders, bargraphs...) using JUCE widgets
10 - `JuceOSCUI.h`: allows to link Faust UI components (buttons, sliders, bargraphs...) to the JUCE OSC messaging system, allowing to control them in both directions
11 - `JuceParameterUI.h`: allows to link Faust UI components (buttons, sliders, bargraphs...) with the JUCE AudioParameterFloat/AudioParameterFloat classes
12 - `JuceStateUI.h`: allows to save/restore Faust UI components (buttons, sliders, bargraphs...) values using the JUCE state management system (MemoryInputStream/MemoryOutputStream classes)
13
14Some additional files are needed for soundfile and MIDI support:
15
16- `JuceReader.h`: contains code to load audio files using JUCE code, that will be used when the `soundfile` primitive is used in the Faust code
17- `juce-midi.h`: allows to link Faust UI components (buttons, sliders, bargraphs...) to the JUCE MIDI messaging system (for inputs and outputs)
18
19Two different achitecture files will be used to glue the previously described files with the Faust C++ generated class:
20- `juce-plugin.cpp`: is used to create a JUCE plugin
21- `juce-standalone.cpp`: is used to create a JUCE stanalone application
22
23## How to use
24
25**faust2juce** is used with the following command:
26
27`faust2juce [-osc] [-midi] [-soundfile] [-nvoices <num>] [-effect auto|<effect.dsp>] [-standalone] [-jucemodulesdir <dir>] [-vst2sdkdir <dir>] [-disable-splash-screen] [-jsynth] [-llvm] [-magic] [additional Faust options (-vec -vs 8...)] file.dsp`
28
29By default it will create a plugin project, with a folder named with the dsp file name, containing a .jucer project with a FaustPluginProcessor.cpp file to be used by JUCE.
30
31When using `-standalone` mode, it will create a standalone project, with a folder named with the dsp file name, containing a .jucer project with a FaustAudioApplication.cpp file to be used by JUCE.
32
33The resulting folder has to be moved on the "examples" folder of your JUCE installation, the .jucer file has to be opened, and projects for specific native platforms can be generated. Using the `-jucemodulesdir` allows to generate projects that can be used without moving them in JUCE installation.
34
35## Options
36
37Here are the available options:
38
39- `-osc` : activates OSC control
40- `-midi` : activates MIDI control
41- `-soundfile` : when compiling DSP using 'soundfile' primitive, to add needed resources
42- `-nvoices <num>` : to produce a polyphonic self-contained DSP with <num> voices, ready to be used with MIDI or OSC
43- `-effect <effect.dsp>` : to produce a polyphonic DSP connected to a global output effect, ready to be used with MIDI or OSC
44- `-effect auto` : to produce a polyphonic DSP connected to a global output effect defined as 'effect' in <file.dsp>, ready to be used with MIDI or OSC
45- `-standalone` : to produce a standalone project, otherwise a plugin project is generated
46- `-jucemodulesdir <folder>` : to set JUCE modules directory to `<folder>`, such as ~/JUCE/modules
47- `-vst2sdkdir <folder>` : to set VST 2 Legacy Directory to `<folder>`. This is the directory that contains "plugininterfaces/vst2.x/aeffect.h".
48- `-disable-splash-screen` : to disable the JUCE splash screen (license is required).
49- `-jsynth` : to use JUCE polyphonic Synthesizer instead of Faust polyphonic code
50- `-llvm` : to use the LLVM compilation chain (OSX and Linux for now)
51---
52- `-magic` : to generate a project using the [PluginGuiMagic GUI builder](https://foleysfinest.com/developer/pluginguimagic/)
53Tested with PGM version 1.13. Support for Faust components is incomplete. Supporting some features (e.g. visualizers) in PGM requires editing the generated C++ code.
54
55 This creates a preprocessor definition "PLUGIN_MAGIC" in the jucer file e.g. using VisualStudio 2019.
56
57
58
59There are a couple of other options as well:
60
61MAGIC_LOAD_BINARY
62- adds generated code if defined. By default not defined, lets you "bake in" your XML file by adding it to your Jucer project and then defining this variable. You'll also need to configure the foleys_gui_magic module in Jucer:
63
64 
65
66 You also have to change the names of the variables magic_xml and magic_xmlSize in the code to match your file name. If you don't you'll get a compilation error, so you'll know where to look.
67
68MAGIC_LEVEL_SOURCE
69- adds generated code if defined. By default not defined, just to show you where in the source code you would add hooks for a visualizer. These are PGM specific features not represented in Faust. Knowledge of how to use the PGM components is assumed.
70
71To use either of these options, either enter the option into the JUCER exporter settings page as shown, or add a `#define` line near the top of your FaustPluginProcessor.cpp.
72
73---
74- `-help or -h` : shows the different options
75
76As usual with faust2xx tools, other Faust compiler specific options can be given to **faust2juce**, like `-vec -lv 1` to compile in vector mode.etc.
77
78
){kind=link}
){kind=link}