A lightweight, robust, and plugin-ready Lavalink client (v3 & v4) for Node.js.

📄 Documentation | 💬 Discord Support | 📦 NPM

📚 Documentation

Check out our comprehensive documentation for detailed guides, API reference, and examples.

🤖 Example Bot

Looking for a ready-to-use implementation? Check out our official music bot example. It's fully featured with slash commands and beautiful music cards.

🎨 Visuals (FrameCard)

Enhance your bot's user experience with @ramkrishna-js/framecard. It's perfectly integrated with Framelink to generate beautiful music cards for every track.

npm install @ramkrishna-js/framecard

Features

• Universal Support: Seamlessly works with Lavalink v3 and v4.
• Multi-Platform: Built-in support for YouTube, Spotify, Apple Music, Deezer, and more.
• Performance: Optimized for speed with minimal memory footprint.
• Advanced Queue: Smart queue system with shuffling, moving, and track manipulation.
• Aggressive Autoplay: Intelligent recommendation system for continuous playback.
• Extensible: Robust plugin system to customize your experience.
• Type-Safe: Written entirely in TypeScript for a superior DX.

Installation

npm install @ramkrishna-js/framelink

Quick Start

Initializing the Manager

import { LavalinkManager } from '@ramkrishna-js/framelink';

const manager = new LavalinkManager({
    nodes: [
        {
            host: 'localhost',
            port: 2333,
            password: 'youshallnotpass',
            version: 'v4' // or 'v3'
        }
    ],
    send: (guildId, payload) => {
        // Your library's send logic (Discord.js, Eris, etc.)
    }
});

manager.init('YOUR_BOT_ID');

Creating a Player & Playing

const player = manager.createPlayer({
    guildId: 'GUILD_ID',
    voiceChannelId: 'VOICE_CHANNEL_ID',
    textChannelId: 'TEXT_CHANNEL_ID',
    autoplay: true
});

// Search for a track
const res = await manager.search('Never Gonna Give You Up', 'yt');

// Add to queue and play
player.queue.add(res.tracks[0]);
player.play();

Event Handling

manager.on('nodeConnect', (node) => {
    console.log(`Node ${node.options.host} connected!`);
});

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

manager.on('queueEnd', (player) => {
    console.log(`Queue ended for guild ${player.guildId}`);
});

Player & Queue Controls

FrameLink provides comprehensive control over your music session:

Player Methods

• player.pause(state: boolean) - Pause or resume playback.
• player.resume() - Alias for player.pause(false).
• player.skip() - Skip the current track.
• player.previous() - Play the previous track.
• player.seek(position: number) - Seek to a specific position (ms).
• player.setVolume(volume: number) - Set the player volume (0-1000).
• player.setFilters(filters: any) - Apply Lavalink filters.
• player.connect(options) - Join a voice channel.
• player.disconnect() - Leave a voice channel.

Queue Methods

• player.queue.add(track | track[]) - Add tracks to the queue.
• player.queue.remove(index) - Remove a track by index.
• player.queue.move(from, to) - Move a track within the queue.
• player.queue.shuffle() - Randomize the queue order.
• player.queue.clear() - Clear all tracks from the queue.
• player.queue.skipTo(index) - Skip directly to a specific track index.
• player.queue.removeDuplicates() - Remove duplicate tracks from the queue.

Aggressive Autoplay

Enable autoplay: true in your player options to automatically play related tracks when the queue ends. FrameLink uses an aggressive strategy to ensure the music never stops by fetching recommendations based on the previous track's source.

Supported Platforms

FrameLink supports any platform compatible with Lavalink and its plugins (like LavaSrc):

• YouTube / YouTube Music
• Spotify
• Apple Music
• Deezer
• SoundCloud
• Twitch
• HTTP Links

Plugins

FrameLink is built with extensibility in mind. You can easily create and load plugins to extend the manager's functionality.

import { Plugin } from '@ramkrishna-js/framelink';

class MyCustomPlugin extends Plugin {
    name = 'MyPlugin';
    load(manager) {
        super.load(manager);
        console.log('Plugin loaded!');
    }
    unload() {}
}

const manager = new LavalinkManager({
    // ... other options
    plugins: [new MyCustomPlugin()]
});

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please see CONTRIBUTING.md for more details.

License

Distributed under the MIT License. See LICENSE for more information.

Built with ❤️ by Ramkrishna