From 53a935cffb9d70fc3c2abb693c3d60db608d91b7 Mon Sep 17 00:00:00 2001 From: David Braun <2096055+DBraun@users.noreply.github.com> Date: Thu, 4 Apr 2024 19:51:44 -0400 Subject: [PATCH] Update README.md --- README.md | 72 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 43 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index c4e52f8..c58c6b3 100644 --- a/README.md +++ b/README.md @@ -23,31 +23,6 @@ Demo / Tutorial: Examples of projects made with TD-Faust can be found [here](https://github.com/DBraun/TD-Faust/wiki/Made-With-TD-Faust). Contributions are welcome! -## Building a Custom Operator - -The previous overview was about using a multi-purpose CHOP to dynamically compile Faust code inside TouchDesigner. Although it's powerful, you have to specify the DSP code, press the `compile` parameter, and then begin modifying the CHOP's parameters. Ordinary CHOPs can be created from the Op Create Dialog and don't require nearly as much setup, but they are narrower in purpose. What if you want to use Faust to create a more single-purpose CHOP such as a dedicated Reverb CHOP? In this case, you should use the `faust2touchdesigner.py` script. - -These are the requirements: - -* Download libfaust by going to `thirdparty/libfaust` and running `python download_libfaust.py` (`python3 download_libfaust.py` on macOS). -* Pick a Faust DSP file such as `reverb.dsp` that defines a `process = ...;`. -* Python should be installed. -* CMake should be installed. - -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: - -```bash -python faust2td.py --dsp reverb.dsp --type "Reverb" --label "Reverb" --icon "Rev" --author "David Braun" --email "github.com/DBraun" --drop-prefix -``` - -Limitations and Gotchas: -* The example script above overwrites `Faust_Reverb_CHOP.h`, `Faust_Reverb_CHOP.cpp`, and `Reverb.h`, so avoid changing those files later. -* Polyphonic instruments have not been implemented. -* MIDI has not been implemented. -* The `soundfile` primitive has not been implemented (`waveform` is ok!) -* CHOP Parameters are not "smoothed" automatically, so you may want to put `si.smoo` after each `hslider`/`vslider`. -* File a GitHub issue with any other problems or requests. Pull requests are welcome too! - ## New to FAUST? * Browse the suggested [Documentation and Resources](https://github.com/grame-cncm/faust#documentation-and-resources). @@ -60,17 +35,27 @@ Limitations and Gotchas: ### Windows +#### Pre-compiled + Visit TD-Faust's [Releases](https://github.com/DBraun/TD-Faust/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. -If you need to compile `TD-Faust.dll` yourself, you should first install [Python 3.11](https://www.python.org/downloads/release/python-3117/) 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 `thirdparty/libsndfile` and run `python download_libfaust.py`. Then `cd` to this repo's root directory and run `python build_tdfaust.py`. +#### Compiling locally + +If you need to compile `TD-Faust.dll` yourself, you should first install [Python 3.11](https://www.python.org/downloads/release/python-3117/) 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 `thirdparty/libfaust` and run `python download_libfaust.py`. Then `cd` to this repo's root directory and run `python build_tdfaust.py`. ### macOS - +Visit TD-Faust's [Releases](https://github.com/DBraun/TD-Faust/releases) page. Download and unzip the latest macOS version. Users with "Apple Silicon" computers should download "arm64". Copy `Reverb.plugin`, `TD-Faust.plugin`, and the `faustlibraries` folder to this repository's `Plugins` folder. Then run the following in Terminal. +```bash +xattr -d com.apple.quarantine Plugins/Reverb.plugin +xattr -d com.apple.quarantine Plugins/TD-Faust.plugin +``` + +Open `TD-Faust.toe` and compile a few examples. -TD-Faust is designed for macOS version 11.0 and later. Also, macOS users need to compile TD-Faust on their own computers because [@DBraun](https://github.com/DBraun/) doesn't have an App Distribution license. +#### 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. @@ -81,6 +66,35 @@ TD-Faust is designed for macOS version 11.0 and later. Also, macOS users need to 7. In the same Terminal window, navigate to the root of this repository and run `python3 build_tdfaust.py --pythonver=3.11` 8. 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](https://docs.derivative.ca/CHOP) can be created from the [OP Create Dialog](https://docs.derivative.ca/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: + +* Download libfaust by going to `thirdparty/libfaust` and running `python download_libfaust.py` (`python3 download_libfaust.py` on macOS). +* Pick a Faust DSP file such as `reverb.dsp` that defines a `process = ...;`. +* Python should be installed. +* CMake should be installed. +* If Faust is not installed (see [here](https://github.com/grame-cncm/faust/releases)), then you must put the libfaust's `faust` executable in your path. +* * On macOS arm64: `export PATH=$PWD/thirdparty/libfaust/darwin-arm64/bin:$PATH` +* * On macOS x86_64: `export PATH=$PWD/thirdparty/libfaust/darwin-x64/bin:$PATH` +* * On Windows: `set PATH=%CD%/thirdparty/libfaust/win64/bin;%PATH%` + +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: + +```bash +python faust2td.py --dsp reverb.dsp --type "Reverb" --label "Reverb" --icon "Rev" --author "David Braun" --email "github.com/DBraun" --drop-prefix +``` + +Limitations and Gotchas: +* The example script above overwrites `Faust_Reverb_CHOP.h`, `Faust_Reverb_CHOP.cpp`, and `Reverb.h`, so avoid changing those files later. +* [Polyphonic](https://faustdoc.grame.fr/manual/midi/#standard-polyphony-parameters) instruments have not been implemented. +* MIDI has not been implemented. +* The [`soundfile`](https://faustdoc.grame.fr/manual/syntax/#soundfile-primitive) primitive has not been implemented ([`waveform`](https://faustdoc.grame.fr/manual/syntax/#waveform-primitive) is ok!) +* CHOP Parameters are not "smoothed" automatically, so you may want to put `si.smoo` after each [`hslider`](https://faustdoc.grame.fr/manual/syntax/#hslider-primitive)/[`vslider`](https://faustdoc.grame.fr/manual/syntax/#vslider-primitive). +* File a GitHub issue with any other problems or requests. Pull requests are welcome too! + ## Tutorial ### Writing Code