Skip to content

Latest commit

 

History

History
88 lines (54 loc) · 3.59 KB

README.md

File metadata and controls

88 lines (54 loc) · 3.59 KB
Raw

Earwurm

License: ISC Mutable.ai Auto Wiki

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

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

# Using PNPM
pnpm add earwurm

Initializing a global instance:

import {Earwurm, type ManagerConfig} from 'earwurm';

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

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

Important context

Before getting too deep into Earwurm development, 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.

For help on how to convert your audio files, check out the provided docs.

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, or (presumably) on a server.

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.

If having more flexibility of network requests is a feature you would like to see... please get involved and help out!

Documentation

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