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

Important

Before beginning, it is critical to understand the following:

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.

Converting audio

This documentation will not describe authoring audio and exporting it from any editing software.

Quite simply, if you have existing audio files that are not already in webm format, you can convert them using a command-line tool called ffmpeg. You can learn some audio-specific commands from the ffmpeg documentation.

Using ffmpeg, you can select an audio file as an “input source”, pass some options that tell ffmpeg how you want to transform the audio, and point to an “output source” to save the converted asset.

Good defaults for web audio:

The following command will take a wav asset and convert it to webm:

# Navigate to the directory with your audio assets:
cd to/directory/that/has/audio-assets

# Convert a single audio file:
ffmpeg -i input-file.wav -dash 1 -map_metadata -1 -acodec libopus -ar 48000 -ac 2 -ab 96k -f webm output-file.webm

Here is a breakdown of the command:

• ffmpeg: Call the ffmpeg function.
• -i {input-file.ext}: Select a file as input.
• -dash 1: Create a WebM file conforming to WebM DASH specification (may not be necessary for more use-cases).
• -map_metadata -1: Strip out metadata, resulting in a smaller file size.
• -acodec libopus: Use the opus codec.
• -ar 48000: Set the audio frequency. 48000hz might be the minimum for libopus (could throw an error at a lower value).
• -ac 2: Set the number of audio channels (mono = 1, stereo = 2).
• -ab 96k: Set the bitrate. 96k for 2-channel stereo sound is probably good, but 128k might be preferrable.
• -f webm: Specifiy the output format.
• {output-file.ext}: End with the file name (including extension) you wish to save.

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.

Getting started

Follow these steps to get up and running with Earwurm.

Installing the dependency:

# Using NPM
npm install earwurm

# Using Yarn
yarn add earwurm

Initializing a global instance:

import {Earwurm} from 'earwurm';
import type {ManagerConfig} from '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