lavalink-client - GitLite

KO | EN

gitlite — search

#react #ai #llm #go #android #machine-learning #deep-learning #macos #awesome #cli #security #mcp #ios #open-source

lavalink-client

(★ 126)

Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Proficients.

파일 탐색기

최종 버전 다운로드 (.zip)

- - deployDocs.yml
  - publishAnyCommit.yml
- - favicon.svg
- - env.d.ts
- .gitignore
- astro.config.mjs
- package.json
- post_build.mjs
- tsconfig.json
- - Constants.ts
  - Filters.ts
  - LavalinkManager.ts
  - LavalinkManagerStatics.ts
  - Node.ts
  - NodeLink.ts
  - NodeManager.ts
  - Player.ts
  - Queue.ts
  - Utils.ts
- index.ts
- - addUnresolved.ts
  - audioOutput.ts
  - equalizer.ts
  - eval.ts
  - examples.ts
  - filter.ts
  - floweryTts.ts
  - join.ts
  - lavaSearch.ts
  - listqueue.ts
  - localfile.ts
  - loop.ts
  - pause.ts
  - play.ts
  - reconnectSync.ts
  - resume.ts
  - resumeFixed.ts
  - seek.ts
  - skip.ts
  - stop.ts
  - stopPlaying.ts
  - volume.ts
- - interactionCreate.ts
  - raw.ts
  - ready.ts
- - commandLoader.ts
  - eventsLoader.ts
  - index.ts
- - index.ts
  - Nodes.ts
  - Player.ts
- - Client.ts
  - lavalink-client.d.ts
- - EQList.ts
  - handleResuming.ts
  - testPlay.ts
  - Time.ts
- config.ts
- example.env
- index.ts
- package.json
- README.md
- tsconfig.json
.gitattributes
.gitignore
.oxfmtrc.json
LICENSE
package.json
README.md
tsconfig.json
tsdown.config.ts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/Tomato6966/lavalink-client

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd lavalink-client

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install --save lavalink-client

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm install --save tomato6966/lavalink-client

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

yarn add lavalink-client

이 명령어를 터미널에 그대로 입력해 실행하세요.

yarn add tomato6966/lavalink-client

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm add lavalink-client

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div style="font-family: Arial, sans-serif; border: 1px solid #fab788; border-radius: 15px; padding: 25px; ">

<h1 align="center" style="color: #fab788; border-bottom: 2px solid #3498db; padding-bottom: 10px;">Lavalink Client</h1>
<p align="center" style="font-size: 1.2em; color: #555;">An easy, flexible, and feature-rich Lavalink v4 Client for both beginners and experts.</p>

<div align="center">
  <p>
    <img src="https://madewithlove.now.sh/at?heart=true&template=for-the-badge" alt="Made with love in Austria">
    <img alt="Made with TypeScript" src="https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white">
  </p>
  <p>
    <a href="https://www.npmjs.com/package/lavalink-client">
      <img src="https://img.shields.io/npm/v/lavalink-client.svg?maxAge=3600&style=for-the-badge&logo=npm&logoColor=red" alt="NPM Version" />
    </a>
    <a href="https://www.npmjs.com/package/lavalink-client">
      <img src="https://img.shields.io/npm/dt/lavalink-client.svg?maxAge=3600&style=for-the-badge&logo=npm&logoColor=red" alt="NPM Downloads" />
    </a>
    <a href="https://tomato6966.github.io/lavalink-client/">
      <img src="https://img.shields.io/badge/Documentation-%230288D1.svg?style=for-the-badge&logo=gitbook&logoColor=white" alt="Get Started Now">
    </a>
  </p>
  <p>
    <a href="https://www.npmjs.com/package/lavalink-client"><img src="https://nodei.co/npm/lavalink-client.png?downloads=true&stars=true" alt="NPM Install: lavalink-client" /></a>
  </p>
</div>

---

## 🚀 Features

