ziplayer 0.0.9 → 0.1.0

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,259 @@ 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;
 
 	/**
-	 * 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);
+		}
+	}
 
-			if (!plugin) {
-				this.debug(`[Player] No plugin found for track: ${track.title}`);
-				throw new Error(`No plugin found for track: ${track.title}`);
+	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 };
+	}
 
-			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 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 {
-				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;
+				await Promise.resolve(hook.call(extension, this.extensionContext, immutablePayload));
+			} catch (err) {
+				this.debug(`[Player] Extension ${extension.name} afterPlay error:`, err);
+			}
+		}
+	}
+
+	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;
+	}
+
+	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 {
+				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 +367,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 +410,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 +499,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 +542,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 +587,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 +651,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 +660,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 +669,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 +685,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 +718,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 +731,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;
@@ -448,8 +772,15 @@ export class Player extends EventEmitter {
 			// Derive timeout from resource/track duration when available, with a sensible cap
 			const md: any = (resource as any)?.metadata ?? {};
 			const declared =
-				typeof md.duration === "number" ? md.duration : typeof next?.duration === "number" ? next.duration : undefined;
-			const declaredMs = declared ? (declared > 1000 ? declared : declared * 1000) : undefined;
+				typeof md.duration === "number" ? md.duration
+				: typeof next?.duration === "number" ? next.duration
+				: undefined;
+			const declaredMs =
+				declared ?
+					declared > 1000 ?
+						declared
+					:	declared * 1000
+				:	undefined;
 			const cap = this.options?.tts?.Max_Time_TTS ?? 60_000;
 			const idleTimeout = declaredMs ? Math.min(cap, Math.max(1_000, declaredMs + 1_500)) : cap;
 			await entersState(ttsPlayer, AudioPlayerStatus.Idle, idleTimeout).catch(() => null);
@@ -481,15 +812,16 @@ export class Player extends EventEmitter {
 
 		let streamInfo: any;
 		try {
-			streamInfo = await this.withTimeout(plugin.getStream(track), "getStream timed out");
+			streamInfo = await withTimeout(plugin.getStream(track), this.options.extractorTimeout ?? 15000, "getStream timed out");
 		} catch (streamError) {
 			// try fallbacks
 			const allplugs = this.pluginManager.getAll();
 			for (const p of allplugs) {
 				if (typeof (p as any).getFallback !== "function") continue;
 				try {
-					streamInfo = await this.withTimeout(
+					streamInfo = await withTimeout(
 						(p as any).getFallback(track),
+						this.options.extractorTimeout ?? 15000,
 						`getFallback timed out for plugin ${(p as any).name}`,
 					);
 					if (!streamInfo?.stream) continue;
@@ -537,11 +869,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 +932,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 +948,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 +972,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 +990,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 +1010,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 +1025,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 +1091,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 +1120,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 +1169,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 +1187,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 +1213,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 +1240,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 +1275,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 +1305,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();
 	}