cyfaust 0.1.0__cp311-cp311-macosx_15_0_arm64.whl

cyfaust/resources/architecture/api/README.md

@@ -0,0 +1,237 @@
+# `faust2api` Documentation
+
+**NOTE:** this documentation was taken from the `faust2api` README.
+
+## Overview
+
+Thanks to its architectures system, [Faust](http://faust.grame.fr) can generate a wide range of objects compatible with different platforms (Linux, Windows, OSX, RPI, Android, iOS, ROS, Bela and Web/JavaScript) and tools (Max/MSP, SuperCollider, PD, VST, AU, LV2, etc.). The mechanism behind this was designed to be as modular and reusable as possible. Additionally, the Faust compiler can be embedded in any C++ program using the [LLVM](http://llvm.org/) technology making it very portable.
+
+The goal of the `faust2api` project is to provide a tool to easily generate custom APIs based on one or several Faust objects. On one hand, [Faust DSP libraries](http://faust.grame.fr/libraries.html) implement hundreds of open source DSP algorithms that can be turned into C++, C, JAVA, JavaScript and LLVM bit code and embedded in your applications. On the other hand, Faust C++ libraries can carry out a wide range of tasks going from connecting Faust DSP objects to a specific audio engine (CoreAudio, OpenSL/ES, Alsa, JACK, etc.) or adding MIDI and polyphony support, sensor data handling, etc. to the same object.
+
+Most major Faust targets are supported:
+
+* iOS
+* Android
+* OSX CoreAudio
+* ALSA
+* JACK
+* PortAudio
+* RTAudio
+* openFrameworks
+* JUCE
+* Teensy
+* ESP32
+
+**NOTE:** This documentation only provides high level information on how to use `faust2api`. For detailed tutorials on this topic, visit [this page](https://ccrma.stanford.edu/~rmichon/faustTutorials/#adding-faust-real-time-audio-support-to-android-apps).
+
+## Using `faust2api`
+
+Elements generated by `faust2api` greatly vary from one platform to another. Thus, a custom documentation is generated and integrated to packages generated by `faust2api` in function of the options provided to it (if you only want to generate the package without the documentation, which can save some compilation time, you can use the `-mdoc` option). As a result, this page doesn't provide information on how to use the generated APIs, but rather high level instructions on how to configure `faust2api` to carry out specific tasks.
+
+The various options of `faust2api` can be displayed at any point by running:
+
+	faust2api -help
+
+`faust2api` is part of the [Faust distribution](https://github.com/grame-cncm/faust). To use it, Faust must be properly installed on your system (read the Faust README in the previous link to get more information on how to do that).
+
+
+Common options for all platforms:
+
+- `-opt native|generic`: to activate 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 (this option is ignored if -nvoices is not specified).
+- `-effect auto`: adds an effect (extracted automatically from the dsp file) to the polyphonic synth (this option is 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"
+
+
+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.
+
+
+### Android Support
+
+To turn a Faust code into an Android API, just run the following command:
+
+```
+faust2api -android yourFaustCode.dsp
+```
+
+The JAVA package name of the API generated by `faust2api` is `com.DspFaust`. It can easily be changed by using the `-package` option. For example, to change the package to `com.you.DspFaust`, just run the following command:
+
+```
+faust2api -android -package com.you yourFaustCode.dsp
+```
+
+### iOS Support
+
+To turn a Faust code into an iOS API, just run the following command:
+
+```
+faust2api -ios yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add RtMidi support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### OSX CoreAudio Support
+
+To turn a Faust code into an OSX CoreAudio API, just run the following command:
+
+```
+faust2api -coreaudio yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add RtMidi support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### ALSA Support
+
+To turn a Faust code into an ALSA API, just run the following command:
+
+```
+faust2api -alsa yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add RtMidi support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### JACK Support
+
+To turn a Faust code into a JACK API, just run the following command:
+
+```
+faust2api -jack yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add JACK MIDI support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### PortAudio Support
+
+To turn a Faust code into a PortAudio API, just run the following command:
+
+```
+faust2api -portaudio yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add RtMidi support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### RTAudio Support
+
+To turn a Faust code into an RTAudio API, just run the following command:
+
+```
+faust2api -rtaudio yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add RtMidi support to the API.
+The `-osc` option can be used to add OSC support to the API.
+
+### OpenFrameworks Support
+
+To turn a Faust code into an openFrameworks API, just run the following command:
+
+```
+faust2api -of yourFaustCode.dsp
+```
+
+### JUCE Support
+
+To turn a Faust code into a JUCE API, just run the following command:
+
+```
+faust2api -juce yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add JUCE MIDI support to the API.
+The `-osc` option can be used to add JUCE OSC support to the API.
+
+### Teensy Support
+
+To turn a Faust code into a Teensy API, just run the following command:
+
+```
+faust2api -teensy yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add Teensy MIDI support to the API.
+
+### ESP32 Support
+
+To turn a Faust code into a ESP32 API, just run the following command:
+
+```
+faust2api -esp32 yourFaustCode.dsp
+```
+
+The `-midi` option can be used to add ESP32 MIDI support to the API.
+
+
+### Customizing the API
+
+#### Polyphonic Object
+
+To create a polyphonic object, set the maximum number of voices of this object
+using the `-nvoices` option e.g.:
+
+```
+faust2api -android -nvoices 12 yourSynth.dsp
+```
+
+In this case, we're creating an object with a maximum number of 12 polyphonic voices. Voices are only instantiated and computed when they are used, so this is just a safe guard...
+
+#### MIDI Enabled Polyphonic Object
+
+To create a polyphonic object controllable by a MIDI keyboard, run the previous command but make sure that the `freq`, `gain` and `gate` parameters are declared in your Faust code. E.g:
+
+```
+f = hslider("freq",300,50,2000,0.01);
+bend = hslider("bend[midi:pitchwheel]",1,0,10,0.01) : si.polySmooth(gate,0.999,1);
+gain = hslider("gain",1,0,1,0.01);
+s = hslider("sustain[midi:ctrl 64]",0,0,1,1); // for sustain pedal
+t = button("gate");
+
+cutoff = hslider("cutoff[midi:ctrl 1]",50,50,4000,0.001) : si.polySmooth(gate,0.999,2);
+gate = t+s : min(1);
+freq = f*bend;
+envelope = gate*gain : si.smoo;
+
+process = os.sawtooth(freq)*envelope : fi.lowpass(3,cutoff) <: _,_;
+```
+
+`freq` (which should be a frequency) will be automatically mapped to MIDI note numbers, `gain` (which should be a value between 0 and 1) to velocity and `gate` to *note-on* / *note-off* events. Thus, `gate` can be used as a trigger signal for any envelope generator, etc.
+
+Continuous pitch control is carried out through `bend` which is used to modulate
+the pitch set by `freq`.
+
+Note that we're using the `si.polySmooth` function here to smooth the value of some parameters. This function is very useful when creating polyphonic objects as it only starts smoothing after the note was created, preventing "ugly" sweeps, etc.
+
+0.999 is the pole of the lowpass used for smoothing and 2 is the number of samples to wait before smoothing begins after the voice was created.
+
+#### Adding an Audio Effect to a Polyphonic Object
+
+If creating a polyphonic synthesizer, it is very likely that you will need to plug its output to an audio effect like a reverb. Putting that effect in your main Faust code is not a good idea since it will be instanciated for each voice which would be very inefficient. Fortunately, `faust2api` can take a second Faust file as one of its arguments, containing an audio effect (could be a chain of audio effects, of course). The only rule is that the number of outputs of the synth must the same as the number of inputs of the effect. For example, your effect Faust file could look like this:
+
+	import("stdfaust.lib");
+	process = dm.zita_rev1;
+
+`zita_rev1` is a stereo reverb with a built-in UI that can be connected to the synthesizer presented in the previous section. This code must be saved in a separate Faust file (e.g., `effect.dsp`).
+
+To generate the corresponding API on Android, run:
+
+	faust2api -android -nvoices 12 -effect effect.dsp yourSynth.dsp
+
+Keep in mind that the package generated by `faust2api` contains a README file (see the [generic version](https://github.com/grame-cncm/faust/blob/master-dev/architecture/api/doc/Generic.md)) that you should really read at this point! Also, for more information, check our tutorials on [Using `faust2api` to Add Faust Audio Support to Android Apps](https://ccrma.stanford.edu/~rmichon/faustTutorials/#adding-faust-real-time-audio-support-to-android-apps) and [Using `faust2api` to Add Faust Audio Support to iOS Apps](https://ccrma.stanford.edu/~rmichon/faustTutorials/#adding-faust-real-time-audio-support-to-ios-apps).
+
+## Additional Resources
+
+* [What Is Faust?](https://ccrma.stanford.edu/~rmichon/faustTutorials/#what-is-faust)
+* [Faust Hero in 2 Hours](https://ccrma.stanford.edu/~rmichon/faustTutorials/#faust-hero-in-2-hours)
+* [Using `faust2api` to Add Faust Audio Support to Android Apps](https://ccrma.stanford.edu/~rmichon/faustTutorials/#adding-faust-real-time-audio-support-to-android-apps)
+* [Using `faust2api` to Add Faust Audio Support to iOS Apps](https://ccrma.stanford.edu/~rmichon/faustTutorials/#adding-faust-real-time-audio-support-to-ios-apps)

cyfaust/resources/architecture/api/doc/Generic.md

@@ -0,0 +1,38 @@
+# Faust API
+
+This API allows to interact with a Faust object and its associated audio engine at a high level. The idea is that all the audio part of the app is implemented in Faust allowing developers to focus on the design of the application itself. 
+
+### Application Set-Up
+
+Import `DspFaust.h` and `DspFaust.cpp` in your project (this can be done simply by dragging these files in your project tree). Then, import `DspFaust.h` (`#include "DspFaust.h"`) in the file where you want to create/control the Faust object. 
+
+### Using the C++ API
+
+The current Faust API is designed to seamlessly integrate to the life cycle of an app. It is accessible through a single `DspFaust` object. The constructor of that object is used to set the sampling rate and the buffer size:
+
+	DspFaust* dspFaust = new DspFaust(SR, BS);
+
+The `start()` method is used to start the audio computing. Similarly, `stop()` can be called to stop the audio computing.
+
+It is possible to interact with the different parameters of the Faust object by using the `setParamValue` method. Two versions of this method exist: one where the parameter can be selected by its address and one where it can be selected using its ID. The [Parameters List](#parameters-list) section gives a list of the addresses and corresponding IDs of the current Faust object.
+
+If your Faust object is polyphonic (e.g. if you used the `-nvoices` option when generating this API), then you can use the MIDI polyphony methods like `keyOn`, `keyOff`, etc.
+
+It is possible to change the parameters of polyphonic voices independently using the `setVoiceParamValue` method. This method takes as one of its arguments the address to the voice returned by `keyOn` or `newVoice` when it is called. E.g:
+
+	uintptr_t voiceAddress = dspFaust->keyOn(70, 100);
+	dspFaust->setVoiceParamValue(1, voiceAddress, 214);
+	dspFaust->keyOff(70);
+	
+In the example above, a new note is created and its parameter ID 1 is modified. This note is then terminated. Note that parameters addresses (path) are different for independent voices than when using `setParamValue`. The list of these addresses is provided in a separate sub-section of the [Parameters List](#parameters-list) section.
+
+Finally, note that new voices don't necessarily have to be created using `keyOn`. Indeed, you might choose to just use the `newVoice` method for that:
+
+	uintptr_t voiceAddress = dspFaust->newVoice();
+	dspFaust->setVoiceParamValue(1, voiceAddress, 214);
+	dspFaust->deleteVoice(voiceAddress);
+
+This is particularly useful when making applications where each finger of the user is an independent sound that doesn't necessarily has a pitch.
+
+In case you would like to use the built-in accelerometer or gyroscope of your device to control some of the parameters of your Faust object, all you have to do is to send the raw accelerometer data to it by using the `propagateAcc` or `propagateGyr` for the gyroscope. After that, mappings can be configured directly from the Faust code using [this technique](#using-built-in-sensors-to-control-parameters) or using the `setAccConverter` and `setGyrConverter` method.
+