Player¶

Player extends discord.VoiceProtocol. Create one by passing cls=revvlink.Player to channel.connect().

player: revvlink.Player = await channel.connect(cls=revvlink.Player)

Guide

See the Player Guide for playback patterns, state management, and lifecycle examples.

Player ¶

Player(
    client: Client = MISSING,
    channel: Connectable = MISSING,
    *,
    nodes: list[Node] | None = None,
)

Bases: VoiceProtocol

The Player is a :class:discord.VoiceProtocol used to connect your :class:discord.Client to a :class:discord.VoiceChannel.

The player controls the music elements of the bot including playing tracks, the queue, connecting etc. See Also: The various methods available.

ℹNote

Since the Player is a discord.VoiceProtocol, it is attached to the various voice_client attributes in discord.py, including guild.voice_client, ctx.voice_client and interaction.voice_client.

Attributes:

Name	Type	Description
`queue`	:class:`~revvlink.Queue`	The queue associated with this player.
`auto_queue`	:class:`~revvlink.Queue`	The auto_queue associated with this player. This queue holds tracks that are recommended by the AutoPlay feature.
`home`	:class:`discord.TextChannel` \| None	The text channel associated with this player. Used for automated library notifications (e.g., failover messages).

state `property` ¶

state: PlayerBasicState

Property returning a dict of the current basic state of the player.

This property includes the voice_state received via Discord.

Returns:

Type	Description
`PlayerBasicState`

inactive_channel_tokens `property` `writable` ¶

inactive_channel_tokens: int | None

The number of tracks to play before firing the inactivity event.

A channel is considered inactive when no real members (Members other than bots) are in the connected voice channel. On each consecutive track played without a real member in the channel, this token bucket will reduce by 1. After hitting 0, the :func:on_revvlink_inactive_player event will be fired and the token bucket will reset to the set value. The default value for this property is 3.

This property can be set with any valid int or None. If this property is set to <= 0 or None, the check will be disabled.

Setting this property to 1 will fire the :func:on_revvlink_inactive_player event at the end of every track if no real members are in the channel and you have not disconnected the player.

If this check successfully fires the :func:on_revvlink_inactive_player event, it will cancel any waiting :attr:inactive_timeout checks until a new track is played.

The default for every player can be set on :class:~revvlink.Node.

See: :class:~revvlink.Node
See: :func:on_revvlink_inactive_player

⚠Warning

Setting this property will reset the bucket.

Returns:

Type	Description
`int \| None`	The current token limit, or `None` if disabled.

inactive_timeout `property` `writable` ¶

inactive_timeout: int | None

The time in seconds to wait before dispatching the inactivity event.

This property could return None if no time has been set. An inactive player is a player that has not been playing anything for the specified amount of seconds.

Pausing the player while a song is playing will not activate this countdown.
The countdown starts when a track ends and cancels when a track starts.
The countdown will not trigger until a song is played for the first time or this property is reset.
The default countdown for all players is set on :class:~revvlink.Node.

This property can be set with a valid int of seconds to wait before dispatching the :func:on_revvlink_inactive_player event or None to remove the timeout.

⚠Warning

Setting this to a value of 0 or below is the equivalent of setting this property to None.

When this property is set, the timeout will reset, and all previously waiting countdowns are cancelled.

See: :class:~revvlink.Node
See: :func:on_revvlink_inactive_player

Returns:

Type	Description
`int \| None`	The timeout in seconds, or `None` if disabled.

autoplay `property` `writable` ¶

autoplay: AutoPlayMode

The :class:~revvlink.AutoPlayMode the player is currently in.

Returns:

Type	Description
class:`~revvlink.AutoPlayMode`	The current autoplay mode.

node `property` ¶

node: Node

The :class:Node currently associated with this player.

Returns:

Type	Description
class:`Node`	The current node.

guild `property` ¶

guild: Guild | None

The :class:discord.Guild associated with this player.

Returns:

Type	Description
class:`discord.Guild` \| None	The associated guild, or `None` if not connected.

connected `property` ¶

connected: bool

Whether the player is currently connected to a voice channel.

Returns:

Type	Description
`bool`	True if connected, False otherwise.

is_e2ee `property` ¶

is_e2ee: bool

Whether the player is currently using end-to-end encryption (DAVE protocol).

Returns:

Type	Description
`bool`	True if using E2EE, False otherwise.

current `property` ¶

current: Playable | None

Returns the currently playing :class:~revvlink.Playable or None if no track is playing.

volume `property` ¶

volume: int

Returns an int representing the currently set volume, as a percentage.

See: :meth:set_volume for setting the volume.

filters `property` ¶

filters: Filters

Property which returns the :class:~revvlink.Filters currently assigned to the Player.

