Csound for Portable Native Client

Victor Lazzarini

November 8, 2014

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

A binary package for PNaCl-Csound can be found in the Csound releases http://sourceforge.net/projects/csound/files/csound6

1.1 Running the example application

NaCl pages need to be served over http, which means they will not work when opened as local files. For this you will need a http server. A minimal one, written in Python, can be found in the NaCl SDK https://developer.chrome.com/native-client/sdk/download.

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

2.1 Control functions

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

2.2 Filesystem functions

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

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

2.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" + 
  "icps = 440+rnd(440) \n" + 
  "chnset icps, \"freq\" \n" + 
  "a1 oscili 0.1, icps\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; 
   if(mess.slice(0,11) == "::control::") { 
   var messField = document.getElementById("console") 
   messField.innerText = mess.slice(11); 
   } 
   else { 
   var messField = document.getElementById("mess") 
   messField.innerText += mess; 
   csound.RequestChannel("freq"); 
  } 
 } 
 
 // 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>

3 Limitations

The following limitations apply: