Playable¶

A Playable represents a single audio track. Use Playable.search() to search for tracks.

Playable.search() returns Search, a type alias for list[Playable] | Playlist.

results: revvlink.Search = await revvlink.Playable.search("lofi chill")

if isinstance(results, revvlink.Playlist):
    await player.queue.put_wait(results)
elif results:
    await player.play(results[0])

Guide

See the Tracks & Search Guide for source selection, URL searching, and playlist handling.

Playable ¶

Playable(
    data: TrackPayload,
    *,
    playlist: PlaylistInfo | None = None,
)

The RevvLink Playable object which represents all tracks in RevvLink 3.

ℹNote

You should not construct this class manually.

Supported operations

str(track)The title of this playable.

repr(track)The official string representation of this playable.

track == otherWhether this track is equal to another. Checks both the track encoding and identifier.

encoded `property` ¶

encoded: str

The encoded track string from Lavalink.

Returns:

Type	Description
`str`	The base64 encoded track string.

identifier `property` ¶

identifier: str

The identifier of this track from its source.

E.g. YouTube ID or Spotify ID.

Returns:

Type	Description
`str`	The track identifier.

is_seekable `property` ¶

is_seekable: bool

Whether this track supports seeking.

Returns:

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

author `property` ¶

author: str

The author or artist of this track.

Returns:

Type	Description
`str`	The track author.

length `property` ¶

length: int

The duration of this track in milliseconds.

Returns:

Type	Description
`int`	The track length in ms.

is_stream `property` ¶

is_stream: bool

Whether this track is an ongoing stream.

Returns:

Type	Description
`bool`	True if a stream, False otherwise.

position `property` ¶

position: int

The starting position of this track in milliseconds.

Returns:

Type	Description
`int`	The start position in ms.

title `property` ¶

title: str

The title or name of this track.

Returns:

Type	Description
`str`	The track title.

uri `property` ¶

uri: str | None

The URL to this track.

Returns:

Type	Description
`str \| None`	The track URI, or `None` if not available.

artwork `property` ¶

artwork: str | None

The URL to the artwork for this track.

Returns:

Type	Description
`str \| None`	The artwork URL, or `None` if not available.

isrc `property` ¶

isrc: str | None

The International Standard Recording Code (ISRC) for this track.

Returns:

Type	Description
`str \| None`	The ISRC, or `None` if not available.

source `property` ¶

source: str

The source name for this track.

E.g. "spotify" or "youtube".

Returns:

Type	Description
`str`	The source name.

album `property` ¶

album: Album

The album data associated with this track.

Returns:

Type	Description
class:`Album`	The album information.

artist `property` ¶

artist: Artist

The artist data associated with this track.

Returns:

Type	Description
class:`Artist`	The artist information.

preview_url `property` ¶

preview_url: str | None

The URL to a short preview of this track.

Returns:

Type	Description
`str \| None`	The preview URL, or `None` if not available.

is_preview `property` ¶

is_preview: bool | None

Whether this track is a short preview.

Returns:

Type	Description
`bool \| None`	True if a preview, False otherwise, or `None` if unknown.

playlist `property` ¶

playlist: PlaylistInfo | None

The playlist information if this track part of one.

Returns:

Type	Description
class:`PlaylistInfo` \| None	The playlist info, or `None` if not in a playlist.

recommended `property` ¶

recommended: bool

Whether this track was added via the AutoPlay feature.

Returns:

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

extras `property` `writable` ¶

extras: ExtrasNamespace

Property returning a :class:~revvlink.ExtrasNamespace of extras for this :class:Playable.

You can set this property with a :class:dict of valid :class:str keys to any valid JSON value, or a :class:~revvlink.ExtrasNamespace.

If a dict is passed, it will be converted into an :class:~revvlink.ExtrasNamespace, which can be converted back to a dict with dict(...). Additionally, you can also use list or tuple on :class:~revvlink.ExtrasNamespace.

The extras dict will be sent to Lavalink as the userData field.

⚠Warning

This is only available when using Lavalink 4+ (Non BETA) versions.

Examples:

.. code:: python

    track: revvlink.Playable = revvlink.Playable.search("QUERY")
    track.extras = {"requester_id": 1234567890}

    # later...
    print(track.extras.requester_id)
    # or
    print(dict(track.extras)["requester_id"])

raw_data `property` ¶

raw_data: TrackPayload

The raw data for this Playable received via Lavalink.

You can use this data to reconstruct this Playable object.

Examples:

.. code:: python3

    # For example purposes...
    old_data = track.raw_data

    # Later...
    track: revvlink.Playable = revvlink.Playable(old_data)

