Client
The YukinoClient is the core class that manages your bot's connection to Lavalink and handles all audio operations, supporting multiple nodes and advanced player management.
Creating a Client
import { Client } from 'discord.js';
import { YukinoClient } from 'yukinojs';
const yukino = new YukinoClient(client, {
auth: 'your-password',
debug: true,
// Custom options
reconnectInterval: 5000, // Optional, default: 5000
reconnectTries: 3 // Optional, default: 3
});
Configuration Options
Required Options for Connector
client- Your Discord.js client instanceauth- The password for your Lavalink server
Optional Options for Connector
debug- Enable debug logging (default: false)reconnectInterval- Time between reconnect attempts in ms (default: 5000)reconnectTries- Number of reconnect attempts (default: 3)defaultSearchEngine- Search engine to use when no source is specified (default: 'ytsearch')userAgent- Custom user agent for REST requestsrestOptions- Custom REST options (timeout, retries, headers, etc.)
Required Options for Node
name- Unique identifier for the nodeurl- URL of the Lavalink server (hostname:port)auth- Password for the Lavalink server
Optional Options for Node
secure- Whether to use WSS/HTTPS (default: false)group- Group identifier for region-based selectionpriority- Node priority for load balancing (lower is higher priority)region- Region identifier for region-based selectionresumeKey- Key for resuming a sessionresumeTimeout- Timeout in seconds for resuming a sessionreconnectInterval- Time between reconnect attempts (default: 5000)reconnectTries- Maximum number of reconnect attempts (default: 3)
Node Management
Adding Nodes
// Add a single node
// NodeOptions type is required for each node
const node = yukino.addNode({
name: "main",
url: "localhost:2333",
auth: "your-password",
secure: false,
});
// Add multiple nodes
const nodes = yukino.addNodes([
{
name: "node1",
url: "node1.example.com:2333",
auth: "password1",
secure: true,
group: "us",
},
{
name: "node2",
url: "node2.example.com:2333",
auth: "password2",
secure: true,
group: "eu",
},
]);
Node Selection
Yukino automatically selects the best node for each player based on:
- Load balancing
- Node status
- Node penalty (calculated from CPU/memory usage)
- Node priority (lower values have higher priority)
- Node group (for region-based routing)
You can customize node selection with your own algorithm:
yukino.setNodeSelector((nodes, guildId) => {
// Custom node selection logic
return nodes.sort(
(a, b) =>
a.stats.cpu.lavalinkLoad / a.stats.memory.free -
b.stats.cpu.lavalinkLoad / b.stats.memory.free
)[0];
});
Player Management
Creating Players
import { PlayerOptions } from "yukinojs";
const player = yukino.createPlayer({
guildId: "guild-id",
voiceChannelId: "channel-id",
textChannelId: "text-channel-id", // Optional
deaf: true, // Whether to deafen the bot
mute: false, // Whether to mute the bot
volume: 100, // Initial volume (0-1000)
node: "node1", // Optional: Specific node to use
nodeGroup: "us", // Optional: Node group to select from
autoReconnect: true, // Automatically reconnect on disconnect
} as PlayerOptions);
Getting Players
// Get a specific player
const player = yukino.getPlayer("guild-id");
// Get all players (Map<string, Player>)
const players = yukino.players;
// Check if a guild has a player
const hasPlayer = yukino.hasPlayer("guild-id");
// Get a queue by guild ID
const queue = yukino.getQueue("guild-id");
Destroying Players
// Destroy a specific player (returns Promise<boolean>)
await yukino.destroyPlayer("guild-id");
// Destroy all players (returns Promise<number>)
await yukino.destroyAllPlayers();
Track Loading
Loading Tracks
// Load a track by search query
const result = await yukino.loadTrack("never gonna give you up");
// Load a track by URL
const result = await yukino.loadTrack(
"https://youtube.com/watch?v=dQw4w9WgXcQ"
);
// Load a playlist
const result = await yukino.loadTrack("https://youtube.com/playlist?list=...");
Search Options
import { SearchTypes, SearchOptions } from "yukinojs";
const result = await yukino.loadTrack("your query", {
// Specify search source (from SearchTypes enum)
source: SearchTypes.YOUTUBE, // 'ytsearch'
// Other options: YOUTUBE_MUSIC, SOUNDCLOUD, SPOTIFY, APPLE_MUSIC, DEEZER
// Add requester info (will be attached to each track)
requester: "user-id",
// Add custom context data (optional)
context: {
channelId: "channel-id",
requestTime: Date.now(),
},
} as SearchOptions);
Event Handling
Note: All events are emitted from
yukino.nodeManager. Useyukino.nodeManager.on(...)to listen for events.
Node Events
import { Events } from "yukinojs";
// Node ready
yukino.nodeManager.on(Events.NODE_READY, (node) => {
console.log(`Node ${node.name} is now ready`);
});
// Node error
yukino.nodeManager.on(Events.NODE_ERROR, (node, error) => {
console.error(`Node ${node.name} error:`, error);
});
// Node closed
yukino.nodeManager.on(Events.NODE_CLOSED, (node, code, reason) => {
console.log(`Node ${node.name} closed: Code ${code}, Reason: ${reason}`);
});
// Node stats update
yukino.nodeManager.on(Events.NODE_STATS, (node, stats) => {
console.log(`Node ${node.name} stats:`, stats);
});
Track Events
import { Events } from "yukinojs";
// Track started
yukino.nodeManager.on(Events.TRACK_START, (player, track) => {
console.log(`Playing ${track.info.title} in guild ${player.guildId}`);
});
// Track ended
yukino.nodeManager.on(Events.TRACK_END, (player, track, reason) => {
console.log(`Finished ${track.info.title} (${reason})`);
});
// Track stuck
yukino.nodeManager.on(Events.TRACK_STUCK, (player, track, thresholdMs) => {
console.warn(`Track ${track.info.title} stuck for ${thresholdMs}ms`);
});
// Track error
yukino.nodeManager.on(Events.TRACK_ERROR, (player, track, error) => {
console.error(`Error playing ${track.info.title}:`, error);
});
Player Events
import { Events } from "yukinojs";
// Player created
yukino.nodeManager.on(Events.PLAYER_CREATE, (player) => {
console.log(`Player created for guild ${player.guildId}`);
});
// Player destroyed
yukino.nodeManager.on(Events.PLAYER_DESTROY, (player) => {
console.log(`Player destroyed for guild ${player.guildId}`);
});
// Player updated
yukino.nodeManager.on(Events.PLAYER_UPDATE, (player, state) => {
console.log(`Player updated for guild ${player.guildId}`, state);
});
// WebSocket closed
yukino.nodeManager.on(Events.WS_CLOSED, (player, code, reason, byRemote) => {
console.log(`WebSocket closed for guild ${player.guildId}: ${reason}`);
});
Error Handling
Client Level Error Handling
import { Events } from "yukinojs";
// General error handling
yukino.nodeManager.on(Events.NODE_ERROR, (node, error) => {
console.error(`Node ${node.name} error:`, error);
// Reconnect logic for specific errors
if (error.message.includes("ECONNREFUSED")) {
console.log(`Connection refused to node ${node.name}, will retry...`);
}
});
// Track error handling
yukino.nodeManager.on(Events.TRACK_ERROR, (player, track, error) => {
console.error(
`Error playing ${track.info.title} in guild ${player.guildId}:`,
error
);
// Skip to next track on error
player.skip().catch(console.error);
});
Player Level Error Handling
// Get an existing player
const player = yukino.getPlayer("guild-id");
// Handle errors at the player level
player.on(Events.TRACK_ERROR, (track, error) => {
console.error(`Error playing ${track.info.title}:`, error);
// Take appropriate action
player.skip().catch(console.error);
});
Advanced Usage
Custom REST Options
const connectorOptions = {
client,
auth: "your-password",
restOptions: {
timeout: 10000,
retries: 3,
headers: {
"User-Agent": "MyBot/1.0.0",
"X-Custom-Header": "CustomValue",
},
},
};
const yukino = new YukinoClient(client, connectorOptions, nodeOptions);
Node Groups for Region-based Routing
// Create node groups for different regions
yukino.addNodes([
{
name: "us-east",
url: "us1.example.com:2333",
auth: "password",
group: "us",
region: "us-east",
},
{
name: "us-west",
url: "us2.example.com:2333",
auth: "password",
group: "us",
region: "us-west",
},
{
name: "eu-central",
url: "eu1.example.com:2333",
auth: "password",
group: "eu",
region: "eu-central",
},
]);
// Select nodes by group and region
yukino.setNodeSelector((nodes, guildId) => {
if (!guildId) return nodes[0];
// Get guild from Discord.js client
const guild = client.guilds.cache.get(guildId);
if (!guild) return nodes[0];
// Determine best region based on guild settings
let preferredGroup = "us";
if (guild.preferredLocale.startsWith("en-US")) {
preferredGroup = "us";
} else if (
guild.preferredLocale.startsWith("en-GB") ||
guild.preferredLocale.startsWith("de") ||
guild.preferredLocale.startsWith("fr")
) {
preferredGroup = "eu";
}
// Filter by group, then sort by penalties
const groupNodes = nodes.filter((node) => node.group === preferredGroup);
if (groupNodes.length === 0) return nodes[0];
return groupNodes.sort((a, b) => a.penalties - b.penalties)[0];
});
State Management and Statistics
// Get client state
console.log("Version:", yukino.version);
console.log("Ready:", yukino.isReady);
console.log("Players:", yukino.players.size);
console.log("Nodes:", yukino.nodes.size);
console.log("Ideal node:", yukino.idealNode?.name);
// Get detailed Lavalink stats
const stats = yukino.getLavaStats();
console.log("Total players:", stats.players);
console.log("Playing players:", stats.playingPlayers);
console.log("Memory usage:", {
used: `${Math.round(stats.memory.used / 1024 / 1024)} MB`,
allocated: `${Math.round(stats.memory.allocated / 1024 / 1024)} MB`,
free: `${Math.round(stats.memory.free / 1024 / 1024)} MB`,
});
console.log("CPU usage:", {
cores: stats.cpu.cores,
systemLoad: `${Math.round(stats.cpu.systemLoad * 100)}%`,
lavalinkLoad: `${Math.round(stats.cpu.lavalinkLoad * 100)}%`,
});
console.log("Uptime:", `${Math.round(stats.uptime / 1000 / 60)} minutes`);
// Get stats for individual nodes
Object.entries(stats.nodeStats).forEach(([nodeName, nodeStats]) => {
console.log(`Node ${nodeName} stats:`, {
players: nodeStats.players,
playingPlayers: nodeStats.playingPlayers,
cpuLoad: `${Math.round(nodeStats.cpu.lavalinkLoad * 100)}%`,
});
});