lavalink-client 2.1.3 → 2.1.5

package/README.md

@@ -24,7 +24,7 @@ Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Profi
 
 # Install
 
-Latest stable Version: (currently, unreleased)
+Latest stable Version: **`v2.1.3`**
 
 <details><summary>👉 via NPM</summary>
 
@@ -57,7 +57,12 @@ yarn add tomato6966/lavalink-client
 
 # Documentation
 
-Check out the [Documentation](https://lc4.gitbook.io/lavalink-client) for **Examples**, and **__detailled__ Docs**, and to figure out **how to get started**. *note: it's not fully done yet (see the docs)*
+Check out the [Documentation](https://lc4.gitbook.io/lavalink-client) | or the [TSDocumentation](https://tomato6966.github.io/lavalink-client/) for **Examples**, and **__detailled__ Docs**, and to figure out **how to get started**. *note: it's not fully done yet (see the docs)*
+
+# Used in:
+
+- [Betty](https://betty.cx/)
+- [Mivator](https://discord.gg/5dUb7M2qCj)
 
 # Features
 
@@ -97,6 +102,91 @@ Check out the [Documentation](https://lc4.gitbook.io/lavalink-client) for **Exam
 
 - 😁 Much much more!
 
+*** 
+
+# All Events:
+
+## On **Lavalink-Manager**:
+> *Player related logs*
+- `playerCreate` ➡️ `(player) => {}`
+- `playerDestroy` ➡️ `(player, reason) => {}`
+- `playerDisconnect` ➡️ `(player, voiceChannelId) => {}`
+- `playerMove` ➡️ `(player, oldChannelId, newChannelId) => {}`
+  - Updating the voice channel is handled by the client automatically
+- `playerSocketClosed` ➡️ `(player, payload) => {}`
+
+> *Track / Manager related logs*
+- `trackStart` ➡️ `(player, track, payload) => {}`
+- `trackStuck` ➡️ `(player, track, payload) => {}`
+- `trackError` ➡️ `(player, track, payload) => {}`
+- `trackEnd` ➡️ `(player, track, payload) => {}`
+- `queueEnd` ➡️ `(player, track, payload) => {}`
+- `playerUpdate` ➡️ `(player) => {}`
+
+```js
+client.lavalink.on("create", (node, payload) => {
+  console.log(`The Lavalink Node #${node.id} connected`);
+});
+// for all node based errors:
+client.lavalink.on("error", (node, error, payload) => {
+  console.error(`The Lavalink Node #${node.id} errored: `, error);
+  console.error(`Error-Payload: `, payload)
+});
+```
+
+## On **Node-Manager**:
+- `raw` ➡️ `(node, payload) => {}`
+- `disconnect` ➡️ `(node, reason) => {}`
+- `connect` ➡️ `(node) => {}`
+- `reconnecting` ➡️ `(node) => {}`
+- `create` ➡️ `(node) => {}`
+- `destroy` ➡️ `(node) => {}`
+- `error` ➡️ `(node, error, payload) => {}`
+- `resumed` ➡️ `(node, payload, players) => {}`
+  - Resuming needs to be handled manually by you *(aka add the players to the manager)*
+- e.g.:
+```js
+client.lavalink.nodeManager.on("create", (node, payload) => {
+  console.log(`The Lavalink Node #${node.id} connected`);
+});
+// for all node based errors:
+client.lavalink.nodeManager.on("error", (node, error, payload) => {
+  console.error(`The Lavalink Node #${node.id} errored: `, error);
+  console.error(`Error-Payload: `, payload)
+});
+```
+
+## How to log queue logs?
+> When creating the manager, add the option: `queueOptions.queueChangesWatcher: new myCustomWatcher(botClient)`
+> E.g:
+```js
+import { QueueChangesWatcher, LavalinkManager } from "lavalink-client";
+
+class myCustomWatcher implements QueueChangesWatcher {
+    constructor(client) {
+        this.client = client;
+    }
+    shuffled(guildId, oldStoredQueue, newStoredQueue) {
+        console.log(`${this.client.guilds.cache.get(guildId)?.name || guildId}: Queue got shuffled`)    
+    }
+    tracksAdd(guildId, tracks, position, oldStoredQueue, newStoredQueue) {
+        console.log(`${this.client.guilds.cache.get(guildId)?.name || guildId}: ${tracks.length} Tracks got added into the Queue at position #${position}`);    
+    }
+    tracksRemoved(guildId, tracks, position, oldStoredQueue, newStoredQueue) {
+        console.log(`${this.client.guilds.cache.get(guildId)?.name || guildId}: ${tracks.length} Tracks got removed from the Queue at position #${position}`);
+    }
+}
+
+client.lavalink = new LavalinkManager({
+  // ... other options
+  queueOptions: {
+    queueChangesWatcher: new myCustomWatcher(client)
+  }
+})
+```
+
+***
+
 # UpdateLog
 
 ## **Version 1.2.0**

package/dist/cjs/structures/Filters.d.ts

@@ -61,27 +61,27 @@ export declare class FilterManager {
      */
     setRate(rate?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the rotation effect, (Optional: provide your Own Data)
+     * Enables / Disables the rotation effect, (Optional: provide your Own Data)
      * @param rotationHz
      * @returns
      */
     toggleRotation(rotationHz?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the Vibrato effect, (Optional: provide your Own Data)
+     * Enables / Disables the Vibrato effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
      */
     toggleVibrato(frequency?: number, depth?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the Tremolo effect, (Optional: provide your Own Data)
+     * Enables / Disables the Tremolo effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
      */
     toggleTremolo(frequency?: number, depth?: number): Promise<boolean>;
     /**
-     * Enabels / Disables the LowPass effect, (Optional: provide your Own Data)
+     * Enables / Disables the LowPass effect, (Optional: provide your Own Data)
      * @param smoothing
      * @returns
      */
@@ -94,14 +94,14 @@ export declare class FilterManager {
     };
     lavalinkFilterPlugin: {
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delay
          * @param decay
          * @returns
          */
         toggleEcho: (delay?: number, decay?: number) => Promise<boolean>;
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delays
          * @param gains
          * @returns
@@ -109,7 +109,7 @@ export declare class FilterManager {
         toggleReverb: (delays?: number[], gains?: number[]) => Promise<boolean>;
     };
     /**
-     * Enables / Disabels a Nightcore-like filter Effect. Disables/Overwrides both: custom and Vaporwave Filter
+     * Enables / Disables a Nightcore-like filter Effect. Disables/Overrides both: custom and Vaporwave Filter
      * @param speed
      * @param pitch
      * @param rate
@@ -117,7 +117,7 @@ export declare class FilterManager {
      */
     toggleNightcore(speed?: number, pitch?: number, rate?: number): Promise<boolean>;
     /**
-     * Enables / Disabels a Vaporwave-like filter Effect. Disables/Overwrides both: custom and nightcore Filter
+     * Enables / Disables a Vaporwave-like filter Effect. Disables/Overrides both: custom and nightcore Filter
      * @param speed
      * @param pitch
      * @param rate

package/dist/cjs/structures/Filters.js

@@ -266,12 +266,12 @@ class FilterManager {
                 rotationHz: 0
             },
             tremolo: {
-                frequency: 2,
-                depth: 0.1 // 0 < x = 1
+                frequency: 0,
+                depth: 0 // 0 < x = 1
             },
             vibrato: {
-                frequency: 2,
-                depth: 0.1 // 0 < x = 1
+                frequency: 0,
+                depth: 0 // 0 < x = 1
             },
             channelMix: exports.audioOutputsData.stereo,
         })) {
@@ -374,7 +374,7 @@ class FilterManager {
         return this.filters.custom;
     }
     /**
-     * Enabels / Disables the rotation effect, (Optional: provide your Own Data)
+     * Enables / Disables the rotation effect, (Optional: provide your Own Data)
      * @param rotationHz
      * @returns
      */
@@ -386,7 +386,7 @@ class FilterManager {
         return await this.applyPlayerFilters(), this.filters.rotation;
     }
     /**
-     * Enabels / Disables the Vibrato effect, (Optional: provide your Own Data)
+     * Enables / Disables the Vibrato effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
@@ -401,7 +401,7 @@ class FilterManager {
         return this.filters.vibrato;
     }
     /**
-     * Enabels / Disables the Tremolo effect, (Optional: provide your Own Data)
+     * Enables / Disables the Tremolo effect, (Optional: provide your Own Data)
      * @param frequency
      * @param depth
      * @returns
@@ -416,7 +416,7 @@ class FilterManager {
         return this.filters.tremolo;
     }
     /**
-     * Enabels / Disables the LowPass effect, (Optional: provide your Own Data)
+     * Enables / Disables the LowPass effect, (Optional: provide your Own Data)
      * @param smoothing
      * @returns
      */
@@ -528,7 +528,7 @@ class FilterManager {
     };
     lavalinkFilterPlugin = {
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delay
          * @param decay
          * @returns
@@ -553,7 +553,7 @@ class FilterManager {
             return this.filters.lavalinkFilterPlugin.echo;
         },
         /**
-         * Enabels / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
+         * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
          * @param delays
          * @param gains
          * @returns
@@ -579,7 +579,7 @@ class FilterManager {
         }
     };
     /**
-     * Enables / Disabels a Nightcore-like filter Effect. Disables/Overwrides both: custom and Vaporwave Filter
+     * Enables / Disables a Nightcore-like filter Effect. Disables/Overrides both: custom and Vaporwave Filter
      * @param speed
      * @param pitch
      * @param rate
@@ -598,7 +598,7 @@ class FilterManager {
         return this.filters.nightcore;
     }
     /**
-     * Enables / Disabels a Vaporwave-like filter Effect. Disables/Overwrides both: custom and nightcore Filter
+     * Enables / Disables a Vaporwave-like filter Effect. Disables/Overrides both: custom and nightcore Filter
      * @param speed
      * @param pitch
      * @param rate

package/dist/cjs/structures/LavalinkManager.d.ts

@@ -6,10 +6,6 @@ import { DestroyReasonsType, Player, PlayerJson, PlayerOptions } from "./Player"
 import { ManagerQueueOptions } from "./Queue";
 import { Track, UnresolvedTrack } from "./Track";
 import { ChannelDeletePacket, GuildShardPayload, ManagerUtils, MiniMap, SearchPlatform, SponsorBlockChaptersLoaded, SponsorBlockChapterStarted, SponsorBlockSegmentSkipped, SponsorBlockSegmentsLoaded, TrackEndEvent, TrackExceptionEvent, TrackStartEvent, TrackStuckEvent, VoicePacket, VoiceServer, VoiceState, WebSocketClosedEvent } from "./Utils";
-export interface LavalinkManager {
-    nodeManager: NodeManager;
-    utils: ManagerUtils;
-}
 export interface BotClientOptions {
     /** Bot Client Id */
     id: string;
@@ -168,31 +164,186 @@ interface LavalinkManagerEvents {
     "ChaptersLoaded": (player: Player, track: Track | UnresolvedTrack, payload: SponsorBlockChaptersLoaded) => void;
 }
 export interface LavalinkManager {
-    options: ManagerOptions;
+    /** @private */
     on<U extends keyof LavalinkManagerEvents>(event: U, listener: LavalinkManagerEvents[U]): this;
+    /** @private */
     emit<U extends keyof LavalinkManagerEvents>(event: U, ...args: Parameters<LavalinkManagerEvents[U]>): boolean;
 }
 export declare class LavalinkManager extends EventEmitter {
-    static DefaultSources: Record<SearchPlatform, import("./Utils").LavalinkSearchPlatform | import("./Utils").ClientCustomSearchPlatformUtils>;
-    static SourceLinksRegexes: Record<import("./Utils").SourcesRegex, RegExp>;
+    /** The Options of LavalinkManager (changeable) */
+    options: ManagerOptions;
+    /** LavalinkManager's NodeManager to manage all Nodes */
+    nodeManager: NodeManager;
+    /** LavalinkManager's Utils Class */
+    utils: ManagerUtils;
+    /** Wether the manager was initiated or not */
     initiated: boolean;
+    /** All Players stored in a MiniMap */
     readonly players: MiniMap<string, Player>;
+    /**
+     * Applies the options provided by the User
+     * @param options
+     * @returns
+     */
     private applyOptions;
+    /**
+     * Validates the current manager's options
+     * @param options
+     */
     private validateOptions;
+    /**
+     * Create the Lavalink Manager
+     * @param options
+     *
+     * @example
+     * ```ts
+     * //const client = new Client({...}); // create your BOT Client (e.g. via discord.js)
+     * client.lavalink = new LavalinkManager({
+     *   nodes: [
+     *     {
+     *       authorization: "yourverystrongpassword",
+     *       host: "localhost",
+     *       port: 2333,
+     *       id: "testnode"
+     *     },
+     *     sendToShard(guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+     *     client: {
+     *       id: process.env.CLIENT_ID,
+     *       username: "TESTBOT"
+     *     },
+     *     // optional Options:
+     *     autoSkip: true,
+     *     playerOptions: {
+     *       applyVolumeAsFilter: false,
+     *       clientBasedPositionUpdateInterval: 150,
+     *       defaultSearchPlatform: "ytmsearch",
+     *       volumeDecrementer: 0.75,
+     *       //requesterTransformer: YourRequesterTransformerFunction,
+     *       onDisconnect: {
+     *         autoReconnect: true,
+     *         destroyPlayer: false
+     *       },
+     *       onEmptyQueue: {
+     *         destroyAfterMs: 30_000,
+     *         //autoPlayFunction: YourAutoplayFunction,
+     *       },
+     *       useUnresolvedData: true
+     *     },
+     *     queueOptions: {
+     *       maxPreviousTracks: 25,
+     *       //queueStore: yourCustomQueueStoreManagerClass,
+     *       //queueChangesWatcher: yourCustomQueueChangesWatcherClass
+     *     },
+     *     linksBlacklist: [],
+     *     linksWhitelist: [],
+     *     advancedOptions: {
+     *       debugOptions: {
+     *         noAudio: false,
+     *         playerDestroy: {
+     *           dontThrowError: false,
+     *           debugLogs: false
+     *         }
+     *       }
+     *     }
+     *   ]
+     * })
+     * ```
+     */
     constructor(options: ManagerOptions);
-    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Get a Player from Lava
+     * @param guildId The guildId of the player
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.getPlayer(interaction.guildId);
+     * ```
+     * A quicker and easier way than doing:
+     * ```ts
+     * const player = client.lavalink.players.get(interaction.guildId);
+     * ```
+     * @returns
+     */
     getPlayer(guildId: string): Player;
+    /**
+     * Create a Music-Player. If a player exists, then it returns it before creating a new one
+     * @param options
+     * @returns
+     *
+     * @example
+     * ```ts
+     * const player = client.lavalink.createPlayer({
+     *   guildId: interaction.guildId,
+     *   voiceChannelId: interaction.member.voice.channelId,
+     *   // everything below is optional
+     *   textChannelId: interaction.channelId,
+     *   volume: 100,
+     *   selfDeaf: true,
+     *   selfMute: false,
+     *   instaUpdateFiltersFix: true,
+     *   applyVolumeAsFilter: false
+     *   //only needed if you want to autopick node by region (configured by you)
+     *   // vcRegion: interaction.member.voice.rtcRegion,
+     *   // provide a specific node
+     *   // node: client.lavalink.nodeManager.leastUsedNodes("memory")[0]
+     * });
+     * ```
+     */
+    createPlayer(options: PlayerOptions): Player;
+    /**
+     * Destroy a player with optional destroy reason and disconnect it from the voice channel
+     * @param guildId
+     * @param destroyReason
+     * @returns
+     *
+     * @example
+     * ```ts
+     * client.lavalink.destroyPlayer(interaction.guildId, "forcefully destroyed the player");
+     * // recommend to do it on the player tho: player.destroy("forcefully destroyed the player");
+     * ```
+     */
     destroyPlayer(guildId: string, destroyReason?: string): Promise<Player>;
+    /**
+     * Delete's a player from the cache without destroying it on lavalink (only works when it's disconnected)
+     * @param guildId
+     * @returns
+     */
     deletePlayer(guildId: string): boolean;
+    /**
+     * Checks wether the the lib is useable based on if any node is connected
+     */
     get useable(): boolean;
     /**
-     * Initiates the Manager.
+     * Initiates the Manager, creates all nodes and connects all of them
      * @param clientData
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot ready event
+     * client.on("ready", () => {
+     *   client.lavalink.init({
+     *     id: client.user.id,
+     *     username: client.user.username
+     *   });
+     * });
+     * ```
      */
     init(clientData: BotClientOptions): Promise<this>;
     /**
      * Sends voice data to the Lavalink server.
+     * ! Without this the library won't work
      * @param data
+     *
+     * @example
+     *
+     * ```ts
+     * // on the bot "raw" event
+     * client.on("raw", (d) => {
+     *   // required in order to send audio updates and register channel deletion etc.
+     *   client.lavalink.sendRawData(d)
+     * })
+     * ```
      */
     sendRawData(data: VoicePacket | VoiceServer | VoiceState | ChannelDeletePacket): Promise<void>;
 }