Filters¶

Filters is the top-level container for all audio filters. Retrieve from a player, modify, and apply.

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

# Reset all filters
await player.set_filters()

Guide

See the Filters Guide for presets (nightcore, bass boost, 8D audio) and recipes.

Filters ¶

Filters(*, data: FilterPayload | None = None)

The revvlink Filters class.

This class contains the information associated with each of Lavalinks filter objects, as Python classes. Each filter can be set or reset individually.

Using set on an individual filter only updates any new values you pass. Using reset on an individual filter, resets its payload, and can be used before set when you want a clean state for that filter.

See: :meth:~revvlink.Filters.reset to reset every individual filter.

This class is already applied an instantiated on all new :class:~revvlink.Player.

See: :meth:~revvlink.Player.set_filters for information on applying this class to your :class:~revvlink.Player. See: :attr:~revvlink.Player.filters for retrieving the applied filters.

To retrieve the payload for this Filters class, you can call an instance of this class.

Examples:

python3

import revvlink

# Create a brand new Filters and apply it...
# You can use player.set_filters() for an easier way to reset.
filters: revvlink.Filters = revvlink.Filters()
await player.set_filters(filters)


# Retrieve the payload of any Filters instance...
filters: revvlink.Filters = player.filters
print(filters())


# Set some filters...
# You can set and reset individual filters at the same time...
filters: revvlink.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 a filter...
filters: revvlink.Filters = player.filters
filters.timescale.reset()

await player.set_filters(filters)


# Reset all filters...
filters: revvlink.Filters = player.filters
filters.reset()

await player.set_filters(filters)


# Reset and apply filters easier method...
await player.set_filters()

volume `property` `writable` ¶

volume: float | None

The volume multiplier for the player.

Adjusts the volume multiplier for the player from 0.0 to 5.0, where 1.0 is 100%. Values > 1.0 may cause clipping.

Returns:

Type	Description
`float \| None`	The current volume multiplier, or `None` if not set.

equalizer `property` ¶

equalizer: Equalizer

Property which returns the :class:~revvlink.Equalizer filter associated with this Filters payload.

karaoke `property` ¶

karaoke: Karaoke

Property which returns the :class:~revvlink.Karaoke filter associated with this Filters payload.

timescale `property` ¶

timescale: Timescale

The :class:~revvlink.Timescale filter associated with this payload.

Returns:

Type	Description
class:`~revvlink.Timescale`	The timescale filter.

tremolo `property` ¶

tremolo: Tremolo

Property which returns the :class:~revvlink.Tremolo filter associated with this Filters payload.

vibrato `property` ¶

vibrato: Vibrato

Property which returns the :class:~revvlink.Vibrato filter associated with this Filters payload.

rotation `property` ¶

rotation: Rotation

Property which returns the :class:~revvlink.Rotation filter associated with this Filters payload.

distortion `property` ¶

distortion: Distortion

Property which returns the :class:~revvlink.Distortion filter associated with this Filters payload.

channel_mix `property` ¶

channel_mix: ChannelMix

Property which returns the :class:~revvlink.ChannelMix filter associated with this Filters payload.

low_pass `property` ¶

low_pass: LowPass

Property which returns the :class:~revvlink.LowPass filter associated with this Filters payload.

plugin_filters `property` ¶

plugin_filters: PluginFilters

The :class:~revvlink.PluginFilters associated with this payload.

Returns:

Type	Description
class:`~revvlink.PluginFilters`	The plugin filters.

set_filters ¶

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

Set multiple filters at once to a standalone Filter object. To set the filters to the player directly see :meth:revvlink.Player.set_filters

Parameters:

Name	Description	Default
`volume`	The Volume filter to apply to the player.	required
`equalizer`	The Equalizer filter to apply to the player.	required
`karaoke`	The Karaoke filter to apply to the player.	required
`timescale`	The Timescale filter to apply to the player.	required
`tremolo`	The Tremolo filter to apply to the player.	required
`vibrato`	The Vibrato filter to apply to the player.	required
`rotation`	The Rotation filter to apply to the player.	required
`distortion`	The Distortion filter to apply to the player.	required
`channel_mix`	The ChannelMix filter to apply to the player.	required
`low_pass`	The LowPass filter to apply to the player.	required
`plugin_filters`	The extra Plugin Filters to apply to the player. See :class:`~revvlink.PluginFilters` for more details.	required
`reset`	Whether to reset all filters that were not specified.	required

reset ¶

reset() -> None

Method which resets this object to an original state.

This method will clear all individual filters, and assign the revvlink default classes.

from_filters `classmethod` ¶

from_filters(**filters: Unpack[FiltersOptions]) -> Self

Creates a Filters object with specified filters.

Parameters:

