audiotoolheadless
A modern, headless audio player with HLS support, equalizer, queue management, and media session integration
A modern, lightweight TypeScript audio player library that provides universal HLS support, built-in equalizer, queue management, and media session integration across all browsers.
- MP3 (.mp3) → Supported in all major browsers
- AAC (.aac, .m4a, .mp4) → Supported in all major browsers
- WAV (.wav) → Supported everywhere, but large file sizes
- OGG Vorbis (.ogg) → Supported by Chrome/Firefox/Edge, not always Safari
- Opus (.opus) → Supported in Chrome/Firefox/Edge; Safari has partial support
- Safari (macOS + iOS) → Native HLS support in audio object
- Chrome/Firefox/Edge → No native HLS support, uses hls.js wrapper
- 🎵 Universal HLS Support - Seamless streaming across all browsers using hls.js
- 🎛️ Built-in Equalizer - 10-band EQ with presets and bass boost controls
- 📱 Media Session API - Native OS-level media controls and notifications
- 🔄 Advanced Queue Management - Smart playlist handling with shuffle, loop modes, and navigation
- ⚡ Variable Playback Rates - Smooth speed control from 1x to 3x
- 📊 Reactive State Management - Observable state system with custom event emission
- 🎯 Modern Architecture - Clean, modular design with absolute imports
- ✨ TypeScript First - Complete type safety with intelligent IntelliSense
- 📦 Universal Package - Works seamlessly with ESM and CommonJS
- 🔧 Zero Config - Smart defaults with extensive customization options
- 🧪 Production Ready - Comprehensive error handling and edge case coverage
npm install audiotoolheadless
# or
pnpm add audiotoolheadless
# or
yarn add audiotoolheadless
import { AudioHeadless, type MediaTrack, type PlayerConfiguration } from 'audiotoolheadless';
// Create audio player instance
const player = new AudioHeadless();
// Initialize with configuration
const config: PlayerConfiguration = {
mode: 'VANILLA',
useDefaultEventListeners: true,
enableHls: true, // Enable HLS streaming support
enableEqualizer: true, // Enable 10-band equalizer
showNotificationActions: true, // OS-level media controls
autoPlay: false,
preloadStrategy: 'auto',
crossOrigin: 'anonymous'
};
await player.initialize(config);
// Create a media track
const track: MediaTrack = {
id: '1',
title: 'My Song',
source: 'https://example.com/audio.mp3',
artist: 'Artist Name',
album: 'Album Name',
artwork: [{ src: 'https://example.com/artwork.jpg' }]
};
// Load and play audio
await player.loadTrack(track);
await player.play();
// HLS streaming (works on all browsers)
const hlsTrack: MediaTrack = {
id: '2',
title: 'Live Stream',
source: 'https://example.com/stream.m3u8',
artist: 'Live Artist',
artwork: null
};
await player.loadAndPlay(hlsTrack);
// State management
player.onStateChange((state) => {
console.log('Player state:', state.playbackState);
console.log('Current track:', state.currentTrack?.title);
});
// Playback controls
player.pause();
player.setVolume(75); // 0-100
player.seekToTime(30); // Seek to 30 seconds
player.setPlaybackRate(1.5); // 1.5x speed
// Queue management
const playlist = [track, hlsTrack];
player.setQueue(playlist);
player.playNext();
player.enableShuffle(true);
player.setLoopMode('QUEUE');
// Equalizer controls
player.setEqualizerPreset('ROCK');
player.setCustomEqualizer([1, 2, 0, -1, 3, 0, 2, 1, 0, -1]);
const { AudioHeadless } = require('audiotoolheadless');
const player = new AudioHeadless();
// Initialize and play
player.initialize({
mode: 'VANILLA',
useDefaultEventListeners: true,
enableHls: true,
enableEqualizer: true
}).then(() => {
const track = {
id: '1',
title: 'My Song',
source: 'https://example.com/audio.mp3',
artist: 'Artist Name',
artwork: null
};
return player.loadAndPlay(track);
}).then(() => {
console.log('Audio playing successfully');
});
The main audio player class that provides universal audio format support with HLS streaming capabilities, queue management, equalizer, and media session integration.
class AudioHeadless {
constructor();
// Core lifecycle methods
initialize(config: PlayerConfiguration): Promise<void>;
destroy(): Promise<void>;
reset(): Promise<void>;
// Media loading and playback
loadTrack(track: MediaTrack, fetchFn?: (track: MediaTrack) => Promise<void>): Promise<void>;
loadAndPlay(track: MediaTrack, fetchFn?: (track: MediaTrack) => Promise<void>): Promise<void>;
play(): Promise<void>;
pause(): void;
stop(): void;
// Playback controls
setVolume(volume: number): void; // 0-100
getVolume(): number;
setPlaybackRate(rate: PlaybackRate): void;
getPlaybackRate(): PlaybackRate;
seekToTime(seconds: number): void;
seekByTime(seconds: number): void;
mute(): void;
unmute(): void;
isMuted(): boolean;
// Queue management
setQueue(tracks: MediaTrack[], playbackType?: QueuePlaybackType): void;
addToQueue(tracks: MediaTrack | MediaTrack[]): void;
removeFromQueue(trackId: string): void;
clearQueue(): void;
getQueue(): MediaTrack[];
getCurrentTrackIndex(): number;
playNext(): void;
playPrevious(): void;
playTrackAt(index: number): void;
// Shuffle and Loop controls
enableShuffle(enabled: boolean): void;
isShuffleEnabled(): boolean;
setLoopMode(mode: LoopMode): void;
getLoopMode(): LoopMode;
// Equalizer controls
initializeEqualizer(): void;
getEqualizerPresets(): EqualizerPresets;
setEqualizerPreset(presetName: keyof EqualizerPresets): void;
setCustomEqualizer(gains: number[]): void;
enableBassBoost(enabled: boolean, boost?: number): void;
getEqualizerState(): EqualizerStatus;
// State and event handling
onStateChange(callback: (state: PlayerState) => void): () => void;
getCurrentState(): PlayerState;
addEventListener(event: keyof HTMLMediaElementEventMap, callback: EventListener): void;
removeEventListener(event: keyof HTMLMediaElementEventMap, callback: EventListener): void;
// Static utilities
static getInstance(): AudioHeadless;
static getAudioElement(): HTMLAudioElement;
}
Configuration object for initializing the AudioHeadless player.
interface PlayerConfiguration {
mode: InitMode; // 'REACT' | 'VANILLA'
useDefaultEventListeners: boolean;
showNotificationActions?: boolean;
preloadStrategy?: PreloadStrategy; // 'none' | 'metadata' | 'auto'
playbackRate?: PlaybackRate;
customEventListeners?: EventCallbackMap | null;
autoPlay?: boolean;
enablePlayLog?: boolean;
enableHls?: boolean; // Enable HLS streaming support
enableEqualizer?: boolean; // Enable 10-band equalizer
crossOrigin?: CrossOriginValue; // 'anonymous' | 'use-credentials' | null
hlsConfig?: HlsConfig; // HLS.js configuration options
}
Represents an audio track with metadata.
interface MediaTrack {
id: string;
title: string;
source: string; // URL to audio file or HLS stream (.m3u8)
artwork: MediaArtwork[] | null;
duration?: number;
genre?: string;
album?: string;
comment?: string;
year?: number | string;
artist?: string;
}
interface MediaArtwork {
src: string;
name?: string;
sizes?: string;
}
Initialize the AudioHeadless instance with configuration options.
Required before any playback operations.
Load a media track. Automatically detects HLS streams (.m3u8) and uses hls.js for browsers without native HLS support.
Convenience method that loads and immediately plays a media track.
Start audio playback. Media must be loaded first.
Set playback volume.
Parameters:
-
volume
- Volume level between 0 (muted) and 100 (full volume)
Set playback speed.
Parameters:
-
playbackRate
- Speed multiplier:1.0 | 1.25 | 1.5 | 1.75 | 2.0 | 2.5 | 3.0
Set the playback queue.
Parameters:
-
queue
- Array of media tracks -
playbackType
-'DEFAULT' | 'REVERSE' | 'SHUFFLE'
Navigate through the queue.
Apply a preset equalizer setting.
Apply custom equalizer gains.
Subscribe to events using the subscribe()
method:
const unsubscribe = audioPlayer.subscribe('AUDIO_STATE', (state) => {
console.log('State changed:', state.playbackState);
});
// Unsubscribe when done
unsubscribe();
Available Events:
-
AUDIO_STATE
- Audio state changes (play, pause, track change, etc.) - Standard HTML5 audio events via
addEventListener()
- Node.js 16+
- pnpm (recommended)
# Clone the repository
git clone <repository-url>
cd audioToolHeadless
# Install dependencies
pnpm install
# Install git hooks
pnpm run prepare
# Development
pnpm run dev # Watch mode with auto-rebuild
pnpm run build # Build for production
pnpm run typecheck # Type checking only
# Code Quality
pnpm run lint # Lint code
pnpm run lint:fix # Lint and auto-fix
pnpm run format # Format code
# Documentation
pnpm run docs # Generate documentation
pnpm run docs:clean # Clean docs folder
# Testing
pnpm run test # Run tests
# Release
pnpm run release:patch # Patch release (0.0.1 -> 0.0.2)
pnpm run release:minor # Minor release (0.0.1 -> 0.1.0)
pnpm run release:major # Major release (0.0.1 -> 1.0.0)
audioToolHeadless/
├── src/
│ └── index.ts # Main source file
├── dist/ # Built files
│ ├── index.js # ESM build
│ ├── index.cjs # CommonJS build
│ └── index.d.ts # Type definitions
├── docs/ # Generated documentation
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
├── tsup.config.ts # Build configuration
├── typedoc.json # Documentation configuration
└── README.md # This file
- Fork the repository
- Create a feature branch:
git checkout -b feat/amazing-feature
- Make your changes
- Commit using conventional commits:
git commit -m "feat: add amazing feature"
- Push to the branch:
git push origin feat/amazing-feature
- Open a Pull Request
This project uses Conventional Commits:
-
feat:
- New features -
fix:
- Bug fixes -
docs:
- Documentation changes -
style:
- Code style changes -
refactor:
- Code refactoring -
test:
- Adding tests -
chore:
- Maintenance tasks
ISC License - see the LICENSE file for details.
See CHANGELOG.md for version history.