lavalink-client 2.6.3 → 2.6.5

package/dist/index.js

@@ -671,6 +671,29 @@ var ManagerUtils = class {
     if ("requestTimeout" in data && (typeof data.requestTimeout !== "number" || isNaN(data.requestTimeout) || data.requestTimeout <= 0 && data.requestTimeout !== void 0)) return false;
     return true;
   }
+  /**
+   * Validate tracks based on duration wether they are playble or broken tracks.
+   * most tracks should be longer than 30s, so you can put a minDuration of 29e3 (cause preview tracks are exactly 30s) or put 0.
+   * This check is not done automatically, you need to check it yourself by doing:
+   * @example
+   * ```ts
+   * const tracks = await player.search("Adele");
+   *
+   * // short hand:
+   * const validTracks = tracks.filter(client.lavalink.utils.isNotBrokenTrack)
+   * // or with options:
+   * const vaildTracks = tracks.filter(t => client.lavalink.utils.isNotBrokenTrack(t, 29e3));
+   *
+   * // then you can add it to the queue.
+   * await player.queue.add(validTracks);
+   * ```
+   */
+  isNotBrokenTrack(data, minDuration = 29e3) {
+    if (typeof data?.info?.duration !== "number" || isNaN(data?.info?.duration)) return false;
+    if (data.info.duration <= Math.max(minDuration, 0)) return false;
+    if (!data.info) return false;
+    return this.isTrack(data);
+  }
   /**
    * Validate if a data is equal to a track
    * @param data the Track to validate
@@ -2772,6 +2795,7 @@ var DEFAULT_FILTER_DATAS = {
   }*/
 };
 var FilterManager = class {
+  static EQList = EQList;
   /** The Equalizer bands currently applied to the Lavalink Server */
   equalizerBands = [];
   /** Private Util for the instaFix Filters option */
@@ -2809,6 +2833,17 @@ var FilterManager = class {
   }
   /**
    * Apply Player filters for lavalink filter sending data, if the filter is enabled / not
+   *
+   * @returns {Promise<void>}
+   *
+   * @example
+   * ```ts
+   * // Apply the filters after changing them manually:
+   * player.filterManager.data.volume = 0.5;
+   * // maybe you wanna manually set a distorition filter? then do it like this...
+   * player.filterManager.data.distortion = { sinOffset: 0.5, sinScale: 2, cosOffset: 0.5, cosScale: 2, tanOffset: 0.5, tanScale: 2, offset: 0.5, scale: 2 };
+   * await player.filterManager.applyPlayerFilters();
+   * ```
    */
   async applyPlayerFilters() {
     const sendData = { ...this.data };
@@ -2848,9 +2883,17 @@ var FilterManager = class {
     return;
   }
   /**
-   * Checks if the filters are correctly stated (active / not-active)
+   * Checks if the filters are correctly stated (active / not-active) - mostly used internally.
    * @param oldFilterTimescale
-   * @returns
+   * @returns {boolean} True, if the check was successfull
+   *
+   * @example
+   * ```ts
+   * // Check the filter states
+   * player.filterManager.checkFiltersState();
+   * // Apply the filters after checking
+   * await player.filterManager.applyPlayerFilters();
+   * ```
    */
   checkFiltersState(oldFilterTimescale) {
     this.filters.rotation = this.data.rotation.rotationHz !== 0;
@@ -2876,6 +2919,13 @@ var FilterManager = class {
   }
   /**
    * Reset all Filters
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Reset all filters
+   * await player.filterManager.resetFilters();
+   * ```
    */
   async resetFilters() {
     this.filters.lavalinkLavaDspxPlugin.echo = false;
@@ -2893,83 +2943,21 @@ var FilterManager = class {
     this.filters.karaoke = false;
     this.filters.volume = false;
     this.filters.audioOutput = "stereo";
-    for (const [key, value] of Object.entries({
-      volume: 1,
-      lowPass: {
-        smoothing: 0
-      },
-      karaoke: {
-        level: 0,
-        monoLevel: 0,
-        filterBand: 0,
-        filterWidth: 0
-      },
-      timescale: {
-        speed: 1,
-        // 0 = x
-        pitch: 1,
-        // 0 = x
-        rate: 1
-        // 0 = x
-      },
-      pluginFilters: {
-        "lavalink-filter-plugin": {
-          echo: {
-            // delay: 0, // in seconds
-            // decay: 0 // 0 < 1
-          },
-          reverb: {
-            // delays: [], // [0.037, 0.042, 0.048, 0.053]
-            // gains: [] // [0.84, 0.83, 0.82, 0.81]
-          }
-        },
-        "high-pass": {
-          // Cuts off frequencies lower than the specified {cutoffFrequency}.
-          // "cutoffFrequency": 1475, // Integer, higher than zero, in Hz.
-          // "boostFactor": 1.0    // Float, higher than 0.0. This alters volume output. A value of 1.0 means no volume change.
-        },
-        "low-pass": {
-          // Cuts off frequencies higher than the specified {cutoffFrequency}.
-          // "cutoffFrequency": 284, // Integer, higher than zero, in Hz.
-          // "boostFactor": 1.24389    // Float, higher than 0.0. This alters volume output. A value of 1.0 means no volume change.
-        },
-        "normalization": {
-          // Attenuates peaking where peaks are defined as having a higher value than {maxAmplitude}.
-          // "maxAmplitude": 0.6327, // Float, within the range of 0.0 - 1.0. A value of 0.0 mutes the output.
-          // "adaptive": true    // false
-        },
-        "echo": {
-          // Self-explanatory; provides an echo effect.
-          // "echoLength": 0.5649, // Float, higher than 0.0, in seconds (1.0 = 1 second).
-          // "decay": 0.4649       // Float, within the range of 0.0 - 1.0. A value of 1.0 means no decay, and a value of 0.0 means
-        }
-      },
-      rotation: {
-        rotationHz: 0
-      },
-      tremolo: {
-        frequency: 0,
-        // 0 < x
-        depth: 0
-        // 0 < x = 1
-      },
-      vibrato: {
-        frequency: 0,
-        // 0 < x = 14
-        depth: 0
-        // 0 < x = 1
-      },
-      channelMix: audioOutputsData.stereo
-    })) {
-      this.data[key] = value;
-    }
+    this.data = structuredClone(DEFAULT_FILTER_DATAS);
     await this.applyPlayerFilters();
-    return this.filters;
+    return this;
   }
   /**
    * Set the Filter Volume
-   * @param volume
-   * @returns
+   * @param volume the volume (0.0 - 5.0)
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set Volume to 50%
+   * await player.filterManager.setVolume(0.5);
+   * // note this is a filter, so it will "jump" to the volume, i think it's like a "volume boost effect" so i marketed it as a filter
+   * ```
    */
   async setVolume(volume) {
     if (volume < 0 || volume > 5) throw new SyntaxError("Volume-Filter must be between 0 and 5");
@@ -2977,12 +2965,27 @@ var FilterManager = class {
     this.data.volume = volume;
     this.filters.volume = volume !== 1;
     await this.applyPlayerFilters();
-    return this.filters.volume;
+    return this;
   }
   /**
    * Set the AudioOutput Filter
-   * @param type
-   * @returns
+   * @param {AudioOutputs} type the audio output type
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set Audio Output to Mono
+   * await player.filterManager.setAudioOutput("mono");
+   *
+   * // Set Audio Output to Stereo
+   * await player.filterManager.setAudioOutput("stereo");
+   *
+   * // Set Audio Output to Left
+   * await player.filterManager.setAudioOutput("left");
+   *
+   * // Set Audio Output to Right
+   * await player.filterManager.setAudioOutput("right");
+   * ```
    */
   async setAudioOutput(type) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("channelMix")) throw new Error("Node#Info#filters does not include the 'channelMix' Filter (Node has it not enable)");
@@ -2991,12 +2994,18 @@ var FilterManager = class {
     this.data.channelMix = audioOutputsData[type];
     this.filters.audioOutput = type;
     await this.applyPlayerFilters();
-    return this.filters.audioOutput;
+    return this;
   }
   /**
    * Set custom filter.timescale#speed . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
-   * @param speed
-   * @returns
+   * @param {number} speed set the speed of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set Speed to 1.25 (disableds nightcore and vaporwave effect which are pre-made timescale settings of rate,pitch and speed)
+   * await player.filterManager.setSpeed(1.25);
+   * ```
    */
   async setSpeed(speed = 1) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("timescale")) throw new Error("Node#Info#filters does not include the 'timescale' Filter (Node has it not enable)");
@@ -3006,12 +3015,18 @@ var FilterManager = class {
     this.data.timescale = { ...DEFAULT_FILTER_DATAS.timescale, speed };
     this.isCustomFilterActive();
     await this.applyPlayerFilters();
-    return this.filters.custom;
+    return this;
   }
   /**
    * Set custom filter.timescale#pitch . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
-   * @param speed
-   * @returns
+   * @param  {number} pitch set the pitch of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set Pitch to 1.25 (disableds nightcore and vaporwave effect which are pre-made timescale settings of rate,pitch and speed)
+   * await player.filterManager.setPitch(1.25);
+   * ```
    */
   async setPitch(pitch = 1) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("timescale")) throw new Error("Node#Info#filters does not include the 'timescale' Filter (Node has it not enable)");
@@ -3021,12 +3036,18 @@ var FilterManager = class {
     this.data.timescale = { ...DEFAULT_FILTER_DATAS.timescale, pitch };
     this.isCustomFilterActive();
     await this.applyPlayerFilters();
-    return this.filters.custom;
+    return this;
   }
   /**
    * Set custom filter.timescale#rate . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
-   * @param speed
-   * @returns
+   * @param {number} rate set the rate of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set Rate to 1.25 (disableds nightcore and vaporwave effect which are pre-made timescale settings of rate,pitch and speed)
+   * await player.filterManager.setRate(1.25);
+   * ```
    */
   async setRate(rate = 1) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("timescale")) throw new Error("Node#Info#filters does not include the 'timescale' Filter (Node has it not enable)");
@@ -3036,12 +3057,21 @@ var FilterManager = class {
     this.data.timescale = { ...DEFAULT_FILTER_DATAS.timescale, rate };
     this.isCustomFilterActive();
     await this.applyPlayerFilters();
-    return this.filters.custom;
+    return this;
   }
   /**
    * Enables / Disables the rotation effect, (Optional: provide your Own Data)
-   * @param rotationHz
-   * @returns
+   * @param {number} rotationHz set the rotationHz of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Rotation filter with custom settings
+   * await player.filterManager.toggleRotation(0.4);
+   * // or use the defaults
+   * await player.filterManager.toggleRotation();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleRotation(rotationHz = 0.2) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("rotation")) throw new Error("Node#Info#filters does not include the 'rotation' Filter (Node has it not enable)");
@@ -3049,13 +3079,22 @@ var FilterManager = class {
     this.data.rotation = this.filters.rotation ? DEFAULT_FILTER_DATAS.rotation : { rotationHz };
     this.filters.rotation = !this.filters.rotation;
     await this.applyPlayerFilters();
-    return this.filters.rotation;
+    return this;
   }
   /**
    * Enables / Disables the Vibrato effect, (Optional: provide your Own Data)
-   * @param frequency
-   * @param depth
-   * @returns
+   * @param {number} frequency set the frequency of the filter
+   * @param {number} depth set the depth of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Vibrato filter with custom settings
+   * await player.filterManager.toggleVibrato(8, 0.5);
+   * // or use the defaults
+   * await player.filterManager.toggleVibrato();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleVibrato(frequency = 10, depth = 1) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("vibrato")) throw new Error("Node#Info#filters does not include the 'vibrato' Filter (Node has it not enable)");
@@ -3063,13 +3102,22 @@ var FilterManager = class {
     this.data.vibrato = this.filters.vibrato ? DEFAULT_FILTER_DATAS.vibrato : { depth, frequency };
     this.filters.vibrato = !this.filters.vibrato;
     await this.applyPlayerFilters();
-    return this.filters.vibrato;
+    return this;
   }
   /**
    * Enables / Disables the Tremolo effect, (Optional: provide your Own Data)
-   * @param frequency
-   * @param depth
-   * @returns
+   * @param {number} frequency set the frequency of the filter
+   * @param {number} depth set the depth of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Tremolo filter with custom settings
+   * await player.filterManager.toggleTremolo(5, 0.7);
+   * // or use the defaults
+   * await player.filterManager.toggleTremolo();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleTremolo(frequency = 4, depth = 0.8) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("tremolo")) throw new Error("Node#Info#filters does not include the 'tremolo' Filter (Node has it not enable)");
@@ -3077,12 +3125,21 @@ var FilterManager = class {
     this.data.tremolo = this.filters.tremolo ? DEFAULT_FILTER_DATAS.tremolo : { depth, frequency };
     this.filters.tremolo = !this.filters.tremolo;
     await this.applyPlayerFilters();
-    return this.filters.tremolo;
+    return this;
   }
   /**
    * Enables / Disables the LowPass effect, (Optional: provide your Own Data)
-   * @param smoothing
-   * @returns
+   * @param {number} smoothing set the smoothing of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle LowPass filter with custom settings
+   * await player.filterManager.toggleLowPass(30);
+   * // or use the defaults
+   * await player.filterManager.toggleLowPass();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleLowPass(smoothing = 20) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("lowPass")) throw new Error("Node#Info#filters does not include the 'lowPass' Filter (Node has it not enable)");
@@ -3090,14 +3147,26 @@ var FilterManager = class {
     this.data.lowPass = this.filters.lowPass ? DEFAULT_FILTER_DATAS.lowPass : { smoothing };
     this.filters.lowPass = !this.filters.lowPass;
     await this.applyPlayerFilters();
-    return this.filters.lowPass;
+    return this;
   }
+  /**
+   * Lavalink LavaDspx Plugin Filters
+   */
   lavalinkLavaDspxPlugin = {
     /**
      * Enables / Disables the LowPass effect, (Optional: provide your Own Data)
-     * @param boostFactor
-     * @param cutoffFrequency
-     * @returns
+     * @param {number} boostFactor set the boost factor of the filter
+     * @param {number} cutoffFrequency set the cutoff frequency of the filter
+     * @returns  {Promise<boolean>} the state of the filter after execution.
+     *
+     * @example
+     * ```ts
+     * // Toggle LowPass filter with custom settings
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleLowPass(1.2, 300);
+     * // or use the defaults
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleLowPass();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleLowPass: async (boostFactor = 1, cutoffFrequency = 80) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavadspx-plugin")) throw new Error("Node#Info#plugins does not include the lavadspx plugin");
@@ -3108,13 +3177,22 @@ var FilterManager = class {
       else this.data.pluginFilters["low-pass"] = { boostFactor, cutoffFrequency };
       this.filters.lavalinkLavaDspxPlugin.lowPass = !this.filters.lavalinkLavaDspxPlugin.lowPass;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkLavaDspxPlugin.lowPass;
+      return this;
     },
     /**
      * Enables / Disables the HighPass effect, (Optional: provide your Own Data)
-     * @param boostFactor
-     * @param cutoffFrequency
-     * @returns
+     * @param {number} boostFactor [] set the boost factor of the filter
+     * @param {number} cutoffFrequency set the cutoff frequency of the filter
+     * @returns  {Promise<boolean>} the state of the filter after execution.
+     *
+     * @example
+     * ```ts
+     * // Toggle HighPass filter with custom settings
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleHighPass(1.2, 150); // custom values
+     * // or use the defaults
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleHighPass();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleHighPass: async (boostFactor = 1, cutoffFrequency = 80) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavadspx-plugin")) throw new Error("Node#Info#plugins does not include the lavadspx plugin");
@@ -3125,13 +3203,22 @@ var FilterManager = class {
       else this.data.pluginFilters["high-pass"] = { boostFactor, cutoffFrequency };
       this.filters.lavalinkLavaDspxPlugin.highPass = !this.filters.lavalinkLavaDspxPlugin.highPass;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkLavaDspxPlugin.highPass;
+      return this;
     },
     /**
      * Enables / Disables the Normalization effect.
      * @param {number} [maxAmplitude=0.75] - The maximum amplitude of the audio.
-     * @param {boolean} [adaptive=true] - Whether to use adaptive normalization or not.
-     * @returns {Promise<boolean>} - The state of the filter after execution.
+     * @param {boolean} [adaptive=true] Whether to use adaptive normalization or not.
+     * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+     *
+     * @example
+     * ```ts
+     * // Toggle Normalization filter with custom settings
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleNormalization(0.9, false); // custom values
+     * // or use the defaults
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleNormalization();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleNormalization: async (maxAmplitude = 0.75, adaptive = true) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavadspx-plugin")) throw new Error("Node#Info#plugins does not include the lavadspx plugin");
@@ -3142,13 +3229,22 @@ var FilterManager = class {
       else this.data.pluginFilters.normalization = { adaptive, maxAmplitude };
       this.filters.lavalinkLavaDspxPlugin.normalization = !this.filters.lavalinkLavaDspxPlugin.normalization;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkLavaDspxPlugin.normalization;
+      return this;
     },
     /**
      * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
-     * @param {number} [decay=0.5] - The decay of the echo effect.
-     * @param {number} [echoLength=0.5] - The length of the echo effect.
-     * @returns {Promise<boolean>} - The state of the filter after execution.
+     * @param {number} [decay=0.5] The decay of the echo effect.
+     * @param {number} [echoLength=0.5] The length of the echo effect.
+     * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+     *
+     * @example
+     * ```ts
+     * // Toggle Echo filter with custom settings
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleEcho(0.7, 0.6); // custom values
+     * // or use the defaults
+     * await player.filterManager.lavalinkLavaDspxPlugin.toggleEcho();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleEcho: async (decay = 0.5, echoLength = 0.5) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavadspx-plugin")) throw new Error("Node#Info#plugins does not include the lavadspx plugin");
@@ -3159,15 +3255,27 @@ var FilterManager = class {
       else this.data.pluginFilters.echo = { decay, echoLength };
       this.filters.lavalinkLavaDspxPlugin.echo = !this.filters.lavalinkLavaDspxPlugin.echo;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkLavaDspxPlugin.echo;
+      return this;
     }
   };
+  /**
+   * LavalinkFilter Plugin specific Filters
+   */
   lavalinkFilterPlugin = {
     /**
      * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
-     * @param delay
-     * @param decay
-     * @returns
+     * @param {number} delay set the delay of the echo
+     * @param {number} decay set the decay of the echo
+     * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+     *
+     * @example
+     * ```ts
+     * // Toggle Echo filter with custom settings
+     * await player.filterManager.lavalinkFilterPlugin.toggleEcho(3, 0.7); // custom values
+     * // or use the defaults
+     * await player.filterManager.lavalinkFilterPlugin.toggleEcho();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleEcho: async (delay = 4, decay = 0.8) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavalink-filter-plugin")) throw new Error("Node#Info#plugins does not include the lavalink-filter-plugin plugin");
@@ -3183,13 +3291,22 @@ var FilterManager = class {
       };
       this.filters.lavalinkFilterPlugin.echo = !this.filters.lavalinkFilterPlugin.echo;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkFilterPlugin.echo;
+      return this;
     },
     /**
      * Enables / Disables the Echo effect, IMPORTANT! Only works with the correct Lavalink Plugin installed. (Optional: provide your Own Data)
-     * @param delays
-     * @param gains
-     * @returns
+     * @param {number} delays set the delays of the reverb
+     * @param {number} gains set the gains of the reverb
+     * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+     *
+     * @example
+     * ```ts
+     * // Toggle Reverb filter with custom settings
+     * await player.filterManager.lavalinkFilterPlugin.toggleReverb([0.04, 0.045, 0.05, 0.055], [0.85, 0.84, 0.83, 0.82]);
+     * // or use the defaults
+     * await player.filterManager.lavalinkFilterPlugin.toggleReverb();
+     * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+     * ```
      */
     toggleReverb: async (delays = [0.037, 0.042, 0.048, 0.053], gains = [0.84, 0.83, 0.82, 0.81]) => {
       if (this.player.node.info && !this.player.node.info?.plugins?.find((v) => v.name === "lavalink-filter-plugin")) throw new Error("Node#Info#plugins does not include the lavalink-filter-plugin plugin");
@@ -3205,15 +3322,24 @@ var FilterManager = class {
       };
       this.filters.lavalinkFilterPlugin.reverb = !this.filters.lavalinkFilterPlugin.reverb;
       await this.applyPlayerFilters();
-      return this.filters.lavalinkFilterPlugin.reverb;
+      return this;
     }
   };
   /**
    * Enables / Disables a Nightcore-like filter Effect. Disables/Overrides both: custom and Vaporwave Filter
-   * @param speed
-   * @param pitch
-   * @param rate
-   * @returns
+   * @param {number} speed set the speed of the filter
+   * @param {number} pitch set the pitch of the filter
+   * @param {number} rate set the rate of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Nightcore filter with custom settings
+   * await player.filterManager.toggleNightcore(1.3, 1.3, 0.9);
+   * // or use the defaults
+   * await player.filterManager.toggleNightcore();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleNightcore(speed = 1.289999523162842, pitch = 1.289999523162842, rate = 0.9365999523162842) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("timescale")) throw new Error("Node#Info#filters does not include the 'timescale' Filter (Node has it not enable)");
@@ -3223,14 +3349,23 @@ var FilterManager = class {
     this.filters.vaporwave = false;
     this.filters.custom = false;
     await this.applyPlayerFilters();
-    return this.filters.nightcore;
+    return this;
   }
   /**
    * Enables / Disables a Vaporwave-like filter Effect. Disables/Overrides both: custom and nightcore Filter
-   * @param speed
-   * @param pitch
-   * @param rate
-   * @returns
+   * @param {number} speed set the speed of the filterq
+   * @param {number} pitch set the pitch of the filter
+   * @param {number} rate set the rate of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Vaporwave filter with custom settings
+   * await player.filterManager.toggleVaporwave(0.9, 0.7, 1);
+   * // or use the defaults
+   * await player.filterManager.toggleVaporwave();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleVaporwave(speed = 0.8500000238418579, pitch = 0.800000011920929, rate = 1) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("timescale")) throw new Error("Node#Info#filters does not include the 'timescale' Filter (Node has it not enable)");
@@ -3240,15 +3375,24 @@ var FilterManager = class {
     this.filters.nightcore = false;
     this.filters.custom = false;
     await this.applyPlayerFilters();
-    return this.filters.vaporwave;
+    return this;
   }
   /**
    * Enable / Disables a Karaoke like Filter Effect
-   * @param level
-   * @param monoLevel
-   * @param filterBand
-   * @param filterWidth
-   * @returns
+   * @param {number} level set the level of the filter
+   * @param {number} monoLevel set the mono level of the filter
+   * @param {number} filterBand set the filter band of the filter
+   * @param {number} filterWidth set the filter width of the filter
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Toggle Karaoke filter with custom settings
+   * await player.filterManager.toggleKaraoke(1.5, 1.0, 220, 100);
+   * // or use the defaults
+   * await player.filterManager.toggleKaraoke();
+   * // when it's enabled before calling the toggle function, it disables it, so you might need to do some if/else logic.
+   * ```
    */
   async toggleKaraoke(level = 1, monoLevel = 1, filterBand = 220, filterWidth = 100) {
     if (this.player.node.info && !this.player.node.info?.filters?.includes("karaoke")) throw new Error("Node#Info#filters does not include the 'karaoke' Filter (Node has it not enable)");
@@ -3256,17 +3400,56 @@ var FilterManager = class {
     this.data.karaoke = this.filters.karaoke ? DEFAULT_FILTER_DATAS.karaoke : { level, monoLevel, filterBand, filterWidth };
     this.filters.karaoke = !this.filters.karaoke;
     await this.applyPlayerFilters();
-    return this.filters.karaoke;
+    return this;
   }
-  /** Function to find out if currently there is a custom timescamle etc. filter applied */
+  /**
+   * Function to find out if currently there is a custom timescamle etc. filter applied
+   * @returns {boolean} whether a custom filter is active
+   *
+   * @example
+   * ```ts
+   * // Check if a custom filter is active
+   * const isCustom = player.filterManager.isCustomFilterActive();
+   * console.log(`Is custom filter active? ${isCustom}`);
+   * ```
+   */
   isCustomFilterActive() {
     this.filters.custom = !this.filters.nightcore && !this.filters.vaporwave && Object.values(this.data.timescale).some((d) => d !== 1);
     return this.filters.custom;
   }
   /**
-  * Sets the players equalizer band on-top of the existing ones.
-  * @param bands
-  */
+   * Sets the players equalizer bands using one of the predefined presets.
+   * @param {keyof typeof EQList} preset The preset to use.
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set EQ preset
+   * await player.filterManager.setEQPreset('BassboostMedium');
+   * ```
+   */
+  async setEQPreset(preset) {
+    const bands = EQList[preset];
+    return this.setEQ(bands);
+  }
+  /**
+   * Sets the players equalizer band on-top of the existing ones.
+   * @param {number} bands
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Set EQ bands
+   * await player.filterManager.setEQ([
+   *   { band: 0, gain: 0.3 },
+   *   { band: 1, gain: -0.2 },
+   *   { band: 2, gain: 0.1 }
+   * ]);
+   *
+   * // or use one of the templates:
+   * await player.filterManager.setEQ(player.filterManager.EQList.BassboostMedium); // you can also import EQList from somewhere package if wanted.
+   * ```
+   */
   async setEQ(bands) {
     if (!Array.isArray(bands)) bands = [bands];
     if (!bands.length || !bands.every((band) => safeStringify(Object.keys(band).sort()) === '["band","gain"]')) throw new TypeError("Bands must be a non-empty object array containing 'band' and 'gain' properties.");
@@ -3283,7 +3466,16 @@ var FilterManager = class {
     this.player.ping.lavalink = Math.round((performance.now() - now) / 10) / 100;
     return this;
   }
-  /** Clears the equalizer bands. */
+  /**
+   * Clears the equalizer bands.
+   * @returns {Promise<FilterManager>} The Filter Manager, for chaining.
+   *
+   * @example
+   * ```ts
+   * // Clear all EQ bands
+   * await player.filterManager.clearEQ();
+   * ```
+   */
   async clearEQ() {
     return this.setEQ(Array.from({ length: 15 }, (_v, i) => ({ band: i, gain: 0 })));
   }