Name	Description	Default
`volume`	The Volume filter to apply to the player.	required
`equalizer`	The Equalizer filter to apply to the player.	required
`karaoke`	The Karaoke filter to apply to the player.	required
`timescale`	The Timescale filter to apply to the player.	required
`tremolo`	The Tremolo filter to apply to the player.	required
`vibrato`	The Vibrato filter to apply to the player.	required
`rotation`	The Rotation filter to apply to the player.	required
`distortion`	The Distortion filter to apply to the player.	required
`channel_mix`	The ChannelMix filter to apply to the player.	required
`low_pass`	The LowPass filter to apply to the player.	required
`plugin_filters`	The extra Plugin Filters to apply to the player. See :class:`~revvlink.PluginFilters` for more details.	required
`reset`	Whether to reset all filters that were not specified.	required

Equalizer ¶

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

Equalizer Filter Class.

There are 15 bands 0 to 14 that can be changed. Each band has a gain which is the multiplier for the given band. gain defaults to 0.

Valid gain values range from -0.25 to 1.0, where -0.25 means the given band is completely muted, and 0.25 means it will be doubled.

Modifying the gain could also change the volume of the output.

Initialize an Equalizer filter.

Parameters:

Name	Type	Description	Default
`payload`	`list[Equalizer] \| None`	An optional list of 15 bands to initialize the equalizer with. Each dictionary should contain the keys `band` and `gain`. If not provided, all bands will be initialized with a gain of `0.0`.	`None`

payload `property` ¶

payload: dict[int, Equalizer]

The raw payload associated with this filter.

Returns:

Type	Description
dict[int, :class:`~revvlink.types.filters.Equalizer`]	A copy of the equalizer payload.

set ¶

set(**options: Unpack[EqualizerOptions]) -> Self

Set the bands of the Equalizer.

This method changes all bands, resetting any bands not provided to 0.0.

Parameters:

Name	Type	Description	Default
`bands`		A list of dictionary objects containing `band` and `gain`. `band` must be an integer between `0` and `14`. `gain` must be a float between `-0.25` and `1.0`.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset the Equalizer to its default state.

Returns:

Type	Description
`Self`	The current instance for chaining.

Timescale ¶

Timescale(payload: Timescale)

Bases: _BaseFilter[Timescale]

Timescale Filter class.

Changes the speed, pitch, and rate.

payload `property` ¶

payload: Timescale

The raw payload associated with this filter.

This property returns a copy.

set ¶

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

Set the properties of the Timescale filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Description	Default
`speed`	The playback speed.	required
`pitch`	The pitch multiplier.	required
`rate`	The rate multiplier.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

Karaoke ¶

Karaoke(payload: Karaoke)

Bases: _BaseFilter[Karaoke]

Karaoke Filter class.

Uses equalization to eliminate part of a band, usually targeting vocals.

payload `property` ¶

payload: Karaoke

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[KaraokeOptions]) -> Self

Set the properties of the Karaoke filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Description	Default
`level`	The vocal elimination level, between `0.0` and `1.0`.	required
`mono_level`	The mono level, between `0.0` and `1.0`.	required
`filter_band`	The filter band in Hz.	required
`filter_width`	The filter width.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

Tremolo ¶

Tremolo(payload: Tremolo)

Bases: _BaseFilter[Tremolo]

The Tremolo Filter class.

Uses amplification to create a shuddering effect, where the volume quickly oscillates. Demo: https://en.wikipedia.org/wiki/File:Fuse_Electronics_Tremolo_MK-III_Quick_Demo.ogv

payload `property` ¶

payload: Tremolo

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[Tremolo]) -> Self

Set the properties of the Tremolo filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Type	Description	Default
`frequency`		The frequency of the oscillations.	required
`depth`		The tremolo depth.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

Vibrato ¶

Vibrato(payload: Vibrato)

Bases: _BaseFilter[Vibrato]

The Vibrato Filter class.

Similar to tremolo. While tremolo oscillates the volume, vibrato oscillates the pitch.

payload `property` ¶

payload: Vibrato

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[Vibrato]) -> Self

Set the properties of the Vibrato filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Type	Description	Default
`frequency`		The frequency of the oscillations.	required
`depth`		The vibrato depth.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

Rotation ¶

Rotation(payload: Rotation)

Bases: _BaseFilter[Rotation]

The Rotation Filter class.

Rotates the sound around the stereo channels/user headphones (aka Audio Panning). It can produce an effect similar to https://youtu.be/QB9EB8mTKcc (without the reverb).

payload `property` ¶

payload: Rotation

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[RotationOptions]) -> Self

Set the properties of the Rotation filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Type	Description	Default
`rotation_hz`		The frequency of the audio rotating around the listener in Hz. `0.2` is a good starting point.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

Distortion ¶

