High-performance, minimal Lavalink client for Discord.js

npm install @pappu100/oneplayer

⚡ Why OnePlayer?

| Feature | Description | |:-------:|:------------| | 🚀 | Ultra-low latency - Optimized for performance | | 🎯 | Minimal footprint - Only essential dependencies | | 🎵 | Multi-source - YouTube, Spotify, SoundCloud, Apple Music | | 🎛️ | Audio filters - Equalizer, Karaoke, Timescale, and more | | 🔄 | Loop modes - Track, Queue, or None | | 📦 | Queue management - Advanced queue operations | | 🔌 | Multiple nodes - Load balancing support |

📦 Installation

npm install @pappu100/oneplayer

Requirements:

• Node.js 18.0.0 or newer
• Discord.js 14.0.0 or newer
• A running Lavalink server

🚀 Quick Start

const { Client, GatewayIntentBits } = require('discord.js');
const { OnePlayer } = require('@pappu100/oneplayer');

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

const oneplayer = new OnePlayer(client, [
  {
    name: 'main',
    host: 'localhost',
    port: 2333,
    password: 'youshallnotpass',
    secure: false,
    restVersion: 'v4'
  },
], {
  send: (guildId, payload) => {
    const guild = client.guilds.cache.get(guildId);
    if (guild) guild.shard.send(payload);
  },
  defaultSearchPlatform: 'ytmsearch',
  restVersion: 'v4',
  defaultVolume: 100,
});

client.on('ready', () => {
  oneplayer.init(client.user.id);
  console.log('✅ Bot ready!');
});

client.on('raw', (packet) => {
  oneplayer.updateVoiceState(packet);
});

client.login('YOUR_BOT_TOKEN');

🎵 Playing Music

// Create player
const player = oneplayer.createConnection({
  guildId: message.guild.id,
  voiceChannel: message.member.voice.channel.id,
  textChannel: message.channel.id,
  deaf: true,
});

// Search and play
const result = await oneplayer.resolve({
  query: 'never gonna give you up',
  requester: message.author,
});

if (result.tracks.length) {
  player.queue.add(result.tracks[0]);
  await player.play();
}

🎛️ Audio Filters

// Presets
await player.filters.setBassBoost(0.5);
await player.filters.setNightcore();
await player.filters.setVaporwave();
await player.filters.set8D();

// Custom filters
await player.filters.setEqualizer([
  { band: 0, gain: 0.5 },
  { band: 1, gain: 0.3 },
]);

await player.filters.setTimescale(true, {
  speed: 1.2,
  pitch: 1.0,
  rate: 1.0,
});

await player.filters.setKaraoke(true, {
  level: 1.0,
  monoLevel: 1.0,
  filterBand: 220.0,
  filterWidth: 100.0,
});

// Clear all filters
await player.filters.clearFilters();

� Loop Modes

player.setLoop('none');   // No loop
player.setLoop('track');  // Loop current track
player.setLoop('queue');  // Loop entire queue

📋 Queue Management

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

// Queue operations
player.queue.shuffle();
player.queue.clear();
player.queue.remove(0);
player.queue.move(0, 5);
player.queue.swap(0, 1);

// Get queue info
console.log(player.queue.size);
console.log(player.queue.totalDuration);
console.log(player.queue.formattedDuration);

� Player Control

// Playback control
await player.play();
await player.pause(true);
await player.stop();
await player.skip();

// Volume control
await player.setVolume(100); // 0-200

// Seek
await player.seek(30000); // 30 seconds

// Get current position
const position = player.currentPosition;

// Check player state
if (player.isIdle) {
  console.log('Player is idle');
}

📡 Events

OnePlayer supports both player-level and global-level event listening for maximum flexibility.

Global Events (OnePlayer Instance)

Listen to events from all players globally:

// Track events - fired for all players
oneplayer.on('trackStart', (player, track) => {
  console.log(`Now playing: ${track.info.title} in guild ${player.guildId}`);
});

oneplayer.on('trackEnd', (player, track, payload) => {
  console.log(`Track ended: ${payload.reason} in guild ${player.guildId}`);
});

oneplayer.on('trackError', (player, track, payload) => {
  console.error('Track error:', payload.exception);
});

oneplayer.on('trackStuck', (player, track, payload) => {
  console.error('Track stuck:', payload);
});

// Player lifecycle events
oneplayer.on('playerCreate', (player) => {
  console.log(`Player created: ${player.guildId}`);
});

oneplayer.on('playerDestroy', (player) => {
  console.log(`Player destroyed: ${player.guildId}`);
});

// Node events
oneplayer.on('nodeCreate', (node) => {
  console.log(`Node created: ${node.name}`);
});

oneplayer.on('nodeDestroy', (node) => {
  console.log(`Node destroyed: ${node.name}`);
});

Player-Specific Events

Listen to events from a specific player:

const player = oneplayer.createConnection({ /* ... */ });

// These events only fire for this specific player
player.on('trackStart', (player, track) => {
  console.log(`Track started: ${track.info.title}`);
});

player.on('trackEnd', (player, track, payload) => {
  console.log(`Track ended: ${payload.reason}`);
});

player.on('trackError', (player, track, payload) => {
  console.error('Track error:', payload.exception);
});

Event Compatibility

For backward compatibility, all track events (trackStart, trackEnd, trackError, trackStuck, socketClosed) are emitted on both:

• The specific player instance
• The global OnePlayer instance

This means you can listen on either level depending on your needs:

• Use global events for centralized logging or handling across all guilds
• Use player-specific events for guild-specific functionality

🔧 Configuration Options

const oneplayer = new OnePlayer(client, nodes, {
  // Required: Send voice state to Discord
  send: (guildId, payload) => { /* ... */ },
  
  // Search settings
  defaultSearchPlatform: 'ytmsearch', // or 'ytsearch', 'scsearch'
  restVersion: 'v4',                  // or 'v3'
  
  // Player settings
  defaultVolume: 100,                 // 0-200
  connectionTimeout: 10000,           // ms
  
  // Node settings
  reconnectTimeout: 3000,             // ms
  reconnectTries: 3,                  // attempts
  
  // Debug
  debug: false,
});

Full documentation is available at oneplayer.js.org

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ by the Community One