@ircam/sc-loader

sc-loader

Load AudioBuffer in Node.js (cf. node-web-audio-api) and the Browser with a unified interface

Install

npm install --save @ircam/sc-loader

Usage

import { AudioBufferLoader } from '@ircam/sc-loader';

const audioContext = new AudioContext();
const loader = new AudioBufferLoader(audioContext);
// load one file
const buffer = await loader.load('path/to/file.wav');
const src = audioContext.createBufferSource();
src.buffer = buffer;
src.connect(audioContext.destination);
src.start();

API

Table of Contents

• AudioBufferLoader
  • Parameters
  • Examples
  • sampleRate
  • serverAddress
  • load
  • get
  • getValues
  • abort
  • clear

AudioBufferLoader

The AudioBufferLoader interface allows to load AudioBuffer in Node.js and the Browser with a unified interface.

Parameters

• sampleRateOrAudioContext (AudioContext | number) An exisiting AudioContext instance or a valid sample rate. Loaded audio buffers will be resampled to the given sample rate or audio context sample rate
• serverAddress string Optional server address URL to use for loading the audio files. (optional, default null)

Examples

import { AudioBufferLoader } from '@ircam/sc-loader';
// import { AudioContext } from 'node-web-audio-api';

const audioContext = new AudioContext()
const loader = new AudioBufferLoader(audioContext);
// load one file
const buffer = await loader.load('path/to/file.wav');

sampleRate

Sample rate of loader and decoded audio buffers

serverAddress

Optional server address URL to use for loading the audio files.

load

Load audio buffers.

In the browser, the given path to the audio files are resolved as following:

• if serverAddress is null, rely on default fetch behavior
• if serverAddress is not null, try to create an URL from pathname and serverAddress

In Node.js,

• load from filesystem relative to process.cwd()
• load from filesystem relative to caller site
• load from network if an absolute URL is given
• if serverAddress is given and all other strategies failed, try to build a valid URL from pathname and serverAddress, and try to load from network

Calling this function will erase the cache from previous load call.

Returns null if aborted

Parameters

• requestInfos (string | array<string> | object<string, string>) List of sound file to load, the returned value structure will match the strcuture of the argument. If the sound file could not be load (e.g. file not found or decoding error) the slot will be set to null.

Examples

// load single file
const buffer = await loader.load('path/to/file.wav');
// load array
const buffers = await loader.load(['file1.wav', 'file2.mp3', 'ile3.wav']);
// load object
const buffers = await loader.load({ file1: 'file1.wav' });

Returns (AudioBuffer | array<AudioBuffer> | object<string, AudioBuffer>)

get

Get an AudioBuffer from cache according the its key or index.

If the cache is a single AudioBuffer, it will be returned disregarding the given key.

Parameters

• key
• null-null (number | string) Key to the AudioBuffer

Examples

// load and get single file
await loader.load('path/to/file.wav');
const buffer = loader.get();
// load array and get file at index
await loader.load(['file1.wav', 'file2.mp3', 'ile3.wav']);
const buffer = loader.get(0);
// load object and get file by key
await loader.load({ file1: 'file1.wav' });
const buffer = loader.get('file1');

Returns AudioBuffer

getValues

Get full cache of the loader.

Examples

const buffers = await loader.load(['file1.wav', 'file2.mp3', 'ile3.wav']);
const cache = loader.getValues(0);
console.log(buffers === cache);

Returns (AudioBuffer | array<AudioBuffer> | object<string, AudioBuffer>)

abort

Abort an ongoing load call.

The cache from previous load call will be preserved.

Examples

const promise = loader.load(['file1.wav', 'file2.mp3', 'ile3.wav']);
await true;
loader.abort();
const result = await promise;
console.log(result === null);

Returns (AudioBuffer | array<AudioBuffer> | object<string, AudioBuffer>)

clear

Clear the cache.

Examples

const buffers = await loader.load(['file1.wav', 'file2.mp3', 'ile3.wav']);
loader.clear();
const cache = loader.getValues();
console.log(cache === null);

Development notes

Running the tests

npm run test

TODOS

Provides loaders for other type of files?

• [ ] AudioBuffers
• [ ] JSON
• [ ] raw text
• [ ] binary format (i.e. midi files)

License

BSD-3-Clause