feat: add player audio effects module with real-time pipeline, distortion, fourth density, and UI controls

zyrarbot/audio/effects/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from zyrarbot.audio.effects.base import AudioEffect
+from zyrarbot.audio.effects.distortion import DistortionEffect
+from zyrarbot.audio.effects.fourth_density import FourthDensityEffect
+from zyrarbot.audio.effects.muffled import MuffledEffect
+from zyrarbot.audio.effects.pipeline import AudioEffectsPipeline
+from zyrarbot.audio.effects.registry import (
+    create_default_effects,
+    get_available_effects_metadata,
+)
+from zyrarbot.audio.effects.tremolo import TremoloEffect
+
+__all__ = [
+    "AudioEffect",
+    "AudioEffectsPipeline",
+    "DistortionEffect",
+    "FourthDensityEffect",
+    "MuffledEffect",
+    "TremoloEffect",
+    "create_default_effects",
+    "get_available_effects_metadata",
+]
+

zyrarbot/audio/effects/base.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AudioEffect(ABC):
+    """Bazowy interfejs efektu audio operującego na 16-bitowym PCM stereo (48000Hz)."""
+
+    id: str
+    name: str
+    description: str
+    badge: str
+    icon: str
+
+    @abstractmethod
+    def process(self, pcm_data: bytes, sample_rate: int = 48000) -> bytes:
+        """Przetwarza ramkę surowego PCM (16-bit signed stereo little-endian)."""
+        ...
+
+    def reset(self) -> None:
+        """Resetuje ewentualny stan wewnętrzny filtra/efektu."""
+        pass

zyrarbot/audio/effects/distortion.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from zyrarbot.audio.effects.base import AudioEffect
+
+try:
+    import audioop
+except ImportError:  # pragma: no cover
+    try:
+        import audioop_lts as audioop
+    except ImportError:
+        audioop = None
+
+
+class DistortionEffect(AudioEffect):
+    """Efekt ekstremalnego przesteru (distortion / overdrive 1000%)."""
+
+    id = "distortion"
+    name = "Przester"
+    description = "Ekstremalne podbicie głośności (1000%) z przesterem"
+    badge = "1000%"
+    icon = "zap"
+
+    def __init__(self, multiplier: float = 10.0) -> None:
+        self.multiplier = multiplier
+
+    def process(self, pcm_data: bytes, sample_rate: int = 48000) -> bytes:
+        if not pcm_data or audioop is None or self.multiplier == 1.0:
+            return pcm_data
+        # audioop.mul multiplies 16-bit PCM and hard-clips at [-32768, 32767]
+        return audioop.mul(pcm_data, 2, self.multiplier)

zyrarbot/audio/effects/fourth_density.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import array
+import math
+
+from zyrarbot.audio.effects.base import AudioEffect
+
+
+class FourthDensityEffect(AudioEffect):
+    """Efekt 'czwartej gęstości' – płynna sinusoidalna modulacja wysokości dźwięku (pitch) z okresem ~1s."""
+
+    id = "fourth_density"
+    name = "Czwarta gęstość"
+    description = "Pływający ton (sinusoidalna zmiana pitch z okresem ~1 sekundy)"
+    badge = "~1s PITCH"
+    icon = "sparkles"
+
+    def __init__(
+        self,
+        rate_hz: float = 1.0,
+        depth_samples: float = 350.0,
+        base_delay: float = 450.0,
+        buffer_size: int = 2400,
+    ) -> None:
+        self.rate_hz = rate_hz
+        self.depth = depth_samples
+        self.base_delay = base_delay
+        self.buffer_size = buffer_size
+        self._buf_l = [0.0] * buffer_size
+        self._buf_r = [0.0] * buffer_size
+        self._write_ptr = 0
+        self._phase = 0.0
+        self._phase_inc = 2.0 * math.pi * rate_hz / 48000.0
+
+    def process(self, pcm_data: bytes, sample_rate: int = 48000) -> bytes:
+        if not pcm_data:
+            return pcm_data
+
+        samples = array.array("h", pcm_data)
+        num_frames = len(samples) // 2
+        buf_l = self._buf_l
+        buf_r = self._buf_r
+        buf_size = self.buffer_size
+        w = self._write_ptr
+        phase = self._phase
+        phase_inc = self._phase_inc
+        depth = self.depth
+        base_delay = self.base_delay
+
+        for i in range(num_frames):
+            in_l = samples[i * 2]
+            in_r = samples[i * 2 + 1]
+
+            buf_l[w] = in_l
+            buf_r[w] = in_r
+
+            # Modulacja opóźnienia generująca efekt vibrato / pitch wow
+            delay = base_delay + depth * math.sin(phase)
+            phase += phase_inc
+            if phase >= 2.0 * math.pi:
+                phase -= 2.0 * math.pi
+
+            r_idx = w - delay
+            while r_idx < 0:
+                r_idx += buf_size
+
+            idx0 = int(r_idx)
+            idx1 = (idx0 + 1) % buf_size
+            frac = r_idx - idx0
+
+            out_l = buf_l[idx0] + frac * (buf_l[idx1] - buf_l[idx0])
+            out_r = buf_r[idx0] + frac * (buf_r[idx1] - buf_r[idx0])
+
+            samples[i * 2] = max(-32768, min(32767, int(out_l)))
+            samples[i * 2 + 1] = max(-32768, min(32767, int(out_r)))
+
+            w = (w + 1) % buf_size
+
+        self._write_ptr = w
+        self._phase = phase
+        return samples.tobytes()
+
+    def reset(self) -> None:
+        self._buf_l = [0.0] * self.buffer_size
+        self._buf_r = [0.0] * self.buffer_size
+        self._write_ptr = 0
+        self._phase = 0.0

zyrarbot/audio/effects/muffled.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import array
+
+from zyrarbot.audio.effects.base import AudioEffect
+
+
+class MuffledEffect(AudioEffect):
+    """Efekt dźwięku zza ściany / pod wodą (filtr dolnoprzepustowy IIR)."""
+
+    id = "muffled"
+    name = "Pod wodą"
+    description = "Filtr dolnoprzepustowy (dźwięk przytłumiony / zza ściany)"
+    badge = "LOWPASS"
+    icon = "waves"
+
+    def __init__(self, alpha: float = 0.085) -> None:
+        self.alpha = alpha
+        self._prev_l = 0.0
+        self._prev_r = 0.0
+
+    def process(self, pcm_data: bytes, sample_rate: int = 48000) -> bytes:
+        if not pcm_data:
+            return pcm_data
+
+        samples = array.array("h", pcm_data)
+        alpha = self.alpha
+        prev_l = self._prev_l
+        prev_r = self._prev_r
+
+        # Przetwarzanie stereo (próbka lewa i prawa)
+        for i in range(0, len(samples), 2):
+            prev_l += alpha * (samples[i] - prev_l)
+            prev_r += alpha * (samples[i + 1] - prev_r)
+            samples[i] = int(prev_l)
+            samples[i + 1] = int(prev_r)
+
+        self._prev_l = prev_l
+        self._prev_r = prev_r
+        return samples.tobytes()
+
+    def reset(self) -> None:
+        self._prev_l = 0.0
+        self._prev_r = 0.0

zyrarbot/audio/effects/pipeline.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Iterable
+
+from zyrarbot.audio.effects.base import AudioEffect
+
+try:
+    import audioop
+except ImportError:  # pragma: no cover
+    try:
+        import audioop_lts as audioop
+    except ImportError:
+        audioop = None
+
+
+class AudioEffectsPipeline:
+    """Łańcuch efektów audio przetwarzający ramki PCM w locie."""
+
+    def __init__(self, effects: Iterable[AudioEffect] | None = None) -> None:
+        self._effects: dict[str, AudioEffect] = {}
+        self._active_ids: set[str] = set()
+        if effects:
+            for effect in effects:
+                self.register(effect)
+
+    def register(self, effect: AudioEffect) -> None:
+        self._effects[effect.id] = effect
+
+    def get(self, effect_id: str) -> AudioEffect | None:
+        return self._effects.get(effect_id)
+
+    @property
+    def active_ids(self) -> set[str]:
+        return self._active_ids
+
+    @active_ids.setter
+    def active_ids(self, ids: Iterable[str]) -> None:
+        self._active_ids = set(ids)
+
+    def is_active(self, effect_id: str) -> bool:
+        return effect_id in self._active_ids
+
+    def set_active(self, effect_id: str, active: bool) -> bool:
+        if effect_id not in self._effects:
+            return False
+        if active:
+            self._active_ids.add(effect_id)
+        else:
+            self._active_ids.discard(effect_id)
+            self._effects[effect_id].reset()
+        return True
+
+    def toggle(self, effect_id: str) -> bool:
+        new_state = not self.is_active(effect_id)
+        self.set_active(effect_id, new_state)
+        return new_state
+
+    def process(self, pcm_data: bytes, volume: float = 1.0) -> bytes:
+        if not pcm_data:
+            return b""
+
+        # 1. Przetwarzanie aktywnych efektów w ustalonej kolejności rejestru
+        for effect in self._effects.values():
+            if effect.id in self._active_ids:
+                pcm_data = effect.process(pcm_data)
+
+        # 2. Skalowanie głośności głównej
+        if volume != 1.0 and audioop is not None:
+            pcm_data = audioop.mul(pcm_data, 2, volume)
+
+        return pcm_data
+
+    def reset(self) -> None:
+        for effect in self._effects.values():
+            effect.reset()

zyrarbot/audio/effects/registry.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from zyrarbot.audio.effects.base import AudioEffect
+from zyrarbot.audio.effects.distortion import DistortionEffect
+from zyrarbot.audio.effects.fourth_density import FourthDensityEffect
+from zyrarbot.audio.effects.muffled import MuffledEffect
+from zyrarbot.audio.effects.tremolo import TremoloEffect
+from zyrarbot.music.guild_music_state import VOLUME_BOOST_MULTIPLIER
+
+
+def create_default_effects() -> list[AudioEffect]:
+    """Tworzy domyślną listę efektów audio w zalecanej kolejności przetwarzania."""
+    return [
+        MuffledEffect(),
+        FourthDensityEffect(),
+        DistortionEffect(multiplier=VOLUME_BOOST_MULTIPLIER),
+        TremoloEffect(),
+    ]
+
+
+
+def get_available_effects_metadata() -> list[dict[str, Any]]:
+    """Zwraca metadane wszystkich dostępnych w systemie efektów."""
+    return [
+        {
+            "id": effect.id,
+            "name": effect.name,
+            "description": effect.description,
+            "badge": effect.badge,
+            "icon": effect.icon,
+        }
+        for effect in create_default_effects()
+    ]

zyrarbot/audio/effects/tremolo.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import math
+
+from zyrarbot.audio.effects.base import AudioEffect
+
+try:
+    import audioop
+except ImportError:  # pragma: no cover
+    try:
+        import audioop_lts as audioop
+    except ImportError:
+        audioop = None
+
+
+class TremoloEffect(AudioEffect):
+    """Efekt pulsowania głośności (tremolo) z generatorem LFO."""
+
+    id = "tremolo"
+    name = "Tremolo"
+    description = "Pulsowanie amplitudy (efekt wibracji głośności)"
+    badge = "LFO"
+    icon = "activity"
+
+    def __init__(self, freq_hz: float = 4.0, depth: float = 0.6) -> None:
+        self.freq_hz = freq_hz
+        self.depth = depth
+        self._phase = 0.0
+
+    def process(self, pcm_data: bytes, sample_rate: int = 48000) -> bytes:
+        if not pcm_data or audioop is None:
+            return pcm_data
+
+        # Obliczamy współczynnik modulacji na podstawie fazy LFO
+        lfo = 0.5 + 0.5 * math.sin(self._phase)
+        factor = 1.0 - (self.depth * lfo)
+
+        # 20ms = 0.02s
+        self._phase = (self._phase + 2.0 * math.pi * self.freq_hz * 0.02) % (2.0 * math.pi)
+
+        return audioop.mul(pcm_data, 2, factor)
+
+    def reset(self) -> None:
+        self._phase = 0.0

zyrarbot/audio/ytdl_source.py

@@ -8,6 +8,9 @@ import discord
 FRAME_LENGTH_SECONDS = 0.02
 
 
+from zyrarbot.audio.effects.pipeline import AudioEffectsPipeline
+from zyrarbot.audio.effects.registry import create_default_effects
+
 try:
     import audioop
 except ImportError:  # pragma: no cover
@@ -20,7 +23,14 @@ except ImportError:  # pragma: no cover
 class YTDLSource(discord.PCMVolumeTransformer):
     """Źródło audio (strumień YouTube lub plik lokalny) z metadanymi utworu."""
 
-    def __init__(self, source: discord.AudioSource, *, data: dict[str, Any], volume: float = 0.5):
+    def __init__(
+        self,
+        source: discord.AudioSource,
+        *,
+        data: dict[str, Any],
+        volume: float = 0.5,
+        effects_pipeline: AudioEffectsPipeline | None = None,
+    ):
         super().__init__(source, volume)
         self.data = data
         self.title: str | None = data.get("title")
@@ -30,6 +40,9 @@ class YTDLSource(discord.PCMVolumeTransformer):
         self.elapsed: float = 0.0
         self.plays_left: int | None = data.get("plays_left")
         self.played: bool = False
+        self.effects_pipeline: AudioEffectsPipeline = (
+            effects_pipeline if effects_pipeline is not None else AudioEffectsPipeline(create_default_effects())
+        )
 
     @property
     def is_local(self) -> bool:
@@ -48,21 +61,18 @@ class YTDLSource(discord.PCMVolumeTransformer):
         url = self.display_url
         return bool(url and str(url).startswith("http"))
 
-    def read(self) -> bytes:
-        # discord.PCMVolumeTransformer clamps volume to min(self._volume, 2.0).
-        # We read self.original directly and use audioop.mul without the 2.0 cap
-        # so that boosted volume overdrive produces authentic PCM clipping / distortion (przester).
-        if audioop is None:
-            data = super().read()
-            if data:
-                self.elapsed += FRAME_LENGTH_SECONDS
-            return data
+    def set_active_effects(self, effect_ids: Any) -> None:
+        if self.effects_pipeline:
+            self.effects_pipeline.active_ids = effect_ids
 
+    def read(self) -> bytes:
         data = self.original.read()
         if not data:
             return b""
         self.elapsed += FRAME_LENGTH_SECONDS
-        if self._volume != 1.0:
+        if self.effects_pipeline is not None:
+            return self.effects_pipeline.process(data, volume=self._volume)
+        if audioop is not None and self._volume != 1.0:
             return audioop.mul(data, 2, self._volume)
         return data
 

zyrarbot/music/guild_music_state.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 import discord
 
-from zyrarbot.audio.ytdl_source import YTDLSource
 from zyrarbot.music.loop_mode import LoopMode
 
+if TYPE_CHECKING:
+    from zyrarbot.audio.ytdl_source import YTDLSource
+
 VOLUME_BOOST_MULTIPLIER: float = 10.0
 
 
@@ -23,16 +26,28 @@ class GuildMusicState:
     current: YTDLSource | None = None
     index: int = -1
     volume: float = 1.0
-    volume_boost: bool = False
+    active_effects: set[str] = field(default_factory=set)
     loop_mode: LoopMode = LoopMode.OFF
     jump_pending: bool = False
     notification_channel: discord.abc.Messageable | None = None
 
