@awesome-web-projects/audio-engine

Framework-agnostic audio engine powered by the Web Audio API. Provides streaming audio loading, playlist management, playback control, and visualization data — no rendering library required.

Features

• Web Audio API playback with AudioContext, AnalyserNode, and GainNode
• Streaming audio loading via ReadableStream with XHR fallback
• Web Worker support for background audio fetching
• Partial loading — starts playing in seconds, preloads the full song in the background
• Built-in playlist management (next, previous, go-to)
• Event-driven PlayerController that orchestrates everything
• Frequency data access for building custom visualizers
• Zero runtime dependencies
• Full TypeScript support with exported types
• Works with any framework (React, Vue, Svelte, Web Components, vanilla JS)

Installation

npm install @awesome-web-projects/audio-engine

Quick Start

import { PlayerController } from '@awesome-web-projects/audio-engine';

const player = new PlayerController({
  tracks: [
    { name: 'Song One', artist: 'Artist A', url: '/songs/one.mp3' },
    { name: 'Song Two', artist: 'Artist B', url: '/songs/two.mp3' },
  ],
  thread: 'worker',
  initialVolume: 0.5,
});

// Listen to events
player.on('play', () => console.log('Playing'));
player.on('pause', () => console.log('Paused'));
player.on('trackchange', (track, index) => console.log(`Now playing: ${track.name}`));
player.on('timeupdate', (currentTime, duration) => {
  console.log(`${currentTime.toFixed(1)}s / ${duration.toFixed(1)}s`);
});

// Control playback
player.play();
player.pause();
player.togglePlay();
player.next();
player.prev();
player.seek(0.5);       // seek to 50%
player.setVolume(0.8);  // 0-1

// Access state
console.log(player.isPlaying);
console.log(player.currentTrack);
console.log(player.progress);

// Visualization data
const analyser = player.analyserNode;
const freqData = player.frequencyData;

// Clean up
player.dispose();

API

PlayerController

The main class that orchestrates the audio engine, playlist, and loader.

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | tracks | Track[] | required | Array of tracks to play | | thread | 'main' \| 'worker' | 'worker' | Audio fetching strategy | | initialVolume | number | 0.5 | Initial volume (0-1) | | autoPlay | boolean | false | Start playing immediately | | workerURL | URL \| string | — | Custom worker URL for cross-package bundling |

Methods

| Method | Description | |--------|-------------| | play() | Start or resume playback | | pause() | Pause playback | | togglePlay() | Toggle play/pause | | seek(progress) | Seek to position (0-1) | | setVolume(value) | Set volume (0-1) | | next() | Skip to next track | | prev() | Go to previous track | | goTo(index) | Jump to track by index | | setTracks(tracks) | Replace the playlist | | dispose() | Clean up all resources |

State Getters

| Getter | Type | Description | |--------|------|-------------| | isPlaying | boolean | Whether audio is currently playing | | isLoading | boolean | Whether a track is being loaded | | isReady | boolean | Whether the engine is initialized | | isFullSong | boolean | Whether the full song has been loaded | | volume | number | Current volume (0-1) | | currentTime | number | Current playback time in seconds | | duration | number | Total duration in seconds | | progress | number | Playback progress (0-1) | | currentTrack | Track | Currently active track | | currentIndex | number | Index of current track | | tracks | Track[] | All tracks in the playlist | | analyserNode | AnalyserNode \| null | Web Audio analyser for visualization | | frequencyData | Uint8Array \| null | Current frequency data |

Events

| Event | Payload | Description | |-------|---------|-------------| | play | — | Playback started or resumed | | pause | — | Playback paused | | timeupdate | (currentTime, duration) | Playback time changed | | trackchange | (track, index) | Active track changed | | loading | (isLoading) | Loading state changed | | ended | — | Current track finished | | volumechange | (volume) | Volume changed | | fullsongloaded | — | Full song buffer loaded | | ready | — | Engine initialized |

AudioEngine

Low-level Web Audio API wrapper. Use PlayerController unless you need direct control.

Playlist

Standalone playlist class with next(), prev(), goTo(), and onChange callback.

Utilities

| Export | Description | |--------|-------------| | formatTime(seconds) | Formats seconds to m:ss string | | fetchAudioStream(url) | Streams audio via ReadableStream | | fetchAudioXHR(url) | Fetches audio via XHR (fallback) | | hasStreamSupport | Whether the browser supports streaming | | EventEmitter | Generic typed event emitter |

Types

interface Track {
  name: string;
  artist: string;
  url: string;
}

Related Packages

• @awesome-web-projects/react-player — React components built on this engine
• @awesome-web-projects/music-player — Web Components built on this engine

Development

npm install
npm run build        # Build library
npm run dev          # Build in watch mode
npm run typecheck    # Type check

License

MIT