Registry / communication / discord-player

discord-player

JSON →
library7.2.0jsnpmunverified

Discord Player is a comprehensive, feature-rich framework designed to facilitate music commands within Discord bots using discord.js. The current stable version is 7.2.0, with an active release cadence addressing features, bug fixes, and compatibility. Key differentiators include its robust queue management, support for various audio sources via the `@discord-player/extractor` ecosystem, stream interception API for advanced audio processing, a dedicated lyrics API, and a flexible hooks API for simplified state management. Version 7 introduced a significant rewrite focusing on improved architecture and performance, requiring a migration for users upgrading from v6. It supports modern JavaScript/TypeScript development and aims to provide a stable foundation for complex music bot functionalities.

npm install discord-player
INSTALL
IMPORT
SIG · DISCORD-PLAYER
D
discord-player
communicationjavascriptv7.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Player
import { Player } from 'discord-player';
const { Player } = require('discord-player');
discord-player is primarily designed for ESM usage since v7. While CommonJS might work with transpilation, direct `require` can lead to issues without proper configuration.
Queue
import { Queue } from 'discord-player';
import Queue from 'discord-player';
Queue is a named export, not a default export. Ensure correct destructuring.
useQueue
import { useQueue } from 'discord-player';
import { useQueue } from 'discord-player/hooks';
The hooks API, including `useQueue`, is exported directly from the main package since recent v6 updates, and remains so in v7.
Track
import type { Track } from 'discord-player';
import { Track } from 'discord-player';
While `Track` can be imported as a value, it's often used as a type for type hinting, in which case `import type` is preferred for cleaner bundle outputs.

This quickstart initializes a Discord bot, sets up the discord-player, loads default extractors, and demonstrates how to play a song from a user's query when they are in a voice channel. It includes error handling and basic bot setup.

import { Client, GatewayIntentBits } from 'discord.js'; import { Player, QueryType } from 'discord-player'; const client = new Client({ intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates, GatewayIntentBits.MessageContent // Required for reading commands ] }); const player = new Player(client); // Load extractors (e.g., YouTube, Spotify, SoundCloud) player.extractors.loadDefault(); client.on('ready', () => { console.log(`Bot logged in as ${client.user?.tag}`); }); client.on('messageCreate', async (message) => { if (message.author.bot || !message.guild || !message.content.startsWith('!play ')) return; const voiceChannel = message.member?.voice.channel; if (!voiceChannel) { return message.reply('You need to be in a voice channel to play music!'); } const query = message.content.substring(6).trim(); try { const { track } = await player.play(voiceChannel, query, { nodeOptions: { metadata: message.channel, leaveOnEmpty: true, leaveOnEnd: true, leaveOnStop: true }, // Automatically detects query type, but explicit is safer // You might need to install `@discord-player/extractor` for specific sources. searchEngine: QueryType.Auto }); message.reply(`Playing ${track.title} by ${track.author}`); } catch (e) { console.error(e); await message.reply(`Error playing track: ${(e as Error).message}`); } }); client.login(process.env.DISCORD_BOT_TOKEN ?? '');
Debug
Known issues
breakingVersion 7.0.0 introduced a significant rewrite with many breaking changes. The API surface was refactored for improved consistency and performance. Direct upgrades from v6 without consulting the migration guide will likely result in non-functional code.
fix
Refer to the official migration guide for v7 (discord-player.js.org/docs/migrating/migrating_to_v7) to update your bot's codebase.
affects: >=7.0.0
gotchadiscord-player relies heavily on external audio extractors (e.g., for YouTube, Spotify). While `@discord-player/extractor` is a peer dependency, specific extractors might need to be explicitly loaded or installed based on your use case.
fix
Ensure you have `@discord-player/extractor` installed. For specific sources, check the discord-player documentation for required plugins or `player.extractors.loadDefault()`.
affects: >=6.0.0
breakingThe `Player` constructor options, especially `ytdlOptions`, have changed significantly or been removed/relocated in v7. Direct passing of `ytdl-core` options is often handled internally or via specific extractor configurations.
fix
Review the v7 documentation for how to configure audio options. Many previous `ytdlOptions` are now managed by the player or specific extractors, or through stream interceptors.
affects: >=7.0.0
gotchaDiscord's API changes and `discord.js` updates can sometimes introduce compatibility issues. Ensure your `discord.js` version is compatible with the `discord-player` version you are using.
fix
Always check the `discord-player` documentation and release notes for recommended `discord.js` versions. Keep both packages updated in tandem.
affects: >=6.0.0
gotchaWhen playing local files or using certain streaming protocols, ensure the necessary ffmpeg binary is available in your system's PATH or specified in your application's environment. Discord Player often uses `mediaplex` which relies on `ffmpeg`.
fix
Install `ffmpeg` on your system and ensure it's accessible in the environment where your bot runs. On Linux/macOS, use your package manager. For Windows, add it to your PATH.
affects: >=6.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'play')
Attempting to call `player.play` without a valid `voiceChannel` object, or `player` was not initialized correctly.
fix
Ensure the user is in a voice channel and the `voiceChannel` variable is not `null` or `undefined`. Also, verify `new Player(client)` was called and `player.extractors.loadDefault()` is executed before attempting to play.
Error: FFmpeg/FFprobe not found!
The `ffmpeg` executable is not found in the system's PATH or explicitly specified.
fix
Install `ffmpeg` on your system. For example, `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download from the official FFmpeg website and add to PATH on Windows.
Error: No extractor was able to extract the given url
The provided URL is not supported by any loaded extractor, or the necessary extractor is not installed/loaded.
fix
Ensure `@discord-player/extractor` is installed and `player.extractors.loadDefault()` is called. If using a specific source, confirm the corresponding extractor is installed and enabled (e.g., for Spotify, make sure the Spotify extractor is working).
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in a project configured for ES Modules (`"type": "module"` in `package.json`).
fix
Update your imports to use ES Module syntax: `import { Player } from 'discord-player';`. If you must use CommonJS, ensure your `package.json` does not have `"type": "module"` or use a transpiler like Babel.
Upgrade
Version history
7.2.0latest on npm
Audit
Dependencies
@discord-player/extractorrequiredRequired for extracting metadata and streams from various audio sources (e.g., YouTube, Spotify).
mediaplexrequiredCore dependency for media processing and playback handling.
Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
1
Resources
discord-player — npm install discord-player · libregistry