faust-stratus

A toolkit that simplifies the use of Faust in designing algorithms to be used for Chaos Stratus pedal effects.

IMPORTANT NOTE

Version 0.5+ of this toolkit is significantly different from previous versions!

• If you build Faust itself from the sources as of today, then almost ALL the functionality of this toolkit is already present in Faust.

  The only thing missing is the Python wrapper, that can now be installed from Pypi.

• You no longer need to install anything on your pedal. The toolkit (and its embedded Faust counterparts) work entirely on your local computer.

Consequently you really only need this toolkit if you have an existing Faust installation that is not completely up to date. You CAN use this toolkit on your pedal - however, we no longer deliver the tools for that. If you want that, downlod 0.4.n of this toolkit, install onto your pedal, then install this version onto your pedal.

Resources

Your most important resources:

• Faust - do the YouTube workshops!
• Chaos Stratus Developers Portal

For now, you'll need to be using Linux to have the tools work for you, though there is no reason why, in the future, we can't get the tools running on Windows and Mac. (Note, this has, in fact, been tested on a Mac and appears to work! And Windows has WSL - so, perhaps we are OK!)

The Linux-preference has sense, by the way: If you generate CPP from Faust on Linux then it will reference standard Linux libraries. If you then modify the code, it should be still be direct compilable and usable on the Stratus.

Installation

Download the latest version of the install bundle to your local computer (NOT the Stratus pedal) and un-zip it into a folder of your choosing.

You install this toolkit on your standard computer, NOT on your Stratus

• You must have Faust installed on the same computer
• You do NOT need C++ buildtools installed, unless you want to build versions of your libraries that work locally - primarily for use with the Python testing wrapper.
• Use the install command to install the Stratus-related components.

Usage

The usage is based on a few principles:

• Faust has good patterns for integrating faust2something build scripts and what Faust calls "architecture wrappers" - we exploit that to the full.
• There are simple effects and complex effects - simple effects can generally be fully described in Faust and built for use with the Stratus without any complications. Complex effects may require "tweaking" the CPP code generated by the Faust compiler before they are fully compatible with the Stratus. This toolkit allows for both scenarios, but, obviously, the latter requires more knowledge and intervention from the effect designer.
• Building and testing effects on your "normal" computer is a great way to speed up the development cycle. For that the toolkit allows you to pass arbitrary sound sources through your effect and hear the results without having to load up the effect on the Stratus itself.
• On the other hand, once you are happy, you really do want your effect compiled and installed on the Stratus with the minimum of fuss. The toolkit facilitates that too.

The faust2stratus command

As part of installation, a command named faust2stratus is installed into the Faust binary folder. This is the core of getting your DSPs compiled for the Stratus.

The basic command line invocation is as follows:

faust2stratus <the location of your DSP file>

This will take your DSP file and

• Invoke the Faust command with the correct options for the compiler to generate CPP code suitable for use in the Stratus
• Compile that CPP code for the platform upon which the command is being executed, generating a shared library that implements the Stratus binary interface.
• Save the CPP file and the shared library in the folder from which the originating DSP file was read.

If you run that with no further options, the command will generate a shared library that will run on your local machine (but not on the pedal). Such a library is useful for testing with the Python wrapper without having to install onto the pedal.

But that shared library will not work on the Stratus.

Options

The faust2stratus command has a number of Stratus-specific options that you can add on the command line:

• -nocppc - this will skip the CPP compile step, only generating the Stratus-compatible CPP code.
• -nodocker - If you have docker installed, the following two options will not build the effect shared library on your pedal. Instead they will build it in a docker container. This is MUCH faster than building on the pedal. However, if you would rather not use docker to build the effect, then specify this option.
• -stratusbuild - this will generate the CPP code for your effect, copy it to the Stratus pedal, compile it there and copy the generated shared library back to your local machine (be aware that the SO won't WORK on your local machine).
• -stratusinstall - this will generate the CPP code for your effect, copy it to the Stratus pedal, compile it there and copy the generated shared library back to your local machine (be aware that it won't WORK on your local machine). It will then install the library onto the pedal under the correct name and location for immediate use in the Stratus. If you are currently using the effect in the active effects chain of the Stratus, you will be alerted to this by the Stratus itself going through a short upgrade cycle accompanied by the standard flashing lights.

Apart from these options, you can add other Faust compiler options to the command line. This may be interesting if you are experimenting with different CPP code generation strategies that may better suit your algorithm (e.g. improved vectorization).

Finally, you can affect the CPP compile itself by adding CPP compiler options to the CXXFLAGS environment variable before running the command.

Designing Effects in Faust

Obviously, since this is a toolkit to get Faust-designed effect algorithms working on the Chaos Stratus pedal with as little fuss as possible, your gonna have to design your effect algorithm in Faust.

By FAR the easiest way to do this is using the online IDE, test there with sample audio extracts, then copy the DSP code to your computer (not the Stratus ... yet).

I'm not going to detail that process - Faust itself has some very complete doc, and some very useful online workshops, that will help you - but there are certain principles that will help you build a Faust DSP file that is easily adapted to the Stratus:

• Represent Stratus knobs using vslider and/or hslider.

  This toolkit will recognize hslider and vslider UI components as Stratus knobs. For a nice UI in the Faust IDE you can add as many organizing containers as you want, but they will have no effect on the final representation. Neither will the labels you give your knobs.

  Your parameterization of the sliders should match that which you will declare in the Stratus UI (not part of this toolkit). If you are using the tester "9 KNOB" effect, you are stuck with nine knobs with the following parameterization:

  • Minimum value of 0
  • Maximum value of 10 (I tried for 11 in recognition of Spinal Tap, but Landon said no!)
  • Step value of 0.1

  In this situation, where the UI is a given but the values don't exactly match what you might want, you need to apply the necessary scaling of the values in your algorithm. When you move to a UI that is dedicated to your effect, you can have the knobs defined as you want and can remove the algorithmic scaling.

• Represent Stratus switches using button, checkbox, or nvalue

  While a rarer component of a Stratus UI, switches are also supported by this toolkit. Stratus supports both 2-state (on/off) and 3-state (on/mid/off) switches. Technically this toolkit doesn't distinguish between the two - it's up to the Stratus firmware to use the switches correctly.

  To represent switches in the Faust IDE UI and the Faust DSP file, you can use:

  • button, or
  • checkbox, or
  • nvalue, with a minimum value of 0, a maximum value of 1 or 2, and a step value of 1.

  Again, organize them as you will in the Faust IDE UI, but only these controls will be recognized

• Mark your sliders and switches correctly according to your Stratus UI

  As-is, your sliders, buttons, checkboxes, and/or nvalues will not be "attached" to the equivalent knobs and switches in the Stratus UI.

  To do that you must exploit a feature of Faust UI labels - adding metadata.

  This is how you do it:

  vslider("This is my totally ignored label for my first knob[stratus:0]", ...)
  

  More generally, you add the stratus key with a value between 0 and 9 for knobs, and between 0 and 4 for switches (if you aren't familiar with zero-based indices, welcome to that world!).

  Obviously, those indices indicate to which control on the Stratus effect UI a specific Faust control pertains. Stratus knobs themselves are numbered left-to-right, top-to-bottom. Switches too.

  If you try to assign the same control number to two different Faust controls then the second control will be ignored (here I mean two different controls of the same "class" - knob and switch numbering are independent of each other).

• You get one input signal and must produce only one output signal

  If you don't know what that means, read the Faust doc - but the Stratus is a mono pedal.

  Within the algorithm you can split the signal any number of times you need, but you MUST merge it all back to one signal on output.

  Here's a "blend" pattern that might help explain that:

  ...
  // The blend control is the SECOND knob on the Stratus UI
  blend = vslider("Blend[stratus:1]", 0.5, 0, 1, 0.01);
  weird_effect = ...;
  
  // Splits the single input signal in two, applies the weird effect to one, scales the two signals
  // based upon the blend control such that blend = 0 gives only clean, blend = 1 gives only weird, 
  // and anything in between ... well, blends the two appropriately - and finally merges the internal
  // signals back to one
  process = _ <: (weird_effect : *(blend)),*(1-blend) :> _;
  

• Declare the UUID of your Stratus effect in the DSP code

  That is, if you want it properly installed on the pedal. You do it like this (preferably at the top of your DSP code, but technically it doesn't really matter where):

  declare stratusId "01234567-89ab-cdef-0123-456789abcdef"
  

  For the "9 KNOB" test effect, use 55631e3a-94f7-42f8-8204-f5c6c11c4a21.

• Declare the version of your Stratus effect in the DSP code

  That is, if you want it properly installed on the pedal. You do it like this (preferably at the top of your DSP code, but technically it doesn't really matter where):

  declare stratusVersion "0.1.0"
  

  Note that this used to be called version - however the Faust version uses that name. That said, because our older version ended up after the Faust setting, we still got to use it :) The scripting supports the old naming but you are strongly encouraged to move to the new name ASAP.

So, now you have your Stratus-compatible DSP file - get it onto your computer (the one where you originally unzipped this toolkit) and build away!

Building

As discussed above, building an effect is based around the faust2stratus command.

In the following use cases, if/when the command needs to access your pedal, you must have previously connected it to your computer by USB, and you must enter its root password when requested.

• If you want to test your effect locally execute the following command:

  Note you do not have to connect your pedal to the computer to use the use case

  faust2Stratus [path to your DSP file] <any optional flags for the Faust compiler>
  

  You will end up with a shared object in the source folder of the DSP file (as well as the c++ code that the Faust compiler built).

  That shared object will not work on your pedal, but will be loadable by the Python wrapper. See the usage examples in the Python wrapper documentation for ideas around how to test your effect.

  See below for usage notes.

• If you want to build your effect for the pedal but not install it:

  faust2Stratus [path to your DSP file] -stratusbuild <any optional flags for the Faust compiler>
  

  You will end up with a shared object in the source folder of the DSP file (as well as the c++ code that the Faust compiler built) You can then handle installation onto your pedal yourself.

  If you used the -nodocker you will also find a copy of the shared object on your pedal in the /tmp folder.

  If do use docker for the build, then this workflow will not need to access your pedal.

• If you want to install your effect for the pedal:

  Firstly, you must have set the stratusId metadata item in the DSP code. See above for more details

  Then you use this command:

  faust2Stratus [path to your DSP file] -stratusinstall <any optional flags for the Faust compiler>
  

  You will end up with a shared object in the source folder of the DSP file (as well as the c++ code that the Faust compiler built) and that shared object in the /tmp folder of your pedal. You can then handle installation and backup yourself. Note that the local copy of the shared object will not work on your computer - it is simply there for backup purposes.

Using the Python wrapper

The Python interface is installed locally by the install-local command, and on the Stratus by the install-stratus command.

This is very useful for devising tests for your effect that closely emulate how the Stratus will interact with your effect without actually having to build the UI yet. In particular, you can build the effect locally and test it with Python without even requiring you Stratus pedal to be accessed.

You don't have to do anything special to get the Python interface to work - the effect libraries generated by the toolkit are by default compatible with the Python wrapper

See the delivered test script for examples of how this can be used.