libsamplerate-js

!GitHub Workflow Status   

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:

``bash
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.

$3

`javascript
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

`javascript
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
});
`

$3

`javascript
// 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'
);
`

`javascript
// 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._

$3

`html


`

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

`html

`

API Reference

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

$3

`javascript
/**
* 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) { ... }
`

$3

`javascript
/**
* 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) { ... }
`

$3

`javascript
/**
* 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() { ... }
`

$3

`javascript
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
});
`

$3

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

`javascript
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

$3

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

and listen to to the result

$3

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

`bash
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:

`bash
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:

`bash
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):

`bash
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`.