+    @property
+    def volume_boost(self) -> bool:
+        return "distortion" in self.active_effects
+
+    @volume_boost.setter
+    def volume_boost(self, value: bool) -> None:
+        if value:
+            self.active_effects.add("distortion")
+        else:
+            self.active_effects.discard("distortion")
+
     @property
     def effective_volume(self) -> float:
         """Zwraca głośność z uwzględnieniem trybu podbicia (mnożnik VOLUME_BOOST_MULTIPLIER)."""
         return self.volume * VOLUME_BOOST_MULTIPLIER if self.volume_boost else self.volume
 
+
     def reset(self) -> None:
         self.queue.clear()
         self.current = None

zyrarbot/music/music_player.py

@@ -212,19 +212,36 @@ class MusicPlayer:
         voice_client = self.voice_client(guild_id)
         if voice_client and voice_client.source:
             voice_client.source.volume = state.effective_volume
+            if hasattr(voice_client.source, "set_active_effects"):
+                voice_client.source.set_active_effects(state.active_effects)
 
     def set_volume(self, guild_id: int, volume: float) -> None:
         self.state(guild_id).volume = volume
         self._apply_volume(guild_id)
 
-    def set_volume_boost(self, guild_id: int, boost: bool) -> bool:
-        self.state(guild_id).volume_boost = boost
+    def set_effect(self, guild_id: int, effect_id: str, enabled: bool) -> bool:
+        state = self.state(guild_id)
+        if enabled:
+            state.active_effects.add(effect_id)
+        else:
+            state.active_effects.discard(effect_id)
         self._apply_volume(guild_id)
-        return boost
+        return enabled
+
+    def toggle_effect(self, guild_id: int, effect_id: str) -> bool:
+        state = self.state(guild_id)
+        enabled = effect_id not in state.active_effects
+        return self.set_effect(guild_id, effect_id, enabled)
+
+    def is_effect_active(self, guild_id: int, effect_id: str) -> bool:
+        return effect_id in self.state(guild_id).active_effects
+
+    def set_volume_boost(self, guild_id: int, boost: bool) -> bool:
+        return self.set_effect(guild_id, "distortion", boost)
 
     def toggle_volume_boost(self, guild_id: int) -> bool:
-        state = self.state(guild_id)
-        return self.set_volume_boost(guild_id, not state.volume_boost)
+        return self.toggle_effect(guild_id, "distortion")
+
 
     def set_loop_mode(self, guild_id: int, mode: LoopMode) -> None:
         self.state(guild_id).loop_mode = mode
@@ -334,6 +351,8 @@ class MusicPlayer:
         track = await self._tracks.recreate(current, loop=self._bot.loop, start_at=position)
         track.played = True
         track.volume = state.effective_volume
+        if hasattr(track, "set_active_effects"):
+            track.set_active_effects(state.active_effects)
         track.plays_left = self.plays_left(current, guild_id)
         track.elapsed = position
         state.queue[state.index] = track
@@ -440,6 +459,8 @@ class MusicPlayer:
         track.played = True
         track.plays_left = self.plays_left(track, guild_id)
         track.volume = state.effective_volume
+        if hasattr(track, "set_active_effects"):
+            track.set_active_effects(state.active_effects)
 
         state.queue[next_index] = track
         if track.plays_left <= 0 and state.loop_mode.loops_track:

zyrarbot/ui/api/requests/effect_toggle_request.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class EffectToggleRequest(BaseModel):
+    effect_id: str
+    enabled: bool | None = None

zyrarbot/ui/api/routers/playback_router.py

@@ -17,6 +17,7 @@ from zyrarbot.ui.api.dependencies import (
     get_tracks,
     get_uploads,
 )
+from zyrarbot.ui.api.requests.effect_toggle_request import EffectToggleRequest
 from zyrarbot.ui.api.requests.loop_request import LoopRequest
 from zyrarbot.ui.api.requests.play_file_request import PlayFileRequest
 from zyrarbot.ui.api.requests.play_request import PlayRequest