- 💯 **Lavalink v4 Native:** Full support for Lavalink v4, including its powerful plugin ecosystem.
- ✅ **Detailed Player-Destroy Reasons:** Understand precisely why a player was destroyed (e.g., channel deleted, bot disconnected).
- ✨ **Flexible Queue Stores:** Use the default in-memory store or bring your own (Redis, databases, etc.) to sync queues across multiple processes.
- 🎶 **Unresolved Tracks:** Supports unresolved track objects, fetching full data only when a track is about to play, saving API requests and resources.
- 🎚️ **Built-in Filters & EQ:** Easy-to-use management for audio filters and equalizers.
- 🔍 **Advanced Queue Filtering:** Search and filter tracks in the queue by title, author, duration, and more with powerful query options.
- ⚙️ **Advanced Player Options:** Fine-tune player behavior for disconnects, empty queues, volume handling, and more.
- 🛡️ **Lavalink-Side Validation:** Ensures you only use filters, plugins, and sources that your Lavalink node actually supports.
- 🔒 **Client-Side Validation:** Whitelist and blacklist URLs or domains to prevent unwanted requests and protect your bot.
- 🧑‍💻 **Developer-Friendly:** A memory-efficient design with a clean, intuitive API that mirrors Lavalink's own implementation.
- 🤖 **Automated Handling:** Automatically handles track skipping on errors, voice channel deletions, server-wide mutes, and much more.

---

## 📦 Installation

**Latest Stable Version: `v2.9.x`**

<details>
<summary><strong>👉 via NPM</strong></summary>

```bash
# Stable (install release)
npm install --save lavalink-client

# Development (Install github dev-branch)
npm install --save tomato6966/lavalink-client
```

</details>

<details>
<summary><strong>👉 via YARN</strong></summary>

```bash
# Stable (install release)
yarn add lavalink-client

# Development (Install github dev-branch)
yarn add tomato6966/lavalink-client
```

</details>

<details>
<summary><strong>👉 via BUN</strong></summary>

```bash
# Stable (install release)
bun add lavalink-client

# Development (Install github dev-branch)
bun add tomato6966/lavalink-client
```

</details>

<details>
<summary><strong>👉 via pnpm</strong></summary>

```bash
# Stable (install release)
pnpm add lavalink-client

# Development (Install github dev-branch)
pnpm add tomato6966/lavalink-client
```

</details>

## 📖 Documentation & Guides

