recv

Author: DA-344

discord/opus.py

@@ -42,6 +42,8 @@
 from .sinks import RawData
 
 if TYPE_CHECKING:
+    from discord.voice.recorder import VoiceRecorderClient
+
     T = TypeVar("T")
     APPLICATION_CTL = Literal["audio", "voip", "lowdelay"]
     BAND_CTL = Literal["narrow", "medium", "wide", "superwide", "full"]
@@ -548,17 +550,17 @@ def decode(self, data, *, fec=False):
 
 
 class DecodeManager(threading.Thread, _OpusStruct):
-    def __init__(self, client):
+    def __init__(self, client: VoiceRecorderClient):
         super().__init__(daemon=True, name="DecodeManager")
 
-        self.client = client
-        self.decode_queue = []
+        self.client: VoiceRecorderClient = client
+        self.decode_queue: list[RawData] = []
 
-        self.decoder = {}
+        self.decoder: dict[int, Decoder] = {}
 
         self._end_thread = threading.Event()
 
-    def decode(self, opus_frame):
+    def decode(self, opus_frame: RawData):
         if not isinstance(opus_frame, RawData):
             raise TypeError("opus_frame should be a RawData object.")
         self.decode_queue.append(opus_frame)
@@ -579,26 +581,26 @@ def run(self):
                         data.decrypted_data
                     )
             except OpusError:
-                print("Error occurred while decoding opus frame.")
+                _log.exception("Error occurred while decoding opus frame.", exc_info=True)
                 continue
 
-            self.client.recv_decoded_audio(data)
+            self.client.receive_audio(data)
 
-    def stop(self):
+    def stop(self) -> None:
         while self.decoding:
             time.sleep(0.1)
             self.decoder = {}
             gc.collect()
-            print("Decoder Process Killed")
+            _log.debug("Decoder Process Killed")
         self._end_thread.set()
 
-    def get_decoder(self, ssrc):
+    def get_decoder(self, ssrc: int) -> Decoder:
         d = self.decoder.get(ssrc)
         if d is not None:
             return d
         self.decoder[ssrc] = Decoder()
         return self.decoder[ssrc]
 
     @property
-    def decoding(self):
+    def decoding(self) -> bool:
         return bool(self.decode_queue)

discord/sinks/core.py

@@ -224,7 +224,7 @@ def __init__(self, *, filters=None):
         self.audio_data = {}
 
     def init(self, vc):  # called under listen
-        self.vc: VoiceClient = vc
+        self.vc = vc
         super().init()
 
     @Filters.container

discord/voice/_types.py

@@ -25,27 +25,34 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Generic, TypeVar
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, Union
 
 if TYPE_CHECKING:
+    from typing_extensions import ParamSpec
+
     from discord import abc
     from discord.client import Client
     from discord.raw_models import (
         RawVoiceServerUpdateEvent,
         RawVoiceStateUpdateEvent,
     )
-    from discord.voice.client import VoiceClient
+    from discord.sinks import Sink
+
+    P = ParamSpec('P')
+    R = TypeVar('R')
+    RecordCallback = Union[Callable[P, R], Callable[P, Awaitable[R]]]
 
 ClientT = TypeVar("ClientT", bound="Client", covariant=True)
