Csound for Portable Native Client

Victor Lazzarini

November 26, 2013

1 Introduction

Native Client (NaCl) is a sandboxing technology developed by Google that allows C/C++ modules to extend the support provided by HTML5. Portable Native Client (pNaCl) is one of the toolchains in the NaCl SDK (the others are newlib and glibc). The advantage of pNaCl over the other options is that it only requires a single module to be built for all supported architectures.

The other major advantage is that pNaCl is, as of Google Chrome 31, enabled by default in the browser. This means that users just need to load a page containing the pNaCl application and it will work. pNaCl modules are compiled to llvm bytecode that is translated to a native binary by the browser. To check whether your version of Chrome supports pNaCl, use the following address:

chrome://nacl

Porting Csound to pNaCl involved three steps, following the SDK installation:

  1. Building libsndfile as a pNaCl library
  2. Build Csound as a pNaCl library
  3. Developing the pNaCl module to provide an interface to the Csound library

2 Building Csound for pNaCl

2.1 Building the libraries

With the NaCl SDK installed, and the NACL_SDK_ROOT set as per installation instructions and the libsndfile-nacl sources (https://www.dropbox.com/s/ezfo9rmo5wtzptz/libsndfile-nacl.tar.gz), you can use the make command to build libsndfile. To build the Csound library, run the build.sh script in the ./nacl subdirectory of the Csound 6 sources. When libraries are built, they are added to the SDK, and made readily available for applications to be built with them.

2.2 Building the pNaCl Csound module

Once the libraries are built, you can run make in the ./nacl/csound subdirectory of the Csound sources. This will build the nacl module in pnacl/Release. There is a package.sh that can be used to copy and package all the relevant files for HTML5 development. This package is self-contained, i.e. it does not have any dependencies, and it can be expanded elsewhere in your project application folders.

2.3 Running the example application

NaCl pages need to be served over http, which means they will not work when opened as local files. You need to start a local server, and this can be done with the python script httpd.py found in the $NACL_SDK_ROOT/tools directory. If you start this script in the top level directory of the pNaCl Csound package, then the example will be found at the http://localhost:5103 address.

3 Csound pNaCl module reference

The interface to Csound is found in the csound.js javascript file. Csound is ready on module load, and can accept control messages from then on.

3.1 Control functions

The following control functions can be used to interact with Csound:

3.2 Filesystem functions

In order to facilitate access to files, the following filesystem functions can be used:

3.3 Callbacks

The csound.js module will call the following window functions when it starts:

You should implement these functions in your HTML page script, in order to use the Csound javascript interface. In addition to the above, Csound javascript module messages are always sent to the HTML element with id=‘console’, which is normally of type <div> or <textarea>.

3.4 Example

Here is a minimal HTML example showing the use of Csound

,  
<!DOCTYPE html> 
<html> 
<!-- 
 Csound pnacl minimal example 
 Copyright (C) 2013 V Lazzarini 
--> 
<head> 
 <title>Minimal Csound Example</title> 
 <script type="text/javascript" src="csound.js"></script> 
 <script type="text/javascript"> 
 // called by csound.js 
 function moduleDidLoad() { 
  csound.Play(); 
  csound.CompileOrc( 
  "instr 1 \n" + 
  "a1 oscili 0.1,440+rnd(440)\n" + 
  "outs a1,a1 \n" + 
  "endin"); 
  document.getElementById("tit").innerHTML = "Click on the page below to play"; 
 } 
 function attachListeners() { 
   document.getElementById("mess"). 
       addEventListener("click",Play); 
 } 
 function handleMessage(message) { 
   var mess = message.data; 
   var messField = document.getElementById("mess") 
   messField.innerText += mess; 
 } 
 
 // click handler 
 function Play() { 
   csound.Event("i 1 0 5"); 
 } 
 </script> 
</head> 
<body> 
  <div id="console"></div> 
   <h3 id="tit"> </h3> 
  <div id="mess"> 
 
  </div> 
  <!--pNaCl csound module--> 
  <div id="engine"></div> 
</body> 
</html>

4 Limitations

The following limitations apply: