WebPd is a 100% JavaScript Pure Data runtime using Web Audio API to play audio in the browser. It aims at allowing a subset of Pure Data programming language to run in the browser without plugins and with best possible performance.
WebPd should be supported by all browsers supporting Web Audio API.
The following documentation is only about WebPd. To learn more about Pure Data, and start creating Pd patches which you can later use with WebPd, please refer to the official Pure Data documentation.
The following instructions provide a quick start for people with JavaScript knowledge. If you have no experience with JS, you might want to read the step-by-step guide instead.
-
Grab the latest version of WebPd from here.
-
Add WebPd to your Web page, and load a patch by calling Pd.loadPatch.
<!doctype HTML>
<html>
<head>
<script src="js/jquery.js"></script>
<script src="js/webpd-latest.js"></script>
<script>
var patch
$.get('patches/myPatch.pd', function(patchStr) {
patch = Pd.loadPatch(patchStr)
Pd.start()
})
</script>
</head>
<body></body>
</html>If you are testing locally, the ajax request might be blocked by your browser because of same-origin policy. For a workaround, see the troubleshooting section.
The following instructions provide a detailed guide to start working with WebPd. If you have experience with web development, you might want to read the quick start instead.
- First create a folder
myProjectin which you will create your first WebPd project. In this folder, create the following structure :
myProject/
patches/
js/
-
Download the latest version of WebPd, save it as
webpd-latest.jsonto your computer, in the foldermyProject/js. -
Download the latest version of jquery, save it as
jquery.jsonto your computer, in the foldermyProject/js. -
In the folder
myProject, create a file calledindex.htmland copy/paste the following code in it
<!doctype HTML>
<html>
<head>
<script src="js/jquery.js"></script>
<script src="js/webpd-latest.js"></script>
<script>
var patch
$.get('patches/myPatch.pd', function(patchStr) {
patch = Pd.loadPatch(patchStr)
Pd.start()
})
</script>
</head>
<body></body>
</html>
Save that file. Be sure to use a text editor that is programmer-friendly. Microsoft Word and other text processors will add a lot of extra informations, making your code impossible to understand by a web browser. I recommend using something like notepad, gedit, ...
-
Create a patch using Pure Data. Make sure that you use only features and objects supported by WebPd. Save that patch as
myPatch.pdin the foldermyProject/patches. -
Because we are working locally on our computer, we now need to run a web server to be able to open the web page
index.htmlproperly. For this, we will use the web server that comes with Python.
Chances are, you already have Python installed on your computer. To check this, open a terminal (or command prompt), and run python --version, this should print the version of Python installed. If instead you get something like command not found, then you need to install Python.
In the terminal use the command cd to navigate to the folder myProject. When you've arrived there, run the command python -m SimpleHTTPServer if you have Python 2 or python -m http.server if you have Python 3.
- You can finally open your web page and listen to your patch, by opening a web browser and navigating to http://localhost:8000/index.html.
There are a few examples in the examples/ folder. You can also open them online :
For security reasons, browsers control access to your file system from web pages. Because of this, getting Pd files with Ajax might fail on your local machine. A workaround is to start a local server and access all the example web pages through it.
Python comes bundled with such a web server. Open a terminal, navigate to the folder containing the web page you want to open, then run python -m SimpleHTTPServer if you are using Python 2 or python -m http.server if you are using Python 3. Then open your web browser to http://localhost:8000 and things should start working.
Alternatively, if you prefer node, you may want to install the handy http-server command-line utility.
WebPd has a few limitations. For example, some of the Pd objects are not available. Open your browser's developer console (ctrl+shift+i on firefox and chrome for linux or windows), and you should get a clear error message telling you what is wrong. If the error is unclear, or if there is no error, it might be a bug with WebPd. In that case, it would be great if you could submit a bug report.
Here is a non-exhaustive list of other limitations and inconsistencies with Pure Data :
- commas in messages are not implemented yet
- Pd system messages, such as the widely used
[;pd dsp 1(, are not implemented [phasor~]is not a real, perfect, phasor. You shouldn't use it to read from an array for example.[phasor~]inlet 2 (used to set the phase) is not implemented
WebPd uses Web Audio API, and as it happens, running Web Audio API on mobile is not always easy. First, make sure that you use a browser that does support Web Audio API. For example the default Android browser does not, and so on Android you have to use Chrome or Firefox.
On iPhone and iPad, things are even trickier. For security reasons, audio is blocked by iOS, unless you start it in direct answer to a user action (click, touch, ...). So to get sound with WebPd, you will need to do exactly that and for example call Pd.start in a button's ontouchend handler : ontouchend="Pd.start()". You can copy the code to launch WebPd's examples to get around this, and work in all browsers.
Also some objects such as [adc~] depend on features which are not available in all browsers and on all platforms. For example [adc~] won't work on iOS.
Not all of Pure Data's objects are available in WebPd. Please check-out the list of available objects.
Abstractions are implemented, but at the moment they require a bit of extra JavaScript in order to work. You can check-out the abstractions example, to see how this works.
While WebPd uses only Web Audio API and should therefore be quite efficient, you might find that some patches perform poorly on mobile devices, or if there are too many objects running at the same time. This is because Web Audio API is not optimized to work in the same way as Pure Data. For example, modulating parameters with an audio signal (frequencies, delay times, ...), though it is very frequent in Pd, can cause audio glitches in the browser if you use it too much or in a big patch.
If you find a bug, you can submit a bug report on the project's issue tracker.
Please try to include as much information as possible. Also try to include code, and the patch that you cannot get to work.
// We assume this patch has an [outlet~] object.
var patch = Pd.loadPatch(patchStr)
// In order to establish the connection, nodes need to have been created in the
// same audio context. You can for example use WebPd's audio context.
var webPdContext = Pd.getAudio().context
// Some web audio node
var myExternalAudioNode = webPdContext.createGain()
// Connect the output 0 of the patch to our audio node
patch.o(0).getOutNode().connect(myExternalAudioNode)Loads a Pd patch, and returns a Patch object. patchStr is the whole contents of a Pd file (and not only a file name).
Receives messages from named senders within a patch (e.g. [send someName]). Example :
Pd.receive('someName', function(args) {
console.log('received a message from "someName" : ', args)
})Sends messages from JavaScript to a named receiver within a patch (e.g. [receive someName]). Example :
Pd.send('someName', ['hello!'])This is the base class for all WebPd nodes, patches, dsp or glue objects.
Returns the outlet ind of the node. If ind is out of range, an error will be thrown.
Returns the inlet ind of the node. If ind is out of range, an error will be thrown.
To build WebPd yourself, you will need node.js and gulp.js.
When these are installed, run npm install in WebPd root folder.
Finally, run npm run build to build a new version of WebPd in dist/webpd-latest.js.
WebPd comes with two test suites.
The tests in test/lib run on node.js using mocha. To run them, simply execute the command npm test.
The tests in test/browser run in a web browser.
To build them, first scaffold by running node node_modules/waatest/bin/scaffold.js ./waatest. This will create a folder waatest containing a test web page.
Build the tests by running npm run test.browser.build.
Then start a local web server (see troubleshooting), and open waatest/index.html in your web browser.
Any kind of contribution would be very welcome. Check out the issue tracker or contact me directly.