search `async` `classmethod` ¶

search(
    query: str,
    /,
    *,
    source: TrackSource
    | str
    | None = TrackSource.YouTubeMusic,
    node: Node | None = None,
) -> Search

Search for a list of :class:~revvlink.Playable or a :class:~revvlink.Playlist, with the given query.

ℹNote

This method differs from revvlink.Pool.fetch_tracks in that it will apply a relevant search prefix for you when a URL is not provided. This prefix can be controlled via the source keyword argument.

ℹNote

This method of searching is preferred over, revvlink.Pool.fetch_tracks.

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to search tracks for. If this is not a URL based search, this method will provide an appropriate search prefix based on what is provided to the `source` keyword only parameter, or it's default. If this query is a URL, a search prefix will not be used.	required
`source`	`TrackSource \| str \| None`	This parameter determines which search prefix to use when searching for tracks. If `None` is provided, no prefix will be used, however this behaviour is default regardless of what is provided when a URL is found. For basic searches, E.g. YouTube, YouTubeMusic and SoundCloud, see: :class:`revvlink.TrackSource`. Otherwise, a `str` may be provided for plugin based searches, E.g. "spsearch:" for the LavaSrc Spotify based search. Defaults to :attr:`revvlink.TrackSource.YouTubeMusic` which is equivalent to "ytmsearch:".	`YouTubeMusic`
`node`	`Node \| None`	An optional :class:`~revvlink.Node` to use when searching for tracks. Defaults to `None`, which uses the :class:`~revvlink.Pool`'s automatic node selection.	`None`

Returns:

Type	Description
class:`revvlink.Search`	A list of [:class:`Playable`] or a [:class:`Playlist`].

Raises:

Type	Description
`LavalinkLoadException`	Exception raised when Lavalink fails to load results based on your query.

Examples:

python3

# Search for tracks, with the default "ytsearch:" prefix.
tracks: revvlink.Search = await revvlink.Playable.search("Ocean Drive")
if not tracks:
    # No tracks were found...
    ...

# Search for tracks, with a URL.
tracks: revvlink.Search = await revvlink.Playable.search("https://www.youtube.com/watch?v=KDxJlW6cxRk")
...

# Search for tracks, using Spotify and the LavaSrc Plugin.
tracks: revvlink.Search = await revvlink.Playable.search(
    "4b93D55xv3YCH5mT4p6HPn", source="spsearch"
)
...

# Search for tracks, using Spotify and the LavaSrc Plugin, with a URL.
tracks: revvlink.Search = await revvlink.Playable.search("https://open.spotify.com/track/4b93D55xv3YCH5mT4p6HPn")
...

# Search for a playlist, using Spotify and the LavaSrc Plugin.
# or alternatively any other playlist URL from another source like YouTube.
tracks: revvlink.Search = await revvlink.Playable.search("https://open.spotify.com/playlist/37i9dQZF1DWXRqgorJj26U")
...

# Set extras on a playlist result.
playlist: revvlink.Playlist = await revvlink.Playable.search("https://open.spotify.com/playlist/37i9dQZF1DWXRqgorJj26U")
playlist.extras = {"requester_id": 1234567890}

# later...
print(track.extras.requester_id)
# or
print(dict(track.extras)["requester_id"])

Playlist ¶

Playlist(data: PlaylistPayload)

The revvlink Playlist container class.

This class is created and returned via both :meth:Playable.search and :meth:revvlink.Pool.fetch_tracks.

It contains various information about the playlist and a list of :class:Playable that can be used directly in :meth:revvlink.Player.play. See below for various supported operations.

⚠Warning

You should not instantiate this class manually, use Playable.search or revvlink.Pool.fetch_tracks instead.

⚠Warning

You can not use .search directly on this class, see: Playable.search.

ℹNote

This class can be directly added to revvlink.Queue identical to Playable. When added, all tracks contained in this playlist, will be individually added to the revvlink.Queue.

Supported operations

str(x)Return the name associated with this playlist.

repr(x)Return the official string representation of this playlist.

x == yCompare the equality of playlist.

len(x)Return an integer representing the amount of tracks contained in this playlist.

x[0]Return a track contained in this playlist with the given index.

x[0:2]Return a slice of tracks contained in this playlist.

for x in yIterate over the tracks contained in this playlist.

reversed(x)Reverse the tracks contained in this playlist.

x in yCheck if a :class:`Playable` is contained in this playlist.

Attributes:

Name	Type	Description
`name`	`str`	The name of this playlist.
`selected`	`int`	The index of the selected track from Lavalink.
`tracks`	list[:class:`Playable`]	A list of :class:`Playable` contained in this playlist.
`type`	`str \| None`	An optional `str` identifying the type of playlist this is. Only available when a plugin is used.
`url`	`str \| None`	An optional `str` to the URL of this playlist. Only available when a plugin is used.
`artwork`	`str \| None`	An optional `str` to the artwork of this playlist. Only available when a plugin is used.
`author`	`str \| None`	An optional `str` of the author of this playlist. Only available when a plugin is used.

extras `property` `writable` ¶

extras: ExtrasNamespace

The extras associated with this :class:Playlist.

This property can be set with a :class:dict of valid :class:str keys to any valid JSON value, or a :class:~revvlink.ExtrasNamespace.

If a dict is passed, it will be converted into an :class:~revvlink.ExtrasNamespace, which can be converted back to a dict with dict(...). Additionally, you can also use list or tuple on :class:~revvlink.ExtrasNamespace.

The extras dict will be sent to Lavalink as the userData field for each track in the playlist.

⚠Warning

This is only available when using Lavalink 4+ (Non BETA) versions.

Examples:

python

playlist: revvlink.Search = revvlink.Playable.search("QUERY")
playlist.extras = {"requester_id": 1234567890}

# later...
print(track.extras.requester_id)
# or
print(dict(track.extras)["requester_id"])

Returns:

Type	Description
class:`~revvlink.ExtrasNamespace`	The playlist extras.

track_extras ¶

track_extras(**attrs: object) -> None

Method which sets attributes to all :class:Playable in this playlist, with the provided keyword arguments.

This is useful when you need to attach state to your :class:Playable, E.g. create a requester attribute.

⚠Warning

If you try to override any existing property of Playable this method will fail.

Parameters:

Name	Type	Description	Default
`**attrs`	`object`	The keyword arguments to set as attribute name=value on each :class:`Playable`.	`{}`

Examples:

.. code:: python3

    playlist.track_extras(requester=ctx.author)

    track: revvlink.Playable = playlist[0]
    print(track.requester)

PlaylistInfo ¶

PlaylistInfo(data: PlaylistPayload)

The revvlink PlaylistInfo container class.

It contains various information about the playlist but does not contain the tracks associated with this playlist.

This class provides information about the original :class:revvlink.Playlist on tracks.

Attributes:

Name	Type	Description
`name`	`str`	The name of this playlist.
`selected`	`int`	The index of the selected track from Lavalink.
`tracks`	`int`	The amount of tracks this playlist originally contained.
`type`	`str \| None`	An optional `str` identifying the type of playlist this is. Only available when a plugin is used.
`url`	`str \| None`	An optional `str` to the URL of this playlist. Only available when a plugin is used.
`artwork`	`str \| None`	An optional `str` to the artwork of this playlist. Only available when a plugin is used.
`author`	`str \| None`	An optional `str` of the author of this playlist. Only available when a plugin is used.

Album ¶

Album(*, data: dict[Any, Any])

Container class representing Album data received via Lavalink.

Attributes:

Name	Type	Description
`name`	`str \| None`	The album name. Could be `None`.
`url`	`str \| None`	The album url. Could be `None`.

Artist ¶

Artist(*, data: dict[Any, Any])

Container class representing Artist data received via Lavalink.

Attributes:

Name	Type	Description
`url`	`str \| None`	The artist url. Could be `None`.
`artwork`	`str \| None`	The artist artwork url. Could be `None`.

Playable¶

Playable ¶

encoded property ¶

identifier property ¶

is_seekable property ¶

author property ¶

length property ¶

is_stream property ¶

position property ¶

title property ¶

uri property ¶

artwork property ¶

isrc property ¶

source property ¶

album property ¶

artist property ¶

preview_url property ¶

is_preview property ¶

playlist property ¶

recommended property ¶

extras property writable ¶

raw_data property ¶

search async classmethod ¶

Playlist ¶

extras property writable ¶

track_extras ¶

PlaylistInfo ¶

Album ¶

Artist ¶

encoded `property` ¶

identifier `property` ¶

is_seekable `property` ¶

author `property` ¶

length `property` ¶

is_stream `property` ¶

position `property` ¶

title `property` ¶

uri `property` ¶

artwork `property` ¶

isrc `property` ¶

source `property` ¶

album `property` ¶

artist `property` ¶

preview_url `property` ¶

is_preview `property` ¶

playlist `property` ¶

recommended `property` ¶

extras `property` `writable` ¶

raw_data `property` ¶

search `async` `classmethod` ¶

extras `property` `writable` ¶