### Manage Audio Filters with Revvlink

Source: https://revvlink.revvlabs.in/api/filters

Demonstrates how to retrieve, modify, and apply audio filters to a player. Includes examples for setting specific filter parameters, resetting individual filters, and clearing all active filters.

```python
import revvlink

# Retrieve and modify filters
filters = player.filters
filters.timescale.set(pitch=1.2, speed=1.2)
await player.set_filters(filters)

# Reset all filters
await player.set_filters()

# Create new filters and apply
filters = revvlink.Filters()
await player.set_filters(filters)

# Set and reset individual filters
filters = player.filters
filters.timescale.set(pitch=1.2, speed=1.1, rate=1)
filters.rotation.set(rotation_hz=0.2)
filters.equalizer.reset()
await player.set_filters(filters)

# Reset specific filter
filters.timescale.reset()
await player.set_filters(filters)

# Reset all filters via instance method
filters.reset()
await player.set_filters(filters)
```

--------------------------------

### GET /fetch_version

Source: https://revvlink.revvlabs.in/api/node

Retrieves the version string of the connected Lavalink node.

```APIDOC
## GET /fetch_version

### Description
Fetches the version string associated with the current Lavalink node.

### Method
GET

### Endpoint
/fetch_version

### Response
#### Success Response (200)
- **version** (str) - The version string of the Lavalink node.

#### Errors
- **LavalinkException**: Error occurred while making the request.
- **NodeException**: Error occurred and the node failed to provide error details.
```

--------------------------------

### GET /fetch_version

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves the version string of the connected Lavalink node.

```APIDOC
## GET /fetch_version

### Description
Fetches the version string associated with the current Lavalink node.

### Method
GET

### Endpoint
/fetch_version

### Response
#### Success Response (200)
- **version** (str) - The version string of the Lavalink node.

#### Errors
- **LavalinkException**: Error occurred while making the request.
- **NodeException**: Request failed and no error information was returned.
```

--------------------------------

### Queue Operations and Attributes

Source: https://revvlink.revvlabs.in/api/queue?q=

Demonstrates common operations and attributes for interacting with a Queue object. This includes checking for items, adding tracks, getting the queue length, peeking at tracks, iterating, checking for track existence, setting tracks at specific indices, deleting tracks, and reversing the queue.

```python
str(queue)
repr(queue)
if queue
queue(track)
len(queue)
queue[1]
for item in queue:
if item in queue
queue[1] = track
del queue[1]
reversed(queue)
```

--------------------------------

### Playable Property Accessors

Source: https://revvlink.revvlabs.in/api/playable?q=

Examples of accessing various metadata and state properties of a Playable track, such as identifiers, source information, and playback attributes.

```python
encoded: str
identifier: str
is_seekable: bool
author: str
length: int
is_stream: bool
position: int
title: str
uri: str | None
artwork: str | None
isrc: str | None
source: str
album: Album
artist: Artist
preview_url: str | None
is_preview: bool | None
playlist: PlaylistInfo | None
recommended: bool
```

--------------------------------

### Play Track with Options (Python)

Source: https://revvlink.revvlabs.in/api/player?q=

Initiates playback of a specified track with various customizable options. Supports replacing the current track, setting start and end positions, adjusting volume, managing player state (paused/resumed), adding to history, applying filters, and populating the auto-queue. Dependencies include the `Playable` and `Filters` types from the `revvlink` library.

```python
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
```

--------------------------------

### Get Track at Index from Queue

Source: https://revvlink.revvlabs.in/api/queue

Retrieves a track from the queue at a specific index without removing it. Note that this method loads the retrieved track for looping. Similar to `get()`, it should not be used for track removal.

```python
get_at(index: int) -> Playable
# Example usage:
track_at_index_2 = queue.get_at(2)
```

--------------------------------

### GET /get_player

Source: https://revvlink.revvlabs.in/api/node

Retrieves a player instance associated with a specific guild ID.

```APIDOC
## GET /get_player

### Description
Returns the Player object associated with the provided discord guild ID.

### Method
GET

### Endpoint
/get_player

### Parameters
#### Query Parameters
- **guild_id** (int) - Required - The discord.Guild.id to retrieve a player for.

### Response
#### Success Response (200)
- **player** (Player|None) - The Player object associated with the guild, or null if none exists.

### Response Example
{
  "player": {
    "guild_id": 123456789,
    "status": "connected"
  }
}
```

--------------------------------

### GET /search

Source: https://revvlink.revvlabs.in/api/playable?q=

Searches for tracks or playlists using a query string. This method automatically handles search prefixes based on the provided source or URL detection.