See: :meth:~revvlink.Player.set_filters for setting the players filters.

paused `property` ¶

paused: bool

Returns the paused status of the player. A currently paused player will return True.

See: :meth:pause and :meth:play for setting the paused status.

ping `property` ¶

ping: int

Returns the ping in milliseconds as int between your connected Lavalink Node and Discord (Players Channel).

Returns -1 if no player update event has been received or the player is not connected.

playing `property` ¶

playing: bool

Returns whether the :class:~Player is currently playing a track and is connected.

Due to relying on validation from Lavalink, this property may in some cases return True directly after skipping/stopping a track, although this is not the case when disconnecting the player.

This property will return True in cases where the player is paused and has a track loaded.

position `property` ¶

position: int

Returns the position of the currently playing :class:~revvlink.Playable in milliseconds.

This property relies on information updates from Lavalink.

In cases there is no :class:~revvlink.Playable loaded or the player is not connected, this property will return 0.

This property will return 0 if no update has been received from Lavalink.

switch_node `async` ¶

switch_node(new_node: Node) -> None

Attempt to switch the current node of the player.

This method initiates a live switch, and all player state will be moved from the current node to the provided node.

⚠Warning

Caution should be used when using this method. If this method fails, your player might be left in a stale state. Consider handling cases where the player is unable to connect to the new node. To avoid stale state in both revvlink and discord.py, it is recommended to disconnect the player when a RuntimeError occurs.

Parameters:

Name	Type	Description	Default
`new_node`	`Node`	A positional only argument of a :class:`Node` instance. This must not be the same as the current node.	required

Raises:

Type	Description
`InvalidNodeException`	The provided node was identical to the players current node.
`RuntimeError`	The player was unable to connect properly to the new node. At this point your player might be in a stale state. Consider trying another node, or :meth:`disconnect` the player.

connect `async` ¶

connect(
    *,
    timeout: float = 10.0,
    reconnect: bool,
    self_deaf: bool = False,
    self_mute: bool = False,
) -> None

⚠Warning

Do not use this method directly on the player. See: discord.VoiceChannel.connect for more details.

Pass the :class:revvlink.Player to cls= in :meth:discord.VoiceChannel.connect.

Raises:

Type	Description
`ChannelTimeoutException`	Connecting to the voice channel timed out.
`InvalidChannelStateException`	You tried to connect this player without an appropriate voice channel.

move_to `async` ¶

move_to(
    channel: VocalGuildChannel | None,
    *,
    timeout: float = 10.0,
    self_deaf: bool | None = None,
    self_mute: bool | None = None,
) -> None

Method to move the player to another channel.

Parameters:

Name	Type	Description	Default
`channel`	`VocalGuildChannel \| None`	The new channel to move to.	required
`timeout`	`float`	The timeout in `seconds` before raising. Defaults to 10.0.	`10.0`
`self_deaf`	`bool \| None`	Whether to deafen when moving. Defaults to `None` which keeps the current setting or `False` if they can not be determined.	`None`
`self_mute`	`bool \| None`	Whether to self mute when moving. Defaults to `None` which keeps the current setting or `False` if they can not be determined.	`None`

Raises:

Type	Description
`ChannelTimeoutException`	Connecting to the voice channel timed out.
`InvalidChannelStateException`	You tried to connect this player without an appropriate guild.

play `async` ¶

play(
    track: Playable,
    *,
    replace: bool = True,
    start: int = 0,
    end: int | None = None,
    volume: int | None = None,
    paused: bool | None = None,
    add_history: bool = True,
    filters: Filters | None = None,
    populate: bool = False,
    max_populate: int = 5,
) -> Playable

Play the provided :class:~revvlink.Playable.

Parameters:

