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

Important Note On libsamplerate.wasm

The web assembly file located at /node_modules/@alexanderolsen/libsamplerate-js/dist/libsamplerate.wasm needs to be placed where libsamplerate-js can find it. The default location is at the root of your public directory. This location can be changed using the wasmPath variable in the options dict passed into create():

create(nChannels, inputSampleRate, outputSampleRate, {
    wasmPath: "/some/path/to/libsamplerate.wasm",
});

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
    wasmPath: "/path/from/root/libsamplerate.wasm", // default '/libsamplerate.wasm'
}).then((src) => {
    let data = new Float32Array(44100);
    let resampledData = src.simple(data);
    src.destroy(); // clean up
});

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
    wasmPath: "/path/from/root/libsamplerate.wasm", // default '/libsamplerate.wasm'
}).then((src) => {
    let data = new Float32Array(44100);
    let resampledData = src.full(data);
    src.destroy(); // clean up
});

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
        wasmPath: "/path/from/root/libsamplerate.wasm", // default '/libsamplerate.wasm'
    }).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
 * @return {Float32Array}                 The resampled data. If dataOut != null, dataOut is returned
 */
full(dataIn, dataOut=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

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.

has-n/libsamplerate-js