The Player class is the core of Discord Player. It manages guild queues, extractors, voice connections, and provides the main API for searching and playing audio.
Constructor Create a new Player instance:
import { Player } from 'discord-player' ; import { Client } from 'discord.js' ; const client = new Client ({ intents: [ 'GuildVoiceStates' , 'Guilds' ] }); const player = new Player ( client , options );
Parameters The Discord.js client instance
Player initialization options Show PlayerInitOptions properties
Voice connection timeout in milliseconds
Time in ms to re-monitor event loop lag
Prevent voice state handler from being overridden
List of extractors to disable querying metadata from
List of extractors to disable streaming from
queryCache
QueryCacheProvider | null
Query cache provider
Skip ffmpeg process when possible
The probe timeout in milliseconds
Configure custom ffmpeg path
Whether to override the fallback context
Properties The unique identifier of this player instance (Snowflake)
The Discord.js client instance
The player initialization options
events
PlayerEventsEmitter<GuildQueueEvents>
The player events channel for queue events
LrcLib client for fetching synced lyrics
The hooks context for using player hooks
streamInterceptor
PlayerStreamInterceptor | null
The stream interceptor instance (if configured)
The version of discord-player (static property)
Methods play() Play a track in a voice channel:
const { track , queue } = await player . play ( channel , 'https://youtube.com/watch?v=...' , { nodeOptions: { metadata: interaction } });
channel
GuildVoiceChannelResolvable
required
The voice channel to play in
The query to search for (can be string, Track, Playlist, SearchResult, Track[], or AudioResource)
options
PlayerNodeInitializerOptions
Initialization options Show PlayerNodeInitializerOptions properties
Options for creating the guild queue
Voice connection configuration
The user who requested this track
Abort signal for cancellation
afterSearch
(result: SearchResult) => Promise<SearchResult>
Callback to modify search result before playing
returns
Promise<PlayerNodeInitializationResult>
Promise resolving with track, queue, extractor, and searchResult
search() Search for tracks:
const result = await player . search ( 'despacito' , { requestedBy: interaction . user , searchEngine: QueryType . YOUTUBE });
Promise resolving with search results
generateStatistics() Generate player statistics:
const stats = player . generateStatistics ();
Object containing player statistics including queues, tracks, uptime, memory usage, and versions
scanDeps() Scan and validate dependencies:
const report = await player . scanDeps (); console . log ( report );
Promise resolving with formatted dependency report
setVoiceStateHandler() Set custom voice state handler:
player . setVoiceStateHandler (( player , queue , oldState , newState ) => { // Custom voice state logic });
handler
VoiceStateHandler
required
The voice state handler function
voiceStateHandler() Get the current voice state handler:
const handler = player . voiceStateHandler ();
The current voice state handler function
createContext() Create a custom hooks context:
const customContext = player . createContext (); await customContext . provide ({ guild: someGuild }, async () => { // Use hooks here const queue = useQueue (); });
Events The Player class emits the following events:
debug Emitted when debug information is available:
player . on ( 'debug' , ( message ) => { console . log ( `[DEBUG] ${ message } ` ); });
error Emitted when an error occurs:
player . on ( 'error' , ( error ) => { console . error ( 'Player error:' , error ); });
voiceStateUpdate Emitted when voice state updates:
player . on ( 'voiceStateUpdate' , ( queue , oldState , newState ) => { console . log ( 'Voice state changed' ); });
Example Complete example with error handling:
import { Player } from 'discord-player' ; import { DefaultExtractors } from '@discord-player/extractor' ; import { Client , GatewayIntentBits } from 'discord.js' ; const client = new Client ({ intents: [ GatewayIntentBits . Guilds , GatewayIntentBits . GuildVoiceStates ] }); const player = new Player ( client , { skipFFmpeg: false , connectionTimeout: 30000 }); // Load extractors await player . extractors . loadMulti ( DefaultExtractors ); // Player events player . on ( 'debug' , ( message ) => console . log ( '[Player]' , message )); player . on ( 'error' , ( error ) => console . error ( '[Player Error]' , error )); // Queue events player . events . on ( 'playerStart' , ( queue , track ) => { queue . metadata . channel . send ( `Now playing: ** ${ track . cleanTitle } **` ); }); player . events . on ( 'error' , ( queue , error ) => { console . error ( 'Queue error:' , error ); queue . metadata . channel . send ( 'An error occurred!' ); }); // Play command await player . context . provide ({ guild: interaction . guild }, async () => { try { const { track } = await player . play ( channel , query , { nodeOptions: { metadata: interaction } }); await interaction . followUp ( `Queued ** ${ track . cleanTitle } **` ); } catch ( error ) { await interaction . followUp ( 'Failed to play track' ); } });