audio-resumer

Note: Comments, documentation, and TypeScript types in this package were automatically generated by AI.

Automatic AudioContext management for Web Audio API. Handles browser autoplay policy and page visibility suspend/resume.

Features

• Autoplay policy bypass - Automatically unlocks AudioContext on user interaction
• Page visibility management - Suspends AudioContext when page is hidden, resumes when visible
• Zero dependencies - Uses only standard Web APIs
• TypeScript support - Full type definitions included
• Small size - Minimal footprint

Installation

npm install audio-resumer

Usage

import { AudioResumer } from 'audio-resumer';

// Create AudioContext
const audioContext = new AudioContext();

// Enable automatic AudioContext management
AudioResumer.create(audioContext);

// Now AudioContext will be automatically managed:
// - Unlocked on first user interaction
// - Suspended when page is hidden
// - Resumed when page becomes visible

What it solves

1. Browser Autoplay Policy

Modern browsers block autoplay audio without user interaction. AudioResumer creates an invisible empty audio element that unlocks AudioContext when the user first interacts with the page.

2. Resource Saving

When a page is hidden (tab switched, minimized), AudioContext continues running and consumes resources. AudioResumer automatically suspends AudioContext when the page is hidden and resumes it when the page becomes visible again.

API

AudioResumer

Static Method: create

AudioResumer.create(audioContext: AudioContext): AudioResumer

Creates and initializes AudioResumer for the given AudioContext. Starts managing the AudioContext automatically.

Parameters:

• audioContext - The AudioContext instance to manage

Returns:

• AudioResumer - The created AudioResumer instance (usually not needed to store)

Example:

const audioContext = new AudioContext();
AudioResumer.create(audioContext);

How it works

1. Autoplay unlock: Creates an invisible empty WAV file (data URI) and plays it on user interaction to unlock AudioContext
2. Visibility tracking: Listens to visibilitychange, pagehide, and pageshow events
3. Automatic suspend/resume: Suspends AudioContext when page is hidden, resumes when visible

Browser Support

Works in all modern browsers that support:

• Web Audio API
• Page Visibility API
• HTMLAudioElement

License

MIT