@sonardigital/audio-notifier

A React package for safely using howler.js for audio notifications with context and hooks.

Features

• 🔊 Safe wrapper around howler.js
• 🎵 Register and manage multiple sounds
• 🔇 Global mute/unmute control
• 🎚️ Global and per-sound volume control
• 📊 Sound status tracking (loading, playing, paused, stopped, error)
• ⚛️ React Context + Hook pattern
• 🧹 Automatic cleanup on unmount

Installation

npm install @sonardigital/audio-notifier howler

Usage

With Provider (Recommended)

import { AudioNotifierProvider, useAudioNotifierContext } from '@sonardigital/audio-notifier';

// Wrap your app
function App() {
	return (
		<AudioNotifierProvider initialVolume={0.8} initialMuted={false}>
			<YourApp />
		</AudioNotifierProvider>
	);
}

// Use in any component
function NotificationButton() {
	const { registerSound, play, isMuted, setMuted } = useAudioNotifierContext();

	useEffect(() => {
		registerSound('notification', '/sounds/notification.mp3');
		registerSound('success', '/sounds/success.mp3', { volume: 0.5 });
	}, [registerSound]);

	return (
		<div>
			<button onClick={() => play('notification')}>Play Notification</button>
			<button onClick={() => play('success')}>Play Success</button>
			<button onClick={() => setMuted(!isMuted)}>{isMuted ? 'Unmute' : 'Mute'}</button>
		</div>
	);
}

Standalone Hook

import { useAudioNotifier } from '@sonardigital/audio-notifier';

function MyComponent() {
	const {
		registerSound,
		unregisterSound,
		play,
		pause,
		stop,
		isMuted,
		setMuted,
		volume,
		setVolume,
		getSoundStatus,
		isPlaying,
	} = useAudioNotifier({ initialVolume: 1, initialMuted: false });

	useEffect(() => {
		registerSound('alert', ['/sounds/alert.mp3', '/sounds/alert.ogg']);
		return () => unregisterSound('alert');
	}, []);

	return (
		<div>
			<button onClick={() => play('alert')}>Play Alert</button>
			<button onClick={() => stop('alert')}>Stop</button>
			<input
				type="range"
				min="0"
				max="1"
				step="0.1"
				value={volume}
				onChange={(e) => setVolume(Number(e.target.value))}
			/>
		</div>
	);
}

API

AudioNotifierContextType

| Property | Type | Description | | ----------------- | ------------------------------------------ | ------------------------------- | | sounds | Map<string, AudioSound> | Map of registered sounds | | isMuted | boolean | Whether audio is globally muted | | volume | number | Global volume (0-1) | | play | (soundId: string) => number \| null | Play a sound by ID | | pause | (soundId: string) => void | Pause a sound by ID | | stop | (soundId: string) => void | Stop a sound by ID | | registerSound | (id, src, options?) => void | Register a new sound | | unregisterSound | (id: string) => void | Unregister a sound | | setMuted | (muted: boolean) => void | Set global mute state | | setVolume | (volume: number) => void | Set global volume | | getSoundStatus | (soundId: string) => AudioStatus \| null | Get sound status | | isPlaying | (soundId: string) => boolean | Check if sound is playing |

HowlOptions

| Option | Type | Default | Description | | --------- | ----------------------- | ------- | ----------------------- | | volume | number | 1 | Volume (0-1) | | loop | boolean | false | Whether to loop | | rate | number | 1 | Playback rate (0.5-4) | | preload | boolean \| 'metadata' | true | Whether to preload | | html5 | boolean | false | Use HTML5 Audio | | sprite | object | - | Audio sprite definition |

AudioStatus

'idle' | 'loading' | 'playing' | 'paused' | 'stopped' | 'error'

Provider Props

| Prop | Type | Default | Description | | --------------- | --------- | ------- | --------------------------- | | initialVolume | number | 1 | Initial global volume (0-1) | | initialMuted | boolean | false | Initial muted state |

Browser Support

Howler.js supports all modern browsers and handles codec fallbacks automatically. Provide multiple audio formats for best compatibility.