ryanlink 1.0.1

package/src/extensions/FairPlayExtension.ts

@@ -0,0 +1,154 @@
+import { PlayerPlugin } from "../core/PluginSystem";
+import type { Player } from "../core/RyanlinkPlayer";
+import type { Track } from "../audio/AudioTrack";
+
+interface PlayerWithGet extends Player {
+    get?<T>(key: string): T;
+}
+
+export interface FairPlayPluginEvents {
+    /**
+     * Emitted when fair play reorders the queue
+     */
+    fairPlayApplied: [player: Player, guildId: string, trackCount: number];
+}
+
+export interface FairPlayConfig {
+    enabled: boolean;
+    /** Minimum tracks before fair play kicks in */
+    minTracks: number;
+    /** Maximum consecutive tracks from same requester */
+    maxConsecutive: number;
+}
+
+/**
+ * Fair Play Plugin - Distributes tracks fairly among requesters
+ * Prevents one user from dominating the queue
+ */
+export class FairPlayPlugin extends PlayerPlugin<FairPlayPluginEvents & Record<string, unknown[]>> {
+    readonly name = "fairplay" as const;
+
+    #player!: Player;
+    config: FairPlayConfig = {
+        enabled: true,
+        minTracks: 5,
+        maxConsecutive: 3,
+    };
+
+    init(player: Player): void {
+        this.#player = player;
+
+        const config = (player as PlayerWithGet).get?.("fairplay_config");
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+
+        // Apply fair play when tracks are added
+        player.on("trackAdd", (p, g, t) => {
+            void this.#handleTrackAdd(p, g, t);
+        });
+    }
+
+    #handleTrackAdd(_player: Player, guildId: string, _tracks: Track[]): void {
+        if (!this.config.enabled) {
+            return;
+        }
+
+        const queue = this.#player.queues.get(guildId);
+        if (!queue || queue.length < this.config.minTracks) {
+            return;
+        }
+
+        this.applyFairPlay(queue.guildId);
+    }
+
+    /**
+     * Apply fair play algorithm to a queue
+     */
+    applyFairPlay(guildId: string): void {
+        const queue = this.#player.queues.get(guildId);
+        if (!queue) {
+            return;
+        }
+
+        const playerConfig = (this.#player as PlayerWithGet).get?.("fairplay_config");
+        const config = playerConfig ? { ...this.config, ...playerConfig } : this.config;
+
+        if (queue.length < config.minTracks) {
+            return;
+        }
+
+        const tracks = queue.tracks;
+        const fairQueue: Track[] = [];
+        const requesterQueues = new Map<string, Track[]>();
+
+        // Group tracks by requester
+        for (const track of tracks) {
+            const requesterId = this.#getRequesterId(track);
+            let requesterQueue = requesterQueues.get(requesterId);
+            if (!requesterQueue) {
+                requesterQueue = [];
+                requesterQueues.set(requesterId, requesterQueue);
+            }
+            requesterQueue.push(track);
+        }
+
+        // Distribute tracks fairly
+        let hasMore = true;
+        let consecutiveCount = 0;
+        let lastRequesterId: string | null = null;
+
+        while (hasMore) {
+            hasMore = false;
+
+            for (const [requesterId, requesterTracks] of requesterQueues) {
+                if (requesterTracks.length === 0) {
+                    continue;
+                }
+
+                hasMore = true;
+
+                // Check if we need to switch requester
+                if (lastRequesterId === requesterId) {
+                    consecutiveCount++;
+                    if (consecutiveCount >= config.maxConsecutive) {
+                        // Skip this requester for now
+                        continue;
+                    }
+                } else {
+                    consecutiveCount = 1;
+                    lastRequesterId = requesterId;
+                }
+
+                // Add track from this requester
+                const track = requesterTracks.shift();
+                if (track) {
+                    fairQueue.push(track);
+                }
+            }
+
+            // Reset if we've gone through all requesters
+            if (!hasMore) {
+                lastRequesterId = null;
+                consecutiveCount = 0;
+                hasMore = Array.from(requesterQueues.values()).some((q) => q.length > 0);
+            }
+        }
+
+        // Update queue with fair distribution
+        if (fairQueue.length > 0) {
+            queue.clear("current");
+            queue.add(fairQueue);
+
+            this.#player.emit("fairPlayApplied", this.#player, guildId, fairQueue.length);
+        }
+    }
+
+    #getRequesterId(track: Track): string {
+        const requester = (track.userData as { requester?: { id: string } }).requester;
+        if (requester && typeof requester === "object") {
+            return requester.id || "unknown";
+        }
+        return "unknown";
+    }
+}

