diff --git a/docs/migrating.rst b/docs/migrating.rst index 989f77c3..3bc7ad07 100644 --- a/docs/migrating.rst +++ b/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 diff --git a/docs/wavelink.rst b/docs/wavelink.rst index e4c25d9b..16dbe552 100644 --- a/docs/wavelink.rst +++ b/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 ----- diff --git a/wavelink/payloads.py b/wavelink/payloads.py index 2edc46f2..e869e37a 100644 --- a/wavelink/payloads.py +++ b/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 diff --git a/wavelink/websocket.py b/wavelink/websocket.py index 96222563..c13b5e8f 100644 --- a/wavelink/websocket.py +++ b/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.")