@students-dev/audify-js 1.0.0 → 1.0.1

package/LICENSE

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

@@ -12,7 +12,7 @@ A lightweight, modern, modular audio engine that provides playback, filters, que
 - 🎛️ **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
+- 🌐 **Multi-Source Support**: Local files, remote URLs, YouTube, SoundCloud, Spotify, Lavalink
 - 🛠️ **Developer-Friendly**: TypeScript declarations, ESM/CJS builds
 
 ## Installation
@@ -76,6 +76,39 @@ The main class that orchestrates all audio functionality.
 const engine = new AudioEngine(options);
 ```
 
+#### Spotify Integration
+
+```javascript
+// Initialize Spotify provider
+engine.initSpotify({
+  clientId: 'your_client_id',
+  clientSecret: 'your_client_secret'
+});
+
+// Search tracks
+const results = await engine.searchSpotifyTracks('query', { token: 'access_token' });
+
+// Load track
+const track = await engine.loadSpotifyTrack('track_id', { token: 'access_token' });
+```
+
+#### Lavalink Integration
+
+```javascript
+// Connect to Lavalink server
+await engine.connectLavalink({
+  host: 'localhost',
+  port: 2333,
+  password: 'youshallnotpass'
+});
+
+// Load track from Lavalink
+const track = await engine.loadLavalinkTrack('ytsearch:query');
+
+// Get Lavalink player for Discord bots
+const player = engine.getLavalinkPlayer('guild_id', 'channel_id');
+```
+
 #### Methods
 
 ##### Playback Controls
@@ -219,7 +252,7 @@ engine.pluginManager.enable('my-plugin');
 Fetch metadata from different sources.
 
 ```javascript
-import { YouTubeProvider, SoundCloudProvider, LocalProvider } from '@students-dev/audify-js';
+import { YouTubeProvider, SoundCloudProvider, LocalProvider, SpotifyProvider, LavalinkProvider } from '@students-dev/audify-js';
 
 // YouTube
 const ytInfo = await YouTubeProvider.getInfo('https://youtube.com/watch?v=VIDEO_ID');
