@itslanguage/recorder

ITSLanguage Recorder Package

Speech technology for language education. 📣

This package exposes a very simple wrapper around a polyfill for the MediaRecorder API. We have two reasons to use the polyfill:

1. The MediaRecorder API is not available in some browser (like safari). With this polyfill it is.
2. The polyfill supports WAVE which is what we need for the backend.

In the future we want to be able to support both the browser default MediaRecorder, and this polyfill.

Getting started

Install with npm:

npm install @itslanguage/recorder

Example usage, in code:

import { createRecorder, createMediaStream } from '@itslanguage/recorder';

// Ask and wait for the user to give permission and get an audio stream.
createMediaStream().then(stream => {
  // Create a MediaRecorder instance with the stream you got.
  const recorder = createRecorder(stream);

  // Store audio chunks
  let audioChunks = [];

  // Start listening to onDataavailable to process data
  // This event will be raised per x milliseconds, per
  // recorder.requestData() call or on the end.
  recorder.addEventListener('dataavailable', event => {
    audioChunks.push(event.data);
  });

  // Let's record approximately 25 seconds of audio, and automatically playback
  recorder.start();

  window.setTimeout(() => {
    recorder.stop();

    // Now we can loop over the audio chunks and display them to the browser
    audioChunks.forEach(chunk => {
      const audioElm = document.createElement('audio');
      audioElm.controls = true;
      audioElm.src = URL.createObjectURL(chunk);

      // Just a quick way to display the audio element to the screen
      document.getElementsByTagName('body')[0].appendChild(audioElm);

      // At this point you will see some audio elements on the
      // screen which you can use to listen to the audio recorded.
    });
  }, 25000);
});

Plugins

The recorder is prepared to be extended with plugins. For example, we have written a plugin called AmplitudePlugin that will output (emit) volume information directly via the recorder. This information can, for example, be used to create a volume meter to indicate recording to an end user. For more information on this plugin, check the plugin itself.

Plugins can be used to create an instance of the plugin, and then add it to the recorder. The recorder will then call the apply function of the plugin.

This is an example on how one could use the AmplitudePlugin.

import {
  createRecorder,
  createMediaStream,
  createAmplitudePlugin,
} from '@itslanguage/recorder';

// Ask and wait for the user to give permission and get an audio stream.
createMediaStream().then(stream => {
  const amplitudePlugin = createAmplitudePlugin(/* options here*/);

  // Create a MediaRecorder instance with the stream you got. Also, pass the
  // plugins as the second argument.
  const recorder = createRecorder(stream, [amplitudePlugin]);

  // Start listening to amplitudelevels. Once fired, it will return
  // an object with volume information.
  recorder.addEventListener('amplitudelevels', event => {
    // log the current volume of the recorder to the console.
    console.log(event.data.volume);
  });

  // Start recording!
  recorder.start();
});

API

createRecorder

createRecorder([stream], [plugins], [(mimeType = 'audio/wav')]);

This function is a factory method that just instantiates and returns a MediaRecorder object.

Arguments

• [stream : MediaStream]: Pass a MediaStream object to the constructor of MediaStream. This param is not required, even though if you would omit it, recording would not work obviously (no stream = no data).
• [plugins: Array]: Pass plugins to the recorder to initialize.
• [mimeType: 'audio/wav' : String]: Override the default mimeType for the recorder. Whether a mimeType is valid or not can be checked with MediaRecorder.isTypeSupported(). Defaults to audio/wav.

createMediaStream

createMediaStream();

This method will (try to) call navigator.mediaDevices.getUserMedia(). This will give you the required (authorized) stream to use with the MediaRecorder object.

Also, this function will trigger the browser to ask the user for permission to access the microphone.

It returns a promise and if all good the promise resolve with a MediaStream object

createAmplitudePlugin

createAmplitudePlugin(
  (options = { immediateStart: false, stopAfterRecording: true }),
);

Factory function to create an amplitude plugin. It will accept some options and if all good it will return an AmplitudePlugin object that can be passed to the plugin array for createRecorder.

The amplitude plugin wil dispatch amplitudelevels events on the recorder with information about the volume levels (per input channel if possible).

Arguments

• [options: Object]: Pass an object with options to control how the plugin behaves.
• [options.immediateStart: false : Boolean]: Start dispatching volume levels when instantiating the plugin. If false (default value) it will start when the recording is started.
• [options.stopAfterRecording: true : Boolean]: Stop dispatching volume levels when the recorder is stopped, which is the default behaviour.

createBufferPlugin

createBufferPlugin(
  (options = {
    immediateStart: false,
    stopAfterRecording: true,
    secondsToBuffer: 30,
    eventToDispatch: 'bufferdataavailable',
  }),
);

Factory function to create a buffer plugin. It will accept some options and if all good it will return a BufferPlugin object that can be passed to the plugin array for createRecorder.

The buffer plugin will dispatch buffered audio as audio/wav blob to the recorder via the bufferdataavailable event. When instantiated it will register a function requestBufferedData on the recorder. When invoking that function the configured event will be dispatched with the requested data. See below for the API of requestBufferedData.

Arguments

• [options: Object]: Pass an object with options to control how the plugin behaves.
• [options.immediateStart: false : Boolean]: Start buffering audio when instantiating the plugin. If false (default value) it will start when the recording is started.
• [options.stopAfterRecording: true : Boolean]: Stop buffering audio when the recorder is stopped, which is the default behaviour.
• [options.secondsToBuffer: 30: Number]: Value that controls how many seconds of audio will always be in the buffer. Defaults to 30 seconds.
• [options.eventToDispatch: bufferdataavailable: String]: The event that is used to dispatch the buffered audio on when requested. Use this option to override the default value.

requestBufferedData

requestBufferedData((secondsToRead = 3));

This function will be registered on a recorder and allow you to get the buffered data. When invoked it will make sure the configured event (by default bufferdataavailable) will be dispatched.

The function will be registered when audio buffering is started, and will be deleted once the buffering stops.

Arguments

• [secondsToRead: 3: Number]: Use this param to define how may seconds there will be read from the buffer. By default there will be gathered 3 seconds of audio. If the value of secondsToRead is 0 or equal or larger than the amount of audio in the buffer the buffer will be returned completely.

Example

import {
  createRecorder,
  createMediaStream,
  createNufferPlugin,
} from '@itslanguage/recorder';

// Ask and wait for the user to give permission and get an audio stream.
createMediaStream().then(stream => {
  const bufferPlugin = createNufferPlugin(/* options here*/);

  // Create a MediaRecorder instance with the stream you got. Also, pass the
  // plugins as the second argument.
  const recorder = createRecorder(stream, [bufferPlugin]);

  // Start listening to bufferdataavailable. Once fired, it will return
  // a Blob with the requested audio from the buffer.
  recorder.addEventListener('bufferdataavailable', event => {
    console.log(event.data); // Outputs a Blob {};
  });

  // Start recording!
  recorder.start();

  // At a certain point in time you will want to get some audio from the buffer
  recorder.requestBufferedData();
});

Read more

Read more on the MediaStream Recording API on MDN: https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder

Read more on the polyfill we used: https://github.com/ai/audio-recorder-polyfill