Update dev to Lavalink.py 4.0 (#121)

* Rename some errors, support Union[int, str] for user_id

* Expose AuthenticationError

* Ambiguous no more

* Update get_tracks returns

* Fix dispatching to empty hook lists

* Bump aiohttp

* Fix slight mistake in example cog.

* Readme QoL change.

* Use a link reference instead

* Start on filter stuff

* Update license stuff

* Fix CI badge

* Fix broken doc ref

* Finishing up filter stuff maybe

* Specify decode_errors when decoding author too

* Exceptions -> Errors, more reliably pull WS close code, handle ConnectionResetError

* Didn't mean to push this loool

* Add utfm decoding capabilities

* Fix equalizer failing to serialize

* forgot an await, oops

* Reorder player_manager funcs

* Fix docs & expand parameter names

* Update Lavalink URL

* Fix Python 3.5 support not displayed in badge (#109)

lol

* Update example to use voice client (#116)

* Update example to use voice client

discord.py 2.0 removed the `on_socket_response` event. This resulted in
Lavalink.py not being able to forward the events. At least in the
current implementation of the example.
We now use the preferred way of using the VoiceProtocol to forward the
voice events to Lavalink.

* Set player.channel_id to None manually

* support new lavalink exception format (#105)

* Bump min aiohttp version

* Update copyright

* who did this

* Update license 2

* Making a note of this issue

* Bump aiohttp upper version

* Slight adjustments to strings

* Expose previously unused variables 'position' and 'encoder_version'

* Clarify some units in Stats.py

* Logging message consistency

* Remove superfluous log call in _node_disconnect

* Logging consistency

* Init node with empty stats object

* scheisse

* Redundant logic check as this will be zero anyway

* int() guild_id in create, add doc link to DefaultPlayer

* Doc consistency in playermanager.py

* Document player.channel_id attr

* More documentation updates

* Finalise guild_id -> int change

* Lavalink.py v4.0.0

* 0.0 is the default gain

* Add timestamp_to_millis helper function.

* Linting

* Register auto docs for new things

* Minor docs changes again

* How much other stuff is missing???

* cmon

* Fixing docs build error

* Add filter limits, allow passing str to Player.X_filter, add filter TODOs

* Fix docs formatting

* Add missing list call

* Avoid handling TrackStartEvent to prevent None being fired

* Rotation filter

* Low Pass filter

* Add channelmix + lint

* Add missing __ to init

* Add filter command to example cog.

* Lavalink appears to have exception handling for this...

* Mark set_gain(s) & reset_equalizer as deprecated, add docs for remove_filter.

* Enlarge deprecation warning

* Move deprecation warning last to ensure func summary still works as intended

* Distortion filter

* Lint

* New year new me xx

* doc stuff

* forgot to cd out of docs/

* update readme badge

* Support volume filter

* Enforce 0 < volume < 5

* Support connected in PlayerUpdateEvent

* Linting

* Small cleanups

* new codacy badge

* Implement DeferredAudioTrack

* Linting

* Imports & docs

* Custom source support

* Implement hash for source

* Implement handling for info attribute access in AudioTrack

* More docstrings, a little more consistency

* Clarify docs.

* Adjust player.add parameters, docs

* Fix an issue with track needing to be declared, improve compatibility

* Oversight

* Implement two more docstrings in Client.

* Custom Source provider example

* If check to avoid returning bogus track on every query.

* Enum documentation

* missing ,

* self._raw in AudioTrack

* slotssssssss

* lets gloss over this ok

* Copy-paste RIP

* Fix typo in custom_source.py

* Add player.destroy shortcut

* Reluctantly support passing AudioTrack to AudioTrack

* Don't overwrite requester

* Remove AudioTrack construction from example cog

* Access attributes directly in example cog

* Filter descriptions.

* an -> a

* Support position + sourceName fields

* Correctly reflect that track is Optional

* Close any existing websockets before connecting

* support volume + pause in play op

* Fix volume not having an immediate effect

* Add @lavalink.listener decorator support

* Clarify listener decorator

* forgot to cd out of docs again lol

* Add player.update_filter, improve docs

* Ensure provided filter is a class not instance

* Instances passed to issubclass will throw, catch that.

* subclass check in other x_filter commands

* Add custom source to README

* Updating readme

* Reducing duplicated code in client

* Fixing a slight oversight

* Sorting out comment lines a little lol

* Remove unused import from example/music.py

* Experimental command-line tools

* Support SSL on nodes

* Use pythonic naming

* Add clear_filters()

* Only apply endTime if > 0

* On second thoughts, move endTime check AFTER sanity check

Co-authored-by: AlexFlipnote <[email protected]>
Co-authored-by: sh0tx420 <[email protected]>
Co-authored-by: Eric Schneider <[email protected]>
Co-authored-by: Rob Wainwright <[email protected]>

Author: 5 people

README.md

@@ -1,18 +1,25 @@
+[Lavalink]: https://github.com/freyacodes/Lavalink
+[Documentation]: https://lavalink.readthedocs.io/en/master/
+[Latest Docs]: https://lavalink.readthedocs.io/en/latest/
+
 <img align="right" src="https://serux.pro/9e83af1581.png" height="150" width="150">
 
 # Lavalink.py
-[![Python](https://img.shields.io/badge/Python-3.6%20%7C%203.7%20%7C%203.8-blue.svg)](https://www.python.org) [![Build Status](https://travis-ci.com/devoxin/Lavalink.py.svg?branch=master)](https://travis-ci.com/Devoxin/Lavalink.py) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/5f4c2517818042c593c57f911ff61062)](https://www.codacy.com/manual/Devoxin/Lavalink.py?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=Devoxin/Lavalink.py&amp;utm_campaign=Badge_Grade) [![License](https://img.shields.io/github/license/Devoxin/Lavalink.py.svg)](LICENSE) [![Documentation Status](https://readthedocs.org/projects/lavalink/badge/?version=latest)](https://lavalink.readthedocs.io/en/latest/?badge=latest)
+[![Python](https://img.shields.io/badge/Python-3.5%20%7C%203.6%20%7C%203.7%20%7C%203.8%20%7C%203.9%20%7C%203.10-blue.svg)](https://www.python.org) [![Build Status](https://travis-ci.com/devoxin/Lavalink.py.svg?branch=master)](https://travis-ci.com/Devoxin/Lavalink.py) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/428eebed5a2e467fb038eacfa1d92e62)](https://www.codacy.com/gh/Devoxin/Lavalink.py/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=Devoxin/Lavalink.py&amp;utm_campaign=Badge_Grade) [![License](https://img.shields.io/github/license/Devoxin/Lavalink.py.svg)](LICENSE) [![Documentation Status](https://readthedocs.org/projects/lavalink/badge/?version=latest)](https://lavalink.readthedocs.io/en/latest/?badge=latest)
+
+Lavalink.py is a wrapper for [Lavalink] which abstracts away most of the code necessary to use Lavalink, allowing for easier integration into your projects, while still promising full API coverage and powerful tools to get the most out of it.
 
-Lavalink.py is a wrapper for [Lavalink](https://github.com/Frederikam/Lavalink) which abstracts away most of the code necessary to use Lavalink, allowing for easier integration into your projects, while still promising full API coverage and powerful tools to get the most out of it.
+# What is Lavalink?
+Lavalink is standalone audio sending software capable of transmitting audio to Discord, utilising Lavaplayer for audio transcoding. It can be configured to work independently, or as part of a cluster depending on needs, which allows it to be highly scalable and performant. Head over to the [Lavalink] repository to find out more.
 
 # Getting Started
 First you need to run a command to install the library,
 ```shell
 pip install lavalink
 ```
 
-Then you need to setup the Lavalink server, you will need to install Java, and then download the latest [Lavalink.jar](https://github.com/Frederikam/Lavalink/releases/).
-Then place an ``application.yml`` file in the same directory. The file should look like [this](https://github.com/Frederikam/Lavalink/blob/master/LavalinkServer/application.yml.example/). Finally run `java -jar Lavalink.jar` in the directory of the jar.
+Then you need to setup the Lavalink server, you will need to install Java, and then download the latest [Lavalink.jar](https://github.com/freyacodes/Lavalink/releases/).
+Then place an ``application.yml`` file in the same directory. The file should look like [this](https://github.com/freyacodes/Lavalink/blob/master/LavalinkServer/application.yml.example/). Finally run `java -jar Lavalink.jar` in the directory of the jar.
 
 Additionally, there is an [example cog](examples). It should be noted that the example cog is oriented towards usage with Discord.py rewrite and Lavalink v3.1+, although backwards
 compatibility may be possible, it's not encouraged nor is support guaranteed.
@@ -21,7 +28,8 @@ compatibility may be possible, it's not encouraged nor is support guaranteed.
 - Regions
 - Multi-Node Support
 - Load Balancing (this includes region-based load balancing)
-- Equalizer
+- Audio Filters
+- [Custom Sources](examples/custom_source.py)
 
 ## Optional Dependencies
 *These are used by aiohttp.*
@@ -39,7 +47,7 @@ It is highly recommended that you invest in a dedicated server or a [VPS](https:
 The exception to the "unsupported platforms" rule are ARM-based machines, for example; a Raspberry Pi. While official Lavalink builds do not support the ARM architecture, there are [custom builds by Cog-Creators](https://github.com/Cog-Creators/Lavalink-Jars/releases) that offer ARM support. These are the official builds, with additional native libraries for running on otherwise unsupported platforms.
 
 
-## Need Further Help? 
-[Discord Server](https://discord.gg/SbJXU9s) 
+## Need Further Help?
+[Discord Server](https://discord.gg/SbJXU9s)
 
-[Documentation](https://lavalink.readthedocs.io/en/latest/)
+[Documentation] or [Latest Docs] (for Lavalink.py 4.0)

docs/_static/style.css

@@ -15,5 +15,23 @@
 }
 
 code {
-    padding: 0px; !important
-}
+    padding: 0px !important;
+}
+
+div.deprecated {
+  margin: 20px 0;
+  padding: 20px;
+  background-color: #fff;
+  border-radius: 3px;
+  color: #333;
+  overflow: auto;
+  border-width: 0 0 0 2px;
+  border-color: #ff5858;
+  border-style: solid;
+  padding-right: 0;
+}
+
+span.deprecated {
+display: block;
+font-size: large;
+}

docs/conf.py

@@ -19,7 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Lavalink.py'
-copyright = '2020, Devoxin'
+copyright = '2022, Devoxin'
 author = 'Devoxin'
 master_doc = 'index'
 
@@ -41,6 +41,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'guzzle_sphinx_theme',
+    'enum_tools.autoenum'
 ]
 
 rst_prolog = """
@@ -88,6 +89,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['style.css']
 
 # html_context = {
 #     'css_files': ['_static/style.css']

docs/index.rst

@@ -17,14 +17,14 @@ Welcome to Lavalink.py's documentation!
 
 \
     Lavalink.py is a wrapper for which `Lavalink
-    <https://github.com/Frederikam/Lavalink/>`_ abstracts away most of the code necessary to use Lavalink to allow for easier integration into your bots, while still promising full API coverage and powerful tools to get the most out of it.
+    <https://github.com/freyacodes/Lavalink/>`_ abstracts away most of the code necessary to use Lavalink to allow for easier integration into your bots, while still promising full API coverage and powerful tools to get the most out of it.
 
     **Features:**
 
     - Regions
     - Multi-Node Support
     - Load Balancing (this includes region-based load balancing)
-    - Equalizer
+    - Audio Filters
 
     **Support:**
 
@@ -33,4 +33,4 @@ Welcome to Lavalink.py's documentation!
 
 :ref:`genindex`
 
-:ref:`search`
+:ref:`search`

docs/lavalink.rst

@@ -5,13 +5,23 @@ Documentation
 
 .. autofunction:: enable_debug_logging
 
+.. autofunction:: listener
+
 .. autofunction:: add_event_hook
 
 Client
 ------
 .. autoclass:: Client
     :members:
 
+Errors
+------
+.. autoclass:: NodeError
+
+.. autoclass:: AuthenticationError
+
+.. autoclass:: InvalidTrack
+
 Events
 ------
 All Events are derived from :class:`Event`
@@ -22,37 +32,89 @@ All Events are derived from :class:`Event`
 .. autoclass:: TrackStartEvent
     :members:
 
-.. autoclass:: TrackEndEvent
-    :members:
-
 .. autoclass:: TrackStuckEvent
     :members:
 
 .. autoclass:: TrackExceptionEvent
     :members:
 
+.. autoclass:: TrackEndEvent
+    :members:
+
 .. autoclass:: QueueEndEvent
     :members:
 
-.. autoclass:: NodeConnectedEvent
+.. autoclass:: PlayerUpdateEvent
     :members:
 
-.. autoclass:: NodeChangedEvent
+.. autoclass:: NodeConnectedEvent
     :members:
 
 .. autoclass:: NodeDisconnectedEvent
     :members:
 
+.. autoclass:: NodeChangedEvent
+    :members:
+
 .. autoclass:: WebSocketClosedEvent
     :members:
 
+Filters
+-------
+**All** custom filters must derive from :class:`Filter`
+
+.. autoclass:: Filter
+    :members:
+
+.. autoclass:: Equalizer
+    :members:
+
+.. autoclass:: Karaoke
+    :members:
+
+.. autoclass:: Timescale
+    :members:
+
+.. autoclass:: Tremolo
+    :members:
+
+.. autoclass:: Vibrato
+    :members:
+
+.. autoclass:: Rotation
+    :members:
+
+.. autoclass:: LowPass
+    :members:
+
+.. autoclass:: ChannelMix
+    :members:
+
+.. autoclass:: Volume
+    :members:
+
 Models
 ------
 **All** custom players must derive from :class:`BasePlayer`
 
 .. autoclass:: AudioTrack
     :members:
 
+.. autoclass:: DeferredAudioTrack
+    :members:
+
+.. autoenum:: LoadType
+    :members:
+
+.. autoclass:: PlaylistInfo
+    :members:
+
+.. autoclass:: LoadResult
+    :members:
+
+.. autoclass:: Source
+    :members:
+
 .. autoclass:: BasePlayer
     :members:
 
@@ -84,8 +146,10 @@ Stats
 
 Utilities
 ---------
+.. autofunction:: timestamp_to_millis
+
 .. autofunction:: format_time
 
 .. autofunction:: parse_time
 
-.. autofunction:: decode_track
+.. autofunction:: decode_track

docs/license.rst

@@ -4,7 +4,7 @@ Licensed using the `MIT license <http://opensource.org/licenses/MIT>`_.
 
     MIT License
 
-    Copyright (c) 2019 Luke & William
+    Copyright (c) 2022 Devoxin
 
     Permission is hereby granted, free of charge, to any person obtaining a copy
     of this software and associated documentation files (the "Software"), to deal

docs/quickstart.rst

@@ -3,14 +3,14 @@ Quickstart
 
 Setting up Lavalink server
 --------------------------
-Download the latest `Lavalink.jar <https://github.com/Frederikam/Lavalink/releases/>`_
-Place an ``application.yml`` file in the same directory. The file should look like `this <https://github.com/Frederikam/Lavalink/blob/master/LavalinkServer/application.yml.example/>`_.
+Download the latest `Lavalink.jar <https://github.com/freyacodes/Lavalink/releases/>`_
+Place an ``application.yml`` file in the same directory. The file should look like `this <https://github.com/freyacodes/Lavalink/blob/master/LavalinkServer/application.yml.example/>`_.
 
 Run ``java -jar Lavalink.jar`` in the directory of the jar.
 
 Using Lavalink.py
 -----------------
-This only applies if you are using the library `Discord.py <https://github.com/Rapptz/discord.py/>`_ and with `Lavalink v3.1+ <https://github.com/Frederikam/Lavalink/releases/>`_
+This only applies if you are using the library `Discord.py <https://github.com/Rapptz/discord.py/>`_ and with `Lavalink v3.1+ <https://github.com/freyacodes/Lavalink/releases/>`_
 Although backwards compatibility may be possible, it's not encouraged nor is support guaranteed.
 
 Place the `example cog <https://github.com/Devoxin/Lavalink.py/blob/master/examples/music.py>`_ in your cogs folder or anywhere in your bot's file directory.

examples/custom_source.py

@@ -0,0 +1,45 @@
+from lavalink.models import (DeferredAudioTrack, LoadResult, LoadType,
+                             PlaylistInfo, Source)
+
+
+class LoadError(Exception):  # We'll raise this if we have trouble loading our track.
+    pass
+
+
+class CustomAudioTrack(DeferredAudioTrack):
+    # A DeferredAudioTrack allows us to load metadata now, and a playback URL later.
+    # This makes the DeferredAudioTrack highly efficient, particularly in cases
+    # where large playlists are loaded.
+
+    async def load(self, client):  # Load our 'actual' playback track using the metadata from this one.
+        result: LoadResult = await client.get_tracks('ytsearch:{0.title} {0.author}'.format(self))  # Search for our track on YouTube.
+
+        if result.load_type != LoadType.SEARCH or not result.tracks:  # We're expecting a 'SEARCH' due to our 'ytsearch' prefix above.
+            raise LoadError
+
+        first_track = result.tracks[0]  # Grab the first track from the results.
+        base64 = first_track.track  # Extract the base64 string from the track.
+        self.track = base64  # We'll store this for later, as it allows us to save making network requests
+        # if this track is re-used (e.g. repeat).
+
+        return base64
+
+
+class CustomSource(Source):
+    def __init__(self):
+        super().__init__(name='custom')  # Initialising our custom source with the name 'custom'.
+
+    async def load_item(self, client, query: str):
+        if 'keyword' in query:
+            # track_metadata = http.get("https://our.provider/api/{}".format(query))
+
+            track = CustomAudioTrack({  # Create an instance of our CustomAudioTrack.
+                'identifier': '27cgqh0VRhVeM61ugTnorD',  # Fill it with metadata that we've obtained from our source's provider.
+                'isSeekable': True,
+                'author': 'DJ Seinfeld',
+                'length': 296000,
+                'isStream': False,
+                'title': 'These Things Will Come To Be',
+                'uri': 'https://open.spotify.com/track/27cgqh0VRhVeM61ugTnorD'
+                }, requester=0)  # Init requester with a default value.
+            return LoadResult(LoadType.TRACK, [track], playlist_info=PlaylistInfo.none())