ziplayer 0.0.9 → 0.1.1

package/src/structures/Player.ts

@@ -15,15 +15,70 @@ import {
 
 import { VoiceChannel } from "discord.js";
 import { Readable } from "stream";
-import { Track, PlayerOptions, PlayerEvents, SourcePlugin, SearchResult, ProgressBarOptions, LoopMode } from "../types";
+import { BaseExtension } from "../extensions";
+import {
+	Track,
+	PlayerOptions,
+	PlayerEvents,
+	SourcePlugin,
+	SearchResult,
+	ProgressBarOptions,
+	LoopMode,
+	StreamInfo,
+} from "../types";
+import type {
+	ExtensionContext,
+	ExtensionPlayRequest,
+	ExtensionPlayResponse,
+	ExtensionAfterPlayPayload,
+	ExtensionStreamRequest,
+	ExtensionSearchRequest,
+} from "../types";
 import { Queue } from "./Queue";
 import { PluginManager } from "../plugins";
+import { withTimeout } from "../utils/timeout";
 import type { PlayerManager } from "./PlayerManager";
 export declare interface Player {
 	on<K extends keyof PlayerEvents>(event: K, listener: (...args: PlayerEvents[K]) => void): this;
 	emit<K extends keyof PlayerEvents>(event: K, ...args: PlayerEvents[K]): boolean;
 }
 
+/**
+ * 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");
+ * });
+ *
+ */
 export class Player extends EventEmitter {
 	public readonly guildId: string;
 	public connection: VoiceConnection | null = null;
@@ -40,83 +95,264 @@ export class Player extends EventEmitter {
 	private currentResource: AudioResource | null = null;
 	private volumeInterval: NodeJS.Timeout | null = null;
 	private skipLoop = false;
+	private extensions: BaseExtension[] = [];
+	private extensionContext!: ExtensionContext;
+
+	// Cache for plugin matching to improve performance
+	private pluginCache = new Map<string, SourcePlugin>();
+	private readonly PLUGIN_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+	private pluginCacheTimestamps = new Map<string, number>();
 
 	/**
-	 * Start playing a specific track immediately, replacing the current resource.
+	 * Attach an extension to the player
+	 *
+	 * @param {BaseExtension} extension - The extension to attach
+	 * @example
+	 * player.attachExtension(new MyExtension());
 	 */
-	private async startTrack(track: Track): Promise<boolean> {
+	public attachExtension(extension: BaseExtension): void {
+		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());
+	 */
+	public detachExtension(extension: BaseExtension): void {
+		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}`);
+	 */
+	public getExtensions(): readonly BaseExtension[] {
+		return this.extensions;
+	}
+
+	private invokeExtensionLifecycle(extension: BaseExtension, hook: "onRegister" | "onDestroy"): void {
+		const fn = (extension as any)[hook];
+		if (typeof fn !== "function") return;
 		try {
-			// Find plugin that can handle this track
-			const plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
+			const result = fn.call(extension, this.extensionContext);
+			if (result && typeof (result as Promise<unknown>).then === "function") {
+				(result as Promise<unknown>).catch((err) => this.debug(`[Player] Extension ${extension.name} ${hook} error:`, err));
+			}
+		} catch (err) {
+			this.debug(`[Player] Extension ${extension.name} ${hook} error:`, err);
+		}
+	}
+
+	private async runBeforePlayHooks(
+		initial: ExtensionPlayRequest,
+	): Promise<{ request: ExtensionPlayRequest; response: ExtensionPlayResponse }> {
+		const request: ExtensionPlayRequest = { ...initial };
+		const response: ExtensionPlayResponse = {};
+		for (const extension of this.extensions) {
+			const hook = (extension as any).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 };
+	}
+
+	private async runAfterPlayHooks(payload: ExtensionAfterPlayPayload): Promise<void> {
+		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 as any).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);
+			}
+		}
+	}
 
-			if (!plugin) {
-				this.debug(`[Player] No plugin found for track: ${track.title}`);
-				throw new Error(`No plugin found for track: ${track.title}`);
+	private async extensionsProvideSearch(query: string, requestedBy: string): Promise<SearchResult | null> {
+		const request: ExtensionSearchRequest = { query, requestedBy };
+		for (const extension of this.extensions) {
+			const hook = (extension as any).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 as SearchResult;
+				}
+			} catch (err) {
+				this.debug(`[Player] Extension ${extension.name} provideSearch error:`, err);
 			}
+		}
+		return null;
+	}
 
-			this.debug(`[Player] Getting stream for track: ${track.title}`);
-			this.debug(`[Player] Using plugin: ${plugin.name}`);
-			this.debug(`[Track] Track Info:`, track);
-			let streamInfo;
+	private async extensionsProvideStream(track: Track): Promise<StreamInfo | null> {
+		const request: ExtensionStreamRequest = { track };
+		for (const extension of this.extensions) {
+			const hook = (extension as any).provideStream;
+			if (typeof hook !== "function") continue;
 			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 as any).getFallback !== "function") {
-						continue;
+				const result = await Promise.resolve(hook.call(extension, this.extensionContext, request));
+				if (result && (result as StreamInfo).stream) {
+					this.debug(`[Player] Extension ${extension.name} provided stream for track: ${track.title}`);
+					return result as StreamInfo;
+				}
+			} catch (err) {
+				this.debug(`[Player] Extension ${extension.name} provideStream error:`, err);
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Start playing a specific track immediately, replacing the current resource.
+	 */
+	private async startTrack(track: Track): Promise<boolean> {
+		try {
+			let streamInfo: StreamInfo | null = await this.extensionsProvideStream(track);
+			let plugin: SourcePlugin | undefined;
+
+			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 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 as any).getFallback !== "function") {
+							continue;
+						}
+						try {
+							streamInfo = await withTimeout(
+								(p as any).getFallback(track),
+								this.options.extractorTimeout ?? 15000,
+								`getFallback timed out for plugin ${p.name}`,
+							);
+							if (!(streamInfo as any)?.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);
+						}
 					}
-					try {
-						streamInfo = await this.withTimeout((p as any).getFallback(track), `getFallback timed out for plugin ${p.name}`);
-						if (!(streamInfo as any).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);
+					if (!(streamInfo as any)?.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 (!(streamInfo as any)?.stream) {
-					throw new Error(`All getFallback attempts failed for track: ${track.title}`);
-				}
+			if (plugin) {
 				this.debug(streamInfo);
 			}
 
-			function mapToStreamType(type: string): StreamType {
-				switch (type) {
-					case "webm/opus":
-						return StreamType.WebmOpus;
-					case "ogg/opus":
-						return StreamType.OggOpus;
-					case "arbitrary":
-						return StreamType.Arbitrary;
-					default:
-						return StreamType.Arbitrary;
+			// Kiểm tra nếu có stream thực sự để tạo AudioResource
+			if (streamInfo && (streamInfo as any).stream) {
+				function mapToStreamType(type: string | undefined): StreamType {
+					switch (type) {
+						case "webm/opus":
+							return StreamType.WebmOpus;
+						case "ogg/opus":
+							return StreamType.OggOpus;
+						case "arbitrary":
+						default:
+							return StreamType.Arbitrary;
+					}
 				}
-			}
 
-			let stream: Readable = (streamInfo as any).stream;
-			let inputType = mapToStreamType((streamInfo as any).type);
+				const stream: Readable = (streamInfo as StreamInfo).stream;
+				const inputType = mapToStreamType((streamInfo as StreamInfo).type);
 
-			this.currentResource = createAudioResource(stream, {
-				metadata: track,
-				inputType,
-				inlineVolume: true,
-			});
+				this.currentResource = 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);
+				// 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);
+				this.debug(`[Player] Playing resource for track: ${track.title}`);
+				this.audioPlayer.play(this.currentResource);
 
-			await entersState(this.audioPlayer, AudioPlayerStatus.Playing, 5_000);
-			return true;
+				await entersState(this.audioPlayer, AudioPlayerStatus.Playing, 5_000);
+				return true;
+			} else if (streamInfo && !(streamInfo as any).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}`);
+			}
 		} catch (error) {
 			this.debug(`[Player] startTrack error:`, error);
 			this.emit("playerError", error as Error, track);
@@ -136,11 +372,6 @@ export class Player extends EventEmitter {
 		}
 	}
 
-	private withTimeout<T>(promise: Promise<T>, message: string): Promise<T> {
-		const timeout = this.options.extractorTimeout ?? 15000;
-		return Promise.race([promise, new Promise<never>((_, reject) => setTimeout(() => reject(new Error(message)), timeout))]);
-	}
-
 	private debug(message?: any, ...optionalParams: any[]): void {
 		if (this.listenerCount("debug") > 0) {
 			this.emit("debug", message, ...optionalParams);
@@ -184,6 +415,7 @@ export class Player extends 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) {
@@ -272,6 +504,14 @@ export class Player extends EventEmitter {
 		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: VoiceChannel): Promise<VoiceConnection> {
 		try {
 			this.debug(`[Player] Connecting to voice channel: ${channel.id}`);
@@ -307,15 +547,34 @@ export class Player extends EventEmitter {
 		}
 	}
 
+	/**
+	 * 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: string, requestedBy: string): Promise<SearchResult> {
 		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: any = 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 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;
@@ -333,23 +592,63 @@ export class Player extends EventEmitter {
 		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: string | Track, requestedBy?: string): Promise<boolean> {
+		this.debug(`[Player] Play called with query: ${typeof query === "string" ? query : query?.title}`);
+		this.clearLeaveTimeout();
+		let tracksToAdd: Track[] = [];
+		let isPlaylist = false;
+		let effectiveRequest: ExtensionPlayRequest = { query, requestedBy };
+		let hookResponse: ExtensionPlayResponse = {};
+
 		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: Track[] = [];
-			let isPlaylist = false;
-			if (typeof query === "string") {
-				const searchResult = await this.search(query, requestedBy || "Unknown");
-				tracksToAdd = searchResult.tracks;
+			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: ExtensionAfterPlayPayload = {
+					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 as Track];
 			}
 
 			if (tracksToAdd.length === 0) {
@@ -357,7 +656,6 @@ export class Player extends EventEmitter {
 				throw new Error("No tracks found");
 			}
 
-			// If a TTS track is requested and interrupt mode is enabled, handle it separately
 			const isTTS = (t: Track | undefined) => {
 				if (!t) return false;
 				try {
@@ -367,7 +665,8 @@ export class Player extends EventEmitter {
 				}
 			};
 
-			const queryLooksTTS = typeof query === "string" && query.trim().toLowerCase().startsWith("tts");
+			const queryLooksTTS =
+				typeof effectiveRequest.query === "string" && effectiveRequest.query.trim().toLowerCase().startsWith("tts");
 
 			if (
 				!isPlaylist &&
@@ -375,9 +674,15 @@ export class Player extends EventEmitter {
 				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;
 			}
 
@@ -385,17 +690,30 @@ export class Player extends EventEmitter {
 				this.queue.addMultiple(tracksToAdd);
 				this.emit("queueAddList", tracksToAdd);
 			} else {
-				this.queue.add(tracksToAdd?.[0]);
-				this.emit("queueAdd", tracksToAdd?.[0]);
+				this.queue.add(tracksToAdd[0]);
+				this.emit("queueAdd", tracksToAdd[0]);
 			}
 
-			// Start playing if not already playing
-			if (!this.isPlaying) {
-				return this.playNext();
-			}
+			const started = !this.isPlaying ? await this.playNext() : true;
 
-			return 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 as Error,
+			});
 			this.debug(`[Player] Play error:`, error);
 			this.emit("playerError", error as Error);
 			return false;
@@ -405,6 +723,11 @@ export class Player extends 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);
 	 */
 	public async interruptWithTTSTrack(track: Track): Promise<void> {
 		this.ttsQueue.push(track);
@@ -413,7 +736,13 @@ export class Player extends EventEmitter {
 		}
 	}
 
-	/** Play queued TTS items sequentially */
+	/**
+	 * Play queued TTS items sequentially
+	 *
+	 * @returns {Promise<void>}
+	 * @example
+	 * await player.playNextTTS();
+	 */
 	private async playNextTTS(): Promise<void> {
 		const next = this.ttsQueue.shift();
 		if (!next) return;
@@ -473,32 +802,195 @@ export class Player extends 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
+	 */
+	private getCachedPlugin(track: Track): SourcePlugin | null {
+		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
+	 */
+	private clearExpiredCache(): void {
+		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();
+	 */
+	public clearPluginCache(): void {
+		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}%`);
+	 */
+	public getPluginCacheStats(): { size: number; hitRate: number; expiredEntries: number } {
+		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 */
 	private async resourceFromTrack(track: Track): Promise<AudioResource> {
-		// Resolve plugin similar to playNext
-		const plugin = this.pluginManager.findPlugin(track.url) || this.pluginManager.get(track.source);
-		if (!plugin) throw new Error(`No plugin found for track: ${track.title}`);
+		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}`);
+		}
+
+		this.debug(`[ResourceFromTrack] Using plugin: ${plugin.name} for track: ${track.title}`);
+
+		let streamInfo: StreamInfo | null = null;
+		const timeoutMs = this.options.extractorTimeout ?? 15000;
 
-		let streamInfo: any;
 		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 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 as any).getFallback !== "function") continue;
+				if (typeof (p as any).getFallback !== "function" && typeof (p as any).getStream !== "function") {
+					this.debug(`[ResourceFromTrack] Skipping plugin ${(p as any).name} - no getFallback or getStream method`);
+					continue;
+				}
+
+				fallbackAttempts++;
+				this.debug(`[ResourceFromTrack] Trying fallback plugin ${(p as any).name} (attempt ${fallbackAttempts})`);
+
 				try {
-					streamInfo = await this.withTimeout(
+					// Try getStream first
+					const startTime = Date.now();
+					streamInfo = await withTimeout(p.getStream(track), timeoutMs, "getStream timed out");
+					const duration = Date.now() - startTime;
+
+					if (streamInfo?.stream) {
+						this.debug(`[ResourceFromTrack] Fallback getStream successful with ${(p as any).name} in ${duration}ms`);
+						break;
+					}
+
+					// Try getFallback if getStream didn't work
+					this.debug(`[ResourceFromTrack] Trying getFallback with ${(p as any).name}`);
+					const fallbackStartTime = Date.now();
+					streamInfo = await withTimeout(
 						(p as any).getFallback(track),
+						timeoutMs,
 						`getFallback timed out for plugin ${(p as any).name}`,
 					);
-					if (!streamInfo?.stream) continue;
-					break;
-				} catch {}
+					const fallbackDuration = Date.now() - fallbackStartTime;
+
+					if (streamInfo?.stream) {
+						this.debug(`[ResourceFromTrack] Fallback getFallback successful with ${(p as any).name} in ${fallbackDuration}ms`);
+						break;
+					}
+
+					this.debug(`[ResourceFromTrack] Fallback plugin ${(p as any).name} returned no stream`);
+				} catch (fallbackError) {
+					const errorMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+					this.debug(`[ResourceFromTrack] Fallback plugin ${(p as any).name} failed: ${errorMessage}`);
+
+					// Log more details for debugging
+					if (fallbackError instanceof Error && fallbackError.stack) {
+						this.debug(`[ResourceFromTrack] Fallback error stack:`, fallbackError.stack);
+					}
+				}
+			}
+
+			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}`);
 			}
-			if (!streamInfo?.stream) 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: string): StreamType => {
 			switch (type) {
 				case "webm/opus":
@@ -512,15 +1004,23 @@ export class Player extends EventEmitter {
 		};
 
 		const inputType = mapToStreamType(streamInfo.type);
-		return createAudioResource(streamInfo.stream, {
+		this.debug(`[ResourceFromTrack] Creating AudioResource with inputType: ${inputType}`);
+
+		// Merge metadata safely
+		const mergedMetadata = {
+			...track,
+			...(streamInfo.metadata || {}),
+		};
+
+		const audioResource = createAudioResource(streamInfo.stream, {
 			// Prefer plugin-provided metadata (e.g., precise duration), fallback to track fields
-			metadata: {
-				...(track as any),
-				...((streamInfo as any)?.metadata || {}),
-			},
+			metadata: mergedMetadata,
 			inputType,
 			inlineVolume: true,
 		});
+
+		this.debug(`[ResourceFromTrack] AudioResource created successfully for track: ${track.title}`);
+		return audioResource;
 	}
 
 	private async generateWillNext(): Promise<void> {
@@ -537,11 +1037,12 @@ export class Player extends EventEmitter {
 		for (const p of candidates) {
 			try {
 				this.debug(`[Player] Trying related from plugin: ${p.name}`);
-				const related = await this.withTimeout(
+				const related = await withTimeout(
 					(p as any).getRelatedTracks(lastTrack.url, {
 						limit: 10,
 						history: this.queue.previousTracks,
 					}),
+					this.options.extractorTimeout ?? 15000,
 					`getRelatedTracks timed out for ${p.name}`,
 				);
 
@@ -599,6 +1100,14 @@ export class Player extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Pause the current track
+	 *
+	 * @returns {boolean} True if paused successfully
+	 * @example
+	 * const paused = player.pause();
+	 * console.log(`Paused: ${paused}`);
+	 */
 	pause(): boolean {
 		this.debug(`[Player] pause called`);
 		if (this.isPlaying && !this.isPaused) {
@@ -607,6 +1116,14 @@ export class Player extends EventEmitter {
 		return false;
 	}
 
+	/**
+	 * Resume the current track
+	 *
+	 * @returns {boolean} True if resumed successfully
+	 * @example
+	 * const resumed = player.resume();
+	 * console.log(`Resumed: ${resumed}`);
+	 */
 	resume(): boolean {
 		this.debug(`[Player] resume called`);
 		if (this.isPaused) {
@@ -623,6 +1140,14 @@ export class Player extends EventEmitter {
 		return false;
 	}
 
+	/**
+	 * Stop the current track
+	 *
+	 * @returns {boolean} True if stopped successfully
+	 * @example
+	 * const stopped = player.stop();
+	 * console.log(`Stopped: ${stopped}`);
+	 */
 	stop(): boolean {
 		this.debug(`[Player] stop called`);
 		this.queue.clear();
@@ -633,6 +1158,15 @@ export class Player extends EventEmitter {
 		return result;
 	}
 
+	/**
+	 * Skip to the next track
+	 *
+	 * @returns {boolean} True if skipped successfully
+	 * @example
+	 * const skipped = player.skip();
+	 * console.log(`Skipped: ${skipped}`);
+	 */
+
 	skip(): boolean {
 		this.debug(`[Player] skip called`);
 		if (this.isPlaying || this.isPaused) {
@@ -644,6 +1178,11 @@ export class Player extends 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(): Promise<boolean> {
 		this.debug(`[Player] previous called`);
@@ -654,14 +1193,41 @@ export class Player extends EventEmitter {
 		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?: LoopMode): LoopMode {
 		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?: boolean): boolean {
 		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: number): boolean {
 		this.debug(`[Player] setVolume called: ${volume}`);
 		if (volume < 0 || volume > 200) return false;
@@ -693,11 +1259,25 @@ export class Player extends EventEmitter {
 		return true;
 	}
 
+	/**
+	 * Shuffle the queue
+	 *
+	 * @returns {void}
+	 * @example
+	 * player.shuffle();
+	 */
 	shuffle(): void {
 		this.debug(`[Player] shuffle called`);
 		this.queue.shuffle();
 	}
 
+	/**
+	 * Clear the queue
+	 *
+	 * @returns {void}
+	 * @example
+	 * player.clearQueue();
+	 */
 	clearQueue(): void {
 		this.debug(`[Player] clearQueue called`);
 		this.queue.clear();
@@ -708,6 +1288,14 @@ export class Player extends 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: string | Track | Track[], index: number, requestedBy?: string): Promise<boolean> {
 		try {
@@ -749,6 +1337,15 @@ export class Player extends EventEmitter {
 		}
 	}
 
+	/**
+	 * 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: number): Track | null {
 		this.debug(`[Player] remove called for index: ${index}`);
 		const track = this.queue.remove(index);
@@ -758,6 +1355,15 @@ export class Player extends 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: ProgressBarOptions = {}): string {
 		const { size = 20, barChar = "▬", progressChar = "🔘" } = options;
 		const track = this.queue.currentTrack;
@@ -775,6 +1381,14 @@ export class Player extends EventEmitter {
 		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;
@@ -794,6 +1408,15 @@ export class Player extends EventEmitter {
 		};
 	}
 
+	/**
+	 * 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: number): string {
 		const totalSeconds = Math.floor(ms / 1000);
 		const hours = Math.floor(totalSeconds / 3600);
@@ -820,6 +1443,13 @@ export class Player extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Destroy the player
+	 *
+	 * @returns {void}
+	 * @example
+	 * player.destroy();
+	 */
 	destroy(): void {
 		this.debug(`[Player] destroy called`);
 		if (this.leaveTimeout) {
@@ -843,36 +1473,99 @@ export class Player extends 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(): number {
 		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(): Track | null {
 		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(): Track | null {
 		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(): Track[] {
 		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(): Track[] {
 		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(): string[] {
 		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(): Track[] | null {
 		return this.queue.relatedTracks();
 	}