Earwurm

Earwurm is a minimal-scope library for managing webm audio files using the Web Audio API.

The intention of this library is to help make it easier to add sound effects in user interfaces. Earwurm solves for modern use-cases only. The scope of this library is small. If you require more capabilities than what this library offers, it is recommended to use the Web Audio API directly (alternatively, another library that offers the features you require).

File formats:

Since webm should be the most compact and broadly-supported format for playing audio on the web, it is the only format to be supported by this library.

It is recommended to use the opus codec for any webm files used with Earwurm. However, vorbis should work as well.

Technically, you can still provide mp3, wav, and other audio files to Earwurm. Just don't expect this library to make accommodations for those formats if problems arise.

Web Audio:

This library only supports the Web Audio API. Interacting with HTML5 audio elements is not supported. Long-playing audio files are not recommended as inputs for Earwurm (example: full-length songs). This library expects to playback short-duration sound effects.

Other sounds:

Earwurm was built to control audio files only. Generating sounds using Web Audio (and subsequently controlling them) is not supported by this library.

Compatibility:

This library was built for the web, and cannot be used within a node.js project.

Network requests:

At the moment, Earwurm expects your audio files to originate from the same domain. If you are attempting to load audio assets from a different domain, you may encounter cross-origin issues.

Each sound asset is obtained via a fetch request. It is possible to pass an optional options object for the Request, but this can only be customized per-instance of Earwurm, and not for each individual asset. If asset’s require different Request > options, you may need to instantiate multiple instances of Earwurm.

Setup

Follow these steps to get up and running with Earwurm.

Installing the dependency:

# Using NPM
npm install @beefchimi/earwurm

# Using Yarn
yarn add @beefchimi/earwurm

Initializing a global instance:

import {Earwurm} from '@beefchimi/earwurm';
import type {ManagerConfig} from '@beefchimi/earwurm';

// Optionally configure some global settings.
const customConfig: ManagerConfig = {
  fadeMs: 200,
  request: {},
};

// Initialize the global audio controller.
const controller = new Earwurm(customConfig);

Documentation

Please see the following links for more insight into using Earwurm:

• API
• Design
• Examples
• Resources
• Roadmap