```APIDOC
## GET /search

### Description
Search for a list of Playable tracks or a Playlist using a query. This method is preferred over standard pool fetching as it automatically applies search prefixes for non-URL queries.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (str) - Required - The search string or URL to look up.
- **source** (TrackSource | str) - Optional - The search prefix to apply (e.g., "ytmsearch:", "spsearch:"). Defaults to YouTubeMusic.
- **node** (Node) - Optional - Specific node to execute the search on.

### Request Example
{
  "query": "Ocean Drive",
  "source": "ytmsearch"
}

### Response
#### Success Response (200)
- **result** (Search) - A collection containing Playable tracks or a Playlist object.

#### Response Example
{
  "type": "playlist",
  "tracks": [...]
}
```

--------------------------------

### Search Tracks with Plugin Sources (Python)

Source: https://revvlink.revvlabs.in/api/enums?q=

Demonstrates how to search for tracks using specific plugin sources like Spotify, Apple Music, and Deezer. This requires the LavaSrc plugin to be installed and configured. The function takes a search query and a source prefix as input.

```python
# Requires LavaSrc plugin
tracks = await revvlink.Playable.search("lofi", source="spsearch")   # Spotify
tracks = await revvlink.Playable.search("lofi", source="amsearch")   # Apple Music
tracks = await revvlink.Playable.search("lofi", source="dzsearch")   # Deezer
```

--------------------------------

### TrackStartEventPayload Structure (Python)

Source: https://revvlink.revvlabs.in/api/events

Defines the payload structure for the `on_revvlink_track_start` event. It includes the player associated with the event (which can be None) and the track that has started.

```python
TrackStartEventPayload(
    player: Player | None, track: Playable
)
```

--------------------------------

### Get Player Filters

Source: https://revvlink.revvlabs.in/api/player?q=

Retrieves the currently applied filters for the player. The filters are represented by the Filters class. Use set_filters to modify them.

```python
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.
```

--------------------------------

### Get and Set Player Volume

Source: https://revvlink.revvlabs.in/api/player?q=

Retrieves the current volume level of the player as a percentage. The volume is represented as an integer. Use the set_volume method to change the volume.

```python
volume: int

Returns an int representing the currently set volume, as a percentage.
See: :meth:`set_volume` for setting the volume.
```

--------------------------------

### Node Initialization - Python

Source: https://revvlink.revvlabs.in/api/node?q=

Initializes a Node instance for connecting to a Lavalink server. Requires URI and password, with optional parameters for session, heartbeat, retries, client, resume timeout, inactive player timeout, inactive channel tokens, and region. A unique identifier can be generated if not provided.

```python
Node(
    *,
    identifier: str | None = None,
    uri: str,
    password: str,
    session: ClientSession | None = None,
    heartbeat: float = 15.0,
    retries: int | None = None,
    client: Client | None = None,
    resume_timeout: int = 60,
    inactive_player_timeout: int | None = 300,
    inactive_channel_tokens: int | None = 3,
    region: str | None = None,
)
```

--------------------------------

### Get Node Info (Python)

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves cached node information, including available source managers and plugins. This property returns a NodeInfo dataclass or None if info has not yet been fetched. Use refresh_info() to get the latest data.

```python
info: NodeInfo | None

# Returns the cached node info including source managers and plugins.
```

--------------------------------

### Importing RevvLink Core Modules and Utilities

Source: https://revvlink.revvlabs.in/api?q=

Demonstrates the standard import pattern for accessing core RevvLink functionality, including connection management, audio players, track handling, and event payloads. This snippet serves as the entry point for integrating RevvLink into a Python project.

```python
import revvlink

# Core
revvlink.Pool
revvlink.Node
revvlink.Player

# Tracks
revvlink.Playable
revvlink.Playlist

# Queue
revvlink.Queue
revvlink.QueueMode

# Filters
revvlink.Filters

# Enums
revvlink.AutoPlayMode
revvlink.TrackSource
revvlink.TrackEndReason

# Events
revvlink.TrackStartEventPayload
revvlink.TrackEndEventPayload
revvlink.NodeReadyEventPayload

# Exceptions
revvlink.RevvLinkException
revvlink.NodeException
revvlink.PlayerException
revvlink.QueueException
```

--------------------------------

### Initialize LavalinkLoadException

Source: https://revvlink.revvlabs.in/api/exceptions?q=

Constructor signature for the LavalinkLoadException class, triggered when track loading operations fail via Lavalink.

```python
LavalinkLoadException(
    msg: str | None = None, /, *, data: LoadedErrorPayload
)
```

--------------------------------

### Queue Insertion Methods

Source: https://revvlink.revvlabs.in/api/queue?q=

Methods for adding tracks to the queue. Includes synchronous 'put' and 'put_at' for specific positioning, and asynchronous 'put_wait' for ordered insertion.

```python
put_at(index: int, value: Playable) -> None
put(item: list[Playable] | Playable | Playlist, /, *, atomic: bool = True) -> int
put_wait(item: list[Playable] | Playable | Playlist, /, *, atomic: bool = True) -> int
```

--------------------------------

### GET /get_player

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves a player instance associated with a specific Discord guild ID.

