@alexanderolsen/libsamplerate-js

libsamplerate-js

libsamplerate-js is a port of libsamplerate to Web Assembly exposed through a simple JS API for use in-browser or node. The simple API is ideal for resampling large pieces of audio. The full API is ideal for quickly resampling small portions (128+ samples) of a larger piece of audio such as audio received from a Websocket or WebRTC connection.

Features:

• works both in-browser and in node!
• 1-128 channels
• 1-192000 sample rates
• libsamplerate Full and Simple APIs
• See the libsamplerate docs for much more (and better) info

Installation

Install using NPM:

npm i @alexanderolsen/libsamplerate-js

See Usage or API for more examples and instructions.

Usage

libsamplerate-js expects to receive Float32Array mono or multi-channel interleaved data, where each sample is -1 < sample < 1.

In modules:

import { create, ConverterType } from '@alexanderolsen/libsamplerate-js';

let converterType = ConverterType.SRC_SINC_BEST_QUALITY;
let nChannels = 2;
let inputSampleRate = 44100;
let outputSampleRate = 48000;

create(nChannels, inputSampleRate, outputSampleRate, {
  converterType: converterType, // default SRC_SINC_FASTEST. see API for more
}).then((src) => {
  let data = new Float32Array(44100);
  let resampledData = src.simple(data);
  src.destroy(); // clean up
});

or

const LibSampleRate = require('@alexanderolsen/libsamplerate-js');

let converterType = LibSampleRate.ConverterType.SRC_SINC_BEST_QUALITY;
let nChannels = 2;
let inputSampleRate = 44100;
let outputSampleRate = 48000;

LibSampleRate.create(nChannels, inputSampleRate, outputSampleRate, {
  converterType: converterType, // default SRC_SINC_FASTEST. see API for more
}).then((src) => {
  let data = new Float32Array(44100);
  let resampledData = src.full(data);
  src.destroy(); // clean up
});

In AudioWorklets:

// project.js
const audioContext = new AudioContext({ sampleRate: 44100 });
await audioContext.audioWorklet.addModule('processor.js');
// You can also bundle libsamplerate.worklet.js with your own application; cdn link provided for convenience
await audioContext.audioWorklet.addModule(
  'https://cdn.jsdelivr.net/npm/@alexanderolsen/libsamplerate-js/dist/libsamplerate.worklet.js'
);

// processor.js
const { create, ConverterType } = globalThis.LibSampleRate;

let nChannels = 1;
let inputSampleRate = 44100;
let outputSampleRate = 16000; // or another target sample rate

// somewhere in the declaration of your Processor:
create(nChannels, inputSampleRate, outputSampleRate, {
  converterType: ConverterType.SRC_SINC_BEST_QUALITY, // or some other quality
}).then((src) => {
  this.src = src;
});

See examples/worklet for a full implementation example. Configuring libsamplerate-js to work in AudioWorklets is less trival than it ought to be due to AudioWorklet limitations. Note that typing support is not avaialble for LibSampleRate within the context of AudioWorklets.

In HTML:

<script src="https://cdn.jsdelivr.net/npm/@alexanderolsen/libsamplerate-js"></script>
<script>
  var converterType = LibSampleRate.ConverterType.SRC_SINC_BEST_QUALITY;
  var nChannels = 2;
  var inputSampleRate = 44100;
  var outputSampleRate = 48000;

  LibSampleRate.create(nChannels, inputSampleRate, outputSampleRate, {
    converterType: converterType, // default SRC_SINC_FASTEST. see API for more
  }).then((src) => {
    var data = new Float32Array(44100);
    let resampledData = src.full(data);
    src.destroy(); // clean up
  });
</script>

Or use the libsamplerate.js file in the dist folder:

<script src="libsamplerate.js"></script>

API Reference

Once you've created the JS wrapper using create() or LibSampleRate.create(), the returned object exposes:

simple

/**
 * Calls the libsamplerate `simple` API. This should be used when resampling one individual chunk of audio,
 * and no more calls to are required. If more calls are required, use the `full` API. If the array submitted
 * is > 4MB, audio will be broken up into chunks and the `full` API will be used
 *
 * More (and better) info available at: http://www.mega-nerd.com/SRC/api_simple.html
 *
 * @param  {Float32Array}         dataIn  Float32Array containing mono|interleaved audio data where -1 < dataIn[i] < 1
 * @return {Float32Array}                 The resampled data
 */
simple(dataIn) { ... }

full

/**
 * Calls the libsamplerate `full` API. This should be used when resampling several chunks of the
 * sample audio, e.g. receiving a live stream from WebRTC/websocket API.
 *
 * More (and better) info available at: http://www.mega-nerd.com/SRC/api_full.html
 *
 * @param {Float32Array}      dataIn              Float32Array containing mono|interleaved audio data where -1 < dataIn[i] < 1
 * @param {Float32Array|null} dataOut             Optionally, pass a Float32Array to avoid allocating an extra array for every esampling operation
 * @param {Object|null}       outLength           Amount of data written to dataOut
 * @param {number}            [outLength.frames]  The number of frames in the output

 * @return {Float32Array} The resampled data. If dataOut != null, dataOut is returned
 */
full(dataIn, dataOut=null, outLength = null) { ... }

destroy

/**
 * Cleans up WASM SRC resources. Once this is called on an instance, that instance must be
 * reinitialized with src.init() before it can be used again.
 */
destroy() { ... }

Update outputSampleRate & inputSampleRate

let nChannels = 2;
let inputSampleRate = 44100;
let outputSampleRate = 48000;

create(nChannels, inputSampleRate, outputSampleRate).then((src) => {
  let data = new Float32Array(44100);
  let resampled48k = src.simple(data); // returns ~48000 samples
  src.outputSampleRate = 96000;
  let resampled96k = src.simple(data); // returns ~96000 samples
});

ConverterType

Converter types are as follows. More information can be found at the libsamplerate website.

const ConverterType = {
  SRC_SINC_BEST_QUALITY: 0, // highest quality, slowest
  SRC_SINC_MEDIUM_QUALITY: 1, //
  SRC_SINC_FASTEST: 2, // in-between
  SRC_ZERO_ORDER_HOLD: 3, // poor quality, "blindingly" fast
  SRC_LINEAR: 4, // poor quality, "blindingly" fast
};

Examples

Node

cd libsamplerate-js/examples/cli
node index.js 48000 result.wav

and listen to to the result

Web

Run any server (http-server, etc) from the project directory:

cd libsamplerate-js
http-server

and visit localhost:8080/examples/basic or localhost:8080/examples/worker in a browser. Examples and benchmarks must be hosted from the root directory, as they need to access the files in dist.

Benchmarks

Get a sense of how long resampling operations take in your environment:

cd libsamplerate-js
http-server

and visit localhost:8080/benchmarks. A minimalistic UI is provided to test different batch sizes, APIs, sample rates, and ConverterTypes.

Building From Source

Before you can compile the WASM code you need to download and install Empscripten and activate PATH variables for the current terminal. To build and compile the JS + WASM resources from source, run:

git clone https://github.com/aolsenjazz/libsamplerate-js
cd libsamplerate-js
npm i
npm run compile-wasm
npm run build

You can also build with docker (either from scratch or the wasm only):

git clone https://github.com/aolsenjazz/libsamplerate-js
cd libsamplerate-js
git submodule update --init
cd scripts/library/
docker build -t gcc-emscripten .
cd ../../
npm run compile-library-docker
npm run compile-wasm-docker
npm run build

Production files are placed in the dist directory.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

Licenses are available in LICENSE.md.