Objects

class harmonize.objects.LoadResult(load_type: ~harmonize.enums.load_type.LoadType, tracks: list[~harmonize.objects.track.Track], playlist_info: ~harmonize.objects.playlist_info.PlaylistInfo = <harmonize.objects.PlaylistInfo selected_track=-1>, plugin_info: dict[str, any] | None = None, error: ~harmonize.objects.load_result.LoadError | None = None)

Represents the result of a load operation.

Operations

x[key]

Returns the value of a given attribute of the LoadResult object.

load_type

The type of load operation.

Type:

harmonize.enums.LoadType

playlist_info

The playlist information. If the load operation is not a playlist, this will be None.

Type:

harmonize.objects.PlaylistInfo

tracks

The decoded Track objects.

Type:

list[harmonize.objects.Track]

plugin_info

Additional plugin information associated with the load operation, if applicable.

Type:

Optional[dict[str, any]]

error

The load error, if applicable.

Type:

Optional[harmonize.objects.LoadError]

classmethod empty()

Creates an empty LoadResult instance.

Return type:

LoadResult

classmethod from_dict(mapping: dict) → LoadResult

Creates a LoadResult instance from a dictionary.

Parameters:

mapping (dict) – A dictionary containing the data to create the LoadResult instance.

Return type:

LoadResult

property selected_track: Track | None

Retrieves the currently selected track from the playlist.

Returns:

The selected track if it exists, otherwise None.

Return type:

Optional[Track]

class harmonize.objects.PlaylistInfo(name: str, selected_track: int = -1)

Represents the information about a playlist.

Operations

x[key]

Returns the value of a given attribute of the LoadResult object.

name

The name of the playlist.

Type:

str

selected_track

The index of the selected track in the playlist. If no track is selected, it defaults to -1.

Type:

int

classmethod from_dict(mapping: dict[str, any]) → PlaylistInfo

Creates a new instance of the PlaylistInfo class from a dictionary.

Parameters:

mapping (dict[str, any]) – A dictionary containing the playlist information.

Return type:

PlaylistInfo

classmethod none() → PlaylistInfo

Creates a new instance of the PlaylistInfo class with default values.

Returns:

PlaylistInfo

class harmonize.objects.Stats(node: Node, data: dict[str, any])

Represents the statistics of a Lavalink node.

is_fake

Inducing whether statistics are fake or not

Type:

bool

uptime

The uptime of the node in milliseconds.

Type:

float

players

Number of players connected to this node

Type:

int

playing_players

Number of players currently playing on this node

Type:

int

memory_free

The free memory in bytes.

Type:

int

memory_used

The used memory in bytes.

Type:

int

memory_allocated

The allocated memory in bytes.

Type:

int

memory_reservable

The reservable memory in bytes.

Type:

int

cpu_cores

The number of CPU cores.

Type:

int

system_load

The system load average.

Type:

float

lavalink_load

The Lavalink load average.

Type:

float

frames_sent

The number of frames sent by the node.

Type:

int

frames_nulled

The number of frames nulled by the node.

Type:

int

frames_deficit

The number of frames deficit by the node.

Type:

int

classmethod empty(node: Node) → Stats

Creates an empty Stats object with default values.

Parameters:

node (harmonize.connection.Node) – The node associated with the stats.

Return type:

Stats

class harmonize.objects.Track(data: dict[str, str | None | bool | int])

Represents a track.

Operations

x[key]

Returns the value of a given attribute of the LoadResult object.

raw

Unserialized object track

Type:

dict[str, Union[Optional[str], bool, int]]

encoded

The encoded track data

Type:

str

identifier

The unique identifier of the track.

Type:

str

is_seekable

Indicates whether the track can be seeked or not.

Type:

bool

author

The author of the track.

Type:

str

duration

The duration of the track in milliseconds.

Type:

int

is_stream

Indicates whether the track is a stream or not.

Type:

bool

title

The title of the track.

Type:

str

uri

The URI of the track.

Type:

str

artwork_url

The URL of the track’s artwork.

Type:

Optional[str]

isrc

The ISRC of the track.

Type:

Optional[str]

position

The current position in the track in milliseconds.

Type:

int

source_name

The name of the source of the track.

Type:

str

plugin_info

