[![NPM Downloads](https://img.shields.io/npm/dw/aqualink.svg?style=for-the-badge&color=3498db)](https://www.npmjs.com/package/aqualink) [![NPM Version](https://img.shields.io/npm/v/aqualink?color=0061ff&label=Aqualink&style=for-the-badge&logo=npm)](https://www.npmjs.com/package/aqualink) [![GitHub Stars](https://img.shields.io/github/stars/ToddyTheNoobDud/AquaLink?color=00bfff&style=for-the-badge&logo=github)](https://github.com/ToddyTheNoobDud/AquaLink/stargazers) [![Discord](https://img.shields.io/discord/1346930640049803266?color=7289da&label=Discord&logo=discord&style=for-the-badge)](https://discord.gg/K4CVv84VBC)

🌊 REIMAGINING AUDIO STREAMING FOR DISCORD 🌊

Built for high uptime, clean APIs, and real-world bot workloads

## 💎 Why Choose Aqualink?

🚀

Performance First

Efficient queue/player internals and load-balanced node selection.

🛠️

Developer Friendly

Simple API surface with CJS/ESM compatibility and TypeScript types.

🔌

Extensible

Plugin base class + rich event system for custom bot behavior.

## 📦 Installation **Latest Stable Release: `v2.20.1`**

📦 NPM

```bash # Stable release npm install aqualink # Development build npm install ToddyTheNoobDud/aqualink ```

🧶 Yarn

```bash yarn add aqualink yarn add ToddyTheNoobDud/aqualink ```

⚡ Bun

```bash bun add aqualink bun add ToddyTheNoobDud/aqualink ```

📦 pnpm

```bash pnpm add aqualink pnpm add ToddyTheNoobDud/aqualink ```

## 🔥 Implemented Highlights (v2.20.1)

Advanced Filters

EQ, Bassboost, Nightcore, Vaporwave, 8D, Karaoke, and more.

Failover + Recovery

Node failover, player migration, auto-resume, queue persistence.

Diagnostics

Debug events + trace buffer for production troubleshooting.

Flexible Runtime

Load balancing, region-aware nodes, autoplay, lyrics, mixer APIs.

## 📦 Resources

## 💻 Quick Start ```bash npm install aqualink discord.js ``` ```javascript const { Aqua, AqualinkEvents } = require('aqualink') const { Client, GatewayIntentBits, Events } = require('discord.js') const client = new Client({ intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent, GatewayIntentBits.GuildVoiceStates ] }) const nodes = [ { host: '127.0.0.1', password: 'your_password', // alias for `auth` port: 2333, ssl: false, name: 'main-node' } ] const aqua = new Aqua(client, nodes, { defaultSearchPlatform: 'ytsearch', restVersion: 'v4', autoResume: true, infiniteReconnects: true, loadBalancer: 'leastLoad', leaveOnEnd: false, autoRegionMigrate: false }) client.once(Events.ClientReady, async () => { await aqua.init(client.user.id) console.log(`Logged in as ${client.user.tag}`) }) // Forward Discord voice packets to Aqualink client.on(Events.Raw, (packet) => { if (packet.t === 'VOICE_SERVER_UPDATE' || packet.t === 'VOICE_STATE_UPDATE') { aqua.updateVoiceState(packet) } }) client.on(Events.MessageCreate, async (message) => { if (message.author.bot || !message.content.startsWith('!play')) return const query = message.content.slice(6).trim() if (!query) return message.channel.send('Please provide a song to play.') if (!message.member.voice.channel) { return message.channel.send('You need to be in a voice channel to play music!') } const player = aqua.createConnection({ guildId: message.guild.id, voiceChannel: message.member.voice.channel.id, textChannel: message.channel.id, deaf: true }) try { const resolved = await aqua.resolve({ query, requester: message.member }) const { loadType, tracks, playlistInfo } = resolved if (loadType === 'playlist') { player.queue.add(...tracks) message.channel.send(`Added ${tracks.length} songs from ${playlistInfo?.name || 'playlist'}.`) } else if (loadType === 'search' || loadType === 'track') { const track = tracks[0] player.queue.add(track) message.channel.send(`Added **${track.title}** to the queue.`) } else { return message.channel.send('No results found.') } if (!player.playing && !player.paused) { await player.play() } } catch (error) { console.error('Playback error:', error) message.channel.send('An error occurred while trying to play the song.') } }) aqua.on(AqualinkEvents.NodeConnect, (node) => { console.log(`Node connected: ${node.name}`) }) aqua.on(AqualinkEvents.NodeError, (node, error) => { console.log(`Node "${node.name}" encountered an error: ${error.message}`) }) aqua.on(AqualinkEvents.TrackStart, (player, track) => { const channel = client.channels.cache.get(player.textChannel) if (channel) channel.send(`Now playing: **${track.title}**`) }) aqua.on(AqualinkEvents.QueueEnd, (player) => { const channel = client.channels.cache.get(player.textChannel) if (channel) channel.send('The queue has ended.') player.destroy() }) client.login('YOUR_DISCORD_BOT_TOKEN') ``` ### Additional Commands You Can Add ```javascript client.on(Events.MessageCreate, async (message) => { if (message.content === '!skip') { const player = aqua.players.get(message.guild.id) if (player) { player.skip() message.channel.send('⏭️ Skipped current track!') } } }) client.on(Events.MessageCreate, async (message) => { if (message.content === '!stop') { const player = aqua.players.get(message.guild.id) if (player) { player.destroy() message.channel.send('⏹️ Stopped playback and cleared queue!') } } }) ``` ## 🌟 Featured Projects

Add to Discord

[View All Projects →](https://github.com/ToddyTheNoobDud/AquaLink#used-by) ## 📖 Documentation For detailed usage, API references, and examples, check out the official documentation: [![Docs](https://img.shields.io/badge/Documentation-0099FF?style=for-the-badge&logo=readthedocs&logoColor=white)](https://aqualink-6006388d.mintlify.app) 📌 **Get Started Quickly** - Installation guide - API methods - Events and filters - Troubleshooting 🔗 Visit: **[Aqualink Docs](https://aqualink-6006388d.mintlify.app)** ## 👑 Bots Using Aqualink | Bot | Invite Link | Notes | |-----|-------------|-------| | Kenium | [Add to Discord](https://discord.com/oauth2/authorize?client_id=1202232935311495209) | Music playback, playlist support | | Soya Music | [Add to Discord](https://discord.com/oauth2/authorize?client_id=997906613082013868&permissions=281357446481&integration_type=0&scope=bot+applications.commands) | Music playback, Discord integration | | Rive | [Add to Discord](https://discord.com/oauth2/authorize?client_id=1384158871207280651) | Audio streaming bot | ## 🛠️ Advanced Features

🎛️ Audio Filters

Equalizer
Bassboost preset
Nightcore & Vaporwave presets
8D rotation
Karaoke, ChannelMix, LowPass, Distortion

🔄 Queue & Player Control

Shuffle & loop modes
Seek, replay, skip
Queue move/swap/remove
Autoplay support
Save/load player sessions

📡 Reliability

Auto reconnects
Node failover migration
Region-aware node migration
Debug trace buffer
Lyrics and live lyrics support

## 👥 Contributors

_southctrl
💻 📖

_{ToddyTheNoobDud}
💻 📖

_SoulDevs
💻

[Become a contributor →](CONTRIBUTING.md)

## 🤝 Contributing

We welcome contributions of all sizes: fixes, features, and docs improvements. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-0061ff.svg?style=for-the-badge)](CONTRIBUTING.md)

## 💬 Community & Support

Join the community and get help quickly: [![Discord Server](https://img.shields.io/badge/Discord_Server-7289da?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/K4CVv84VBC) [![GitHub Discussions](https://img.shields.io/badge/GitHub_Discussions-0061ff?style=for-the-badge&logo=github&logoColor=white)](https://github.com/ToddyTheNoobDud/AquaLink/discussions)

_{Built with 💙 by the Aqualink Team}