Name	Type	Description	Default
`track`	`Playable`	The track to being playing.	required
`replace`	`bool`	Whether this track should replace the currently playing track, if there is one. Defaults to `True`.	`True`
`start`	`int`	The position to start playing the track at in milliseconds. Defaults to `0` which will start the track from the beginning.	`0`
`end`	`int \| None`	The position to end the track at in milliseconds. Defaults to `None` which means this track will play until the very end.	`None`
`volume`	`int \| None`	Sets the volume of the player. Must be between `0` and `1000`. Defaults to `None` which will not change the current volume. See Also: :meth:`set_volume`	`None`
`paused`	`bool \| None`	Setting this parameter to `True` will pause the player. Setting this parameter to `False` will resume the player if it is currently paused. Setting this parameter to `None` will not change the status of the player. Defaults to `None`.	`None`
`add_history`	`bool`	If this argument is set to `True`, the :class:`~Player` will add this track into the :class:`revvlink.Queue` history, if loading the track was successful. If `False` this track will not be added to your history. This does not directly affect the `AutoPlay Queue` but will alter how `AutoPlay` recommends songs in the future. Defaults to `True`.	`True`
`filters`	`Filters \| None`	An Optional[:class:`~revvlink.Filters`] to apply when playing this track. Defaults to `None`. If this is `None` the currently set filters on the player will be applied.	`None`
`populate`	`bool`	Whether the player should find and fill AutoQueue with recommended tracks based on the track provided. Defaults to `False`. Populate will only search for recommended tracks when the current tracks has been accepted by Lavalink. E.g. if this method does not raise an error. You should consider when you use the `populate` keyword argument as populating the AutoQueue on every request could potentially lead to a large amount of tracks being populated.	`False`
`max_populate`	`int`	The maximum amount of tracks that should be added to the AutoQueue when the `populate` keyword argument is set to `True`. This is NOT the exact amount of tracks that will be added. You should set this to a lower amount to avoid the AutoQueue from being overfilled. This argument has no effect when `populate` is set to `False`. Defaults to `5`.	`5`

Returns:

Type	Description
class:`~revvlink.Playable`	The track that began playing.

pause `async` ¶

pause(value: bool) -> None

Set the paused or resume state of the player.

Parameters:

Name	Type	Description	Default
`value`	`bool`	A bool indicating whether the player should be paused or resumed. True indicates that the player should be `paused`. False will resume the player if it is currently paused.	required

seek `async` ¶

seek(position: int = 0) -> None

Seek to a specific position in the currently playing track.

Parameters:

Name	Type	Description	Default
`position`	`int`	The position to seek to in milliseconds. To restart the song from the beginning, you can disregard this parameter or set position to 0.	`0`

set_filters `async` ¶

set_filters(
    filters: Filters | None = None, /, *, seek: bool = False
) -> None

Set the :class:revvlink.Filters on the player.

Parameters:

Name	Type	Description	Default
`filters`	`Filters \| None`	The filters to set on the player. Could be `None` to reset the currently applied filters. Defaults to `None`.	`None`
`seek`	`bool`	Whether to seek immediately when applying these filters. Seeking uses more resources, but applies the filters immediately. Defaults to `False`.	`False`

set_volume `async` ¶

set_volume(value: int = 100) -> None

Set the player volume.

Parameters:

Name	Type	Description	Default
`value`	`int`	A volume value between 0 and 1000. To reset the player to 100, you can disregard this parameter. Values outside this range will be clamped.	`100`

disconnect `async` ¶

disconnect(**kwargs: Any) -> None

Disconnect the player from the current voice channel and remove it from the :class:~revvlink.Node.

This method will cause any playing track to stop and potentially trigger the following events:

- ``on_revvlink_track_end``
- ``on_revvlink_websocket_closed``

⚠Warning

Please do not re-use a Player instance that has been disconnected, unwanted side effects are possible.

stop `async` ¶

stop(*, force: bool = True) -> Playable | None

An alias to :meth:skip.

See Also: :meth:skip for more information.

skip `async` ¶

skip(*, force: bool = True) -> Playable | None

Stop playing the currently playing track.

Parameters:

Name	Type	Description	Default
`force`	`bool`	Whether the track should skip looping, if :class:`revvlink.Queue` has been set to loop. Defaults to `True`.	`True`

Returns:

Type	Description
class:`~revvlink.Playable` \| None	The currently playing track that was skipped, or `None` if no track was playing.

Player¶

Player ¶

state property ¶

inactive_channel_tokens property writable ¶

inactive_timeout property writable ¶

autoplay property writable ¶

node property ¶

guild property ¶

connected property ¶

is_e2ee property ¶

current property ¶

volume property ¶

filters property ¶

paused property ¶

ping property ¶

playing property ¶

position property ¶

switch_node async ¶

connect async ¶

move_to async ¶

play async ¶

pause async ¶

seek async ¶

set_filters async ¶

set_volume async ¶

disconnect async ¶

stop async ¶

skip async ¶

state `property` ¶

inactive_channel_tokens `property` `writable` ¶

inactive_timeout `property` `writable` ¶

autoplay `property` `writable` ¶

node `property` ¶

guild `property` ¶

connected `property` ¶

is_e2ee `property` ¶

current `property` ¶

volume `property` ¶

filters `property` ¶

paused `property` ¶

ping `property` ¶

playing `property` ¶

position `property` ¶

switch_node `async` ¶

connect `async` ¶

move_to `async` ¶

play `async` ¶

pause `async` ¶

seek `async` ¶

set_filters `async` ¶

set_volume `async` ¶

disconnect `async` ¶

stop `async` ¶

skip `async` ¶