Skip to content

Latest commit

 

History

History
executable file
·
133 lines (93 loc) · 4.56 KB

07.javascript.md

File metadata and controls

executable file
·
133 lines (93 loc) · 4.56 KB
Raw

Javascript

Getting Started

Heavy can provide a Javascript (JS) implementation of your patch. The library can be served directly from our servers or downloaded locally and provides a basic interface for processing audio, handling playback and sending or receiving messages.

Web Preview

The quickest way to try out your patch in the web is to use the pre-generated widget. This is automatically generated each time the patch is compiled, see the patch target pages for a example of it running.

<iframe type="text/html" frameborder="0"
    width="100%" height="592"
    src="https://enzienaudio.com/h/{USERNAME}/{PATCH}/{VERSION}/web/{PATCH}.html">
</iframe>

When specifying the {VERSION} you can either provide a number indicating the version of the patch, or use 'latest' to get the most recent revision.

For example:

<iframe type="text/html" frameborder="0"
    width="100%" height="592"
    src="https://enzienaudio.com/h/enzien/springy/latest/web/springy.html">
</iframe>

Alternatively if you want to use a custom HTML interface it is possible to link against just the javascript library, see below for more instructions on how to do that.

<script type="application/javascript" src="https://enzienaudio.com/h/{USERNAME}/{PATCH}/{VERSION}/web/{PATCH}.js"></script>

Feel free to use our servers for hosting the JS library, or choose to download it for linking locally...

Download the JS Target

For a more detailed example of running your patch in the web it can be more informative to download the JS target.

Heavy provides the following:

File Description
index.html A simple web page similar to the pre-generated widget
{PATCH}.js The main javascript library to link against
{PATCH}.wasm A web assembly compiled binary of the patch. The main js library will reference this
{PATCH}.asm.js An asmjs fallback library for non wasm compatible browsers

AudioLibLoader

The AudioLibLoader is a helper object that implements the boilerplate code for setting up the WebAudio context and making sure the heavy patch is processed correctly. It acts as a wrapper around the AudioLib.

This object simplifies the set-up required and should be sufficient for most use cases. However, if you're creating something more specific, for example routing between multiple patches, it's probably best to look into loading the AudioLib manually.

Set Up

The initial set up should look something like this:

<script type="application/javascript" src="https://enzienaudio.com/h/{USERNAME}/{PATCH}/latest/web/{PATCH}.js"></script>

<script type="text/javascript">
  // the AudioLibLoader object
  var loader = null;

  // construct a new patch module, this contains all the necessary libraries
  // make sure to replace {PATCH} with the name of your patch
  var heavyModule = {PATCH}_Module();

  // set a callback to be notified when the module has finished loading
  heavyModule['onRuntimeInitialized'] = onModuleLoaded;

  function onModuleLoaded() {
    // instantiate the AudioLibLoader object
    loader = new heavyModule.AudioLibLoader();

    // this will set up the WebAudio context add a new audio node
    loader.init({
      blockSize: 2048, // number of samples on each audio processing block
      printHook: onPrint, // callback for [print] messages, can be null
      sendHook: onFloatMessage // callback for output parameters [s {name} @hv_param], can be null
    });
  }

  // print callback
  function onPrint(message) {
    console.log(message);
  }

  // output parameter callback
  function onFloatMessage(sendName, floatValue) {
    console.log(sendName, floatValue);
  }

  // ...

</script>

Transport Controls

<script type="text/javascript">
  // ...

  // starts processing the web audio context, will generate sound
  loader.start();

  // stop processing
  loader.stop();

  // can use this to check if the patch is currently processing
  loader.isPlaying
</script>

Sending Events or Parameters

The JS target supports exposing event and parameter interfaces from the patch.

<script type="text/javascript">
  // ...

  // send a bang to an event receiver called "Attack"
  loader.audiolib.sendEvent("Attack");

  // send a float value to a parameter receiver called "Distance"
  loader.audiolib.setFloatParameter("Distance", 10);

</script>

Note: these are calls directly to the AudioLib so make sure to include .audiolib when sending events or messages.