- **[Full Documentation](https://tomato6966.github.io/lavalink-client/)** - Your starting point for everything.
- **[Manager Events](https://tomato6966.github.io/lavalink-client/extra/manager-events)** - Handle track, player, and general client events.
- **[NodeManager Events](https://tomato6966.github.io/lavalink-client/extra/node-events)** - Manage node connections, errors, and logs.
- **[Session Resuming Guide](https://tomato6966.github.io/lavalink-client/extra/resuming)** - Learn how to implement session resuming for seamless restarts.

---

# Node Link

This client can be used with nodelink too, but because nodelink's websocket is different than the one from lavalink, you need to disable a few things on the NODE OPTIONS / NODE PROPERTIES:

Import the NodeType Enum:

```
import { NodeType } from "lavalink-client"
```

// You must assign NodeLink enum to nodeType of the node options, before creating the node.

```ts
nodeOptions.nodeType = NodeType.NodeLink;
```

this can be done directly when creating the node in the lavalinkmanager.

```ts
client.lavalink = new LavalinkManager({
    nodes: [
        {
            host: "localhost",
            nodeType: NodeType.NodeLink, // provide nodeType "nodelink" to it.
        },
    ],
});
// or here if you need a bigger example.
client.lavalink = new LavalinkManager({
    nodes: [
        {
            authorization: "youshallnotpass", // The password for your Lavalink server
            host: "localhost",
            port: 2333,
            id: "Main Node",
            // set to nodeLink
            nodeType: NodeType.NodeLink, // provide it here
        },
        // you can also use the util like this, and it will return a valid node option object. must start with: lavalink:// | nodelink://
        // parseLavalinkConnUrl("nodelink://<nodeId>:<nodeAuthorization(Password)>@<NodeHost>:<NodePort>")
    ],
    // A function to send voice server updates to the Lavalink client
    sendToShard: (guildId, payload) => {
        const guild = client.guilds.cache.get(guildId);
        if (guild) guild.shard.send(payload);
    },
    autoSkip: true,
    client: {
        id: process.env.CLIENT_ID, // Your bot's user ID
        username: "MyBot",
    },
});
```

Now if you want to use NodeLink specific functions, you can use the type assertion checker function:

```ts
if (node.isNodeLink()) {
    // node is now typed as NodeLink
    node.addMixerLayer();
} else if (node.isLavalinkNode()) {
    // node is now typed as LavalinkNode
} else {
    // node is now typed as whatever it is..
}
```

or you have to assert the type...

```
const node = client.lavalink.lavalinkManager.getNode("id") as NodeLinkNode;
node.addMixerLayer()
```

⚠️ NODELINK does not really require you to run "instaUpdateFiltersFix" on player creation.

### NodeLink Specific Methods

- **`node.getYoutubeOAUTH(refreshToken)`**: Exchange a Refresh Token for an Access Token. [Docs](https://nodelink.js.org/docs/api/nodelink-features#oauth)
- **`node.updateYoutubeOAUTH(refreshToken)`**: Update the OAUTH token. [Docs](https://nodelink.js.org/docs/api/nodelink-features#oauth)
- **`node.getChapters(player, track?)`**: Retrieve Chapters of Youtube Videos. [Docs](https://nodelink.js.org/docs/api/nodelink-features#loadchapters)
- **`node.nodeLinkLyrics(player, track?, language?)`**: Retrieve Lyrics of Youtube Videos. [Docs](https://nodelink.js.org/docs/api/nodelink-features#lyrics--chapters)
- **`node.getDirectStream(track)`**: Stream audio directly from NodeLink. [Docs](https://nodelink.js.org/docs/api/nodelink-features#direct-streaming)
- **`node.listMixerLayers(player)`**: Retrieves a list of currently active mix layers. [Docs](https://nodelink.js.org/docs/api/rest#get-active-mixes)
- **`node.addMixerLayer(player, track, volume)`**: Adds a new audio track to be mixed. [Docs](https://nodelink.js.org/docs/api/rest#add-mix-layer)
- **`node.removeMixerLayer(player, mixId)`**: Removes a specific mix layer. [Docs](https://nodelink.js.org/docs/api/rest#remove-mix-layer)
- **`node.updateMixerLayerVolume(player, mixId, volume)`**: Updates the volume of a specific mix layer. [Docs](https://nodelink.js.org/docs/api/rest#update-mix-volume)
- **`node.changeAudioTrackLanguage(player, language_audioTrackId)`**: Changes the current language of the audio. [Docs](https://nodelink.js.org/docs/api/nodelink-features#additional-filters)
- **`node.updateYoutubeConfig(refreshToken?, visitorData?)`**: Updates the YouTube configuration. [Docs](https://nodelink.js.org/docs/api/nodelink-features#update-config)
- **`node.getYoutubeConfig(validate?)`**: Gets the YouTube configuration.
- **`node.getConnectionMetrics()`**: Get connection metrics. [Docs](https://nodelink.js.org/docs/api/rest#node-information)
- **`node.loadDirectStream(track, volume, position, filters)`**: Stream raw PCM audio. [Docs](https://nodelink.js.org/docs/api/nodelink-features#loadstream)

### NodeLink Specific Sources (`SourcesRecord`)

By default, the client uses a generic `DefaultSources` record to map human-friendly prefixes like `youtube:`, `spotify:`, etc. to Lavalink search sources.

For NodeLink, you can override this behavior to use the NodeLink-specific source prefixes (including `admsearch`, `audiomack`, `gaanasearch`, `gtts`, `pipertts`, etc.) via the `NodeLinkDefaultSources` export and the `ManagerUtils#SourcesRecord` property:

```ts
import { LavalinkManager, NodeType, NodeLinkNode, NodeLinkDefaultSources } from "lavalink-client";

// create the manager as usual, but with a NodeLink node
client.lavalink = new LavalinkManager({
    nodes: [
        {
            authorization: "youshallnotpass",
            host: "localhost",
            port: 2333,
            id: "nodelink-main",
            nodeType: NodeType.NodeLink,
        },
    ],
    sendToShard: (guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
    autoSkip: true,
    client: {
        id: envConfig.clientId,
        username: "MyBot",
    },
});

// IMPORTANT: Override the default source mapping so `ytsearch:`, `amsearch:`, `admsearch:`, etc.
// use the NodeLink-specific prefixes.
client.lavalink.utils.SourcesRecord = NodeLinkDefaultSources;

// Optional: You can also provide your own custom record extending NodeLinkDefaultSources:
client.lavalink.utils.SourcesRecord = {
    ...NodeLinkDefaultSources,
    // custom alias that only your bot understands, which resolves to a NodeLink source
    mycustomsource: "ytsearch",
};
```

This makes all helper methods that use `ManagerUtils` (such as `transformQuery`, `transformLavaSearchQuery` and `validateSourceString`) work with NodeLink’s extended search prefixes when you are connected to a NodeLink node.

### NodeLink Specififc Events?

```ts
// NodeLink specific events
client.lavalink.nodeManager.on("nodeLinkEvent", (node, eventName, player, track, payload) => {
    switch (eventName) {
        // -------------Player LifeCycle Events-------------
        // https://nodelink.js.org/docs/api/websocket#playercreatedevent
        case "PlayerCreatedEvent":
            {
                // { "guildId": "987654321098765432", "track": null, "paused": false, "volume": 100 }
                const playerInfo = payload.player;
                console.log(`Player created in guildId: ${playerInfo.guildId}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#playerdestroyedevent
        case "PlayerDestroyedEvent":
            {
                // "987654321098765432"
                const playerInfo = payload.guildId;
                console.log(`Player destroyed in guildId: ${playerInfo.guildId}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#playerconnectedevent
        case "PlayerConnectedEvent":
            {
                // { "sessionId": "abc", "token": "token", "endpoint": "us-central123.discord.media", "channelId": "123456789012345678" }
                const playerInfo = payload.voice;
                console.log(`Player connected in guildId: ${playerInfo.guildId}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#playerreconnectingevent
        case "PlayerReconnectingEvent":
            {
                // { "sessionId": "abc", "token": "token", "endpoint": "us-central123.discord.media", "channelId": "123456789012345678" }
                const playerInfo = payload.voice;
                console.log(`Player reconnecting in guildId: ${playerInfo.guildId}`);
            }
            break;

// -------------Player State Events-------------
        // https://nodelink.js.org/docs/api/websocket#volumechangedevent
        case "VolumeChangedEvent":
            {
                // "guildId": "987654321098765432",
                // "volume": 100
                const { guildId, volume } = payload;
                console.log(`Player volume changed in guildId: ${guildId} to ${volume}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#filterschangedevent
        case "FiltersChangedEvent":
            {
                // { ...Filtersdata... }
                const { guildId, filters } = payload;
                console.log(`Player filters changed in guildId: ${guildId}, new Data: `, filters);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#seekevent
        case "SeekEvent":
            {
                // "guildId": "987654321098765432",
                // "position": 10000,
                const { guildId, position } = payload;
                console.log(`Player seeked in guildId: ${guildId}, new position: ${position}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#pauseevent
        case "PauseEvent":
            {
                // "guildId": "987654321098765432",
                // "paused": true
                const { guildId, paused } = payload;
                console.log(`Player paused in guildId: ${guildId}, paused true/false: ${paused}`);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#connectionstatusevent
        case "ConnectionStatusEvent":
            {
                // "guildId": "987654321098765432",
                // "status": "CONNECTED"
                // "metrics": { ... }
                const { guildId, status, metrics } = payload;
                console.log(
                    `Player connection status changed in guildId: ${guildId}, status: ${status}, metrics: `,
                    metrics,
                );
            }
            break;

// -------------LYRICS EVENTS-------------
        // https://nodelink.js.org/docs/api/websocket#lyrics-events
        case "LyricsFoundEvent":
            {
                // "guildId": "987654321098765432",
                // "lyrics": "..."
                const { guildId, lyrics } = payload;
                console.log(`Lyrics found in guildId: ${guildId}, lyrics: `, lyrics);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#lyricslineevent
        case "LyricsLineEvent":
            {
                // "guildId": "987654321098765432",
                // "lineIndex": 0,
                // "line": "..."
                const { guildId, lineIndex, line } = payload;
                console.log(`Lyrics line in guildId: ${guildId}, lineIndex: ${lineIndex}, line: `, line);
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#lyricsnotfoundevent
        case "LyricsNotFoundEvent":
            {
                // "guildId": "987654321098765432",
                const { guildId } = payload;
                console.log(`Lyrics not found in guildId: ${guildId}`);
            }
            break;

// -------------AUDIO MIXER EVENTS-------------
        // https://nodelink.js.org/docs/api/websocket#mixstartedevent
        case "MixStartedEvent":
            {
                // "guildId": "987654321098765432",
                // "mixId": "123456789012345678"
                // "volume": 0.8,
                // "track": { ...TrackData... }
                const { guildId, mixId, volume, track } = payload.player;
                console.log(
                    `Player mix started in guildId: ${guildId}, mixId: ${mixId}, volume: ${volume}, track: `,
                    track,
                );
            }
            break;
        // https://nodelink.js.org/docs/api/websocket#mixendedevent
        case "MixEndedEvent":
            {
                //  "guildId": "987654321098765432",
                //  "mixId": "123456789012345678",
                //  "reason": "USER_STOPPED"
                const { guildId, mixId, reason } = payload;
                console.log(`Player mix ended in guildId: ${guildId}, mixId: ${mixId}, reason: ${reason}`);
            }
            break;
    }
});
```

---

## 💖 Used In

This client powers various Discord bots:

- **[Mivator](https://discord.gg/5dUb7M2qCj)** (Public Bot by @Tomato6966)
- **[Betty](https://betty.bot/?utm_source=lavalink-client)** (Public Bot by @fb_sean)
- **[Nero](https://betty.bot/?utm_source=lavalink-client)** (Public Bot by @fb_sean)
- **Bots by Contributors:**
    - [Mintone](https://mintone.tech/) (@appujet)
    - [Stelle](https://github.com/Ganyu-Studios/stelle-music) (@EvilG-MC)
    - [Panais](https://panais.xyz/) (@LucasB25)
    - [Akyn](https://akynbot.vercel.app/) (@notdeltaxd)
    - [ARINO](https://site.arinoapp.qzz.io/) (@ryanwtf88)
    - [iHorizon](https://github.com/ihrz/ihrz) (@iHorizon)
- **Bots By Community (Users):**
    - [Soundy](https://github.com/idMJA/Soundy) (@idMJA)
    - [BeatBot](https://getbeatbot.vercel.app/) (@zenitsujs)
    - [Atom Music](https://top.gg/bot/1320469557411971165) (@sakshamyep)
    - [All Time Bot](https://top.gg/bot/1163027457671180418) (@PeterGamez)
    - [BeatDock](https://github.com/lazaroagomez/BeatDock) (@lazaroagomez)
    - [Nazha](https://top.gg/bot/1124681788070055967) (@Nazha-Team)
    - [Arii Music](https://arimusic.me/) (@friston_ae)

---

## 🛠️ Configuration Examples

### Basic Setup

A minimal example to get you started quickly.

```typescript
import { LavalinkManager } from "lavalink-client";
import { Client, GatewayIntentBits } from "discord.js"; // example for a discord bot

// Extend the Client type to include the lavalink manager
declare module "discord.js" {
    interface Client {
        lavalink: LavalinkManager;
    }
}

const client = new Client({
    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
});

client.lavalink = new LavalinkManager({
    nodes: [
        {
            authorization: "youshallnotpass", // The password for your Lavalink server
            host: "localhost",
            port: 2333,
            id: "Main Node",
        },
        // you can also use the util like this, and it will return a valid node option object.
        // parseLavalinkConnUrl("nodelink://<nodeId>:<nodeAuthorization(Password)>@<NodeHost>:<NodePort>")
    ],
    // A function to send voice server updates to the Lavalink client
    sendToShard: (guildId, payload) => {
        const guild = client.guilds.cache.get(guildId);
        if (guild) guild.shard.send(payload);
    },
    autoSkip: true,
    client: {
        id: process.env.CLIENT_ID, // Your bot's user ID
        username: "MyBot",
    },
});

// Listen for the 'raw' event from discord.js and forward it
client.on("raw", (d) => client.lavalink.sendRawData(d));

client.on("ready", () => {
    console.log(`Logged in as ${client.user.tag}!`);
    // Initialize the Lavalink client
    client.lavalink.init({ ...client.user });
});

client.login(process.env.DISCORD_TOKEN);
```

<details>
<summary><strong>🔩 Complete Configuration Example (almost all Options)</strong></summary>

```typescript
import { LavalinkManager, QueueChangesWatcher, QueueStoreManager, StoredQueue } from "lavalink-client";
import { RedisClientType, createClient } from "redis";
import { Client, GatewayIntentBits, User } from "discord.js";

// It's recommended to extend the Client type
declare module "discord.js" {
    interface Client {
        lavalink: LavalinkManager;
        redis: RedisClientType;
    }
}

const client = new Client({
    intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
});

client.lavalink = new LavalinkManager({
    nodes: [
        {
            authorization: "youshallnotpass",
            host: "localhost",
            port: 2333,
            id: "testnode",
            secure: false, // Set to true for wss://
            retryAmount: 5,
            retryDelay: 10_000, // 10 seconds
        },
        // you can also use the util like this, and it will return a valid node option object. must start with: lavalink:// | nodelink://
        // parseLavalinkConnUrl("lavalink://<nodeId>:<nodeAuthorization(Password)>@<NodeHost>:<NodePort>")
    ],
    sendToShard: (guildId, payload) => client.guilds.cache.get(guildId)?.shard?.send(payload),
    autoSkip: true, // automatically play the next song of the queue, on: trackend, trackerror, trackexception
    client: {
        id: process.env.CLIENT_ID,
        username: "TESTBOT",
    },
    playerOptions: {
        applyVolumeAsFilter: false,
        clientBasedPositionUpdateInterval: 50,
        defaultSearchPlatform: "ytmsearch",
        volumeDecrementer: 0.75,
        onDisconnect: {
            autoReconnect: true,
            destroyPlayer: false,
        },
        onEmptyQueue: {
            destroyAfterMs: 30_000,
            // function get's called onqueueempty, and if there are songs added to the queue, it continues playing. if not then not (autoplay functionality)
            // autoPlayFunction: async (player) => { /* ... */ },
        },
        useUnresolvedData: true,
    },
    queueOptions: {
        maxPreviousTracks: 10,
        queueStore: new MyCustomRedisStore(client.redis),
        queueChangesWatcher: new MyCustomQueueWatcher(client),
    },
    // Whitelist/Blacklist links or words
    linksAllowed: true,
    linksBlacklist: ["somebadsite.com"],
    linksWhitelist: [],
    advancedOptions: {
        debugOptions: {
            noAudio: false,
            playerDestroy: { dontThrowError: false, debugLog: false },
        },
    },
});

client.on("raw", (d) => client.lavalink.sendRawData(d));
client.on("ready", () => client.lavalink.init({ ...client.user }));

// Example Custom Redis Queue Store
class MyCustomRedisStore implements QueueStoreManager {
    private redis: RedisClientType;
    constructor(redisClient: RedisClientType) {
        this.redis = redisClient;
    }
    private key(guildId: string) {
        return `lavalinkqueue_${guildId}`;
    }
    async get(guildId: string) {
        return await this.redis.get(this.key(guildId));
    }
    async set(guildId: string, data: string) {
        return await this.redis.set(this.key(guildId), data);
    }
    async delete(guildId: string) {
        return await this.redis.del(this.key(guildId));
    }
    async parse(data: string): Promise<Partial<StoredQueue>> {
        return JSON.parse(data);
    }
    stringify(data: Partial<StoredQueue>): string {
        return JSON.stringify(data);
    }
}

// Example Custom Queue Watcher
class MyCustomQueueWatcher implements QueueChangesWatcher {
    private client: Client;
    constructor(client: Client) {
        this.client = client;
    }
    shuffled(guildId: string) {
        console.log(`Queue shuffled in guild: ${guildId}`);
    }
    tracksAdd(guildId: string, tracks: any[], position: number) {
        console.log(`${tracks.length} tracks added at position ${position} in guild: ${guildId}`);
    }
    tracksRemoved(guildId: string, tracks: any[], position: number) {
        console.log(`${tracks.length} tracks removed at position ${position} in guild: ${guildId}`);
    }
}
```

</details>

---

## 📢 Events

Listen to events to create interactive and responsive logic.

### Lavalink Manager Events

These events are emitted from the main `LavalinkManager` instance and relate to players and tracks.

- `playerCreate (player)`
- `playerDestroy (player, reason)`
- `playerDisconnect (player, voiceChannelId)`
- `playerMove (player, oldChannelId, newChannelId)`
- `trackStart (player, track)`
- `trackEnd (player, track)`
- `trackStuck (player, track, payload)`
- `trackError (player, track, payload)`
- `queueEnd (player)`

<details>
<summary><strong>📢 Example for Manager-Event-Listeners</strong></summary>

```javascript
// Example: Listening to a track start event
client.lavalink.on("trackStart", (player, track) => {
    const channel = client.channels.cache.get(player.textChannelId);
    if (channel) channel.send(`Now playing: ${track.info.title}`);
});

// Example: Handling queue end
client.lavalink.on("queueEnd", (player) => {
    const channel = client.channels.cache.get(player.textChannelId);
    if (channel) channel.send("The queue has finished. Add more songs!");
    player.destroy();
});
```

</details>

### Node Manager Events

These events are emitted from `lavalink.nodeManager` and relate to the Lavalink node connections.

- `create (node)`
- `connect (node)`
- `disconnect (node, reason)`
- `reconnecting (node)`
- `destroy (node)`
- `error (node, error, payload)`
- `resumed (node, payload, players)`

<details>
<summary><strong>📢 Example for Node-Event-Listeners</strong></summary>

```javascript
// Example: Logging node connections and errors
client.lavalink.nodeManager.on("connect", (node) => {
    console.log(`Node "${node.id}" connected!`);
});

client.lavalink.nodeManager.on("error", (node, error) => {
    console.error(`Node "${node.id}" encountered an error:`, error.message);
});
```

</details>

---

## 📚 Advanced How-To Guides

### How to Implement Session Resuming

Resuming allows your music bot to continue playback even after a restart.

1.  **Enable Resuming on the Node:** When a node connects, enable resuming with a timeout.
2.  **Listen for the `resumed` Event:** This event fires on a successful reconnect, providing all player data from Lavalink.
3.  **Re-create Players:** Use the data from the `resumed` event and your own saved data (from a database/store) to rebuild the players and their queues.

> 💡 **For a complete, working example, see the [official test bot's implementation](https://github.com/Tomato6966/lavalink-client/blob/main/testBot/Utils/handleResuming.ts).**

<details>
<summary><strong>💡 Principle of how to enable **resuming**</strong></summary>

```javascript
// 1. Enable resuming on connect
client.lavalink.nodeManager.on("connect", (node) => {
    // Enable resuming for 5 minutes (300,000 ms)
    node.updateSession(true, 300_000);
});

// 2. Listen for the resumed event
client.lavalink.nodeManager.on("resumed", async (node, payload, fetchedPlayers) => {
    console.log(`Node "${node.id}" successfully resumed with ${fetchedPlayers.length} players.`);

for (const lavalinkData of fetchedPlayers) {
        // 3. Get your saved data (e.g., from Redis/DB)
        const savedData = await getFromDatabase(lavalinkData.guildId);
        if (!savedData || !lavalinkData.state.connected) {
            if (savedData) await deleteFromDatabase(lavalinkData.guildId);
            continue; // Skip if no saved data or Lavalink reports disconnected
        }

// Re-create the player instance
        const player = client.lavalink.createPlayer({
            guildId: lavalinkData.guildId,
            voiceChannelId: savedData.voiceChannelId,
            textChannelId: savedData.textChannelId,
            // Important: Use the same node that was resumed
            node: node.id,
            // Set volume from Lavalink's data, accounting for the volume decrementer
            volume: lavalinkData.volume,
            selfDeaf: savedData.selfDeaf,
        });

// Re-establish voice connection
        await player.connect();

// Restore player state
        player.paused = lavalinkData.paused;
        player.lastPosition = lavalinkData.state.position;
        player.filterManager.data = lavalinkData.filters;

// Restore the queue
        await player.queue.utils.sync(true, false); // Syncs with your QueueStore

// Restore the current track
        if (lavalinkData.track) {
            player.queue.current = client.lavalink.utils.buildTrack(lavalinkData.track, savedData.requester);
        }
    }
});

// Persist player data on updates to use for resuming later
client.lavalink.on("playerUpdate", (oldPlayer, newPlayer) => {
    saveToDatabase(newPlayer.toJSON());
});

// Clean up data when a player is permanently destroyed
client.lavalink.on("playerDestroy", (player) => {
    deleteFromDatabase(player.guildId);
});
```

</details>

### How to Use Plugins

Lavalink client supports most of the major lavalink-plugins.
The client itself is - for beginner friendly reasons - atm not extendable (via plugins)
You can just use the built in functions (sponsor block, lyrics) or search plattforms (deezer, spotify, apple music, youtube, ...) and use the lavalink-plugins without any configuration on the client side.

Some plugins require extra-parameters, such as flowerytts:
Pass extra parameters to the search function to use plugin-specific features.

<details>
<summary><strong>How to use the flowerytts plugin</strong></summary>

```javascript
// Example for flowertts plugin
const query = interaction.options.getString("text");
const voice = interaction.options.getString("voice"); // e.g., "MALE_1"

const extraParams = new URLSearchParams();
if (voice) extraParams.append(`voice`, voice);

// All params for flowertts can be found here: https://flowery.pw/docs
const response = await player.search(
    {
        query: `${query}`,
        // This is used by plugins like ftts to adjust the request
        extraQueryUrlParams: extraParams,
        source: "ftts", // Specify the plugin source
    },
    interaction.user, // The requester
);

// Add the TTS track to the queue
if (response.tracks.length > 0) {
    player.queue.add(response.tracks[0]);
    if (!player.playing) player.play();
}
```

</details>

</div>