improved plugin develpment experience for TBD V2

[mjleehh]

---

Plugin Implementation Mechanism

---

This document will sketch out some ideas on how future users could implement plugins

Problem Statement

Currently interested users who would like to develop plugins are faced with three major
hurdles:

1. setting up and building to project
2. the system lacks documentation to understand how it works
3. implementing a plugin requires a significant amount of C programming skills, as well as
   several additional steps like creating the JSON description files etc

This document will address problem 3 because it creates a gap between which domain knowledge
(math, algorithms and sound design) is actually required to create a plugin and all the
technical knowledge required that has nothing to do with the actual problem at hand.

Which Simplifications Already Exist

The current approach already includes some good ideas to simplify this, by auto generating

• CV and trigger fields
• type reflection to manipulate CV and trigger values

This keeps the following implementation details away from users

• wrapping types in atomics and adding the
• implementing ability to manipulate CVs/triggers plugins dynamically by using field names
• registering plugins in the plugin factory so they can be created dynamically by name

Creating a Plugin With the Current Process

Creating a plugin using the current methodology involves three steps:

1. define the plugin in a mui-SomePluginClass.jsn
2. generate ctagSomePluginClass.hpp and ctagSomePluginClass.cpp files
3. implement ctagSomePluginClass::Process(..) method

The first step is creating a file similar to the following

    {
        "id": "CStripM",
        "name": "CStripM",
        "isStereo": false,
        "hint": "Mono version of port of airwindows' CStrip",
        "params": [
            {
            "id": "treble",
            "name": "Treble",
            "type": "int",
            "min": 0,
            "max": 4095,
            "step": 1,
            "params": null
            },
            {
            "id": "mid",
            "name": "Mid",
            "type": "int",
            "min": 0,
            "max": 4095,
            "step": 1,
            "params": null
            },
            // ...
        ]
    }

This automatically creates a header like this

    #include <atomic>
    #include <tbd/sound_processor.hpp>
    #include "airwindows/CStripM.hpp"

    namespace CTAG {
        namespace SP {
            class ctagSoundProcessorCStripM : public ctagSoundProcessor {
            public:
                virtual void Process(const ProcessData &) override;
            virtual void Init(std::size_t blockSize, void *blockPtr) override;
                virtual ~ctagSoundProcessorCStripM();

            private:
                virtual void knowYourself() override;

                airwindows::CStripM CStripM;

                // private attributes could go here
                // autogenerated code here
                // sectionHpp
                std::atomic<int32_t> treble, cv_treble;
                std::atomic<int32_t> mid, cv_mid;
                // ...
            };
        }
    }

And finally after implementing the actual ctagSoundProcessorCStripM::Process(...)
method we end up with something like this:

    #include <tbd/sounds/ctagSoundProcessorCStripM.hpp>
    #include <cmath>
    #include "helpers/ctagFastMath.hpp"

    using namespace CTAG::SP;

    void ctagSoundProcessorCStripM::Process(const ProcessData &data) {

        float fTreble = treble / 4095.f;
        if (cv_treble != -1) {
            fTreble = data.cv[cv_treble]; // range 0 ..1 or -1 .. 1
        }
        CStripM.SetTreble(fTreble);

        float fMid = mid / 4095.f;
        if (cv_mid != -1) {
            fMid = data.cv[cv_mid]; // range 0 ..1 or -1 .. 1
        }
        CStripM.SetMid(fMid);
        // ... more boilerplate

    }

    // ... helper methods and generated reflection code

Things to be Improved

One major problem with this approach is, that the implementation always needs to be updated
from the json files and JSON files and the actual implementation can even contradict each
other in terms of the plugins CVs/triggers. This is a real problem since the JSON file
is used to inform the APIs about the available plugin parameters.

There is also a significant amount of boiler plate code that could be deduced from the JSON
file like value range limiting. This has to be done manually in the processing function
the MK_BOOL_PAR, MK_INT_PAR_ and MK_FLT_PAR_ range of macros. Take the
implementation of the Bjorklund plugin for example, which contains screens and screens
of boilerplate like this:

    MK_TRIG_PAR(t_EGringActive, EGringActive);
    MK_TRIG_PAR(t_EGringNegative, EGringNegative);
    MK_FLT_PAR_ABS(f_RingAttack, RingAttack, 4095.f, 8.f);
    MK_FLT_PAR_ABS(f_RingDecay, RingDecay, 4095.f, 10.f);
    MK_FLT_PAR_ABS(f_RingAmount, RingAmount, 4095.f, 1.f);
    MK_TRIG_PAR(t_EGringLoop, EGringLoop);

Another challenge is that there is still a significant amount of pure C++ complexity users
should not have to concern themselves with. This can be rather intimidating and creates a
lot of noise that users have to ignore and scroll past, in order to get to what they
would actually like to do.

Suggested Improvements

All suggested improvements shouldn't be forced upon users, but rather allow an alternate
easier way to do things. As a first step We propose the following workflow:

• have a single folder say plugins/ that contain simple header files, like
  MyPlugin.hpp putting the entire plugin implementation in a single file
• allow users to declare a simple class only requiring a process(...) method
• use plain bool, float and int fields to declare CVs/triggers by using C++
  attributes
• use attributes to add meta information like descriptions, readable field names, field
  ranges etc
• do the CV/trigger mapping automatically so the user code does not have to handle it
• provide CVs preprocessed, scaled, clamped etc

This could result in a single header file containing the entire plugin, that will still
work with IDE code intelligence and could look something like this

    #include <tbd/plugin.hpp>

    /**
     *  a plugin class 
     *  
     *  add name and description and put documentation in this help string
     *  to be extracted and added to the docs webpage
     */
    [[ tbd_plugin(
        name="Bjorklund",
        is_stereo,
        description="Combining Patterns based on Bjorklund's implementation of Euclidian rhythms and mathematical palindromes"
    )]]
    struct Bjorklund {

        /**
         *  group attributes
         *
         *  this also groups these values in the web UI and docs and integrate this help 
         *  text into the docs 
         */
        [[ tbd_group(name="Global", description="Global (Quantizer relative to Master Tune!)") ]]
        struct Global {
        
            /**
            *  declare a property
            *
            *  this property documentation will be shown in the docs too  
            */
            [[ tbd_trigger(name="Trgger") ]]
            bool trigger;

            [[ tbd_cv(name="Beat Divider", min=0, max=32) ]]
            uint beat_divider;

        } global;

        // more groups and properties ...

        /**
        *  plugin code: plain dsp and math here
        */
        void process(SampleChunk chunk) {
            // all is ready to go
            if global.trigger:
                // maybe have some nice operations on sample data?
                chunk(0, 1ms) /= 2;
        }
    }