ziplayer 0.0.8 → 0.1.0

package/src/structures/PlayerManager.ts

@@ -1,6 +1,8 @@
 import { EventEmitter } from "events";
 import { Player } from "./Player";
 import { PlayerManagerOptions, PlayerOptions, Track, SourcePlugin, SearchResult } from "../types";
+import type { BaseExtension } from "../extensions";
+import { withTimeout } from "../utils/timeout";
 
 const GLOBAL_MANAGER_KEY: symbol = Symbol.for("ziplayer.PlayerManager.instance");
 export const getGlobalManager = (): PlayerManager | null => {
@@ -23,15 +25,49 @@ const setGlobalManager = (instance: PlayerManager): void => {
 	}
 };
 
+/**
+ * The main class for managing players across multiple Discord guilds.
+ *
+ * @example
+ * // Basic setup with plugins and extensions
+ * const manager = new PlayerManager({
+ *   plugins: [
+ *     new YouTubePlugin(),
+ *     new SoundCloudPlugin(),
+ *     new SpotifyPlugin(),
+ *     new TTSPlugin({ defaultLang: "en" })
+ *   ],
+ *   extensions: [
+ *     new voiceExt(null, { lang: "en-US" }),
+ *     new lavalinkExt(null, {
+ *       nodes: [{ host: "localhost", port: 2333, password: "youshallnotpass" }]
+ *     })
+ *   ],
+ *   extractorTimeout: 10000
+ * });
+ *
+ * // Create a player for a guild
+ * const player = await manager.create(guildId, {
+ *   tts: { interrupt: true, volume: 1 },
+ *   leaveOnEnd: true,
+ *   leaveTimeout: 30000
+ * });
+ *
+ * // Get existing player
+ * const existingPlayer = manager.get(guildId);
+ * if (existingPlayer) {
+ *   await existingPlayer.play("Never Gonna Give You Up", userId);
+ * }
+ */
 export class PlayerManager extends EventEmitter {
 	private static instance: PlayerManager | null = null;
 	private players: Map<string, Player> = new Map();
-	static default(opt?: PlayerOptions): Player {
+	static async default(opt?: PlayerOptions): Promise<Player> {
 		let globaldef = getGlobalManager();
 		if (!globaldef) {
 			globaldef = new PlayerManager({});
 		}
-		return globaldef.create("default", opt);
+		return await globaldef.create("default", opt);
 	}
 	private plugins: SourcePlugin[];
 	private extensions: any[];
@@ -79,7 +115,42 @@ export class PlayerManager extends EventEmitter {
 		throw new Error("Invalid guild or guildId provided.");
 	}
 
-	create(guildOrId: string | { id: string }, options?: PlayerOptions): Player {
+	/**
+	 * Create a new player for a guild
+	 *
+	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
+	 * @param {PlayerOptions} options - Player configuration options
+	 * @returns {Promise<Player>} The created player instance
+	 *
+	 * @example
+	 * // Create player with basic options
+	 * const player = await manager.create(guildId, {
+	 *   tts: { interrupt: true, volume: 1 },
+	 *   leaveOnEnd: true,
+	 *   leaveTimeout: 30000
+	 * });
+	 *
+	 * // Create player with advanced options
+	 * const advancedPlayer = await manager.create(guild, {
+	 *   volume: 0.8,
+	 *   quality: "high",
+	 *   selfDeaf: false,
+	 *   selfMute: false,
+	 *   tts: {
+	 *     createPlayer: true,
+	 *     interrupt: true,
+	 *     volume: 1.0,
+	 *     Max_Time_TTS: 30000
+	 *   },
+	 *   userdata: { customData: "example" }
+	 * });
+	 *
+	 * // Connect and play immediately
+	 * await player.connect(voiceChannel);
+	 * await player.play("Never Gonna Give You Up", userId);
+	 */
+
+	async create(guildOrId: string | { id: string }, options?: PlayerOptions): Promise<Player> {
 		const guildId = this.resolveGuildId(guildOrId);
 		if (this.players.has(guildId)) {
 			return this.players.get(guildId)!;
@@ -116,14 +187,26 @@ export class PlayerManager extends EventEmitter {
 				}
 			}
 			if (instance && typeof instance === "object") {
-				if ("player" in instance && !instance.player) instance.player = player;
-				if (typeof instance.active === "function") {
+				const extInstance = instance as BaseExtension;
+				if ("player" in extInstance && !extInstance.player) extInstance.player = player;
+				player.attachExtension(extInstance);
+				if (typeof extInstance.active === "function") {
+					let activated: boolean | void = true;
 					try {
-						instance.active({ manager: this, player });
-						this.debug(`[PlayerManager] Extension ${instance?.name} active`);
+						activated = await withTimeout(
+							Promise.resolve(extInstance.active({ manager: this, player })),
+							player.options.extractorTimeout ?? 15000,
+							`Extension ${extInstance?.name} activation timed out`,
+						);
+						this.debug(`[PlayerManager] Extension ${extInstance?.name} active`);
 					} catch (e) {
+						activated = false;
 						this.debug(`[PlayerManager] Extension activation error:`, e);
 					}
+					if (activated === false) {
+						player.detachExtension(extInstance);
+						continue;
+					}
 				}
 			}
 		}
@@ -158,15 +241,90 @@ export class PlayerManager extends EventEmitter {
 		return player;
 	}
 
+	/**
+	 * Get an existing player for a guild
+	 *
+	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
+	 * @returns {Player | undefined} The player instance or undefined if not found
+	 * @example
+	 * // Get player by guild ID
+	 * const player = manager.get(guildId);
+	 * if (player) {
+	 *   await player.play("Never Gonna Give You Up", userId);
+	 * } else {
+	 *   console.log("No player found for this guild");
+	 * }
+	 *
+	 * // Get player by guild object
+	 * const playerFromGuild = manager.get(guild);
+	 * if (playerFromGuild) {
+	 *   playerFromGuild.setVolume(0.5);
+	 * }
+	 *
+	 * // Check if player exists before using
+	 * const existingPlayer = manager.get(guildId);
+	 * if (existingPlayer && existingPlayer.playing) {
+	 *   existingPlayer.pause();
+	 * }
+	 */
+
 	get(guildOrId: string | { id: string }): Player | undefined {
 		const guildId = this.resolveGuildId(guildOrId);
 		return this.players.get(guildId);
 	}
 
+	/**
+	 * Get an existing player for a guild
+	 *
+	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
+	 * @returns {Player | undefined} The player instance or undefined
+	 * @example
+	 * const player = manager.get(guildId);
+	 * if (player) {
+	 *   await player.play("song name", userId);
+	 * }
+	 */
+	getPlayer(guildOrId: string | { id: string }): Player | undefined {
+		const guildId = this.resolveGuildId(guildOrId);
+		return this.players.get(guildId);
+	}
+
+	/**
+	 * Get all players
+	 *
+	 * @returns {Player[]} All player instances
+	 * @example
+	 * const players = manager.getall();
+	 * console.log(`Players: ${players.length}`);
+	 */
 	getall(): Player[] | [] {
 		return Array.from(this.players.values());
 	}
 
+	/**
+	 * Destroy a player and clean up resources
+	 *
+	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
+	 * @returns {boolean} True if player was destroyed, false if not found
+	 * @example
+	 * // Destroy player by guild ID
+	 * const destroyed = manager.delete(guildId);
+	 * if (destroyed) {
+	 *   console.log("Player destroyed successfully");
+	 * } else {
+	 *   console.log("No player found to destroy");
+	 * }
+	 *
+	 * // Destroy player by guild object
+	 * const destroyedFromGuild = manager.delete(guild);
+	 * console.log(`Player destroyed: ${destroyedFromGuild}`);
+	 *
+	 * // Clean up all players
+	 * for (const [guildId, player] of manager.players) {
+	 *   const destroyed = manager.delete(guildId);
+	 *   console.log(`Destroyed player for ${guildId}: ${destroyed}`);
+	 * }
+	 */
 	delete(guildOrId: string | { id: string }): boolean {
 		const guildId = this.resolveGuildId(guildOrId);
 		const player = this.players.get(guildId);
@@ -178,6 +336,15 @@ export class PlayerManager extends EventEmitter {
 		return false;
 	}
 
+	/**
+	 * Check if a player exists for a guild
+	 *
+	 * @param {string | {id: string}} guildOrId - Guild ID or guild object
+	 * @returns {boolean} True if player exists, false if not
+	 * @example
+	 * const exists = manager.has(guildId);
+	 * console.log(`Player exists: ${exists}`);
+	 */
 	has(guildOrId: string | { id: string }): boolean {
 		const guildId = this.resolveGuildId(guildOrId);
 		return this.players.has(guildId);
@@ -190,7 +357,14 @@ export class PlayerManager extends EventEmitter {
 	get debugEnabled(): boolean {
 		return this.B_debug;
 	}
-
+	/**
+	 * Destroy all players
+	 *
+	 * @returns {void}
+	 * @example
+	 * manager.destroy();
+	 * console.log(`All players destroyed`);
+	 */
 	destroy(): void {
 		this.debug(`[PlayerManager] Destroying all players`);
 		for (const player of this.players.values()) {
@@ -202,6 +376,13 @@ export class PlayerManager extends EventEmitter {
 
 	/**
 	 * Search using registered plugins without creating a Player.
+	 *
+	 * @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 manager.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(`[PlayerManager] Search called with query: ${query}, requestedBy: ${requestedBy}`);

package/src/structures/Queue.ts

@@ -1,5 +1,40 @@
 import { Track, LoopMode } from "../types";
 
+/**
+ * Manages the track queue for a player.
+ *
+ * @example
+ * // Basic queue operations
+ * const queue = player.queue;
+ *
+ * // Add single track
+ * queue.add(track);
+ *
+ * // Add multiple tracks
+ * queue.add([track1, track2, track3]);
+ *
+ * // Queue controls
+ * queue.shuffle(); // Randomize order
+ * queue.clear(); // Remove all tracks
+ * queue.autoPlay(true); // Enable auto-play
+ *
+ * // Get queue information
+ * console.log(`Queue length: ${queue.length}`);
+ * console.log(`Current track: ${queue.current?.title}`);
+ * console.log(`Is empty: ${queue.isEmpty}`);
+ * console.log(`Is playing: ${queue.isPlaying}`);
+ *
+ * // Loop modes
+ * queue.setLoopMode("track"); // Loop current track
+ * queue.setLoopMode("queue"); // Loop entire queue
+ * queue.setLoopMode("off"); // No loop
+ *
+ * // Remove specific track
+ * const removed = queue.remove(0); // Remove first track
+ * if (removed) {
+ *   console.log(`Removed: ${removed.title}`);
+ * }
+ */
 export class Queue {
 	private tracks: Track[] = [];
 	private current: Track | null = null;
@@ -9,15 +44,37 @@ export class Queue {
 	private _loop: LoopMode = "off";
 	private willnext: Track | null = null;
 
+	/**
+	 * Add track(s) to the queue
+	 *
+	 * @param {Track | Track[]} track - Track or array of tracks to add
+	 * @example
+	 * queue.add(track);
+	 * queue.add([track1, track2, track3]);
+	 */
 	add(track: Track): void {
 		this.tracks.push(track);
 	}
 
+	/**
+	 * Add multiple tracks to the queue
+	 *
+	 * @param {Track[]} tracks - Tracks to add
+	 * @example
+	 * queue.addMultiple([track1, track2, track3]);
+	 */
 	addMultiple(tracks: Track[]): void {
 		this.tracks.push(...tracks);
 	}
 
-	/** Insert a track at a specific upcoming position (0 = next) */
+	/**
+	 * Insert a track at a specific upcoming position (0 = next)
+	 *
+	 * @param {Track} track - Track to insert
+	 * @param {number} index - Index to insert the track at
+	 * @example
+	 * queue.insert(track, 0);
+	 */
 	insert(track: Track, index: number): void {
 		if (!Number.isFinite(index)) {
 			this.tracks.push(track);
@@ -35,7 +92,14 @@ export class Queue {
 		this.tracks.splice(i, 0, track);
 	}
 
-	/** Insert multiple tracks at a specific upcoming position, preserving order */
+	/**
+	 * Insert multiple tracks at a specific upcoming position, preserving order
+	 *
+	 * @param {Track[]} tracks - Tracks to insert
+	 * @param {number} index - Index to insert the tracks at
+	 * @example
+	 * queue.insertMultiple([track1, track2, track3], 0);
+	 */
 	insertMultiple(tracks: Track[], index: number): void {
 		if (!Array.isArray(tracks) || tracks.length === 0) return;
 		if (!Number.isFinite(index)) {
@@ -54,11 +118,30 @@ export class Queue {
 		this.tracks.splice(i, 0, ...tracks);
 	}
 
+	/**
+	 * Remove a track from the queue
+	 *
+	 * @param {number} index - Index of track to remove
+	 * @returns {Track | null} Removed track or null
+	 * @example
+	 * const removed = queue.remove(0);
+	 * console.log(`Removed: ${removed?.title}`);
+	 */
+
 	remove(index: number): Track | null {
 		if (index < 0 || index >= this.tracks.length) return null;
 		return this.tracks.splice(index, 1)[0];
 	}
 
+	/**
+	 * Get the next track in the queue
+	 *
+	 * @param {boolean} ignoreLoop - Ignore the loop mode
+	 * @returns {Track | null} The next track or null
+	 * @example
+	 * const nextTrack = queue.next();
+	 * console.log(`Next track: ${nextTrack?.title}`);
+	 */
 	next(ignoreLoop = false): Track | null {
 		if (this.current) {
 			if (this._loop === "track" && !ignoreLoop) {
@@ -78,10 +161,26 @@ export class Queue {
 		return this.current;
 	}
 
+	/**
+	 * Clear all tracks from the queue
+	 *
+	 * @example
+	 * queue.clear();
+	 */
 	clear(): void {
 		this.tracks = [];
 	}
 
+	/**
+	 * Enable or disable auto-play
+	 *
+	 * @param {boolean} value - Enable/disable auto-play
+	 * @returns {boolean} Current auto-play state
+	 * @example
+	 * queue.autoPlay(true);
+	 * queue.autoPlay(); // Get current auto-play state
+	 */
+
 	autoPlay(value?: boolean): boolean {
 		if (typeof value !== "undefined") {
 			this._autoPlay = value;
@@ -89,6 +188,14 @@ export class Queue {
 		return this._autoPlay;
 	}
 
+	/**
+	 * Set the loop mode
+	 *
+	 * @param {LoopMode} mode - Loop mode to set
+	 * @returns {LoopMode} The loop mode
+	 * @example
+	 * queue.loop("track");
+	 */
 	loop(mode?: LoopMode): LoopMode {
 		if (mode) {
 			this._loop = mode;
@@ -96,6 +203,13 @@ export class Queue {
 		return this._loop;
 	}
 
+	/**
+	 * Shuffle the queue
+	 *
+	 * @example
+	 * queue.shuffle();
+	 */
+
 	shuffle(): void {
 		for (let i = this.tracks.length - 1; i > 0; i--) {
 			const j = Math.floor(Math.random() * (i + 1));
@@ -103,22 +217,62 @@ export class Queue {
 		}
 	}
 
+	/**
+	 * Get the size of the queue
+	 *
+	 * @returns {number} The size of the queue
+	 * @example
+	 * const size = queue.size;
+	 * console.log(`Queue size: ${size}`);
+	 */
 	get size(): number {
 		return this.tracks.length;
 	}
 
+	/**
+	 * Check if the queue is empty
+	 *
+	 * @returns {boolean} True if the queue is empty
+	 * @example
+	 * const empty = queue.isEmpty;
+	 * console.log(`Queue is empty: ${empty}`);
+	 */
 	get isEmpty(): boolean {
 		return this.tracks.length === 0;
 	}
 
+	/**
+	 * Get the current track
+	 *
+	 * @returns {Track | null} The current track or null
+	 * @example
+	 * const currentTrack = queue.currentTrack;
+	 * console.log(`Current track: ${currentTrack?.title}`);
+	 */
 	get currentTrack(): Track | null {
 		return this.current;
 	}
 
+	/**
+	 * Get the previous tracks
+	 *
+	 * @returns {Track[]} The previous tracks
+	 * @example
+	 * const previousTracks = queue.previousTracks;
+	 * console.log(`Previous tracks: ${previousTracks.length}`);
+	 */
 	get previousTracks(): Track[] {
 		return [...this.history];
 	}
 
+	/**
+	 * Get the next track
+	 *
+	 * @returns {Track | null} The next track or null
+	 * @example
+	 * const nextTrack = queue.nextTrack;
+	 * console.log(`Next track: ${nextTrack?.title}`);
+	 */
 	get nextTrack(): Track | null {
 		return this.tracks[0] || null;
 	}
@@ -126,6 +280,11 @@ export class Queue {
 	/**
 	 * Move back to the previously played track.
 	 * Makes the current track the next upcoming track, then sets previous as current.
+	 *
+	 * @returns {Track | null} The previous track or null
+	 * @example
+	 * const previousTrack = queue.previous();
+	 * console.log(`Previous track: ${previousTrack?.title}`);
 	 */
 	previous(): Track | null {
 		if (this.history.length === 0) return null;
@@ -136,6 +295,15 @@ export class Queue {
 		return this.current;
 	}
 
+	/**
+	 * Get the next track
+	 *
+	 * @param {Track} track - The next track
+	 * @returns {Track | null} The next track or null
+	 * @example
+	 * const nextTrack = queue.willNextTrack();
+	 * console.log(`Next track: ${nextTrack?.title}`);
+	 */
 	willNextTrack(track?: Track): Track | null {
 		if (track) {
 			this.willnext = track;
@@ -143,6 +311,15 @@ export class Queue {
 		return this.willnext;
 	}
 
+	/**
+	 * Get the related tracks
+	 *
+	 * @param {Track[]} track - The related tracks
+	 * @returns {Track[] | null} The related tracks or null
+	 * @example
+	 * const relatedTracks = queue.relatedTracks();
+	 * console.log(`Related tracks: ${relatedTracks?.length}`);
+	 */
 	relatedTracks(track?: Track[]): Track[] | null {
 		if (track) {
 			this.related = track;
@@ -150,10 +327,27 @@ export class Queue {
 		return this.related;
 	}
 
+	/**
+	 * Get the tracks
+	 *
+	 * @returns {Track[]} The tracks
+	 * @example
+	 * const tracks = queue.getTracks();
+	 * console.log(`Tracks: ${tracks.length}`);
+	 */
 	getTracks(): Track[] {
 		return [...this.tracks];
 	}
 
+	/**
+	 * Get a track at a specific index
+	 *
+	 * @param {number} index - The index of the track
+	 * @returns {Track | null} The track or null
+	 * @example
+	 * const track = queue.getTrack(0);
+	 * console.log(`Track: ${track?.title}`);
+	 */
 	getTrack(index: number): Track | null {
 		return this.tracks[index] || null;
 	}