{"id":20502925,"url":"https://github.com/evandrolg/ts-audio","last_synced_at":"2026-01-04T22:13:42.516Z","repository":{"id":10247135,"uuid":"12353347","full_name":"EvandroLG/ts-audio","owner":"EvandroLG","description":":musical_score: ts-audio is an agnostic library that makes it easy to work with AudioContext and create audio playlists in the browser","archived":false,"fork":false,"pushed_at":"2025-05-01T03:50:01.000Z","size":12379,"stargazers_count":334,"open_issues_count":1,"forks_count":23,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-10T11:33:38.471Z","etag":null,"topics":["audio","audiocontext-api","client-side","song","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvandroLG.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-08-25T03:01:42.000Z","updated_at":"2025-05-07T14:36:04.000Z","dependencies_parsed_at":"2023-07-13T14:24:45.680Z","dependency_job_id":"f23e53ec-a122-4ecf-b3c2-bf04c86f4c76","html_url":"https://github.com/EvandroLG/ts-audio","commit_stats":{"total_commits":306,"total_committers":8,"mean_commits":38.25,"dds":"0.21568627450980393","last_synced_commit":"02a29fa2fb6f89fe83f8465bec0c85e39d08d18e"},"previous_names":["evandrolg/audiojs"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvandroLG%2Fts-audio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvandroLG%2Fts-audio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvandroLG%2Fts-audio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvandroLG%2Fts-audio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvandroLG","download_url":"https://codeload.github.com/EvandroLG/ts-audio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audiocontext-api","client-side","song","typescript"],"created_at":"2024-11-15T19:28:30.729Z","updated_at":"2026-01-04T22:13:42.511Z","avatar_url":"https://github.com/EvandroLG.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg alt=\"ts-audio\" src=\"https://github.com/EvandroLG/ts-audio/blob/master/.github/logo.svg?sanitize=true\" width=\"144\"\u003e \u0026middot; [![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)\n\n`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.\n\n## ✨ Features\n\n- **Simple API** - Abstracts the complexity of the Web Audio API\n- **Cross-browser support** - Works in all modern browsers\n- **Playlist management** - Create and manage audio playlists with advanced features\n- **TypeScript support** - Full type definitions included\n- **Zero dependencies** - Lightweight bundle\n- **Event-driven** - Built-in event system for audio state changes\n- **Advanced controls** - Volume, time, loop, shuffle, and more\n- **Preloading support** - Optimize performance with audio preloading\n\n## 📦 Installation\n\n```bash\nnpm install ts-audio\n```\n\n```bash\nyarn add ts-audio\n```\n\n```bash\npnpm add ts-audio\n```\n\n## 🚀 Quick Start\n\n### Basic Audio Player\n\n```typescript\nimport { Audio } from 'ts-audio';\n\nconst audio = Audio({\n  file: './song.mp3',\n  volume: 0.5,\n  loop: true,\n  preload: true\n});\n\n// Play the audio\naudio.play();\n\n// Pause\naudio.pause();\n\n// Stop and reset\naudio.stop();\n```\n\n### Audio Playlist\n\n```typescript\nimport { AudioPlaylist } from 'ts-audio';\n\nconst playlist = AudioPlaylist({\n  files: ['./song1.mp3', './song2.mp3', './song3.mp3'],\n  volume: 0.7,\n  shuffle: true,\n  loop: true\n});\n\n// Start the playlist\nplaylist.play();\n\n// Next track\nplaylist.next();\n\n// Previous track\nplaylist.previous();\n```\n\n## 📚 API Reference\n\n### Audio Component\n\nThe `Audio` component provides control over a single audio file with full playback controls.\n\n#### Configuration Options\n\n```typescript\ntype AudioConfig = {\n  file: string;           // Path or URL to the audio file\n  volume?: number;        // Initial volume (0-1, default: 1)\n  time?: number;          // Start time in seconds (default: 0)\n  autoPlay?: boolean;     // Auto-play on creation (default: false)\n  loop?: boolean;         // Loop the audio (default: false)\n  preload?: boolean;      // Preload the audio file (default: false)\n}\n```\n\n#### Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `duration` | `number` | Total duration in seconds |\n| `currentTime` | `number` | Current playback position in seconds |\n| `volume` | `number` | Current volume level (0-1) |\n| `loop` | `boolean` | Whether audio is looping |\n| `isPlaying` | `boolean` | Current playback state |\n\n#### Methods\n\n| Method | Description |\n|--------|-------------|\n| `play()` | Start or resume playback |\n| `pause()` | Pause playback |\n| `stop()` | Stop playback and reset to beginning |\n| `toggle()` | Toggle between play/pause |\n| `seek(time: number)` | Seek to specific time in seconds |\n| `destroy()` | Clean up resources and remove all event listeners |\n\n#### Events\n\n```typescript\n// Listen to audio events\naudio.on('ready', (data) =\u003e console.log('Audio loaded:', data));\naudio.on('start', () =\u003e console.log('Playback started'));\naudio.on('state', (data) =\u003e console.log('State changed:', data));\naudio.on('end', () =\u003e console.log('Playback ended'));\n```\n\n### AudioPlaylist Component\n\nThe `AudioPlaylist` component manages multiple audio files with advanced playlist features.\n\n#### Configuration Options\n\n```typescript\ntype AudioPlaylistConfig = {\n  files: string[] | { [key: string]: number };  // Array of files or weighted object\n  volume?: number;        // Initial volume (0-1, default: 1)\n  loop?: boolean;         // Loop the playlist (default: false)\n  shuffle?: boolean;      // Shuffle playback order (default: false)\n  preload?: boolean;      // Preload audio files (default: false)\n  preloadLimit?: number;  // Number of files to preload (default: 3)\n}\n```\n\n#### Methods\n\n| Method | Description |\n|--------|-------------|\n| `play()` | Start or resume playlist |\n| `pause()` | Pause playlist |\n| `stop()` | Stop playlist and reset |\n| `next()` | Play next track |\n| `previous()` | Play previous track |\n| `shuffle()` | Shuffle remaining tracks |\n| `destroy()` | Clean up resources and remove all event listeners |\n\n## 🎯 Advanced Examples\n\n### Weighted Random Playlist\n\n```typescript\nconst weightedPlaylist = AudioPlaylist({\n  files: {\n    './popular-song.mp3': 0.6,    // 60% chance\n    './regular-song.mp3': 0.3,    // 30% chance\n    './rare-song.mp3': 0.1        // 10% chance\n  },\n  shuffle: true\n});\n```\n\n### Audio with Event Handling\n\n```typescript\nconst audio = Audio({\n  file: './background-music.mp3',\n  volume: 0.3,\n  loop: true\n});\n\naudio.on('ready', () =\u003e {\n  console.log('Background music loaded');\n  audio.play();\n});\n\naudio.on('end', () =\u003e {\n  console.log('Track finished, looping...');\n});\n```\n\n### Interactive Audio Controls\n\n```typescript\nconst audio = Audio({\n  file: './song.mp3',\n  preload: true\n});\n\n// Volume control\ndocument.getElementById('volume-slider').addEventListener('input', (e) =\u003e {\n  audio.volume = e.target.value / 100;\n});\n\n// Time seeking\ndocument.getElementById('time-slider').addEventListener('change', (e) =\u003e {\n  const percent = e.target.value / 100;\n  audio.currentTime = audio.duration * percent;\n});\n\n// Play/pause toggle\ndocument.getElementById('play-button').addEventListener('click', () =\u003e {\n  audio.toggle();\n});\n```\n\n### Resource Management and Cleanup\n\n```typescript\n// Create audio instance\nconst audio = Audio({\n  file: './background-music.mp3',\n  volume: 0.5,\n  loop: true\n});\n\naudio.play();\n\n// When done or component unmounts (e.g., in React useEffect cleanup)\n// Always call destroy to prevent memory leaks\naudio.destroy();\n\n// For playlists\nconst playlist = AudioPlaylist({\n  files: ['./song1.mp3', './song2.mp3', './song3.mp3'],\n  preload: true\n});\n\nplaylist.play();\n\n// Clean up playlist resources when done\nplaylist.destroy();\n\n// Example in React component\nimport { useEffect } from 'react';\nimport { Audio } from 'ts-audio';\n\nfunction MusicPlayer() {\n  useEffect(() =\u003e {\n    const audio = Audio({\n      file: './song.mp3',\n      autoPlay: true\n    });\n\n    // Cleanup function\n    return () =\u003e {\n      audio.destroy();\n    };\n  }, []);\n\n  return \u003cdiv\u003ePlaying music...\u003c/div\u003e;\n}\n```\n\n## 🔧 Browser Compatibility\n\n- Chrome 14+\n- Firefox 23+\n- Safari 6+\n- Edge 12+\n- Opera 15+\n\n## 📖 Demo Projects\n\n- [Basic Audio Player](https://codesandbox.io/s/ts-audio-audio-m54u5)\n- [Audio Playlist](https://codesandbox.io/s/ts-audio-playlist-ovynj)\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Audio won't play:**\n- Ensure user interaction before calling `play()` (browser autoplay policy)\n- Check if audio file path is correct\n- Verify audio file format is supported (MP3, WAV, OGG, etc.)\n\n**Volume not working:**\n- Volume range is 0-1 (0 = muted, 1 = full volume)\n- Check if volume is being set after audio is loaded\n\n**Events not firing:**\n- Ensure event listeners are attached before calling `play()`\n- Check browser console for errors\n\n**Memory leaks:**\n- Always call `destroy()` when done with an Audio or AudioPlaylist instance\n- Particularly important in single-page applications (SPA) and React components\n- Call `destroy()` in component cleanup/unmount lifecycle methods\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [GitHub Repository](https://github.com/EvandroLG/ts-audio)\n- [NPM Package](https://www.npmjs.com/package/ts-audio)\n- [Issue Tracker](https://github.com/EvandroLG/ts-audio/issues)\n- [Changelog](https://github.com/EvandroLG/ts-audio/releases)\n\n---\n\nMade with ❤️ by [EvandroLG](https://github.com/EvandroLG)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevandrolg%2Fts-audio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevandrolg%2Fts-audio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevandrolg%2Fts-audio/lists"}