lavalink-client 1.0.0 → 1.0.2

package/README.md

@@ -1,187 +1,138 @@
 # lavalink-client
 Easy and advanced lavalink client. Use it with lavalink plugins as well as latest lavalink versions
 
+# Install
 
-### What is Lavalink?
-- Lavalink is an open-source Discord Queue Manager and Audioplayer, as well as scraper.
-
-*Coming soon*
-
-
-
-## How to self Host Lavalink
-
-<details>
-<summary>
-👉 Click here to see how to self host a Lavalink instance
-</summary>
-
-### Requirements - JAVA
-- [v18](https://github.com/Tomato6966/Debian-Cheat-Sheat-Setup/wiki/3.5.7-java-18) - for Lavalink@latest (v3.5+ or rc*)
-- [v13](https://github.com/Tomato6966/Debian-Cheat-Sheat-Setup/wiki/3.5.3-java-13) - for Lavalink v3.3-v3.4
-- [v11](https://github.com/Tomato6966/Debian-Cheat-Sheat-Setup/wiki/3.5.2-java-11) - for all older Versions
-
-### Installation
-- First download the [Lavalink executeable File v3.6.2](https://github.com/freyacodes/Lavalink/releases/download/3.6.2/Lavalink.jar): [from the releases page](https://github.com/freyacodes/Lavalink/releases)
+Latest stable Version: (currently, unreleased)
 ```
-wget https://github.com/freyacodes/Lavalink/releases/download/3.6.2/Lavalink.jar
+npm install --save lavalink-client
 ```
-- Then download my [example **configuration File** application.yml](https://raw.githubusercontent.com/Tomato6966/Debian-Cheat-Sheet-Setup/main/application.yml) | [Example application.yml from official repo - LINK](https://github.com/freyacodes/Lavalink/blob/master/LavalinkServer/application.yml.example)
+Dev Version: (Current)
 ```
-wget https://raw.githubusercontent.com/Tomato6966/Debian-Cheat-Sheet-Setup/main/application.yml
+npm install tomato6966/lavalink-client
 ```
-*Make sure the file-name is equal to: `application.yml` and is in the same Directory as the `Lavalink.jar` file*
-
-**NOTE:** If you don't wanna use the spotify plugin, or any other sources Plugin, then remove it from MY EXAMPLE application.yml 
-> other wise you'd get errors. as far this is just a note-cheatsheet FOR ME
 
-# Plugins Example
-- In the server config Level of the applicatino.yml for `plugins` you can find all plugins and their versions which will be downloaded
+# Features
 
-# Edit Application.yml
-make sure to edit:
-- **port** to access Lavalink from a different Port
-- **password** so that you have a password
-- **spotify** -> **clientId** & **clientSecret** [get them from here](https://developer.spotify.com/dashboard/applications)
-- **deezer** -> **masterEncryptionKey** [find it out yourself, how to get it](https://github.com/yne/dzr/issues/11)
-- All other values to fit your needs
-
-# Start Lavalink
-
-in the folder of `Lavalink.jar` and `application.yml` execute the following
-```bash
-java -jar Lavalink.jar
-```
-
-# How to start it 24/7 - 2 Methods
-
-- pm2:
-
-```bash
-npm i -g pm2; # add pm2 to the system
-pm2 start --name Lavalink --max-memory-restart 4G java -- -jar Lavalink.jar
-```
+- 💯 Lavalink v4 Supported only (with Lavalink Plugins)
 
-- screen:
-```bash
-apt-get install screen
-screen -t Lavalink -s Lavalink
-java -jar Lavalink # in the screen window:
+- ✅ Player-Destroy Reasons like:
+  - Channel got deleted, Player got disconnected...
 
-# strg + alt + a + d -> to exit
-# screen -ls to view all screens
-# screen -r <ID> to re-enter a screen
+- ✨ Choose able queue stores (maps, collections, redis, databases, ...)
+  - You can create your own queueStore, thus make it easy to sync queues accross multiple connections (e.g. dashboard-bot)
 
-# How to connect to it?
+- 😍 Included Filter & Equalizer Management
 
-you need the following information:
-- host: `localhost` | `127.0.0.1` | `IPV4 Address` (only works if firewall allows it)
-- port: `2333` | `defined_port`
-- password: `youshallnotpass` | `defined_port`
+- 👍 Multiple Player Options *for easier use*
+  - onDisconnect -> Player Destroy / auto Reconnect
+  - onEmptyQueue -> Player Destroy / leave After x Time
+  - instaFixFilter -> seek the player after applying a filter, to instantly apply it's effect (only works for little-durational-songs)
+  - applyVolumeAsFilter -> instead of using lavalink.volume, it uses lavalink.filters.volume which is much different!
 
+- 🛡️ Lavalink Validations
+  - It only let's you use the filters / plugins / sources, if Lavalink actually has it enabled
 
-# Recommendation
+- 🧑‍💻 Memory friendly and easy style
+  - Only the required data is displayed, and the store-way & types match Lavalink#IMPLEMENTATION.md
 
-Start using ipv6 routating, to prevent an ip ban from youtube!
-check [here](https://github.com/freyacodes/Lavalink/issues/369) for more infos and for how to use tunnelbroker to get an ipv6 address-block, if you don't have one
+- 😘 Automated Handlings
+  - Skips the songs, on TrackEnd, TrackStuck, TrackError, 
+  - Destroys the player on channeldelete
+  - Pauses / resumes the player if it get's muted / unmuted (server-wide) [soon]
+  - ...
+- 😁 Much much more!
 
-## How to do ip routing notes:
+# Documentation
 
-First enable allowments for ipv6
+*soon*
 
-```
-# Enable now
-sysctl -w net.ipv6.ip_nonlocal_bind=1
-# Persist for next boot
-echo 'net.ipv6.ip_nonlocal_bind = 1' >> /etc/sysctl.conf
-```
+# How to Use
 
-replace `1234:1234:1234::/64` with your BLOCK (e.g. `2a01:12ab:12::/64`), if it's a /48 then it's `1234:1234:1234::/48` ofc.
+1. Import the Manager
 
+```ts
+import { LavalinkManager } from "lavalink-client"; // Modular JS  /  Typescript
 ```
-ip -6 route replace local 1234:1234:1234::/64 dev lo
-```
-Don't know how to route it with netplan / interfaces? Ask your provider or do:
-```
-ip add add local 1234:1234:1234::/64 dev lo
-```
-
-Test the config
 
-```
-# Test that IPv6 works in the first place
-ping6 google.com
-
-# If you have the IPv6 block 1234:1234:1234::/48
-# You should be able to use any of the IPs within that block
-ping6 -I 1234:1234:1234:: -c 2 google.com
-ping6 -I 1234:1234:1234::1 -c 2 google.com
-ping6 -I 1234:1234:1234::2 -c 2 google.com
-ping6 -I 1234:1234:1234:dead:beef:1234:1234 -c 2 google.com
+```js
+const { LavalinkManager } = require("lavalink-client"); // Common Js
 ```
 
-**IF you get could not assign requested address, then it's not routed to your system..**
+2. create the Manager
 
-**IF YOU GET 100% PACKET LOSS THEN EVERYTHING IS OKAY DO THE FOLLOWING:**
-```
-# Install routing proxy
-sudo apt-get -y install ndppd
-# Create / edit it's config file
-nano /etc/ndppd.conf
-# Next paste the following: again replace the block with your block
-
-route-ttl 30000 
-
-proxy enp1s0 { # your interface name
-   router no # If it should send router bit | default: yes
-   timeout 500 # How long (in ms) it waits to assign a request address (lower == faster but more unstable) | default: 500
-   ttl 30000 # How long (in ms) it caches an Ip Address (for lavalink you can def. set this one to 3600000 | default: 30000
-   rule 1234:1234:1234::/64{
-       static # to respond immediatelly
-   }
-}
+```ts
+// Suggest it to extend it to the bot Client
+client.lavalink = new LavalinkManager({
+    nodes: [
+        {
+            authorization: "youshallnotpass",
+            host: "localhost",
+            port: 2333,
+            id: "testnode",
+            requestTimeout: 10000,
+        }
+    ],
+    sendToShard: (guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
+    autoSkip: true,
+    client: {
+        id: envConfig.clientId,
+        username: "TESTBOT",
+        shards: "auto"
+    },
+    playerOptions: {
+        applyVolumeAsFilter: false,
+        clientBasedUpdateInterval: 50,
+        defaultSearchPlatform: "dzsearch",
+        volumeDecrementer: 0.7
+    },
+    queueOptions: {
+        maxPreviousTracks: 5
+    },
+    // queueStore: new myCustomStore(client.redis), // OPTIONAL! 'class myCustomStore extends DefaultQueueStore' --> for custom queue stores, e.g. redis, etc. | default is lavalink-client#MiniMap
+    // queueChangesWatcher: new myCustomWatcher(), // OPTIONAL! 'class myCustomWatcher extends QueueChangesWatcher' --> for queue action logs!
+});
 ```
 
-Before saving replace `enp1s0` with your interface block name
-
-It's findable with: ip addr
-there are multiple, just find the name of the one where your ipv6 Block is in!
-
-**NOW START ndppd**
+3. **VERY IMPORTANT!** - Register Voice State updates + initialize the Manager
 
-```
-ndppd -d -c /etc/ndppd.conf
-# Restart: systemctl restart ndppd
-# Stop: systemctl stop ndppd
-# Status : systemctl status ndppd
-# Start: systemctl start ndppd
+```ts
+client.on("raw", d => client.lavalink.sendRawData(d)); // for voice state updates!
+client.on("ready", async () => {
+    console.log("Discord Bot is ready to be Used!");
+    // user.id is required, user.shards (not), user.username (not, but recommended for lavalink stats!) 
+    await client.lavalink.init({ ...client.user!, shards: "auto" }); 
+});
 ```
 
-If apt-install fails do this:
-```
-wget http://data.vshell.net/files/ndppd-0.2.5.tar.gz
-tar -zxvf ndppd-0.2.5.tar.gz
-cd ndppd-0.2.5
-make
-make install
-```
+4. **Use it!**
 
+```ts
+// create player
+const player = await client.lavalink.createPlayer({
+    guildId: guild.id, voiceChannelId: voice.id, textChannelId: text.id, // in what guild + channel(s)
+    selfDeaf: true, selfMute: false, volume: 100 // configuration(s)
+}); 
+// connect the player to it's vc
+await player.connect();
 
-How does my /etc/ndppd.conf look like?
-```
-route-ttl 3600000 
-proxy enp1s0 {
-   router yes
-   timeout 50
-   ttl 3600000 
-   rule 2423:2220:123:1234::/64{
-       static
-   }
-}
-```
-  
-</details>
+const res = await player.search({
+    query: `Elton John`, // source: `soundcloud`,
+}, client.user); // search a query (query-search, url search, identifier search, etc.)
+
+await player.queue.add(res.tracks); // add 1 track, or an array of tracks
+await player.play(); // you can provide specific track, or let the manager choose the track from the queue!
+```
+
+## Example (typescript)
+
+Can be found in the [`/testBot`](https://github.com/Tomato6966/lavalink-client/blob/main/testBot/README.md) Directory
+
+It contains the following features:
 
-## Public Lavalink Services:
-  
-https://lavalink.milrato.com
+- Example Use for `Redis based Queue`
+- Example Use for `Queue Changes Watcher Logger`
+- Example Use for `Filters`, `Audio Output`, `equalizers`
+- How to make an easy, yet advanced `Slash Commands Only Bot`
+- `Slim Memory Usage`
+- `All lavalink-client events` displayments

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./structures/LavalinkManager";
+export * from "./structures/Filters";
+export * from "./structures/LavalinkManagerStatics";
+export * from "./structures/Node";
+export * from "./structures/NodeManager";
+export * from "./structures/Player";
+export * from "./structures/Queue";
+export * from "./structures/Track";
+export * from "./structures/Utils";

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./structures/LavalinkManager"), exports);
+tslib_1.__exportStar(require("./structures/Filters"), exports);
+tslib_1.__exportStar(require("./structures/LavalinkManagerStatics"), exports);
+tslib_1.__exportStar(require("./structures/Node"), exports);
+tslib_1.__exportStar(require("./structures/NodeManager"), exports);
+tslib_1.__exportStar(require("./structures/Player"), exports);
+tslib_1.__exportStar(require("./structures/Queue"), exports);
+tslib_1.__exportStar(require("./structures/Track"), exports);
+tslib_1.__exportStar(require("./structures/Utils"), exports);

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

@@ -0,0 +1,231 @@
+import { Player } from "./Player";
+export type AudioOutputs = "mono" | "stereo" | "left" | "right";
+export interface FilterManager {
+    player: Player;
+}
+export declare class FilterManager {
+    equalizerBands: EQBand[];
+    filterUpdatedState: number;
+    filters: PlayerFilters;
+    data: LavalinkFilterData;
+    constructor(player: Player);
+    applyPlayerFilters(): Promise<void>;
+    /**
+     * Checks if the filters are correctly stated (active / not-active)
+     * @param oldFilterTimescale
+     * @returns
+     */
+    checkFiltersState(oldFilterTimescale?: Partial<TimescaleFilter>): boolean;
+    /**
+     * Reset all Filters
+     */
+    resetFilters(): Promise<PlayerFilters>;
+    setVolume(volume: number): Promise<boolean>;
+    /**
+     * Set the AudioOutput Filter
+     * @param type
+     */
+    setAudioOutput(type: AudioOutputs): Promise<AudioOutputs>;
+    /**
+     * Set custom filter.timescale#speed . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
+     * @param speed
+     * @returns
+     */
+    setSpeed(speed?: number): Promise<boolean>;
+    /**
+     * Set custom filter.timescale#pitch . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
+     * @param speed
+     * @returns
+     */
+    setPitch(pitch?: number): Promise<boolean>;
+    /**
+     * Set custom filter.timescale#rate . This method disabled both: nightcore & vaporwave. use 1 to reset it to normal
+     * @param speed
+     * @returns
+     */
+    setRate(rate?: number): Promise<boolean>;
+    /**
+     * Enabels / 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)
+     * @param frequency
+     * @param depth
+     * @returns
+     */
+    toggleVibrato(frequency?: number, depth?: number): Promise<boolean>;
+    /**
+     * Enabels / 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)
+     * @param smoothing
+     * @returns
+     */
+    toggleLowPass(smoothing?: number): Promise<boolean>;
+    /**
+     * Enabels / 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)
+     * @param delay
+     * @param decay
+     * @returns
+     */
+    toggleReverb(delay?: number, decay?: number): Promise<boolean>;
+    /**
+     * Enables / Disabels a Nightcore-like filter Effect. Disables/Overwrides both: custom and Vaporwave Filter
+     * @param speed
+     * @param pitch
+     * @param rate
+     * @returns
+     */
+    toggleNightcore(speed?: number, pitch?: number, rate?: number): Promise<boolean>;
+    /**
+     * Enables / Disabels a Vaporwave-like filter Effect. Disables/Overwrides both: custom and nightcore Filter
+     * @param speed
+     * @param pitch
+     * @param rate
+     * @returns
+     */
+    toggleVaporwave(speed?: number, pitch?: number, rate?: number): Promise<boolean>;
+    /**
+     * Enable / Disables a Karaoke like Filter Effect
+     * @param level
+     * @param monoLevel
+     * @param filterBand
+     * @param filterWidth
+     * @returns
+     */
+    toggleKaraoke(level?: number, monoLevel?: number, filterBand?: number, filterWidth?: number): Promise<boolean>;
+    /** Function to find out if currently there is a custom timescamle etc. filter applied */
+    isCustomFilterActive(): boolean;
+    /**
+   * Sets the players equalizer band on-top of the existing ones.
+   * @param bands
+   */
+    setEQ(bands: EQBand | EQBand[]): Promise<this>;
+    /** Clears the equalizer bands. */
+    clearEQ(): Promise<this>;
+}
+export declare const audioOutputsData: {
+    mono: {
+        leftToLeft: number;
+        leftToRight: number;
+        rightToLeft: number;
+        rightToRight: number;
+    };
+    stereo: {
+        leftToLeft: number;
+        leftToRight: number;
+        rightToLeft: number;
+        rightToRight: number;
+    };
+    left: {
+        leftToLeft: number;
+        leftToRight: number;
+        rightToLeft: number;
+        rightToRight: number;
+    };
+    right: {
+        leftToLeft: number;
+        leftToRight: number;
+        rightToLeft: number;
+        rightToRight: number;
+    };
+};
+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;
+    /** only with the custom lavalink filter plugin */
+    echo: boolean;
+    /** only with the custom lavalink filter plugin */
+    reverb: boolean;
+    rotation: boolean;
+    karaoke: boolean;
+    tremolo: boolean;
+    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;
+}
+export interface EQBand {
+    band: number;
+    gain: number;
+}
+export interface KaraokeFilter {
+    level?: number;
+    monoLevel?: number;
+    filterBand?: number;
+    filterWidth?: number;
+}
+export interface TimescaleFilter {
+    speed?: number;
+    pitch?: number;
+    rate?: number;
+}
+export interface FreqFilter {
+    frequency?: number;
+    depth?: number;
+}
+export interface RotationFilter {
+    rotationHz?: number;
+}
+export interface DistortionFilter {
+    sinOffset?: number;
+    sinScale?: number;
+    cosOffset?: number;
+    cosScale?: number;
+    tanOffset?: number;
+    tanScale?: number;
+    offset?: number;
+    scale?: number;
+}
+export interface ChannelMixFilter {
+    leftToLeft?: number;
+    leftToRight?: number;
+    rightToLeft?: number;
+    rightToRight?: number;
+}
+export interface LowPassFilter {
+    smoothing?: number;
+}
+export interface EchoFilter {
+    delay: number;
+    decay: number;
+}
+export interface ReverbFilter {
+    delay: number;
+    decay: number;
+}
+export interface LavalinkFilterData {
+    volume?: number;
+    equalizer?: EQBand[];
+    karaoke?: KaraokeFilter;
+    timescale?: TimescaleFilter;
+    tremolo?: FreqFilter;
+    vibrato?: FreqFilter;
+    rotation?: RotationFilter;
+    distortion?: DistortionFilter;
+    channelMix?: ChannelMixFilter;
+    lowPass?: LowPassFilter;
+    echo: EchoFilter;
+    reverb: ReverbFilter;
+}