ziplayer 0.3.1 → 0.3.3

package/src/structures/PlayerManager.ts

@@ -1,8 +1,20 @@
 import { EventEmitter } from "events";
 import { Player } from "./Player";
-import { PlayerManagerOptions, PlayerOptions, Track, SourcePlugin, SearchResult, ManagerEvents, PlayerStats } from "../types";
+import {
+	PlayerManagerOptions,
+	PlayerOptions,
+	type Track,
+	SourcePlugin,
+	SearchResult,
+	ManagerEvents,
+	PlayerStats,
+	type PlaybackMirrorOptions,
+	type TrackMiddleware,
+	normalizeTrackMiddleware,
+} from "../types";
 import type { BaseExtension } from "../extensions";
 import { withTimeout } from "../utils/timeout";
+import { PluginManager } from "../plugins";
 
 const GLOBAL_MANAGER_KEY: symbol = Symbol.for("ziplayer.PlayerManager.instance");
 
@@ -92,12 +104,15 @@ export class PlayerManager extends EventEmitter {
 	}
 
 	private plugins: SourcePlugin[];
+	private pluginManager: PluginManager;
 	private extensions: any[];
 	private B_debug: boolean = false;
 	private extractorTimeout: number = 10000;
 	private autoCleanup: boolean = true;
 	private cleanupTimeout: number = 60000; // 1 minute
 	private enableSearchCache: boolean = true;
