feat: Support Voice rcv (#1288)

* feat: Support voice rcv

* style: linter pass

* fix: further fixes to voice rcv (see desc.)

- Handle rtp header ext without discarding 
- ffmpeg now respects decoder settings
- fix errant decode_float opus def
- add `get_ssrc` method to recorder
- sockets are no longer blocking
- irregular sounds (voice) will no longer crash the opus decoder

* ci: correct from checks.

* feat: add ctx.voice_state

* feat 💥: support recording to file

breaking as `start``stop`recording are now async

* fix: prevent re-use of recorders

new recorders are now created as needed

* ci: correct from checks.

* style: linter pass

* fix: ensure recorder can exit when no audio recieved

* feat: add elapsed time to recorder

* ci: correct from checks.

* fix: ensure socket buffer is purged before recording

* feat: send udp keepalive packets

* feat: switch to monotick clock instead of using the audio timestamp

* ci: correct from checks.

* docs: add voice recorder docs

* fix: ensure non-ffmpeg encoders output to file when expected

* refactor: update to comply with linter

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: LordOfPolls

docs/src/API Reference/API Reference/API_Communication/voice/recorder.md

@@ -0,0 +1 @@
+::: interactions.api.voice.recorder

docs/src/Guides/23 Voice.md

@@ -55,20 +55,39 @@ async def play_file(ctx: interactions.InteractionContext):
 
 Check out [Active Voice State](/interactions.py/API Reference/API Reference/models/Internal/active_voice_state/) for a list of available methods and attributes.
 
-## Okay, but what about Soundcloud?
+# Voice Recording
 
-interactions.py has an extension library called [`NAFFAudio`](https://github.com/NAFTeam/NAFF-Audio) which can help with that.
-It has an object called `YTAudio` which can be used to play audio from Soundcloud and other video platforms.
+So you've got a bot that can play music, but what about recording? Well, you're in luck! We've got you covered.
 
-```
-pip install naff_audio
-```
+Let's start with a simple example:
 
 ```python
-from naff_audio import YTAudio
+import asyncio
+import interactions
+
+@interactions.slash_command("record", "record some audio")
+async def record(ctx: interactions.InteractionContext):
+    voice_state = await ctx.author.voice.channel.connect()
+
+    # Start recording
+    await voice_state.start_recording()
+    await asyncio.sleep(10)
+    await voice_state.stop_recording()
+    await ctx.send(files=[interactions.File(file, file_name="user_id.mp3") for user_id, file in voice_state.recorder.output.items()])
+```
+This code will connect to the author's voice channel, start recording, wait 10 seconds, stop recording, and send a file for each user that was recorded.
 
-audio = await YTAudio.from_url("https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-4")
-await voice_state.play(audio)
+But what if you didn't want to use `mp3` files? Well, you can change that too! Just pass the encoding you want to use to `start_recording`.
+
+```python
+await voice_state.start_recording(encoding="wav")
 ```
 
-`NAFFAudio` also contains other useful features for audio-bots. Check it out if that's your *jam*.
+For a list of available encodings, check out Recorder's [documentation](/interactions.py/API Reference/API_Communication/voice/recorder.md)
+
+Are you going to be recording for a long time? You are going to want to write the files to disk instead of keeping them in memory. You can do that too!
+
+```python
+await voice_state.start_recording(output_dir="folder_name")
+```
+This will write the files to the folder `folder_name` in the current working directory, please note that the library will not create the folder for you, nor will it delete the files when you're done.

interactions/api/voice/audio.py

@@ -5,19 +5,70 @@
 import time
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Union, Optional
+from typing import Union, Optional, TYPE_CHECKING
 
-__all__ = (
-    "AudioBuffer",
-    "BaseAudio",
-    "Audio",
-    "AudioVolume",
-)
+__all__ = ("AudioBuffer", "BaseAudio", "Audio", "AudioVolume", "RawInputAudio")
 
 from interactions.client.const import get_logger
 from interactions.api.voice.opus import Encoder
 from interactions.client.utils import FastJson
 
+if TYPE_CHECKING:
+    from interactions.api.voice.recorder import Recorder
+
+
+class RawInputAudio:
+    decoded: bytes
+    """The decoded audio"""
+    pcm: bytes
+    """The raw PCM audio"""
+    sequence: int
+    """The audio sequence"""
+    audio_timestamp: int
+    """The current timestamp for this audio"""
+    timestamp_ns: float
+    """The time this audio was received, in nanoseconds"""
+    timestamp: float
+    """The time this audio was received, in seconds"""
+    ssrc: int
+    """The source of this audio"""
+    _recoder: "Recorder"
+    """A reference to the audio recorder managing this object"""
+
+    def __init__(self, recorder: "Recorder", data: bytes) -> None:
+        self.decoded: bytes = b""
+        self._recorder = recorder
+        self.timestamp_ns = time.monotonic_ns()
+        self.timestamp = self.timestamp_ns / 1e9
+        self.pcm = b""
+
+        self.ingest(data)
+
+    def ingest(self, data: bytes) -> bytes | None:
+        data = bytearray(data)
+        header = data[:12]
+
+        decrypted: bytes = self._recorder.decrypt(header, data[12:])
+        self.ssrc = int.from_bytes(header[8:12], byteorder="big")
+        self.sequence = int.from_bytes(header[2:4], byteorder="big")
+        self.audio_timestamp = int.from_bytes(header[4:8], byteorder="big")
+
+        if not self._recorder.recording_whitelist or self.user_id in self._recorder.recording_whitelist:
+            # noinspection PyProtectedMember
+            if decrypted[0] == 0xBE and decrypted[1] == 0xDE:
+                # rtp header extension, remove it
+                header_ext_length = int.from_bytes(decrypted[2:4], byteorder="big")
+                decrypted = decrypted[4 + 4 * header_ext_length :]
+            self.decoded = self._recorder.get_decoder(self.ssrc).decode(decrypted)
+            return self.decoded
+
+    @property
+    def user_id(self) -> Optional[int]:
+        """The ID of the user who made this audio."""
+        while not self._recorder.state.ws.user_ssrc_map.get(self.ssrc):
+            time.sleep(0.05)
+        return self._recorder.state.ws.user_ssrc_map.get(self.ssrc)["user_id"]
+
 
 class AudioBuffer:
     def __init__(self) -> None:
@@ -38,25 +89,54 @@ def extend(self, data: bytes) -> None:
         with self._lock:
             self._buffer.extend(data)
 
-    def read(self, total_bytes: int) -> bytearray:
+    def read(self, total_bytes: int, *, pad: bool = True) -> bytearray:
         """
         Read `total_bytes` bytes of audio from the buffer.
 
         Args:
             total_bytes: Amount of bytes to read.
+            pad: Whether to pad incomplete frames with 0's.
 
         Returns:
             Desired amount of bytes
+
+        Raises:
+            ValueError: If `pad` is False and the buffer does not contain enough data.
         """
         with self._lock:
             view = memoryview(self._buffer)
             self._buffer = bytearray(view[total_bytes:])
             data = bytearray(view[:total_bytes])
             if 0 < len(data) < total_bytes:
-                # pad incomplete frames with 0's
-                data.extend(b"\0" * (total_bytes - len(data)))
+                if pad:
+                    # pad incomplete frames with 0's
+                    data.extend(b"\0" * (total_bytes - len(data)))
+                else:
+                    raise ValueError(
+                        f"Buffer does not contain enough data to fulfill request {len(data)} < {total_bytes}"
+                    )
             return data
 
+    def read_max(self, total_bytes: int) -> bytearray:
+        """
+        Read up to `total_bytes` bytes of audio from the buffer.
+
+        Args:
+            total_bytes: Maximum amount of bytes to read.
+
+        Returns:
+            Desired amount of bytes
+
+        Raises:
+            EOFError: If the buffer is empty.
+        """
+        with self._lock:
+            if len(self._buffer) == 0:
+                raise EOFError("Buffer is empty")
+            view = memoryview(self._buffer)
+            self._buffer = bytearray(view[total_bytes:])
+            return bytearray(view[:total_bytes])
+
 
 class BaseAudio(ABC):
     """Base structure of the audio."""