Distortion(payload: Distortion)

Bases: _BaseFilter[Distortion]

The Distortion Filter class.

According to Lavalink "It can generate some pretty unique audio effects."

payload `property` ¶

payload: Distortion

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[DistortionOptions]) -> Self

Set the properties of the Distortion filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Description	Default
`sin_offset`	The sin offset.	required
`sin_scale`	The sin scale.	required
`cos_offset`	The cos offset.	required
`cos_scale`	The cos scale.	required
`tan_offset`	The tan offset.	required
`tan_scale`	The tan scale.	required
`offset`	The offset.	required
`scale`	The scale.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

ChannelMix ¶

ChannelMix(payload: ChannelMix)

Bases: _BaseFilter[ChannelMix]

The ChannelMix Filter class.

Mixes both channels (left and right), with a configurable factor on how much each channel affects the other. With the defaults, both channels are kept independent of each other.

Setting all factors to 0.5 means both channels get the same audio.

payload `property` ¶

payload: ChannelMix

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[ChannelMixOptions]) -> Self

Set the properties of the ChannelMix filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Description	Default
`left_to_left`	The left to left channel mix factor. Between `0.0` and `1.0`.	required
`left_to_right`	The left to right channel mix factor. Between `0.0` and `1.0`.	required
`right_to_left`	The right to left channel mix factor. Between `0.0` and `1.0`.	required
`right_to_right`	The right to right channel mix factor. Between `0.0` and `1.0`.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

LowPass ¶

LowPass(payload: LowPass)

Bases: _BaseFilter[LowPass]

The LowPass Filter class.

Higher frequencies get suppressed, while lower frequencies pass through this filter, thus the name low pass. Any smoothing values equal to or less than 1.0 will disable the filter.

payload `property` ¶

payload: LowPass

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: Unpack[LowPass]) -> Self

Set the properties of the LowPass filter.

This method accepts keyword argument pairs. This method does not override existing settings if they are not provided.

Parameters:

Name	Type	Description	Default
`smoothing`		The smoothing factor. Higher values mean more smoothing. Values `<= 1.0` disable the filter.	required

Returns:

Type	Description
`Self`	The current instance for chaining.

reset ¶

reset() -> Self

Reset this filter to its defaults.

PluginFilters ¶

PluginFilters(payload: dict[str, Any])

Bases: _BaseFilter[dict[str, Any]]

The PluginFilters class.

This class handles setting filters on plugins that support setting filter values. See the documentation of the Lavalink Plugin for more information on the values that can be set.

This class takes in a dict[str, Any] usually in the form of:

python3

{"pluginName": {"filterKey": "filterValue"}, ...}

⚠Warning

Do NOT include the "pluginFilters" top level key when setting your values for this class.

payload `property` ¶

payload: dict[str, Any]

The raw payload associated with this filter.

This property returns a copy.

set ¶

set(**options: dict[str, Any]) -> Self

Set the properties of this filter.

This method accepts keyword argument pairs OR you can alternatively unpack a dictionary. See the documentation of the Lavalink Plugin for more information on the values that can be set.

Examples:

python3

plugin_filters: PluginFilters = PluginFilters()
plugin_filters.set(pluginName={"filterKey": "filterValue", ...})

# OR...

plugin_filters.set(**{"pluginName": {"filterKey": "filterValue", ...}})

reset ¶

reset() -> Self

Reset this filter to its defaults.

Filters¶

Filters ¶

volume property writable ¶

equalizer property ¶

karaoke property ¶

timescale property ¶

tremolo property ¶

vibrato property ¶

rotation property ¶

distortion property ¶

channel_mix property ¶

low_pass property ¶

plugin_filters property ¶

set_filters ¶

reset ¶

from_filters classmethod ¶

Equalizer ¶

payload property ¶

set ¶

reset ¶

Timescale ¶

payload property ¶

set ¶

reset ¶

Karaoke ¶

payload property ¶

set ¶

reset ¶

Tremolo ¶

payload property ¶

set ¶

reset ¶

Vibrato ¶

payload property ¶

set ¶

reset ¶

Rotation ¶

payload property ¶

set ¶

reset ¶

Distortion ¶

payload property ¶

set ¶

reset ¶

ChannelMix ¶

payload property ¶

set ¶

reset ¶

LowPass ¶

payload property ¶

set ¶

reset ¶

PluginFilters ¶

payload property ¶

set ¶

reset ¶

volume `property` `writable` ¶

equalizer `property` ¶

karaoke `property` ¶

timescale `property` ¶

tremolo `property` ¶

vibrato `property` ¶

rotation `property` ¶

distortion `property` ¶

channel_mix `property` ¶

low_pass `property` ¶

plugin_filters `property` ¶

from_filters `classmethod` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶

payload `property` ¶