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 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.

Examples¶

Examples of plugins that have already been converted can be found in the examples directory in the piper-vamp-js repository. The vamp-example-plugins example is the most complete.

An illustrative Docker file¶

To accompany this explanation, you can find an example Docker file here 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.

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 - basic schema
• Piper Vamp C++ - supporting C++ code
• Piper Vamp JS - Javascript adapter code
• 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 in which to compile the JS module. 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.

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

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

Build the Piper Vamp JS repository:

$ cd piper-vamp-js ; make

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

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.)

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.

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

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).

Fix the generated code and add a Makefile¶

Open the generated file (referred to above as plugin-library-name.cpp) in an editor and check its contents. The generator guesses the names of likely plugin header files and classes based on the plugin identifiers, and they are probably not actually correct. If your library is accompanied by valid category and RDF files, you should find suitable category and output type URI metadata for each plugin in the generated file -- if these are absent, check that the original plugin location has the appropriate files.

Now the part that needs the most actual work: create a Makefile to build your plugin code with Emscripten.

The piper-vamp-js repository contains most of what you need, in the form of a file Makefile.inc that you can include from your Makefile. But you need to provide all the plugin-specific source files and any additional build flags, and set the variables that Makefile.inc expects. There is a comment at the top of Makefile.inc that explains this further.

An example Makefile is as follows:

PIPER_VAMP_JS_DIR       := ../piper-vamp-js
PLUGIN_DIR              := ../cepstral-pitchtracker

SRC_DIR                 := $(PLUGIN_DIR)

MODULE_NAME             := CepstralPitchTracker
MODULE_SOURCE           := cepstral-pitchtracker.cpp

PLUGIN_SOURCES          := $(SRC_DIR)/AgentFeeder.cpp \
                           $(SRC_DIR)/CepstralPitchTracker.cpp \
                           $(SRC_DIR)/NoteHypothesis.cpp \
                           $(SRC_DIR)/PeakInterpolator.cpp

INCLUDES                := -I$(SRC_DIR)

include $(PIPER_VAMP_JS_DIR)/Makefile.inc

This goes into the same directory as your entry point file.

Now, to build the JS module, run

$ make clean
$ make em

This should produce a pair of JS files named after your MODULE_NAME variable, one with a .js extension and one with .umd.js. Both of these contain the same module code, just wrapped in different ways (plain Emscripten module vs UMD wrapper). Use whichever your application finds more convenient.

To test the resulting build, run

$ make test