Merge pull request #263 from PythonistaGuild/feature/extra-events

Add extra_event for unknown plugin events

docs/migrating.rst

@@ -86,6 +86,7 @@ Added
 - :meth:`wavelink.Node.fetch_player_info`
 - :meth:`wavelink.Node.fetch_players`
 - :attr:`wavelink.Playable.extras`
+- :func:`wavelink.on_wavelink_extra_event`
 
 
 Connecting

docs/wavelink.rst

@@ -77,6 +77,18 @@ An event listener in a cog.
     Called when a node has been closed and cleaned-up. The second parameter ``disconnected`` is a list of
     :class:`wavelink.Player` that were connected on this Node and are now disconnected.
 
+.. function:: on_wavelink_extra_event(payload: wavelink.ExtraEventPayload)
+
+    Called when an ``Unknown`` and/or ``Unhandled`` event is recevied via Lavalink. This is most likely due to
+    a plugin like SponsorBlock sending custom event data. The payload includes the raw data sent from Lavalink.
+
+    .. note::
+
+        Please see the documentation for your Lavalink plugins to determine what data they send.
+
+
+    .. versionadded:: 3.1.0
+
 
 Types
 -----
@@ -190,6 +202,11 @@ Payloads
 .. autoclass:: InfoResponsePayload
     :members:
 
+.. attributetable:: ExtraEventPayload
+
+.. autoclass:: ExtraEventPayload
+    :members:
+
 
 Enums
 -----

wavelink/payloads.py

@@ -62,6 +62,7 @@
     "PlayerStatePayload",
     "VoiceStatePayload",
     "PlayerResponsePayload",
+    "ExtraEventPayload",
 )
 
 
@@ -520,3 +521,33 @@ def __init__(self, data: InfoResponse) -> None:
         self.source_managers: list[str] = data["sourceManagers"]
         self.filters: list[str] = data["filters"]
         self.plugins: list[PluginResponsePayload] = [PluginResponsePayload(p) for p in data["plugins"]]
+
+
+class ExtraEventPayload:
+    """Payload received in the :func:`on_wavelink_extra_event` event.
+
+    This payload is created when an ``Unknown`` and ``Unhandled`` event is received from Lavalink, most likely via
+    a plugin.
+
+    .. note::
+
+        See the appropriate documentation of the plugin for the data sent with these events.
+
+
+    Attributes
+    ----------
+    node: :class:`~wavelink.Node`
+        The node that the event pertains to.
+    player: :class:`~wavelink.Player` | None
+        The player associated with this event. Could be None.
+    data: dict[str, Any]
+        The raw data sent from Lavalink for this event.
+
+
+    .. versionadded:: 3.1.0
+    """
+
+    def __init__(self, *, node: Node, player: Player | None, data: dict[str, Any]) -> None:
+        self.node = node
+        self.player = player
+        self.data = data

wavelink/websocket.py

@@ -239,7 +239,8 @@ async def keep_alive(self) -> None:
                     self.dispatch("websocket_closed", wcpayload)
 
                 else:
-                    logger.debug(f"Received unknown event type from Lavalink '{data['type']}'. Disregarding.")
+                    other_payload: ExtraEventPayload = ExtraEventPayload(node=self.node, player=player, data=data)
+                    self.dispatch("extra_event", other_payload)
             else:
                 logger.debug(f"'Received an unknown OP from Lavalink '{data['op']}'. Disregarding.")