Harmonize

Player

class harmonize.Player(*args, **kwargs)

Represents a Discord voice player.

node

The node the player is connected to.

Type:

harmonize.connection.Node

connection_event

An event triggered when the player’s connection state changes.

Type:

asyncio.Event

voice_state

The current voice state of the player.

Type:

dict[str, any]

user_data

The user data of the player.

Type:

dict[any, any]

volume

The current volume of the player.

Type:

int

paused

A boolean indicating whether the player is paused or not.

Type:

bool

connected

A boolean indicating whether the player is connected or not.

Type:

bool

is_playing

A boolean indicating whether the player is currently playing or not.

Type:

bool

guild

The guild the player is connected to.

Type:

Optional[disnake.Guild]

loop

The loop status of the player.

Type:

harmonize.enums.LoopStatus

position_timestamp

The timestamp of the player’s current position.

Type:

int

last_position

The last known position of the player.

Type:

int

last_update

The timestamp of the player’s last update.

Type:

int

queue

The queue of the player.

Type:

harmonize.queue.Queue

filters

The list of filters currently applied to the player.

Type:

list[harmonize.abstract.Filter]

async on_voice_server_update(data: dict) → None

This function is a coroutine.

An abstract method that is called when initially connecting to voice. This corresponds to VOICE_SERVER_UPDATE.

Parameters:

data (dict) – The raw :ddocs:`voice server update payload <topics/gateway-events#voice-server-update>`.

async on_voice_state_update(data: dict) → None

This function is a coroutine.

An abstract method that is called when the client’s voice state has changed. This corresponds to VOICE_STATE_UPDATE.

Parameters:

data (dict) – The raw :ddocs:`voice state payload <resources/voice#voice-state-object>`.

async handle_event(reason: EndReason) → None

This function is a coroutine.

Handles an event triggered by the player, such as a track finishing or a load failure.

Note

This function is required for autoplay please do not touch it for personal use

Parameters:

reason (harmonize.enums.EndReason) – The reason for the event.

Return type:

None

async update_state(state: dict) → None

This function is a coroutine.

Updates the state of the player with the given state dictionary.

Note

This function is required to update the node statistics, please do not touch it for personal use

Parameters:

state (dict) – The state dictionary containing the ‘position’ and ‘time’ keys.

Return type:

None

dispatch(name: str, *args: any) → None

Dispatches a message to the client with the given name and arguments.

Parameters:

• name (str) – The name of the message to dispatch.

• *args (any) – Variable number of arguments.

Return type:

None

add_user_data(**kwargs: any) → None

Adds the given keyword arguments to the user data dictionary.

Parameters:

**kwargs (any) – The keyword arguments to be added to the user data dictionary.

Return type:

None

fetch_user_data(key: any) → any

Retrieves the value associated with the specified key from the user data dictionary.

Parameters:

key (any) – The key to retrieve the value from the user data dictionary.

Return type:

any

async play(track: Track | None = ..., start_time: int = ..., end_time: int = ..., no_replace: bool = ..., volume: int = ..., pause: bool = ..., **kwargs: any) → None

This function is a coroutine.

Plays a track with the given parameters.

Note

Start_time must be an int with a value equal to, or greater than 0, and less than the track duration

End_time must be an int with a value equal to, or greater than 1, and less than or equal to the track duration

Parameters:

• track (Optional[Track]) – The track to play. If MISSING, the next track in the queue will be played.

• start_time (int) – The start time of the track. If MISSING, the track will start from the beginning.

• end_time (int) – The end time of the track. If MISSING, the track will play until its end.

• no_replace (bool) – Whether to replace the current track or not. If True, the current track will not be replaced.

• volume (int) – The volume of the track. If MISSING, the current volume will be used.

• pause (bool) – Whether to pause the track after playing. If MISSING, the track will not be paused.

• **kwargs (any) – Additional options to be passed to the player.

Raises:

• ValueError – If the start_time or end_time is invalid.

• TypeError – If the pause parameter is not a bool.

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async stop() → None

This function is a coroutine.

Stops the current player.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async skip() → Track | None

This function is a coroutine.

Skips the current track in the player’s queue.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

Optional[harmonize.objects.Track]

async set_pause(paused: bool) → None

This function is a coroutine.

Sets the pause state of the player.

Parameters:

paused (bool) – Whether the player should be paused or not.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async change_volume(volume: int) → None

This function is a coroutine.

Changes the volume of the player.

Parameters:

volume (int) – The new volume of the player. It will be clamped between 0 and 1000.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async seek(position: int) → None

This function is a coroutine.

Seeks to a specific position in the player.

Parameters:

position (int) – The position to seek to.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async remove_filters() → None

This function is a coroutine.

Removes all audio filters from the player.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async update_filters(filter: Filter) → None

async update_filters(filters: list[Filter]) → None

This function is a coroutine.

Updates the player’s audio filters.

Parameters:

**kwargs (any) –

Keyword arguments containing the filters to update.

• filters (list[Filter]): The list of filters to update.

• filter (Filter): The filter to update.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async set_filters(filter: Filter) → None

async set_filters(filters: list[Filter]) → None

This function is a coroutine.

Sets the player’s audio filters.

Parameters:

**kwargs (any) –

Keyword arguments containing the filters to set.

• filters (list[Filter]): The list of filters to set.

• filter (Filter): The filter to set.

Raises:

• Forbidden – If the request is forbidden.

• RequestError – Throws an error when the request fails.

• IOError – If the connection has been closed

Return type:

None

async classmethod connect_to_channel(channel: VocalGuildChannel, /, **kwargs: any) → Player

This function is a coroutine.

Connects a player to a specified channel.

Parameters:

• channel (VocalGuildChannel) – The channel to connect the player to.

• **kwargs (any) – Additional keyword arguments to be passed to the player user data.

Return type:

harmonize.Player

Raises:

InvalidChannelStateException – If the provided channel is not a valid voice channel.

async connect(*, timeout: float = 10.0, reconnect: bool, self_deaf: bool = True, self_mute: bool = False) → None

This function is a coroutine.

Connects the player to a voice channel.

Parameters:

• timeout (float) – The timeout in seconds before the connection.rst attempt is cancelled. Defaults to 10.0.

• reconnect (bool) – Whether the player should reconnect if the connection.rst is lost.

• self_deaf (bool) – Whether the player should be deafened in the voice channel. Defaults to True.

• self_mute (bool) – Whether the player should be muted in the voice channel. Defaults to False.

Raises:

InvalidChannelStateException – If the provided channel is not a valid voice channel.

Return type:

None

async disconnect(**kwargs: any) → None

This function is a coroutine.

Disconnects the player from the voice channel.

Parameters:

**kwargs (any) – Additional keyword arguments.

Return type:

None

async move_to(channel: VocalGuildChannel | None, *, timeout: float = 10.0, self_deaf: bool | None = True, self_mute: bool | None = None) → None

This function is a coroutine.

Moves the player to a specified voice channel.

Parameters:

• channel – VocalGuildChannel | None The voice channel to move the player to. If None, the player will remain in its current channel.

• timeout – Optional[float] The maximum time in seconds to wait for the player to connect to the channel. Defaults to 10.0.

• self_deaf – Optional[bool] Whether the player should be deafened in the voice channel. If None, the player’s deafened status will be inherited from the current voice state. Defaults to True.

• self_mute –

  Optional[bool] Whether the player should be muted in the voice channel. If None, the player’s muted status will be inherited from the current voice state.

  Defaults to None.

Return type:

None

Raises:

InvalidChannelStateException – If the player tries to move without a valid guild or channel.:

Note

This method will clear the _connection_event event and wait for the player to connect to the specified channel. If the connection attempt times out or is cancelled, the player will be destroyed.

Queue

class harmonize.Queue(player: Player)

Represents a queue of tracks for a Discord voice player.

Operations

len(x)

Returns the number of tracks in the queue.

x == y

Checks if two queues are the same.

x != y

Checks if two filters are not the same.

x <= y

Checks if the first queue is less than or equal to the second queue.

x > y

Checks if the first queue is greater than the second queue.

x < y

Checks if the first queue is less than the second queue.

for y in x

Returns an iterator over the tracks in the queue.

x[key]

Returns the track at the specified index.

x in y

Checks if a track is in the queue.

bool(x)

Checks if the queue is empty.

hash(x)

Return the filter’s hash.

str(x)

Returns a string representation of the queue.

Tip

The history and tracks attributes give the ORIGINAL OBJECT, you can change them at will

current

The currently playing track in the queue.

Type:

Optional[harmonize.objects.Track]

tracks

The list of tracks currently in the queue.

Type:

list[harmonize.objects.Track]

history

The list of tracks that have been played in the queue.

Type:

list[harmonize.objects.Track]

loop

The loop status of the queue.

Type:

harmonize.enums.LoopStatus

listened_count

The number of times a track has been played in the queue.

Type:

int

set_loop(value: LoopStatus, /) → None

Sets the loop status of the queue.

Parameters:

value (harmonize.enums.LoopStatus) – The new loop status to set.

Raises:

ValueError – If the provided value is not an instance of LoopStatus.

Return type:

None

add(track: Track) → None

add(tracks: list[Track]) → None

Adds a track or multiple tracks to the queue.

Parameters:

**kwargs (harmonize.objects.Track | list[harmonize.objects.Track]) –

‘track’ (harmonize.objects.Track): A single track to add to the queue.

’tracks’ (list[harmonize.objects.Track]): A list of tracks to add to the queue.

Raises:

ValueError – If neither ‘track’ nor ‘tracks’ is provided in kwargs.:

Return type:

None

clear() → None

Clears the queue by removing all tracks from the current and history lists.

Return type:

None

shuffle() → None

Shuffles the current queue in-place.

Return type:

None

reverse() → None

Reverses the current queue in-place.

Return type:

None

Exceptions

class harmonize.HarmonizeException

Base class for Harmonize exceptions.

Tip

When catching errors, you can use this error class without using all other error classes

class harmonize.AuthorizationError

Represents an authorization error. Throws when authorization fails.

class harmonize.NodeUnknownError

Represents a node unknown error. Throws at 404 status.

class harmonize.Forbidden(name: str)

Represents an authentication error. Throws when authorization fails or forbidden status

class harmonize.InvalidData

Represents an invalid data error. Throws when data is not valid.

class harmonize.InvalidSession

Represents an invalid session error. Throws when session is not valid.

class harmonize.RequestError

Represents a request error. Throws when the request fails.

class harmonize.InvalidChannelStateException

Represents an invalid channel state error. Throws when trying to move a player without a valid guild or channel.