package/src/extensions/LyricsExtension.ts

@@ -0,0 +1,187 @@
+import { PlayerPlugin } from "../core/PluginSystem";
+import type { Player } from "../core/RyanlinkPlayer";
+import { Track } from "../audio/AudioTrack";
+
+export interface LyricsPluginEvents {
+    /**
+     * Emitted when lyrics are found
+     */
+    lyricsFound: [player: Player, track: Track, lyrics: LyricsResult];
+
+    /**
+     * Emitted when lyrics are not found
+     */
+    lyricsNotFound: [player: Player, track: Track];
+}
+
+export interface LyricsLine {
+    timestamp: number;
+    duration: number | null;
+    line: string;
+}
+
+export interface LyricsResult {
+    sourceName: string;
+    provider: string;
+    text: string | null;
+    lines: LyricsLine[];
+    track: {
+        title: string;
+        artist: string;
+        album?: string;
+        duration: number;
+    };
+}
+
+export interface LyricsConfig {
+    sources: {
+        lavalink: boolean;
+        lrclib: boolean;
+        musixmatch: boolean;
+        genius: boolean;
+    };
+    apiKeys?: {
+        musixmatch?: string;
+        genius?: string;
+    };
+}
+
+/**
+ * Lyrics Plugin - Fetches and manages track lyrics from multiple sources
+ * Supports Lavalink LavaLyrics, LRCLib, Musixmatch, and Genius
+ */
+export class LyricsPlugin extends PlayerPlugin<LyricsPluginEvents & Record<string, unknown[]>> {
+    readonly name = "lyrics" as const;
+
+    #player!: Player;
+
+    init(player: Player): void {
+        this.#player = player;
+    }
+
+    /**
+     * Fetch lyrics for a track
+     * @param track - The track to fetch lyrics for
+     * @param config - Configuration for lyrics sources
+     */
+    async getLyrics(track: Track, config?: LyricsConfig): Promise<LyricsResult | null> {
+        const defaultConfig: LyricsConfig = {
+            sources: {
+                lavalink: true,
+                lrclib: true,
+                musixmatch: false,
+                genius: false,
+            },
+            ...config,
+        };
+
+        const title = track.info.title;
+        const artist = track.info.author;
+
+        if (defaultConfig.sources.lavalink) {
+            const lavalinkLyrics = await this.#fetchFromLavalink(track);
+            if (lavalinkLyrics) {
+                this.#player.emit("lyricsFound", this.#player, track, lavalinkLyrics);
+                return lavalinkLyrics;
+            }
+        }
+
+        if (defaultConfig.sources.lrclib) {
+            const lrclibLyrics = await this.#fetchFromLRCLib(title, artist);
+            if (lrclibLyrics) {
+                this.#player.emit("lyricsFound", this.#player, track, lrclibLyrics);
+                return lrclibLyrics;
+            }
+        }
+
+        if (defaultConfig.sources.musixmatch && defaultConfig.apiKeys?.musixmatch) {
+            const musixmatchLyrics = await this.#fetchFromMusixmatch(title, artist, defaultConfig.apiKeys.musixmatch);
+            if (musixmatchLyrics) {
+                this.#player.emit("lyricsFound", this.#player, track, musixmatchLyrics);
+                return musixmatchLyrics;
+            }
+        }
+
+        if (defaultConfig.sources.genius && defaultConfig.apiKeys?.genius) {
+            const geniusLyrics = await this.#fetchFromGenius(title, artist, defaultConfig.apiKeys.genius);
+            if (geniusLyrics) {
+                this.#player.emit("lyricsFound", this.#player, track, geniusLyrics);
+                return geniusLyrics;
+            }
+        }
+
+        this.#player.emit("lyricsNotFound", this.#player, track);
+        return null;
+    }
+
+    /**
+     * Get the current lyric line based on playback position
+     */
+    getCurrentLine(lyrics: LyricsResult, position: number): LyricsLine | null {
+        if (!lyrics.lines || lyrics.lines.length === 0) {
+            return null;
+        }
+
+        for (let i = lyrics.lines.length - 1; i >= 0; i--) {
+            if (lyrics.lines[i].timestamp <= position) {
+                return lyrics.lines[i];
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Format lyrics for display
+     */
+    formatLyrics(lyrics: LyricsResult, maxLength: number = 2000): string {
+        if (lyrics.text) {
+            return lyrics.text.slice(0, maxLength);
+        }
+
+        if (lyrics.lines && lyrics.lines.length > 0) {
+            let formatted = "";
+            for (const line of lyrics.lines) {
+                const timestamp = this.#formatTimestamp(line.timestamp);
+                formatted += `[${timestamp}] ${line.line}\n`;
+
+                if (formatted.length > maxLength) {
+                    return `${formatted.slice(0, maxLength)}...`;
+                }
+            }
+            return formatted;
+        }
+
+        return "No lyrics available";
+    }
+
+    #formatTimestamp(ms: number): string {
+        const minutes = Math.floor(ms / 60000);
+        const seconds = Math.floor((ms % 60000) / 1000);
+        return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+    }
+
+    async #fetchFromLavalink(_track: Track): Promise<LyricsResult | null> {
+        // Implementation would call Lavalink's lyrics endpoint
+        // This is a placeholder
+        return await Promise.resolve(null);
+    }
+
+    async #fetchFromLRCLib(_title: string, _artist: string): Promise<LyricsResult | null> {
+        // Implementation would call LRCLib API
+        // This is a placeholder
+        return await Promise.resolve(null);
+    }
+
+    async #fetchFromMusixmatch(_title: string, _artist: string, _apiKey: string): Promise<LyricsResult | null> {
+        // Implementation would call Musixmatch API
+        // This is a placeholder
+        return await Promise.resolve(null);
+    }
+
+    async #fetchFromGenius(_title: string, _artist: string, _apiToken: string): Promise<LyricsResult | null> {
+        // Implementation would call Genius API
+        // This is a placeholder
+        return await Promise.resolve(null);
+    }
+}

