ziplayer 0.3.2 → 0.3.4

package/src/types/extension.ts

@@ -47,6 +47,9 @@ export interface SourceExtension {
 export interface ExtensionContext {
 	player: Player;
 	manager: PlayerManager;
+	playNext?: () => Promise<void>;
+	skip?: () => void;
+	emit?: (event: string, ...args: any[]) => void;
 }
 
 /**

package/src/types/index.ts

@@ -4,6 +4,12 @@ import type { PlayerManager } from "../structures/PlayerManager";
 import type { AudioFilter } from "./fillter";
 import type { SourcePluginLike } from "./plugin";
 import type { AudioResource } from "@discordjs/voice";
+
+export enum PlaybackMode {
+	NATIVE = "native",
+	REMOTE = "remote",
+	FORWARD = "forward",
+}
 /**
  * Represents a music track with metadata and streaming information.
  *
@@ -118,8 +124,50 @@ export interface SearchScore {
  */
 export interface StreamInfo {
 	stream: Readable;
-	type: "webm/opus" | "ogg/opus" | "arbitrary";
+	type: "webm/opus" | "ogg/opus" | "arbitrary" | string;
 	metadata?: Record<string, any>;
+
+	remote?: boolean;
+
+	handle?: {
+		play(): Promise<void>;
+		stop(): Promise<void>;
+		pause(): Promise<void>;
+		resume(): Promise<void>;
+		seek(position: number): Promise<void>;
+		setVolume(volume: number): Promise<void>;
+		destroy(): Promise<void>;
+	};
+}
+
+/** Passed to each {@link TrackMiddleware} run (before stream resolution). */
+export interface TrackMiddlewareContext {
+	player: Player;
+	manager: PlayerManager;
+}
+
+/**
+ * Runs immediately before stream extraction (`Player.getStream`): after enqueue, before extension `provideStream` and plugins.
+ * Prefer mutating `track` in place (especially `metadata`). If you return another object, its fields are merged into the original
+ * `track` reference so queue/current-track pointers stay valid.
+ */
+export type TrackMiddleware = (track: Track, context: TrackMiddlewareContext) => void | Track | Promise<void | Track>;
+
+/** Options for {@link PlayerManager.subscribeForwardMirror}. */
+export interface PlaybackMirrorOptions {
+	leaderGuildId: string;
+	followerGuildIds: string[];
+	/**
+	 * When enabled, follower connections subscribe directly
+	 * to leader.audioPlayer
+	 * Default: true
+	 */
+	forwardMode?: boolean;
+}
+
+export function normalizeTrackMiddleware(input?: TrackMiddleware | TrackMiddleware[]): TrackMiddleware[] {
+	if (!input) return [];
+	return Array.isArray(input) ? input : [input];
 }
 
 /**
@@ -302,6 +350,11 @@ export interface PlayerOptions {
 		 */
 		limiterCeiling?: number;
 	};
+	/**
+	 * Chain of middleware applied to every track immediately before stream extraction (after queueing).
+	 * Merged after {@link PlayerManagerOptions.trackMiddleware} from the manager.
+	 */
+	trackMiddleware?: TrackMiddleware | TrackMiddleware[];
 }
 
 export interface PlayerManagerOptions {
@@ -312,6 +365,10 @@ export interface PlayerManagerOptions {
 	cleanupInterval?: number; // Cleanup interval in ms
 	enableSearchCache?: boolean; // Enable search result caching
 	enableStatsCollection?: boolean; // Enable stats collection events
+	/**
+	 * Global track middleware for every {@link Player} created from this manager (before per-player middleware).
+	 */
+	trackMiddleware?: TrackMiddleware | TrackMiddleware[];
 }
 
 /**
@@ -381,12 +438,28 @@ export interface PreloadState {
 	isBeingUsed: boolean;
 }
 
+export interface ForwardHealthStatus {
+	guildId: string;
+	healthy: boolean;
+	role: "leader" | "follower" | "none";
+	issues: string[];
+	details: {
+		leaderId?: string;
+		followerCount?: number;
+		connectionState?: string;
+		audioPlayerState?: string;
+	};
+}
+
 export interface PlayerStats {
 	totalPlayers: number;
+	leader: number;
+	follower: number;
 	activePlayers: number;
 	pausedPlayers: number;
 	connectedPlayers: number;
 	totalTracksInQueue: number;
+	forwardHealthStatus: ForwardHealthStatus[];
 }
 
 export interface StreamSlot {
@@ -507,7 +580,10 @@ export interface ManagerEvents {
 	lyricsChange: [player: Player, track: Track, lyrics: any];
 	voiceCreate: [player: Player, evt: any];
 	stats: [stats: PlayerStats];
-	streamError: [error: Error, track: Track | null];
+	streamError: [player: Player, error: Error, track: Track | null];
+
+	forwardModeStart: [player: Player, leader: Player];
+	forwardModeEnd: [player: Player, leader: Player, reason: string | undefined];
 }
 export interface PlayerEvents {
 	debug: [message: string, ...args: any[]];
@@ -541,6 +617,8 @@ export interface PlayerEvents {
 	streamError: [error: Error, track: Track | null];
 	/** Emitted when player stats are updated (if enabled) */
 	stats: [stats: PlayerStats];
+	forwardModeStart: [leader: Player];
+	forwardModeEnd: [leader: Player, reason: string | undefined];
 }
 
 export * from "./fillter";