magmastream 2.10.6-alpha.1 → 2.10.6-alpha.3

package/dist/structures/Manager.js

@@ -532,8 +532,7 @@ class Manager extends events_1.EventEmitter {
     async restorePlayerFromState(node, nodeId, guildId, state, cleanup) {
         if (!state.guildId || state.node?.options?.identifier !== nodeId)
             return;
-        const hasGuild = this.resolveGuild(state.guildId);
-        if (!hasGuild)
+        if (state.guildId !== guildId)
             return;
         const lavaPlayer = (await node.rest.get(`/v4/sessions/${state.node.sessionId}/players/${state.guildId}`));
         if (!lavaPlayer)
@@ -720,6 +719,9 @@ class Manager extends events_1.EventEmitter {
                         .map(async ({ name: guildId }) => {
                         const stateFilePath = Utils_1.PlayerUtils.getPlayerStatePath(guildId);
                         try {
+                            // Guilds outside this client's cache belong to another cluster; skip them before reading any file.
+                            if (!this.resolveGuild(guildId))
+                                return;
                             await promises_1.default.access(stateFilePath);
                             const state = JSON.parse(await promises_1.default.readFile(stateFilePath, "utf-8"));
                             await this.restorePlayerFromState(node, nodeId, guildId, state, async () => {
@@ -742,15 +744,15 @@ class Manager extends events_1.EventEmitter {
                     const keys = await this.redis.keys(`${Utils_1.PlayerUtils.getRedisKey()}playerstore:*`);
                     await Promise.all(keys.map(async (key) => {
                         try {
+                            const guildId = key.split(":").pop();
+                            if (!guildId || !this.resolveGuild(guildId))
+                                return;
                             const data = await this.redis.get(key);
                             if (!data)
                                 return;
                             const state = JSON.parse(data);
                             if (!state || typeof state !== "object")
                                 return;
-                            const guildId = key.split(":").pop();
-                            if (!guildId)
-                                return;
                             await this.restorePlayerFromState(node, nodeId, guildId, state, async () => {
                                 await this.redis.del(key);
                                 this.emit(Enums_1.ManagerEventTypes.Debug, `[MANAGER] Deleted Redis state: ${key}`);

package/dist/structures/Node.d.ts

@@ -2,7 +2,7 @@ import { Manager } from "./Manager";
 import { Player } from "./Player";
 import { Rest } from "./Rest";
 import WebSocket from "ws";
-import { LavalinkInfo, Lyrics, NodeLinkGetLyrics, NodeLinkChapter, NodeLinkEvent, NodeLinkMix, NodeLinkMeaningResult, NodeLinkSponsorBlockSegment, NodeLinkSponsorBlockUpdate, NodeOptions, NodeStats, NodeLinkSponsorBlockState, PlayerEvent, Track, TrackEndEvent, TrackExceptionEvent, TrackStartEvent, TrackStuckEvent, WebSocketClosedEvent } from "./Types";
+import { FetchLyricsOptions, LavalinkInfo, Lyrics, NormalizedLyrics, NodeLinkGetLyrics, NodeLinkChapter, NodeLinkEvent, NodeLinkMix, NodeLinkMeaningResult, NodeLinkSponsorBlockSegment, NodeLinkSponsorBlockUpdate, NodeOptions, NodeStats, NodeLinkSponsorBlockState, PlayerEvent, Track, TrackEndEvent, TrackExceptionEvent, TrackStartEvent, TrackStuckEvent, WebSocketClosedEvent } from "./Types";
 import { SponsorBlockSegment } from "./Enums";
 export declare class Node {
     manager: Manager;
@@ -251,6 +251,19 @@ export declare class Node {
      * @returns {Promise<Lyrics | NodeLinkGetLyrics>} A promise that resolves with the lyrics data.
      */
     getLyrics(track: Track, skipTrackSource?: boolean, language?: string): Promise<Lyrics | NodeLinkGetLyrics>;
+    /**
+     * Fetches lyrics and returns them in one shape for Lavalink and NodeLink.
+     *
+     * On Lavalink, a failure of the track's own lyrics source does not end the lookup.
+     * LavaLyrics returns HTTP 500 when any one source throws, so the node is asked again
+     * with `skipTrackSource=true`. With `lrclibFallback`, LRCLIB is asked when the node fails or finds nothing.
+     *
+     * @param {Track} track - The track to fetch the lyrics for.
+     * @param {FetchLyricsOptions} [options] - Lookup options.
+     * @returns {Promise<NormalizedLyrics | null>} The lyrics, or null when no source has lyrics for the track.
+     * @throws {MagmaStreamError} When every lookup failed with an error (node down, missing plugins, server errors).
+     */
+    fetchLyrics(track: Track, options?: FetchLyricsOptions): Promise<NormalizedLyrics | null>;
     /**
      * Loads chapters for a track using NodeLink.
      * @param {Track} track - The track to load chapters for.

package/dist/structures/Node.js

@@ -534,6 +534,7 @@ class Node {
         if (!player || player.node.options.identifier !== this.options.identifier)
             return;
         player.position = payload.state.position ?? 0;
+        player.ping = payload.state.ping ?? -1;
         this.manager.emit(Enums_1.ManagerEventTypes.PlayerUpdate, player, payload);
     }
     /**
@@ -1070,7 +1071,60 @@ class Node {
             });
         }
         const lyrics = (await this.rest.get(`/v4/lyrics?track=${encodeURIComponent(track.track)}&skipTrackSource=${skipTrackSource}`));
-        return lyrics || { source: null, provider: null, text: null, lines: [], plugin: [] };
+        return lyrics || { sourceName: null, source: null, provider: null, text: null, lines: [], plugin: [] };
+    }
+    /**
+     * Fetches lyrics and returns them in one shape for Lavalink and NodeLink.
+     *
+     * On Lavalink, a failure of the track's own lyrics source does not end the lookup.
+     * LavaLyrics returns HTTP 500 when any one source throws, so the node is asked again
+     * with `skipTrackSource=true`. With `lrclibFallback`, LRCLIB is asked when the node fails or finds nothing.
+     *
+     * @param {Track} track - The track to fetch the lyrics for.
+     * @param {FetchLyricsOptions} [options] - Lookup options.
+     * @returns {Promise<NormalizedLyrics | null>} The lyrics, or null when no source has lyrics for the track.
+     * @throws {MagmaStreamError} When every lookup failed with an error (node down, missing plugins, server errors).
+     */
+    async fetchLyrics(track, options = {}) {
+        const { skipTrackSource = false, retryWithoutTrackSource = true, language, lrclibFallback = false } = options;
+        const origin = this.isNodeLink ? "nodelink" : "lavalink";
+        const attempts = this.isNodeLink || skipTrackSource || !retryWithoutTrackSource ? [skipTrackSource] : [false, true];
+        let lastError = null;
+        let nodeAnswered = false;
+        for (const skip of attempts) {
+            try {
+                const raw = await this.getLyrics(track, skip, language);
+                if (raw && "loadType" in raw && raw.loadType === "error") {
+                    throw new MagmastreamError_1.MagmaStreamError({
+                        code: Enums_1.MagmaStreamErrorCode.REST_REQUEST_FAILED,
+                        message: `NodeLink lyrics request failed: ${raw.data?.message ?? "unknown error"}`,
+                        context: { identifier: this.options.identifier },
+                    });
+                }
+                nodeAnswered = true;
+                const lyrics = Utils_1.LyricsUtils.normalize(raw, origin);
+                if (lyrics)
+                    return lyrics;
+            }
+            catch (error) {
+                lastError = error;
+                this.manager.emit(Enums_1.ManagerEventTypes.Debug, `[NODE] Lyrics lookup on node ${this.options.identifier} failed (skipTrackSource=${skip}): ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (lrclibFallback) {
+            try {
+                return await Utils_1.LyricsUtils.fetchLrclib(track, { userAgent: options.lrclibUserAgent, timeoutMs: options.lrclibTimeoutMs });
+            }
+            catch (error) {
+                this.manager.emit(Enums_1.ManagerEventTypes.Debug, `[NODE] LRCLIB lyrics lookup failed: ${error instanceof Error ? error.message : String(error)}`);
+                if (nodeAnswered)
+                    return null;
+                throw lastError ?? error;
+            }
+        }
+        if (!nodeAnswered && lastError)
+            throw lastError;
+        return null;
     }
     /**
      * Loads chapters for a track using NodeLink.

package/dist/structures/Player.d.ts

@@ -1,7 +1,7 @@
 import { Filters } from "./Filters";
 import { Manager } from "./Manager";
 import { Node } from "./Node";
-import { AnyMessage, IQueue, Lyrics, NodeLinkChapter, NodeLinkFadingConfig, NodeLinkMeaningResult, NodeLinkMix, NodeLinkNextTrackOptions, NodeLinkSponsorBlockSegment, NodeLinkSponsorBlockState, NodeLinkSponsorBlockUpdate, PlayerOptions, PlayerVoiceState, PlayOptions, SearchQuery, SearchResult, Track } from "./Types";
+import { AnyMessage, FetchLyricsOptions, IQueue, Lyrics, NormalizedLyrics, NodeLinkChapter, NodeLinkFadingConfig, NodeLinkMeaningResult, NodeLinkMix, NodeLinkNextTrackOptions, NodeLinkSponsorBlockSegment, NodeLinkSponsorBlockState, NodeLinkSponsorBlockUpdate, PlayerOptions, PlayerVoiceState, PlayOptions, SearchQuery, SearchResult, Track } from "./Types";
 import { SponsorBlockSegment, StateTypes } from "./Enums";
 import { WebSocket } from "ws";
 export declare class Player {
@@ -18,6 +18,8 @@ export declare class Player {
     dynamicRepeat: boolean;
     /** The time the player is in the track. */
     position: number;
+    /** Last node-reported Discord voice ping in milliseconds; -1 when unavailable. */
+    ping: number;
     /** Whether the player is playing. */
     playing: boolean;
     /** Whether the player is paused. */
@@ -84,6 +86,8 @@ export declare class Player {
      * @returns {T} - The data associated with the key, cast to the specified type.
      */
     get<T>(key: string): T;
+    /** Returns the last node-reported Discord voice ping in milliseconds, or -1 when unavailable. */
+    getPing(): number;
     /**
      * Same as Manager#search() but a shortcut on the player itself.
      * @param query
@@ -369,11 +373,19 @@ export declare class Player {
      */
     getSerializableData(): Record<string, unknown>;
     /**
-     * Retrieves the current lyrics for the playing track.
+     * Retrieves the raw lyrics response for the playing track.
+     * On NodeLink the response is NodeLink's shape, not {@link Lyrics}. Use {@link Player.fetchCurrentLyrics} for one shape.
      * @param skipTrackSource - Indicates whether to skip the track source when fetching lyrics.
      * @returns {Promise<Lyrics>} - The lyrics of the current track.
      */
     getCurrentLyrics(skipTrackSource?: boolean): Promise<Lyrics>;
+    /**
+     * Fetches lyrics for the playing track in one shape for Lavalink and NodeLink.
+     * See {@link Node.fetchLyrics} for the lookup order and options.
+     * @param options - Lookup options.
+     * @returns {Promise<NormalizedLyrics | null>} - The lyrics, or null when nothing is playing or no source has lyrics.
+     */
+    fetchCurrentLyrics(options?: FetchLyricsOptions): Promise<NormalizedLyrics | null>;
     /**
      * Sets up the voice receiver for the player.
      * @returns {Promise<void>} - A promise that resolves when the voice receiver is set up.

package/dist/structures/Player.js

@@ -26,6 +26,8 @@ class Player {
     dynamicRepeat = false;
     /** The time the player is in the track. */
     position = 0;
+    /** Last node-reported Discord voice ping in milliseconds; -1 when unavailable. */
+    ping = -1;
     /** Whether the player is playing. */
     playing = false;
     /** Whether the player is paused. */
@@ -162,6 +164,10 @@ class Player {
         // Access the data object using the key and cast it to the specified type T.
         return this.data[key];
     }
+    /** Returns the last node-reported Discord voice ping in milliseconds, or -1 when unavailable. */
+    getPing() {
+        return this.ping;
+    }
     /**
      * Same as Manager#search() but a shortcut on the player itself.
      * @param query
@@ -1184,7 +1190,8 @@ class Player {
         return { ...this.data };
     }
     /**
-     * Retrieves the current lyrics for the playing track.
+     * Retrieves the raw lyrics response for the playing track.
+     * On NodeLink the response is NodeLink's shape, not {@link Lyrics}. Use {@link Player.fetchCurrentLyrics} for one shape.
      * @param skipTrackSource - Indicates whether to skip the track source when fetching lyrics.
      * @returns {Promise<Lyrics>} - The lyrics of the current track.
      */
@@ -1194,6 +1201,7 @@ class Player {
         // If no lyrics are found, return a default empty lyrics object
         if (!result) {
             result = {
+                sourceName: null,
                 source: null,
                 provider: null,
                 text: null,
@@ -1203,6 +1211,18 @@ class Player {
         }
         return result;
     }
+    /**
+     * Fetches lyrics for the playing track in one shape for Lavalink and NodeLink.
+     * See {@link Node.fetchLyrics} for the lookup order and options.
+     * @param options - Lookup options.
+     * @returns {Promise<NormalizedLyrics | null>} - The lyrics, or null when nothing is playing or no source has lyrics.
+     */
+    async fetchCurrentLyrics(options = {}) {
+        const current = await this.queue.getCurrent();
+        if (!current)
+            return null;
+        return this.node.fetchLyrics(current, options);
+    }
     /**
      * Sets up the voice receiver for the player.
      * @returns {Promise<void>} - A promise that resolves when the voice receiver is set up.

package/dist/structures/Types.d.ts

@@ -1184,24 +1184,75 @@ export interface LavalinkInfo {
  */
 export interface LyricsLine {
     timestamp: number;
-    duration: number;
+    duration: number | null;
     line: string;
     words?: Array<Record<string, unknown>>;
     plugin: Record<string, unknown>;
 }
 /**
- * Lyrics interface
+ * Lyrics interface. The raw LavaLyrics response from `GET /v4/lyrics`.
  */
 export interface Lyrics {
-    /** Lavalink lyrics plugin source field. */
-    source?: string | null;
-    /** NodeLink lyrics source field. */
+    /** LavaLyrics source name, for example "spotify", "deezer" or "LRCLIB". */
     sourceName?: string | null;
+    /** @deprecated LavaLyrics sends `sourceName`. This field is never set by Lavalink. */
+    source?: string | null;
     provider: string | null;
     text?: string | null;
     lines: LyricsLine[];
     plugin: Record<string, unknown> | Array<Record<string, unknown>>;
 }
+/**
+ * One line of {@link NormalizedLyrics}.
+ */
+export interface NormalizedLyricsLine {
+    /** Start of the line in milliseconds. Null when the lyrics are not synced. */
+    timestamp: number | null;
+    /** Length of the line in milliseconds, when the source sends it. */
+    duration: number | null;
+    /** The line text, trimmed. An empty string marks a break between verses. */
+    line: string;
+}
+/**
+ * Lyrics in one shape for Lavalink (LavaLyrics), NodeLink and LRCLIB.
+ * Returned by `Node.fetchLyrics` and `Player.fetchCurrentLyrics`.
+ */
+export interface NormalizedLyrics {
+    /** The source that found the lyrics, for example "spotify", "deezer" or "LRCLIB". */
+    sourceName: string | null;
+    /** The lyrics provider, for example "MusixMatch" or "LRCLIB". */
+    provider: string | null;
+    /** The plain text, when the source sends it. */
+    text: string | null;
+    /** True when every line has a timestamp and the timestamps are not all 0. */
+    synced: boolean;
+    lines: NormalizedLyricsLine[];
+    /** The backend that answered. */
+    origin: "lavalink" | "nodelink" | "lrclib";
+}
+/**
+ * Options for `Node.fetchLyrics` and `Player.fetchCurrentLyrics`.
+ */
+export interface FetchLyricsOptions {
+    /** Skip the track's own source and ask the node's lyrics sources in priority order. Default: false. */
+    skipTrackSource?: boolean;
+    /**
+     * When the track's own source fails or finds nothing, ask the node again with `skipTrackSource=true`.
+     * Lavalink only. Default: true.
+     */
+    retryWithoutTrackSource?: boolean;
+    /** NodeLink only: the lyrics language. */
+    language?: string;
+    /**
+     * Ask LRCLIB (https://lrclib.net) when the node fails or finds nothing.
+     * This sends the track title, artist and length to lrclib.net. Default: false.
+     */
+    lrclibFallback?: boolean;
+    /** User-Agent sent to LRCLIB. LRCLIB asks clients to name themselves. Default: "magmastream". */
+    lrclibUserAgent?: string;
+    /** Timeout for each LRCLIB request, in milliseconds. Default: 8000. */
+    lrclibTimeoutMs?: number;
+}
 /**
  * LyricsFoundEvent interface
  */

package/dist/structures/Utils.d.ts

@@ -1,6 +1,6 @@
 import { AutoPlayPlatform, TrackPartial } from "./Enums";
 import { Manager } from "./Manager";
-import { AnyUser, ErrorOrEmptySearchResult, Extendable, LavalinkResponse, SearchResult, SerializedPlayerState, Track, TrackData } from "./Types";
+import { AnyUser, ErrorOrEmptySearchResult, Extendable, LavalinkResponse, Lyrics, NodeLinkGetLyrics, NormalizedLyrics, NormalizedLyricsLine, SearchResult, SerializedPlayerState, Track, TrackData } from "./Types";
 import { Player } from "./Player";
 export declare abstract class TrackUtils {
     static trackPartial: TrackPartial[] | null;
@@ -163,7 +163,61 @@ export declare abstract class Structure {
      */
     static get<K extends keyof Extendable>(name: K): Extendable[K];
 }
+/** Track fields the LRCLIB lookup reads. */
+type LyricsTrack = Pick<Track, "title" | "author" | "duration" | "isStream">;
+/**
+ * Turns Lavalink (LavaLyrics), NodeLink and LRCLIB lyrics into one shape,
+ * and looks lyrics up on LRCLIB.
+ */
+export declare abstract class LyricsUtils {
+    /**
+     * Normalizes a raw `Node.getLyrics` response.
+     * @returns The lyrics, or null when the response holds no lyrics.
+     */
+    static normalize(raw: Lyrics | NodeLinkGetLyrics | null | undefined, origin: "lavalink" | "nodelink"): NormalizedLyrics | null;
+    private static normalizeNodeLink;
+    private static normalizeNodeLinkData;
+    /**
+     * Looks a track up on LRCLIB: an exact match first, then the search result closest in length.
+     * @returns The lyrics, or null when LRCLIB has none.
+     * @throws When LRCLIB cannot be reached or answers with an error.
+     */
+    static fetchLrclib(track: LyricsTrack, options?: {
+        userAgent?: string;
+        timeoutMs?: number;
+    }): Promise<NormalizedLyrics | null>;
+    /**
+     * One LRCLIB request. A 404 means LRCLIB has no such song and gives null.
+     */
+    static lrclibRequest<T>(path: string, params: Record<string, string | number>, options?: {
+        userAgent?: string;
+        timeoutMs?: number;
+    }): Promise<T | null>;
+    private static fromLrclibRecord;
+    /**
+     * Parses LRC text. Accepts "[mm:ss.xx]text" with or without a space after the timestamp,
+     * more than one timestamp per line, and skips tags such as "[ar:Artist]".
+     */
+    static parseLrc(text: string): NormalizedLyricsLine[];
+    /**
+     * Removes video noise so a lyrics database can match the track.
+     * "Coldplay - Yellow (Official Video)" by "ColdplayVEVO" gives artist "Coldplay" and title "Yellow".
+     */
+    static cleanTrackInfo(track: Pick<Track, "title" | "author">): {
+        artist: string;
+        title: string;
+    };
+    /**
+     * Trims lines and decides if the lyrics are synced. Unsynced lyrics get null timestamps.
+     * @returns The lyrics, or null when no line has text.
+     */
+    private static finish;
+    private static linesFromText;
+    private static finiteOrNull;
+    private static looseIncludes;
+}
 export declare abstract class JSONUtils {
     static safe<T>(obj: T, space?: number): string;
     static serializeTrack(track: Track): string;
 }
+export {};

package/dist/structures/Utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JSONUtils = exports.Structure = exports.PlayerUtils = exports.AutoPlayUtils = exports.TrackUtils = void 0;
+exports.JSONUtils = exports.LyricsUtils = exports.Structure = exports.PlayerUtils = exports.AutoPlayUtils = exports.TrackUtils = void 0;
 const tslib_1 = require("tslib");
 /* eslint-disable @typescript-eslint/no-require-imports */
 const undici_1 = require("undici");
@@ -887,6 +887,235 @@ class Structure {
     }
 }
 exports.Structure = Structure;
+const LRCLIB_API = "https://lrclib.net/api";
+const LRCLIB_DEFAULT_USER_AGENT = "magmastream (https://gitryx.com/MagmaStream/magmastream)";
+const LRCLIB_DEFAULT_TIMEOUT_MS = 8000;
+/** A search result whose length is further off than this is another recording. */
+const LRCLIB_MAX_DURATION_DIFF_S = 15;
+const LRC_STAMP = /^\[(\d+):(\d{1,2}(?:[.:]\d+)?)\]/;
+const TITLE_NOISE = /[([][^)\]]*\b(official|video|audio|lyrics?|visuali[sz]er|remaster(ed)?|hd|hq|4k|mv|live|explicit|clean)\b[^)\]]*[)\]]/gi;
+/**
+ * Turns Lavalink (LavaLyrics), NodeLink and LRCLIB lyrics into one shape,
+ * and looks lyrics up on LRCLIB.
+ */
+class LyricsUtils {
+    /**
+     * Normalizes a raw `Node.getLyrics` response.
+     * @returns The lyrics, or null when the response holds no lyrics.
+     */
+    static normalize(raw, origin) {
+        if (!raw || typeof raw !== "object")
+            return null;
+        if ("loadType" in raw)
+            return this.normalizeNodeLink(raw);
+        let lines = Array.isArray(raw.lines)
+            ? raw.lines.map((line) => ({
+                timestamp: this.finiteOrNull(line?.timestamp),
+                duration: this.finiteOrNull(line?.duration),
+                line: typeof line?.line === "string" ? line.line : "",
+            }))
+            : [];
+        // Some sources send only plain text.
+        if (!lines.some((line) => line.line.trim()) && typeof raw.text === "string") {
+            lines = this.linesFromText(raw.text);
+        }
+        return this.finish(lines, {
+            sourceName: raw.sourceName ?? raw.source ?? null,
+            provider: raw.provider ?? null,
+            text: typeof raw.text === "string" ? raw.text : null,
+            origin,
+        });
+    }
+    static normalizeNodeLink(raw) {
+        switch (raw.loadType) {
+            case "lyrics": {
+                const data = raw.data ?? {};
+                const lines = (data.lines ?? []).map((line) => ({
+                    timestamp: this.finiteOrNull(line?.time),
+                    duration: this.finiteOrNull(line?.duration),
+                    line: typeof line?.text === "string" ? line.text : "",
+                }));
+                return this.finish(lines, { sourceName: data.provider ?? data.name ?? null, provider: data.provider ?? null, text: null, origin: "nodelink" }, data.synced);
+            }
+            case "lyricsSingle":
+                return this.normalizeNodeLinkData(raw.data);
+            case "lyricsMultiple": {
+                const entries = Array.isArray(raw.data) ? [...raw.data] : [];
+                // Prefer synced lyrics.
+                entries.sort((a, b) => Number(Boolean(b?.synced)) - Number(Boolean(a?.synced)));
+                for (const entry of entries) {
+                    const lyrics = this.normalizeNodeLinkData(entry);
+                    if (lyrics)
+                        return lyrics;
+                }
+                return null;
+            }
+            default:
+                return null;
+        }
+    }
+    static normalizeNodeLinkData(data) {
+        if (!data)
+            return null;
+        const lines = (data.data ?? []).map((line) => {
+            const start = this.finiteOrNull(line?.startTime);
+            const end = this.finiteOrNull(line?.endTime);
+            return {
+                timestamp: start,
+                duration: start !== null && end !== null && end >= start ? end - start : null,
+                line: typeof line?.text === "string" ? line.text : "",
+            };
+        });
+        return this.finish(lines, { sourceName: data.name ?? null, provider: data.name ?? null, text: null, origin: "nodelink" }, data.synced);
+    }
+    /**
+     * Looks a track up on LRCLIB: an exact match first, then the search result closest in length.
+     * @returns The lyrics, or null when LRCLIB has none.
+     * @throws When LRCLIB cannot be reached or answers with an error.
+     */
+    static async fetchLrclib(track, options = {}) {
+        const { artist, title } = this.cleanTrackInfo(track);
+        if (!title)
+            return null;
+        const durationS = !track.isStream && track.duration > 0 ? Math.round(track.duration / 1000) : null;
+        if (artist && durationS) {
+            const exact = await this.lrclibRequest("/get", { track_name: title, artist_name: artist, duration: durationS }, options);
+            const lyrics = exact ? this.fromLrclibRecord(exact) : null;
+            if (lyrics)
+                return lyrics;
+        }
+        let records = await this.lrclibRequest("/search", artist ? { track_name: title, artist_name: artist } : { q: title }, options);
+        if ((!Array.isArray(records) || !records.length) && artist) {
+            records = await this.lrclibRequest("/search", { q: `${artist} ${title}` }, options);
+        }
+        if (!Array.isArray(records))
+            return null;
+        const candidates = records
+            .filter((record) => record && (record.syncedLyrics || record.plainLyrics))
+            .map((record) => ({ record, diff: durationS && record.duration ? Math.abs(record.duration - durationS) : 0 }))
+            .filter(({ diff }) => diff <= LRCLIB_MAX_DURATION_DIFF_S)
+            // The closest length wins. Within 2 seconds, synced lyrics win.
+            .sort((a, b) => (Math.abs(a.diff - b.diff) > 2 ? a.diff - b.diff : Number(Boolean(b.record.syncedLyrics)) - Number(Boolean(a.record.syncedLyrics))));
+        for (const { record } of candidates) {
+            const lyrics = this.fromLrclibRecord(record);
+            if (lyrics)
+                return lyrics;
+        }
+        return null;
+    }
+    /**
+     * One LRCLIB request. A 404 means LRCLIB has no such song and gives null.
+     */
+    static async lrclibRequest(path, params, options = {}) {
+        const url = new URL(LRCLIB_API + path);
+        for (const [key, value] of Object.entries(params))
+            url.searchParams.set(key, String(value));
+        const response = await (0, undici_1.fetch)(url, {
+            headers: { Accept: "application/json", "User-Agent": options.userAgent ?? LRCLIB_DEFAULT_USER_AGENT },
+            signal: AbortSignal.timeout(options.timeoutMs ?? LRCLIB_DEFAULT_TIMEOUT_MS),
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            throw new MagmastreamError_1.MagmaStreamError({
+                code: Enums_1.MagmaStreamErrorCode.REST_REQUEST_FAILED,
+                message: `LRCLIB request ${path} failed (${response.status}).`,
+            });
+        }
+        return (await response.json());
+    }
+    static fromLrclibRecord(record) {
+        const meta = { sourceName: "LRCLIB", provider: "LRCLIB", text: record.plainLyrics ?? null, origin: "lrclib" };
+        if (record.syncedLyrics) {
+            const lyrics = this.finish(this.parseLrc(record.syncedLyrics), meta);
+            if (lyrics)
+                return lyrics;
+        }
+        return record.plainLyrics ? this.finish(this.linesFromText(record.plainLyrics), meta) : null;
+    }
+    /**
+     * Parses LRC text. Accepts "[mm:ss.xx]text" with or without a space after the timestamp,
+     * more than one timestamp per line, and skips tags such as "[ar:Artist]".
+     */
+    static parseLrc(text) {
+        const lines = [];
+        for (const raw of text.split("\n")) {
+            let rest = raw.trim();
+            const stamps = [];
+            let match;
+            while ((match = LRC_STAMP.exec(rest))) {
+                const seconds = Number.parseFloat(match[2].replace(":", "."));
+                stamps.push(Number.parseInt(match[1], 10) * 60000 + Math.round(seconds * 1000));
+                rest = rest.slice(match[0].length);
+            }
+            for (const timestamp of stamps)
+                lines.push({ timestamp, duration: null, line: rest.trim() });
+        }
+        return lines.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
+    }
+    /**
+     * Removes video noise so a lyrics database can match the track.
+     * "Coldplay - Yellow (Official Video)" by "ColdplayVEVO" gives artist "Coldplay" and title "Yellow".
+     */
+    static cleanTrackInfo(track) {
+        let artist = String(track.author ?? "")
+            .replace(/\s*-\s*topic$/i, "")
+            .replace(/vevo$/i, "")
+            .replace(/\s*(official)?\s*$/i, "")
+            .trim();
+        let title = String(track.title ?? "");
+        const dash = title.match(/^(.+?)\s+[-–—]\s+(.+)$/);
+        if (dash) {
+            const titleArtist = dash[1].trim();
+            if (!artist || this.looseIncludes(titleArtist, artist) || this.looseIncludes(artist, titleArtist)) {
+                artist = titleArtist;
+                title = dash[2];
+            }
+        }
+        title = title
+            .replace(TITLE_NOISE, "")
+            .replace(/\s+[([]?(feat\.?|ft\.?|featuring)\s.*$/i, "")
+            .replace(/\s+[|/]\s+.*$/, "")
+            .replace(/\s{2,}/g, " ")
+            .trim();
+        artist = artist.split(/\s*(?:,|&|\bfeat\.?|\bft\.?|\bx\b)\s*/i)[0].trim();
+        return { artist, title };
+    }
+    /**
+     * Trims lines and decides if the lyrics are synced. Unsynced lyrics get null timestamps.
+     * @returns The lyrics, or null when no line has text.
+     */
+    static finish(lines, meta, syncedHint) {
+        const cleaned = lines.map((line) => ({ ...line, line: line.line.replace(/\r/g, "").trim() }));
+        if (!cleaned.some((line) => line.line))
+            return null;
+        // Unsynced Spotify lyrics come with every timestamp at 0.
+        const synced = syncedHint !== false && cleaned.length > 1 && cleaned.every((line) => line.timestamp !== null) && cleaned.some((line) => (line.timestamp ?? 0) > 0);
+        if (synced) {
+            cleaned.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));
+        }
+        else {
+            for (const line of cleaned) {
+                line.timestamp = null;
+                line.duration = null;
+            }
+        }
+        return { ...meta, synced, lines: cleaned };
+    }
+    static linesFromText(text) {
+        return text.split("\n").map((line) => ({ timestamp: null, duration: null, line }));
+    }
+    static finiteOrNull(value) {
+        return typeof value === "number" && Number.isFinite(value) ? value : null;
+    }
+    static looseIncludes(a, b) {
+        const fold = (value) => value.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+        const left = fold(a);
+        const right = fold(b);
+        return Boolean(left && right && left.includes(right));
+    }
+}
+exports.LyricsUtils = LyricsUtils;
 class JSONUtils {
     static safe(obj, space) {
         return (0, safe_stable_stringify_1.default)(obj, null, space);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "magmastream",
-    "version": "2.10.6-alpha.1",
+    "version": "2.10.6-alpha.3",
     "description": "A user-friendly Lavalink client designed for NodeJS.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
         "prepare": "npm run build",
         "build": "tsc",
         "types": "rtb --dist dist",
-        "test": "npm run build && node --test tests/player-state.test.cjs tests/hot-paths.test.cjs tests/restore-performance.test.cjs",
+        "test": "npm run build && node --test tests/player-state.test.cjs tests/hot-paths.test.cjs tests/restore-performance.test.cjs tests/lyrics.test.cjs",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "lint": "eslint \"src/**/*.{ts,js}\"",