🌊 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

# Stable release
npm install aqualink

# Development build
npm install ToddyTheNoobDud/aqualink

🧶 Yarn

yarn add aqualink
yarn add ToddyTheNoobDud/aqualink

⚡ Bun

bun add aqualink
bun add ToddyTheNoobDud/aqualink

📦 pnpm

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

npm install aqualink discord.js

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

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

Add to Discord

Add to Discord

View All Projects →

📖 Documentation

For detailed usage, API references, and examples, check out the official documentation:

📌 Get Started Quickly

• Installation guide
• API methods
• Events and filters
• Troubleshooting

🔗 Visit: Aqualink Docs

👑 Bots Using Aqualink

Bot	Invite Link	Notes
Kenium	Add to Discord	Music playback, playlist support
Soya Music	Add to Discord	Music playback, Discord integration
Rive	Add to Discord	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

We welcome contributions of all sizes: fixes, features, and docs improvements.

💬 Community & Support

Join the community and get help quickly:

_{Built with 💙 by the Aqualink Team}