Table of Contents
| Property | Type | Description |
|---|
autoplayTries | number | The number of autoplay attempts before emitting queueEnd. |
bands | number[] | The 15-band equalizer values. Defaults to 0.0 for each band. |
clusterId | number | The cluster ID this player belongs to. |
dynamicRepeat | boolean | Whether dynamic repeat (shuffle-on-loop) is enabled. |
dynamicRepeatIntervalMs | number | null | The interval in milliseconds for dynamic repeat. null if disabled. |
filters | Filters | The audio filters applied to this player. |
guildId | string | The guild ID this player belongs to. |
isAutoplay | boolean | Whether autoplay is enabled. |
manager | Manager | The Manager instance. |
node | Node | The Node this player is connected to. |
nowPlayingMessage | AnyMessage | undefined | The now playing message, if set. |
options | PlayerOptions | The resolved options for this player. |
paused | boolean | Whether the player is currently paused. |
playing | boolean | Whether the player is currently playing. |
position | number | The current playback position in milliseconds. |
queue | IQueue | The queue for this player. |
queueRepeat | boolean | Whether queue repeat is enabled. |
state | StateTypes | The current connection state of the player. |
textChannelId | string | null | The text channel ID this player is bound to. |
trackRepeat | boolean | Whether track repeat is enabled. |
voiceChannelId | string | null | The voice channel ID this player is connected to. |
voiceState | VoiceState | The current voice state for this player. |
volume | number | The current volume level. Range: 0–1000 (or 0–500 in filter mode). |
new Player(options: PlayerOptions)
| Parameter | Type | Description | Optional |
|---|
options | PlayerOptions | The player options. | |
async autoMoveNode(): Promise<Player | void>
Moves the player to the most suitable available node as determined by useableNode.
| Type | Description |
|---|
Promise<Player | void> | The player after being moved, or void. |
Connects the player to the configured voice channel. Throws if no voiceChannelId has been set.
async deleteSponsorBlock(): Promise<void>
Removes all active SponsorBlock segment categories for this player.
async destroy(disconnect?: boolean): Promise<boolean>
Destroys the player, clears the queue, and removes it from the manager. Optionally disconnects from the voice channel first.
| Parameter | Type | Description | Optional |
|---|
disconnect | boolean | Whether to disconnect from the voice channel first. Defaults to true. | |
| Type | Description |
|---|
| Promise<boolean> | true if the player was successfully removed from the manager. |
async disconnect(): Promise<this>
Disconnects the player from the voice channel, optionally pausing playback if pauseOnDisconnect is enabled.
| Type | Description |
|---|
Promise<this> | The player instance. |
Retrieves a custom data value by key.
| Parameter | Type | Description | Optional |
|---|
key | string | The key to retrieve. | |
| Type | Description |
|---|
| T | The value cast to the specified type, or undefined. |
Requires the LavaLyrics plugin on the player's node.
async getCurrentLyrics(skipTrackSource?: boolean): Promise<Lyrics>
Fetches lyrics for the currently playing track. Returns an empty lyrics object if none are found.
| Parameter | Type | Description | Optional |
|---|
skipTrackSource | boolean | Whether to skip the track's source URL. Defaults to false. | |
| Type | Description |
|---|
Promise<Lyrics> | The lyrics, or an empty lyrics object. |
getData(): Record<string, unknown>
Returns the full internal data store for this player.
| Type | Description |
|---|
| Record<string, unknown> | The raw data object. |
getDynamicLoopIntervalPublic(): NodeJS.Timeout | null
Returns the active dynamic repeat interval handle, or null if dynamic repeat is not enabled.
| Type | Description |
|---|
| NodeJS.Timeout | null | The interval handle, or null. |
async getRecommendedTracks(track: Track): Promise<Track[]>
Returns a list of recommended tracks based on the given track.
| Parameter | Type | Description | Optional |
|---|
track | Track | The track to base recommendations on. | |
| Type | Description |
|---|
Promise<Track[]> | The recommended tracks. |
getSerializableData(): Record<string, unknown>
Returns a shallow copy of the internal data store, safe for serialization.
| Type | Description |
|---|
| Record<string, unknown> | A copy of the player's internal data. |
async getSponsorBlock(): Promise<SponsorBlockSegment[]>
Returns the active SponsorBlock segment categories for this player.
static init(manager: Manager): void
Initializes the static Manager reference used by all Player instances. Called internally by the manager.
| Parameter | Type | Description | Optional |
|---|
manager | Manager | The manager instance. | |
async moveNode(identifier: string): Promise<Player>
Migrates the player to a different node, transferring voice state, position, volume, and filters.
| Parameter | Type | Description | Optional |
|---|
identifier | string | The identifier of the target node. | |
| Type | Description |
|---|
Promise<Player> | The player after being moved. |
async pause(pause: boolean): Promise<this>
Pauses or resumes the player.
| Parameter | Type | Description | Optional |
|---|
pause | boolean | true to pause, false to resume. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
async play(): Promise<Player>
async play(track: Track): Promise<Player>
async play(options: PlayOptions): Promise<Player>
async play(track: Track, options: PlayOptions): Promise<Player>
Starts playback. If a track is provided it becomes the current track. If only options are provided they apply to the current queue track.
| Parameter | Type | Description | Optional |
|---|
track | Track | The track to play. | |
options | PlayOptions | Playback options (start time, end time, etc.) | |
| Type | Description |
|---|
Promise<Player> | The player instance. |
async previous(addBackToQueue?: boolean): Promise<this>
Plays the most recent track from the previous queue. Optionally re-inserts the current track at the front of the queue.
| Parameter | Type | Description | Optional |
|---|
addBackToQueue | boolean | Whether to re-add the current track to the front of the queue. Defaults to true. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
Only available when the player is connected to a NodeLink node.
async removeVoiceReceiver(): Promise<void>
Closes and removes the voice receiver WebSocket connection for this player.
async restart(): Promise<Player>
Restarts the currently playing track from position 0. If no track is current but the queue has tracks, plays the next one.
| Type | Description |
|---|
Promise<Player> | The player instance. |
async search<T = unknown>(query: string | SearchQuery, requester?: T): Promise<SearchResult>
Shortcut for Manager#search(). Searches for tracks using the manager.
| Parameter | Type | Description | Optional |
|---|
query | string | SearchQuery | The search query or URL. | |
requester | T | The user who requested the search. | |
async seek(position: number): Promise<this>
Seeks to the specified position in the current track. The position is clamped to the valid range [0, duration].
| Parameter | Type | Description | Optional |
|---|
position | number | The position in milliseconds to seek to. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
set(key: string, value: unknown): void
Stores a custom value on the player by key. Retrievable with get().
| Parameter | Type | Description | Optional |
|---|
key | string | The key to store the value under. | |
value | unknown | The value to store. | |
setAutoplay<T = unknown>(autoplayState: boolean, AutoplayUser?: T, tries?: number): this
Enables or disables autoplay. When enabled, the player will attempt to find and queue a recommended track when the queue ends.
| Parameter | Type | Description | Optional |
|---|
autoplayState | boolean | Whether to enable autoplay. | |
AutoplayUser | T | The bot user object used as the requester for autoplay tracks. Required if enabling. | |
tries | number | Max recommendation attempts before giving up. Defaults to 3. | |
| Type | Description |
|---|
this | The player instance. |
async setDynamicRepeat(repeat: boolean, ms: number): Promise<this>
Enables or disables dynamic repeat, which shuffles and re-queues tracks on an interval.
| Parameter | Type | Description | Optional |
|---|
repeat | boolean | Whether to enable dynamic repeat. | |
ms | number | The shuffle interval in milliseconds. Ignored when disabling. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
setNowPlayingMessage(message: AnyMessage): AnyMessage
Sets the now playing message on the player. Also stored internally via set().
| Parameter | Type | Description | Optional |
|---|
message | AnyMessage | The message to set. | |
| Type | Description |
|---|
AnyMessage | The now playing message. |
setQueueRepeat(repeat: boolean): this
Enables or disables queue repeat. Disables trackRepeat and dynamicRepeat if currently active.
| Parameter | Type | Description | Optional |
|---|
repeat | boolean | Whether to enable queue repeat. | |
| Type | Description |
|---|
this | The player instance. |
async setSponsorBlock(segments?: SponsorBlockSegment[]): Promise<void>
Sets the active SponsorBlock segment categories for this player. Defaults to [Sponsor, SelfPromo] if not provided.
| Parameter | Type | Description | Optional |
|---|
segments | SponsorBlockSegment[] | The segment categories to activate. Defaults to [Sponsor, SelfPromo]. | |
setTextChannelId()
setTextChannelId(channel: string): this
Updates the text channel ID for this player.
| Parameter | Type | Description | Optional |
|---|
channel | string | The new text channel ID. | |
| Type | Description |
|---|
this | The player instance. |
setTrackRepeat(repeat: boolean): this
Enables or disables track repeat. Disables queueRepeat and dynamicRepeat if currently active.
| Parameter | Type | Description | Optional |
|---|
repeat | boolean | Whether to enable track repeat. | |
| Type | Description |
|---|
this | The player instance. |
setVoiceChannelId(channel: string): this
Updates the voice channel ID and reconnects the player to the new channel.
| Parameter | Type | Description | Optional |
|---|
channel | string | The new voice channel ID. | |
| Type | Description |
|---|
this | The player instance. |
async setVolume(volume: number): Promise<this>
Sets the player volume. Valid range is 0–1000, or 0–500 when applyVolumeAsFilter is enabled.
| Parameter | Type | Description | Optional |
|---|
volume | number | The new volume level. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
Only available when the player is connected to a NodeLink node.
async setupVoiceReceiver(): Promise<void>
Opens a WebSocket connection to the NodeLink voice receiver endpoint for this player.
async stop(amount?: number): Promise<this>
Stops the current track. If amount is greater than 1, also removes that many tracks from the front of the queue before stopping.
| Parameter | Type | Description | Optional |
|---|
amount | number | The number of upcoming tracks to also remove from the queue. | |
| Type | Description |
|---|
Promise<this> | The player instance. |
async updateVoice(): Promise<void>
Sends the current voice state (token, endpoint, session ID, channel ID) to the Lavalink node. Called automatically after voice state updates.