empd

what

Pure-data compiled with Emscripten.

why

Run Pd patches (without GUI) in a web browser.

but

There is also WebPd with a limited subset of Pd functionality. empd is full Pd vanilla -nogui.

how

Emscripten compiles C to HTML, Javascript and Web Assembly. A small stub program written in C interfaces between libpd and SDL2 Audio API (which is implemented by Emscripten). The patch files are preloaded into Emscripten's virtual filesystem at compile time.

Pd uses C function pointers internally. Emscripten is stricter about calling function pointers with the exact type of the function (in C, extra arguments and return values are ignored). This means Pd has to be modified to do extra type checking: this bloats some code from 6 cases to 60 cases. to consider. Also pd_objectmaker has to be handled even more specially in various places. Bugs may remain in some code paths, because these type errors are only exposed at runtime.

Pd uses dynamic linking to load external plugins. This is not supported in Emscripten, so all needed externals have to be statically linked at compile time.

get

First install and activate the emscripten environment. As of 2019-01-10, if you want to try Gem you need the 'incoming' emsdk, the regal port is very fresh.

build core

git clone --recursive https://github.com/claudeha/libpd.git
cd libpd
git checkout emscripten
cd pure-data
git remote add claudeha https://github.com/claudeha/pure-data.git
git fetch claudeha
git checkout claudeha/emscripten
cd ..
mkdir build
cd build
emconfigure cmake .. -DPD_UTILS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release
emmake make

build examples

cd ../samples/emscripten/pdtest
make

To load in a browser you need a web server (local filesystem might not work). For example:

python -m SimpleHTTPServer 8080 &
firefox http://localhost:8080/pdtest.html

build gem (advanced users only!)

Gem support is not for the faint hearted at this stage. Worst case you'll end up with a blank gemwin with no error messages, best case LOTS of errors.

glu
git clone https://gitlab.freedesktop.org/mesa/glu.git
Gem
git clone https://github.com/claudeha/Gem.git
cd Gem
git checkout emscripten

Inspect the scripts below for detailed build instructions (in flux).

build gem examples (advanced users only!)

Inspect the scripts below for detailed build instructions (in flux).

building in a cleanroom environment

Using a chroot for the sole purpose helps isolate from the rest of your system, which helps with reproducibility and license auditing. Here are three scripts:

empd-build-chroot.sh
Execute this as root, after installing 'debootstrap' on your linux.
empd-chroot-prepare.sh
Execute this as root, within the chroot (you should be there after the first script).
empd-build-script.sh
Execute this as user, within the chroot (you should be there after the second script). But first edit 'JOBS=8' at the start of the file if your core count/RAM is small or large.

You need about 6GB disk space total.

examples

performance

One less trivial patch I tested uses 6% of one core at 2.2GHz in native Pd, but 12% of one core at 2.2GHz in Firefox 64. So performance is around 2x worse than native. This is with a Release build, with a Debug build of empd add another 10x slowdown on top.

bugs

Please report any issues specific to empd (if you have issues reproducible in upstream pure-data or libpd or Gem, please report to those projects first).

My changes are Copyright (C) 2019 Claude Heiland-Allen. The changes to pure-data are under the pure-data licence. The changes to libpd are under the libpd license. The changes to Gem are under the Gem license.

Be aware of your legal obligations when publishing patches on the web using empd, as far as I can tell this counts as binary distribution (I am no lawyer, you may wish to consult one).

pure-data license

This software is copyrighted by Miller Puckette and others.  The following
terms (the "Standard Improved BSD License") apply to all files associated with
the software unless explicitly disclaimed in individual files:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above  
   copyright notice, this list of conditions and the following 
   disclaimer in the documentation and/or other materials provided
   with the distribution.
3. The name of the author may not be used to endorse or promote
   products derived from this software without specific prior 
   written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,   
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

libpd license

This software is copyrighted by Miller Puckette and others.  The following
terms (the "Standard Improved BSD License") apply to all files associated with
the software unless explicitly disclaimed in individual files:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above  
   copyright notice, this list of conditions and the following 
   disclaimer in the documentation and/or other materials provided
   with the distribution.
3. The name of the author may not be used to endorse or promote
   products derived from this software without specific prior 
   written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,   
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

gem license

GEM - Graphics Environment for Multimedia
Copyright © 1997-2000 Mark Danks
Copyright © Günter Geiger
Copyright © 2001-2011 IOhannes m zmölnig, 
Copyright © 2003-2007 James Tittle II, 
Copyright © 2003-2008 Chris Clepper

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program.  If not, see <http://www.gnu.org/licenses/>.

In the official GEM distribution, the GNU General Public License is
in the file GnuGPL.LICENSE

..