Skip to main content

Introduction

Welcome to Yukino - a modern, feature-rich Lavalink client for Discord.js. Yukino makes it easy to add high-quality audio playback to your Discord bot with minimal setup and maximum flexibility.

What is Yukino?​

Yukino is a TypeScript library that connects your Discord.js bot to a Lavalink server, providing:

  • 🎵 High-quality audio streaming
  • 🎚️ Advanced audio filters and effects
  • 📊 Queue management and track control
  • 🔄 Automatic voice state handling
  • ⚡ Excellent performance and stability
  • 🛡️ Full TypeScript support

Why Yukino?​

Easy to Use​

import { Client, GatewayIntentBits } from 'discord.js';
import { YukinoClient } from 'yukinojs';

// Create Discord.js client with required intents
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildVoiceStates
]
});

// Configure Yukino with enhanced options
const connectorOptions = {
client,
host: 'localhost',
port: 2333,
auth: 'youshallnotpass',
version: 'v4',
debug: false
};

const nodeOptions = {
name: 'MainNode',
url: 'localhost:2333',
auth: 'youshallnotpass',
reconnectOptions: {
maxRetryAttempts: 10,
retryDelayInMs: 5000
}
};

// Create Yukino client with resilient configuration
const yukino = new YukinoClient(client, connectorOptions, nodeOptions);

// Create a player and play music
const player = await yukino.createPlayer({
guildId: 'guild-id',
voiceChannelId: 'channel-id',
autoReconnect: true
});

// Search and play with error handling
try {
const result = await yukino.loadTrack('song name');
if (result.data[0]) {
await player.play({ track: result.data[0] });
}
} catch (error) {
console.error('Error playing track:', error);
}

Feature Rich​

  • Load tracks from various sources (YouTube, SoundCloud, etc.)
  • Apply real-time audio filters
  • Manage queues and playlists
  • Handle voice state changes automatically
  • Monitor track and player events

Type Safe​

// Get full TypeScript support
interface PlayerOptions {
guildId: string;
voiceChannelId: string;
textChannelId?: string;
}

const player = await yukino.createPlayer({
guildId, // Type checked!
voiceChannelId // Type checked!
});

Powerful Audio Control​

// Apply audio filters
await player.setFilters({
equalizer: [
{ band: 0, gain: 0.3 },
{ band: 1, gain: 0.2 }
],
volume: 100,
timescale: {
speed: 1.2,
pitch: 1.1
}
});

// Control playback
await player.pause();
await player.resume();
await player.seek(60000); // Seek to 1 minute

Queue Management​

// Add tracks to queue
player.queue.add(track);
player.queue.addMany(tracks);

// Control queue
player.queue.shuffle();
player.queue.clear();
player.queue.remove(0);

// Loop modes
player.setLoop('track'); // Loop current track
player.setLoop('queue'); // Loop entire queue
player.setLoop('none'); // Disable looping

Key Concepts​

YukinoClient​

The main client that manages the connection to Lavalink and creates players. Configure it with:

  • Connector options for basic connection settings
  • Node options for advanced features like auto-reconnection
  • Debug mode for detailed logging

Node​

Represents a connection to a Lavalink server. Handles:

  • Track loading and audio processing
  • Connection resilience with retry logic
  • Load balancing and failover

Player​

Manages playback for a specific voice channel:

  • Auto-reconnection on disconnects
  • Voice state tracking
  • Queue management
  • Audio filter control

Queue​

Handles track organization and playback order for a player.

Getting Started​

Ready to add music to your Discord bot? Follow our Installation Guide to get started!

Example Bot​

Here's a complete example of a simple music bot using Yukino:

import { Client, GatewayIntentBits } from 'discord.js';
import { YukinoClient } from 'yukinojs';

// Create Discord.js client
const client = new Client({
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildVoiceStates,
GatewayIntentBits.GuildMessages
]
});

// Configure Yukino options
const connectorOptions = {
client,
host: 'localhost',
port: 2333,
auth: 'youshallnotpass',
version: 'v4',
debug: false
};

const nodeOptions = {
name: 'MainNode',
url: 'localhost:2333',
auth: 'youshallnotpass',
reconnectOptions: {
maxRetryAttempts: 10,
retryDelayInMs: 5000
}
};

// Create Yukino client
const yukino = new YukinoClient(client, connectorOptions, nodeOptions);

// Error handling
yukino.node.on('nodeError', (error) => {
console.error('[Lavalink] Node error:', error);
});

yukino.node.on('nodeReady', () => {
console.log('[Lavalink] Node is ready!');
});

// Handle voice state updates
client.on('voiceStateUpdate', async (oldState, newState) => {
if (oldState.member?.user.id !== client.user?.id) return;

const player = yukino.getPlayer(oldState.guild.id);
if (!player) return;

if (oldState.channelId && !newState.channelId) {
// Bot was disconnected
if (player.playing) {
await player.connect().catch(() => player.destroy());
} else {
await player.destroy();
}
}
});

// Connect when ready
client.once('ready', () => {
console.log('Bot is ready!');
yukino.connect();
});

client.on('interactionCreate', async (interaction) => {
if (!interaction.isCommand()) return;

switch (interaction.commandName) {
case 'play': {
const query = interaction.options.getString('song', true);
const voiceChannel = interaction.member.voice.channel;

if (!voiceChannel) {
return interaction.reply('Join a voice channel first!');
}

try {
// Get or create player
const player = yukino.getPlayer(interaction.guildId) ||
await yukino.createPlayer({
guildId: interaction.guildId,
voiceChannelId: voiceChannel.id,
textChannelId: interaction.channelId,
autoReconnect: true
});

// Search and play
const result = await yukino.loadTrack(query);
if (result.data[0]) {
if (!player.playing) {
await player.play({ track: result.data[0] });
await interaction.reply(
`Now playing: ${result.data[0].info.title}`
);
} else {
player.queue.add(result.data[0]);
await interaction.reply(
`Added to queue: ${result.data[0].info.title}`
);
}
}
} catch (error) {
console.error('Play error:', error);
await interaction.reply('Failed to play track!');
}
break;
}

case 'stop': {
const player = yukino.getPlayer(interaction.guildId);
if (player) {
await player.destroy();
await interaction.reply('Stopped playback!');
}
break;
}
}
});

client.login('your-token');

Next Steps​