StandingWaveJS

StandingWaveJS is a native-feeling wrapper for the StandingWave3 audio synthesis library for Flash Player 10. By native-feeling, we mean the best of both worlds - you get the flexibility of declaratively specifying sound sources in client-side Javascript, combined with the high-performance cross-platform-today sound support of Flash.

StandingWaveJS is built on an Adobe library called FABridge, which exposes proxies of ActionScript objects as plain old Javascript objects, with lazy serialization of their contents. All the audio data stays in Flash, where it takes advantage of the new Adobe Alchemy opcodes to give near-native data processing performance. Meanwhile, your user interface and logic can live entirely in Javascript.

Here's a snippet from index.html that shows how simple this is. Note that every line of Javascript operates in constant time, so your user interface will remain responsive.

$("#piano").click(function() {
  sw.whenInitialized(function() {
    var desc = sw.newAudioDescriptor();
    sw.loadSound("piano_Ab4.mp3", function(err, sound) {
      if (err) return console.error(err);
      var player = sw.newAudioPlayer();
      var s1 = sw.newSoundSource(sound);
      var s2 = sw.newResamplingFilter(s1, 1.5);
      var s3 = sw.newResamplingFilter(s2, 1.5);
      var s4 = sw.newResamplingFilter(s2, 5/3);
      var seq = sw.newListPerformance();
      seq.addSourceAt(0, s1);
      seq.addSourceAt(0.1, s2);
      seq.addSourceAt(0.2, s3);
      seq.addSourceAt(0.3, s4);
      var perf = sw.newAudioPerformer(seq, desc);
      var perf2 = perf.clone();
      player.play(perf);
    })
  })
})

Compare this to an example from the StandingWave3 documentation itself, and you can see that the spirit of the API is maintained perfectly (just with a couple fewer spaces).

// Create an ascending sequence of three sine tones: A3, E4, A4
// whose start times are separated by exactly 1 second.
var sequence:ListPerformance = new ListPerformance();
sequence.addSourceAt(0, new SineSource(new AudioDescriptor(), 0.1, 440));
sequence.addSourceAt(1, new SineSource(new AudioDescriptor(), 0.1, 660));
sequence.addSourceAt(2, new SineSource(new AudioDescriptor(), 0.1, 880));
// Play it back.
var source:IAudioSource = new AudioPerformer(sequence);
player.play(source);

Running the Example

Due to local file sandboxing, you won't be able to just double-click on index.html. Instead, download Node.js, install the server dependencies with npm install, and browse to localhost:8000.

Using the Library

The standingwavejs.swf SWF should be embedded in the page, either using SWFObject or some other method; FABridge has been patched to allow for this.

The standingwavejs.js script can be included in the page directly, in which case it exposes window.sw as its namespace. You can inspect this object in your browser console to see the API, but it largely follows the Flash API.

Alternately, StandingWaveJS will integrate with packages such as Browserify, which use the NPM package manager to bundle dependencies. If such a bundler is used, and module is defined globally, then module.exports will be set to the namespace, and window.sw will not be touched. A wrapped version of FABridge is bundled with this script so that the correct internal globals are registered; however, at the moment, it will not play nicely with other FABridge-powered wrappers.

Some gotchas:

• Occasionally, Javascript errors will be eaten by the Flash ExternalInterface mechanism, and Javascript callbacks will just return silently in the middle of their execution. To make your debugging a bit saner, wrap your closures in try/catch blocks that print the errors.

• If an error is printed with a numeric error number, just Google the number and "flash error" to see what it means.

Recompiling the Library

Change the first line of the Makefile to point to an installed Flex SDK, and you should be able to make all to regenerate those two files.

About

Original library by Max Lord and Joe Berkovitz.

Wrapper by Brenton Partridge, as a very small part of something that will change the music game... but you're going to need to wait to learn about that!

MIT license.