Discord Player

Discord Player is a music framework for Discord bots. Manage queues, tracks, playback, filters, and events while Remedia handles audio and Discord voice.

This README describes the v8 development branch. For v7, use the documentation matching your installed version.

Install

Node.js 22.18+ and ESM are required. To start a new bot, generate a project:

npm create music-bot@dev my-bot

To add Discord Player to an existing project, install the dev tag (npm's latest is still v7). For embedded playback:

pnpm add discord-player@dev discord.js @remedia/node

Install FFmpeg 9 shared libraries on the machine running audio. Remote-only bot processes do not need FFmpeg locally.

Create a player

import { Client, Events, GatewayIntentBits } from 'discord.js';
import { Player } from 'discord-player';
import { directMedia } from './direct-media.js';

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

const player = new Player({
  nodes: [{ id: 'local', type: 'embedded' }],
  plugins: [directMedia()],
  send(guildId, packet) {
    const guild = client.guilds.cache.get(guildId);
    if (!guild) throw new Error('Guild unavailable');
    return guild.shard.send(packet);
  },
});

client.on('raw', (packet) => player.receive(packet));
client.once(Events.ClientReady, (ready) => {
  void player.initialize(ready.user.id).catch(console.error);
});

The directMedia plugin is defined in the manual setup tutorial. Source plugins supply playable audio. Discord Player does not automatically register a music provider.

Inside your play command, after initialization:

const result = await player.play({ guildId, channelId }, 'https://your-media-host.example/song.mp3');
if (result.track) console.log('Playing', result.track.title);

Replace the example URL with a real audio file.

Playback controls

const queue = player.getQueue(guildId);
if (queue) {
  await queue.node.pause();
  await queue.node.resume();
  await queue.node.setVolume(70);
  await queue.skip();
}

Documentation

• Getting started
• Queues and events
• Source plugins
• Embedded and remote playback
• Migrating from v7
• API reference