Difference between revisions of "Max gen~"

From MOD Wiki
Jump to navigation Jump to search
Line 1: Line 1:
−
This page describes how to get Max gen~ objects working as LV2 plugins, with the purpose of running them on the MOD.<br>
+
== Introduction ==
−
Note that the same procedure also allows for building cross-platform VST2 plugins (Linux, Mac and Windows), but without a custom graphical interface.<br>
 
−
In this page we'll focus on LV2 and MOD.
 
  
−
'''NOTE: This is a work in progress! (specially this page!)'''
+
Apart from programming LV2-plugins in a "traditional" way, it's also possible to generate LV2-plugins for the MOD Duo from gen~ objects created in Cycling '74 Max. This quick start guide will tell you the how and why of programming audio effects for the MOD Duo using this very different approach.
−
<br>
 
−
Expect some information to be missing.
 
  
−
== How it works ==
+
== Gen Basics ==
  
−
This works by mixing pre-existing plugin wrapper code with the gen~'s code export feature.<br>
+
Gen~ objects are normally used in Max as a way to write low-level code that is run at signal-rate, using (if you want to) the same visual approach Max is known for. Therefore the insides of a gen~ object can be seen as a pedal schematic, perfect for designing audio effects.
−
By exporting the code we can compile them together to create an LV2 plugin binary, then generate the meta-data from it.
 
  
−
The idea was based on the official [https://github.com/Cycling74/gen-plugin-export gen-plugin-export] project made by Cycling '74.<br>
+
If you're not familiair with Gen, and this sounds all like gibberish to you, have a look at the links below.
−
We're not using that project for MOD because it uses Juce, which requires quite a few things that unnecessary (not to mention a graphical server).
 
  
−
Based on that project was made [https://github.com/DISTRHO/DPF-Max-Gen DPF-Max-Gen],
+
* [https://docs.cycling74.com/max7/vignettes/gen_overview : Gen Overview]
−
which uses the much simpler (and limited) [https://github.com/DISTRHO/DPF DPF] instead of Juce.<br>
+
* [http://blog.moddevices.com/2017/01/06/create-a-gen-based-plugin-for-the-mod-duo : Create a Gen-based plugin for the MOD Duo]
−
That way we no longer require X11, freetype and quite a few other things that Juce needs in Linux. The final binary code is also a lot smaller.<br>
 
−
Since the plugin DSP code is all done in Max, the wrapper for exposing it as plugin does not really matter per se.<br>
 
−
So we use the most lightweight and simple approach possible - in this case being [https://github.com/DISTRHO/DPF DPF].
 
  
−
== DPF-Max-Gen ==
+
== Designing your effect in Gen ==
  
−
If you open the [https://github.com/DISTRHO/DPF-Max-Gen DPF-Max-Gen project page], you'll see a few things inside.<br>
+
-To get your gen~ object working on the MOD Duo, you'll first need to design one using only Gen's internal objects, without referring to objects outside the gen~ object. Only the objects insides will make it to the final LV2-plugin.
−
The most important part is the 'plugins' folder. Inside it there's more folders, each containing a separate plugin
+
-If you want controllable parameters, define the minimum, maximum and default arguments in the "param" object.
−
(with the exception of 'common', which provides the common/base code for gen~).
+
-While designing your gen~ object, remember that the MOD Duo's samplerate is running at 48 KhZ.
  
−
Taking the example of bitcrush, we have:
+
When you're finished, send the "exportcode" message to the gen~ object in your main Max-patch to get the gen_exported.cpp and gen_exported.h files.
−
* DistrhoPluginInfo.h
 
−
* DistrhoPluginMaxGen.cpp
 
−
* Makefile
 
−
* gen_exported.cpp
 
−
* gen_exported.h
 
−
* gen~.bitcrush.maxpat
 
  
−
'''DistrhoPluginInfo.h''' is a C header file, required by DPF, that describes some plugin meta-data.<br>
+
== Getting your Gen-based plugin to the MOD Duo ==
−
This includes name, author, description, LV2 URI and the amount of audio channels.<br>
 
−
Modify this file as needed. Remember that LV2 URIs are global and unique, and don't have to be real online URLs.
 
  
−
'''DistrhoPluginMaxGen.cpp''' is a symlink to the real DistrhoPluginMaxGen.cpp file located in the common folder.<br>
+
At this point you should have the exported code from your gen~ object, and have met the requirements specified above.
−
This symlink is here so that we compile a different instance per plugin, but the actual code is the same.<br>
+
If so, follow the steps below to get your plugin on the MOD Duo.
−
Do not modify this file.
 
  
−
'''Makefile''' contains the build rules for compiling the plugin.<br>
+
=== Compiling the plugin ===
−
The only thing that needs change here is the 'NAME' parameter, which specifies the target LV2 bundle and binary name for the plugin.
 
  
−
'''gen_exported.cpp/h''' is the output from Max gen~ code export utility.<br>
+
In order to run Gen-based plugins on the MOD Duo they must be compiled using a custom MOD cloud build system. If you're running Linux or macOS just clone [https://github.com/moddevices/max-gen-skeleton Max Gen Skeleton] and follow the [https://github.com/moddevices/max-gen-skeleton/README.md instructions].
−
You should get a few more files when exporting code, but only these 2 matter.
 
  
−
'''gen~.bitcrush.maxpat''' is the Max patch that was used to generate this plugin, being here only for reference.
+
<source lang="console">
 +
$ git clone https://github.com/moddevices/max-gen-skeleton
 +
$ cd max-gen-skeleton
 +
</source>
 +
 
 +
Now copy the gen_exported.cpp and gen_exported.h files into the main max-gen-skeleton folder.
 +
 
 +
<source lang="console">
 +
$ mod-build.sh
 +
</source>
 +
 
 +
You'll be asked for a plugin name, and after providing one the cloud should give you back a tar.gz file within a few minutes.
  
−
== Compiling ==
+
=== Edit the .ttl file ===
  
−
=== Native ===
+
Optionally you can now edit the .ttl file to for example add [http://lv2plug.in/ns/extensions/units/units.html units], [http://lv2plug.in/ns/ext/port-props/port-props.html knob behaviour] or a description. If you do, make sure everything is correct, otherwise the plugin won't work and you might have to SSH into the MOD Duo to get the corrupt plugin out. To prevent this from happening, you can [http://lv2plug.in/pages/validating-lv2-data.html validate the lv2-data].
  
−
Before trying to build the plugins for MOD, it's a good idea to see if they work locally on your own PC first.<br>
 
−
After you git-clone the [https://github.com/DISTRHO/DPF-Max-Gen DPF-Max-Gen project] (recursively, it has submodules), you can just do:<br>
 
 
<source lang="console">
 
<source lang="console">
−
$ cd DPF-Max-Gen
+
OPTIONAL
−
$ make
+
$ gunzip Plugin.lv2-duo.tar.gz
 +
$ tar -xvf Plugin.lv2-duo.tar
 +
make edits in Plugin.lv2/Plugin_dsp.ttl or include a GUI
 +
$ rm Plugin.lv2-duo.tar.gz
 +
$ tar -cvzf Plugin.lv2-duo.tar.gz Plugin.lv2/
 
</source>
 
</source>
  
−
If you're running Mac OS use 'make MACOS=true'.
+
=== Include a GUI ===
  
−
After it finishes you'll have LV2 and VST2 plugins inside the bin folder.<br>
+
Another option is to include a GUI, you can make one with the [https://github.com/moddevices/mod-sdk MOD SDK].
−
See if they work on your favourite host. :)
+
Have a look [http://github.com/moddevices/mod-v2-data/tree/master/plugins-fixed here] how a GUI affects the .ttl structure.
 +
And don't forget to compress everything again.
  
−
=== MOD ===
+
=== Deploying the plugin ===
  
−
Compiling plugins for MOD can be done using [https://github.com/moddevices/mod-plugin-builder mod-plugin-builder].<br>
+
Make sure the MOD Duo is connected to your computer via USB before proceeding.
−
See [[How_To_Build_and_Deploy_LV2_Plugin_to_MOD_Duo]] for more details.
 
  
−
== Making your own plugins ==
+
<source lang="console">
 +
$ mod-deploy.sh
 +
</source>
  
−
Right now we do not have the process of turning the gen~ exported code into a plugin directly. You'll have to do some manual work.<br>
+
<source lang="console">
−
 
+
$ mod-deploy.sh
−
A good starting point might be to just fork the DPF-Max-Gen project and use it to start your own.<br>
+
</source>
−
The 'Makefile' file in the root folder contains the list of plugins to build, which reside in the plugins folder.
 
  
−
If you've handled makefiles before it should be pretty straight forward.<br>
+
If all goes well, your Gen-based plugin should now be inside the MOD Duo, ready to be played!
−
If not please contact us for ideas and discussion on how to possibly automate the creation of this type of plugin.
 

Revision as of 13:02, 20 June 2017

Introduction

Apart from programming LV2-plugins in a "traditional" way, it's also possible to generate LV2-plugins for the MOD Duo from gen~ objects created in Cycling '74 Max. This quick start guide will tell you the how and why of programming audio effects for the MOD Duo using this very different approach.

Gen Basics

Gen~ objects are normally used in Max as a way to write low-level code that is run at signal-rate, using (if you want to) the same visual approach Max is known for. Therefore the insides of a gen~ object can be seen as a pedal schematic, perfect for designing audio effects.

If you're not familiair with Gen, and this sounds all like gibberish to you, have a look at the links below.

Designing your effect in Gen

-To get your gen~ object working on the MOD Duo, you'll first need to design one using only Gen's internal objects, without referring to objects outside the gen~ object. Only the objects insides will make it to the final LV2-plugin. -If you want controllable parameters, define the minimum, maximum and default arguments in the "param" object. -While designing your gen~ object, remember that the MOD Duo's samplerate is running at 48 KhZ.

When you're finished, send the "exportcode" message to the gen~ object in your main Max-patch to get the gen_exported.cpp and gen_exported.h files.

Getting your Gen-based plugin to the MOD Duo

At this point you should have the exported code from your gen~ object, and have met the requirements specified above. If so, follow the steps below to get your plugin on the MOD Duo.

Compiling the plugin

In order to run Gen-based plugins on the MOD Duo they must be compiled using a custom MOD cloud build system. If you're running Linux or macOS just clone Max Gen Skeleton and follow the instructions. 

$ git clone https://github.com/moddevices/max-gen-skeleton
$ cd max-gen-skeleton

Now copy the gen_exported.cpp and gen_exported.h files into the main max-gen-skeleton folder. 

$ mod-build.sh

You'll be asked for a plugin name, and after providing one the cloud should give you back a tar.gz file within a few minutes.

Edit the .ttl file

Optionally you can now edit the .ttl file to for example add units, knob behaviour or a description. If you do, make sure everything is correct, otherwise the plugin won't work and you might have to SSH into the MOD Duo to get the corrupt plugin out. To prevent this from happening, you can validate the lv2-data. 

OPTIONAL
$ gunzip Plugin.lv2-duo.tar.gz
$ tar -xvf Plugin.lv2-duo.tar
make edits in Plugin.lv2/Plugin_dsp.ttl or include a GUI
$ rm Plugin.lv2-duo.tar.gz
$ tar -cvzf Plugin.lv2-duo.tar.gz Plugin.lv2/

Include a GUI

Another option is to include a GUI, you can make one with the MOD SDK. Have a look here how a GUI affects the .ttl structure. And don't forget to compress everything again.

Deploying the plugin

Make sure the MOD Duo is connected to your computer via USB before proceeding. 

$ mod-deploy.sh
$ mod-deploy.sh

If all goes well, your Gen-based plugin should now be inside the MOD Duo, ready to be played!

Retrieved from "http://wiki.mod.audio/index.php?title=Max_gen~&oldid=11184"