@@ -229,6 +262,16 @@ const scInfo = await SoundCloudProvider.getInfo('https://soundcloud.com/artist/t
 
 // Local file (Node.js only)
 const localInfo = await LocalProvider.getInfo('/path/to/file.mp3');
+
+// Spotify (requires access token)
+const spotify = new SpotifyProvider({ clientId: 'your_client_id' });
+spotify.setAccessToken('access_token');
+const trackInfo = await spotify.getTrack('track_id');
+
+// Lavalink (requires Lavalink server)
+const lavalink = new LavalinkProvider({ host: 'localhost', port: 2333, password: 'password' });
+await lavalink.connect();
+const lavalinkTrack = await lavalink.loadTrack('ytsearch:query');
 ```
 
 ### Utils
@@ -250,6 +293,17 @@ const probe = await ProbeUtils.probe(audioBuffer);
 
 ## Examples
 
+The `examples/` directory contains comprehensive examples demonstrating various features:
+
+### 📁 Available Examples
+
+- **`browser-example.html`** - Interactive browser demo with UI controls
+- **`nodejs-example.js`** - Node.js usage with event handling
+- **`queue-example.js`** - Queue management operations
+- **`plugin-examples.js`** - Custom plugin implementations
+- **`spotify-example.js`** - Spotify API integration
+- **`lavalink-example.js`** - Lavalink server integration
+
 ### Basic Playback
 
 ```javascript
@@ -291,15 +345,46 @@ engine.add([
   { url: 'song2.mp3', title: 'Song Two' }
 ]);
 
-// Skip to next
+// Navigation
 engine.next();
+engine.previous();
+engine.jump(2); // Jump to track at index 2
 
-// Shuffle queue
+// Modify queue
 engine.shuffle();
-
-// Clear and add new tracks
 engine.clear();
-engine.add('new-song.mp3');
+
+// Remove specific track
+engine.remove(0); // Remove by index
+engine.remove('track-id'); // Remove by ID
+```
+
+### Audio Filters
+
+```javascript
+// Bass boost
+engine.applyFilter('bassboost', { gain: 1.5 });
+
+// Nightcore effect
+engine.applyFilter('nightcore', { rate: 1.2 });
+
+// Vaporwave effect
+engine.applyFilter('vaporwave', { rate: 0.8 });
+
+// 8D Audio
+engine.applyFilter('8d');
+
+// Pitch adjustment
+engine.applyFilter('pitch', { pitch: 1.1 });
+
+// Speed adjustment
+engine.applyFilter('speed', { speed: 1.25 });
+
+// Reverb
+engine.applyFilter('reverb', { preset: 'hall' });
+
+// Remove filter
+engine.removeFilter('bassboost');
 ```
 
 ### Custom Plugin
@@ -331,6 +416,46 @@ engine.pluginManager.load(loggerPlugin);
 engine.pluginManager.enable('logger');
 ```
 
+### Browser Usage
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>audify-js Demo</title>
+</head>
+<body>
+  <button id="playBtn">Play</button>
+  <button id="bassBtn">Bass Boost</button>
+
+  <script type="module">
+    import { AudioEngine } from '@students-dev/audify-js';
+
+    const engine = new AudioEngine();
+
+    engine.on('ready', () => {
+      engine.add('audio.mp3');
+
+      document.getElementById('playBtn').onclick = () => engine.play();
+      document.getElementById('bassBtn').onclick = () =>
+        engine.applyFilter('bassboost');
+    });
+  </script>
+</body>
+</html>
+```
+
+### Running Examples
+
+```bash
+# Browser example
+# Open examples/browser-example.html in your browser
+
+# Node.js examples
+node examples/nodejs-example.js
+node examples/queue-example.js
+```
+
 ## Browser Compatibility
 
 - Chrome 14+
@@ -385,6 +510,13 @@ Some filters require AudioWorklet support in modern browsers. Check browser comp
 
 ## Changelog
 
+### v1.1.0
+- Added Spotify integration with client-side API support
+- Added Lavalink integration for server-based audio streaming
+- Updated dependencies for better performance and security
+- Enhanced TypeScript type definitions
+- Added comprehensive examples for new integrations
+
 ### v1.0.0
 - Initial release
 - Core audio engine

package/dist/cjs/index.js

@@ -1,12 +1,14 @@
 'use strict';
 
+var SpotifyWebApi = require('spotify-web-api-node');
+var lavalinkClient = require('lavalink-client');
 var fs = require('fs');
 var path = require('path');
 
 /**
  * Loop modes for playback
  */
-const LOOP_MODES$1 = {
+const LOOP_MODES = {
   OFF: 'off',
   TRACK: 'track',
   QUEUE: 'queue'
@@ -15,7 +17,7 @@ const LOOP_MODES$1 = {
 /**
  * Repeat modes (alias for loop modes)
  */
-const REPEAT_MODES = LOOP_MODES$1;
+const REPEAT_MODES = LOOP_MODES;
 
 /**
  * Filter types
@@ -126,7 +128,7 @@ class Player {
     this.currentTime = 0;
     this.duration = 0;
     this.volume = 1;
-    this.loopMode = LOOP_MODES$1.OFF;
+    this.loopMode = LOOP_MODES.OFF;
     this.eventBus = new EventBus();
   }
 
@@ -239,14 +241,14 @@ class Player {
    */
   handleTrackEnd() {
     switch (this.loopMode) {
-      case LOOP_MODES$1.TRACK:
+      case LOOP_MODES.TRACK:
         // Replay current track
         break;
-      case LOOP_MODES$1.QUEUE:
+      case LOOP_MODES.QUEUE:
         // Play next in queue
         this.audioEngine.queue.getNext();
         break;
-      case LOOP_MODES$1.OFF:
+      case LOOP_MODES.OFF:
     }
   }
 
@@ -740,6 +742,276 @@ class Queue {
   }
 }
 
+/**
+ * Spotify provider for client-side API integration
+ */
+class SpotifyProvider {
+  constructor(options = {}) {
+    this.spotifyApi = new SpotifyWebApi({
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      redirectUri: options.redirectUri,
+      accessToken: options.accessToken,
+      refreshToken: options.refreshToken
+    });
+  }
+
+  /**
+   * Set access token
+   * @param {string} token - OAuth access token
+   */
+  setAccessToken(token) {
+    this.spotifyApi.setAccessToken(token);
+  }
+
+  /**
+   * Set refresh token
+   * @param {string} token - OAuth refresh token
+   */
+  setRefreshToken(token) {
+    this.spotifyApi.setRefreshToken(token);
+  }
+
+  /**
+   * Refresh access token
+   * @returns {Promise<Object>} Token response
+   */
+  async refreshAccessToken() {
+    try {
+      const data = await this.spotifyApi.refreshAccessToken();
+      this.spotifyApi.setAccessToken(data.body.access_token);
+      return data.body;
+    } catch (error) {
+      throw new Error(`Failed to refresh token: ${error.message}`);
+    }
+  }
+
+  /**
+   * Search tracks
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<Array>} Array of track objects
+   */
+  async searchTracks(query, options = {}) {
+    try {
+      const data = await this.spotifyApi.searchTracks(query, {
+        limit: options.limit || 20,
+        offset: options.offset || 0
+      });
+
+      return data.body.tracks.items.map(track => this._formatTrack(track));
+    } catch (error) {
+      throw new Error(`Failed to search tracks: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get track by ID
+   * @param {string} trackId - Spotify track ID
+   * @returns {Promise<Object>} Track object
+   */
+  async getTrack(trackId) {
+    try {
+      const data = await this.spotifyApi.getTrack(trackId);
+      return this._formatTrack(data.body);
+    } catch (error) {
+      throw new Error(`Failed to get track: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get tracks by IDs
+   * @param {Array<string>} trackIds - Array of Spotify track IDs
+   * @returns {Promise<Array>} Array of track objects
+   */
+  async getTracks(trackIds) {
+    try {
+      const data = await this.spotifyApi.getTracks(trackIds);
+      return data.body.tracks.map(track => this._formatTrack(track));
+    } catch (error) {
+      throw new Error(`Failed to get tracks: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get audio features for track
+   * @param {string} trackId - Spotify track ID
+   * @returns {Promise<Object>} Audio features
+   */
+  async getAudioFeatures(trackId) {
+    try {
+      const data = await this.spotifyApi.getAudioFeaturesForTrack(trackId);
+      return data.body;
+    } catch (error) {
+      throw new Error(`Failed to get audio features: ${error.message}`);
+    }
+  }
+
+  /**
+   * Format Spotify track to internal format
+   * @param {Object} spotifyTrack - Spotify track object
+   * @returns {Object} Formatted track
+   * @private
+   */
+  _formatTrack(spotifyTrack) {
+    return {
+      id: spotifyTrack.id,
+      title: spotifyTrack.name,
+      artist: spotifyTrack.artists.map(artist => artist.name).join(', '),
+      duration: Math.floor(spotifyTrack.duration_ms / 1000),
+      thumbnail: spotifyTrack.album.images[0]?.url,
+      url: spotifyTrack.external_urls.spotify,
+      source: 'spotify',
+      album: spotifyTrack.album.name,
+      popularity: spotifyTrack.popularity,
+      preview_url: spotifyTrack.preview_url,
+      metadata: {
+        spotifyId: spotifyTrack.id,
+        artists: spotifyTrack.artists,
+        album: spotifyTrack.album
+      }
+    };
+  }
+}
+
+/**
+ * Lavalink provider for connecting to Lavalink server
+ */
+class LavalinkProvider {
+  constructor(options = {}) {
+    this.host = options.host || 'localhost';
+    this.port = options.port || 2333;
+    this.password = options.password || 'youshallnotpass';
+    this.secure = options.secure || false;
+    this.manager = null;
+    this.node = null;
+    this.isConnected = false;
+  }
+
+  /**
+   * Connect to Lavalink server
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    try {
+      this.manager = new lavalinkClient.LavalinkManager({
+        nodes: [{
+          host: this.host,
+          port: this.port,
+          password: this.password,
+          secure: this.secure,
+          id: 'main'
+        }],
+        sendToShard: (guildId, payload) => {
+          // This would need to be implemented to send to Discord gateway
+          // For now, this is a placeholder
+          console.log('Send to shard:', guildId, payload);
+        }
+      });
+
+      await this.manager.connect();
+      this.node = this.manager.nodes.get('main');
+      this.isConnected = true;
+    } catch (error) {
+      throw new Error(`Failed to connect to Lavalink: ${error.message}`);
+    }
+  }
+
+  /**
+   * Disconnect from Lavalink server
+   */
+  disconnect() {
+    if (this.manager) {
+      this.manager.destroy();
+      this.isConnected = false;
+    }
+  }
+
+  /**
+   * Create a player for a guild/channel
+   * @param {string} guildId - Guild ID
+   * @param {string} channelId - Voice channel ID
+   * @returns {Object} Player instance
+   */
+  createPlayer(guildId, channelId) {
+    if (!this.isConnected) {
+      throw new Error('Not connected to Lavalink');
+    }
+
+    return this.manager.createPlayer({
+      guildId,
+      voiceChannelId: channelId,
+      textChannelId: channelId, // Optional
+      selfDeaf: false,
+      selfMute: false
+    });
+  }
+
+  /**
+   * Load track from Lavalink
+   * @param {string} identifier - Track identifier (URL or search query)
+   * @returns {Promise<Object>} Track info
+   */
+  async loadTrack(identifier) {
+    if (!this.isConnected) {
+      throw new Error('Not connected to Lavalink');
+    }
+
+    try {
+      const result = await this.node.rest.loadTracks(identifier);
+
+      if (result.loadType === 'TRACK_LOADED') {
+        return this._formatTrack(result.tracks[0]);
+      } else if (result.loadType === 'PLAYLIST_LOADED') {
+        return result.tracks.map(track => this._formatTrack(track));
+      } else if (result.loadType === 'SEARCH_RESULT') {
+        return result.tracks.map(track => this._formatTrack(track));
+      } else {
+        throw new Error('No tracks found');
+      }
+    } catch (error) {
+      throw new Error(`Failed to load track: ${error.message}`);
+    }
+  }
+
+  /**
+   * Format Lavalink track to internal format
+   * @param {Object} lavalinkTrack - Lavalink track object
+   * @returns {Object} Formatted track
+   * @private
+   */
+  _formatTrack(lavalinkTrack) {
+    const info = lavalinkTrack.info;
+    return {
+      id: lavalinkTrack.track,
+      title: info.title,
+      artist: info.author,
+      duration: Math.floor(info.length / 1000),
+      thumbnail: info.artworkUrl,
+      url: info.uri,
+      source: 'lavalink',
+      isrc: info.isrc,
+      metadata: {
+        lavalinkTrack: lavalinkTrack.track,
+        identifier: info.identifier,
+        sourceName: info.sourceName
+      }
+    };
+  }
+
+  /**
+   * Get node stats
+   * @returns {Promise<Object>} Node stats
+   */
+  async getStats() {
+    if (!this.isConnected) {
+      throw new Error('Not connected to Lavalink');
+    }
+
+    return await this.node.rest.getStats();
+  }
+}
+
 /**
  * Main audio engine class
  */
@@ -751,6 +1023,8 @@ class AudioEngine {
     this.filters = null;
     this.queue = new Queue();
     this.eventBus = new EventBus();
+    this.spotifyProvider = null;
+    this.lavalinkProvider = null;
     this.isReady = false;
 
     this.initialize();
@@ -933,6 +1207,100 @@ class AudioEngine {
     };
   }
 
+  /**
+   * Initialize Spotify provider
+   * @param {Object} options - Spotify options
+   */
+  initSpotify(options = {}) {
+    this.spotifyProvider = new SpotifyProvider(options);
+  }
+
+  /**
+   * Load Spotify track and add to queue
+   * @param {string} trackId - Spotify track ID
+   * @param {Object} options - Options including token
+   * @returns {Promise<Track>} Added track
+   */
+  async loadSpotifyTrack(trackId, options = {}) {
+    if (!this.spotifyProvider) {
+      throw new Error('Spotify provider not initialized');
+    }
+
+    if (options.token) {
+      this.spotifyProvider.setAccessToken(options.token);
+    }
+
+    const trackData = await this.spotifyProvider.getTrack(trackId);
+    const track = new Track(trackData.url, trackData);
+    this.add(track);
+    return track;
+  }
+
+  /**
+   * Search Spotify tracks
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<Array>} Search results
+   */
+  async searchSpotifyTracks(query, options = {}) {
+    if (!this.spotifyProvider) {
+      throw new Error('Spotify provider not initialized');
+    }
+
+    if (options.token) {
+      this.spotifyProvider.setAccessToken(options.token);
+    }
+
+    return await this.spotifyProvider.searchTracks(query, options);
+  }
+
+  /**
+   * Connect to Lavalink server
+   * @param {Object} options - Lavalink connection options
+   * @returns {Promise<void>}
+   */
+  async connectLavalink(options = {}) {
+    this.lavalinkProvider = new LavalinkProvider(options);
+    await this.lavalinkProvider.connect();
+  }
+
+  /**
+   * Load Lavalink track and add to queue
+   * @param {string} identifier - Track identifier
+   * @returns {Promise<Track|Array<Track>>} Added track(s)
+   */
+  async loadLavalinkTrack(identifier) {
+    if (!this.lavalinkProvider) {
+      throw new Error('Lavalink provider not connected');
+    }
+
+    const trackData = await this.lavalinkProvider.loadTrack(identifier);
+
+    if (Array.isArray(trackData)) {
+      const tracks = trackData.map(data => new Track(data.url, data));
+      this.add(tracks);
+      return tracks;
+    } else {
+      const track = new Track(trackData.url, trackData);
+      this.add(track);
+      return track;
+    }
+  }
+
+  /**
+   * Get Lavalink player for guild/channel
+   * @param {string} guildId - Guild ID
+   * @param {string} channelId - Voice channel ID
+   * @returns {Object} Lavalink player
+   */
+  getLavalinkPlayer(guildId, channelId) {
+    if (!this.lavalinkProvider) {
+      throw new Error('Lavalink provider not connected');
+    }
+
+    return this.lavalinkProvider.createPlayer(guildId, channelId);
+  }
+
   /**
    * Destroy the engine
    */
@@ -942,6 +1310,9 @@ class AudioEngine {
     }
     this.filters.clear();
     this.player.stop();
+    if (this.lavalinkProvider) {
+      this.lavalinkProvider.disconnect();
+    }
   }
 }
 
@@ -1479,7 +1850,8 @@ exports.AudioEngine = AudioEngine;
 exports.EVENTS = EVENTS;
 exports.EventBus = EventBus;
 exports.FILTER_TYPES = FILTER_TYPES;
-exports.LOOP_MODES = LOOP_MODES$1;
+exports.LOOP_MODES = LOOP_MODES;
+exports.LavalinkProvider = LavalinkProvider;
 exports.LocalProvider = LocalProvider;
 exports.Logger = Logger;
 exports.MetadataUtils = MetadataUtils;
@@ -1488,6 +1860,7 @@ exports.ProbeUtils = ProbeUtils;
 exports.Queue = Queue;
 exports.REPEAT_MODES = REPEAT_MODES;
 exports.SoundCloudProvider = SoundCloudProvider;
+exports.SpotifyProvider = SpotifyProvider;
 exports.TimeUtils = TimeUtils;
 exports.Track = Track;
 exports.YouTubeProvider = YouTubeProvider;