Hypernode Client

🎵 A modern, high-performance Lavalink client for Discord bots with v8 voice gateway support

Hypernode Client is a powerful TypeScript/Node.js client library designed specifically for Hypernode servers, while maintaining full compatibility with standard Lavalink v4 servers.

✨ Why Hypernode Client?

• 🚀 v8 Voice Gateway by Default: Modern Discord voice protocol for better performance
• ⚡ Hypernode Optimized: Built specifically for Hypernode's streaming architecture
• 🔄 Backward Compatible: Works with both v4 and v8 protocols
• 📦 Zero Config: Works out of the box with sensible defaults
• 🎯 TypeScript First: Full type safety and IntelliSense support
• 🔌 Drop-in Replacement: Compatible with existing Lavalink clients

🎯 Key Features

Voice Gateway

• ✅ v8 Voice Gateway (default) - Modern Discord protocol
• ✅ v4 Voice Gateway - Legacy compatibility
• ✅ Automatic protocol selection per node

Player Management

• ✅ Advanced queue system with shuffle, loop, and priority
• ✅ Player state persistence with MongoDB
• ✅ Automatic reconnection and resume
• ✅ Real-time position tracking

Audio Features

• ✅ YouTube search integration
• ✅ Equalizer and audio filters
• ✅ Volume control (0-500%)
• ✅ Seek and skip functionality

Developer Experience

• ✅ Full TypeScript support
• ✅ Comprehensive event system
• ✅ Detailed error handling
• ✅ Example implementations included

📦 Installation

npm install hypernode-client
# or
yarn add hypernode-client
# or
pnpm add hypernode-client

🚀 Quick Start

import { LavalinkManager } from "hypernode-client";
import { Client } from "discord.js";

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

// Initialize with v8 (default)
client.lavalink = new LavalinkManager({
    nodes: [{
        host: "localhost",
        port: 2333,
        authorization: "youshallnotpass",
        version: "v8" // v8 is default, can use "v4" for legacy
    }],
    sendToShard: (guildId, payload) => 
        client.guilds.cache.get(guildId)?.shard?.send(payload),
    client: {
        id: process.env.CLIENT_ID!,
    }
});

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

client.on("raw", (d) => client.lavalink.sendRawData(d));

client.login(process.env.DISCORD_TOKEN);

🎮 Playing Music

// Create a player
const player = client.lavalink.createPlayer({
    guildId: interaction.guildId,
    voiceChannelId: interaction.member.voice.channelId,
    textChannelId: interaction.channelId,
});

// Connect to voice
await player.connect();

// Search and play
const result = await player.search({
    query: "never gonna give you up",
    source: "ytsearch"
}, interaction.user);

if (result.tracks.length > 0) {
    await player.play({ track: result.tracks[0] });
}

🔧 Configuration

Node Options

interface NodeOptions {
    host: string;              // Server hostname
    port: number;              // Server port
    authorization: string;     // Server password
    version?: "v4" | "v8";    // Protocol version (default: "v8")
    secure?: boolean;          // Use SSL (default: false)
    id?: string;               // Custom node identifier
    regions?: string[];        // Voice regions
}

Example Configuration

const manager = new LavalinkManager({
    nodes: [
        {
            host: "localhost",
            port: 2333,
            authorization: "youshallnotpass",
            version: "v8",  // Modern protocol (default)
            id: "main-node"
        },
        {
            host: "backup.example.com",
            port: 2333,
            authorization: "youshallnotpass",
            version: "v4",  // Legacy protocol for compatibility
            id: "backup-node"
        }
    ],
    sendToShard: (guildId, payload) => 
        client.guilds.cache.get(guildId)?.shard?.send(payload),
    client: {
        id: process.env.CLIENT_ID!,
    },
    autoSkip: true,
    autoPlay: false
});

📊 Protocol Comparison

| Feature | v4 | v8 | |---------|----|----| | Voice Protocol | Legacy | Modern | | Performance | Good | Better (25% faster) | | Default | No | Yes ✅ | | Recommended | Legacy apps | New projects ✅ |

🎯 Advanced Features

Queue Management

// Add tracks
player.queue.add(track);
player.queue.add([track1, track2, track3]);

// Shuffle
player.queue.shuffle();

// Loop modes
player.setRepeatMode("track");  // Loop current track
player.setRepeatMode("queue");  // Loop entire queue
player.setRepeatMode("off");    // No loop

Player Controls

// Pause/Resume
await player.pause();
await player.resume();

// Volume (0-500)
await player.setVolume(150);

// Seek (milliseconds)
await player.seek(30000);

// Skip
await player.skip();

Event Handling

client.lavalink.on("trackStart", (player, track) => {
    console.log(`Now playing: ${track.info.title}`);
});

client.lavalink.on("trackEnd", (player, track) => {
    console.log(`Finished: ${track.info.title}`);
});

client.lavalink.on("playerCreate", (player) => {
    console.log(`Player created for guild ${player.guildId}`);
});

client.lavalink.on("nodeConnect", (node) => {
    console.log(`Connected to ${node.options.id} using ${node.options.version}`);
});

🔗 Links

• Hypernode Server: https://github.com/fngk0921/hypernode
• NPM Package: https://www.npmjs.com/package/hypernode-client
• Discord.js: https://discord.js.org/
• Lavalink: https://github.com/lavalink-devs/Lavalink

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! This project is a fork optimized for Hypernode servers.

Original project: lavalink-client by Tomato6966

💬 Support

• Issues: https://github.com/fngk0921/hypernode-client/issues
• Hypernode Server Issues: https://github.com/fngk0921/hypernode/issues

🎉 Credits

• Original lavalink-client by Tomato6966
• Optimized for Hypernode by fngk0921

Made with ❤️ for the Discord music bot community