package/src/extensions/PersistenceExtension.ts

@@ -0,0 +1,182 @@
+import { PlayerPlugin } from "../core/PluginSystem";
+import type { Player } from "../core/RyanlinkPlayer";
+import type { RepeatMode } from "../types";
+
+export interface QueuePersistencePluginEvents {
+    /**
+     * Emitted when queue is saved
+     */
+    queueSaved: [guildId: string];
+
+    /**
+     * Emitted when queue is loaded
+     */
+    queueLoaded: [guildId: string, trackCount: number];
+}
+
+export interface StoredQueue {
+    guildId: string;
+    tracks: Array<{
+        encoded: string;
+        info: unknown;
+        pluginInfo?: unknown;
+        userData?: unknown;
+    }>;
+    previousTracks: Array<{
+        encoded: string;
+        info: unknown;
+        pluginInfo?: unknown;
+        userData?: unknown;
+    }>;
+    currentTrack?: {
+        encoded: string;
+        info: unknown;
+        position: number;
+    };
+    volume: number;
+    repeatMode: RepeatMode;
+    autoplay: boolean;
+    paused: boolean;
+    timestamp: number;
+}
+
+export interface QueueStore {
+    get(guildId: string): Promise<StoredQueue | null> | StoredQueue | null;
+    set(guildId: string, data: StoredQueue): Promise<void> | void;
+    delete(guildId: string): Promise<void> | void;
+}
+
+/**
+ * Default in-memory queue store
+ */
+export class MemoryQueueStore implements QueueStore {
+    #data = new Map<string, StoredQueue>();
+
+    get(guildId: string): StoredQueue | null {
+        return this.#data.get(guildId) ?? null;
+    }
+
+    set(guildId: string, data: StoredQueue): void {
+        this.#data.set(guildId, data);
+    }
+
+    delete(guildId: string): void {
+        this.#data.delete(guildId);
+    }
+}
+
+/**
+ * Queue Persistence Plugin - Saves and restores queue state
+ * Useful for bot restarts or crashes
+ */
+export class QueuePersistencePlugin extends PlayerPlugin<QueuePersistencePluginEvents & Record<string, unknown[]>> {
+    readonly name = "queue-persistence" as const;
+
+    #player!: Player;
+    #store: QueueStore;
+    #autoSave: boolean;
+
+    constructor(store?: QueueStore, autoSave = true) {
+        super();
+        this.#store = store ?? new MemoryQueueStore();
+        this.#autoSave = autoSave;
+    }
+
+    init(player: Player): void {
+        this.#player = player;
+
+        if (this.#autoSave) {
+            // Auto-save on track changes
+            player.on("trackStart", (queue, _track) => {
+                this.saveQueue(queue.guildId).catch(() => {});
+            });
+
+            player.on("trackFinish", (queue, _track, _reason) => {
+                this.saveQueue(queue.guildId).catch(() => {});
+            });
+
+            // Save on queue destroy
+            player.on("queueDestroy", (queue) => {
+                this.deleteQueue(queue.guildId).catch(() => {});
+            });
+        }
+    }
+
+    /**
+     * Save queue state
+     */
+    async saveQueue(guildId: string): Promise<void> {
+        const queue = this.#player.queues.get(guildId);
+        if (!queue) {
+            return;
+        }
+
+        const data: StoredQueue = {
+            guildId,
+            tracks: queue.tracks.map((track) => ({
+                encoded: track.encoded,
+                info: track.info,
+                pluginInfo: track.pluginInfo,
+                userData: track.userData,
+            })),
+            previousTracks: queue.previousTracks.map((t) => ({
+                encoded: t.encoded,
+                info: t.info,
+                pluginInfo: t.pluginInfo,
+                userData: t.userData,
+            })),
+            currentTrack: queue.track
+                ? {
+                      encoded: queue.track.encoded,
+                      info: queue.track.info,
+                      position: queue.currentTime,
+                  }
+                : undefined,
+            volume: queue.volume,
+            repeatMode: queue.repeatMode,
+            autoplay: queue.autoplay,
+            paused: queue.paused,
+            timestamp: Date.now(),
+        };
+
+        await this.#store.set(guildId, data);
+        this.#player.emit("queueSaved", guildId);
+    }
+
+    /**
+     * Load queue state
+     */
+    async loadQueue(guildId: string): Promise<StoredQueue | null> {
+        const data = await this.#store.get(guildId);
+        if (!data) {
+            return null;
+        }
+
+        const queue = this.#player.queues.get(guildId);
+        if (!queue) {
+            return null;
+        }
+
+        // Restore tracks
+        // Note: Tracks need to be reconstructed from stored data
+        // This is a simplified version - you'd need to properly reconstruct Track objects
+
+        this.#player.emit("queueLoaded", guildId, data.tracks.length);
+        return data;
+    }
+
+    /**
+     * Delete saved queue
+     */
+    async deleteQueue(guildId: string): Promise<void> {
+        await this.#store.delete(guildId);
+    }
+
+    /**
+     * Get all saved queues
+     */
+    async getAllQueues(): Promise<StoredQueue[]> {
+        // This would need to be implemented based on the store type
+        return await Promise.resolve([]);
+    }
+}

