{"id":13074,"library":"discord-player","title":"Discord Player","description":"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.","status":"active","version":"7.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/Androz2091/discord-player","tags":["javascript","music","player","bot","framework","discord","volume","queue","discord.js","typescript"],"install":[{"cmd":"npm install discord-player","lang":"bash","label":"npm"},{"cmd":"yarn add discord-player","lang":"bash","label":"yarn"},{"cmd":"pnpm add discord-player","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for extracting metadata and streams from various audio sources (e.g., YouTube, Spotify).","package":"@discord-player/extractor","optional":false},{"reason":"Core dependency for media processing and playback handling.","package":"mediaplex","optional":false}],"imports":[{"note":"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.","wrong":"const { Player } = require('discord-player');","symbol":"Player","correct":"import { Player } from 'discord-player';"},{"note":"Queue is a named export, not a default export. Ensure correct destructuring.","wrong":"import Queue from 'discord-player';","symbol":"Queue","correct":"import { Queue } from 'discord-player';"},{"note":"The hooks API, including `useQueue`, is exported directly from the main package since recent v6 updates, and remains so in v7.","wrong":"import { useQueue } from 'discord-player/hooks';","symbol":"useQueue","correct":"import { useQueue } from 'discord-player';"},{"note":"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.","wrong":"import { Track } from 'discord-player';","symbol":"Track","correct":"import type { Track } from 'discord-player';"}],"quickstart":{"code":"import { Client, GatewayIntentBits } from 'discord.js';\nimport { Player, QueryType } from 'discord-player';\n\nconst client = new Client({\n    intents: [\n        GatewayIntentBits.Guilds,\n        GatewayIntentBits.GuildVoiceStates,\n        GatewayIntentBits.MessageContent // Required for reading commands\n    ]\n});\n\nconst player = new Player(client);\n\n// Load extractors (e.g., YouTube, Spotify, SoundCloud)\nplayer.extractors.loadDefault();\n\nclient.on('ready', () => {\n    console.log(`Bot logged in as ${client.user?.tag}`);\n});\n\nclient.on('messageCreate', async (message) => {\n    if (message.author.bot || !message.guild || !message.content.startsWith('!play ')) return;\n\n    const voiceChannel = message.member?.voice.channel;\n    if (!voiceChannel) {\n        return message.reply('You need to be in a voice channel to play music!');\n    }\n\n    const query = message.content.substring(6).trim();\n\n    try {\n        const { track } = await player.play(voiceChannel, query, {\n            nodeOptions: {\n                metadata: message.channel,\n                leaveOnEmpty: true,\n                leaveOnEnd: true,\n                leaveOnStop: true\n            },\n            // Automatically detects query type, but explicit is safer\n            // You might need to install `@discord-player/extractor` for specific sources.\n            searchEngine: QueryType.Auto\n        });\n\n        message.reply(`Playing ${track.title} by ${track.author}`);\n    } catch (e) {\n        console.error(e);\n        await message.reply(`Error playing track: ${(e as Error).message}`);\n    }\n});\n\nclient.login(process.env.DISCORD_BOT_TOKEN ?? '');","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the official migration guide for v7 (discord-player.js.org/docs/migrating/migrating_to_v7) to update your bot's codebase.","message":"Version 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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure you have `@discord-player/extractor` installed. For specific sources, check the discord-player documentation for required plugins or `player.extractors.loadDefault()`.","message":"discord-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.","severity":"gotcha","affected_versions":">=6.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Always check the `discord-player` documentation and release notes for recommended `discord.js` versions. Keep both packages updated in tandem.","message":"Discord'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.","severity":"gotcha","affected_versions":">=6.0.0"},{"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.","message":"When 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`.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to call `player.play` without a valid `voiceChannel` object, or `player` was not initialized correctly.","error":"TypeError: Cannot read properties of undefined (reading 'play')"},{"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.","cause":"The `ffmpeg` executable is not found in the system's PATH or explicitly specified.","error":"Error: FFmpeg/FFprobe not found!"},{"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).","cause":"The provided URL is not supported by any loaded extractor, or the necessary extractor is not installed/loaded.","error":"Error: No extractor was able to extract the given url"},{"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.","cause":"Attempting to use CommonJS `require()` syntax in a project configured for ES Modules (`\"type\": \"module\"` in `package.json`).","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}