Piper Vamp JSON Adapter

h1. Convert a Vamp Plugin to a JS Module

This page will describe how to take an existing Vamp plugin library, in the form of C++/C source code, and recompile it into a Javascript module that provides the "Piper":/projects/piper interface.

The process is a bit tricky, but it should only have to be done once for each plugin library, as the Javascript build is portable (unlike native builds of the original plugins which have to be re-done for each platform).

The process is also complicated by any third-party library code that the plugin may use. It's not possible to take an existing native library file (whether .a, .lib, .so, .dylib or .dll) and convert that to Javascript -- you have to add the original library source files to your build. This could be tricky to do if the library has any particular configuration requirements.

h4. An illustrative Docker file

To accompany this explanation, you can "find an example Docker file here":https://github.com/piper-audio/piper-vamp-js/blob/master/examples/docker/Dockerfile which actually carries out the process of converting and building a plugin library within a Docker container. This is not an especially convenient way to do it, but it should make explicit all of the necessary steps in a more-or-less reproducible way.

h4. Prerequisites

You will need the following:

* A typical Unix-like system - this has been tested using Arch Linux and macOS

* A sufficiently recent version of the Emscripten C++-to-Javascript compiler

* Typical native C/C++ build tools

* Node.js environment, to run the tests

You will need to have the following repositories checked out. The build process expects that all of these will be checked out into a common parent directory.

* "Piper":/projects/piper - basic schema

* "Piper Vamp C++":/projects/piper-cpp - supporting C++ code

* "Piper Vamp JS":/projects/piper-vamp-js - Javascript adapter code

* "Vamp Plugin SDK":/projects/vamp-plugin-sdk - Vamp SDK used by both of the last two

* The source code for your own plugin library which you intend to convert

Also create a new directory for the JS module to be compiled in. You will need to provide a Makefile and a main file (in C++, to be cross-compiled to JS along with everything else) for this module so it makes sense to have a dedicated directory (and likely a version control repository) to put them in.

h4. Build the dependencies and tools

Not all of the dependent repositories need to be compiled: the ones that do are the Vamp Plugin SDK and Piper Vamp JS.

Build and install the Vamp plugin SDK. On Linux this is

<pre>

$ cd vamp-plugin-sdk ; ./configure && make && sudo make install

</pre>

Build the Piper Vamp JS repository:

<pre>

$ cd piper-vamp-js ; make

</pre>

This should produce a generator program in @bin/piper-vamp-stub-generator@ which we will use in a moment.

h4. Prepare your own plugin library

Compile your own Vamp plugin library in the normal way, i.e. as a native Vamp plugin for your current platform. This is necessary so that the conversion stub generator program can query the plugin.

Add its location to the @VAMP_PATH@ environment variable. You should also check that the @.cat@ category file and the @.n3@ or @.ttl@ RDF description file for the plugin are available in the same location as the plugin library itself. (If the plugin doesn't have those files, consider making them? They're helpful for other Vamp plugin hosts as well.)

h4. Prepare the JS module code folder

In your new working directory for the converted code, generate an initial version of the module main entry point using the generator program in @piper-vamp-js@. This will only work if your plugin library is in the @VAMP_PATH@.

<pre>

$ ../piper-vamp-js/bin/piper-vamp-stub-generator plugin-library-name > plugin-library-name.cpp

</pre>

replacing @plugin-library-name@ with the name of your plugin library. Be sure to run this in the right directory - the (initially empty) one for your new JS module, not the original plugin directory (as that could overwrite the original plugin code).