```APIDOC
## GET /get_player

### Description
Returns the Player object associated with the provided discord.Guild.id.

### Method
GET

### Endpoint
/get_player

### Parameters
#### Query Parameters
- **guild_id** (int) - Required - The discord.Guild.id to retrieve the player for.

### Response
#### Success Response (200)
- **player** (Player|None) - The Player object associated with the guild, or null if none exists.

### Response Example
{
  "player": {
    "guild_id": 123456789,
    "status": "connected"
  }
}
```

--------------------------------

### Player Initialization

Source: https://revvlink.revvlabs.in/api/player

Defines the constructor for the Player class. It takes optional arguments for the client, channel, and nodes, initializing the player for voice channel operations.

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

--------------------------------

### Get Queue Member Count

Source: https://revvlink.revvlabs.in/api/queue?q=

Returns the total number of tracks currently in the queue.

```python
count: int
```

--------------------------------

### Reconstruct Playable from Raw Data (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

Shows how to use the 'raw_data' property of a Playable object to reconstruct it. This is useful for preserving and recreating Playable objects.

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

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

--------------------------------

### Get Player Connection Status

Source: https://revvlink.revvlabs.in/api/player?q=

Retrieves the connection status of the player to a voice channel. This property returns a boolean value.

```python
connected: bool

Whether the player is currently connected to a voice channel.
Returns:
Type | Description  
---|---  
`bool` |  True if connected, False otherwise.
```

--------------------------------

### Initialize Queue

Source: https://revvlink.revvlabs.in/api/queue?q=

Initializes a new Queue instance. The Queue is thread-safe and includes built-in history tracking, loop modes, and shuffle capabilities. By default, history is enabled.

```python
Queue(*, history: bool = True)
```

--------------------------------

### Initialize NodeException

Source: https://revvlink.revvlabs.in/api/exceptions?q=

Constructor signature for the NodeException class, which is raised during generic node communication failures.

```python
NodeException(
    msg: str | None = None, status: int | None = None
)
```

--------------------------------

### Get Currently Playing Track

Source: https://revvlink.revvlabs.in/api/player?q=

Returns the currently playing track or None if no track is playing. The returned value is of type Playable.

```python
current: Playable | None

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

--------------------------------

### Search Tracks and Playlists with Revvlink (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

Illustrates various ways to use the `Playable.search` class method to find tracks and playlists. It covers searching by query, URL, and specifying different sources like YouTube Music and Spotify via plugins.

```python
# 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"])
```

--------------------------------

### Get Associated Guild

Source: https://revvlink.revvlabs.in/api/player

Retrieves the discord.Guild object associated with this player. Returns None if the player is not currently connected to a voice channel.

```python
guild: Guild | None
```

--------------------------------

### Search and Play Tracks with RevvLink

Source: https://revvlink.revvlabs.in/api/playable?q=

Demonstrates how to search for audio tracks using Playable.search() and handle the resulting Playable list or Playlist. It checks the result type to either queue a playlist or play a single track.

```python
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])
```

--------------------------------

### Get Associated Node

Source: https://revvlink.revvlabs.in/api/player

Retrieves the Node object currently associated with this player. The Node represents the Lavalink server instance connected to.

```python
node: Node
```

--------------------------------

### Node Initialization

Source: https://revvlink.revvlabs.in/api/node?q=

Defines the constructor for creating a new Node instance to connect to a Lavalink server.

```APIDOC
## POST /Node

### Description
Initializes a new Node instance representing a connection to a Lavalink server. This object manages the websocket connection, session resumption, and player tracking.

### Method
POST

