magmastream 2.9.0-dev.33 → 2.9.0-dev.34

package/dist/index.d.ts

@@ -266,6 +266,9 @@ declare enum ManagerEventTypes {
     ChapterStarted = "chapterStarted",
     ChaptersLoaded = "chaptersLoaded",
     Debug = "debug",
+    LyricsFoundEvent = "lyricsFoundEvent",
+    LyricsLineEvent = "lyricsLineEvent",
+    LyricsNotFoundEvent = "lyricsNotFoundEvent",
     NodeConnect = "nodeConnect",
     NodeCreate = "nodeCreate",
     NodeDestroy = "nodeDestroy",
@@ -808,6 +811,9 @@ interface ManagerEvents {
     [ManagerEventTypes.ChapterStarted]: [player: Player, track: Track, payload: SponsorBlockChapterStarted];
     [ManagerEventTypes.ChaptersLoaded]: [player: Player, track: Track, payload: SponsorBlockChaptersLoaded];
     [ManagerEventTypes.Debug]: [info: string];
+    [ManagerEventTypes.LyricsFoundEvent]: [player: Player, track: Track, payload: LyricsFoundEvent];
+    [ManagerEventTypes.LyricsLineEvent]: [player: Player, track: Track, payload: LyricsLineEvent];
+    [ManagerEventTypes.LyricsNotFoundEvent]: [player: Player, track: Track, payload: LyricsNotFoundEvent];
     [ManagerEventTypes.NodeConnect]: [node: Node];
     [ManagerEventTypes.NodeCreate]: [node: Node];
     [ManagerEventTypes.NodeDestroy]: [node: Node];
@@ -1178,6 +1184,31 @@ interface Lyrics {
     lines: LyricsLine[];
     plugin: object[];
 }
+/**
+ * LyricsFoundEvent interface
+ */
+interface LyricsFoundEvent extends PlayerEvent {
+    type: "LyricsFoundEvent";
+    guildId: string;
+    lyrics: Lyrics;
+}
+/**
+ * LyricsNotFoundEvent interface
+ */
+interface LyricsNotFoundEvent extends PlayerEvent {
+    type: "LyricsNotFoundEvent";
+    guildId: string;
+}
+/**
+ * LyricsLineEvent interface
+ */
+interface LyricsLineEvent extends PlayerEvent {
+    type: "LyricsLineEvent";
+    guildId: string;
+    lineIndex: number;
+    line: LyricsLine;
+    skipped: boolean;
+}
 /**
  * NodeLink Get Lyrics Multiple interface
  */
@@ -1363,7 +1394,7 @@ type TrackEndReason = keyof typeof TrackEndReasonTypes;
 /**
  * Player Event Type Enum type
  */
-type PlayerEventType = "TrackStartEvent" | "TrackEndEvent" | "TrackExceptionEvent" | "TrackStuckEvent" | "WebSocketClosedEvent" | "SegmentSkipped" | "SegmentsLoaded" | "ChaptersLoaded" | "ChapterStarted";
+type PlayerEventType = "TrackStartEvent" | "TrackEndEvent" | "TrackExceptionEvent" | "TrackStuckEvent" | "WebSocketClosedEvent" | "SegmentSkipped" | "SegmentsLoaded" | "ChaptersLoaded" | "ChapterStarted" | "LyricsFoundEvent" | "LyricsNotFoundEvent" | "LyricsLineEvent";
 /**
  * Severity Types Enum type
  */
@@ -1379,7 +1410,7 @@ type SponsorBlockSegmentEventType = "SegmentSkipped" | "SegmentsLoaded" | "Chapt
 /**
  * Player Events Enum type
  */
-type PlayerEvents = TrackStartEvent | TrackEndEvent | TrackStuckEvent | TrackExceptionEvent | WebSocketClosedEvent | SponsorBlockSegmentEvents;
+type PlayerEvents = TrackStartEvent | TrackEndEvent | TrackStuckEvent | TrackExceptionEvent | WebSocketClosedEvent | SponsorBlockSegmentEvents | LyricsEvent;
 /**
  * Load Type Enum type
  */
@@ -1396,6 +1427,14 @@ type VoiceReceiverEvent = StartSpeakingEventVoiceReceiver | EndSpeakingEventVoic
  * Search Result Enum type
  */
 type SearchResult = TrackSearchResult | SearchSearchResult | PlaylistSearchResult | ErrorOrEmptySearchResult;
+/**
+ * Lyrics Event Enum type
+ */
+type LyricsEvent = LyricsFoundEvent | LyricsNotFoundEvent | LyricsLineEvent;
+/**
+ * Lyrics Event Type Enum type
+ */
+type LyricsEventType = "LyricsFoundEvent" | "LyricsNotFoundEvent" | "LyricsLineEvent";
 
 declare class Node$1 {
     manager: Manager;
@@ -1622,14 +1661,32 @@ declare class Node$1 {
     queueEnd(player: Player, track: Track, payload: TrackEndEvent): Promise<void>;
     /**
      * Fetches the lyrics of a track from the Lavalink node.
-     * This method uses the `lavalyrics-plugin` to fetch the lyrics.
-     * If the plugin is not available, it will throw a RangeError.
+     *
+     * If the node is a NodeLink, it will use the `NodeLinkGetLyrics` method to fetch the lyrics.
+     *
+     * Requires the `lavalyrics-plugin` to be present in the Lavalink node.
+     * Requires the `lavasrc-plugin` or `java-lyrics-plugin` to be present in the Lavalink node.
      *
      * @param {Track} track - The track to fetch the lyrics for.
      * @param {boolean} [skipTrackSource=false] - Whether to skip using the track's source URL.
      * @returns {Promise<Lyrics | NodeLinkGetLyrics>} A promise that resolves with the lyrics data.
      */
     getLyrics(track: Track, skipTrackSource?: boolean): Promise<Lyrics | NodeLinkGetLyrics>;
+    /**
+     * Subscribes to lyrics for a player.
+     * @param {string} guildId - The ID of the guild to subscribe to lyrics for.
+     * @param {boolean} [skipTrackSource=false] - Whether to skip using the track's source URL.
+     * @returns {Promise<unknown>} A promise that resolves when the subscription is complete.
+     * @throws {RangeError} If the node is not connected to the lavalink server or if the java-lyrics-plugin is not available.
+     */
+    lyricsSubscribe(guildId: string, skipTrackSource?: boolean): Promise<unknown>;
+    /**
+     * Unsubscribes from lyrics for a player.
+     * @param {string} guildId - The ID of the guild to unsubscribe from lyrics for.
+     * @returns {Promise<unknown>} A promise that resolves when the unsubscription is complete.
+     * @throws {RangeError} If the node is not connected to the lavalink server or if the java-lyrics-plugin is not available.
+     */
+    lyricsUnsubscribe(guildId: string): Promise<unknown>;
     /**
      * Handles the event when a track becomes stuck during playback.
      * Stops the current track and emits a `trackStuck` event.
@@ -1691,6 +1748,30 @@ declare class Node$1 {
      * @param {SponsorBlockChapterStarted} payload - The event payload containing additional data about the chapter started event.
      */
     private sponsorBlockChapterStarted;
+    /**
+     * Emitted when lyrics for a track are found.
+     * The payload of the event will contain the lyrics.
+     * @param {Player} player - The player associated with the lyrics.
+     * @param {Track} track - The track associated with the lyrics.
+     * @param {LyricsFoundEvent} payload - The event payload containing additional data about the lyrics found event.
+     */
+    private lyricsFound;
+    /**
+     * Emitted when lyrics for a track are not found.
+     * The payload of the event will contain the track.
+     * @param {Player} player - The player associated with the lyrics.
+     * @param {Track} track - The track associated with the lyrics.
+     * @param {LyricsNotFoundEvent} payload - The event payload containing additional data about the lyrics not found event.
+     */
+    private lyricsNotFound;
+    /**
+     * Emitted when a line of lyrics for a track is received.
+     * The payload of the event will contain the lyrics line.
+     * @param {Player} player - The player associated with the lyrics line.
+     * @param {Track} track - The track associated with the lyrics line.
+     * @param {LyricsLineEvent} payload - The event payload containing additional data about the lyrics line event.
+     */
+    private lyricsLine;
     /**
      * Fetches Lavalink node information.
      * @returns {Promise<LavalinkInfo>} A promise that resolves to the Lavalink node information.
@@ -2850,4 +2931,4 @@ declare class OceanicManager extends Manager {
 }
 
 export { AutoPlayPlatform, AutoPlayUtils, AvailableFilters, DetritusManager, DiscordJSManager, ErisManager, Filters, LoadTypes, Manager, ManagerEventTypes, Node$1 as Node, OceanicManager, Player, PlayerStateEventTypes, Plugin$1 as Plugin, Queue, Rest, SearchPlatform, SeverityTypes, SponsorBlockSegment, StateStorageType, StateTypes, Structure, TrackEndReasonTypes, TrackPartial, TrackSourceTypes, TrackUtils, UseNodeOptions };
-export type { CPUStats, DiscordPacket, EndSpeakingEventVoiceReceiver, EndSpeakingEventVoiceReceiverData, EqualizerBand, ErrorOrEmptySearchResult, Exception, Extendable, FrameStats, IQueue, LavaPlayer, LavalinkInfo, LavalinkResponse, LoadType, Lyrics, LyricsLine, ManagerEvents, ManagerInitOptions, ManagerOptions, MemoryStats, NodeLinkGetLyrics, NodeLinkGetLyricsEmpty, NodeLinkGetLyricsError, NodeLinkGetLyricsMultiple, NodeLinkGetLyricsSingle, NodeMessage, NodeOptions, NodeStats, Payload, PlayOptions, PlayerEvent, PlayerEventType, PlayerEvents, PlayerOptions, PlayerStateUpdateEvent, PlayerUpdate, PlayerUpdateVoiceState, PlaylistData, PlaylistInfoData, PlaylistRawData, PlaylistSearchResult, RedisConfig, SearchQuery, SearchResult, SearchSearchResult, Severity, Sizes, SponsorBlockChapterStarted, SponsorBlockChaptersLoaded, SponsorBlockSegmentEventType, SponsorBlockSegmentEvents, SponsorBlockSegmentSkipped, SponsorBlockSegmentsLoaded, StartSpeakingEventVoiceReceiver, StartSpeakingEventVoiceReceiverData, StateStorageOptions, Track, TrackData, TrackDataInfo, TrackEndEvent, TrackEndReason, TrackExceptionEvent, TrackPluginInfo, TrackSearchResult, TrackSourceName, TrackStartEvent, TrackStuckEvent, UseNodeOption, VoicePacket, VoiceReceiverEvent, VoiceServer, VoiceServerUpdate, VoiceState, WebSocketClosedEvent };
+export type { CPUStats, DiscordPacket, EndSpeakingEventVoiceReceiver, EndSpeakingEventVoiceReceiverData, EqualizerBand, ErrorOrEmptySearchResult, Exception, Extendable, FrameStats, IQueue, LavaPlayer, LavalinkInfo, LavalinkResponse, LoadType, Lyrics, LyricsEvent, LyricsEventType, LyricsFoundEvent, LyricsLine, LyricsLineEvent, LyricsNotFoundEvent, ManagerEvents, ManagerInitOptions, ManagerOptions, MemoryStats, NodeLinkGetLyrics, NodeLinkGetLyricsEmpty, NodeLinkGetLyricsError, NodeLinkGetLyricsMultiple, NodeLinkGetLyricsSingle, NodeMessage, NodeOptions, NodeStats, Payload, PlayOptions, PlayerEvent, PlayerEventType, PlayerEvents, PlayerOptions, PlayerStateUpdateEvent, PlayerUpdate, PlayerUpdateVoiceState, PlaylistData, PlaylistInfoData, PlaylistRawData, PlaylistSearchResult, RedisConfig, SearchQuery, SearchResult, SearchSearchResult, Severity, Sizes, SponsorBlockChapterStarted, SponsorBlockChaptersLoaded, SponsorBlockSegmentEventType, SponsorBlockSegmentEvents, SponsorBlockSegmentSkipped, SponsorBlockSegmentsLoaded, StartSpeakingEventVoiceReceiver, StartSpeakingEventVoiceReceiverData, StateStorageOptions, Track, TrackData, TrackDataInfo, TrackEndEvent, TrackEndReason, TrackExceptionEvent, TrackPluginInfo, TrackSearchResult, TrackSourceName, TrackStartEvent, TrackStuckEvent, UseNodeOption, VoicePacket, VoiceReceiverEvent, VoiceServer, VoiceServerUpdate, VoiceState, WebSocketClosedEvent };

package/dist/structures/Enums.js

@@ -141,6 +141,9 @@ var ManagerEventTypes;
     ManagerEventTypes["ChapterStarted"] = "chapterStarted";
     ManagerEventTypes["ChaptersLoaded"] = "chaptersLoaded";
     ManagerEventTypes["Debug"] = "debug";
+    ManagerEventTypes["LyricsFoundEvent"] = "lyricsFoundEvent";
+    ManagerEventTypes["LyricsLineEvent"] = "lyricsLineEvent";
+    ManagerEventTypes["LyricsNotFoundEvent"] = "lyricsNotFoundEvent";
     ManagerEventTypes["NodeConnect"] = "nodeConnect";
     ManagerEventTypes["NodeCreate"] = "nodeCreate";
     ManagerEventTypes["NodeDestroy"] = "nodeDestroy";

package/dist/structures/Node.js

@@ -485,6 +485,15 @@ class Node {
             case "ChapterStarted":
                 this.sponsorBlockChapterStarted(player, track, payload);
                 break;
+            case "LyricsFoundEvent":
+                this.lyricsFound(player, track, payload);
+                break;
+            case "LyricsNotFoundEvent":
+                this.lyricsNotFound(player, track, payload);
+                break;
+            case "LyricsLineEvent":
+                this.lyricsLine(player, track, payload);
+                break;
             default:
                 error = new Error(`Node#event unknown event '${type}'.`);
                 this.manager.emit(Enums_1.ManagerEventTypes.NodeError, this, error);
@@ -734,19 +743,28 @@ class Node {
     }
     /**
      * Fetches the lyrics of a track from the Lavalink node.
-     * This method uses the `lavalyrics-plugin` to fetch the lyrics.
-     * If the plugin is not available, it will throw a RangeError.
+     *
+     * If the node is a NodeLink, it will use the `NodeLinkGetLyrics` method to fetch the lyrics.
+     *
+     * Requires the `lavalyrics-plugin` to be present in the Lavalink node.
+     * Requires the `lavasrc-plugin` or `java-lyrics-plugin` to be present in the Lavalink node.
      *
      * @param {Track} track - The track to fetch the lyrics for.
      * @param {boolean} [skipTrackSource=false] - Whether to skip using the track's source URL.
      * @returns {Promise<Lyrics | NodeLinkGetLyrics>} A promise that resolves with the lyrics data.
      */
     async getLyrics(track, skipTrackSource = false) {
+        if (!this.connected)
+            throw new RangeError(`The node is not connected to the lavalink server: ${this.options.identifier}`);
         if (this.isNodeLink) {
             return (await this.rest.get(`/v4/lyrics?track=${encodeURIComponent(track.track)}&skipTrackSource=${skipTrackSource}`));
         }
-        if (!this.info.plugins.some((plugin) => plugin.name === "lavalyrics-plugin"))
-            throw new RangeError(`there is no lavalyrics-plugin available in the lavalink node: ${this.options.identifier}`);
+        if (!this.info.plugins.some((plugin) => plugin.name === "lavalyrics-plugin")) {
+            throw new RangeError(`The plugin "lavalyrics-plugin" must be present in the lavalink node: ${this.options.identifier}`);
+        }
+        if (!this.info.plugins.some((plugin) => plugin.name === "lavasrc-plugin" || plugin.name === "java-lyrics-plugin")) {
+            throw new RangeError(`One of the following plugins must also be present in the lavalink node: "lavasrc-plugin" or "java-lyrics-plugin" (Node: ${this.options.identifier})`);
+        }
         return ((await this.rest.get(`/v4/lyrics?track=${encodeURIComponent(track.track)}&skipTrackSource=${skipTrackSource}`)) || {
             source: null,
             provider: null,
@@ -755,6 +773,42 @@ class Node {
             plugin: [],
         });
     }
+    /**
+     * Subscribes to lyrics for a player.
+     * @param {string} guildId - The ID of the guild to subscribe to lyrics for.
+     * @param {boolean} [skipTrackSource=false] - Whether to skip using the track's source URL.
+     * @returns {Promise<unknown>} A promise that resolves when the subscription is complete.
+     * @throws {RangeError} If the node is not connected to the lavalink server or if the java-lyrics-plugin is not available.
+     */
+    async lyricsSubscribe(guildId, skipTrackSource = false) {
+        if (!this.connected)
+            throw new RangeError(`The node is not connected to the lavalink server: ${this.options.identifier}`);
+        if (this.isNodeLink)
+            throw new RangeError(`The node is a node link: ${this.options.identifier}`);
+        if (!this.info.plugins.some((plugin) => plugin.name === "lavalyrics-plugin")) {
+            throw new RangeError(`The plugin "lavalyrics-plugin" must be present in the lavalink node: ${this.options.identifier}`);
+        }
+        if (!this.info.plugins.some((plugin) => plugin.name === "lavasrc-plugin" || plugin.name === "java-lyrics-plugin")) {
+            throw new RangeError(`One of the following plugins must also be present in the lavalink node: "lavasrc-plugin" or "java-lyrics-plugin" (Node: ${this.options.identifier})`);
+        }
+        return await this.rest.post(`/v4/sessions/${this.sessionId}/players/${guildId}/lyrics/subscribe?skipTrackSource=${skipTrackSource}`, {});
+    }
+    /**
+     * Unsubscribes from lyrics for a player.
+     * @param {string} guildId - The ID of the guild to unsubscribe from lyrics for.
+     * @returns {Promise<unknown>} A promise that resolves when the unsubscription is complete.
+     * @throws {RangeError} If the node is not connected to the lavalink server or if the java-lyrics-plugin is not available.
+     */
+    async lyricsUnsubscribe(guildId) {
+        if (!this.connected)
+            throw new RangeError(`The node is not connected to the lavalink server: ${this.options.identifier}`);
+        if (this.isNodeLink)
+            throw new RangeError(`The node is a node link: ${this.options.identifier}`);
+        if (!this.info.plugins.some((plugin) => plugin.name === "java-lyrics-plugin")) {
+            throw new RangeError(`there is no java-lyrics-plugin available in the lavalink node: ${this.options.identifier}`);
+        }
+        return await this.rest.delete(`/v4/sessions/${this.sessionId}/players/${guildId}/lyrics/subscribe`);
+    }
     /**
      * Handles the event when a track becomes stuck during playback.
      * Stops the current track and emits a `trackStuck` event.
@@ -833,6 +887,36 @@ class Node {
     sponsorBlockChapterStarted(player, track, payload) {
         return this.manager.emit(Enums_1.ManagerEventTypes.ChapterStarted, player, track, payload);
     }
+    /**
+     * Emitted when lyrics for a track are found.
+     * The payload of the event will contain the lyrics.
+     * @param {Player} player - The player associated with the lyrics.
+     * @param {Track} track - The track associated with the lyrics.
+     * @param {LyricsFoundEvent} payload - The event payload containing additional data about the lyrics found event.
+     */
+    lyricsFound(player, track, payload) {
+        return this.manager.emit(Enums_1.ManagerEventTypes.LyricsFoundEvent, player, track, payload);
+    }
+    /**
+     * Emitted when lyrics for a track are not found.
+     * The payload of the event will contain the track.
+     * @param {Player} player - The player associated with the lyrics.
+     * @param {Track} track - The track associated with the lyrics.
+     * @param {LyricsNotFoundEvent} payload - The event payload containing additional data about the lyrics not found event.
+     */
+    lyricsNotFound(player, track, payload) {
+        return this.manager.emit(Enums_1.ManagerEventTypes.LyricsNotFoundEvent, player, track, payload);
+    }
+    /**
+     * Emitted when a line of lyrics for a track is received.
+     * The payload of the event will contain the lyrics line.
+     * @param {Player} player - The player associated with the lyrics line.
+     * @param {Track} track - The track associated with the lyrics line.
+     * @param {LyricsLineEvent} payload - The event payload containing additional data about the lyrics line event.
+     */
+    lyricsLine(player, track, payload) {
+        return this.manager.emit(Enums_1.ManagerEventTypes.LyricsLineEvent, player, track, payload);
+    }
     /**
      * Fetches Lavalink node information.
      * @returns {Promise<LavalinkInfo>} A promise that resolves to the Lavalink node information.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "magmastream",
-	"version": "2.9.0-dev.33",
+	"version": "2.9.0-dev.34",
 	"description": "A user-friendly Lavalink client designed for NodeJS.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",