or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

global-audio.mdindex.mdsound-playback.mdspatial-audio.md
tile.json

tessl/npm-howler

Javascript audio library for the modern web with Web Audio API and HTML5 Audio support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/howler@2.2.x

To install, run

npx @tessl/cli install tessl/npm-howler@2.2.0

index.mddocs/

Howler.js

Howler.js is a comprehensive JavaScript audio library for modern web applications that provides a unified API for working with audio across different platforms. It automatically chooses between Web Audio API and HTML5 Audio and gracefully handles browser compatibility, mobile device limitations, and audio format support.

Package Information

  • Package Name: howler
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install howler

Core Imports

import { Howl, Howler } from "howler";

For CommonJS:

const { Howl, Howler } = require("howler");

Browser (via CDN):

<script src="https://cdn.jsdelivr.net/npm/howler@2.2.4/dist/howler.min.js"></script>

Basic Usage

import { Howl, Howler } from "howler";

// Create and play a sound
const sound = new Howl({
  src: ['path/to/audio.mp3', 'path/to/audio.ogg'],
  volume: 0.5,
  loop: true,
  onload: function() {
    console.log('Sound loaded successfully');
  }
});

// Play the sound
const id = sound.play();

// Control playback
sound.pause(id);
sound.stop(id);

// Global controls
Howler.volume(0.8); // Set global volume
Howler.mute(true);  // Mute all sounds

Architecture

Howler.js is built around several key components:

  • Global Controller (Howler): Singleton instance managing global audio settings, codec detection, and audio context management
  • Sound Groups (Howl): Class representing a collection of related sounds with shared settings and audio source files
  • Individual Sounds (Sound): Internal instances representing individual playback instances within a Howl group
  • Audio Technology Abstraction: Automatic selection between Web Audio API and HTML5 Audio based on browser capabilities
  • Mobile Audio Unlocking: Automatic handling of mobile browser audio restrictions
  • Audio Sprites: Support for playing segments of larger audio files for efficient resource usage

Capabilities

Global Audio Control

Centralized management of audio system settings, global volume control, codec detection, and audio context lifecycle.

const Howler: {
  volume(vol?: number): Howler | number;
  mute(muted: boolean): Howler;
  stop(): Howler;
  unload(): Howler;
  codecs(ext: string): boolean;
};

Global Audio Control

Sound Loading and Playback

Core functionality for loading audio files, creating sound instances, and controlling playback with support for multiple audio formats and automatic fallbacks.

class Howl {
  constructor(options: HowlOptions);
  load(): Howl;
  play(sprite?: string): number;
  pause(id?: number): Howl;
  stop(id?: number): Howl;
  volume(vol?: number, id?: number): Howl | number;
  mute(muted?: boolean, id?: number): Howl | boolean;
  fade(from: number, to: number, len: number, id?: number): Howl;
  rate(rate?: number, id?: number): Howl | number;
  seek(seek?: number, id?: number): Howl | number;
  loop(loop?: boolean, id?: number): Howl | boolean;
  playing(id?: number): boolean;
  duration(id?: number): number;
  state(): string;
  unload(): Howl;
  on(event: string, fn: Function, id?: number): Howl;
  off(event?: string, fn?: Function, id?: number): Howl;
  once(event: string, fn: Function, id?: number): Howl;
}

interface HowlOptions {
  src: string | string[];
  volume?: number;
  html5?: boolean;
  loop?: boolean;
  preload?: boolean | 'metadata';
  autoplay?: boolean;
  mute?: boolean;
  sprite?: AudioSprite;
  rate?: number;
  pool?: number;
  format?: string | string[];
  xhr?: XHROptions;
  onend?: () => void;
  onfade?: () => void;
  onload?: () => void;
  onloaderror?: (id: number, error: any) => void;
  onplayerror?: (id: number, error: any) => void;
  onpause?: () => void;
  onplay?: () => void;
  onstop?: () => void;
  onmute?: () => void;
  onvolume?: () => void;
  onrate?: () => void;
  onseek?: () => void;
  onunlock?: () => void;
}

Sound Loading and Playback

Spatial Audio

3D positional audio and stereo panning capabilities for creating immersive audio experiences with spatial positioning, orientation, and realistic audio attenuation.

// Global spatial audio methods
Howler.stereo(pan: number): Howler;
Howler.pos(x: number, y?: number, z?: number): Howler | number[];
Howler.orientation(x: number, y: number, z: number, xUp: number, yUp: number, zUp: number): Howler | number[];

// Per-sound spatial audio methods  
Howl.prototype.stereo(pan: number, id?: number): Howl | number;
Howl.prototype.pos(x: number, y?: number, z?: number, id?: number): Howl | number[];
Howl.prototype.orientation(x: number, y: number, z: number, id?: number): Howl | number[];
Howl.prototype.pannerAttr(o?: PannerAttributes, id?: number): Howl | PannerAttributes;

interface PannerAttributes {
  coneInnerAngle?: number;
  coneOuterAngle?: number;
  coneOuterGain?: number;
  distanceModel?: 'inverse' | 'linear' | 'exponential';
  maxDistance?: number;
  panningModel?: 'equalpower' | 'HRTF';
  refDistance?: number;
  rolloffFactor?: number;
}

Spatial Audio

Types

interface AudioSprite {
  [key: string]: [number, number] | [number, number, boolean];
}

interface XHROptions {
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
}

type HowlEvent = 'load' | 'loaderror' | 'play' | 'end' | 'pause' | 'stop' | 'mute' | 'volume' | 'rate' | 'seek' | 'fade' | 'playerror' | 'unlock';

type LoadState = 'unloaded' | 'loading' | 'loaded';

type AudioContext = AudioContext | webkitAudioContext;