### Parameters
#### Request Body
- **identifier** (str | None) - Optional - A unique identifier for this Node.
- **uri** (str) - Required - The connection URI (e.g., http://localhost:2333).
- **password** (str) - Required - Authorization password for the Node.
- **heartbeat** (float) - Optional - Seconds between websocket pings. Default: 15.0
- **retries** (int | None) - Optional - Number of connection retries. Default: None
- **resume_timeout** (int) - Optional - Seconds to configure session resuming. Default: 60
- **inactive_player_timeout** (int | None) - Optional - Default timeout for players. Default: 300
- **region** (str | None) - Optional - Regional identifier for load balancing.

### Request Example
{
  "uri": "http://localhost:2333",
  "password": "youshallnotpass",
  "identifier": "main-node"
}

### Response
#### Success Response (200)
- **status** (NodeStatus) - The initialized status of the node.

#### Response Example
{
  "status": "CONNECTED",
  "identifier": "main-node"
}
```

--------------------------------

### Get Heartbeat Interval (Python)

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves the duration in seconds between WebSocket heartbeat pings for a Lavalink node. This property returns a float representing the interval.

```python
heartbeat: float

# The duration in seconds between WebSocket heartbeat pings.
```

--------------------------------

### Initialize LavalinkException

Source: https://revvlink.revvlabs.in/api/exceptions?q=

Constructor signature for the LavalinkException class, used when the Lavalink server returns an invalid response.

```python
LavalinkException(
    msg: str | None = None, /, *, data: ErrorResponse
)
```

--------------------------------

### Get Player Ping to Lavalink Node

Source: https://revvlink.revvlabs.in/api/player?q=

Retrieves the ping in milliseconds between the connected Lavalink Node and Discord. Returns -1 if no update has been received or the player is not connected.

```python
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.
```

--------------------------------

### PlaylistInfo Class Initialization (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

The PlaylistInfo class holds metadata about a playlist, such as its name, track count, and URL, but does not contain the actual track data. It provides information about the original playlist associated with tracks.

```python
playlist_info = revvlink.PlaylistInfo(data=playlist_payload)
print(playlist_info.name)
print(playlist_info.tracks)
```

--------------------------------

### Player and Node Management

Source: https://revvlink.revvlabs.in/api/node

Methods for retrieving player information, node statistics, and general node configuration.

```APIDOC
## GET /fetch_player_info

### Description
Fetches the raw player information held by Lavalink for a specific guild.

### Method
GET

### Parameters
#### Query Parameters
- **guild_id** (int) - Required - The ID of the guild to fetch info for.

### Response
#### Success Response (200)
- **PlayerResponsePayload** (object) - The player data or null if not found.

---

## GET /fetch_info

### Description
Fetches the general information response data for the Lavalink node.

### Method
GET

### Response
#### Success Response (200)
- **InfoResponsePayload** (object) - Node information data.

---

## GET /fetch_stats

### Description
Fetches the current statistics of the Lavalink node.

### Method
GET

### Response
#### Success Response (200)
- **StatsResponsePayload** (object) - Node statistics data.
```

--------------------------------

### Queue Inspection and Manipulation

Source: https://revvlink.revvlabs.in/api/queue?q=

Utility methods for inspecting queue state, swapping items, finding indices, and performing bulk operations like shuffling or clearing.

```python
peek(index: int = 0) -> Playable
swap(first: int, second: int) -> None
index(item: Playable) -> int
shuffle() -> None
clear() -> None
copy() -> Queue

# Swap the first and second tracks in the queue.
queue.swap(0, 1)

# Shuffle the queue
player.queue.shuffle()

# Clear the queue
player.queue.clear()
```

--------------------------------

### Get Session ID (Python)

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves the Lavalink session ID for the current node connection. This property returns a string representing the session ID, or None if the node is not connected.

```python
session_id: str | None

# The Lavalink session ID for this node connection.
```

--------------------------------

### Queue Utility Methods

Source: https://revvlink.revvlabs.in/api/queue?q=

Methods for inspecting, reordering, and clearing the queue.

```APIDOC
## GET peek

### Description
Returns the track at a specific index without modifying the queue.

### Parameters
#### Query Parameters
- **index** (int) - Optional - The index to peek at. Defaults to 0.

### Response
#### Success Response (200)
- **Playable** - The track at the given index.

---

## POST swap

### Description
Swaps the positions of two tracks in the queue.

### Parameters
#### Request Body
- **first** (int) - Required - Index of the first track.
- **second** (int) - Required - Index of the second track.

---

## POST shuffle

### Description
Randomly shuffles all tracks currently in the queue in place.

---

## DELETE clear

### Description
Removes all tracks from the queue. Note: Does not affect history.
```

--------------------------------

### Get Player Paused Status

Source: https://revvlink.revvlabs.in/api/player?q=

Returns the paused status of the player. True indicates the player is currently paused. Use pause() and play() methods to control the paused state.

```python
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.
```

--------------------------------

### Implement Exception Handling Patterns

Source: https://revvlink.revvlabs.in/api/exceptions?q=

Common patterns for catching library-wide exceptions, handling empty queues, and managing specific Lavalink API failures.

```python
# Catch any RevvLink error
try:
    await player.play(track)
except revvlink.RevvLinkException as e:
    print(f"Error: {e}")

# Handle empty queue
try:
    next_track = player.queue.get()
except revvlink.QueueEmpty:
    await ctx.send("No more tracks.")

# Handle Lavalink API failures
try:
    results = await revvlink.Playable.search(query)
except revvlink.LavalinkLoadException as e:
    await ctx.send(f"Could not load tracks ({e.severity}): {e.error}")
except revvlink.LavalinkException as e:
    await ctx.send(f"Lavalink error {e.status}: {e.error}")
```

--------------------------------

### Get Player State

Source: https://revvlink.revvlabs.in/api/player

Retrieves the current basic state of the player, including voice state information from Discord. This property provides a snapshot of the player's current status.

```python
state: PlayerBasicState
```

--------------------------------

### Get Current Playback Position

Source: https://revvlink.revvlabs.in/api/player?q=

Returns the current playback position of the track in milliseconds. This relies on Lavalink updates. Returns 0 if no track is loaded or the player is not connected, or if no update has been received.

```python
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.
```

--------------------------------

### Manage Playlist Extras

Source: https://revvlink.revvlabs.in/api/playable

Demonstrates how to set and access custom metadata (extras) on a playlist, which are sent to Lavalink as userData. This requires Lavalink 4+ and allows for attaching stateful information to tracks.

```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"])
```

--------------------------------

### Queue Utility Methods

Source: https://revvlink.revvlabs.in/api/queue

Methods for manipulating the order and state of the queue.

```APIDOC
## DELETE /queue/item

### Description
Removes an item from the queue by its index.

### Parameters
#### Query Parameters
- **index** (int) - Required - The index of the item to delete.

---

## GET /queue/peek

### Description
Returns the track at a specific index without removing it from the queue.

### Parameters
#### Query Parameters
- **index** (int) - Optional - The index to peek at. Defaults to 0.

---

## POST /queue/swap

### Description
Swaps the positions of two tracks in the queue.

### Parameters
#### Request Body
- **first** (int) - Required - Index of the first track.
- **second** (int) - Required - Index of the second track.

---

## POST /queue/shuffle

### Description
Randomly shuffles all tracks currently in the queue in-place.
```

--------------------------------

### Get Player by Guild ID (Python)

Source: https://revvlink.revvlabs.in/api/node?q=

Retrieves a `Player` object associated with a given Discord guild ID. If no player exists for the specified guild, it returns `None`. This method requires the guild ID as an integer input.

```Python
get_player(guild_id: int) -> Player | None

Return a :class:`~revvlink.Player` associated with the provided :attr:`discord.Guild.id`.
Parameters:
Name | Type | Description | Default
---
`guild_id` | `int` | The :attr:`discord.Guild.id` to retrieve a :class:`~revvlink.Player` for. | _required_
Returns:
Type | Description
---
`Optional[:class:`~revvlink.Player`]` | The Player associated with this guild ID. Could be None if no :class:`~revvlink.Player` exists for this guild.
```

--------------------------------

### Remove Item from Queue - Python

Source: https://revvlink.revvlabs.in/api/queue

Removes a specific item from the queue up to a specified count or all occurrences. The removal process starts from the beginning (left side) of the queue. Setting the count to less than or equal to 0 is treated as 1.

```python
remove(item: Playable, /, count: int | None = 1) -> int

Remove a specific track from the queue up to a given count or all instances.
ℹNote
This method starts from the left hand side of the queue E.g. the beginning.
⚠Warning
Setting count to `<= 0` is equivalent to setting it to `1`.
Parameters:
Name | Type | Description | Default  
---|---|---|---
`item` |  `Playable` |  The item to remove from the queue. |  _required_  
`count` |  `int | None` |  The amount of times to remove the item from the queue. Defaults to `1`. If set to `None` this will remove all instances of the item. |  `1`  
Returns:
Type | Description  
---|---
`int` |  The amount of times the item was removed from the queue.  
Raises:
Type | Description  
---|---
`ValueError` |  The item was not found in the queue.
```

--------------------------------

### Queue Management Methods

Source: https://revvlink.revvlabs.in/api/queue

Methods for adding, removing, and retrieving items from the playback queue.

```APIDOC
## PUT /queue/at

### Description
Inserts a track into the queue at a specific index without replacing existing items.

### Method
POST

### Parameters
#### Request Body
- **index** (int) - Required - The index to insert the track at.
- **value** (Playable) - Required - The track to insert.

### Response
#### Success Response (200)
- **None**

---

## GET /queue/wait

### Description
Asynchronously retrieves the first track in the queue, waiting indefinitely if the queue is empty.

### Method
GET

### Response
#### Success Response (200)
- **track** (Playable) - The retrieved track.

---

## POST /queue/add

### Description
Appends a track, playlist, or list of tracks to the end of the queue.

### Parameters
#### Request Body
- **item** (list[Playable] | Playable | Playlist) - Required - The item(s) to add.
- **atomic** (bool) - Optional - If true, ensures all items are added or none are. Defaults to true.

### Response
#### Success Response (200)
- **count** (int) - The number of tracks added.
```

--------------------------------

### Get Track from Queue

Source: https://revvlink.revvlabs.in/api/queue

Retrieves and removes a track from the left side (front) of the queue. This method does not block and will return the same track if the queue is in loop mode. It should not be used for removing tracks; use `del queue[index]`, `revvlink.Queue.remove`, or `revvlink.Queue.delete` instead.

```python
get() -> Playable
# Example usage:
track = queue.get()
```

--------------------------------

### Get Route Planner Status using Revvlink API

Source: https://revvlink.revvlabs.in/api/node?q=

Asynchronously fetches the status of the RoutePlanner for the Lavalink node. This function provides insights into the node's network routing capabilities. It returns a dictionary containing the status or None if the RoutePlanner is not enabled.

```python
async def get_routeplanner_status() -> dict[str, Any] | None:
    """
    Fetch the RoutePlanner status for this Lavalink node.
    
    Returns:
    dict[str, Any] | None: A dictionary containing the RoutePlanner status, or None if the RoutePlanner is not enabled on the server.
    
    Raises:
    LavalinkException: An error occurred while making this request to Lavalink.
    NodeException: An error occured while making this request to Lavalink, and Lavalink was unable to send any error information.
    """
    pass
```

--------------------------------

### Queue Management Methods

Source: https://revvlink.revvlabs.in/api/queue?q=

Methods for adding, retrieving, and removing tracks from the queue.

```APIDOC
## PUT put_at

### Description
Inserts a track into the queue at a specific index without replacing existing items.

### Method
PUT

### Parameters
#### Request Body
- **index** (int) - Required - The index to insert the track at.
- **value** (Playable) - Required - The track to insert.

### Response
#### Success Response (200)
- **None**

---

## GET get_wait

### Description
Asynchronously retrieves the first track in the queue, waiting if the queue is empty.

### Method
GET

### Response
#### Success Response (200)
- **Playable** - The track retrieved from the queue.

---

## POST put

### Description
Adds one or more items to the end of the queue.

### Parameters
#### Request Body
- **item** (list[Playable] | Playable | Playlist) - Required - The item(s) to add.
- **atomic** (bool) - Optional - If True, fails entirely if any item insertion fails. Defaults to True.

### Response
#### Success Response (200)
- **int** - The number of tracks added.

---

## DELETE delete

### Description
Removes a track from the queue at the specified index.

### Parameters
#### Path Parameters
- **index** (int) - Required - The index of the track to remove.

### Response
#### Success Response (200)
- **None**
```

--------------------------------

### Connect to Channel with Player

Source: https://revvlink.revvlabs.in/api/player

Connects a discord.Client to a voice channel using the revvlink.Player class. This is the primary method for initializing a player instance.

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

--------------------------------

### Copy queue

Source: https://revvlink.revvlabs.in/api/queue

Creates and returns a shallow copy of the current queue instance.

```python
copy() -> Queue
```

--------------------------------

### Get Player by Guild ID (Python)

Source: https://revvlink.revvlabs.in/api/node

Retrieves a Player object associated with a specific Discord guild ID. This method takes an integer guild ID as input and returns either a Player object or None if no player exists for that guild. It is crucial for managing player instances within specific guilds.

```python
get_player(guild_id: int) -> Player | None

Return a :class:`~revvlink.Player` associated with the provided :attr:`discord.Guild.id`.
Parameters:
Name | Type | Description | Default  
---
`guild_id` |  `int` |  The :attr:`discord.Guild.id` to retrieve a :class:`~revvlink.Player` for. |  _required_  
Returns:
Type | Description  
---
`Optional[:class:`~revvlink.Player`]` | The Player associated with this guild ID. Could be None if no :class:`~revvlink.Player` exists for this guild.
```

--------------------------------

### RoutePlanner Management

Source: https://revvlink.revvlabs.in/api/node

Methods to manage and monitor the RoutePlanner status for IP rotation.

```APIDOC
## GET /get_routeplanner_status

### Description
Fetches the current status of the RoutePlanner.

### Method
GET

### Response
#### Success Response (200)
- **status** (dict) - RoutePlanner status or null if disabled.

---

## POST /unmark_failed_address

### Description
Unmarks a specific failed IP address to allow reuse.

### Method
POST

### Request Body
- **address** (string) - Required - The IP address to unmark.

---

## POST /unmark_all_failed_addresses

### Description
Unmarks all currently failed IP addresses.

### Method
POST
```

--------------------------------

### Remove Item from Queue - Python

Source: https://revvlink.revvlabs.in/api/queue?q=

Removes a specified item from the queue up to a given count or all instances. The removal starts from the beginning (left side) of the queue. Setting count to 0 or less defaults to removing one instance. If count is None, all instances of the item are removed. The function returns the number of times the item was removed.

```python
remove(item: Playable, /, count: int | None = 1) -> int
```

--------------------------------

### Set and Access Playable Extras (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

Demonstrates how to set and access extra data associated with a Playable object. Extras are sent as 'userData' to Lavalink and require Lavalink 4+.

```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"])
```

--------------------------------

### Properties: extras & raw_data

Source: https://revvlink.revvlabs.in/api/playable?q=

Manage custom metadata via the extras property or retrieve the underlying Lavalink payload via raw_data.

```APIDOC
## Property: extras

### Description
Access or modify the `userData` field sent to Lavalink (requires Lavalink 4+). Accepts a dictionary of JSON-serializable values.

### Parameters
- **value** (dict | ExtrasNamespace) - The metadata to attach to the playable object.

---

## Property: raw_data

### Description
Retrieves the raw TrackPayload received from Lavalink, useful for reconstructing the Playable object later.

### Response
- **data** (TrackPayload) - The raw object data.
```

--------------------------------

### Playlist Class Initialization and Usage (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

The Playlist class is a container for playable tracks, typically obtained from search results or fetched tracks. It supports standard Python sequence operations and provides access to playlist metadata. It should not be instantiated directly but rather obtained through methods like `Playable.search` or `revvlink.Pool.fetch_tracks`.

```python
playlist: revvlink.Search = revvlink.Playable.search("QUERY")
print(str(playlist))
print(len(playlist))
first_track = playlist[0]
for track in playlist:
    print(track.title)
```

--------------------------------

### Player Connection and Node Management

Source: https://revvlink.revvlabs.in/api/player

Asynchronous methods for managing the player's lifecycle, including switching Lavalink nodes, establishing initial connections, and moving between voice channels.

```python
async def switch_node(new_node: Node) -> None:
    # Attempts to migrate player state to a new node
    pass

async def connect(*, timeout: float = 10.0, reconnect: bool, self_deaf: bool = False, self_mute: bool = False) -> None:
    # Establishes connection to a voice channel
    pass

async def move_to(channel: VocalGuildChannel | None, *, timeout: float = 10.0, self_deaf: bool | None = None, self_mute: bool | None = None) -> None:
    # Moves the player to a different voice channel
    pass
```

--------------------------------

### Playable Class Constructor

Source: https://revvlink.revvlabs.in/api/playable?q=

The constructor for the Playable object. Note that this class should not be instantiated manually by the user.

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

--------------------------------

### Insert track into queue with put_at

Source: https://revvlink.revvlabs.in/api/queue

Inserts a Playable track into the queue at a specific index. This operation shifts existing elements rather than replacing them.

```python
put_at(index: int, value: Playable) -> None
```

--------------------------------

### Play track with Revvlink

Source: https://revvlink.revvlabs.in/api/player

Initiates playback of a Playable track. Supports configuration for start/end times, volume, pause state, history tracking, and auto-queue population.

```python
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
```

--------------------------------

### Equalizer Filter Initialization (Python)

Source: https://revvlink.revvlabs.in/api/filters?q=

The `Equalizer` class represents an Equalizer filter with 15 adjustable bands. It can be initialized with an optional list of band gains or defaults to all bands having a gain of 0.0. Valid gain values range from -0.25 to 1.0.

```python
Equalizer(payload: list[Equalizer] | None = None)
```

--------------------------------

### Apply and Reset Audio Filters with Revvlink Filters

Source: https://revvlink.revvlabs.in/api/filters?q=

Demonstrates how to apply and reset audio filters using the Filters class in Revvlink. This includes setting specific filter properties like pitch and speed, resetting individual filters, and resetting all filters.

```python
import revvlink

# Assuming 'player' is an instance of revvlink.Player

# Apply timescale filter
filters = player.filters
filters.timescale.set(pitch=1.2, speed=1.2)
await player.set_filters(filters)

# Reset all filters
await player.set_filters()

# Reset a specific filter (e.g., timescale)
filters = player.filters
filters.timescale.reset()
await player.set_filters(filters)

# Reset all filters using the Filters.reset() method
filters = player.filters
filters.reset()
await player.set_filters(filters)
```

--------------------------------

### Queue Management API

Source: https://revvlink.revvlabs.in/api/queue?q=

Endpoints and methods for interacting with the Revvlink audio queue, including retrieving tracks and managing queue state.

```APIDOC
## GET /queue/get

### Description
Retrieves the next track from the front of the queue without blocking. Note that in loop mode, this may return the same track repeatedly.

### Method
GET

### Endpoint
/queue/get

### Response
#### Success Response (200)
- **track** (Playable) - The track retrieved from the queue.

#### Error Response (404)
- **error** (QueueEmpty) - The queue was empty when attempting to retrieve a track.

---

## GET /queue/get_at

### Description
Retrieves a specific track from the queue at a given index. This action will load the retrieved track for looping if applicable.

### Method
GET

### Endpoint
/queue/get_at

### Parameters
#### Query Parameters
- **index** (int) - Required - The index of the track to retrieve.

### Response
#### Success Response (200)
- **track** (Playable) - The track at the specified index.

#### Error Response (400/404)
- **error** (IndexError) - The index provided is out of range.
- **error** (QueueEmpty) - The queue is empty.
```

--------------------------------

### Setting Attributes for All Tracks in a Playlist (Python)

Source: https://revvlink.revvlabs.in/api/playable?q=

The `track_extras` method allows you to set attributes on all `Playable` objects within a playlist simultaneously. This is useful for attaching metadata like the requester to each track. Existing `Playable` properties cannot be overridden.

```python
playlist.track_extras(requester=ctx.author)

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

--------------------------------

### Fetch Tracks using Pool Search (Python)

Source: https://revvlink.revvlabs.in/api/pool?q=

Searches for playable tracks or playlists through the Pool using a given query. It can optionally use a specific node or find the best available one. Results are cached if the LFU cache is active. This method is asynchronous.

```python
fetch_tracks(
    query: str, /, *, node: Node | None = None
) -> list[Playable] | Playlist

# Example Usage:
# try:
#     results = await client.fetch_tracks("some song name")
# except LavalinkLoadException as e:
#     print(f"Error loading tracks: {e}")
```

--------------------------------

### Set Multiple Filters at Once (Python)

Source: https://revvlink.revvlabs.in/api/filters?q=

The `set_filters` method allows setting multiple audio filters simultaneously on a standalone Filter object. It accepts various filter types as keyword arguments. This is distinct from setting filters directly on a player object.

```python
set_filters(**filters: Unpack[FiltersOptions]) -> None
```

--------------------------------

### Peek at queue items

Source: https://revvlink.revvlabs.in/api/queue

Returns the track at a specified index without modifying the queue. Defaults to the next item in the queue.

```python
peek(index: int = 0) -> Playable
```

--------------------------------

### Pool Class Methods

Source: https://revvlink.revvlabs.in/api/pool?q=

Documentation for the class methods of the Pool class.

```APIDOC
## Pool Class Methods

### Description
Documentation for the class methods of the Pool class.

### `region_from_endpoint`

#### Description
Parses a Discord voice endpoint string to map it back to a Region name.

#### Method
`classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Parameters
- **endpoint** (`str | None`) - Required - The raw Discord voice endpoint (e.g., "us-east1.discord.gg:443").

### `connect`

#### Description
Connects the provided Iterable[:class:`Node`] to Lavalink.

#### Method
`async classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Parameters
- **nodes** (`Iterable[Node]`) - Required - The :class:`Node`'s to connect to Lavalink.
- **client** (`Client | None`) - Optional - The :class:`discord.Client` to use to connect the :class:`Node`. Defaults to None.
- **cache_capacity** (`int | None`) - Optional - An optional integer of the amount of track searches to cache. Defaults to None.
- **regions** (`dict[str, list[str]] | None`) - Optional - An optional mapping of region label to a list of Discord voice endpoint substrings. Defaults to None.

#### Raises
- `AuthorizationFailedException` - The node password was incorrect.
- `InvalidClientException` - The :class:`discord.Client` passed was not valid.
- `NodeException` - The node failed to connect properly.

### `reconnect`

#### Description
Reconnects all nodes in the pool that are currently disconnected.

#### Method
`async classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
None

### `close`

#### Description
Closes and cleans up all :class:`~revvlink.Node` on this Pool.

#### Method
`async classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
None

### `nodes`

#### Description
Returns a mapping of :attr:`Node.identifier` to :class:`Node` that have previously been successfully connected.

#### Method
`classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
None

### `get_node`

#### Description
Retrieves a :class:`Node` from the :class:`Pool` with the given identifier. If no identifier is provided, this method returns the `best` node. If a `region` is provided, it tries to find the best node matching that region.

#### Method
`classmethod`

#### Endpoint
N/A (Class Method)

#### Parameters
##### Path Parameters
None

##### Query Parameters
- **identifier** (`str | None`) - Optional - An optional identifier to retrieve a :class:`Node`.
- **region** (`str | None`) - Optional - An optional region string to filter nodes for load balancing.

#### Raises
- `InvalidNodeException` - Raised when a Node can not be found, or no :class:`Node` exists on the :class:`Pool`.
```

--------------------------------

### Configure Timescale Filter

Source: https://revvlink.revvlabs.in/api/filters

Sets the playback speed, pitch, and rate for the Timescale filter. Returns the instance for method chaining.

```python
set(**options: Unpack[Timescale]) -> Self
```

--------------------------------

### Retrieve track with get_wait

Source: https://revvlink.revvlabs.in/api/queue

Asynchronously retrieves the first Playable track from the queue. If the queue is empty, it waits indefinitely until a track is available.

```python
get_wait() -> Playable
```

--------------------------------

### Fetch tracks from Pool

Source: https://revvlink.revvlabs.in/api/pool

Searches for tracks using a query string and an optional node. Returns a list of playable tracks or a playlist, and may raise a LavalinkLoadException if the search fails.

```python
fetch_tracks(query: str, /, *, node: Node | None = None) -> list[Playable] | Playlist
```

--------------------------------

### Playlist Track Extras

Source: https://revvlink.revvlabs.in/api/playable?q=

Method to set attributes to all Playable objects within a playlist. Useful for attaching state like a requester to each track.

```APIDOC
## Playlist Track Extras

### Description
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
- **`**attrs`** (`object`): The keyword arguments to set as attribute name=value on each :class:`Playable`.

### Example
```python
playlist.track_extras(requester=ctx.author)

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