ziplayer 0.0.9 → 0.1.1

package/dist/structures/Player.js

@@ -5,77 +5,292 @@ const events_1 = require("events");
 const voice_1 = require("@discordjs/voice");
 const Queue_1 = require("./Queue");
 const plugins_1 = require("../plugins");
+const timeout_1 = require("../utils/timeout");
+/**
+ * Represents a music player for a specific Discord guild.
+ *
+ * @example
+ * // Create and configure player
+ * const player = await manager.create(guildId, {
+ *   tts: { interrupt: true, volume: 1 },
+ *   leaveOnEnd: true,
+ *   leaveTimeout: 30000
+ * });
+ *
+ * // Connect to voice channel
+ * await player.connect(voiceChannel);
+ *
+ * // Play different types of content
+ * await player.play("Never Gonna Give You Up", userId); // Search query
+ * await player.play("https://youtube.com/watch?v=dQw4w9WgXcQ", userId); // Direct URL
+ * await player.play("tts: Hello everyone!", userId); // Text-to-Speech
+ *
+ * // Player controls
+ * player.pause(); // Pause current track
+ * player.resume(); // Resume paused track
+ * player.skip(); // Skip to next track
+ * player.stop(); // Stop and clear queue
+ * player.setVolume(0.5); // Set volume to 50%
+ *
+ * // Event handling
+ * player.on("trackStart", (player, track) => {
+ *   console.log(`Now playing: ${track.title}`);
+ * });
+ *
+ * player.on("queueEnd", (player) => {
+ *   console.log("Queue finished");
+ * });
+ *
+ */
 class Player extends events_1.EventEmitter {
+    /**
+     * Attach an extension to the player
+     *
+     * @param {BaseExtension} extension - The extension to attach
+     * @example
+     * player.attachExtension(new MyExtension());
+     */
+    attachExtension(extension) {
+        if (this.extensions.includes(extension))
+            return;
+        if (!extension.player)
+            extension.player = this;
+        this.extensions.push(extension);
+        this.invokeExtensionLifecycle(extension, "onRegister");
+    }
+    /**
+     * Detach an extension from the player
+     *
+     * @param {BaseExtension} extension - The extension to detach
+     * @example
+     * player.detachExtension(new MyExtension());
+     */
+    detachExtension(extension) {
+        const index = this.extensions.indexOf(extension);
+        if (index === -1)
+            return;
+        this.extensions.splice(index, 1);
+        this.invokeExtensionLifecycle(extension, "onDestroy");
+        if (extension.player === this) {
+            extension.player = null;
+        }
+    }
+    /**
+     * Get all extensions attached to the player
+     *
+     * @returns {readonly BaseExtension[]} All attached extensions
+     * @example
+     * const extensions = player.getExtensions();
+     * console.log(`Extensions: ${extensions.length}`);
+     */
+    getExtensions() {
+        return this.extensions;
+    }
+    invokeExtensionLifecycle(extension, hook) {
+        const fn = extension[hook];
+        if (typeof fn !== "function")
+            return;
+        try {
+            const result = fn.call(extension, this.extensionContext);
+            if (result && typeof result.then === "function") {
+                result.catch((err) => this.debug(`[Player] Extension ${extension.name} ${hook} error:`, err));
+            }
+        }
+        catch (err) {
+            this.debug(`[Player] Extension ${extension.name} ${hook} error:`, err);
+        }
+    }
+    async runBeforePlayHooks(initial) {
+        const request = { ...initial };
+        const response = {};
+        for (const extension of this.extensions) {
+            const hook = extension.beforePlay;
+            if (typeof hook !== "function")
+                continue;
+            try {
+                const result = await Promise.resolve(hook.call(extension, this.extensionContext, request));
+                if (!result)
+                    continue;
+                if (result.query !== undefined) {
+                    request.query = result.query;
+                    response.query = result.query;
+                }
+                if (result.requestedBy !== undefined) {
+                    request.requestedBy = result.requestedBy;
+                    response.requestedBy = result.requestedBy;
+                }
+                if (Array.isArray(result.tracks)) {
+                    response.tracks = result.tracks;
+                }
+                if (typeof result.isPlaylist === "boolean") {
+                    response.isPlaylist = result.isPlaylist;
+                }
+                if (typeof result.success === "boolean") {
+                    response.success = result.success;
+                }
+                if (result.error instanceof Error) {
+                    response.error = result.error;
+                }
+                if (typeof result.handled === "boolean") {
+                    response.handled = result.handled;
+                    if (result.handled)
+                        break;
+                }
+            }
+            catch (err) {
+                this.debug(`[Player] Extension ${extension.name} beforePlay error:`, err);
+            }
+        }
+        return { request, response };
+    }
+    async runAfterPlayHooks(payload) {
+        if (this.extensions.length === 0)
+            return;
+        const safeTracks = payload.tracks ? [...payload.tracks] : undefined;
+        if (safeTracks) {
+            Object.freeze(safeTracks);
+        }
+        const immutablePayload = Object.freeze({ ...payload, tracks: safeTracks });
+        for (const extension of this.extensions) {
+            const hook = extension.afterPlay;
+            if (typeof hook !== "function")
+                continue;
+            try {
+                await Promise.resolve(hook.call(extension, this.extensionContext, immutablePayload));
+            }
+            catch (err) {
+                this.debug(`[Player] Extension ${extension.name} afterPlay error:`, err);
+            }
+        }
+    }
+    async extensionsProvideSearch(query, requestedBy) {
+        const request = { query, requestedBy };
+        for (const extension of this.extensions) {
+            const hook = extension.provideSearch;
+            if (typeof hook !== "function")
+                continue;
+            try {
+                const result = await Promise.resolve(hook.call(extension, this.extensionContext, request));
+                if (result && Array.isArray(result.tracks) && result.tracks.length > 0) {
+                    this.debug(`[Player] Extension ${extension.name} handled search for query: ${query}`);
+                    return result;
+                }
+            }
+            catch (err) {
+                this.debug(`[Player] Extension ${extension.name} provideSearch error:`, err);
+            }
+        }
+        return null;
+    }
+    async extensionsProvideStream(track) {
+        const request = { track };
+        for (const extension of this.extensions) {
+            const hook = extension.provideStream;
+            if (typeof hook !== "function")
+                continue;
+            try {
+                const result = await Promise.resolve(hook.call(extension, this.extensionContext, request));
+                if (result && result.stream) {
+                    this.debug(`[Player] Extension ${extension.name} provided stream for track: ${track.title}`);
+                    return result;
+                }
+            }
+            catch (err) {
+                this.debug(`[Player] Extension ${extension.name} provideStream error:`, err);
+            }
+        }
+        return null;
+    }
     /**
      * Start playing a specific track immediately, replacing the current resource.
      */
     async startTrack(track) {
         try {
-            // Find plugin that can handle this track
-            const plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
-            if (!plugin) {
-                this.debug(`[Player] No plugin found for track: ${track.title}`);
-                throw new Error(`No plugin found for track: ${track.title}`);
-            }
-            this.debug(`[Player] Getting stream for track: ${track.title}`);
-            this.debug(`[Player] Using plugin: ${plugin.name}`);
-            this.debug(`[Track] Track Info:`, track);
-            let streamInfo;
-            try {
-                streamInfo = await this.withTimeout(plugin.getStream(track), "getStream timed out");
-            }
-            catch (streamError) {
-                this.debug(`[Player] getStream failed, trying getFallback:`, streamError);
-                const allplugs = this.pluginManager.getAll();
-                for (const p of allplugs) {
-                    if (typeof p.getFallback !== "function") {
-                        continue;
-                    }
-                    try {
-                        streamInfo = await this.withTimeout(p.getFallback(track), `getFallback timed out for plugin ${p.name}`);
-                        if (!streamInfo.stream)
+            let streamInfo = await this.extensionsProvideStream(track);
+            let plugin;
+            if (!streamInfo) {
+                plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
+                if (!plugin) {
+                    this.debug(`[Player] No plugin found for track: ${track.title}`);
+                    throw new Error(`No plugin found for track: ${track.title}`);
+                }
+                this.debug(`[Player] Getting stream for track: ${track.title}`);
+                this.debug(`[Player] Using plugin: ${plugin.name}`);
+                this.debug(`[Track] Track Info:`, track);
+                try {
+                    streamInfo = await (0, timeout_1.withTimeout)(plugin.getStream(track), this.options.extractorTimeout ?? 15000, "getStream timed out");
+                }
+                catch (streamError) {
+                    this.debug(`[Player] getStream failed, trying getFallback:`, streamError);
+                    const allplugs = this.pluginManager.getAll();
+                    for (const p of allplugs) {
+                        if (typeof p.getFallback !== "function") {
                             continue;
-                        this.debug(`[Player] getFallback succeeded with plugin ${p.name} for track: ${track.title}`);
-                        break;
+                        }
+                        try {
+                            streamInfo = await (0, timeout_1.withTimeout)(p.getFallback(track), this.options.extractorTimeout ?? 15000, `getFallback timed out for plugin ${p.name}`);
+                            if (!streamInfo?.stream)
+                                continue;
+                            this.debug(`[Player] getFallback succeeded with plugin ${p.name} for track: ${track.title}`);
+                            break;
+                        }
+                        catch (fallbackError) {
+                            this.debug(`[Player] getFallback failed with plugin ${p.name}:`, fallbackError);
+                        }
                     }
-                    catch (fallbackError) {
-                        this.debug(`[Player] getFallback failed with plugin ${p.name}:`, fallbackError);
+                    if (!streamInfo?.stream) {
+                        throw new Error(`All getFallback attempts failed for track: ${track.title}`);
                     }
                 }
-                if (!streamInfo?.stream) {
-                    throw new Error(`All getFallback attempts failed for track: ${track.title}`);
-                }
+            }
+            else {
+                this.debug(`[Player] Using extension-provided stream for track: ${track.title}`);
+            }
+            if (plugin) {
                 this.debug(streamInfo);
             }
-            function mapToStreamType(type) {
-                switch (type) {
-                    case "webm/opus":
-                        return voice_1.StreamType.WebmOpus;
-                    case "ogg/opus":
-                        return voice_1.StreamType.OggOpus;
-                    case "arbitrary":
-                        return voice_1.StreamType.Arbitrary;
-                    default:
-                        return voice_1.StreamType.Arbitrary;
+            // Kiểm tra nếu có stream thực sự để tạo AudioResource
+            if (streamInfo && streamInfo.stream) {
+                function mapToStreamType(type) {
+                    switch (type) {
+                        case "webm/opus":
+                            return voice_1.StreamType.WebmOpus;
+                        case "ogg/opus":
+                            return voice_1.StreamType.OggOpus;
+                        case "arbitrary":
+                        default:
+                            return voice_1.StreamType.Arbitrary;
+                    }
+                }
+                const stream = streamInfo.stream;
+                const inputType = mapToStreamType(streamInfo.type);
+                this.currentResource = (0, voice_1.createAudioResource)(stream, {
+                    metadata: track,
+                    inputType,
+                    inlineVolume: true,
+                });
+                // Apply initial volume using the resource's VolumeTransformer
+                if (this.volumeInterval) {
+                    clearInterval(this.volumeInterval);
+                    this.volumeInterval = null;
                 }
+                this.currentResource.volume?.setVolume(this.volume / 100);
+                this.debug(`[Player] Playing resource for track: ${track.title}`);
+                this.audioPlayer.play(this.currentResource);
+                await (0, voice_1.entersState)(this.audioPlayer, voice_1.AudioPlayerStatus.Playing, 5000);
+                return true;
             }
-            let stream = streamInfo.stream;
-            let inputType = mapToStreamType(streamInfo.type);
-            this.currentResource = (0, voice_1.createAudioResource)(stream, {
-                metadata: track,
-                inputType,
-                inlineVolume: true,
-            });
-            // Apply initial volume using the resource's VolumeTransformer
-            if (this.volumeInterval) {
-                clearInterval(this.volumeInterval);
-                this.volumeInterval = null;
+            else if (streamInfo && !streamInfo.stream) {
+                // Extension đang xử lý phát nhạc (như Lavalink) - chỉ đánh dấu đang phát
+                this.debug(`[Player] Extension is handling playback for track: ${track.title}`);
+                this.isPlaying = true;
+                this.isPaused = false;
+                this.emit("trackStart", track);
+                return true;
+            }
+            else {
+                throw new Error(`No stream available for track: ${track.title}`);
             }
-            this.currentResource.volume?.setVolume(this.volume / 100);
-            this.debug(`[Player] Playing resource for track: ${track.title}`);
-            this.audioPlayer.play(this.currentResource);
-            await (0, voice_1.entersState)(this.audioPlayer, voice_1.AudioPlayerStatus.Playing, 5000);
-            return true;
         }
         catch (error) {
             this.debug(`[Player] startTrack error:`, error);
@@ -90,10 +305,6 @@ class Player extends events_1.EventEmitter {
             this.debug(`[Player] Cleared leave timeout`);
         }
     }
-    withTimeout(promise, message) {
-        const timeout = this.options.extractorTimeout ?? 15000;
-        return Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), timeout))]);
-    }
     debug(message, ...optionalParams) {
         if (this.listenerCount("debug") > 0) {
             this.emit("debug", message, ...optionalParams);
@@ -109,6 +320,11 @@ class Player extends events_1.EventEmitter {
         this.currentResource = null;
         this.volumeInterval = null;
         this.skipLoop = false;
+        this.extensions = [];
+        // Cache for plugin matching to improve performance
+        this.pluginCache = new Map();
+        this.PLUGIN_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+        this.pluginCacheTimestamps = new Map();
         // TTS support
         this.ttsPlayer = null;
         this.ttsQueue = [];
@@ -145,6 +361,7 @@ class Player extends events_1.EventEmitter {
         this.volume = this.options.volume || 100;
         this.userdata = this.options.userdata;
         this.setupEventListeners();
+        this.extensionContext = Object.freeze({ player: this, manager });
         // Optionally pre-create the TTS AudioPlayer
         if (this.options?.tts?.createPlayer) {
             this.ensureTTSPlayer();
@@ -230,6 +447,14 @@ class Player extends events_1.EventEmitter {
         this.debug(`[Player] Removing plugin: ${name}`);
         return this.pluginManager.unregister(name);
     }
+    /**
+     * Connect to a voice channel
+     *
+     * @param {VoiceChannel} channel - Discord voice channel
+     * @returns {Promise<VoiceConnection>} The voice connection
+     * @example
+     * await player.connect(voiceChannel);
+     */
     async connect(channel) {
         try {
             this.debug(`[Player] Connecting to voice channel: ${channel.id}`);
@@ -261,14 +486,29 @@ class Player extends events_1.EventEmitter {
             throw error;
         }
     }
+    /**
+     * Search for tracks using the player's extensions and plugins
+     *
+     * @param {string} query - The query to search for
+     * @param {string} requestedBy - The user ID who requested the search
+     * @returns {Promise<SearchResult>} The search result
+     * @example
+     * const result = await player.search("Never Gonna Give You Up", userId);
+     * console.log(`Search result: ${result.tracks.length} tracks`);
+     */
     async search(query, requestedBy) {
         this.debug(`[Player] Search called with query: ${query}, requestedBy: ${requestedBy}`);
+        const extensionResult = await this.extensionsProvideSearch(query, requestedBy);
+        if (extensionResult && Array.isArray(extensionResult.tracks) && extensionResult.tracks.length > 0) {
+            this.debug(`[Player] Extension handled search for query: ${query}`);
+            return extensionResult;
+        }
         const plugins = this.pluginManager.getAll();
         let lastError = null;
         for (const p of plugins) {
             try {
                 this.debug(`[Player] Trying plugin for search: ${p.name}`);
-                const res = await this.withTimeout(p.search(query, requestedBy), `Search operation timed out for ${p.name}`);
+                const res = await (0, timeout_1.withTimeout)(p.search(query, requestedBy), this.options.extractorTimeout ?? 15000, `Search operation timed out for ${p.name}`);
                 if (res && Array.isArray(res.tracks) && res.tracks.length > 0) {
                     this.debug(`[Player] Plugin '${p.name}' returned ${res.tracks.length} tracks`);
                     return res;
@@ -286,29 +526,66 @@ class Player extends events_1.EventEmitter {
             this.emit("playerError", lastError);
         throw new Error(`No plugin found to handle: ${query}`);
     }
+    /**
+     * Play a track or search query
+     *
+     * @param {string | Track} query - Track URL, search query, or Track object
+     * @param {string} requestedBy - User ID who requested the track
+     * @returns {Promise<boolean>} True if playback started successfully
+     * @example
+     * await player.play("Never Gonna Give You Up", userId);
+     * await player.play("https://youtube.com/watch?v=dQw4w9WgXcQ", userId);
+     * await player.play("tts: Hello everyone!", userId);
+     */
     async play(query, requestedBy) {
+        this.debug(`[Player] Play called with query: ${typeof query === "string" ? query : query?.title}`);
+        this.clearLeaveTimeout();
+        let tracksToAdd = [];
+        let isPlaylist = false;
+        let effectiveRequest = { query, requestedBy };
+        let hookResponse = {};
         try {
-            this.debug(`[Player] Play called with query: ${typeof query === "string" ? query : query?.title}`);
-            // If a leave was scheduled due to previous idle, cancel it now
-            this.clearLeaveTimeout();
-            let tracksToAdd = [];
-            let isPlaylist = false;
-            if (typeof query === "string") {
-                const searchResult = await this.search(query, requestedBy || "Unknown");
+            const hookOutcome = await this.runBeforePlayHooks(effectiveRequest);
+            effectiveRequest = hookOutcome.request;
+            hookResponse = hookOutcome.response;
+            if (effectiveRequest.requestedBy === undefined) {
+                effectiveRequest.requestedBy = requestedBy;
+            }
+            const hookTracks = Array.isArray(hookResponse.tracks) ? hookResponse.tracks : undefined;
+            if (hookResponse.handled && (!hookTracks || hookTracks.length === 0)) {
+                const handledPayload = {
+                    success: hookResponse.success ?? true,
+                    query: effectiveRequest.query,
+                    requestedBy: effectiveRequest.requestedBy,
+                    tracks: [],
+                    isPlaylist: hookResponse.isPlaylist ?? false,
+                    error: hookResponse.error,
+                };
+                await this.runAfterPlayHooks(handledPayload);
+                if (hookResponse.error) {
+                    this.emit("playerError", hookResponse.error);
+                }
+                return hookResponse.success ?? true;
+            }
+            if (hookTracks && hookTracks.length > 0) {
+                tracksToAdd = hookTracks;
+                isPlaylist = hookResponse.isPlaylist ?? hookTracks.length > 1;
+            }
+            else if (typeof effectiveRequest.query === "string") {
+                const searchResult = await this.search(effectiveRequest.query, effectiveRequest.requestedBy || "Unknown");
                 tracksToAdd = searchResult.tracks;
                 if (searchResult.playlist) {
                     isPlaylist = true;
                     this.debug(`[Player] Added playlist: ${searchResult.playlist.name} (${tracksToAdd.length} tracks)`);
                 }
             }
-            else {
-                tracksToAdd = [query];
+            else if (effectiveRequest.query) {
+                tracksToAdd = [effectiveRequest.query];
             }
             if (tracksToAdd.length === 0) {
                 this.debug(`[Player] No tracks found for play`);
                 throw new Error("No tracks found");
             }
-            // If a TTS track is requested and interrupt mode is enabled, handle it separately
             const isTTS = (t) => {
                 if (!t)
                     return false;
@@ -319,14 +596,20 @@ class Player extends events_1.EventEmitter {
                     return false;
                 }
             };
-            const queryLooksTTS = typeof query === "string" && query.trim().toLowerCase().startsWith("tts");
+            const queryLooksTTS = typeof effectiveRequest.query === "string" && effectiveRequest.query.trim().toLowerCase().startsWith("tts");
             if (!isPlaylist &&
                 tracksToAdd.length > 0 &&
                 this.options?.tts?.interrupt !== false &&
                 (isTTS(tracksToAdd[0]) || queryLooksTTS)) {
-                // Interrupt music playback with TTS (do not modify the music queue)
                 this.debug(`[Player] Interrupting with TTS: ${tracksToAdd[0].title}`);
                 await this.interruptWithTTSTrack(tracksToAdd[0]);
+                await this.runAfterPlayHooks({
+                    success: true,
+                    query: effectiveRequest.query,
+                    requestedBy: effectiveRequest.requestedBy,
+                    tracks: tracksToAdd,
+                    isPlaylist,
+                });
                 return true;
             }
             if (isPlaylist) {
@@ -334,16 +617,28 @@ class Player extends events_1.EventEmitter {
                 this.emit("queueAddList", tracksToAdd);
             }
             else {
-                this.queue.add(tracksToAdd?.[0]);
-                this.emit("queueAdd", tracksToAdd?.[0]);
-            }
-            // Start playing if not already playing
-            if (!this.isPlaying) {
-                return this.playNext();
+                this.queue.add(tracksToAdd[0]);
+                this.emit("queueAdd", tracksToAdd[0]);
             }
-            return true;
+            const started = !this.isPlaying ? await this.playNext() : true;
+            await this.runAfterPlayHooks({
+                success: started,
+                query: effectiveRequest.query,
+                requestedBy: effectiveRequest.requestedBy,
+                tracks: tracksToAdd,
+                isPlaylist,
+            });
+            return started;
         }
         catch (error) {
+            await this.runAfterPlayHooks({
+                success: false,
+                query: effectiveRequest.query,
+                requestedBy: effectiveRequest.requestedBy,
+                tracks: tracksToAdd,
+                isPlaylist,
+                error: error,
+            });
             this.debug(`[Player] Play error:`, error);
             this.emit("playerError", error);
             return false;
@@ -352,6 +647,11 @@ class Player extends events_1.EventEmitter {
     /**
      * Interrupt current music with a TTS track. Pauses music, swaps the
      * subscription to a dedicated TTS player, plays TTS, then resumes.
+     *
+     * @param {Track} track - The track to interrupt with
+     * @returns {Promise<void>}
+     * @example
+     * await player.interruptWithTTSTrack(track);
      */
     async interruptWithTTSTrack(track) {
         this.ttsQueue.push(track);
@@ -359,7 +659,13 @@ class Player extends events_1.EventEmitter {
             void this.playNextTTS();
         }
     }
-    /** Play queued TTS items sequentially */
+    /**
+     * Play queued TTS items sequentially
+     *
+     * @returns {Promise<void>}
+     * @example
+     * await player.playNextTTS();
+     */
     async playNextTTS() {
         const next = this.ttsQueue.shift();
         if (!next)
@@ -415,33 +721,160 @@ class Player extends events_1.EventEmitter {
             }
         }
     }
+    /**
+     * Get cached plugin or find and cache a new one
+     * @param track The track to find plugin for
+     * @returns The matching plugin or null if not found
+     */
+    getCachedPlugin(track) {
+        const cacheKey = `${track.source}:${track.url}`;
+        const now = Date.now();
+        // Check if cache is still valid
+        const cachedTimestamp = this.pluginCacheTimestamps.get(cacheKey);
+        if (cachedTimestamp && now - cachedTimestamp < this.PLUGIN_CACHE_TTL) {
+            const cachedPlugin = this.pluginCache.get(cacheKey);
+            if (cachedPlugin) {
+                this.debug(`[PluginCache] Using cached plugin for ${track.source}: ${cachedPlugin.name}`);
+                return cachedPlugin;
+            }
+        }
+        // Find new plugin and cache it
+        this.debug(`[PluginCache] Finding plugin for track: ${track.title} (${track.source})`);
+        const plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
+        if (plugin) {
+            this.pluginCache.set(cacheKey, plugin);
+            this.pluginCacheTimestamps.set(cacheKey, now);
+            this.debug(`[PluginCache] Cached plugin: ${plugin.name} for ${track.source}`);
+            return plugin;
+        }
+        return null;
+    }
+    /**
+     * Clear expired cache entries
+     */
+    clearExpiredCache() {
+        const now = Date.now();
+        for (const [key, timestamp] of this.pluginCacheTimestamps.entries()) {
+            if (now - timestamp >= this.PLUGIN_CACHE_TTL) {
+                this.pluginCache.delete(key);
+                this.pluginCacheTimestamps.delete(key);
+                this.debug(`[PluginCache] Cleared expired cache entry: ${key}`);
+            }
+        }
+    }
+    /**
+     * Clear all plugin cache entries
+     * @example
+     * player.clearPluginCache();
+     */
+    clearPluginCache() {
+        const cacheSize = this.pluginCache.size;
+        this.pluginCache.clear();
+        this.pluginCacheTimestamps.clear();
+        this.debug(`[PluginCache] Cleared all ${cacheSize} cache entries`);
+    }
+    /**
+     * Get plugin cache statistics
+     * @returns Cache statistics
+     * @example
+     * const stats = player.getPluginCacheStats();
+     * console.log(`Cache size: ${stats.size}, Hit rate: ${stats.hitRate}%`);
+     */
+    getPluginCacheStats() {
+        const now = Date.now();
+        let expiredEntries = 0;
+        for (const timestamp of this.pluginCacheTimestamps.values()) {
+            if (now - timestamp >= this.PLUGIN_CACHE_TTL) {
+                expiredEntries++;
+            }
+        }
+        return {
+            size: this.pluginCache.size,
+            hitRate: 0, // Would need to track hits/misses to calculate this
+            expiredEntries,
+        };
+    }
     /** Build AudioResource for a given track using the plugin pipeline */
     async resourceFromTrack(track) {
-        // Resolve plugin similar to playNext
-        const plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
-        if (!plugin)
+        this.debug(`[ResourceFromTrack] Starting resource creation for track: ${track.title} (${track.source})`);
+        // Clear expired cache entries periodically
+        if (Math.random() < 0.1) {
+            // 10% chance to clean cache
+            this.clearExpiredCache();
+        }
+        // Resolve plugin using cache
+        const plugin = this.getCachedPlugin(track);
+        if (!plugin) {
+            this.debug(`[ResourceFromTrack] No plugin found for track: ${track.title} (${track.source})`);
             throw new Error(`No plugin found for track: ${track.title}`);
-        let streamInfo;
+        }
+        this.debug(`[ResourceFromTrack] Using plugin: ${plugin.name} for track: ${track.title}`);
+        let streamInfo = null;
+        const timeoutMs = this.options.extractorTimeout ?? 15000;
         try {
-            streamInfo = await this.withTimeout(plugin.getStream(track), "getStream timed out");
+            this.debug(`[ResourceFromTrack] Attempting getStream with ${plugin.name}, timeout: ${timeoutMs}ms`);
+            const startTime = Date.now();
+            streamInfo = await (0, timeout_1.withTimeout)(plugin.getStream(track), timeoutMs, "getStream timed out");
+            const duration = Date.now() - startTime;
+            this.debug(`[ResourceFromTrack] getStream successful with ${plugin.name} in ${duration}ms`);
+            if (!streamInfo?.stream) {
+                this.debug(`[ResourceFromTrack] getStream returned no stream from ${plugin.name}`);
+                throw new Error(`No stream returned from ${plugin.name}`);
+            }
         }
         catch (streamError) {
+            const errorMessage = streamError instanceof Error ? streamError.message : String(streamError);
+            this.debug(`[ResourceFromTrack] getStream failed with ${plugin.name}: ${errorMessage}`);
+            // Log more details for debugging
+            if (streamError instanceof Error && streamError.stack) {
+                this.debug(`[ResourceFromTrack] getStream error stack:`, streamError.stack);
+            }
             // try fallbacks
+            this.debug(`[ResourceFromTrack] Attempting fallback plugins for track: ${track.title}`);
             const allplugs = this.pluginManager.getAll();
+            let fallbackAttempts = 0;
             for (const p of allplugs) {
-                if (typeof p.getFallback !== "function")
+                if (typeof p.getFallback !== "function" && typeof p.getStream !== "function") {
+                    this.debug(`[ResourceFromTrack] Skipping plugin ${p.name} - no getFallback or getStream method`);
                     continue;
+                }
+                fallbackAttempts++;
+                this.debug(`[ResourceFromTrack] Trying fallback plugin ${p.name} (attempt ${fallbackAttempts})`);
                 try {
-                    streamInfo = await this.withTimeout(p.getFallback(track), `getFallback timed out for plugin ${p.name}`);
-                    if (!streamInfo?.stream)
-                        continue;
-                    break;
+                    // Try getStream first
+                    const startTime = Date.now();
+                    streamInfo = await (0, timeout_1.withTimeout)(p.getStream(track), timeoutMs, "getStream timed out");
+                    const duration = Date.now() - startTime;
+                    if (streamInfo?.stream) {
+                        this.debug(`[ResourceFromTrack] Fallback getStream successful with ${p.name} in ${duration}ms`);
+                        break;
+                    }
+                    // Try getFallback if getStream didn't work
+                    this.debug(`[ResourceFromTrack] Trying getFallback with ${p.name}`);
+                    const fallbackStartTime = Date.now();
+                    streamInfo = await (0, timeout_1.withTimeout)(p.getFallback(track), timeoutMs, `getFallback timed out for plugin ${p.name}`);
+                    const fallbackDuration = Date.now() - fallbackStartTime;
+                    if (streamInfo?.stream) {
+                        this.debug(`[ResourceFromTrack] Fallback getFallback successful with ${p.name} in ${fallbackDuration}ms`);
+                        break;
+                    }
+                    this.debug(`[ResourceFromTrack] Fallback plugin ${p.name} returned no stream`);
+                }
+                catch (fallbackError) {
+                    const errorMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+                    this.debug(`[ResourceFromTrack] Fallback plugin ${p.name} failed: ${errorMessage}`);
+                    // Log more details for debugging
+                    if (fallbackError instanceof Error && fallbackError.stack) {
+                        this.debug(`[ResourceFromTrack] Fallback error stack:`, fallbackError.stack);
+                    }
                 }
-                catch { }
             }
-            if (!streamInfo?.stream)
+            if (!streamInfo?.stream) {
+                this.debug(`[ResourceFromTrack] All ${fallbackAttempts} fallback attempts failed for track: ${track.title}`);
                 throw new Error(`All getFallback attempts failed for track: ${track.title}`);
+            }
         }
+        this.debug(`[ResourceFromTrack] Stream obtained, type: ${streamInfo.type}, metadata keys: ${Object.keys(streamInfo.metadata || {}).join(", ")}`);
         const mapToStreamType = (type) => {
             switch (type) {
                 case "webm/opus":
@@ -454,15 +887,20 @@ class Player extends events_1.EventEmitter {
             }
         };
         const inputType = mapToStreamType(streamInfo.type);
-        return (0, voice_1.createAudioResource)(streamInfo.stream, {
+        this.debug(`[ResourceFromTrack] Creating AudioResource with inputType: ${inputType}`);
+        // Merge metadata safely
+        const mergedMetadata = {
+            ...track,
+            ...(streamInfo.metadata || {}),
+        };
+        const audioResource = (0, voice_1.createAudioResource)(streamInfo.stream, {
             // Prefer plugin-provided metadata (e.g., precise duration), fallback to track fields
-            metadata: {
-                ...track,
-                ...(streamInfo?.metadata || {}),
-            },
+            metadata: mergedMetadata,
             inputType,
             inlineVolume: true,
         });
+        this.debug(`[ResourceFromTrack] AudioResource created successfully for track: ${track.title}`);
+        return audioResource;
     }
     async generateWillNext() {
         const lastTrack = this.queue.previousTracks[this.queue.previousTracks.length - 1] ?? this.queue.currentTrack;
@@ -475,10 +913,10 @@ class Player extends events_1.EventEmitter {
         for (const p of candidates) {
             try {
                 this.debug(`[Player] Trying related from plugin: ${p.name}`);
-                const related = await this.withTimeout(p.getRelatedTracks(lastTrack.url, {
+                const related = await (0, timeout_1.withTimeout)(p.getRelatedTracks(lastTrack.url, {
                     limit: 10,
                     history: this.queue.previousTracks,
-                }), `getRelatedTracks timed out for ${p.name}`);
+                }), this.options.extractorTimeout ?? 15000, `getRelatedTracks timed out for ${p.name}`);
                 if (Array.isArray(related) && related.length > 0) {
                     const randomchoice = Math.floor(Math.random() * related.length);
                     const nextTrack = this.queue.nextTrack ? this.queue.nextTrack : related[randomchoice];
@@ -529,6 +967,14 @@ class Player extends events_1.EventEmitter {
             return this.playNext();
         }
     }
+    /**
+     * Pause the current track
+     *
+     * @returns {boolean} True if paused successfully
+     * @example
+     * const paused = player.pause();
+     * console.log(`Paused: ${paused}`);
+     */
     pause() {
         this.debug(`[Player] pause called`);
         if (this.isPlaying && !this.isPaused) {
@@ -536,6 +982,14 @@ class Player extends events_1.EventEmitter {
         }
         return false;
     }
+    /**
+     * Resume the current track
+     *
+     * @returns {boolean} True if resumed successfully
+     * @example
+     * const resumed = player.resume();
+     * console.log(`Resumed: ${resumed}`);
+     */
     resume() {
         this.debug(`[Player] resume called`);
         if (this.isPaused) {
@@ -551,6 +1005,14 @@ class Player extends events_1.EventEmitter {
         }
         return false;
     }
+    /**
+     * Stop the current track
+     *
+     * @returns {boolean} True if stopped successfully
+     * @example
+     * const stopped = player.stop();
+     * console.log(`Stopped: ${stopped}`);
+     */
     stop() {
         this.debug(`[Player] stop called`);
         this.queue.clear();
@@ -560,6 +1022,14 @@ class Player extends events_1.EventEmitter {
         this.emit("playerStop");
         return result;
     }
+    /**
+     * Skip to the next track
+     *
+     * @returns {boolean} True if skipped successfully
+     * @example
+     * const skipped = player.skip();
+     * console.log(`Skipped: ${skipped}`);
+     */
     skip() {
         this.debug(`[Player] skip called`);
         if (this.isPlaying || this.isPaused) {
@@ -570,6 +1040,11 @@ class Player extends events_1.EventEmitter {
     }
     /**
      * Go back to the previous track in history and play it.
+     *
+     * @returns {Promise<boolean>} True if previous track was played successfully
+     * @example
+     * const previous = await player.previous();
+     * console.log(`Previous: ${previous}`);
      */
     async previous() {
         this.debug(`[Player] previous called`);
@@ -581,12 +1056,39 @@ class Player extends events_1.EventEmitter {
         this.clearLeaveTimeout();
         return this.startTrack(track);
     }
+    /**
+     * Loop the current track
+     *
+     * @param {LoopMode} mode - The loop mode to set
+     * @returns {LoopMode} The loop mode
+     * @example
+     * const loopMode = player.loop("track");
+     * console.log(`Loop mode: ${loopMode}`);
+     */
     loop(mode) {
         return this.queue.loop(mode);
     }
+    /**
+     * Set the auto-play mode
+     *
+     * @param {boolean} mode - The auto-play mode to set
+     * @returns {boolean} The auto-play mode
+     * @example
+     * const autoPlayMode = player.autoPlay(true);
+     * console.log(`Auto-play mode: ${autoPlayMode}`);
+     */
     autoPlay(mode) {
         return this.queue.autoPlay(mode);
     }
+    /**
+     * Set the volume of the current track
+     *
+     * @param {number} volume - The volume to set
+     * @returns {boolean} True if volume was set successfully
+     * @example
+     * const volumeSet = player.setVolume(50);
+     * console.log(`Volume set: ${volumeSet}`);
+     */
     setVolume(volume) {
         this.debug(`[Player] setVolume called: ${volume}`);
         if (volume < 0 || volume > 200)
@@ -614,10 +1116,24 @@ class Player extends events_1.EventEmitter {
         this.emit("volumeChange", oldVolume, volume);
         return true;
     }
+    /**
+     * Shuffle the queue
+     *
+     * @returns {void}
+     * @example
+     * player.shuffle();
+     */
     shuffle() {
         this.debug(`[Player] shuffle called`);
         this.queue.shuffle();
     }
+    /**
+     * Clear the queue
+     *
+     * @returns {void}
+     * @example
+     * player.clearQueue();
+     */
     clearQueue() {
         this.debug(`[Player] clearQueue called`);
         this.queue.clear();
@@ -627,6 +1143,14 @@ class Player extends events_1.EventEmitter {
      * - If `query` is a string, performs a search and inserts resulting tracks (playlist supported).
      * - If a Track or Track[] is provided, inserts directly.
      * Does not auto-start playback; it only modifies the queue.
+     *
+     * @param {string | Track | Track[]} query - The track or tracks to insert
+     * @param {number} index - The index to insert the tracks at
+     * @param {string} requestedBy - The user ID who requested the insert
+     * @returns {Promise<boolean>} True if the tracks were inserted successfully
+     * @example
+     * const inserted = await player.insert("Song Name", 0, userId);
+     * console.log(`Inserted: ${inserted}`);
      */
     async insert(query, index, requestedBy) {
         try {
@@ -667,6 +1191,15 @@ class Player extends events_1.EventEmitter {
             return false;
         }
     }
+    /**
+     * Remove a track from the queue
+     *
+     * @param {number} index - The index of the track to remove
+     * @returns {Track | null} The removed track or null
+     * @example
+     * const removed = player.remove(0);
+     * console.log(`Removed: ${removed?.title}`);
+     */
     remove(index) {
         this.debug(`[Player] remove called for index: ${index}`);
         const track = this.queue.remove(index);
@@ -675,6 +1208,15 @@ class Player extends events_1.EventEmitter {
         }
         return track;
     }
+    /**
+     * Get the progress bar of the current track
+     *
+     * @param {ProgressBarOptions} options - The options for the progress bar
+     * @returns {string} The progress bar
+     * @example
+     * const progressBar = player.getProgressBar();
+     * console.log(`Progress bar: ${progressBar}`);
+     */
     getProgressBar(options = {}) {
         const { size = 20, barChar = "▬", progressChar = "🔘" } = options;
         const track = this.queue.currentTrack;
@@ -690,6 +1232,14 @@ class Player extends events_1.EventEmitter {
         const bar = barChar.repeat(progress) + progressChar + barChar.repeat(size - progress);
         return `${this.formatTime(current)} | ${bar} | ${this.formatTime(total)}`;
     }
+    /**
+     * Get the time of the current track
+     *
+     * @returns {Object} The time of the current track
+     * @example
+     * const time = player.getTime();
+     * console.log(`Time: ${time.current}`);
+     */
     getTime() {
         const resource = this.currentResource;
         const track = this.queue.currentTrack;
@@ -706,6 +1256,15 @@ class Player extends events_1.EventEmitter {
             format: this.formatTime(resource.playbackDuration),
         };
     }
+    /**
+     * Format the time in the format of HH:MM:SS
+     *
+     * @param {number} ms - The time in milliseconds
+     * @returns {string} The formatted time
+     * @example
+     * const formattedTime = player.formatTime(1000);
+     * console.log(`Formatted time: ${formattedTime}`);
+     */
     formatTime(ms) {
         const totalSeconds = Math.floor(ms / 1000);
         const hours = Math.floor(totalSeconds / 3600);
@@ -730,6 +1289,13 @@ class Player extends events_1.EventEmitter {
             }, this.options.leaveTimeout);
         }
     }
+    /**
+     * Destroy the player
+     *
+     * @returns {void}
+     * @example
+     * player.destroy();
+     */
     destroy() {
         this.debug(`[Player] destroy called`);
         if (this.leaveTimeout) {
@@ -750,30 +1316,92 @@ class Player extends events_1.EventEmitter {
         }
         this.queue.clear();
         this.pluginManager.clear();
+        for (const extension of [...this.extensions]) {
+            this.invokeExtensionLifecycle(extension, "onDestroy");
+            if (extension.player === this) {
+                extension.player = null;
+            }
+        }
+        this.extensions = [];
         this.isPlaying = false;
         this.isPaused = false;
         this.emit("playerDestroy");
         this.removeAllListeners();
     }
-    // Getters
+    /**
+     * Get the size of the queue
+     *
+     * @returns {number} The size of the queue
+     * @example
+     * const queueSize = player.queueSize;
+     * console.log(`Queue size: ${queueSize}`);
+     */
     get queueSize() {
         return this.queue.size;
     }
+    /**
+     * Get the current track
+     *
+     * @returns {Track | null} The current track or null
+     * @example
+     * const currentTrack = player.currentTrack;
+     * console.log(`Current track: ${currentTrack?.title}`);
+     */
     get currentTrack() {
         return this.queue.currentTrack;
     }
+    /**
+     * Get the previous track
+     *
+     * @returns {Track | null} The previous track or null
+     * @example
+     * const previousTrack = player.previousTrack;
+     * console.log(`Previous track: ${previousTrack?.title}`);
+     */
     get previousTrack() {
         return this.queue.previousTracks?.at(-1) ?? null;
     }
+    /**
+     * Get the upcoming tracks
+     *
+     * @returns {Track[]} The upcoming tracks
+     * @example
+     * const upcomingTracks = player.upcomingTracks;
+     * console.log(`Upcoming tracks: ${upcomingTracks.length}`);
+     */
     get upcomingTracks() {
         return this.queue.getTracks();
     }
+    /**
+     * Get the previous tracks
+     *
+     * @returns {Track[]} The previous tracks
+     * @example
+     * const previousTracks = player.previousTracks;
+     * console.log(`Previous tracks: ${previousTracks.length}`);
+     */
     get previousTracks() {
         return this.queue.previousTracks;
     }
+    /**
+     * Get the available plugins
+     *
+     * @returns {string[]} The available plugins
+     * @example
+     * const availablePlugins = player.availablePlugins;
+     * console.log(`Available plugins: ${availablePlugins.length}`);
+     */
     get availablePlugins() {
         return this.pluginManager.getAll().map((p) => p.name);
     }
+    /**
+     * Get the related tracks
+     *
+     * @returns {Track[] | null} The related tracks or null
+     * @example
+     * const relatedTracks = player.relatedTracks;
+     * console.log(`Related tracks: ${relatedTracks?.length}`);
+     */
     get relatedTracks() {
         return this.queue.relatedTracks();
     }