@generative-music/web-provider

An audio sample file provider with caching for use in the browser.

Usage

The default export of this library is the factory function createProvider, which returns WebProvider instances. WebProvider instances can be used to fetch, cache, and decode audio files.

`createProvider()`

A factory function which returns a WebProvider.

Syntax

const webProvider = createProvider(saveWorker);

Parameters

saveWorker (optional): An instance of a SaveWorker. If omitted, save will silently fail.

Return value

A WebProvider instance.

`WebProvider`

A WebProvider can be used to load, cache, and decode audio files.

`WebProvider.has()`

The has method of the WebProvider interface returns a Promise that resolves to a boolean value indicating whether or not the provider is currently capable of providing the requested audio files given the current network conditions. The resolved value will be true if the client is currently online or if all the audio files are cached locally.

Syntax

webProvider.has(urls).then(function(result) {
  // Do something with the result
});

Parameters

urls: An array of strings containing URLs to audio files.

Return value

A Promise which resolves to a boolean indicating whether the provider is currently capable of providing the requested audio files given the current network conditions.

`WebProvider.request()`

The request method of the WebProvider interface returns a Promise that resolves to an array of AudioBuffer instances.

Syntax

webProvider.request(audioContext, urls).then(function(results) {
  // Do something with the results
});

Parameters

audioContext: An AudioContext object used to create the [AudioBuffer] instances.
urls: An array of strings containing URLs to audio files.

Return value

A Promise which resolves to an array of AudioBuffer instances of the requested audio files. The resolved array is of the same length as urls and in the same order. If an audio file could not be loaded or decoded, the promise will reject.

`WebProvider.save()`

The save method of the WebProvider interface caches AudioBuffer instances for later retrieval via request.

⚠️ This method requires a instance of SaveWorker to have been passed to makeWebProvider. See SaveWorker below.

Syntax

webProvider.save(cacheEntries).then(function() {
  // The entries were saved!
});

Parameters

cacheEntries: An array of [key, value] pairs where key is a string and value is an AudioBuffer.

Return value

A promise which resolves to undefined once the cacheEntries have been saved.

`SaveWorker`

To enable the save method, an instantiated SaveWorker must be passed to makeWebProvider. Two SaveWorker scripts are included at the following locations:

ESM: @generative-music/web-provider/worker/save-worker.esm.js
CJS: @generative-music/web-provider/worker/save-worker.cjs.js

Use the script most appropriate for your configuration.

⚠️ The included SaveWorker depends on IndexedDB support, though it can be safely instantiated and passed to makeWebProvider even if IndexedDB is not supported.

Creating a worker

SaveWorker is just special a special WebWorker used for saving AudioBuffer objects.

import makeWebProvider from '@generative-music/web-provider';

const saveWorker = new Worker('public/path/to/save-worker.js');

const provider = makeWebProvider(saveWorker);

See MDN: Using Web Workers for more information.

With webpack and worker-loader

In apps using webpack, consider using worker-loader:

import makeWebProvider from '@generative-music/web-provider';
import SaveWorker from '@generative-music/web-provider/worker/save-worker.esm';

const saveWorker = new SaveWorker();

const provider = makeWebProvider(saveWorker);