Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/evandrolg/ts-audio

:musical_score: ts-audio is an agnostic library that makes it easy to work with AudioContext and create audio playlists in the browser
https://github.com/evandrolg/ts-audio

audio audiocontext-api client-side song typescript

Last synced: 2 months ago
JSON representation

:musical_score: ts-audio is an agnostic library that makes it easy to work with AudioContext and create audio playlists in the browser

Awesome Lists containing this project

README 

          
# ts-audio · [![license](https://badgen.now.sh/badge/license/MIT)](./LICENSE) [![npm version](https://badgen.now.sh/npm/v/ts-audio)](https://www.npmjs.com/package/ts-audio)



`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



```bash

npm install ts-audio

```



```bash

yarn add ts-audio

```



```bash

pnpm add ts-audio

```



## 🚀 Quick Start



### Basic Audio Player



```typescript

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



```typescript

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



```typescript

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



```typescript

// 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



```typescript

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



```typescript

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



```typescript

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



```typescript

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



```typescript

// 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](https://codesandbox.io/s/ts-audio-audio-m54u5)

- [Audio Playlist](https://codesandbox.io/s/ts-audio-playlist-ovynj)



## 🐛 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](LICENSE) file for details.



## 🔗 Links



- [GitHub Repository](https://github.com/EvandroLG/ts-audio)

- [NPM Package](https://www.npmjs.com/package/ts-audio)

- [Issue Tracker](https://github.com/EvandroLG/ts-audio/issues)

- [Changelog](https://github.com/EvandroLG/ts-audio/releases)



---



Made with ❤️ by [EvandroLG](https://github.com/EvandroLG)