Csound and CsoundAC for WebAssembly v3.3.0

csound-wasm

Michae Gogins, Edward Costello, Steven Yi, Henri Manson

https://github.com/gogins

http://michaelgogins.tumblr.com

Release Notes

v3.3.0

• Added a CsoundAudioNode.GetFileData method to enable users to get data
  from ta file in the memory filesystem of the AudioWorkletGlobalScope, e.g. a
  soundfile record by Csound's fout opcode, into the browser's JavaScript
  context, where it can be downloaded.

• Enable source level debugging of C/C++ code compiled to WASM in DWARF
  format. Very useful!

• Updated Csound.

v3.2.0

• Updated Csound to version 6.19.0.

• Improved the WebAssembly builds of Csound and CsoundAC to support
  running either in NW.js with native Csound, or in Web browsers with
  Csound for WebAssembly. This makes it possible, e.g., to compose pieces
  using Strudel with native Csound, VST plugins, access to the local
  filesystem, and so on.

Important Note

In order for Csound to use audio, the microphone, and MIDI, the user must
grant these permissions for the site hosting Csound to the Web browser
(usually by right-clicking on the lock symbol to the left of the URL, or
on a permissions icon to the left of the URL).

Introduction

THis directory builds and packages csound-wasm (Csound for WebAssembly),
which includes my WebAssembly build of Csound
and a WebAssembly build of my Csound Algorithmic Composition
library.

This build replaces CsoundObj.js from the core Csound repository with my
own WebAssembly build of Csound, compiled using the Emscripten LLVM
toolchain.

Although I have tried to use CsoundObj in my compositions, I find that
my own build is more stable and easier to use for my purposes. That is because
my WebAssembly version of the Csound API is much closer to the original C++
interface, supports printing Csound messages from JavaScript, and appears to
be more resilient and reliable. As long as this project is easy to maintain, I
will continue to support it and use it.

This build uses the new WebAudio AudioWorklet for superior performance with
fewer audio issues. Features include:

• A number of C++ plugin opcodes (here, statically linked).

• A new JavaScript interface to Csound that follows, as exactly as possible,
  the interface defined by the Csound class in csound.hpp and also
  implemented in CsoundOboe by csound_oboe.hpp for the Csound for Android
  app, and by csound.node.

• Additional Csound API methods exposed to JavaScript.

Please log any bug reports or requests for enhancements at
https://github.com/gogins/csound-extended/issues.

Changes

See https://github.com/gogins/csound-wasm/commits/develop for the commit log.

Installation

Download the latest version of csound-wasm-{version.zip} from the
release page here. Unzip
it and it is ready to use.

Examples

There are some working examples in the release zip file. In the directory where
you have unzipped the release, execute:

python3 -m http.server

Then navigate to http://localhost:8000 and view minimal.html. Click on
the Play button to validate your installation. Do the same with
trichord_space.html which uses CsoundAC in addition to Csound.

Some of the examples herein will run from
https://gogins.github.io/csound-examples. For more information, see my
csound-examples repository.

Building

If you are simply going to use csound-wasm, download the binary release
hosted here. If you are going to build csound-wasm, for example in order to
debug or contribute to it, follow these instructions.

You will need to make sure that the boost header files and the Eigen library
for matrix algebra are available to the Emscripten toolchain. The easiest way
to do this is to install the libeigen3-dev and libboost-dev system
packages, and make them available to the Emscripten toolchain. Only header
files from these packages are used here.

The main build scripts are:

1. build-prequisites-wasm.sh, which re-installs the Emscripten SDK,
   downloads libsndfile and its dependencies, and builds libsndfile. This step
   is quite time-consuming, but you should only have to run it once.

2. build-wasm.sh, which updates submodules, builds Csound for WASM, builds
   CsoundAC for WASM, and creates a release package that also includes
   examples, Csound instrument definitions, miscellaneous JavaScript files,
   and so on.

Minor Updates

This release is updated to match Csound 6.18.2, and with some new convenience functions in CsoundAC:

Score.setDurationFromZero and Score.getDurationFromZero
Scale.modulations_for_voices

Yet another refactoring

1. The csound-extended submodule has been replaced by the newer and simpler csound-ac submodule.
2. The build scripts have been simplified and should work on both macOS and Linux.
3. The FluidSynth and STK opcodes are not currently included.

First release of refactored csound-extended-wasm

This WebAssembly build of Csound, CMask, and CsoundAC has been moved into its own repository from https://github.com/gogins/csound-extended.

Examples may be found in the https://github.com/gogins/csound-examples repository, in the docs subdirectory.

Please log an issue here to report any problems, or make any suggestions or requests.