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

* "Vamp Test Plugin":/projects/vamp-test-plugin - Plugin used to run tests when building the adapter code

* Your own plugin library's source code

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.