+	private trackMiddlewareFromOptions: TrackMiddleware[] = [];
+	private playbackMirrorUnsubscribes = new Map<string, () => void>();
 
 	private debug(message?: any, ...optionalParams: any[]): void {
 		if (this.listenerCount("debug") > 0) {
@@ -111,17 +126,26 @@ export class PlayerManager extends EventEmitter {
 	constructor(options: PlayerManagerOptions = {}) {
 		super();
 		this.plugins = [];
+		this.pluginManager = new PluginManager(null as any, this, {
+			extractorTimeout: this.extractorTimeout,
+		});
 		this.searchCache = new Map();
 
 		// Initialize plugins
 		const provided = options.plugins || [];
 		for (const p of provided as any[]) {
 			try {
+				let instance: SourcePlugin | null = null;
+
 				if (p && typeof p === "object") {
-					this.plugins.push(p as SourcePlugin);
+					instance = p as SourcePlugin;
 				} else if (typeof p === "function") {
-					const instance = new (p as any)();
-					this.plugins.push(instance as SourcePlugin);
+					instance = new (p as any)();
+				}
+
+				if (instance) {
+					this.plugins.push(instance);
+					this.pluginManager.register(instance);
 				}
 				this.debug(`Registered plugin: ${p.name || "unnamed"}`);
 			} catch (e) {
@@ -134,6 +158,7 @@ export class PlayerManager extends EventEmitter {
 		this.autoCleanup = options.autoCleanup ?? true;
 		this.cleanupTimeout = options.cleanupInterval ?? 60000;
 		this.enableSearchCache = options.enableSearchCache ?? true;
+		this.trackMiddlewareFromOptions = normalizeTrackMiddleware(options.trackMiddleware);
 
 		// Setup auto cleanup
 		if (this.autoCleanup) {
@@ -149,11 +174,6 @@ export class PlayerManager extends EventEmitter {
 		this.debug(`Initialized with ${this.plugins.length} plugins, ${this.extensions.length} extensions`);
 	}
 
-	private withTimeout<T>(promise: Promise<T>, message: string): Promise<T> {
-		const timeout = this.extractorTimeout;
-		return Promise.race([promise, new Promise<never>((_, reject) => setTimeout(() => reject(new Error(message)), timeout))]);
-	}
-
 	private resolveGuildId(guildOrId: string | { id: string }): string {
 		if (typeof guildOrId === "string") return guildOrId;
 		if (guildOrId && typeof guildOrId === "object" && "id" in guildOrId) return guildOrId.id;
@@ -571,12 +591,208 @@ export class PlayerManager extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Like {@link broadcast} but awaits every return value (for async methods such as `play`).
+	 * Uses `Promise.allSettled` — failures are captured per guild, not thrown as a whole.
+	 */
+	async broadcastAsync(action: string, ...args: any[]): Promise<PromiseSettledResult<unknown>[]> {
+		const pending: Promise<unknown>[] = [];
+		for (const player of this.players.values()) {
+			const fn = (player as any)[action];
+			if (typeof fn !== "function") continue;
+			try {
+				pending.push(Promise.resolve(fn.apply(player, args)));
+			} catch (error) {
+				pending.push(Promise.reject(error));
+			}
+		}
+		return Promise.allSettled(pending);
+	}
+
+	/**
+	 * Broadcast a player method only to the given guild ids (players must already exist).
+	 */
+	broadcastGuilds(guildIds: readonly string[], action: string, ...args: any[]): void {
+		const wanted = new Set(guildIds);
+		for (const player of this.players.values()) {
+			if (!wanted.has(player.guildId)) continue;
+			if (typeof (player as any)[action] === "function") {
+				try {
+					(player as any)[action](...args);
+				} catch (error) {
+					this.debug(`Error broadcasting ${action} to ${player.guildId}:`, error);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Global {@link TrackMiddleware} configured on this manager (applied before per-player middleware).
+	 */
+	getTrackMiddlewareChain(): TrackMiddleware[] {
+		return [...this.trackMiddlewareFromOptions];
+	}
+
+	/**
+	 * Mirror playback controls from a leader guild to follower guilds (each guild must already have a {@link Player} via
+	 * {@link create}). Followers receive the same track on `trackStart`, and pause/resume/stop/volume from the leader when
+	 * applicable.
+	 *
+	 * @returns Unsubscribe function — also runs when the leader player is destroyed.
+	 */
+	subscribePlaybackMirror(options: PlaybackMirrorOptions): () => void {
+		const leader = this.get(options.leaderGuildId);
+		if (!leader) {
+			throw new Error(`subscribePlaybackMirror: no player for leader guild ${options.leaderGuildId}`);
+		}
+
+		const followers = [...new Set(options.followerGuildIds)].filter((id) => id !== options.leaderGuildId);
+		const mirrorUserId = options.mirrorUserId;
+		const syncVolume = options.syncVolume ?? true;
+		const forwardMode = options.forwardMode ?? true;
+
+		const existing = this.playbackMirrorUnsubscribes.get(options.leaderGuildId);
+		existing?.();
+
+		const runFollowers = (fn: (p: Player) => void | Promise<void>) => {
+			for (const gid of followers) {
+				const fp = this.get(gid);
+				if (!fp) {
+					this.debug(`Playback mirror: no player for follower guild ${gid}`);
+					continue;
+				}
+				Promise.resolve(fn(fp)).catch((e) => this.debug(`Playback mirror follower error (${gid}):`, e));
+			}
+		};
+
+		const onTrackStart = async (track: Track) => {
+			if (!forwardMode) {
+				runFollowers(async (fp) => {
+					fp.stop();
+					await fp.play(track, mirrorUserId);
+				});
+				return;
+			}
+
+			runFollowers((fp) => {
+				if (!fp.connection || !leader.connection) {
+					this.debug(`Playback mirror forwardMode: missing connection for follower ${fp.guildId}`);
+					return;
+				}
+
+				try {
+					// sync state
+					fp.queue.clear();
+
+					// optional fake current track sync
+					if (track) {
+						fp.queue.setCurrentTrack(track);
+					}
+
+					// subscribe directly to leader player
+					fp.subscribeTo(leader);
+					fp.isPlaying = leader.isPlaying;
+					fp.isPaused = leader.isPaused;
+
+					fp.emit("trackStart", track);
+					this.debug(`Playback mirror forwardMode subscribed ${fp.guildId} -> ${leader.guildId}`);
+				} catch (e) {
+					this.debug(`Playback mirror forwardMode error (${fp.guildId}):`, e);
+				}
+			});
+		};
+
+		const onPause = () => {
+			runFollowers((fp) => {
+				if (forwardMode) {
+					fp.isPaused = true;
+					fp.isPlaying = false;
+					return;
+				}
+
+				fp.pause();
+			});
+		};
+
+		const onResume = () => {
+			runFollowers((fp) => {
+				if (forwardMode) {
+					fp.isPaused = false;
+					fp.isPlaying = true;
+					return;
+				}
+
+				fp.resume();
+			});
+		};
+
+		const onStop = () => {
+			runFollowers((fp) => {
+				if (forwardMode) {
+					try {
+						fp.connection?.subscribe(fp.audioPlayer);
+
+						fp.isPlaying = false;
+						fp.isPaused = false;
+
+						fp.audioPlayer.stop(true);
+					} catch {}
+					return;
+				}
+
+				fp.stop();
+			});
+		};
+
+		const onVolume = (_oldVol: number, newVol: number) => {
+			if (!syncVolume) return;
+			runFollowers((fp) => {
+				fp.setVolume(newVol);
+			});
+		};
+
+		let closed = false;
+		const unsubscribe = () => {
+			if (closed) return;
+			closed = true;
+			leader.off("trackStart", onTrackStart);
+			leader.off("playerPause", onPause);
+			leader.off("playerResume", onResume);
+			leader.off("playerStop", onStop);
+			leader.off("volumeChange", onVolume);
+			leader.off("playerDestroy", onLeaderDestroy);
+			onStop();
+			this.playbackMirrorUnsubscribes.delete(options.leaderGuildId);
+		};
+
+		const onLeaderDestroy = () => {
+			unsubscribe();
+		};
+
+		leader.on("trackStart", onTrackStart);
+		leader.on("playerPause", onPause);
+		leader.on("playerResume", onResume);
+		leader.on("playerStop", onStop);
+		leader.on("volumeChange", onVolume);
+		leader.on("playerDestroy", onLeaderDestroy);
+		if (leader?.currentTrack) onTrackStart(leader.currentTrack);
+		this.playbackMirrorUnsubscribes.set(options.leaderGuildId, unsubscribe);
+		return unsubscribe;
+	}
+
 	/**
 	 * Destroy all players and clean up
 	 */
 	destroy(): void {
 		this.debug(`Destroying all players`);
 
+		for (const unsub of this.playbackMirrorUnsubscribes.values()) {
+			try {
+				unsub();
+			} catch {}
+		}
+		this.playbackMirrorUnsubscribes.clear();
+
 		// Stop cleanup intervals
 		if (this.cleanupInterval) {
 			clearInterval(this.cleanupInterval);
@@ -600,30 +816,42 @@ export class PlayerManager extends EventEmitter {
 	}
 
 	/**
-	 * Search using registered plugins without creating a Player.
+	 * Search using PluginManager 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
+	 * Uses the same search pipeline as Player.search():
+	 * - cache
+	 * - plugin deduplication
+	 * - plugin scoring/evaluation
+	 * - fallback handling
+	 *
+	 * @param {string} query
+	 * @param {string} requestedBy
+	 * @returns {Promise<SearchResult>}
 	 */
 	async search(query: string, requestedBy: string): Promise<SearchResult> {
 		this.debug(`Search called with query: ${query}, requestedBy: ${requestedBy}`);
 
-		// Check cache first
+		// Cache
 		const cached = this.getCachedSearch(query);
 		if (cached) {
 			return cached;
 		}
 
-		const plugin = this.plugins.find((p) => p.canHandle(query));
-		if (!plugin) {
-			this.debug(`No plugin found to handle: ${query}`);
-			throw new Error(`No plugin found to handle: ${query}`);
-		}
-
 		try {
-			const result = await this.withTimeout(plugin.search(query, requestedBy), "Search operation timed out");
+			const result = await this.pluginManager.search(query, requestedBy);
+
+			if (!result || !Array.isArray(result.tracks) || result.tracks.length === 0) {
+				throw new Error(`No results found for: ${query}`);
+			}
+
+			this.debug(`Plugin search returned ${result.tracks.length} tracks (score: ${result.score?.score ?? "unknown"}%)`);
+
+			if (result.score) {
+				this.debug(`Search evaluation - ${result.score.reason}`);
+			}
+
 			this.setCachedSearch(query, result);
+
 			return result;
 		} catch (error) {
 			this.debug(`Search error:`, error);
@@ -647,9 +875,10 @@ export class PlayerManager extends EventEmitter {
 	 */
 	registerPlugin(plugin: SourcePlugin): void {
 		this.plugins.push(plugin);
+		this.pluginManager.register(plugin);
+
 		this.debug(`Registered plugin: ${plugin.name}`);
 
-		// Register plugin with all existing players
 		for (const player of this.players.values()) {
 			player.addPlugin(plugin);
 		}
@@ -666,9 +895,10 @@ export class PlayerManager extends EventEmitter {
 		if (index === -1) return false;
 
 		this.plugins.splice(index, 1);
+		this.pluginManager.unregister(name);
+
 		this.debug(`Unregistered plugin: ${name}`);
 
-		// Note: Cannot easily remove plugins from existing players
 		return true;
 	}
 

package/src/structures/PreloadManager.ts

@@ -0,0 +1,274 @@
+import { createAudioResource, AudioResource } from "@discordjs/voice";
+import type { Track, StreamInfo, StreamSlot } from "../types";
+import type { StreamManager } from "./StreamManager";
+
+interface PreloadManagerDeps {
+	streamManager: StreamManager;
+	debug: (message?: any, ...optionalParams: any[]) => void;
+	getNextTrack: () => Track | null;
+	getStream: (track: Track) => Promise<StreamInfo | null>;
+	isDestroyed: () => boolean;
+	isEnabled: () => boolean;
+}
+
+export class PreloadManager {
+	private readonly streamManager: StreamManager;
+	private readonly debugLog: (message?: any, ...optionalParams: any[]) => void;
+	private readonly getNextTrack: () => Track | null;
+	private readonly getStream: (track: Track) => Promise<StreamInfo | null>;
+	private readonly isDestroyed: () => boolean;
+	private readonly isEnabled: () => boolean;
+
+	private preloadLock = false;
+	private readonly preloadSlot: StreamSlot = {
+		resource: null,
+		track: null,
+		streamId: null,
+		abortController: null,
+		isValid: false,
+		isLoading: false,
+		loadPromise: null,
+	};
+
+	constructor(deps: PreloadManagerDeps) {
+		this.streamManager = deps.streamManager;
+		this.debugLog = deps.debug;
+		this.getNextTrack = deps.getNextTrack;
+		this.getStream = deps.getStream;
+		this.isDestroyed = deps.isDestroyed;
+		this.isEnabled = deps.isEnabled;
+	}
+
+	public hasValidPreload(track: Track): boolean {
+		return !!(
+			this.preloadSlot.isValid &&
+			this.preloadSlot.track?.id === track.id &&
+			this.preloadSlot.resource &&
+			this.preloadSlot.resource.playStream?.readable !== false
+		);
+	}
+
+	public promoteToCurrent(track: Track, currentSlot: StreamSlot): AudioResource | null {
+		const promotedResource = this.preloadSlot.resource;
+		const promotedStreamId = this.preloadSlot.streamId;
+		if (!promotedResource) return null;
+
+		currentSlot.resource = promotedResource;
+		currentSlot.track = track;
+		currentSlot.streamId = promotedStreamId;
+		currentSlot.abortController = null;
+		currentSlot.isValid = true;
+		currentSlot.isLoading = false;
+		currentSlot.loadPromise = null;
+
+		this.preloadSlot.resource = null;
+		this.preloadSlot.track = null;
+		this.preloadSlot.streamId = null;
+		this.preloadSlot.abortController = null;
+		this.preloadSlot.isValid = false;
+		this.preloadSlot.isLoading = false;
+		this.preloadSlot.loadPromise = null;
+
+		return promotedResource;
+	}
+
+	public async preloadNextTrack(): Promise<void> {
+		if (this.isDestroyed()) return;
+		if (!this.isEnabled()) {
+			this.debugLog(`[Preload] Disabled by options/runtime profile`);
+			return;
+		}
+
+		if (this.preloadLock) {
+			this.debugLog(`[Preload] Already preloading, skipping`);
+			return;
+		}
+
+		const nextTrack = this.getNextTrack();
+		if (!nextTrack) {
+			this.debugLog(`[Preload] No next track to preload`);
+			return;
+		}
+
+		if (this.preloadSlot.isValid && this.preloadSlot.track?.id === nextTrack.id && this.preloadSlot.resource) {
+			this.debugLog(`[Preload] Already have valid preload for: ${nextTrack.title}`);
+			return;
+		}
+
+		if (this.preloadSlot.isLoading && this.preloadSlot.track?.id === nextTrack.id) {
+			this.debugLog(`[Preload] Currently loading same track, waiting...`);
+			if (this.preloadSlot.loadPromise) {
+				await this.preloadSlot.loadPromise;
+			}
+			return;
+		}
+
+		if (this.preloadSlot.isValid && this.preloadSlot.track?.id !== nextTrack.id) {
+			this.debugLog(`[Preload] Cancelling old preload for different track: ${this.preloadSlot.track?.title}`);
+			await this.safeCancelPreload();
+		}
+
+		this.preloadLock = true;
+		const abortController = new AbortController();
+		this.preloadSlot.track = nextTrack;
+		this.preloadSlot.abortController = abortController;
+		this.preloadSlot.isLoading = true;
+
+		const loadPromise = this.executePreload(nextTrack, abortController);
+		this.preloadSlot.loadPromise = loadPromise;
+
+		try {
+			await loadPromise;
+		} catch (err) {
+			if (err instanceof Error && err.message === "PRELOAD_CANCELLED") {
+				this.debugLog(`[Preload] Cancelled for ${nextTrack.title}`);
+			} else {
+				this.debugLog(`[Preload] Failed for ${nextTrack.title}:`, err);
+			}
+			this.clearPreloadSlot();
+		} finally {
+			this.preloadLock = false;
+			this.preloadSlot.isLoading = false;
+			this.preloadSlot.loadPromise = null;
+		}
+	}
+
+	public async safeCancelPreload(): Promise<void> {
+		if (!this.preloadSlot.abortController && !this.preloadSlot.resource) {
+			return;
+		}
+
+		this.debugLog(`[Preload] Safely cancelling preload for: ${this.preloadSlot.track?.title || "unknown"}`);
+
+		if (this.preloadSlot.abortController) {
+			this.preloadSlot.abortController.abort();
+			this.preloadSlot.abortController = null;
+		}
+
+		if (this.preloadSlot.streamId) {
+			this.streamManager.unregisterStream(this.preloadSlot.streamId, true);
+		}
+
+		if (this.preloadSlot.resource) {
+			try {
+				const stream = this.preloadSlot.resource.playStream;
+				if (stream && typeof stream.destroy === "function" && !stream.destroyed) {
+					stream.destroy();
+				}
+			} catch {
+				// ignore
+			}
+		}
+
+		this.clearPreloadSlot();
+	}
+
+	public cancelPreload(): void {
+		if (this.preloadSlot.abortController) {
+			this.debugLog(`[Preload] Cancelling preload for: ${this.preloadSlot.track?.title}`);
+			this.preloadSlot.abortController.abort();
+		}
+		if (this.preloadSlot.streamId) {
+			this.streamManager.unregisterStream(this.preloadSlot.streamId, true);
+		}
+		this.clearPreloadSlot();
+	}
+
+	public clearPreloadSlot(): void {
+		if (this.preloadSlot.resource) {
+			try {
+				const stream = this.preloadSlot.resource.playStream;
+				if (stream && typeof stream.destroy === "function" && !stream.destroyed) {
+					stream.destroy();
+				}
+			} catch {
+				// ignore
+			}
+		}
+
+		if (this.preloadSlot.streamId) {
+			this.streamManager.unregisterStream(this.preloadSlot.streamId, true);
+		}
+
+		this.preloadSlot.resource = null;
+		this.preloadSlot.track = null;
+		this.preloadSlot.streamId = null;
+		this.preloadSlot.abortController = null;
+		this.preloadSlot.isValid = false;
+		this.preloadSlot.isLoading = false;
+		this.preloadSlot.loadPromise = null;
+	}
+
+	private async executePreload(track: Track, abortController: AbortController): Promise<void> {
+		if (this.isDestroyed()) throw new Error("PLAYER_DESTROYED");
+		this.debugLog(`[Preload] Starting preload for: ${track.title}`);
+
+		if (abortController.signal.aborted) {
+			throw new Error("PRELOAD_CANCELLED");
+		}
+
+		if (this.getNextTrack()?.id !== track.id) {
+			this.debugLog(`[Preload] Track changed, cancelling`);
+			throw new Error("PRELOAD_CANCELLED");
+		}
+
+		const streamInfo = await this.getStreamWithCancel(track, abortController.signal);
+		if (abortController.signal.aborted) {
+			throw new Error("PRELOAD_CANCELLED");
+		}
+		if (this.getNextTrack()?.id !== track.id) {
+			this.debugLog(`[Preload] Track changed after stream fetch`);
+			throw new Error("PRELOAD_CANCELLED");
+		}
+		if (!streamInfo?.stream) {
+			throw new Error(`No stream available`);
+		}
+
+		const streamId = this.streamManager.registerStream(streamInfo.stream, track, {
+			source: track.source || "preload",
+			isPreload: true,
+			priority: 5,
+		});
+
+		const resource = createAudioResource(streamInfo.stream, {
+			inlineVolume: true,
+			metadata: { ...track, preloaded: true },
+		});
+
+		if (!resource.playStream || resource.playStream.readable === false) {
+			throw new Error("Resource not readable");
+		}
+
+		this.preloadSlot.resource = resource;
+		this.preloadSlot.streamId = streamId;
+		this.preloadSlot.isValid = true;
+		this.preloadSlot.track = track;
+
+		this.debugLog(`[Preload] Successfully preloaded: ${track.title} (Stream ID: ${streamId})`);
+	}
+
+	private async getStreamWithCancel(track: Track, signal: AbortSignal): Promise<StreamInfo | null> {
+		if (this.isDestroyed()) throw new Error("PLAYER_DESTROYED");
+		const abortPromise = new Promise<never>((_, reject) => {
+			if (signal.aborted) {
+				reject(new Error("PRELOAD_CANCELLED"));
+				return;
+			}
+			const handler = () => {
+				signal.removeEventListener("abort", handler);
+				reject(new Error("PRELOAD_CANCELLED"));
+			};
+			signal.addEventListener("abort", handler);
+		});
+
+		const existingStream = this.streamManager.getStreamByTrack(track.id || track.title);
+		if (existingStream && !existingStream.destroyed && existingStream.readable !== false) {
+			this.debugLog(`[Stream] Using existing stream for preload: ${track.title}`);
+			return { stream: existingStream, type: "arbitrary" };
+		}
+
+		const streamPromise = this.getStream(track);
+		const result = await Promise.race([streamPromise, abortPromise]);
+		return result as StreamInfo | null;
+	}
+}

package/src/structures/Queue.ts

@@ -400,6 +400,28 @@ export class Queue {
 		return this.current;
 	}
 
+	/**
+	 * Force set current playing track.
+	 *
+	 * Mainly used internally for playback synchronization,
+	 * playback mirroring, restoring player state,
+	 * or forward-mode shared audio sessions.
+	 *
+	 * This does NOT modify queue order/history automatically.
+	 * It only updates the current active track reference.
+	 *
+	 * @param {Track | null} track - Track to set as current
+	 *
+	 * @example
+	 * queue.setCurrentTrack(track);
+	 *
+	 * @example
+	 * queue.setCurrentTrack(null);
+	 */
+	setCurrentTrack(track: Track | null): void {
+		this.current = track;
+	}
+	
 	/**
 	 * Get the previous tracks
 	 */