· [](./LICENSE) [](https://www.npmjs.com/package/ts-audio)

January 17, 2026 · View on GitHub

ts-audio is a lightweight, agnostic, and easy-to-use TypeScript/JavaScript library that simplifies working with the Web Audio API (AudioContext) and provides powerful playlist management capabilities.

✨ Features

Simple API - Abstracts the complexity of the Web Audio API
Cross-browser support - Works in all modern browsers
Playlist management - Create and manage audio playlists with advanced features
TypeScript support - Full type definitions included
Zero dependencies - Lightweight bundle
Event-driven - Built-in event system for audio state changes
Advanced controls - Volume, time, loop, shuffle, and more
Preloading support - Optimize performance with audio preloading

📦 Installation

npm install ts-audio

yarn add ts-audio

pnpm add ts-audio

bun add ts-audio

🚀 Quick Start

Basic Audio Player

import { Audio } from 'ts-audio'

const audio = Audio({
  file: './song.mp3',
  volume: 0.5,
  loop: true,
  preload: true,
})

// Play the audio
audio.play()

// Pause
audio.pause()

// Stop and reset
audio.stop()

Audio Playlist

import { AudioPlaylist } from 'ts-audio'

const playlist = AudioPlaylist({
  files: ['./song1.mp3', './song2.mp3', './song3.mp3'],
  volume: 0.7,
  shuffle: true,
  loop: true,
})

// Start the playlist
playlist.play()

// Next track
playlist.next()

// Previous track
playlist.previous()

📚 API Reference

Audio Component

The Audio component provides control over a single audio file with full playback controls.

Configuration Options

type AudioConfig = {
  file: string // Path or URL to the audio file
  volume?: number // Initial volume (0-1, default: 1)
  time?: number // Start time in seconds (default: 0)
  autoPlay?: boolean // Auto-play on creation (default: false)
  loop?: boolean // Loop the audio (default: false)
  preload?: boolean // Preload the audio file (default: false)
}

Properties

Property	Type	Description
`duration`	`number`	Total duration in seconds
`currentTime`	`number`	Current playback position in seconds
`volume`	`number`	Current volume level (0-1)
`loop`	`boolean`	Whether audio is looping
`isPlaying`	`boolean`	Current playback state

Methods

Method	Description
`play()`	Start or resume playback
`pause()`	Pause playback
`stop()`	Stop playback and reset to beginning
`toggle()`	Toggle between play/pause
`seek(time: number)`	Seek to specific time in seconds
`destroy()`	Clean up resources and remove all event listeners

Events

// Listen to audio events
audio.on('ready', (data) => console.log('Audio loaded:', data))
audio.on('start', () => console.log('Playback started'))
audio.on('state', (data) => console.log('State changed:', data))
audio.on('end', () => console.log('Playback ended'))

AudioPlaylist Component

The AudioPlaylist component manages multiple audio files with advanced playlist features.

Configuration Options

type AudioPlaylistConfig = {
  files: string[] | { [key: string]: number } // Array of files or weighted object
  volume?: number // Initial volume (0-1, default: 1)
  loop?: boolean // Loop the playlist (default: false)
  shuffle?: boolean // Shuffle playback order (default: false)
  preload?: boolean // Preload audio files (default: false)
  preloadLimit?: number // Number of files to preload (default: 3)
}

Methods

Method	Description
`play()`	Start or resume playlist
`pause()`	Pause playlist
`stop()`	Stop playlist and reset
`next()`	Play next track
`previous()`	Play previous track
`shuffle()`	Shuffle remaining tracks
`destroy()`	Clean up resources and remove all event listeners

🎯 Advanced Examples

Weighted Random Playlist

const weightedPlaylist = AudioPlaylist({
  files: {
    './popular-song.mp3': 0.6, // 60% chance
    './regular-song.mp3': 0.3, // 30% chance
    './rare-song.mp3': 0.1, // 10% chance
  },
  shuffle: true,
})

Audio with Event Handling

const audio = Audio({
  file: './background-music.mp3',
  volume: 0.3,
  loop: true,
})

audio.on('ready', () => {
  console.log('Background music loaded')
  audio.play()
})

audio.on('end', () => {
  console.log('Track finished, looping...')
})

Interactive Audio Controls

const audio = Audio({
  file: './song.mp3',
  preload: true,
})

// Volume control
document.getElementById('volume-slider').addEventListener('input', (e) => {
  audio.volume = e.target.value / 100
})

// Time seeking
document.getElementById('time-slider').addEventListener('change', (e) => {
  const percent = e.target.value / 100
  audio.currentTime = audio.duration * percent
})

// Play/pause toggle
document.getElementById('play-button').addEventListener('click', () => {
  audio.toggle()
})

Resource Management and Cleanup

// Create audio instance
const audio = Audio({
  file: './background-music.mp3',
  volume: 0.5,
  loop: true
});

audio.play();

// When done or component unmounts (e.g., in React useEffect cleanup)
// Always call destroy to prevent memory leaks
audio.destroy();

// For playlists
const playlist = AudioPlaylist({
  files: ['./song1.mp3', './song2.mp3', './song3.mp3'],
  preload: true
});

playlist.play();

// Clean up playlist resources when done
playlist.destroy();

// Example in React component
import { useEffect } from 'react';
import { Audio } from 'ts-audio';

function MusicPlayer() {
  useEffect(() => {
    const audio = Audio({
      file: './song.mp3',
      autoPlay: true
    });

    // Cleanup function
    return () => {
      audio.destroy();
    };
  }, []);

  return <div>Playing music...</div>;
}