feat: implement volume boost functionality with signal-based multiplier and audio processing override

tests/test_ytdl_source.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import struct
+import unittest
+from unittest.mock import MagicMock
+
+import discord
+
+from zyrarbot.audio.ytdl_source import FRAME_LENGTH_SECONDS, YTDLSource
+
+
+class DummyPCM(discord.AudioSource):
+    def __init__(self, data: bytes):
+        self._data = data
+        self.cleanup_called = False
+
+    def read(self) -> bytes:
+        data = self._data
+        self._data = b""
+        return data
+
+    def cleanup(self) -> None:
+        self.cleanup_called = True
+
+
+class TestYTDLSource(unittest.TestCase):
+    def test_read_advances_elapsed_and_returns_data(self):
+        # 1 sample of 16-bit stereo = 4 bytes
+        pcm = struct.pack("<hh", 1000, 2000)
+        source = DummyPCM(pcm)
+        ytdl = YTDLSource(source, data={"title": "test"}, volume=1.0)
+
+        self.assertEqual(ytdl.elapsed, 0.0)
+        data = ytdl.read()
+        self.assertEqual(data, pcm)
+        self.assertAlmostEqual(ytdl.elapsed, FRAME_LENGTH_SECONDS)
+
+        # Subsequent read returns empty and does not advance elapsed further
+        empty = ytdl.read()
+        self.assertEqual(empty, b"")
+        self.assertAlmostEqual(ytdl.elapsed, FRAME_LENGTH_SECONDS)
+
+    def test_read_with_volume_boost_over_2_does_not_clamp_to_2(self):
+        # Sample value 5000:
+        # At volume 2.0 (discord limit): 5000 * 2 = 10000
+        # At volume 5.0: 5000 * 5 = 25000
+        # At volume 10.0: 5000 * 10 = 50000 -> clipped to 32767
+        pcm = struct.pack("<hh", 5000, -5000)
+        source = DummyPCM(pcm)
+        ytdl = YTDLSource(source, data={"title": "distortion test"}, volume=5.0)
+
+        data = ytdl.read()
+        left, right = struct.unpack("<hh", data)
+        self.assertEqual(left, 25000)
+        self.assertEqual(right, -25000)
+
+    def test_read_distortion_clips_at_pcm_limits(self):
+        # Overdriving large amplitude samples causes clipping / przester at [-32768, 32767]
+        pcm = struct.pack("<hh", 10000, -10000)
+        source = DummyPCM(pcm)
+        ytdl = YTDLSource(source, data={"title": "przester"}, volume=10.0)
+
+        data = ytdl.read()
+        left, right = struct.unpack("<hh", data)
+        self.assertEqual(left, 32767)
+        self.assertEqual(right, -32768)
+
+
+if __name__ == "__main__":
+    unittest.main()