-VoiceClientT = TypeVar('VoiceClientT', bound='VoiceClient', covariant=True)
+VoiceProtocolT = TypeVar('VoiceProtocolT', bound='VoiceProtocol', covariant=True)
 
 
 class VoiceProtocol(Generic[ClientT]):
     """A class that represents the Discord voice protocol.
 
     .. warning::
 
-        If you are a end user, you **should not construct this manually** but instead
+        If you are an end user, you **should not construct this manually** but instead
         take it from the return type in :meth:`abc.Connectable.connect <VoiceChannel.connect>`.
         The parameters and methods being documented here is so third party libraries can refer to it
         when implementing their own VoiceProtocol types.
@@ -161,4 +168,99 @@ def cleanup(self) -> None:
         self.client._connection._remove_voice_client(key)
 
 
-class RecorderProtocol(Generic[VoiceClientT]):
+class VoiceRecorderProtocol(Generic[VoiceProtocolT]):
+    """A class that represents a Discord voice client recorder protocol.
+
+    .. warning::
+
+        If you are an end user, you **should not construct this manually** but instead
+        take it from a :class:`VoiceProtocol` implementation, like :attr:`VoiceClient.recorder`.
+        The parameters and methods being documented here is so third party libraries can refer to it
+        when implementing their own RecorderProtocol types.
+
+    This is an abstract class. The library provides a concrete implementation under
+    :class:`VoiceRecorderClient`.
+
+    This class allows you to implement a protocol to allow for an external
+    method of receiving and handling voice data.
+
+    .. versionadded:: 2.7
+
+    Parameters
+    ----------
+    client: :class:`VoiceProtocol`
+        The voice client (or its subclasses) that are bound to this recorder.
+    channel: :class:`abc.Connectable`
+        The voice channel that is being recorder. If not provided, defaults to
+        :attr:`VoiceProtocol.channel`
+    """
+
+    def __init__(self, client: VoiceProtocolT, channel: abc.Connectable | None = None) -> None:
+        self.client: VoiceProtocolT = client
+        self.channel: abc.Connectable = channel or client.channel
+
+    def get_ssrc(self, user_id: int) -> int:
+        """Gets the ssrc of a user.
+
+        Parameters
+        ----------
+        user_id: :class:`int`
+            The user ID to get the ssrc from.
+
+        Returns
+        -------
+        :class:`int`
+            The ssrc for the provided user ID.
+        """
+        raise NotImplementedError('subclasses must implement this')
+
+    def unpack(self, data: bytes) -> bytes | None:
+        """Takes an audio packet received from Discord and decodes it.
+
+        Parameters
+        ----------
+        data: :class:`bytes`
+            The bytes received by Discord.
+
+        Returns
+        -------
+        Optional[:class:`bytes`]
+            The unpacked bytes, or ``None`` if they could not be unpacked.
+        """
+        raise NotImplementedError('subclasses must implement this')
+
+    def record(
+        self,
+        sink: Sink,
+        callback: RecordCallback[P, R],
+        sync_start: bool,
+        *callback_args: P.args,
+        **callback_kwargs: P.kwargs,
+    ) -> None:
+        """Start recording audio from the current voice channel in the provided sink.
+
+        You must be in a voice channel.
+
+        Parameters
+        ----------
+        sink: :class:`~discord.Sink`
+            The sink to record to.
+        callback: Callable[..., Any]
+            The function called after the bot has stopped recording. This can take any arguments and
+            can return an awaitable.
+        sync_start: :class:`bool`
+            Whether the subsequent recording users will start with silence. This is useful for recording
+            audio just as it was heard.
+
+        Raises
+        ------
+        RecordingException
+            Not connected to a voice channel
+        TypeError
+            You did not pass a Sink object.
+        """
+        raise NotImplementedError('subclasses must implement this')
+
+    def stop(self) -> None:
+        """Stops recording."""
+        raise NotImplementedError('subclasses must implement this')

discord/voice/client.py

@@ -38,7 +38,7 @@
 
 from ._types import VoiceProtocol
 from .player import AudioPlayer
-from .recorder import Recorder
+from .recorder import VoiceRecorderClient
 from .source import AudioSource
 from .state import VoiceConnectionState
 
@@ -100,7 +100,13 @@ class VoiceClient(VoiceProtocol):
 
     channel: VocalGuildChannel
 
-    def __init__(self, client: Client, channel: abc.Connectable) -> None:
+    def __init__(
+        self,
+        client: Client,
+        channel: abc.Connectable,
+        *,
+        use_recorder: bool = True,
+    ) -> None:
         if not has_nacl:
             raise RuntimeError(
                 "PyNaCl library is needed in order to use voice related features, "
@@ -127,7 +133,9 @@ def __init__(self, client: Client, channel: abc.Connectable) -> None:
         self._connection: VoiceConnectionState = self.create_connection_state()
 
         # voice recv things
-        self._recorder: Recorder | None = None
+        self._recorder: VoiceRecorderClient | None = None
+        if use_recorder:
+            self._recorder = VoiceRecorderClient(self)
 
     warn_nacl: bool = not has_nacl
     supported_modes: tuple[SupportedModes, ...] = (
@@ -187,7 +195,7 @@ def checked_add(self, attr: str, value: int, limit: int) -> None:
             setattr(self, attr, val + value)
 
     def create_connection_state(self) -> VoiceConnectionState:
-        return VoiceConnectionState(self)
+        return VoiceConnectionState(self, hook=self._recorder)
 
     async def on_voice_state_update(self, data: RawVoiceStateUpdateEvent) -> None:
         await self._connection.voice_state_update(data)

discord/voice/gateway.py

@@ -171,7 +171,7 @@ async def received_message(self, msg: Any, /):
             )
             self._keep_alive.start()
 
-        await self._hook(self, msg)
+        await utils.maybe_coroutine(self._hook, self, data)
 
     async def ready(self, data: dict[str, Any]) -> None:
         state = self.state

discord/voice/recorder.py

@@ -25,15 +25,52 @@
 
 from __future__ import annotations
 
-# TODO: finish this
+import asyncio
+import threading
+from typing import TYPE_CHECKING, Any, TypeVar
 
+from discord.opus import DecodeManager
 
-class Recorder:
+from ._types import VoiceRecorderProtocol
+
+if TYPE_CHECKING:
+    from discord.sinks import Sink
+
+    from .client import VoiceClient
+    from .gateway import VoiceWebSocket
+
+    VoiceClientT = TypeVar('VoiceClientT', bound=VoiceClient, covariant=True)
+
+
+class VoiceRecorderClient(VoiceRecorderProtocol[VoiceClientT]):
     """Represents a voice recorder for a voice client.
 
     You should not construct this but instead obtain it from :attr:`VoiceClient.recorder`.
 
     .. versionadded:: 2.7
     """
 
-    def __init__(self, client: VoiceClient) -> None:
+    def __init__(self, client: VoiceClientT) -> None:
+        super().__init__(client)
+
+        self._paused: asyncio.Event = asyncio.Event()
+        self._recording: asyncio.Event = asyncio.Event()
+        self.decoder: DecodeManager = DecodeManager(self)
+        self.sync_start: bool = False
+        self.sinks: dict[int, tuple[Sink, threading.Thread]] = {}
+
+    def is_paused(self) -> bool:
+        """Whether the current recorder is paused."""
+        return self._paused.is_set()
+
+    def is_recording(self) -> bool:
+        """Whether the current recording is actively recording."""
+        return self._recording.is_set()
+
+    async def hook(self, ws: VoiceWebSocket, data: dict[str, Any]) -> None:
+        ...
+
+    def record(
+        self,
+        sink: Sink,
+    )