Additional plugin information associated with the track, if applicable.

Type:

Optional[dict[str, any]]

user_data

Additional user data associated with the track, if applicable.

Type:

Optional[dict[str, any]]

classmethod from_dict(mapping: dict) → Track

Create a new instance of the Track class from a dictionary mapping.

Parameters:

mapping (dict) – A dictionary containing the mapping data for the Track object.

Return type:

harmonize.objects.Track

classmethod from_encode(track: str, source_decoders: dict[str, Callable[[DataReader], dict[str, any]]] = None) → Track

Decodes a track from a given string representation.

Parameters:

• track (str) – The string representation of the track to be decoded.

• source_decoders (dict[str, Callable[[harmonize.utils.DataReader], dict[str, any]]]) – A dictionary mapping source names to their respective decoding functions. These functions take a DataReader object as input and return a dictionary containing the decoded source-specific fields. If not provided, the function will use the default decoders from DEFAULT_DECODER_MAPPING.

Returns:

An instance of the Track class representing the decoded track.

Return type:

harmonize.objects.Track

Filters

All custom filters must derive from Filter

class harmonize.objects.Equalizer(gains: list[float] = None)

Represents an equalizer filter. Extended from harmonize.abstract.Filter

update(*, bands: list[tuple[int, float]]) → None

update(*, band: int, gain: int) → None

Updates the equalizer filter with new gain values.

Note

Bands must be a list of tuples (band: int, gain: float) Band between 0 and 14, and gain between -0.25 and 1.0

Parameters:

**kwargs (Keyword arguments containing the new gain values. See above)

Raises:

• ValueError – If the provided gain values are out of range.

• KeyError – If neither ‘bands’ nor ‘band’ and ‘gain’ are provided.

Return type:

None

to_dict() → dict[str, any]

Converts the Equalizer filter object to a dictionary representation.

Returns:

dict[str, any]

Return type:

A dictionary representation of the Equalizer filter object, where each key-value pair represents a band and its corresponding gain.

class harmonize.objects.Karaoke(level: float = 1.0, mono_level: float = 1.0, filter_band: float = 220.0, filter_width: float = 100.0)

Represents a karaoke filter. Extended from harmonize.abstract.Filter

update(*, level: float) → None

update(*, mono_level: float) → None

update(*, filter_band: float) → None

update(*, filter_width: float) → None

update(*, level: float, mono_level: float) → None

update(*, level: float, filter_width: float) → None

update(*, level: float, filter_band: float) → None

update(*, mono_level: float, filter_width: float) → None

update(*, mono_level: float, filter_band: float) → None

update(*, filter_band: float, filter_width: float) → None

update(*, level: float, mono_level: float, filter_width: float) → None

update(*, level: float, mono_level: float, filter_band: float) → None

update(*, level: float, mono_level: float, filter_band: float, filter_width: float) → None

Update the values of the Karaoke filter object.

Parameters:

(dict) (**kwargs)

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the Karaoke filter object to a dictionary.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the Karaoke filter values.

class harmonize.objects.Timescale(speed: float = 1.0, pitch: float = 1.0, rate: float = 1.0)

Represents a timescale filter. Extended from harmonize.abstract.Filter

update(*, speed: float) → None

update(*, pitch: float) → None

update(*, rate: float) → None

update(*, speed: float, pitch: float) → None

update(*, speed: float, rate: float) → None

update(*, rate: float, pitch: float) → None

update(*, speed: float, rate: float, pitch: float) → None

Updates the Timescale filter with new values for speed, pitch, and/or rate.

Note

All new values must be greater than or equal to 0.

Parameters:

**kwargs (A dictionary containing the new values for speed, pitch, and/or rate.)

Raises:

ValueError – If any of the new values for speed, pitch, and/or rate are not greater than 0.

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the Timescale filter to a dictionary.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the Timescale filter values.

class harmonize.objects.Tremolo(frequency: float = 2.0, depth: float = 0.5)

Represents a tremolo filter. Extended from harmonize.abstract.Filter

update(*, frequency: float) → None

update(*, depth: float) → None

update(*, frequency: float, depth: float) → None

Updates the tremolo effect values.

Note

Frequency must be bigger than 0. Depth must be bigger than 0, and less than or equal to 1.

Parameters:

**kwargs (Keyword arguments containing the tremolo effect values to update.)

Raises:

ValueError – If either frequency or depth are not valid.

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the tremolo effect values to a dictionary.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the tremolo effect values.

class harmonize.objects.Vibrato(frequency: float = 2.0, depth: float = 0.5)

Represents a vibrato filter. Extended from harmonize.abstract.Filter

update(*, frequency: float) → None

update(*, depth: float) → None

update(*, frequency: float, depth: float) → None

Updates the vibrato effect values.

Note

Frequency must be bigger than 0, and less than or equal to 14. Depth must be bigger than 0, and less than or equal to 1.

Parameters:

**kwargs (Keyword arguments containing the vibrato effect values to update.)

Raises:

ValueError – If either frequency or depth are not valid.

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the vibrato effect values to a dictionary.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the vibrato effect values.

class harmonize.objects.Rotation(rotation_hz: float = 0.0)

Represents a rotation filter. Extended from harmonize.abstract.Filter

update(*, rotation_hz: float) → None

Updates the Rotation filter with a new rotation frequency.

Note

Rotation_hz must be bigger than or equal to 0

Parameters:

rotation_hz (float) – The new rotation frequency in hertz.

Raises:

ValueError – If rotation_hz is less than 0.:

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the Rotation filter to a dictionary representation.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the rotation frequency in hertz.

class harmonize.objects.LowPass(smoothing: float = 20.0)

Represents a low pass filter. Extended from harmonize.abstract.Filter

update(*, smoothing: float) → None

Updates the LowPass filter with a new smoothing value.

Parameters:

smoothing (float) – The new smoothing value. Must be bigger than 1.

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the LowPass filter to a dictionary.

Returns:

dict[str, dict[str, float]]

Return type:

A dictionary containing the LowPass filter’s smoothing value.

class harmonize.objects.ChannelMix(left_to_left: float = 1.0, left_to_right: float = 0.0, right_to_left: float = 0.0, right_to_right: float = 0.0)

Represents a channel mix filter. Extended from harmonize.abstract.Filter

update(left_to_left: float) → None

update(left_to_right: float) → None

update(right_to_left: float) → None

update(right_to_right: float) → None

Updates the channel mix values of the filter.

Note

All parameters must be bigger than or equal to 0, and less than or equal to 1.

Parameters:

**kwargs – A dictionary containing the new channel mix values to update.

Returns:

This function does not return any value. It updates the internal state of the filter.

Return type:

None

Raises:

ValueError – If any of the new channel mix values are not within the range [0, 1].

to_dict() → dict[str, dict[str, float]]

Converts the ChannelMix filter to a dictionary.

Returns:

A dictionary containing the channel mix values.

Return type:

dict[str, dict[str, float]]

class harmonize.objects.Volume(volume: float = 1.0)

Represents a volume filter. Extended from harmonize.abstract.Filter

update(*, volume: float) → None

Modifies the player volume.

Note

Volume must be bigger than or equal to 0, and less than or equal to 5

Parameters:

volume (float) – The new volume of the player. 1.0 means 100%/default.

Raises:

ValueError – If volume is not within the valid range.

Return type:

None

to_dict() → dict[str, float]

Converts the volume filter to a dictionary representation.

Returns:

dict[str, float]

Return type:

A dictionary containing the volume filter’s values.

class harmonize.objects.Distortion(sin_offset: float = 0.0, sin_scale: float = 1.0, cos_offset: float = 0.0, cos_scale: float = 1.0, tan_offset: float = 0.0, tan_scale: float = 1.0, offset: float = 0.0, scale: float = 1.0)

Represents a distortion filter. Extended from harmonize.abstract.Filter

update(sin_offset: float) → None

update(sin_scale: float) → None

update(cos_offset: float) → None

update(cos_scale: float) → None

update(tan_offset: float) → None

update(tan_scale: float) → None

update(offset: float) → None

update(scale: float) → None

Updates the distortion filter’s values.

Parameters:

**kwargs (Keyword arguments to update the filter's values. See above)

Return type:

None

to_dict() → dict[str, dict[str, float]]

Converts the distortion filter to a dictionary representation.

Returns:

A dictionary containing the distortion filter’s values.

Return type:

dict[str, dict[str, float]]