@@ -189,6 +190,27 @@ async def set_volume_boost(
     return {"status": "success", "volume_boost": boost}
 
 
+@router.post("/effects/toggle")
+async def toggle_effect(
+    request: EffectToggleRequest,
+    guild: discord.Guild = Depends(get_active_guild),
+    player: MusicPlayer = Depends(get_player),
+    broadcaster: StatusBroadcaster = Depends(get_broadcaster),
+) -> dict[str, Any]:
+    if request.enabled is not None:
+        active = player.set_effect(guild.id, request.effect_id, request.enabled)
+    else:
+        active = player.toggle_effect(guild.id, request.effect_id)
+    await broadcaster.broadcast()
+    return {
+        "status": "success",
+        "effect_id": request.effect_id,
+        "active": active,
+        "active_effects": list(player.state(guild.id).active_effects),
+    }
+
+
+
 @router.post("/loop")
 async def set_loop(
     request: LoopRequest,

zyrarbot/ui/api/status_service.py

@@ -4,6 +4,7 @@ from typing import Any
 
 import discord
 
+from zyrarbot.audio.effects import get_available_effects_metadata
 from zyrarbot.audio.ytdl_source import YTDLSource
 from zyrarbot.music.guild_music_state import VOLUME_BOOST_MULTIPLIER
 from zyrarbot.music.music_player import MusicPlayer
@@ -52,6 +53,8 @@ class StatusService:
             "volume": 100,
             "volume_boost": False,
             "volume_boost_multiplier": VOLUME_BOOST_MULTIPLIER,
+            "effects": [{**meta, "active": False} for meta in get_available_effects_metadata()],
+            "active_effects": [],
             "current": None,
             "queue": [],
             "queue_index": -1,
@@ -75,6 +78,11 @@ class StatusService:
             "volume": int(state.volume * 100),
             "volume_boost": state.volume_boost,
             "volume_boost_multiplier": VOLUME_BOOST_MULTIPLIER,
+            "effects": [
+                {**meta, "active": meta["id"] in state.active_effects}
+                for meta in get_available_effects_metadata()
+            ],
+            "active_effects": list(state.active_effects),
             "current": self._current_payload(state.current, guild.id),
             "queue": [self._track_payload(track, guild.id) for track in state.queue],
             "queue_index": state.index,

zyrarbot/ui/bot/cogs/control_cog.py

@@ -125,6 +125,30 @@ class ControlCog(MusicCogBase, name="Control"):
             )
         )
 
+    @app_commands.command(name="efekt", description="Włącz lub wyłącz efekt dźwiękowy odtwarzacza")
+    @app_commands.describe(nazwa="Wybierz efekt audio do przełączenia")
+    @app_commands.choices(
+        nazwa=[
+            app_commands.Choice(name="Przester (1000%)", value="distortion"),
+            app_commands.Choice(name="Czwarta gęstość (~1s pitch)", value="fourth_density"),
+            app_commands.Choice(name="Pod wodą (lowpass)", value="muffled"),
+            app_commands.Choice(name="Tremolo (pulsowanie)", value="tremolo"),
+        ]
+    )
+    async def toggle_effect_command(
+        self, interaction: discord.Interaction, nazwa: app_commands.Choice[str]
+    ) -> None:
+        active = self.player.toggle_effect(interaction.guild.id, nazwa.value)
+        await self.player.trigger_state_change()
+        status_text = "włączony ✅" if active else "wyłączony ❌"
+        await interaction.response.send_message(
+            embed=message_embed(
+                "Efekt odtwarzacza",
+                f"Efekt **{nazwa.name}** jest teraz **{status_text}**.",
+            )
+        )
+
+
     @app_commands.command(name="nowplaying", description="Pokaż aktualnie odtwarzany utwór")
     async def now_playing(self, interaction: discord.Interaction) -> None:
         current = self.player.state(interaction.guild.id).current