Have ideas to improve npm?Join in the discussion! »

    @alexanderolsen/libsamplerate-js

    1.1.6 • Public • Published

    libsamplerate-js

    AppVeyor Coverage Status Maintainability Depfu

    libsamplerate-js is a port of libsamplerate to Web Assembly exposed through a simple JS API for use in-browser. 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:

    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, ouputSampleRate, {
        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
        });

    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, ouputSampleRate, {
        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 should not
     * be used again or else risk hitting a segfault in WASM code.
     */
    destroy() { ... }

    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

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

    Install

    npm i @alexanderolsen/libsamplerate-js

    DownloadsWeekly Downloads

    2

    Version

    1.1.6

    License

    MIT

    Unpacked Size

    1.54 MB

    Total Files

    6

    Last publish

    Collaborators

    • avatar