search

DBraun / TD-Faust

FAUST (Functional Audio Stream) for TouchDesigner
Other
61 stars 2 forks source link
audio audio-processing dsp faust touchdesigner

readme

TD-Faust

TD-Faust is an integration of FAUST (Functional AUdio STream) and TouchDesigner. The latest builds are for TouchDesigner 2023.11290 and newer. Older TD-Faust builds can be found in the Releases.

Overview

Demo / Tutorial:

Demo Video Screenshot

Examples of projects made with TD-Faust can be found here. Contributions are welcome!

New to FAUST?

Quick Install

Windows

Pre-compiled

Visit TD-Faust's Releases page. Download and unzip the latest Windows version. Copy TD-Faust.dll and the faustlibraries folder to this repository's Plugins folder. Open TD-Faust.toe and compile a few examples.

Compiling locally

If you need to compile TD-Faust.dll yourself, you should first install Python 3.11 to C:/Python311/ and confirm it's in your system PATH. You'll also need Visual Studio 2022 and CMake. Then open a "x64 Native Tools for Visual Studio" command prompt with Administrator privileges to this repo's root directory and run python build_tdfaust.py.

macOS

Pre-compiled

Visit TD-Faust's Releases page. Download and unzip the latest macOS version. Users with "Apple Silicon" computers should download "arm64". Copy TD-Faust.plugin and Reverb.plugin to this repository's Plugins folder.

Open TD-Faust.toe and compile a few examples.

Compiling locally

  1. Clone this repository with git. Then update all submodules in the root of the repository with git submodule update --init --recursive
  2. Install Xcode.
  3. Install CMake and confirm that it's installed by running cmake --version in Terminal. You may need to run export PATH="/Applications/CMake.app/Contents/bin":"$PATH"
  4. Install requirements with brew: brew install autoconf autogen automake flac libogg libtool libvorbis opus mpg123 pkg-config
  5. In the same Terminal window, navigate to the root of this repository and run python3 build_tdfaust.py --pythonver=3.11
  6. Open TD-Faust.toe

Building a Custom Operator

We have previously described a multi-purpose CHOP that dynamically compiles Faust code inside TouchDesigner. Although it's powerful, you have to specify the DSP code, press the compile parameter, and only then do the CHOP's parameters appear. In contrast, ordinary CHOPs can be created from the OP Create Dialog and already have parameters, but they are narrower in purpose. What if you want to use Faust to create a more single-purpose Reverb CHOP with these advantages? In this case, you should use the faust2touchdesigner.py script.

These are the requirements:

If on Windows, you should open an "x64 Native Tools for Visual Studio" command prompt. On macOS, you can use Terminal. Then run a variation of the following script:

python faust2td.py --dsp reverb.dsp --type "Reverb" --label "Reverb" --icon "Rev" --author "David Braun" --email "github.com/DBraun" --drop-prefix

Limitations and Gotchas:

Tutorial

Writing Code

You don't need to import("stdfaust.lib"); in the FAUST dsp code. This line is automatically added for convenience.

Custom Parameters in TouchDesigner

Python API

The Faust CHOP's Python interface is similar to the Audio VST CHOP.

Automatic Custom Parameters and UI

One great feature of TD-Faust is that user interfaces that appear in the Faust code become Custom Parameters on the Faust Base. If a Viewer COMP is set, then it can be automatically filled in with widgets with binding. Look at the simple Faust code below:

import("stdfaust.lib");
freq = hslider("Freq", 440, 0, 20000, 0) : si.smoo;
gain = hslider("Volume[unit:dB]", -12, -80, 20, 0) : si.smoo : ba.db2linear;
process = freq : os.osc : _*gain <: si.bus(2);

If you compile this with a Faust Base, the Base will create a "Control" page of custom parameters. Because of the code we've written, there will be two Float parameters named "Freq" and "Volume". In order to automatically create a UI, pressing compile will save a JSON file inside a directory called dsp_output. These files are meant to be temporary and are deleted each time TD-Faust.toe opens.

Group Voices and Dynamic Voices

The Group Voices and Dynamic Voices toggles matter when using polyphony.

If you enable Group Voices, one set of parameters will control all voices at once. Otherwise, you will need to address a set of parameters for each voice.

If you enable Dynamic Voices, then voices whose notes have been released will be dynamically turned off in order to save computation. Dynamic Voices should be on in most cases such as when you're wiring a MIDI buffer as the third input to the Faust CHOP. There is a special case in which you might want Dynamic Voices off:

Control Rate and Sample Rate

The sample rate is typically a high number such as 44100 Hz, and the control rate of UI parameters might be only 60 Hz. This can lead to artifacts. Suppose we are listening to a 44.1 kHz signal, but we are multiplying it by a 60 Hz "control" signal such as a TouchDesigner parameter meant to control the volume.

import("stdfaust.lib");
volume = hslider("Volume", 1., 0., 1., 0);
process = os.osc(440.)*volume <: si.bus(2);

In TouchDesigner, we can press "Compile" to get a "Volume" custom parameter on the "Control" page of the Faust base. You can look inside the base to see how the custom parameter is wired into the Faust CHOP. By default, this "Volume" signal will only be the project cook rate (60 Hz). Therefore, as you change the volume, you will hear artifacts in the output. To reduce artifacts, there are three solutions:

  1. Use si.smoo or si.smooth to smooth the control signal: volume = hslider("Volume", 1., 0., 1., 0) : si.smoo;

  2. Create a higher sample-rate control signal, possibly as high as the Faust CHOP, and connect it as the second input to the Faust base.

  3. Re-design your code so that high-rate custom parameters are actually input signals.

    import("stdfaust.lib");
// "volume" is now an input signal
process = _ * os.osc(440.) <: si.bus(2);

    You could then connect a high-rate single-channel "volume" CHOP to the first input of the Faust Base.

Using TD-Faust in New Projects

From this repository, copy the toxes/FAUST structure into your new project. You should have:

and any other files which are sibling to FAUST.tox

Now drag FAUST.tox into your new TouchDesigner project, probably near the root. FAUST.tox acts as a Global OP Shortcut. Next, copy toxes/FAUST/main_faust_base.tox into the project and use it in a way similar to how it's used in TD-Faust.toe.

Licenses / Thank You

TD-Faust (GPL-Licensed) relies on these projects/softwares: