Development guide: Capturing audio

The SuperpoweredWebAudio class contains a helper function called getUserMediaForAudioAsync for easier audio capturing and ironing out browser differences along the way.

Please note that Web Audio AudioContext and browser audio capture requires a secure context: HTTPS or localhost. User interaction is also required on the page before any audio input can be requested and streamed into the AudioContext. Generally speaking, you'll want to resume the audio context on the user's first interaction.

Within the main application Javascript file, where you created an instance of the Superpowered WebAudio manager (webaudioManager) and AudioWorkletProcessorNode (processorNode), you should request the user microphone with webaudioManager.getUserMediaForAudioAsync(). This will return a MediaStream, which must be passed into a MediaStreamSourceNode allowing audio flowing into our AudioWorkletNode running our own AudioWorkletProcessor script.

async function setupAudioCapture() {
    // either pass in {'fastAndTransparentAudio': true} for the default soundcard/device with no processing,
    // or pass in a MediaStreamConstraints object - see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamConstraints
    const userInputStream = await webaudioManager.getUserMediaForAudioAsync({ 'fastAndTransparentAudio': true });
    if (!userInputStream) throw Error('no access to user microphone');

    // create a WebAudio API MediaStreamSourceNode - https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamAudioSourceNode
    const userInputStreamSourceNode = webaudioManager.audioContext.createMediaStreamSource(userInputStream);

    // if the input is mono, then upmix the mono channel to a stereo node with a WebAudio API ChannelMergerNode
    // because Superpowered expects stereo
    const userInputMergerNode = webaudioManager.audioContext.createChannelMerger(2);

    // connect the userInputStreamSourceNode input to channels 0 and 1 (L and R)
    userInputStreamSourceNode.connect(userInputMergerNode, 0, 0); // left
    userInputStreamSourceNode.connect(userInputMergerNode, 0, 1); // right

    // now we have a stereo audio node (userInputMergerNode) which we can connect to an AudioWorklet Node
    // connect the stereo microphone stream into our processor stereo input
    userInputMergerNode.connect(processorNode);

}

In this example, our AudioWorkletProcessorNode (processorNode) comprises of a single Volume function in processAudio.

import "../Superpowered.js";

class UserAudioProcessor extends SuperpoweredWebAudio.AudioWorkletProcessor {

  // Runs after the constructor
  onReady() {
    this.inputGain = 0.5;
    this.previousInputGain = 0;

    // Notify the main scope that we're prepared.
    this.sendMessageToMainScope({ event: "ready" });
  }

  // onDestruct is called when the parent AudioWorkletNode.destruct() method is called.
  // You should clear up all Superpowered objects and allocated buffers here.
  onDestruct() {
      // Nothing to clear in this example.
  }

  onMessageFromMainScope(message) {
    if (message.type === "parameterChange") {
      if (message.payload?.id === "inputGain") this.inputGain = message.payload.value;
    }
  }

  processAudio(inputBuffer, outputBuffer, buffersize, parameters) {
    // Apply volume while copy the input buffer to the output buffer.
    // Gain is smoothed, starting from "previousInputGain" to "inputGain".
    this.Superpowered.Volume(
      inputBuffer.pointer,
      outputBuffer.pointer,
      this.previousInputGain,
      this.inputGain,
      buffersize
    );
    this.previousInputGain = this.inputGain; // Save the gain for the next round.
  }
}

// The following code registers the processor script in the browser, please note the label and reference.
if (typeof AudioWorkletProcessor !== "undefined") registerProcessor("UserAudioProcessor", UserAudioProcessor);
export default UserAudioProcessor;

We are sending gain control values from our slider input element via the main thread (src/index.js) over the AudioWorket message port like this:

<input
  type="range"
  min="0"
  max="1"
  step="0.01"
  value="0.5"
  oninput="onParamChange('inputGain', this.value)"
/>

...

// the onchange handler on the dom element is bound to the following function in our main applciation
onParamChange = (id, value) => {
    // Here we send the new gain value over to the audio thread to be applied
    this.processorNode.sendMessageToAudioScope({
      type: "parameterChange",
      payload: {
        id,
        value: Number(value) // we should type cast here
      }
    });
  };

...

We've created an ES6 style Javascript sandbox for you to try out the code above.