·

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 

Playing music...

;
}

🔧 Browser Compatibility

• Chrome 14+
• Firefox 23+
• Safari 6+
• Edge 12+
• Opera 15+

📖 Demo Projects

• Basic Audio Player
• Audio Playlist

🐛 Troubleshooting

Common Issues

Audio won't play:

• Ensure user interaction before calling play() (browser autoplay policy)
• Check if audio file path is correct
• Verify audio file format is supported (MP3, WAV, OGG, etc.)

Volume not working:

• Volume range is 0-1 (0 = muted, 1 = full volume)
• Check if volume is being set after audio is loaded

Events not firing:

• Ensure event listeners are attached before calling play()
• Check browser console for errors

Memory leaks:

• Always call destroy() when done with an Audio or AudioPlaylist instance
• Particularly important in single-page applications (SPA) and React components
• Call destroy() in component cleanup/unmount lifecycle methods

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• NPM Package
• Issue Tracker
• Changelog

---

Made with ❤️ by EvandroLG