package/src/extensions/SponsorBlockExtension.ts

@@ -0,0 +1,81 @@
+import { PlayerPlugin } from "../core/PluginSystem";
+import type { Player } from "../core/RyanlinkPlayer";
+import { Track } from "../audio/AudioTrack";
+import { Queue } from "../audio/AudioQueue";
+import type { SponsorBlockSegment } from "../types/lavalink/Node";
+
+export interface SponsorBlockPluginEvents {
+    /**
+     * Emitted when segments are loaded
+     */
+    segmentsLoaded: [queue: Queue, track: Track, segments: SponsorBlockSegment[]];
+
+    /**
+     * Emitted when a segment is skipped
+     */
+    segmentSkipped: [queue: Queue, track: Track, segment: SponsorBlockSegment];
+}
+
+/**
+ * SponsorBlock Plugin - Automatically skip sponsored segments in videos
+ * Requires Lavalink SponsorBlock plugin
+ */
+export class SponsorBlockPlugin extends PlayerPlugin<SponsorBlockPluginEvents & Record<string, unknown[]>> {
+    readonly name = "sponsorblock" as const;
+
+    #player!: Player;
+
+    init(player: Player): void {
+        this.#player = player;
+
+        // Listen to SponsorBlock events from Lavalink
+        player.on("segmentsLoaded", this.#handleSegmentsLoaded.bind(this));
+        player.on("segmentSkipped", this.#handleSegmentSkipped.bind(this));
+    }
+
+    /**
+     * Set which segments to skip for a player
+     */
+    async setSegments(queue: Queue, segments: string[] = ["sponsor", "selfpromo"]): Promise<void> {
+        const node = queue.node;
+        if (!node) {
+            throw new Error("No node available");
+        }
+
+        await node.setSponsorBlock(queue, segments);
+    }
+
+    /**
+     * Get current SponsorBlock segments for a player
+     */
+    async getSegments(queue: Queue): Promise<string[]> {
+        const node = queue.node;
+        if (!node) {
+            throw new Error("No node available");
+        }
+
+        return await node.getSponsorBlock(queue);
+    }
+
+    /**
+     * Delete SponsorBlock configuration for a player
+     */
+    async deleteSegments(queue: Queue): Promise<void> {
+        const node = queue.node;
+        if (!node) {
+            throw new Error("No node available");
+        }
+
+        await node.deleteSponsorBlock(queue);
+    }
+
+    #handleSegmentsLoaded(queue: Queue, track: Track, segments: unknown): void {
+        const _segments = (segments as SponsorBlockSegment[]) || [];
+        this.#player.emit("segmentsLoaded", queue, track, _segments);
+    }
+
+    #handleSegmentSkipped(queue: Queue, track: Track, segment: unknown): void {
+        const _segment = segment as SponsorBlockSegment;
+        this.#player.emit("segmentSkipped", queue, track, _segment);
+    }
+}

package/src/extensions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Extension exports
+ */
+
+export * from "./AutoplayExtension";
+export * from "./LyricsExtension";
+export * from "./SponsorBlockExtension";
+export * from "./FairPlayExtension";
+export * from "./PersistenceExtension";

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Ryanlink - Advanced Lavalink client for Node.js
+ *
+ * @packageDocumentation
+ */
+
+// Export all components
+export * from "./config";
+export * from "./utils";
+export * from "./lavalink";
+export * from "./voice";
+export * from "./audio";
+export * from "./extensions";
+export * from "./core";
+
+/**
+ * Ryanlink version (dynamically loaded from package.json)
+ */
+export { CLIENT_VERSION as version, CLIENT_NAME as name, PACKAGE_INFO } from "./metadata";