lavalink-client 2.2.1 → 2.3.0

package/dist/esm/structures/Queue.d.ts

@@ -1,62 +1,79 @@
-import { Track, UnresolvedTrack } from "./Track";
 import { MiniMap } from "./Utils";
-export interface StoredQueue {
-    current: Track | null;
-    previous: Track[];
-    tracks: Track[];
-}
-export interface QueueStoreManager extends Record<string, any> {
-    /** @async get a Value (MUST RETURN UNPARSED!) */
-    get: (guildId: unknown) => Promise<unknown>;
-    /** @async Set a value inside a guildId (MUST BE UNPARSED) */
-    set: (guildId: unknown, value: unknown) => Promise<unknown>;
-    /** @async Delete a Database Value based of it's guildId */
-    delete: (guildId: unknown) => Promise<unknown>;
-    /** @async Transform the value(s) inside of the QueueStoreManager (IF YOU DON'T NEED PARSING/STRINGIFY, then just return the value) */
-    stringify: (value: unknown) => Promise<unknown>;
-    /** @async Parse the saved value back to the Queue (IF YOU DON'T NEED PARSING/STRINGIFY, then just return the value) */
-    parse: (value: unknown) => Promise<Partial<StoredQueue>>;
-}
-export interface ManagerQueueOptions {
-    /** Maximum Amount of tracks for the queue.previous array. Set to 0 to not save previous songs. Defaults to 25 Tracks */
-    maxPreviousTracks?: number;
-    /** Custom Queue Store option */
-    queueStore?: QueueStoreManager;
-    /** Custom Queue Watcher class */
-    queueChangesWatcher?: QueueChangesWatcher;
-}
-export interface QueueSaver {
-    /** @private */
-    _: QueueStoreManager;
-    /** @private */
+import type { Track, UnresolvedTrack } from "./Types/Track";
+import type { ManagerQueueOptions, QueueStoreManager, StoredQueue } from "./Types/Queue";
+export declare class QueueSaver {
+    /**
+     * The queue store manager
+     */
+    private _;
+    /**
+     * The options for the queue saver
+     */
     options: {
         maxPreviousTracks: number;
     };
-}
-export declare class QueueSaver {
     constructor(options: ManagerQueueOptions);
+    /**
+     * Get the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     get(guildId: string): Promise<Partial<StoredQueue>>;
+    /**
+     * Delete the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     delete(guildId: string): Promise<unknown>;
-    set(guildId: string, value: any): Promise<unknown>;
+    /**
+     * Set the queue for a guild
+     * @param guildId The guild ID
+     * @param valueToStringify The queue to set
+     * @returns The queue for the guild
+     */
+    set(guildId: string, valueToStringify: StoredQueue): Promise<unknown>;
+    /**
+     * Sync the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     sync(guildId: string): Promise<Partial<StoredQueue>>;
 }
 export declare class DefaultQueueStore implements QueueStoreManager {
     private data;
     constructor();
+    /**
+     * Get the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     get(guildId: any): Promise<unknown>;
-    set(guildId: any, stringifiedValue: any): Promise<MiniMap<unknown, unknown>>;
+    /**
+     * Set the queue for a guild
+     * @param guildId The guild ID
+     * @param valueToStringify The queue to set
+     * @returns The queue for the guild
+     */
+    set(guildId: any, valueToStringify: any): Promise<MiniMap<unknown, unknown>>;
+    /**
+     * Delete the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     delete(guildId: any): Promise<boolean>;
+    /**
+     * Stringify the queue for a guild
+     * @param value The queue to stringify
+     * @returns The stringified queue
+     */
     stringify(value: any): Promise<any>;
+    /**
+     * Parse the queue for a guild
+     * @param value The queue to parse
+     * @returns The parsed queue
+     */
     parse(value: any): Promise<Partial<StoredQueue>>;
 }
-export interface QueueChangesWatcher {
-    /** get a Value (MUST RETURN UNPARSED!) */
-    tracksAdd: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => any;
-    /** Set a value inside a guildId (MUST BE UNPARSED) */
-    tracksRemoved: (guildId: string, tracks: (Track | UnresolvedTrack)[], position: number, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => any;
-    /** Set a value inside a guildId (MUST BE UNPARSED) */
-    shuffled: (guildId: string, oldStoredQueue: StoredQueue, newStoredQueue: StoredQueue) => any;
-}
 export declare class Queue {
     readonly tracks: (Track | UnresolvedTrack)[];
     readonly previous: Track[];
@@ -68,6 +85,13 @@ export declare class Queue {
     private readonly QueueSaver;
     private managerUtils;
     private queueChanges;
+    /**
+     * Create a new Queue
+     * @param guildId The guild ID
+     * @param data The data to initialize the queue with
+     * @param QueueSaver The queue saver to use
+     * @param queueOptions
+     */
     constructor(guildId: string, data?: Partial<StoredQueue>, QueueSaver?: QueueSaver, queueOptions?: ManagerQueueOptions);
     /**
      * Utils for a Queue
@@ -113,4 +137,51 @@ export declare class Queue {
      * @returns {Track} Spliced Track
      */
     splice(index: number, amount: number, TrackOrTracks?: Track | UnresolvedTrack | (Track | UnresolvedTrack)[]): any;
+    /**
+     * Remove stuff from the queue.tracks array
+     *  - single Track | UnresolvedTrack
+     *  - multiple Track | UnresovedTrack
+     *  - at the index or multiple indexes
+     * @param removeQueryTrack
+     * @returns null (if nothing was removed) / { removed } where removed is an array with all removed elements
+     *
+     * @example
+     * ```js
+     * // remove single track
+     *
+     * const track = player.queue.tracks[4];
+     * await player.queue.remove(track);
+     *
+     * // if you already have the index you can straight up pass it too
+     * await player.queue.remove(4);
+     *
+     *
+     * // if you want to remove multiple tracks, e.g. from position 4 to position 10 you can do smt like this
+     * await player.queue.remove(player.queue.tracks.slice(4, 10)) // get's the tracks from 4 - 10, which then get's found in the remove function to be removed
+     *
+     * // I still highly suggest to use .splice!
+     *
+     * await player.queue.splice(4, 10); // removes at index 4, 10 tracks
+     *
+     * await player.queue.splice(1, 1); // removes at index 1, 1 track
+     *
+     * await player.queue.splice(4, 0, ...tracks) // removes 0 tracks at position 4, and then inserts all tracks after position 4.
+     * ```
+     */
+    remove<T extends Track | UnresolvedTrack | number | Track[] | UnresolvedTrack[] | number[] | (number | Track | UnresolvedTrack)[]>(removeQueryTrack: T): Promise<{
+        removed: (Track | UnresolvedTrack)[];
+    } | null>;
+    /**
+     * Shifts the previous array, to return the last previous track & thus remove it from the previous queue
+     * @returns
+     *
+     * @example
+     * ```js
+     * // example on how to play the previous track again
+     * const previous = await player.queue.shiftPrevious(); // get the previous track and remove it from the previous queue array!!
+     * if(!previous) return console.error("No previous track found");
+     * await player.play({ clientTrack: previous }); // play it again
+     * ```
+     */
+    shiftPrevious(): Promise<Track>;
 }

package/dist/esm/structures/Queue.js

@@ -1,39 +1,94 @@
 import { ManagerUtils, MiniMap, QueueSymbol } from "./Utils";
 export class QueueSaver {
+    /**
+     * The queue store manager
+     */
+    _;
+    /**
+     * The options for the queue saver
+     */
+    options;
     constructor(options) {
         this._ = options?.queueStore || new DefaultQueueStore();
         this.options = {
             maxPreviousTracks: options?.maxPreviousTracks || 25,
         };
     }
+    /**
+     * Get the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     async get(guildId) {
-        return await this._.parse(await this._.get(guildId));
+        return this._.parse(await this._.get(guildId));
     }
+    /**
+     * Delete the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     async delete(guildId) {
-        return await this._.delete(guildId);
+        return this._.delete(guildId);
     }
-    async set(guildId, value) {
-        return await this._.set(guildId, await this._.stringify(value));
+    /**
+     * Set the queue for a guild
+     * @param guildId The guild ID
+     * @param valueToStringify The queue to set
+     * @returns The queue for the guild
+     */
+    async set(guildId, valueToStringify) {
+        return this._.set(guildId, await this._.stringify(valueToStringify));
     }
+    /**
+     * Sync the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     async sync(guildId) {
-        return await this.get(guildId);
+        return this.get(guildId);
     }
 }
 export class DefaultQueueStore {
     data = new MiniMap();
     constructor() { }
+    /**
+     * Get the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     async get(guildId) {
         return await this.data.get(guildId);
     }
-    async set(guildId, stringifiedValue) {
-        return await this.data.set(guildId, stringifiedValue);
+    /**
+     * Set the queue for a guild
+     * @param guildId The guild ID
+     * @param valueToStringify The queue to set
+     * @returns The queue for the guild
+     */
+    async set(guildId, valueToStringify) {
+        return await this.data.set(guildId, valueToStringify);
     }
+    /**
+     * Delete the queue for a guild
+     * @param guildId The guild ID
+     * @returns The queue for the guild
+     */
     async delete(guildId) {
         return await this.data.delete(guildId);
     }
+    /**
+     * Stringify the queue for a guild
+     * @param value The queue to stringify
+     * @returns The stringified queue
+     */
     async stringify(value) {
         return value; // JSON.stringify(value);
     }
+    /**
+     * Parse the queue for a guild
+     * @param value The queue to parse
+     * @returns The parsed queue
+     */
     async parse(value) {
         return value; // JSON.parse(value)
     }
@@ -47,6 +102,13 @@ export class Queue {
     QueueSaver = null;
     managerUtils = new ManagerUtils();
     queueChanges;
+    /**
+     * Create a new Queue
+     * @param guildId The guild ID
+     * @param data The data to initialize the queue with
+     * @param QueueSaver The queue saver to use
+     * @param queueOptions
+     */
     constructor(guildId, data = {}, QueueSaver, queueOptions) {
         this.queueChanges = queueOptions.queueChangesWatcher || null;
         this.guildId = guildId;
@@ -118,7 +180,7 @@ export class Queue {
         if (this.tracks.length <= 1)
             return this.tracks.length;
         // swap #1 and #2 if only 2 tracks.
-        if (this.tracks.length == 2) {
+        if (this.tracks.length === 2) {
             [this.tracks[0], this.tracks[1]] = [this.tracks[1], this.tracks[0]];
         }
         else { // randomly swap places.
@@ -192,4 +254,103 @@ export class Queue {
         // return the things
         return spliced.length === 1 ? spliced[0] : spliced;
     }
+    /**
+     * Remove stuff from the queue.tracks array
+     *  - single Track | UnresolvedTrack
+     *  - multiple Track | UnresovedTrack
+     *  - at the index or multiple indexes
+     * @param removeQueryTrack
+     * @returns null (if nothing was removed) / { removed } where removed is an array with all removed elements
+     *
+     * @example
+     * ```js
+     * // remove single track
+     *
+     * const track = player.queue.tracks[4];
+     * await player.queue.remove(track);
+     *
+     * // if you already have the index you can straight up pass it too
+     * await player.queue.remove(4);
+     *
+     *
+     * // if you want to remove multiple tracks, e.g. from position 4 to position 10 you can do smt like this
+     * await player.queue.remove(player.queue.tracks.slice(4, 10)) // get's the tracks from 4 - 10, which then get's found in the remove function to be removed
+     *
+     * // I still highly suggest to use .splice!
+     *
+     * await player.queue.splice(4, 10); // removes at index 4, 10 tracks
+     *
+     * await player.queue.splice(1, 1); // removes at index 1, 1 track
+     *
+     * await player.queue.splice(4, 0, ...tracks) // removes 0 tracks at position 4, and then inserts all tracks after position 4.
+     * ```
+     */
+    async remove(removeQueryTrack) {
+        if (typeof removeQueryTrack === "number") {
+            const toRemove = this.tracks[removeQueryTrack];
+            if (!toRemove)
+                return null;
+            const removed = this.tracks.splice(removeQueryTrack, 1);
+            await this.utils.save();
+            return { removed };
+        }
+        if (Array.isArray(removeQueryTrack)) {
+            if (removeQueryTrack.every(v => typeof v === "number")) {
+                const removed = [];
+                for (const i of removeQueryTrack) {
+                    if (this.tracks[i])
+                        removed.push(...this.tracks.splice(i, 1));
+                }
+                if (!removed.length)
+                    return null;
+                await this.utils.save();
+                return { removed };
+            }
+            const tracksToRemove = this.tracks.map((v, i) => ({ v, i })).filter(({ v, i }) => removeQueryTrack.find(t => typeof t === "number" && (t === i) ||
+                typeof t === "object" && (t.encoded && t.encoded === v.encoded ||
+                    t.info?.identifier && t.info.identifier === v.info?.identifier ||
+                    t.info?.uri && t.info.uri === v.info?.uri ||
+                    t.info?.title && t.info.title === v.info?.title ||
+                    t.info?.isrc && t.info.isrc === v.info?.isrc ||
+                    t.info?.artworkUrl && t.info.artworkUrl === v.info?.artworkUrl)));
+            if (!tracksToRemove.length)
+                return null;
+            const removed = [];
+            for (const { i } of tracksToRemove) {
+                if (this.tracks[i])
+                    removed.push(...this.tracks.splice(i, 1));
+            }
+            await this.utils.save();
+            return { removed };
+        }
+        const toRemove = this.tracks.findIndex((v) => removeQueryTrack.encoded && removeQueryTrack.encoded === v.encoded ||
+            removeQueryTrack.info?.identifier && removeQueryTrack.info.identifier === v.info?.identifier ||
+            removeQueryTrack.info?.uri && removeQueryTrack.info.uri === v.info?.uri ||
+            removeQueryTrack.info?.title && removeQueryTrack.info.title === v.info?.title ||
+            removeQueryTrack.info?.isrc && removeQueryTrack.info.isrc === v.info?.isrc ||
+            removeQueryTrack.info?.artworkUrl && removeQueryTrack.info.artworkUrl === v.info?.artworkUrl);
+        if (toRemove < 0)
+            return null;
+        const removed = this.tracks.splice(toRemove, 1);
+        await this.utils.save();
+        return { removed };
+    }
+    /**
+     * Shifts the previous array, to return the last previous track & thus remove it from the previous queue
+     * @returns
+     *
+     * @example
+     * ```js
+     * // example on how to play the previous track again
+     * const previous = await player.queue.shiftPrevious(); // get the previous track and remove it from the previous queue array!!
+     * if(!previous) return console.error("No previous track found");
+     * await player.play({ clientTrack: previous }); // play it again
+     * ```
+     */
+    async shiftPrevious() {
+        const removed = this.previous.shift();
+        if (removed)
+            await this.utils.save();
+        return removed ?? null;
+    }
 }

package/dist/esm/structures/Types/Filters.d.ts

@@ -0,0 +1,190 @@
+import type { FloatNumber, IntegerNumber } from "./Utils";
+/** The Audio Outputs type */
+export type AudioOutputs = "mono" | "stereo" | "left" | "right";
+/** The "active" / "disabled" Player Filters */
+export interface PlayerFilters {
+    /** Sets nightcore to false, and vaporwave to false */
+    custom: boolean;
+    /** Sets custom to false, and vaporwave to false */
+    nightcore: boolean;
+    /** Sets custom to false, and nightcore to false */
+    vaporwave: boolean;
+    /** If rotation filter is enabled / not */
+    rotation: boolean;
+    /** if karaoke filter is enabled / not */
+    karaoke: boolean;
+    /** if tremolo filter is enabled / not */
+    tremolo: boolean;
+    /** if vibrato filter is enabled / not */
+    vibrato: boolean;
+    lowPass: boolean;
+    /** audio Output (default stereo, mono sounds the fullest and best for not-stereo tracks) */
+    audioOutput: AudioOutputs;
+    /** Lavalink Volume FILTER (not player Volume, think of it as a gain booster) */
+    volume: boolean;
+    /** Filters for the Lavalink Filter Plugin */
+    lavalinkFilterPlugin: {
+        /** if echo filter is enabled / not */
+        echo: boolean;
+        /** if reverb filter is enabled / not */
+        reverb: boolean;
+    };
+    lavalinkLavaDspxPlugin: {
+        /** if lowPass filter is enabled / not */
+        lowPass: boolean;
+        /** if highPass filter is enabled / not */
+        highPass: boolean;
+        /** if normalization filter is enabled / not */
+        normalization: boolean;
+        /** if echo filter is enabled / not */
+        echo: boolean;
+    };
+}
+/**
+ * There are 15 bands (0-14) that can be changed.
+ * "gain" is the multiplier for the given band.
+ * The default value is 0.
+ *  Valid values range from -0.25 to 1.0, where -0.25 means the given band is completely muted, and 0.25 means it is doubled.
+ * Modifying the gain could also change the volume of the output.
+ */
+export interface EQBand {
+    /** On what band position (0-14) it should work */
+    band: IntegerNumber | number;
+    /** The gain (-0.25 to 1.0) */
+    gain: FloatNumber | number;
+}
+/**
+ * Uses equalization to eliminate part of a band, usually targeting vocals.
+ */
+export interface KaraokeFilter {
+    /** The level (0 to 1.0 where 0.0 is no effect and 1.0 is full effect) */
+    level?: number;
+    /** The mono level (0 to 1.0 where 0.0 is no effect and 1.0 is full effect) */
+    monoLevel?: number;
+    /** The filter band (in Hz) */
+    filterBand?: number;
+    /**	The filter width */
+    filterWidth?: number;
+}
+/**
+ * Changes the speed, pitch, and rate
+ */
+export interface TimescaleFilter {
+    /** The playback speed 0.0 ≤ x */
+    speed?: number;
+    /** The pitch 0.0 ≤ x */
+    pitch?: number;
+    /** The rate 0.0 ≤ x */
+    rate?: number;
+}
+/**
+ * Uses amplification to create a shuddering effect, where the volume quickly oscillates.
+ * Demo: https://en.wikipedia.org/wiki/File:Fuse_Electronics_Tremolo_MK-III_Quick_Demo.ogv
+ */
+export interface TremoloFilter {
+    /** The frequency 0.0 < x */
+    frequency?: number;
+    /** The tremolo depth 0.0 < x ≤ 1.0 */
+    depth?: number;
+}
+/**
+ * Similar to tremolo. While tremolo oscillates the volume, vibrato oscillates the pitch.
+ */
+export interface VibratoFilter {
+    /** The frequency 0.0 < x ≤ 14.0 */
+    frequency?: number;
+    /** The vibrato depth 0.0 < x ≤ 1.0 */
+    depth?: number;
+}
+/**
+ * Rotates the sound around the stereo channels/user headphones (aka Audio Panning).
+ * It can produce an effect similar to https://youtu.be/QB9EB8mTKcc (without the reverb).
+ */
+export interface RotationFilter {
+    /** The frequency of the audio rotating around the listener in Hz. 0.2 is similar to the example video above */
+    rotationHz?: number;
+}
+/**
+ * Distortion effect. It can generate some pretty unique audio effects.
+ */
+export interface DistortionFilter {
+    sinOffset?: number;
+    sinScale?: number;
+    cosOffset?: number;
+    cosScale?: number;
+    tanOffset?: number;
+    tanScale?: number;
+    offset?: number;
+    scale?: number;
+}
+/**
+ * Mixes both channels (left and right), with a configurable factor on how much each channel affects the other.
+ * With the defaults, both channels are kept independent of each other.
+ * Setting all factors to 0.5 means both channels get the same audio.
+ */
+export interface ChannelMixFilter {
+    /** The left to left channel mix factor (0.0 ≤ x ≤ 1.0) */
+    leftToLeft?: number;
+    /** The left to right channel mix factor (0.0 ≤ x ≤ 1.0) */
+    leftToRight?: number;
+    /** The right to left channel mix factor (0.0 ≤ x ≤ 1.0) */
+    rightToLeft?: number;
+    /** The right to right channel mix factor (0.0 ≤ x ≤ 1.0) */
+    rightToRight?: number;
+}
+/**
+ * Higher frequencies get suppressed, while lower frequencies pass through this filter, thus the name low pass.
+ * Any smoothing values equal to or less than 1.0 will disable the filter.
+ */
+export interface LowPassFilter {
+    /** The smoothing factor (1.0 < x) */
+    smoothing?: number;
+}
+/**
+ * Filter Data stored in the Client and partially sent to Lavalink
+ */
+export interface FilterData {
+    volume?: number;
+    karaoke?: KaraokeFilter;
+    timescale?: TimescaleFilter;
+    tremolo?: TremoloFilter;
+    vibrato?: VibratoFilter;
+    rotation?: RotationFilter;
+    distortion?: DistortionFilter;
+    channelMix?: ChannelMixFilter;
+    lowPass?: LowPassFilter;
+    pluginFilters?: {
+        "lavalink-filter-plugin"?: {
+            "echo"?: {
+                delay?: number;
+                decay?: number;
+            };
+            "reverb"?: {
+                delays?: number[];
+                gains?: number[];
+            };
+        };
+        "high-pass"?: {
+            cutoffFrequency?: number;
+            boostFactor?: number;
+        };
+        "low-pass"?: {
+            cutoffFrequency?: number;
+            boostFactor?: number;
+        };
+        normalization?: {
+            maxAmplitude?: number;
+            adaptive?: boolean;
+        };
+        echo?: {
+            echoLength?: number;
+            decay?: number;
+        };
+    };
+}
+/**
+ * Actual Filter Data sent to Lavalink
+ */
+export interface LavalinkFilterData extends FilterData {
+    equalizer?: EQBand[];
+}