npm - @students-dev/audify-js - Versions diffs - 1.0.0 → 1.0.2 - Mend

@students-dev/audify-js 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

package/LICENSE +21 -0
package/README.md +93 -310
package/dist/AudioEngine.js +232 -0
package/dist/cjs/index.js +1497 -1392
package/dist/cjs/index.js.map +1 -1
package/dist/constants/index.js +35 -0
package/dist/engine/Filters.js +137 -0
package/dist/engine/MockAudioContext.js +53 -0
package/dist/engine/Player.js +209 -0
package/dist/esm/index.js +1490 -1389
package/dist/esm/index.js.map +1 -1
package/dist/events/EventBus.js +61 -0
package/dist/index.js +18 -0
package/dist/interfaces/index.js +1 -0
package/dist/plugins/Plugin.js +27 -0
package/dist/plugins/PluginManager.js +106 -0
package/dist/providers/LavalinkProvider.js +81 -0
package/dist/providers/LocalProvider.js +70 -0
package/dist/providers/ProviderRegistry.js +20 -0
package/dist/providers/SpotifyProvider.js +59 -0
package/dist/providers/YouTubeProvider.js +48 -0
package/dist/queue/Queue.js +186 -0
package/dist/queue/Track.js +54 -0
package/dist/types/AudioEngine.d.ts +107 -0
package/dist/types/constants/index.d.ts +39 -0
package/dist/types/engine/AudioEngine.d.ts +44 -1
package/dist/types/engine/Filters.d.ts +25 -24
package/dist/types/engine/MockAudioContext.d.ts +43 -0
package/dist/types/engine/Player.d.ts +25 -21
package/dist/types/events/EventBus.d.ts +17 -15
package/dist/types/index.d.ts +17 -13
package/dist/types/interfaces/index.d.ts +31 -0
package/dist/types/plugins/Plugin.d.ts +11 -43
package/dist/types/plugins/PluginManager.d.ts +19 -19
package/dist/types/providers/LavalinkProvider.d.ts +17 -0
package/dist/types/providers/LocalProvider.d.ts +11 -22
package/dist/types/providers/ProviderRegistry.d.ts +10 -0
package/dist/types/providers/SpotifyProvider.d.ts +14 -0
package/dist/types/providers/YouTubeProvider.d.ts +11 -28
package/dist/types/queue/Queue.d.ts +28 -22
package/dist/types/queue/Track.d.ts +18 -16
package/dist/types/utils/Logger.d.ts +12 -16
package/dist/types/utils/Metadata.d.ts +16 -15
package/dist/types/utils/Probe.d.ts +7 -7
package/dist/types/utils/Time.d.ts +9 -9
package/dist/utils/Logger.js +59 -0
package/dist/utils/Metadata.js +90 -0
package/dist/utils/Probe.js +59 -0
package/dist/utils/Time.js +54 -0
package/package.json +19 -9

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 @students-dev/audify-js
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,19 +1,38 @@
-# audify-js
+# audify-js v1.0.2
 [![npm version](https://badge.fury.io/js/%40students-dev%2Faudify-js.svg)](https://badge.fury.io/js/%40students-dev%2Faudify-js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 A lightweight, modern, modular audio engine that provides playback, filters, queue management, events, and extensibility through plugins. Works in both **Node.js** and **browser** environments.
+**Version 1.0.2** represents a major stability and architecture enhancement, introducing a standardized provider system, robust plugin lifecycle, and full TypeScript support.
 ## Features
-- 🎵 **Unified Audio Engine**: Cross-environment abstraction using Web Audio API
-- 📋 **Queue Management**: Add, remove, shuffle, jump, and loop modes
-- 🎛️ **Audio Filters**: Bassboost, nightcore, vaporwave, 8D rotate, pitch/speed adjustment, reverb
-- 🔌 **Plugin System**: Extensible architecture with lifecycle hooks
-- 📡 **Event-Driven**: Comprehensive event system for all operations
-- 🌐 **Multi-Source Support**: Local files, remote URLs, YouTube, SoundCloud
-- 🛠️ **Developer-Friendly**: TypeScript declarations, ESM/CJS builds
+- 🎵 **Unified Audio Engine**: Cross-environment abstraction using Web Audio API.
+- 📋 **Advanced Queue Management**: Add, remove, shuffle, jump, loop (track/queue) modes.
+- 🎛️ **Audio Filters**: Bassboost, nightcore, vaporwave, 8D rotate, pitch/speed adjustment, reverb.
+- 🔌 **Robust Plugin System**: Extensible architecture with safe lifecycle hooks and error isolation.
+- 📡 **Event-Driven**: Comprehensive event system for all operations.
+- 🌐 **Provider Registry**: Standardized interface for providers (Local, YouTube, Spotify, Lavalink).
+- 🛠️ **Developer-Friendly**: Full TypeScript support, strict typings, and ESM/CJS builds.
+## Architecture Overview
+Audify-js v1.0.2 uses a modular architecture:
+- **AudioEngine**: The central controller orchestrating playback, queue, and events.
+- **ProviderRegistry**: Manages source providers (e.g., resolving URLs to streams).
+- **Player**: Handles low-level audio context and buffer management.
+- **Queue**: Manages track list and state.
+- **PluginManager**: Handles extensions and hooks.
+## Documentation
+For more detailed information, check out the documentation:
+- [Architecture Overview](docs/ARCHITECTURE.md)
+- [Providers System](docs/PROVIDERS.md)
+- [Plugin Development](docs/PLUGINS.md)
 ## Installation
@@ -33,17 +52,16 @@ npm install @students-dev/audify-js
 </head>
 <body>
   <script type="module">
-    import { AudioEngine } from '@students-dev/audify-js';
+    import { AudioEngine } from './dist/esm/index.js';
     const engine = new AudioEngine();
-    engine.on('ready', () => {
+    engine.eventBus.on('ready', () => {
       console.log('Audio engine ready!');
-      engine.add('https://example.com/audio.mp3');
-      engine.play();
+      engine.play('https://example.com/audio.mp3');
     });
-    engine.on('trackStart', (track) => {
+    engine.eventBus.on('trackStart', (track) => {
       console.log('Now playing:', track.title);
     });
   </script>
@@ -54,343 +72,108 @@ npm install @students-dev/audify-js
 ### Node.js
 ```javascript
-import { AudioEngine } from '@students-dev/audify-js';
+import { AudioEngine, LocalProvider } from '@students-dev/audify-js';
 const engine = new AudioEngine();
-engine.on('ready', () => {
-  engine.add('/path/to/audio.mp3');
-  engine.play();
-});
-```
-## API Reference
-### AudioEngine
-The main class that orchestrates all audio functionality.
-#### Constructor
-```javascript
-const engine = new AudioEngine(options);
-```
-#### Methods
-##### Playback Controls
-- `play(track?)`: Play a track or resume current playback
-- `pause()`: Pause playback
-- `stop()`: Stop playback
-- `seek(time)`: Seek to specific time (seconds)
-- `setVolume(volume)`: Set volume (0-1)
-##### Queue Management
-- `add(tracks)`: Add track(s) to queue
-- `remove(identifier)`: Remove track by index or ID
-- `next()`: Skip to next track
-- `previous()`: Go to previous track
-- `shuffle()`: Shuffle the queue
-- `clear()`: Clear the queue
-- `jump(index)`: Jump to track at index
-##### Filters
-- `applyFilter(type, options)`: Apply audio filter
-- `removeFilter(type)`: Remove audio filter
-##### Loop Modes
-- `setLoopMode(mode)`: Set loop mode (`LOOP_MODES.OFF`, `LOOP_MODES.TRACK`, `LOOP_MODES.QUEUE`)
-##### State
-- `getState()`: Get current engine state
-#### Events
+// Engine automatically registers default providers (Local, YouTube)
+// But you can register custom ones or configure them
-- `ready`: Engine initialized
-- `play`: Playback started
-- `pause`: Playback paused
-- `stop`: Playback stopped
-- `error`: Error occurred
-- `queueEmpty`: Queue became empty
-- `trackStart`: Track started playing
-- `trackEnd`: Track ended
-- `filterApplied`: Filter applied
-- `trackAdd`: Track added to queue
-- `trackRemove`: Track removed from queue
-- `shuffle`: Queue shuffled
-- `clear`: Queue cleared
-### Queue
-Manages the audio playback queue.
-```javascript
-const queue = engine.queue;
-// Add tracks
-queue.add('track.mp3');
-queue.add(['track1.mp3', 'track2.mp3']);
-// Navigate
-queue.next();
-queue.previous();
-queue.jump(5);
-// Modify
-queue.shuffle();
-queue.clear();
-```
-### Track
-Represents an audio track.
-```javascript
-import { Track } from '@students-dev/audify-js';
-const track = new Track('https://example.com/audio.mp3', {
-  title: 'My Song',
-  artist: 'Artist Name',
-  duration: 180
+engine.eventBus.on('ready', async () => {
+  await engine.play('./music/song.mp3');
 });
 ```
-### Filters
-Apply audio effects.
+## Providers
-```javascript
-// Bass boost
-engine.applyFilter('bassboost', { gain: 1.5 });
-// Nightcore
-engine.applyFilter('nightcore', { rate: 1.2 });
+Providers allow `audify-js` to resolve and play tracks from various sources. v1.0.2 introduces a **Provider Registry**.
-// 8D Audio
-engine.applyFilter('8d');
-// Remove filter
-engine.removeFilter('bassboost');
-```
+### Built-in Providers
-Available filters:
-- `bassboost`: Boost low frequencies
-- `nightcore`: Speed up and pitch up
-- `vaporwave`: Slow down and pitch down
-- `8d`: 8D audio rotation effect
-- `pitch`: Adjust pitch
-- `speed`: Adjust playback speed
-- `reverb`: Add reverb effect
+- **LocalProvider**: Plays local files (Node.js) or direct URLs.
+- **YouTubeProvider**: Resolves YouTube URLs (requires `ytdl-core` in real usage, mock included).
+- **SpotifyProvider**: Integrates with Spotify Web API.
+- **LavalinkProvider**: Connects to Lavalink nodes.
-### Plugins
-Extend functionality with plugins.
+### Configuration
 ```javascript
-import { Plugin } from '@students-dev/audify-js';
-class MyPlugin extends Plugin {
-  constructor() {
-    super('my-plugin', '1.0.0');
+const engine = new AudioEngine({
+  spotify: {
+    clientId: '...',
+    clientSecret: '...'
+  },
+  lavalink: {
+    host: 'localhost',
+    password: 'youshallnotpass'
   }
-  onLoad(engine) {
-    console.log('Plugin loaded!');
-  }
-  beforePlay(track) {
-    console.log('About to play:', track.title);
-  }
-}
-// Load plugin
-const plugin = new MyPlugin();
-engine.pluginManager.load(plugin);
-engine.pluginManager.enable('my-plugin');
-```
-### Providers
-Fetch metadata from different sources.
-```javascript
-import { YouTubeProvider, SoundCloudProvider, LocalProvider } from '@students-dev/audify-js';
-// YouTube
-const ytInfo = await YouTubeProvider.getInfo('https://youtube.com/watch?v=VIDEO_ID');
-// SoundCloud
-const scInfo = await SoundCloudProvider.getInfo('https://soundcloud.com/artist/track');
-// Local file (Node.js only)
-const localInfo = await LocalProvider.getInfo('/path/to/file.mp3');
-```
-### Utils
-Utility functions for common tasks.
-```javascript
-import { TimeUtils, MetadataUtils, ProbeUtils } from '@students-dev/audify-js';
-// Time formatting
-TimeUtils.format(125); // "02:05"
-// Metadata extraction
-const metadata = MetadataUtils.extract('https://example.com/song.mp3');
-// Audio probing
-const probe = await ProbeUtils.probe(audioBuffer);
-```
-## Examples
-### Basic Playback
-```javascript
-import { AudioEngine } from '@students-dev/audify-js';
-const engine = new AudioEngine();
-engine.on('ready', async () => {
-  // Add tracks
-  engine.add([
-    'track1.mp3',
-    'track2.mp3',
-    'https://example.com/track3.mp3'
-  ]);
-  // Start playing
-  await engine.play();
-  // Apply filter
-  engine.applyFilter('bassboost');
-});
-// Handle events
-engine.on('trackStart', (track) => {
-  console.log(`Playing: ${track.title}`);
-});
-engine.on('error', (error) => {
-  console.error('Playback error:', error);
 });
 ```
-### Queue Management
-```javascript
-// Add multiple tracks
-engine.add([
-  { url: 'song1.mp3', title: 'Song One' },
-  { url: 'song2.mp3', title: 'Song Two' }
-]);
-// Skip to next
-engine.next();
-// Shuffle queue
-engine.shuffle();
-// Clear and add new tracks
-engine.clear();
-engine.add('new-song.mp3');
-```
+## Plugins
-### Custom Plugin
+Create powerful extensions using the `Plugin` class.
-```javascript
-import { Plugin } from '@students-dev/audify-js';
+```typescript
+import { Plugin, IAudioEngine } from '@students-dev/audify-js';
-class LoggerPlugin extends Plugin {
+class MyLoggerPlugin extends Plugin {
   constructor() {
-    super('logger');
+    super('logger', '1.0.0');
   }
-  beforePlay(track) {
-    console.log(`[Logger] Starting playback: ${track.title}`);
+  onLoad(engine: IAudioEngine) {
+    console.log('Plugin loaded');
   }
-  afterPlay(track) {
-    console.log(`[Logger] Finished playback: ${track.title}`);
+  beforePlay(track: any) {
+    console.log('About to play:', track.title);
   }
-  trackEnd(track) {
-    console.log(`[Logger] Track ended: ${track.title}`);
+  trackEnd(track: any) {
+    console.log('Finished:', track.title);
   }
 }
-// Register plugin
-const loggerPlugin = new LoggerPlugin();
-engine.pluginManager.load(loggerPlugin);
-engine.pluginManager.enable('logger');
+// Register
+const plugin = new MyLoggerPlugin();
+engine.plugins.load(plugin);
+engine.plugins.enable('logger');
 ```
-## Browser Compatibility
+## API Reference
-- Chrome 14+
-- Firefox 25+
-- Safari 6+
-- Edge 12+
+### AudioEngine
-## Node.js Compatibility
+- `play(track?: ITrack | string)`: Play a track object or resolve a string (URL/ID).
+- `pause()`: Pause playback.
+- `stop()`: Stop playback.
+- `seek(time)`: Seek to time in seconds.
+- `setVolume(volume)`: 0.0 to 1.0.
+- `setLoopMode(mode)`: 'off', 'track', 'queue'.
+- `add(tracks)`: Add to queue.
+- `next()`: Skip to next.
+- `previous()`: Skip to previous.
+- `shuffle()`: Shuffle queue.
+- `getProvider(name)`: Get a provider instance.
-- Node.js 14+
+### Events
-For audio playback in Node.js, additional setup may be required for actual audio output.
+Access via `engine.eventBus.on(event, callback)`.
+- `ready`
+- `play`, `pause`, `stop`
+- `trackStart`, `trackEnd`
+- `queueUpdate`
+- `error`
 ## Contributing
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+2. Create feature branch
+3. Commit changes
+4. Push and PR
 ## License
-MIT License - see the [LICENSE](LICENSE) file for details.
-## Troubleshooting
-### Audio not playing in browser
-Ensure you're handling user interaction requirements for Web Audio API:
-```javascript
-// Resume AudioContext on user interaction
-document.addEventListener('click', () => {
-  if (engine.audioContext.state === 'suspended') {
-    engine.audioContext.resume();
-  }
-});
-```
-### CORS issues with remote audio
-When loading audio from different domains, ensure proper CORS headers are set on the server.
-### Node.js audio output
-For actual audio playback in Node.js, you may need additional packages like `speaker` or `node-speaker`.
-### Filter not working
-Some filters require AudioWorklet support in modern browsers. Check browser compatibility.
-## Changelog
-### v1.0.0
-- Initial release
-- Core audio engine
-- Queue management
-- Audio filters
-- Plugin system
-- Event system
-- Provider abstractions
-- Utility functions
+MIT